Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

docs(integrations): setup guides for connecting Slack, Ramp, Xero and Jira

aashu362a31a647fd
diff --git a/docs/components/editorial/architecture-diagrams.tsx b/docs/components/editorial/architecture-diagrams.tsx
index 5c815c871e..8663a44e4c 100644
--- a/docs/components/editorial/architecture-diagrams.tsx
+++ b/docs/components/editorial/architecture-diagrams.tsx
@@ -38,7 +38,9 @@ export type ArchitectureDiagramKey =
| "triage"
| "buy-hosted"
| "buy-selfhosted"
- | "plans";
+ | "plans"
+ | "connect"
+ | "ramp-modes";
/* Part 1. The spine only: people, the two apps, Supabase over Postgres, and the event
* loop back into the ERP. Redis and the Assembler are deliberately absent — they are
@@ -567,6 +569,44 @@ function Plans() {
);
}
+/* Connecting an integration, for the setup guides: three steps, the middle one happens
+ * in the other app. Generic on purpose so one drawing serves every guide. */
+function Connect() {
+ return (
+ <svg viewBox="0 0 740 96" className="w-full h-auto" role="img" aria-label="How connecting an app to Carbon works">
+ <ArrowDefs />
+
+ <Node x={16} y={18} w={206} h={60} label="1. Press Install" sub="in Carbon" tone="app" />
+ <Edge pts={[[222, 48], [267, 48]]} />
+ <Node x={267} y={18} w={206} h={60} label="2. Sign in and allow" sub="in the other app" tone="svc" />
+ <Edge pts={[[473, 48], [518, 48]]} />
+ <Node x={518} y={18} w={206} h={60} label="3. Connected" sub="back in Carbon" tone="app" />
+ </svg>
+ );
+}
+
+/* Ramp's connect question. Ramp lets one accounting system connect at a time, so the
+ * answer to "who keeps your books" decides what Carbon does with Ramp. */
+function RampModes() {
+ return (
+ <svg viewBox="0 0 740 226" className="w-full h-auto" role="img" aria-label="Choosing how Carbon connects to Ramp">
+ <ArrowDefs />
+
+ <Node x={235} y={14} w={270} h={50} label="Who keeps your books?" />
+
+ <Edge pts={[[300, 64], [300, 88], [185, 88], [185, 116]]} label="Carbon" labelAt={[242, 88]} />
+ <Edge pts={[[440, 64], [440, 88], [555, 88], [555, 116]]} label="another system" labelAt={[498, 88]} />
+
+ <Node x={30} y={116} w={310} h={56} label="Carbon is my accounting system" sub="Ramp spend flows into Carbon's books" tone="app" />
+ <Node x={400} y={116} w={310} h={56} label="Another system posts my ledger" sub="Your other system keeps Ramp's accounting spot" tone="svc" />
+
+ <text x={370} y={206} textAnchor="middle" fontSize="11" fill={INK_45}>
+ You pick once. To change it, uninstall Ramp in Carbon and connect again.
+ </text>
+ </svg>
+ );
+}
+
export const architectureDiagrams: Record<ArchitectureDiagramKey, () => ReactElement> = {
map: Map,
click: Click,
@@ -578,4 +618,6 @@ export const architectureDiagrams: Record<ArchitectureDiagramKey, () => ReactEle
"buy-hosted": BuyHosted,
"buy-selfhosted": BuySelfHosted,
plans: Plans,
+ connect: Connect,
+ "ramp-modes": RampModes,
};
diff --git a/docs/content/docs/integrations/accounting.mdx b/docs/content/docs/integrations/accounting.mdx
index ca1f7d6a98..e8e73750cf 100644
--- a/docs/content/docs/integrations/accounting.mdx
+++ b/docs/content/docs/integrations/accounting.mdx
@@ -15,11 +15,11 @@ Once **Sync** is on, Carbon sends **customers**, **vendors**, **items**, **sales
While **Sync** is on, Carbon mirrors every automated GL posting to the connected provider. Journals with a `Manual` source do not synchronize.
</Callout>
-A provider payment creates a Carbon payment and <Term id="invoice-settlement">invoice settlement</Term>, then posts to Carbon's <Term id="general-ledger">general ledger</Term>. Rillet also accepts outbound Carbon payments. Xero and QuickBooks support inbound payment synchronization only.
+A provider payment creates a Carbon payment and <Term id="invoice-settlement">invoice settlement</Term>, then posts to Carbon's <Term id="general-ledger">general ledger</Term>. Rillet, Xero and QuickBooks also accept outbound Carbon payments.
## Connect a ledger
-Xero and QuickBooks Online use **OAuth**. Rillet uses a per-company **API key**.
+Xero and QuickBooks Online use **OAuth**. Rillet uses a per-company **API key**. Step-by-step: [Connect Xero](/docs/integrations/setup/xero).
<Steps>
<Step>
@@ -58,8 +58,8 @@ Rillet's connection fields:
<Field name="Webhook token">Optional secret. Inbound payment write-back stays off until this is set.</Field>
</FieldTable>
-<Callout type="warn" title="Xero and QuickBooks are hidden without a server-side client">
-Xero appears only when `XERO_CLIENT_ID` is set. QuickBooks Online appears only when `QUICKBOOKS_CLIENT_ID` is set. See [Environment variables](/docs/platform/self-hosting/environment-variables). Rillet is always available because it authenticates with a per-company API key.
+<Callout type="warn" title="QuickBooks Online is not available yet">
+The QuickBooks Online card reads **Not Configured** and cannot be installed. On a self-hosted deployment, Xero needs `XERO_CLIENT_ID` and `XERO_CLIENT_SECRET`; without them the connection fails with *Xero OAuth not configured*. See [Environment variables](/docs/platform/self-hosting/environment-variables). Rillet is always available because it authenticates with a per-company API key.
</Callout>
## Configure the sync
diff --git a/docs/content/docs/integrations/assistant.mdx b/docs/content/docs/integrations/assistant.mdx
index bfcb09c3c4..d7dfd96854 100644
--- a/docs/content/docs/integrations/assistant.mdx
+++ b/docs/content/docs/integrations/assistant.mdx
@@ -25,6 +25,8 @@ Connect **Slack** through **OAuth** to add the **Carbon Assistant** to your work
| --- | --- |
| Connection | Established by the Slack OAuth install — no keys to paste. |
+Step-by-step: [Connect Slack](/docs/integrations/setup/slack).
+
<Callout type="warn">
Slack is unavailable in controlled (ITAR) environments.
</Callout>
diff --git a/docs/content/docs/integrations/meta.json b/docs/content/docs/integrations/meta.json
index b330b1d899..4c7d5c9c6a 100644
--- a/docs/content/docs/integrations/meta.json
+++ b/docs/content/docs/integrations/meta.json
@@ -8,6 +8,7 @@
"oee",
"estimating",
"email",
- "assistant"
+ "assistant",
+ "setup"
]
}
diff --git a/docs/content/docs/integrations/project-management.mdx b/docs/content/docs/integrations/project-management.mdx
index c627be664a..8b284713a8 100644
--- a/docs/content/docs/integrations/project-management.mdx
+++ b/docs/content/docs/integrations/project-management.mdx
@@ -47,6 +47,7 @@ Webhooks without a saved secret remain compatible with older configurations, but
## Jira
Connect over **OAuth**. The only setting is an optional webhook secret.
+Step-by-step: [Connect Jira](/docs/integrations/setup/jira).
<Steps>
<Step>
@@ -55,11 +56,11 @@ Connect over **OAuth**. The only setting is an optional webhook secret.
Authorize Carbon in Jira.
</Step>
<Step>
- ### Create the webhook in Jira (optional)
+ ### Create the webhook in Jira
- To send Jira changes to Carbon immediately, go to **System → WebHooks** in Jira and create a
+ Changes made in Jira come back to Carbon only through this webhook. To set it up, go to **System → WebHooks** in Jira and create a
webhook with the URL shown in Carbon's setup instructions (`/api/webhook/jira/<your company id>`),
- subscribed to **Issue updated** and **Issue deleted**. Fill in the webhook's **Secret** field, and paste
+ subscribed to **Issue updated**. Fill in the webhook's **Secret** field, and paste
the same value into **Webhook Secret** in Carbon. With it saved, Carbon only accepts webhook requests
Jira has signed.
</Step>
diff --git a/docs/content/docs/integrations/setup/index.mdx b/docs/content/docs/integrations/setup/index.mdx
new file mode 100644
index 0000000000..17916978bb
--- /dev/null
+++ b/docs/content/docs/integrations/setup/index.mdx
@@ -0,0 +1,33 @@
+---
+title: Setup guides
+plan: Business
+description: Step-by-step guides for connecting Slack, Ramp, Xero and Jira to Carbon.
+---
+
+Connecting an app to Carbon takes a minute. You start in Carbon, say yes in the
+other app, and you're connected. Some apps then ask for a setting or two.
+
+<Diagram name="connect" caption="Most connections work this way. Ramp asks one question before step 2." />
+
+## Pick an app
+
+<Cards>
+ <Card title="Slack" href="/docs/integrations/setup/slack">
+ Use the Carbon Assistant in your Slack workspace.
+ </Card>
+ <Card title="Ramp" href="/docs/integrations/setup/ramp">
+ Keep purchase orders, bills and card spend in sync with Ramp.
+ </Card>
+ <Card title="Xero" href="/docs/integrations/setup/xero">
+ Send invoices, bills and journals to Xero.
+ </Card>
+ <Card title="Jira" href="/docs/integrations/setup/jira">
+ Track quality issues in Jira.
+ </Card>
+ <Card title="Onshape" href="/docs/integrations/cad">
+ Bring parts and drawings in from Onshape.
+ </Card>
+</Cards>
+
+Each setup guide also has a short section at the end for teams that run Carbon
+on their own servers. On Carbon Cloud you can skip it.
diff --git a/docs/content/docs/integrations/setup/jira.mdx b/docs/content/docs/integrations/setup/jira.mdx
new file mode 100644
index 0000000000..b17aab6cdc
--- /dev/null
+++ b/docs/content/docs/integrations/setup/jira.mdx
@@ -0,0 +1,116 @@
+---
+title: Connect Jira
+plan: Business
+description: Connect your Jira site to Carbon in three steps, plus an optional webhook for live updates.
+---
+
+Connect Jira to link action tasks on Carbon's quality issues and change notices to
+Jira issues, so status, assignee and notes can sync.
+
+**You need:** permission to change Settings in Carbon, and a login to the Jira
+Cloud site you want to connect. A Jira admin is needed only for the optional
+webhook.
+
+<Diagram name="connect" />
+
+## Connect Jira
+
+<Steps>
+ <Step>
+ ### Press Install in Carbon
+
+ Go to **Settings → Integrations** and press **Install** on the **Jira** card.
+
+ <Screenshot src="/screens/setup-jira-install-card.png" label="Carbon Settings → Integrations, the Jira card with its Install button" />
+ </Step>
+ <Step>
+ ### Allow Carbon in Jira
+
+ Pick **one** Jira site and accept. Carbon links one site: the first one Atlassian
+ lists for your login.
+
+ {/* Replace with /screens/setup-jira-consent.png */}
+ <Screenshot label="Atlassian's consent screen for Carbon, with the site picker and the Accept button" ratio="tall" />
+ </Step>
+ <Step>
+ ### You're connected
+
+ You land back in Carbon, and the Jira card says **Installed**.
+ </Step>
+</Steps>
+
+## Recommended: updates from Jira
+
+Without a webhook, changes made in Jira don't come back to Carbon. Add one so they do.
+
+<Steps>
+ <Step>
+ ### Create a webhook in Jira
+
+ A Jira admin goes to **System → WebHooks** and creates a webhook with the URL shown
+ in Carbon's Jira setup instructions. Tick **Issue updated**, and type a secret
+ into the **Secret** field.
+
+ {/* Replace with /screens/setup-jira-webhook.png */}
+ <Screenshot label="Jira System → WebHooks, a new webhook with the Carbon URL, a secret, and Issue updated ticked" />
+ </Step>
+ <Step>
+ ### Paste the same secret into Carbon
+
+ Open the Jira integration in Carbon and paste the secret into **Webhook Secret**.
+ Carbon then rejects any webhook call not signed with that secret.
+ </Step>
+</Steps>
+
+## What Carbon can do in Jira
+
+When you accept, Jira lets Carbon:
+
+- see Jira users, to match assignees
+- see, create and update issues
+
+<details>
+<summary>The exact Jira scopes, for your Jira admin</summary>
+
+```
+read:jira-user
+read:jira-work
+write:jira-work
+offline_access
+```
+
+</details>
+
+## Something went wrong?
+
+| What you see | What to do |
+| --- | --- |
+| *No Jira Cloud sites found* | Your Atlassian login has no Jira Cloud site, or Atlassian didn't answer. Try again, with a login that has a Jira site. |
+| *Invalid state parameter* | Carbon couldn't match this sign-in to one you started: it took over an hour, or finished in another browser or Carbon account. Start again from **Settings → Integrations**. |
+
+## Running Carbon on your own servers?
+
+Skip this on Carbon Cloud. The Jira app is already set up.
+
+On your own servers, you create the Atlassian app once:
+
+1. Create an OAuth 2.0 integration in the
+ [Atlassian developer console](https://developer.atlassian.com/console/myapps/).
+2. Add the Jira API with `read:jira-user`, `read:jira-work` and `write:jira-work`.
+3. Set the callback URL to `https://<your Carbon address>/api/integrations/jira/oauth`.
+4. Set `JIRA_CLIENT_ID` and `JIRA_CLIENT_SECRET` in Carbon's environment, then
+ restart Carbon. Until `JIRA_CLIENT_ID` is set, the Jira card says **Not Configured**.
+
+{/* Replace with /screens/setup-jira-app.png */}
+<Screenshot label="Atlassian developer console, the Carbon app's Jira API scopes and callback URL" />
+
+## Related
+
+<Cards>
+ <Card title="Project management" href="/docs/integrations/project-management">
+ What Carbon syncs with Jira.
+ </Card>
+ <Card title="Setup guides" href="/docs/integrations/setup">
+ Connect your other apps.
+ </Card>
+</Cards>
diff --git a/docs/content/docs/integrations/setup/meta.json b/docs/content/docs/integrations/setup/meta.json
new file mode 100644
index 0000000000..839532d31d
--- /dev/null
+++ b/docs/content/docs/integrations/setup/meta.json
@@ -0,0 +1,4 @@
+{
+ "title": "Setup guides",
+ "pages": ["index", "slack", "ramp", "xero", "jira"]
+}
diff --git a/docs/content/docs/integrations/setup/ramp.mdx b/docs/content/docs/integrations/setup/ramp.mdx
new file mode 100644
index 0000000000..fd55e11e65
--- /dev/null
+++ b/docs/content/docs/integrations/setup/ramp.mdx
@@ -0,0 +1,165 @@
+---
+title: Connect Ramp
+plan: Business
+description: Connect Ramp to Carbon in four steps, and pick how the two should work together.
+---
+
+Connect Ramp to keep purchase orders, bills and card spend in sync between Ramp
+and Carbon.
+
+**You need:** permission to change Settings in Carbon, and a Ramp login with the
+**Admin** or **Business Owner** role.
+
+<Diagram name="connect" />
+
+## First, one question: who keeps your books?
+
+Ramp lets only one accounting system connect to it. So before you connect, Carbon
+asks which system that is.
+
+<Diagram name="ramp-modes" />
+
+- **Carbon is my accounting system.** Card charges and bills from Ramp flow into
+ Carbon's books, and reimbursements arrive as drafts for you to review. Once the
+ card liability account is set, Carbon also sends your chart of accounts to Ramp so
+ your team can code spend there.
+- **Another system posts my ledger.** Your other accounting system stays connected
+ to Ramp and keeps posting the spend. Carbon only reads back which bills were paid.
+
+In both modes, Carbon sends purchase orders and draft bills to Ramp, and creates
+their vendors there.
+
+## Connect Ramp
+
+<Steps>
+ <Step>
+ ### Press Install in Carbon
+
+ Go to **Settings → Integrations** and press **Install** on the **Ramp** card.
+
+ <Screenshot src="/screens/setup-ramp-install-card.png" label="Carbon Settings → Integrations, the Ramp card with its Install button" />
+ </Step>
+ <Step>
+ ### Answer the question
+
+ Pick **Carbon is my accounting system** or **Another system posts my ledger**,
+ then press **Continue**.
+
+ <Screenshot src="/screens/setup-ramp-mode.png" label="Carbon's How will you use Ramp? dialog with the two choices" />
+ </Step>
+ <Step>
+ ### Allow Carbon in Ramp
+
+ Sign in to Ramp as an Admin or Business Owner, and allow access.
+
+ {/* Replace with /screens/setup-ramp-consent.png */}
+ <Screenshot label="Ramp's consent screen for Carbon, listing the access requested" ratio="tall" />
+ </Step>
+ <Step>
+ ### Finish in Carbon
+
+ You land back in Carbon. Open the Ramp integration and choose what syncs under
+ **Sync**. Everything is on to start with.
+
+ If you picked **Carbon is my accounting system**, also fill in the accounts under
+ **Accounts**. Card spend can't sync until **Card liability account** is set.
+ </Step>
+</Steps>
+
+## What Carbon can do in Ramp
+
+| | Carbon is my accounting system | Another system posts my ledger |
+| --- | :---: | :---: |
+| Create and update purchase orders | ✓ | ✓ |
+| Create draft bills, and see bills and their payments | ✓ | ✓ |
+| Create and update vendors | ✓ | ✓ |
+| See your business and its entities | ✓ | ✓ |
+| See card transactions, receipts, reimbursements, repayments, transfers, cashback and statements | ✓ | |
+| See Ramp's accounting connection and coding options | ✓ | ✓ |
+| Connect as Ramp's accounting system and publish your chart of accounts | ✓ | |
+
+<details>
+<summary>The exact Ramp scopes, for your Ramp admin</summary>
+
+**Carbon is my accounting system**
+
+```
+accounting:read
+accounting:write
+bills:read
+bills:write
+business:read
+cashbacks:read
+entities:read
+offline_access
+purchase_orders:read
+purchase_orders:write
+receipts:read
+reimbursements:read
+repayments:read
+statements:read
+transactions:read
+transfers:read
+vendors:read
+vendors:write
+```
+
+**Another system posts my ledger**
+
+```
+accounting:read
+bills:read
+bills:write
+business:read
+entities:read
+offline_access
+purchase_orders:read
+purchase_orders:write
+vendors:read
+vendors:write
+```
+
+</details>
+
+## Something went wrong?
+
+| What you see | What to do |
+| --- | --- |
+| *Another system is connected to Ramp as its accounting system* | Your other accounting system already holds Ramp's one spot. Uninstall Ramp in Carbon, then connect again and pick **Another system posts my ledger**. Or disconnect the other system in Ramp, then open the Ramp integration in Carbon and save its settings. |
+| *Ramp denied the connection* | Ramp refused access, for example because it was cancelled. Connect again and allow access, signed in as an Admin or Business Owner. |
+| *The Ramp connection expired* | Carbon couldn't match this sign-in to one you started: it took over an hour, or finished in another browser or Carbon account. Start again from **Settings → Integrations**. |
+| *Ramp connected but setup didn't finish* | Open the Ramp integration and save its settings to finish setup. If that fails too, uninstall Ramp and connect again. |
+
+Picked the wrong answer to the first question? Uninstall Ramp in Carbon and
+connect again.
+
+## Running Carbon on your own servers?
+
+Skip this on Carbon Cloud. The Ramp app is already set up.
+
+On your own servers, you create the Ramp app once:
+
+1. In Ramp's developer settings, create an app and turn on the **refresh token**
+ grant.
+2. Open **Set scopes** and turn on every scope in the first list above (it includes
+ the second). If one is missing, Ramp refuses the connection with
+ `invalid_scope`, and Carbon shows *Ramp denied the connection*.
+3. Add this redirect URL, where your Carbon address is the one in `ERP_URL`:
+ `https://<your Carbon address>/api/integrations/ramp/oauth`.
+4. Set `RAMP_CLIENT_ID` and `RAMP_CLIENT_SECRET` in Carbon's environment, then
+ restart Carbon. Until then the Ramp card says **Not Configured**.
+
+<Screenshot src="/screens/setup-ramp-scopes-1.png" label="Ramp's Set scopes dialog, top half, with Carbon's scopes switched on" />
+<Screenshot src="/screens/setup-ramp-scopes-2.png" label="Ramp's Set scopes dialog, scrolled down, with the rest of Carbon's scopes switched on" caption="Ramp's Set scopes dialog. Check your switches against the lists above rather than copying this picture." />
+
+Carbon tells Ramp where to send updates by itself when you connect. Ramp needs to
+reach your Carbon address over the internet for that. If it can't, Carbon still
+catches up every hour.
+
+## Related
+
+<Cards>
+ <Card title="Setup guides" href="/docs/integrations/setup">
+ Connect your other apps.
+ </Card>
+</Cards>
diff --git a/docs/content/docs/integrations/setup/slack.mdx b/docs/content/docs/integrations/setup/slack.mdx
new file mode 100644
index 0000000000..11dbdfdc9e
--- /dev/null
+++ b/docs/content/docs/integrations/setup/slack.mdx
@@ -0,0 +1,118 @@
+---
+title: Connect Slack
+plan: Business
+description: Add the Carbon Assistant to your Slack workspace in three steps.
+---
+
+Connect Slack to use the Carbon Assistant in your Slack workspace.
+
+**You need:** permission to change Settings in Carbon, and permission to add apps
+to your Slack workspace.
+
+<Diagram name="connect" />
+
+## Connect Slack
+
+<Steps>
+ <Step>
+ ### Press Install in Carbon
+
+ Go to **Settings → Integrations** and press **Install** on the **Slack** card. A
+ Slack window opens.
+
+ <Screenshot src="/screens/setup-slack-install-card.png" label="Carbon Settings → Integrations, the Slack card with its Install button" />
+ </Step>
+ <Step>
+ ### Allow Carbon in Slack
+
+ Pick your workspace and the channel Carbon should post in, then press **Allow**.
+
+ {/* Replace with /screens/setup-slack-consent.png */}
+ <Screenshot label="Slack's consent screen for the Carbon app, with the Allow button" ratio="tall" />
+ </Step>
+ <Step>
+ ### You're connected
+
+ The Slack window turns into Carbon's Integrations page, where the Slack card says
+ **Installed**. Close that window and refresh your first Carbon tab.
+
+ Carbon also tries to post a welcome message in the channel you picked.
+ </Step>
+</Steps>
+
+## What Carbon can do in Slack
+
+When you press Allow, Slack lets Carbon:
+
+- send messages as @Carbon Assistant
+- send messages to channels it isn't a member of
+- post messages to specific channels in Slack
+- add shortcuts and slash commands that people can use
+- act as an app agent
+- view files shared in channels and conversations it has been added to
+- view messages and other content in direct messages it has been added to
+- view the name, email domain and icon of your workspace
+- view people in your workspace, and their email addresses
+
+<Screenshot src="/screens/setup-slack-permissions.png" label="Slack's permissions page for the Carbon Assistant app, listing what it can do and what it can view" caption="Slack shows this list for the Carbon Assistant. It can include a few more than Carbon asks for when you install." />
+
+<details>
+<summary>The exact Slack permissions, for your Slack admin</summary>
+
+```
+assistant:write
+chat:write
+chat:write.public
+commands
+files:read
+im:history
+incoming-webhook
+team:read
+users:read
+users:read.email
+```
+
+</details>
+
+## Something went wrong?
+
+| What you see | What to do |
+| --- | --- |
+| *Invalid company* or *Invalid user* | You switched Carbon company or account partway through. Start again from the company you want to connect. |
+| *Slack OAuth error* | Start again from Carbon. If it keeps happening, contact Carbon support. |
+| An error after more than 10 minutes in the Slack window | The sign-in expired. Start again from Carbon. |
+| Slack opened in the same tab, not a window | Your browser blocked the popup. That's fine: finish in Slack and you'll come back to Carbon. |
+
+## Running Carbon on your own servers?
+
+Skip this on Carbon Cloud. The Slack app is already set up.
+
+On your own servers, you create the Slack app once:
+
+1. Create an app at [api.slack.com/apps](https://api.slack.com/apps).
+2. Add every permission from the list above as a **bot** permission.
+3. Add this redirect URL: `https://<your Carbon address>/api/integrations/slack/oauth`.
+4. Turn on interactivity, with this request URL:
+ `https://<your Carbon address>/api/integrations/slack/interactive`.
+ Add a global shortcut with the callback ID `create_ncr_modal`. It opens Carbon's
+ **Create Issue** form.
+5. Set these in Carbon's environment, then restart Carbon:
+
+| Variable | Value |
+| --- | --- |
+| `SLACK_CLIENT_ID` | The app's client ID |
+| `SLACK_CLIENT_SECRET` | The app's client secret |
+| `SLACK_OAUTH_REDIRECT_URL` | The redirect URL from step 3, exactly |
+| `SLACK_SIGNING_SECRET` | The app's signing secret. Required: without it the install ends on an error, and Carbon rejects every shortcut. |
+| `SLACK_STATE_SECRET` | Any long random string. Required: without it the install can't start. |
+
+## Related
+
+<Cards>
+ <Card title="Assistant" href="/docs/integrations/assistant">
+ What the Carbon Assistant does in Slack.
+ </Card>
+ <Card title="Setup guides" href="/docs/integrations/setup">
+ Connect your other apps.
+ </Card>
+</Cards>
diff --git a/docs/content/docs/integrations/setup/xero.mdx b/docs/content/docs/integrations/setup/xero.mdx
new file mode 100644
index 0000000000..9c3db10786
--- /dev/null
+++ b/docs/content/docs/integrations/setup/xero.mdx
@@ -0,0 +1,106 @@
+---
+title: Connect Xero
+plan: Business
+description: Connect your Xero organisation to Carbon in three steps.
+---
+
+Connect Xero to send Carbon's customers, suppliers, invoices, bills, payments and
+journals to your Xero books, and bring payments made in Xero back into Carbon.
+
+**You need:** permission to change Settings in Carbon, a Xero login that can
+connect apps to your organisation, and the same base currency on your Carbon
+company as on your Xero organisation.
+
+<Diagram name="connect" />
+
+## Connect Xero
+
+<Steps>
+ <Step>
+ ### Press Install in Carbon
+
+ Go to **Settings → Integrations** and press **Install** on the **Xero** card.
+
+ <Screenshot src="/screens/setup-xero-install-card.png" label="Carbon Settings → Integrations, the Xero card with its Install button" />
+ </Step>
+ <Step>
+ ### Allow Carbon in Xero
+
+ Sign in to Xero, pick **one** organisation and allow access. Carbon links one
+ organisation: the first one Xero lists for your login.
+
+ {/* Replace with /screens/setup-xero-consent.png */}
+ <Screenshot label="Xero's consent screen for Carbon, with the organisation picker and the Allow access button" ratio="tall" />
+ </Step>
+ <Step>
+ ### Finish in Carbon
+
+ You land back in Carbon. Choose what syncs and run the first sync, as shown on
+ the [Accounting](/docs/integrations/accounting) page.
+ </Step>
+</Steps>
+
+## What Carbon can do in Xero
+
+When you allow access, Xero lets Carbon:
+
+- create and update contacts (your customers and suppliers)
+- create and update invoices, bills and credit notes, and create and read payments
+- create bank transactions and manual journals
+- read your chart of accounts and tracking categories, and create items
+- read your trial balance, when you turn on accounting in Carbon
+
+<details>
+<summary>The exact Xero scopes, for your Xero admin</summary>
+
+```
+offline_access
+accounting.contacts
+accounting.settings
+accounting.invoices
+accounting.payments
+accounting.banktransactions
+accounting.manualjournals
+accounting.reports.trialbalance.read
+```
+
+</details>
+
+## Something went wrong?
+
+| What you see | What to do |
+| --- | --- |
+| *Company base currency not configured* | Set the base currency on your Carbon company, then connect again. |
+| *Currency mismatch: Your Carbon company uses …* | Your Carbon company and your Xero organisation use different base currencies. Make them match, then connect again. |
+| *No Xero connections found* | Xero didn't return an organisation for your login. Connect again and pick one. |
+| *Invalid state parameter* | Carbon couldn't match this sign-in to one you started: it took over an hour, or finished in another browser or Carbon account. Start again from **Settings → Integrations**. |
+| Carbon asks you to reconnect when you pull the trial balance while turning on accounting | Your connection is older than the trial balance permission, or it has expired. Connect Xero again. |
+
+## Running Carbon on your own servers?
+
+Skip this on Carbon Cloud. The Xero app is already set up.
+
+On your own servers, you create the Xero app once:
+
+1. Create an app at [developer.xero.com](https://developer.xero.com), with this
+ redirect URI: `https://<your Carbon address>/api/integrations/xero/oauth`.
+2. Set its client ID and client secret as `XERO_CLIENT_ID` and `XERO_CLIENT_SECRET`
+ in Carbon's environment.
+3. For live updates from Xero, add a webhook to
+ `https://<your Carbon address>/api/webhook/xero` for contacts and invoices, and set
+ its key as `XERO_WEBHOOK_SECRET`.
+4. Restart Carbon.
+
+{/* Replace with /screens/setup-xero-app.png */}
+<Screenshot label="Xero developer portal, the Carbon app's configuration with its redirect URI" />
+
+## Related
+
+<Cards>
+ <Card title="Accounting" href="/docs/integrations/accounting">
+ What syncs with Xero, and the settings after you connect.
+ </Card>
+ <Card title="Setup guides" href="/docs/integrations/setup">
+ Connect your other apps.
+ </Card>
+</Cards>
diff --git a/docs/content/docs/platform/self-hosting/environment-variables.mdx b/docs/content/docs/platform/self-hosting/environment-variables.mdx
index e270c3f071..9307b8addd 100644
--- a/docs/content/docs/platform/self-hosting/environment-variables.mdx
+++ b/docs/content/docs/platform/self-hosting/environment-variables.mdx
@@ -113,6 +113,11 @@ OAuth credentials for each connector, all optional, set only the ones you use.
<EnvVar name="JIRA_CLIENT_SECRET" type="string">Jira OAuth client secret.</EnvVar>
<EnvVar name="SLACK_CLIENT_ID" type="string">Slack OAuth client id.</EnvVar>
<EnvVar name="SLACK_CLIENT_SECRET" type="string">Slack OAuth client secret.</EnvVar>
+<EnvVar name="SLACK_OAUTH_REDIRECT_URL" type="url">Callback for the Slack install: `https://<erp-host>/api/integrations/slack/oauth`. Must be registered on the Slack app. See [Connect Slack](/docs/integrations/setup/slack).</EnvVar>
+<EnvVar name="SLACK_SIGNING_SECRET" type="string">The Slack app's signing secret. Required: without it the Slack install ends on an error, and Carbon refuses Slack interactivity requests it cannot verify.</EnvVar>
+<EnvVar name="SLACK_STATE_SECRET" type="string">Any long random string. Signs the state of a Slack install. Required: without it the install cannot start.</EnvVar>
+<EnvVar name="RAMP_CLIENT_ID" type="string">Client id of the Ramp developer app. Without it the Ramp card reads Not Configured. See [Connect Ramp](/docs/integrations/setup/ramp).</EnvVar>
+<EnvVar name="RAMP_CLIENT_SECRET" type="string">Client secret of the Ramp developer app.</EnvVar>
<EnvVar name="ONSHAPE_CLIENT_ID" type="string">Client id of the Onshape OAuth application for the pull integration (`onshape`). Without it the Onshape card reads Not Configured.</EnvVar>
<EnvVar name="ONSHAPE_CLIENT_SECRET" type="string">Client secret of the pull integration's Onshape OAuth application.</EnvVar>
<EnvVar name="ONSHAPE_OAUTH_REDIRECT_URL" type="url">Callback for the pull integration: `https://<erp-host>/api/integrations/onshape/oauth`. Must be registered on the pull integration's Onshape application.</EnvVar>
diff --git a/docs/public/screens/setup-jira-install-card.png b/docs/public/screens/setup-jira-install-card.png
new file mode 100644
index 0000000000..f92479c342
Binary files /dev/null and b/docs/public/screens/setup-jira-install-card.png differ
diff --git a/docs/public/screens/setup-ramp-install-card.png b/docs/public/screens/setup-ramp-install-card.png
new file mode 100644
index 0000000000..daef764a3f
Binary files /dev/null and b/docs/public/screens/setup-ramp-install-card.png differ
diff --git a/docs/public/screens/setup-ramp-mode.png b/docs/public/screens/setup-ramp-mode.png
new file mode 100644
index 0000000000..fb48a0fe23
Binary files /dev/null and b/docs/public/screens/setup-ramp-mode.png differ
diff --git a/docs/public/screens/setup-ramp-scopes-1.png b/docs/public/screens/setup-ramp-scopes-1.png
new file mode 100644
index 0000000000..16b2d6b7ff
Binary files /dev/null and b/docs/public/screens/setup-ramp-scopes-1.png differ
diff --git a/docs/public/screens/setup-ramp-scopes-2.png b/docs/public/screens/setup-ramp-scopes-2.png
new file mode 100644
index 0000000000..661c90eb23
Binary files /dev/null and b/docs/public/screens/setup-ramp-scopes-2.png differ
diff --git a/docs/public/screens/setup-slack-install-card.png b/docs/public/screens/setup-slack-install-card.png
new file mode 100644
index 0000000000..4b341c4ef5
Binary files /dev/null and b/docs/public/screens/setup-slack-install-card.png differ
diff --git a/docs/public/screens/setup-slack-permissions.png b/docs/public/screens/setup-slack-permissions.png
new file mode 100644
index 0000000000..379da86a5d
Binary files /dev/null and b/docs/public/screens/setup-slack-permissions.png differ
diff --git a/docs/public/screens/setup-xero-install-card.png b/docs/public/screens/setup-xero-install-card.png
new file mode 100644
index 0000000000..67c4ac9f02
Binary files /dev/null and b/docs/public/screens/setup-xero-install-card.png differ