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.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
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.tsxindex 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.mdxindex 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**, **salesWhile **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 syncdiff --git a/docs/content/docs/integrations/assistant.mdx b/docs/content/docs/integrations/assistant.mdxindex 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.jsonindex 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.mdxindex 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## JiraConnect 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 awebhook 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 pastethe same value into **Webhook Secret** in Carbon. With it saved, Carbon only accepts webhook requestsJira has signed.</Step>diff --git a/docs/content/docs/integrations/setup/index.mdx b/docs/content/docs/integrations/setup/index.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.jsonnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxindex 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.pngnew file mode 100644index 0000000000..f92479c342Binary files /dev/null and b/docs/public/screens/setup-jira-install-card.png differdiff --git a/docs/public/screens/setup-ramp-install-card.png b/docs/public/screens/setup-ramp-install-card.pngnew file mode 100644index 0000000000..daef764a3fBinary files /dev/null and b/docs/public/screens/setup-ramp-install-card.png differdiff --git a/docs/public/screens/setup-ramp-mode.png b/docs/public/screens/setup-ramp-mode.pngnew file mode 100644index 0000000000..fb48a0fe23Binary files /dev/null and b/docs/public/screens/setup-ramp-mode.png differdiff --git a/docs/public/screens/setup-ramp-scopes-1.png b/docs/public/screens/setup-ramp-scopes-1.pngnew file mode 100644index 0000000000..16b2d6b7ffBinary files /dev/null and b/docs/public/screens/setup-ramp-scopes-1.png differdiff --git a/docs/public/screens/setup-ramp-scopes-2.png b/docs/public/screens/setup-ramp-scopes-2.pngnew file mode 100644index 0000000000..661c90eb23Binary files /dev/null and b/docs/public/screens/setup-ramp-scopes-2.png differdiff --git a/docs/public/screens/setup-slack-install-card.png b/docs/public/screens/setup-slack-install-card.pngnew file mode 100644index 0000000000..4b341c4ef5Binary files /dev/null and b/docs/public/screens/setup-slack-install-card.png differdiff --git a/docs/public/screens/setup-slack-permissions.png b/docs/public/screens/setup-slack-permissions.pngnew file mode 100644index 0000000000..379da86a5dBinary files /dev/null and b/docs/public/screens/setup-slack-permissions.png differdiff --git a/docs/public/screens/setup-xero-install-card.png b/docs/public/screens/setup-xero-install-card.pngnew file mode 100644index 0000000000..67c4ac9f02Binary files /dev/null and b/docs/public/screens/setup-xero-install-card.png differ