Xero Grid Integration

The Xero Grid integration connects Salesforce to Xero Accounting, allowing teams to view, search, and export live accounting records (Invoices, Bills, Contacts, Accounts, and Payments) directly inside AppColab Grid.

What’s Deployed

One-Time Manual Setup

1. Register App in Xero Developer Portal

1. Log into the Xero Developer Portal and click New App.
2. Set:
   • App type: Web app
   • App name: AppColab Grid
   • Company or application URL: https://appcolab.com
   • Redirect URI: Paste your Salesforce OAuth Callback URL from your Xero_OAuth Auth Provider in Salesforce Setup.
3. Click Create app and copy your Client ID and Client Secret.

2. Configure Credentials in Salesforce Setup

2.1 Create the Auth. Provider

1. In Salesforce Setup, enter Auth. Providers in the Quick Find box and click New:
   • Provider Type: OpenIdConnect
   • Name: Xero_OAuth
   • URL Suffix: Xero_OAuth
   • Consumer Key: Paste your Xero Client ID from Step 1.
   • Consumer Secret: Paste your Xero Client Secret from Step 1.
   • Default Scopes: openid profile email accounting.transactions accounting.contacts accounting.settings offline_access
   • Click Save.
2. Copy the Callback URL displayed at the bottom of the page and paste it into your Xero App’s Redirect URIs in the Xero Developer Portal.

2.2 Create the External Credential

1. In Salesforce Setup, enter Named Credentials in Quick Find.
2. Click the External Credentials tab → click New:
   • Label: Xero
   • Name: Xero
   • Authentication Protocol: OAuth 2.0
   • Authentication Provider: Select Xero_OAuth
   • Scope: openid profile email offline_access accounting.invoices accounting.contacts accounting.settings
   • Click Save.
3. In the Principals section, click New:
   • Parameter Name: ApiKey
   • Sequence Number: 1
   • Identity Type: Named Principal
   • Scope: openid profile email offline_access accounting.invoices accounting.contacts accounting.settings
   • Click Save.
4. Authenticate the Principal (Crucial Step):

   [!IMPORTANT] Creating the Auth Provider and Principal is not enough. You must complete the 3-legged OAuth consent flow:

   • On the ApiKey row, click the dropdown action arrow ▼ → click Authenticate.
   • A popup window opens to Xero. Log in with your Xero account, select your target organization, and click Allow access.
   • Upon returning to Salesforce, verify the status displays Configured with a green checkmark.

2.3 Create the Named Credential

1. Click the Named Credentials tab (next to External Credentials) → click New:
   • Label: Xero
   • Name: Xero
   • URL: https://api.xero.com
   • External Credential: Select Xero
   • Generate Authorization Header: Checked
   • Allow Formulas in HTTP Header: Checked
2. Click Save.

3. Assign Permission Set Access

1. In Salesforce Setup, enter Permission Sets in Quick Find.
2. Select Integration Admin (or Xero_Integration / your custom admin permission set).
3. Click External Credential Principal Access → click Edit.
4. Add Xero - ApiKey to Enabled External Credential Principals.
5. Click Save and verify the permission set is assigned to your Salesforce users.

Creating a Xero Grid Definition

1. In Salesforce, open AppColab Grid app → Grid Definitions tab → click New Grid Definition.
2. Fill in:
   • Grid Settings Name: Xero_Invoices_Grid
   • Grid Label: Xero Invoices
   • Is Active?: Checked
   • Data Provider Class: XeroGridDataProvider
   • Data Provider Configuration:

     {
       "tenantId": "YOUR_XERO_TENANT_ID",
       "resource": "invoices"
     }
     

     How to find your Tenant ID:

     1. In the Xero Developer Portal, open your app (AppColab Integration).
     2. On the left sidebar menu, click Connection management.
     3. Find your connected organization in the table and copy the Tenant ID UUID (e.g. 83d44152-5f32-405b-a449-41b1c4f59590).

     Tip: Set "resource" to "contacts", "accounts", "bills", or "payments" to display other financial records.

3. Click Save & Next → proceed to Preview.
4. Real-time invoices render with Invoice Number, Contact Name, Date, Due Date, Total, Amount Due, Status, and Currency!

Supported Grid Features

Troubleshooting & Common Gotchas

• 403 Forbidden: AuthenticationUnsuccessful:
  • Cause: The Consumer Key and Secret were saved in the Auth Provider, but the Principal in the External Credential was never authenticated. Without completing the OAuth handshake, Salesforce has no active user tokens.
  • Fix: In Salesforce Setup > Named Credentials > External Credentials > Xero > Principals, click the action arrow ▼ next to ApiKey → click Authenticate, sign in to Xero, and approve access. Ensure the status turns to Configured.
• 400 Bad Request / Tenant ID missing or invalid:
  • Cause: The "tenantId" in Data Provider Configuration JSON does not match any authorized tenant UUID for your Xero connection.
  • Fix: Go to Xero Developer Portal > your app > Connection management to copy the exact Tenant ID UUID.
• 401 Unauthorized / Token Expired:
  • Cause: Authorization was revoked or refreshed token was invalidated on the Xero portal.
  • Fix: Click Authenticate again on the ApiKey principal row in Salesforce Setup to renew credentials.
• Missing External Credential Access:
  • Cause: The user lacks access to the Xero - ApiKey principal.
  • Fix: Add Xero - ApiKey under External Credential Principal Access in the assigned permission set.