HaloPSA

HaloPSA Guides

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

Guides > Xero Integration

Xero Integration

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.



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.





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.





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. 




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.




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.





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. 







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.


Tracking Categories


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 oout and back in for this to take effect.


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. 

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, the item itself or set on the invoice line for the item. 


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

 

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: This step of the integration is compulsory if you want to use the item on an invoice. If the item already exists in your system, but is not assigned a Xero ID via this import, the invoices sync will fail.


When importing, existing product 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 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. 




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.

 



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.




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. 



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.



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.



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. 




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 4 settings which now need to be configured.



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.


Secondly, there is 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.


Finally, you can enable product linking in Halo.



By enabling this feature, when you are creating a product, 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.





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. 





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:




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: 





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.





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.





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:



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.





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 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.


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. 


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.





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 (As of v2.153):


Popular Guides