How to configure the Xero integration

This guide outlines the essential process for setting up a new G.J. Gardner office and its first-time integration with Xero. Tailored specifically for our support teams, it provides a comprehensive walkthrough of the steps required to establish a seamless connection between G.J. Software and Xero. This document is crucial for ensuring that the integration is executed accurately and efficiently, establishing a solid foundation for the office’s financial management systems from the outset.

IMPORTANT: It is crucial to adhere strictly to the designated Xero account for each office. Under no circumstances should an office be connected to a different Xero account than the one originally used for its setup. This guideline is imperative to maintain the integrity and accuracy of the office’s financial records and to ensure compliance with our standard operational procedures. Any deviation from this protocol can result in significant data discrepancies and operational challenges.

Getting Started

The integration process begins with the support team setting up the office’s Xero account. This setup involves two critical steps: ensuring that the standard franchise office Chart of Accounts has been imported, as outlined in the Xero guide for importing a chart of accounts, and managing user access by inviting specific emails based on the office’s location.

Inviting Users to Xero

Refer to the guide on Xero Central for how to add users to Xero. 

• In Australia: Invite xero@gjgardner.com.au and finance@gjgardner.com.au as Advisors to the Xero file.
• In the United States: Only xero@gjgardner.com needs to be invited as an Advisor.

These steps must be executed by the support team to ensure proper configuration and access control for each office’s Xero account.

After the Xero account has been created and the chart of accounts has been imported we can begin the integration process with G.J. Software.

1. Log in to the office in G.J. Software.
2. Open a new tab and log in to the new Xero account.
3. Open a new tab and log in to Xero Developer using the primary Xero account we invited as an Advisor to the organization in the previous section.

1. Create a Xero app

In G.J. Software

4. In G.J. Software navigate to Setup > System Variables > Integration Accounts > Xero.
5. Copy the OAuth 2.0 redirect URI and save it as this will be used in the next step.

In Xero Developer

6. In Xero Developer click New app.
7. In the App name field enter the name of the office and leave the Integration type as Web app.
8. Paste the URI we copied from G.J. Software into the Redirect URI field.
9. Accept the Terms & Conditions and click Create app.
10. Navigate to the configuration tab on the left side of the screen and click Generate secret.
11. Copy the Client id and Client secret as these will be used in the next step.
12. (Optional) In the Login URL for launcher field enter the link to G.J. Software; e.g. “https://builder.gjgardner.com”.

In G.J. Software

13. In G.J. Software paste the Client id and Client secret that were previously copied from the Xero app into their corresponding fields. 
14. In the Organization Name field enter the name exactly as it appears in the Xero file for the organization. 
15. If required, select the office’s Current Financial Year.
16. Click the Connect to Xero button.
17. On the Xero authentication page select the office from the Organization field.
18. Click Allow access and the app will redirect you back to G.J. Software.
19. Wait for the initial synchronization to complete. 

2. Configure webhooks

20. Click the Generate Webhook URL icon and copy it to your clip board.
21. Return to Xero Developer and navigate to the Webhooks tab.
22. Select all of the available services and paste the URL copied in the previous step into the Delivery URL field and click Save.
23. Click Save.
24. Copy the Webhooks key and paste it into the relevant field in G.J. Software and click Save. 
25. Return to Xero Developer and click the Send intent to receive button.

3. Map the Chart of Accounts

26. In G.J. Software navigate to Setup > System Variables > Accounting.
27. Select the relevant Chart of Accounts codes for Accounts Receivable & WIP.
28. Do the same for all Job Expenses, Overheads, Advertising, and Wages accounts.

NOTE: Any time a new Chart of Accounts is created in Xero it needs to be added here in the system variables. 

Troubleshooting Xero Token issues

Sometimes an error may occur when editing contacts, creating draws or change orders, viewing job financials, and running WIP. This typically occurs due to an expired Xero Token and interrupts the synchronization with G.J. Software. To fix this you need to modify the existing connection to refresh the token.

IMPORTANT: Do not attempt to connect a different Xero organization to the office in G.J. Software as it can result in significant data discrepancies.