Xero

Overview

This article explains how to connect your Kompass account to Xero for automatic syncing of clients and invoices. Only admin users can set up and manage the Xero connection.

Prerequisites

• A Xero account with access to the organisation you wish to connect
• Admin access to your Kompass account
• The Xero permission group on your user. If you do not see a Xero group in the Admin site, contact Kompass support to have Xero permissions added to your account.

Step 1: Create a Xero Configuration

1. Navigate to the Admin site by adding /admin after your Kompass URL (e.g. your-server.kompassbms.com/admin).
2. Under the Xero group, select Configurations. If the Xero group is not visible, your user is missing the required permissions; contact Kompass support to have them added.
3. Click Add in the top right to create a new configuration.
4. Select the Kompass organisation(s) that should be linked to this Xero connection.
5. Click Save. Leave the Enable checkbox unticked for now; you will enable the sync in Step 4 once contacts have been reconciled.

Step 2: Authorise with Xero

1. On the Configurations list page, select the configuration you just created using the tick-box.
2. From the Action drop-down menu, select Authorize with Xero and click Go.
3. You will be redirected to the Xero login page. Sign in with your Xero credentials.
4. Xero will ask you to select which Xero organisation to authorise. Choose the organisation you wish to connect.
5. Review the permissions Kompass is requesting and click Allow access.
6. You will be redirected back to the Kompass Admin with a success message.

Step 3: Reconcile Existing Xero Contacts

To reconcile existing Xero contacts with Kompass clients before enabling the sync:

1. On the Configurations list page, select your configuration using the tick-box.
2. From the Action drop-down, select Compare contacts with Kompass clients (email CSV) and click Go. Kompass will fetch every contact from the connected Xero organisation, match them against your Kompass clients by name, and email a download link for a CSV report to the address on your user account. This typically takes a few minutes for organisations with a few hundred contacts.
3. Open the CSV. Each row shows a Xero contact, a candidate Kompass client match, and a confidence percentage. Rows with no match indicate either a Kompass client missing from Xero, or a Xero contact with no corresponding Kompass client.
4. Review the high and medium-confidence matches and confirm they are correct. Correct any false positives by editing the kompass_id column (or clearing it to leave the row unmatched).
5. For each confirmed match, create a Xero Contact link record so the sync uses the existing Xero contact instead of creating a new one: in the Admin site under Xero, open Contacts, click Add, select the Kompass client, and paste the corresponding Xero UUID from the CSV. Save.
6. You can re-run the comparison after creating link records to confirm the unmatched list has shrunk to only the contacts that genuinely need creating in Xero.

Step 4: Configure Sync Settings and Enable

Once contact reconciliation is complete (or if the Xero organisation was empty to start with), configure the sync and enable it:

1. Open the configuration and set the Account default; this is the Xero account used for all invoice syncs.
2. Under Sync modules, select the modules you wish to sync:
   • Clients: syncs Kompass clients as Xero contacts
   • Invoices: syncs Kompass invoices as Xero invoices, credit notes, or manual journals
3. If you enable Invoices, you must also enable Clients.
4. Tick the Enable checkbox to activate the connection.
5. Click Save.

Step 5: Map Items, Accounts, and Tax Rates (Optional)

For more accurate invoice syncing, you can configure additional mappings in the Admin under Xero:

• Items: map Kompass departments/services to Xero items. You can also set a default item as a fallback.
• Accounts: map Kompass nominal accounts to Xero general ledger accounts.
• Tax rates: link Kompass VAT rates to Xero tax types.

Disconnecting from Xero

If you need to disconnect your Xero integration:

1. Go to Xero → Configurations.
2. Select the configuration using the tick-box.
3. From the Action drop-down, select Disconnect from Xero and click Go.
4. Confirm the disconnection when prompted.

The sync will stop immediately. You can re-authorise at any time by following Step 2 again.