HaloPSA

HaloPSA Guides

Documentation to assist with the setup and configuration of the HaloPSA platform

Guides > Xero Integration

Xero Integration

In this guide we will cover:

- Enabling the Module

- Xero Tenants

- Connecting to Xero

- Tax Rates

- Customer Imports

- Tracking Categories and Account Codes

- Product Imports

- Charge Rates

- Syncing to Xero



Enabling the Module

To enable the Xero integration, go to Configuration > Integrations > Billing, and enable the module using the plus icon in the top right hand corner of the menu icon. Once the module has been enabled, click the menu icon to begin configuring it.


Xero Tenants

Halo allows you to connect to multiple Xero tenants. Once connected to a tenant, you will be able to configure tax rates, customers, items and suppliers. You will also be able to sync any changes to customers, items, suppliers, invoices and purchase orders from Halo to Xero.


Before configuring any of the general settings for this integration, you must first connect to at least one Xero tenant. Click the Xero tenants button to start this process.


Fig 1. Xero Tenants button.


Connecting to Xero

Start by creating a new Xero connection. First you must specify a sensible name for the connection. It is recommended that you use your company name that you will be connecting to, as this name will be displayed throughout the Halo application in different places.


Fig 2. Name of tenant and Connect to Xero button.


Choosing an Authentication Type (v2.188+)

From v2.188+ you will have an option to choose an authentication type for the integration. 

Fig 3. Authentication Type


Use the Halo app (recommended) - This is the recommended option and should be selected by all hosted customers. When this option is selected you will need to authenticate the integration by logging into your Xero account. 


Use a custom developer app - This option should only be selected if you are unable to authenticate successfully using the Halo app method. As this option does not support webhooks. On-premise customers that do not allow their Halo instance to communicate with our API will need to use this authentication method. When this option is selected you will need to authenticate the integration using a client ID and secret. 


Note: When you update to v2.188+ the 'Halo app' method will be selected by default. 


Once a sensible name has been chosen, click the Connect Now button to begin the authorization process with Xero. You will be redirected to the Xero login screen to log in to Xero. Once logged in, you will be asked to choose which tenant you would like to connect to. Once you have confirmed a tenant, you will be redirected back to the Xero connection you started setting up in Halo. Providing there were no issues with your authentication, extra options will now be available on the setup screen.


IMPORTANT: Once connected, remember to save the connection in Halo. If you complete the connection process without saving the connection, then the connection will remain in an disconnected state. 


Should you wish to disconnect from a Xero tenant at any time, you can either use the "Disconnect from Xero" button that is now available, or you can delete the connection.


Fig 4. Disconnect from Xero button.


Tax Rates

Before proceeding with any further configuration, you must make sure that every tax rate in Halo is linked to a Xero tax rate. This can achieved by either importing all of your tax rates from Xero, or opening each Halo tax rate manually and choosing a Xero tax rate from the drop down available.


IMPORTANT: This step of the configuration is compulsory. Skipping this step will result in errors when syncing invoices later. 


Fig 5. Import tax rates.


To manually assign the tax rates, click the Edit Tax Rates button and open any tax rate in the list. When creating a new tax rate, you will first need to choose which Xero tenant the tax rate is assigned to. Once you've selected the tenant, a list of tax rates from Xero will be available to choose from.


Fig 6. Xero tax rate configuration.


To import all tax rates automatically, click the Import Tax Rates button. This will remove any tax rates which have been previously configured that are not assigned to a Xero tenant (excluding the zero tax rate). If the import is successful, a popup will display showing how many rates have been imported.


Fig 7. Imported tax rates popup.


Using Automatic Sales Tax in Xero when Xero is integrated with Avalara (v2.188+) 

If your Xero tenant is integrated with Avalara to automate tax calculations, it is possible to have the invoice created in Halo, sent to Xero, then have the tax rates calculated by Avalara synced back into Halo. Ensuring tax is consistent across all applications. 


In order to use this functionality you must have the AVALARA tax rate from Xero mapped to a Halo tax rate and you must be using the 'invoice updated' Xero webhooks. See the section 'Xero Webhooks' of this article for information on enabling webhooks for Xero. 


To do this you must ensure 'Automatic Sales Tax' is enabled for your Xero integration in Halo. This is enabled under the 'Tax Rates' tab of the integration setup page. 

Fig 8. Enable automatic sales tax for Xero.


Once enabled Avalara tax calculations from Xero can sync back into Halo, but additional steps need to be completed when syncing to ensure this is done successfully. 


Any invoice lines that you would like to use automatic sales tax (from Avalara) must have the tax code 'AVALARA' when syncing from Halo to Xero. The tax rate applied to the item in Halo must be mapped to the Xero tax code 'AVALARA'. This will ensure when the invoice is synced to Xero it has the tax rate 'AVALARA', having this tax rate will trigger Avalara to calculate the tax for this item and apply this to the invoice. 


Then when the invoice is updated in Xero this will trigger the 'invoice updated' webhook, pushing the invoice changes back to Halo. The invoice in Halo will then be updated with the correct tax information. 


Customer Imports

Now that tax rates have been configured, you can move onto importing customers. In order for invoices to sync, each customer in Halo must be assigned a Xero ID, so you should ensure that all of your customers are imported from Xero if you want to be able to sync their invoices across.


IMPORTANT: This step of the integration is compulsory if you want invoices for a customer to be synced. If the customer already exists in your system, but is not assigned a Xero ID via this import, their invoices will not sync.


When importing, existing customer records in Halo will be updated if they have the same name or accounts code in Halo as they do in Xero. If they are being imported for a second time, then the record will be updated based on the Xero ID that has been previously assigned to the record.


NOTE: If a customer already exists with the same name or accounts code but is assigned to different Xero tenant, then a new record will be created.


When you are happy, click the Import Customers button to open the importer screen, where your customers from Xero will be listed for you to import. 

Once you have imported at least one record, navigate to the customers view and open a customer that has been imported. On the settings tab of this customer, you will see that your customer record has been linked to your Xero tenant, along with other information which has been imported from Xero. 


Fig 9. Xero tenant on a customer.


It is not possible to edit the Xero tenant that a customer belongs to once it has been assigned to the tenant.


Providing you have correctly mapped all Halo tax rates to a Xero tax rate, you will also see that the customers sales tax and purchase tax rates have been assigned correctly.


Fig 10. Sales and purchase tax rates.


Tracking Categories and Account Codes

To sync categories between Halo and Xero this first needs to be enabled, under Configuration > Integrations > Xero, 'Enable Xero Tracking Categories'. Once enabled you will be able to add a placeholder name for the categories, this is how they will be referred to in Halo. You will need to log out and back in for this to take effect.


Fig 11. Tracking categories name.


Once enabled head into your Xero tenant configuration in Halo > Accounts and Tracking Categories. 


Here you will need to import your categories from Xero using the 'Import Tracking Categories' button. This will import both your categories and category options. 


Once imported you will need to assign a category to the placeholder names you set earlier. 


Fig 12. Selecting a tracking category. 


Now you can set a category option for each of these categories for your items in Halo. This can either be set against the item group or set on the invoice line for the item. 


Fig 13. Selecting a tracking category.


Now each time an invoice is synced to Xero the category information will be also be synced.  


Account codes must also be imported from this screen. This is mandatory to be able to sync invoice line items to Xero. Ideally this should be done before importing products as you can set the codes per product group in Halo which is explained in the next section of this guide. Importing the codes before products also assigns the codes to the products when they are imported if the codes are set at product level in Xero.

 

As of v2.178.1+, you can also use item groups as a way of excluding certain items from 3rd party accounting integrations. Once "Use for Items" is enabled, "Exclude from Accounting Integration" can be selected. This will exclude items from within that group from being synced. This can be useful if you use a catalogue integration and do not want these products syncing to your Xero.


Product Imports

Now that your customer list has been imported, you now need to import your products from Xero. When syncing invoices to Xero, every line on the invoice must be linked to a product that exists in Xero. Therefore, you must ensure that all products that you want to sync to Xero have been imported.


IMPORTANT: When a product is added as a line item to an invoice, it needs to have valid account codes and tax codes assigned to it on the invoice in order for it to sync to Xero. The tax codes are inherited from the customer account easily if the customer has been imported after importing the tax codes. The account codes can be assigned on the product under the billing tab or on the product group as per the previous image. The account codes are inherited on products from the Xero import as well if they have been imported before products.


When importing, existing product records in Halo will be updated if they have the same name in Halo as they do in Xero. If they are being imported for a second time, then the record will be updated based on the Xero ID that has been previously assigned to the record. 


NOTE: If a product already exists with the same name or accounts code but is assigned to different Xero tenant, then a new record will be created.


Before importing, you must choose an product group that any imported products will be assigned to. Failing to do this may result in products not displaying correctly in Halo.  

When you are happy, click the Import Products button to open the importer screen, where your products from Xero will be listed for you to import. 


Once you have imported at least one product, navigate to the products view in Halo and open one of the products you have imported. Under billing settings, you will see that the product has now been linked to the Xero tenant. 


Fig 14. Xero tenant on a product.


Providing you have correctly setup your tax rates, you will see that the tax rates have also been set on the product, along with other values such as the product and accounts codes.


 

Fig 15. Codes and tax rates on a product.


Charge Rates

Although these are not strictly part of the Xero integration configuration, amendments must be made to the configuration of each charge rate to ensure that each rate is linked to a product in Xero. Failing to do this will result in invoices for labour failing to sync to Xero. Now that all products have been imported, it is a good time to configure this part of Halo.


Navigate to Configuration > Billing > Charge Rates and open any of your charge rates. To link a charge rate to a Xero product, add the product code to the Accounts ID/Nominal Code field. To link this rate to the item shown above, we would set the value to "BOOK" which is the product code for the product.


Fig 16. Charge rate.


Any charge rates that you do not want to link to a product should be deleted, otherwise your technicians may use them unknowingly which will cause issues down the line when trying to sync invoices.


Supplier Imports

In order for purchase orders to sync, each supplier in Halo must be assigned a Xero ID. If you intend to sync purchase orders to Xero, you should ensure that all of your suppliers are imported from Xero first.


When importing, existing supplier records in Halo will be updated if they have the same name or accounts code in Halo as they do in Xero. If they are being imported for a second time, then the record will be updated based on the Xero ID that has been previously assigned to the record.


NOTE: If a supplier already exists with the same name or accounts code but is assigned to different Xero tenant, then a new record will be created.


When you are happy, click the "Import Suppliers" button to open the importer screen, where your suppliers from Xero will be listed for you to import. 

Once you have imported at least one record, navigate to the suppliers view and open a supplier that has been imported. On the settings tab of this supplier, you will see that your supplier record has been linked to your Xero tenant, along with other information which has been imported from Xero. 


Fig 17. Tenant linked to a supplier.


Syncing to Xero

Now that you have imported tax rates, customers and products and suppliers, you are ready to enable syncing to Xero. By enabling this feature, whenever you create or update a customer/product/supplier in Halo, the changes will be synced to Xero. If the customer/product/supplier in Halo is correctly linked to a Xero record, then the record will be updated in Xero, otherwise a new record will be created.


To enable syncing of any entity to Xero, add the entity to the Entities to Sync field.


Fig 18. Entities to sync.


Once you have added at least one entity to this field, you will be presented with multiple additional configuration options.


Firstly, there is an option to show a message whenever a sync is successful. It is highly recommended that you enable this feature, particularly when first using the integration, as it gives a good indication that the actions you are taking are working. 


Example: with this feature enabled, if you try to sync an invoice for a customer who has not been correctly linked to a Xero customer, then no popup will display, which will indicate to you that Halo has not tried to sync the invoice to Xero.


It is also possible to archive customers/suppliers in Xero whenever the customer/supplier is made inactive in Halo.


Fig 19. Archive when inactive option.


Finally, it is recommended that you specify a default Xero product code for invoice and purchase order lines. As mentioned earlier in this guide, every line on an invoice must be linked to an product, otherwise the invoice will fail to sync correctly to Xero. It can be difficult maintaining a fully synced item list, so to help with this, we have added an option to choose a default product for invoices. This means that if you do accidentally add a product to an invoice which is not linked to a Xero item, then the default item will be assigned to the line so that the invoice won't fail to sync. We recommend using a miscellaneous item code for this field, which is a common piece of configuration in all accounts systems. 


Fig 20. Default item codes.


General Settings

Now that you have connected to one of your Xero tenants, you can revisit the initial module setup screen (Configuration > Billing > Xero Integration). There are a few settings which now need to be configured.


Fig 21. Default tenant and status.


Firstly, you must choose a default tenant which will be used for new customers, suppliers and products. 


IMPORTANT: This field should not be left blank. If left blank and you don't set this value manually when creating a new record, the record will not be synced to Xero. If the new record is a customer, it would mean that you cannot sync their invoices to Xero.


There is also an option to choose the default status for invoices and purchase orders. There are three options available - DRAFT, SUBMITTED and AUTHORISED. If you are creating a recurring invoice or raising a manual invoice, then this value can be overridden. This will be shown later in the guide.


Allow Xero Purchase Order Status to be updated from Halo - When this is enabled purchase order statuses will update the PO in Xero when changed in Halo. 


Default Invoice Tax Status - Here you can set a default tax status for your invoices, but the tax status can be overridden against each recurring and standalone invoice.


Default Credit Note Tax Status - Similar to the above setting, here you can set a default tax status for your credit notes, but the tax status can be overridden against each credit note.


Allow Products to be linked to other Products- When enabled when you are creating a product in Halo, you have the option to link the product to a parent product. If linked, the child product does not get synced to Xero. Whenever the child product is added to an invoice/purchase order, the product/accounts code for the parent product will be used.


Show Xero fields on the Billing tab of Products - When enabled Xero fields will appear against a product under the 'Billing' tab. 

Use Xero for sending Invoices - When enabled, when invoices are sent out they will be sent from Xero rather than Halo. This applies to invoices that are sent both manually and automatically. If this is enabled and you are sending invoices automatically you must ensure the default statuses for new invoices is set to be a Xero status that allows invoices to be sent out, i.e. not DRAFT. 


Enable Xero Tracking Categories - When enabled Xero tracking categories can be assigned to products. This allows a tracking category to be stored against an invoice line. Categories will need to be imported from Xero then a tracking category can be assigned to each of your product groups. Each time this product is added to an invoice the tracking category will be stored against the invoice line and synced to Xero. See the 'Tracking Categories and Account Codes' section of this guide for more information. 


Syncing Customers

When you are creating a new customer, there are some compulsory fields that must be completed for the sync to be successful. These fields are located on the settings tab of the customer under the Billing Settings header. The first compulsory field is the Xero tenant. If you have chosen a default Xero tenant, then this field will already be populated for you.

The second compulsory field is the account number/code. If you leave this field empty, then the customer record will not be synced to Xero, so you can leave this field blank if the customer is an internal customer that you do not want to be synced. The generate button will automatically calculate an account number. 


Fig 22. Tenant and generating an account number.


If you do not want your technicians to have to manually generate this value, then you can enable auto generation of the accounts number. This can be enabled in Configuration > Billing > General Settings:


Fig 23. Auto generate option.


WARNING: Failure to populate either of these fields will result in the customer not being synced to Xero.


Syncing Products

Like customers, products have compulsory fields that must be completed when you create them in order for the sync to be successful. Again, the Xero tenant and product code field (sales only) are required for the item to sync to Xero. If you have enabled automatic generation of accounts IDs as explained above, then this will also apply for new products and the product code will be automatically generated for you.


In addition to these two fields, the accounts code (sales only) must be be populated. Some technicians will likely not know which accounts codes should be used for new products, which is why we have implemented a default option for these fields. These defaults can be configured in Configuration > Items and Stock Control > General Settings, so whenever your technicians create a new item, these fields are automatically populated for you.


Fig 24. Default account codes.


The account codes can also be inherited from the product group. If technicians create the product on the correct group, when added to an invoice, the product will inherit the group's codes if the fields are left empty at product level.


Syncing Invoices

Providing all steps of this guide have been followed, and every entity in Halo is correctly linked to an entity in Xero, syncing invoices will be straightforward. All types of invoices can be synced to Xero, whether it be for labour on tickets or an invoice created from a recurring invoice. We will only look at raising a basic manual invoice in this guide for simplicity.


When first opening a new invoice, you will see a Xero Details header on the right hand side of the invoice. Initially, this will have a field for the status (set using the default value you chose earlier). If you have enabled the ability to override the third party invoice number, then this field will also be available.


Fig 25. Status on an invoice.


Once you have selected a customer, providing the customer is linked to a Xero tenant, then an additional field will display allowing you to override the branding theme for the invoice.


Fig 26. Branding theme dropdown.


This option can also be overridden when raising a recurring invoice. Invoices which are not raised manually, such as invoices for labour, will apply the default branding theme set against the customer record in Xero.


Now if you try to add a product to the invoice, your product list will be filtered to only show products which are linked to the same Xero tenant as the customer. Products which are not linked to any Xero tenant will also be included.


When first adding a product to an invoice, the product code will be displayed on the invoice line.


Fig 27. Product code on an invoice.


This is the first basic indication that the product you've added to the invoice has been successfully linked to a Xero product. If no product code is shown, you can either edit the line and manually adjust the product code, or when the invoice is saved, if you have chosen a default product code for invoice lines then the line will automatically be assigned the default product code. 


When saving the invoice, there are some common errors that can occur due to misconfiguration. If the error mentions tax rates/codes not being specified or being invalid, then the product that is assigned to your invoice line is likely not assigned to a tax rate which has been linked to a Xero tax rate. Likewise, if the error contains information about an invalid product on the invoice, then one of your items/charge rates has not been correctly linked to a Xero item.


In these circumstances, you should revisit your configuration and check that these entities have been linked together correctly. Once you've made changes to your configuration, you should re-add the line to the invoice so that the changes take effect on the invoice. As long as one field/line is modified, then the changes will be synced across to Xero.


If no errors have been shown but the third party invoice number (shown under the Xero Details heading) is showing as "not set", then Halo has not tried to sync the invoice. This will be due to the customer record not being linked to a Xero tenant or not having an account code assigned to them. In this scenario, you should ensure that these two values are set against the customer record and then delete and recreate the invoice.


Fig 29. Invoice number in the Xero details.


Updates to invoices that have already successfully synced to Xero will also be synced to Xero, for example, if you wanted to increase the quantity of an existing invoice line.


Should you wish to remove an invoice, deleting it from Halo will remove the invoice from Xero. The deletion from Halo will also roll back any billing calculations, so tickets that were billed on the invoice will now re-appear in the ready for invoicing section.


Syncing invoices in Bulk (v2.188+) 

From version 2.188+ of Halo multiple invoices can be selected, when viewing in a list, and synced to Xero from here.

Fig 30. Sync invoices to Xero in bulk 


This can be done from any subsection within the Invoices section in the 'Ready for Invoicing' area, however, syncing from the 'Not synced to Xero' area will help you optimise this functionality. 


By navigating to the 'Not synced to Xero' area you can see all the invoices that are not yet synced, and easily begin the sync for all the invoices here in one go. 


Note: When bulk sync begins this will completed on a background task to adhere to Xero's API limits. Therefore, expect some wait time for sync to complete. 


Syncing Suppliers and Purchase Orders

Syncing suppliers and purchase orders works in the exact same way as customers and invoices. The mandatory fields for a supplier to sync successfully are the same as the mandatory fields for customers and can be found in the same location. There is currently not an option to automatically generate the accounts code for a supplier, so this must be done manually.


As of v2.176 purchase order statuses can be synced from Halo into Xero, allowing you to update the PO status in Xero from Halo. To enable this functionality head to Configuration > Integrations > Xero and enable 'Allow Xero Purchase Order Status to be updated from Halo'. 


Fig 31. Allow status change option.


Note: Due to current limitations, the address field of a supplier does not get synced back to Xero.


Purchase orders also have the exact same requirements as invoices.


Xero Webhooks

You can receive updates back from Xero by going to the Webhooks tab on the integration page. You can enable these webhooks so that when a customer is created or updated in Xero, the update gets sent back to Halo automatically. You can also enable webhooks so when an invoice is created or updated in Xero this change is synced to Halo. 'Invoices (Created)' will also void an invoice in Halo if this is voided in Xero, when enabled. 


Fig 32. Webhooks configuration. 


Note: Xero webhooks are not supported if you are using the 'custom developer app' authentication method. 


Sync Reversed Payments (v2.182)

As of v2.182 invoices in Xero that have had payments reversed will be updated accordingly in Halo. If an invoice in Xero had the status 'PAID' but then the status changed (to any other status) the associated invoice in Halo will have any payment records against it removed. 


To use this functionality you will first need to ensure 'Invoices (Updated)' webhooks are enabled. Then an additional 'Payments' section will show, here enable 'Allow Xero payments to be reversed'. 


Fig 33. Reverse payment option.


Only import customers that have at least one invoice (2.184+) 

As of v.2184+ you can enable the setting 'Only import Customer records (Contacts that have at least one Invoice)' here to ensure only customers that have at least one invoice in Xero are imported into your Halo. 


Fig 34. Import customer records option.


Errors

In the event that a sync to Xero fails, all errors are saved against the Xero tenant connection for traceability. To review these errors, navigate to Configuration > Integrations > Xero > Xero Tenants, open a tenant that you are connected to and switch to the errors tab.


Fig 35. Error log.


The table will provide an overview of the errors in the order in which they occurred. By double clicking the error, a new tab will open on the entity where the error occurred. In the example shown above, the customer Terry's Chocolates would be opened.


We can also decide the invoice line data shown in Xero when the invoice is created in Halo and synced to Xero.


Fig 36. Invoice description option.

Popular Guides