This article explains the standardised integration between Salesforce and Xledger, designed to support grant processing from start to finish. The integration posts double-entry transactions into Xledger using data from Salesforce, reducing manual processing and improving control over supplier payments and grant tracking.
Setting things up
To begin the integration between Salesforce and Xledger, ensure you have administrative access to both platforms. This setup phase involves configuring authentication and preparing your standing data.
When ready get in touch with your Xledger CSM representative or support to book a set up call with the integration team to perform the following tasks. I might also be a good idea to get in touch with your Salesforce contact as some steps in this guide need to take place in there.
Authentication
On Xledger's side
Access Xledger.net and log in to your Xledger account with domain admin credentials. Navigate to the API settings in Xledger (Administration>System Access>GraphQL>API Tokens). To enable API access, generate an API key that the integration will use to communicate with Xledger. Ensure that the API key has the necessary permissions to read and write data, particularly for expenses and accounting modules.
Securely share the Token with your integration consultant. Read here for more information on how to Generate an API token.
On Salesforce's side
To connect to your Salesforce environment, we’ll need a connected app to be created. This allows us to authenticate using OAuth and access the relevant data for the integration. The steps below will need to be completed by your Salesforce administrator:
Log in to Salesforce with admin access
Go to Setup > App Manager
Click New Connected App
Enter the app name and your contact email
-
Under the API (Enable OAuth Settings) section:
Tick Enable OAuth Settings
Set the Callback URL to:
https://xledger-h.cyclr.uk/connector/callbackChoose the OAuth scopes needed for the integration — this typically includes full access and access to data
Save the connected app
After saving, go into the app's Manage page to find the Consumer Key and Consumer Secret — we’ll need these for the integration
We’ll use these credentials to authenticate and securely access your data. If you’re not sure which OAuth scopes to enable or have a more restricted security model in place, just let us know and we can advise based on your setup.
If you need step-by-step guidance, Salesforce’s own documentation is available here: Create a Connected App
What is included in this integration
The integration is built to support the full lifecycle of grants and supplier setup. Specifically, it includes:
Grant creation
Once approved in Salesforce, a top-level grant is posted into Xledger using the addGLImportItems mutation. This is posted as a double-entry transaction.
Grant payments
When payments are made against an approved grant, a matching double-entry transaction is posted into Xledger. Bank details are checked before import.
Grant write-backs
If a grant is cancelled, and meets the right conditions (such as a return type), a write-back is created in Xledger.
Supplier management
If the supplier linked to a grant or payment doesn’t exist in Xledger, the system will create it automatically using details from Salesforce, including bank information. Existing records are updated if changes are found.
Data Mapping
Below is a summary of the key data that is sent from Salesforce into Xledger during each part of the process.
Top-level grant / grant payment / write-back (via addGLImportItems)
| Field | Source in Salesforce | Notes |
|---|---|---|
| tRegnumber | Auto-generated or passed through | Used as unique reference |
| transactionSource | Static value (e.g., “GL”) | Identifies source of the transaction |
| postedDate | Grant or payment date | Controls when it appears in Xledger |
| invoiceDate | Date of approval or payment | Optional |
| account | GL account | Must exist in Xledger |
| text | Grant name or description | Free text field |
| taxRule | Tax rule (if applicable) | Must match code in Xledger |
| costCentre | Cost centre code | Must match code in Xledger |
| project | Project code | Must match code in Xledger |
| subLedger | Subledger type (e.g. supplier) | Used for reporting |
| amount | Total amount | Positive for payments, negative for write-backs |
| currency | Currency code | Must be valid in Xledger |
| jobLevel | Optional for tracking/reporting | Can be left blank |
| extIdentifier | Salesforce record ID or similar | Used for deduplication |
Set-up and configuration
During the onboarding phase, we’ll run a discovery session with your team to:
Understand how your grants and payments are stored in Salesforce
Identify the correct endpoints, objects and fields
Align data codes with Xledger (e.g. account and project codes)
Decide how to handle scenarios like missing data, default values, or test environments
Because Salesforce is highly customisable, each implementation can vary significantly in its data model and API structure. This often means the integration will use custom objects, fields or bespoke endpoints tailored specifically to your organisation. We account for this during onboarding to ensure the integration aligns cleanly with your existing Salesforce configuration.
From there, we’ll configure the integration to pull the relevant data every 15 minutes and post it into Xledger. Any records that fail validation will be logged.
Error handling
The integration includes built-in error handling. Transactions will only be sent to Xledger if all required fields are populated. For example:
If project or cost centre codes don’t exist in Xledger, the GL import will fail for that record
If the grant hasn’t been marked as Approved or the write-back criteria are not met, the record will be ignored