<style>p { margin: 0; }span.fr-emoticon.fr-emoticon-img { background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle; } span.fr-emoticon { font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0; } blockquote { border-left: solid 2px #5e35b1; color: #5e35b1; margin-left:0; padding-left:5px;}blockquote blockquote{ border-color: #00bcd4; color: #00bcd4;}blockquote blockquote blockquote{ border-color: #43a047; color: #43a047;} table.grid{ border-collapse: collapse;} table.grid td, table.grid th { border: 1px solid #ddd;} .fr-fic.fr-dib{ display: block; margin: 5px auto;}.fr-fic.fr-dib.fr-fir{ text-align: right; margin: 5px 0 5px auto;}.fr-fic.fr-dib.fr-fil{ text-align: left; margin: 5px auto 5px 0;}.fr-fic.fr-dii{ float: none; margin: 5px auto;}.fr-fic.fr-dii.fr-fil{ float: left; margin: 5px auto;}.fr-fic.fr-dii.fr-fir{ float: right; margin: 5px auto;}img.fr-dib.fr-fir { margin-right: 0; text-align: right;}img.fr-dib.fr-fil { margin-left: 0; text-align: left;}img.fr-dib { margin: 5px auto; display: block; float: none;}img.fr-bordered { box-sizing: content-box; border: solid 5px #CCC;}img.fr-shadow { box-shadow: 10px 10px 5px 0px #cccccc;}img.fr-rounded { border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;}</style><style>
p {
margin: 0;
}
span.fr-emoticon.fr-emoticon-img {
background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle;
}
span.fr-emoticon {
font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0;
}
blockquote {
border-left: solid 2px #5e35b1; color: #5e35b1; margin-left: 0; padding-left: 5px;
}
blockquote blockquote {
border-color: #00bcd4; color: #00bcd4;
}
blockquote blockquote blockquote {
border-color: #43a047; color: #43a047;
}
table.grid {
border-collapse: collapse;
}
table.grid td,
table.grid th {
border: 1px solid #ddd;
}
.fr-fic.fr-dib {
display: block; margin: 5px auto;
}
.fr-fic.fr-dib.fr-fir {
text-align: right; margin: 5px 0 5px auto;
}
.fr-fic.fr-dib.fr-fil {
text-align: left; margin: 5px auto 5px 0;
}
.fr-fic.fr-dii {
float: none; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fil {
float: left; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fir {
float: right; margin: 5px auto;
}
img.fr-dib.fr-fir {
margin-right: 0; text-align: right;
}
img.fr-dib.fr-fil {
margin-left: 0; text-align: left;
}
img.fr-dib {
margin: 5px auto; display: block; float: none;
}
img.fr-bordered {
box-sizing: content-box; border: solid 5px #CCC;
}
img.fr-shadow {
box-shadow: 10px 10px 5px 0px #cccccc;
}
img.fr-rounded {
border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;
}
</style><style>
p {
margin: 0;
}
span.fr-emoticon.fr-emoticon-img {
background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle;
}
span.fr-emoticon {
font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0;
}
blockquote {
border-left: solid 2px #5e35b1; color: #5e35b1; margin-left: 0; padding-left: 5px;
}
blockquote blockquote {
border-color: #00bcd4; color: #00bcd4;
}
blockquote blockquote blockquote {
border-color: #43a047; color: #43a047;
}
table.grid {
border-collapse: collapse;
}
table.grid td,
table.grid th {
border: 1px solid #ddd;
}
.fr-fic.fr-dib {
display: block; margin: 5px auto;
}
.fr-fic.fr-dib.fr-fir {
text-align: right; margin: 5px 0 5px auto;
}
.fr-fic.fr-dib.fr-fil {
text-align: left; margin: 5px auto 5px 0;
}
.fr-fic.fr-dii {
float: none; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fil {
float: left; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fir {
float: right; margin: 5px auto;
}
img.fr-dib.fr-fir {
margin-right: 0; text-align: right;
}
img.fr-dib.fr-fil {
margin-left: 0; text-align: left;
}
img.fr-dib {
margin: 5px auto; display: block; float: none;
}
img.fr-bordered {
box-sizing: content-box; border: solid 5px #CCC;
}
img.fr-shadow {
box-shadow: 10px 10px 5px 0px #cccccc;
}
img.fr-rounded {
border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;
}
</style><style>
p {
margin: 0;
}
span.fr-emoticon.fr-emoticon-img {
background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle;
}
span.fr-emoticon {
font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0;
}
blockquote {
border-left: solid 2px #5e35b1; color: #5e35b1; margin-left: 0; padding-left: 5px;
}
blockquote blockquote {
border-color: #00bcd4; color: #00bcd4;
}
blockquote blockquote blockquote {
border-color: #43a047; color: #43a047;
}
table.grid {
border-collapse: collapse;
}
table.grid td,
table.grid th {
border: 1px solid #ddd;
}
.fr-fic.fr-dib {
display: block; margin: 5px auto;
}
.fr-fic.fr-dib.fr-fir {
text-align: right; margin: 5px 0 5px auto;
}
.fr-fic.fr-dib.fr-fil {
text-align: left; margin: 5px auto 5px 0;
}
</style><p><strong>In this guide we will cover:</strong></p><p><strong>- Enabling the Module</strong></p><p><strong>- Xero Tenants</strong></p><p><strong>- Connecting to Xero</strong></p><p><strong>- Tax Rates</strong></p><p><strong>- Customer Imports</strong></p><p><strong>- Tracking Categories and Account Codes</strong></p><p><strong>- Product Imports</strong></p><p><strong>- Charge Rates</strong></p><p><strong>- Syncing to Xero</strong></p><p><br></p><p><br></p><p><strong><span style="font-size: 14pt;">What is the Xero Integration?</span></strong></p><p>The Xero integration allows you 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.</p><p><br></p><p><strong>Before setup, ensure the below is set in Xero:</strong></p><ul><li>All tax codes set against customers/products.</li><li>Accounts codes to import.</li><li>Having all products you want to sync to invoices in Xero.</li><li>Suppliers to import if using purchase orders.</li></ul><p><br></p><p><strong><span style="font-size: 14pt;">Enabling the Module</span></strong></p><p>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.</p><p><br></p><p><strong><span style="font-size: 14pt;">Xero Tenants</span></strong></p><p>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.</p><p><br></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFhNzQwMzliLWMyOWYtNGU0ZS04NTdlLWQ4MTBjMWQxYWEwZCJ9.0q8AgNMofpitnP3EP2HkHplzzaNuouJqL0YBHfLB_Jo" alt="" width="870" height="199" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 1. Xero Tenants button.</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Connecting to Xero</span></strong></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjEzY2VjMTc4LThlN2ItNGMwMS1hZGRiLTc2ZTllYjhlYTU3OSJ9.giaTTpr_KpmoxuzjrVh7oL8MFmMcBlCddUwHkl-GOsU" alt="" width="1129" height="356" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 2. Name of tenant and Connect to Xero button.</span></strong></p><p><span style="font-size: 11pt;"><br></span></p><p style="margin-left: 20px;"><span style="font-size: 11pt;"><strong>Choosing an Authentication Type</strong></span></p><p style="margin-left: 20px;"><span style="font-size: 11pt;">You will have an option to choose an authentication type for the integration. </span></p><p style="margin-left: 20px;"><span style="font-size: 11pt;"><strong><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjlkY2FlOTQzLWYxNzUtNDJmZS1hNWMwLTAyMDZlZTZiOTM3OCJ9.gKdDTJTTnSVco5KkBVlez6Nv_krSXiYfcxEVpAKCjC0" class="fr-fic fr-fil fr-dib" width="359" style="width: 361px; height: 140.666px;" height="141"></strong></span></p><p style="margin-left: 20px;"><strong><span style="font-size: 10pt;">Fig 3. Authentication Type</span></strong></p><p style="margin-left: 20px;"><strong><br></strong></p><p style="margin-left: 20px;"><strong>Use the Halo app (recommended)</strong> - 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. </p><p style="margin-left: 20px;"><br></p><p style="margin-left: 20px;"><strong>Use a custom developer app </strong>- 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-Prem 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. </p><p style="margin-left: 20px;"><br></p><p style="margin-left: 20px;"><strong><em>Note: The 'Halo app' method will be selected by default. </em></strong></p><p><br></p><p>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.</p><p><br></p><p><strong><em>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. </em></strong></p><p><br></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjhjZmQxOTE0LTNmYWEtNDExOS1hNDJmLTI4YjliNjQwYzEwNyJ9.x9HX5DlJRr2LZ-iL_c1k3i8PUNe49t9np_2sA4SN11g" alt="" width="360" height="156" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 4. Disconnect from Xero button.</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Tax Rates</span></strong></p><p>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.</p><p><br></p><p><strong><em>IMPORTANT: This step of the configuration is compulsory (unless using automatic sales tax). </em></strong><em><strong>Skipping this step will result in errors when syncing invoices later.</strong> </em></p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImY2M2NiMjM1LWM3YTQtNGFhOS04MjBjLTZmNjY1ZGMzMzgzZCJ9.mmO_jSx7aQWsKuthi-1ln0G4d5cpWf_52XjbjhvaiPY" alt="" width="1120" height="228" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 5. Import tax rates.</span></strong></p><p><br></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQwZmRkMDk3LTAzMTItNGRhZi1iZDlkLTNkNzY4NTdhMWU0NiJ9.C3K2_tvjfPZcAAtZXgHOORdKufVqW1KgNOyadwAmMlQ" alt="" width="376" height="167" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 6. Xero tax rate configuration.</span></strong></p><p><br></p><p>To import all tax rates, 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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjM2NWZmNjU5LTU5NDctNGI5My1hMGEyLWU4MzZlYTk2NjQwNiJ9.FFACOh4xz-kGtgX9f6wd-i7i2nN54YaaGu_Y-O--hz0" alt="" width="230" height="126" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 7. Imported tax rates popup.</span></strong></p><p data-pasted="true"><br></p><p>You can import tax rates from Xero automatically on a daily basis, this will update any existing rates and create new rates. This is enabled using the setting "Import tax rates daily" under the "Tax Rates" tab. When enabled, the latest tax rates will be automatically imported during the daily task scheduler run. This helps to keep your tax rates up to date without having to re-import manually. </p><p><br></p><p><strong><span style="font-size: 12pt;">Using Automatic Sales Tax in Xero when Xero is integrated with Avalara</span></strong></p><p>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. </p><p><br></p><p>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. </p><p><br></p><p>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.<span style="font-size: 11pt;"> </span></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImRhYjk0NmEyLTJlMjUtNDRmMi05OTc3LTA0MTc4YzM4NjkwNSJ9.O7p0x1X1SOrNHK4fZDffoT28BGgrMZgOHa9JBkz69Vg" class="fr-fic fr-fil fr-dib" width="959" style="width: 961px; height: 510.476px;" height="510"></p><p><strong><span style="font-size: 10pt;">Fig 8. Enable automatic sales tax for Xero.</span></strong></p><p><br></p><p>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. </p><p><br></p><p>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. </p><p><br></p><p>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. </p><p><br></p><p><strong><span style="font-size: 14pt;">Customer Imports</span></strong></p><p>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.</p><p><br></p><p><strong><em>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.</em></strong></p><p><br></p><p>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.</p><p><br></p><p><strong><em>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.</em></strong></p><p><br></p><p>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. </p><p>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. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjQ3YmQ1MWFhLWVkZTgtNDA2Ny05ODk4LWYyYWZjMjVjNjU2NSJ9._Wis9VyM_nos0LtsLlqyQ6vb3QLncU79eqcNQsYLvdk" alt="" width="249" height="126" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 9. Xero tenant on a customer.</span></strong></p><p><br></p><p>It is not possible to edit the Xero tenant that a customer belongs to once it has been assigned to the tenant.</p><p><br></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjJiYmMyNjY5LWI0YmUtNDkwMC04YWE0LTQ1MDRiMDFmOWY1OSJ9.xpTlF0Upi-wlCLQV_qXdmwaXzlvAfQalylLDMETgyco" alt="" width="197" height="136" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 10. Sales and purchase tax rates.</span></strong></p><p><br></p><p>From v2.238+, in the "Invoice Settings" section of the Billing tab on a Customer record, you can set a default "Xero branding theme".</p><p><br></p><p><strong><span style="font-size: 14pt;">Tracking Categories and Account Codes</span></strong></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImY0NThiYWU1LTNmNmItNDExMC04OTc1LWMxM2Q1NmEyMjRjZSJ9.oHI4_Uu5IJUq1YMgQkgQNZ0S-jzs4zJqnuQw54gnbXU" class="fr-fic fr-fil fr-dib" width="279" style="width: 281px; height: 190.297px;" height="190"></p><p><strong><span style="font-size: 10pt;">Fig 11. Tracking categories name.</span></strong></p><p><br></p><p>Once enabled head into your Xero tenant configuration in Halo > Accounts and Tracking Categories. </p><p><br></p><p>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. </p><p><br></p><p>Once imported you will need to assign a category to the placeholder names you set earlier. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijg0OTRmZmY3LTdhZGEtNDE2NS1hZjUzLTkwZDNjMWIyNDJlYSJ9.UTzHk5y3rNl4MsHnzNjXvvuMGPWxJz6lA1-F39SpDj0" class="fr-fic fr-fil fr-dib" width="813" style="width: 815px; height: 437.269px;" height="437"></p><p><strong><span style="font-size: 10pt;">Fig 12. Selecting a tracking category. </span></strong></p><p><br></p><p>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. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjdiMThkOWM0LWE3ZWEtNGU5OS1hODg1LTlhZjExOWNlM2Q5ZCJ9.pNg7xVPcFAVBE5yZVKU9Y2cH9ScUmBLq7lADh9n-qqA" class="fr-fic fr-fil fr-dib" width="391" style="width: 393px; height: 492.508px;" height="493"></p><p><strong><span style="font-size: 10pt;">Fig 13. Selecting a tracking category.</span></strong></p><p><br></p><p>Now each time an invoice is synced to Xero the category information will be also be synced. </p><p><br></p><p>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.</p><p> </p><p id="isPasted">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.</p><p><br></p><p><strong><span style="font-size: 14pt;">Product Imports</span></strong></p><p>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.</p><p><br></p><p><strong><em>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.</em></strong></p><p><br></p><p>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. </p><p><br></p><p><strong><em>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.</em></strong></p><p><br></p><p>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. </p><p>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. </p><p><br>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. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImZmNWY3ZjA4LWE2NDgtNGZkMi1hMTdkLWM3YTZkODhkZDZlYSJ9.7lwQYuD2lZpZUQi3AcPQaGu0MTMWrxAa_BmLMDEwplE" alt="" width="230" height="128" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 14. Xero tenant on a product.</span></strong></p><p><br></p><p>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.</p><p><br></p><p><strong> <img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjNlNDVkYjYyLWZkMjAtNDFjNS1hYWIyLWVjNTBmYjQyODA1ZCJ9.jKMXI5zzKJTAnL9hIaXwnwnzrZJasyxh8MXEsy1ook4" alt="" width="256" height="408" class="fr-fic fr-dii"></strong></p><p><strong><span style="font-size: 10pt;">Fig 15. Codes and tax rates on a product.</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Charge Rates</span></strong></p><p>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.</p><p><br></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImVlN2M3OWY4LWFiZGQtNDY2Ny05YmNiLWY3NWU1ZGE2YTc0ZCJ9.Jl4_nhXJ1Rw0cbDCkIHYpwCOpiYyYYqYuzmWWHhEv3s" alt="" width="557" height="418" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 16. Charge rate.</span></strong></p><p><br></p><p>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.</p><p><br></p><p><strong><span style="font-size: 14pt;">Supplier Imports</span></strong></p><p>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.</p><p><br></p><p>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.</p><p><br></p><p><strong><em>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.</em></strong></p><p><br></p><p>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. </p><p>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. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjFlMjg2ZjRlLTc3OTEtNDUxNi05YjllLTE4ZGI5OTM4Mzk2MiJ9.NI2CdQYiFjTBkIgj4pibtn55kZDAcz6vB2qXjClbkNg" alt="" width="170" height="128" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 17. Tenant linked to a supplier.</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Syncing to Xero</span></strong></p><p>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.</p><p><br></p><p>To enable syncing of any entity to Xero, add the entity to the Entities to Sync field.</p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjhmOTdjNWMzLWZlNjgtNDE4Yy05NjE1LWY3YzE0NGRjZDM5OCJ9.9MKz6qphZk7Q7_JUsre3vApEo97HtC7z1y8OwYOelrg" class="fr-fic fr-fil fr-dib" width="1353" style="width: 1355px; height: 256.889px;" height="257"></p><p><strong><span style="font-size: 10pt;">Fig 18. Entities to sync.</span></strong></p><p><br></p><p>Once you have added at least one entity to this field, you will be presented with multiple additional configuration options.</p><p><br></p><p>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. </p><p><br></p><p><strong>Example:</strong> 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.</p><p><br></p><p>It is also possible to archive customers/suppliers in Xero whenever the customer/supplier is made inactive in Halo.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjUwOTc4MjAyLTM0ODQtNDIwZC1iZjE5LWVjZDdiZTVlZmEwNCJ9.5Akk3taD8U-KvNKOTz5o7gfg9iIXdtTu3mNAdN8TV6U" alt="" width="598" height="122" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 19. Archive when inactive option.</span></strong></p><p><br></p><p>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. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjAyMjJlMmQ3LTg3NzgtNGJlZS05ZTRkLWU3OGM0NjExMjM0OSJ9.5TwHQHxYPNOPFItzVnDFMInpu6sJ-DRXkmlDCQnHwVk" alt="" width="809" height="304" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 20. Default item codes.</span></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">General Settings</span></strong></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjI1YjMyOTc5LTkwMWQtNGFjYi04MjgyLTU5Zjg0NzczYzAwNCJ9.-vXgDfs_AfMYBKuOiy6fjawsjMrmw3_fjjW_BMD79ZQ" alt="" width="1098" height="318" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 21. Default tenant and status.</span></strong></p><p><br></p><p>Firstly, you must choose a default tenant which will be used for new customers, suppliers and products. </p><p><br></p><p><strong><em>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.</em></strong></p><p><br></p><p>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.</p><p><br></p><p>The option to use a new webhook processing method is available. In Configuration > Advanced Settings > Backend Monitoring, enable the below.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImZjNWI5ZTRkLWU0MGEtNDhiZC1hZGY1LTcxZThkMzNiZGVmOCJ9.ovKb6X0qHwn7B0CA5x7xHBJwrcqP5FF3C33Zng-DuDM" class="fr-fic fr-fil fr-dib" width="667" height="56"></p><p><strong><span style="font-size: 10pt;">Fig 22. Enabling webhook services.</span></strong></p><p><br></p><p>Then back in the Xero module, a dropdown with two additional methods of processing webhooks are now available. The default follows the previous behaviour.</p><p><br></p><p id="isPasted"><strong>1. Use the default webhook processing functionality</strong></p><p>This is the default option. Each incoming webhook will be processed immediately, and failed webhooks will not be retried.</p><p><br></p><p><strong>2. Use the incoming webhook service with immediate processing</strong></p><p>This means the webhook service is in use for the integration. Each incoming webhook will be processed immediately, and any failed webhooks will then be automatically retried a further 2 times via the task scheduling service. This is the recommended option.</p><p><br></p><p><strong>3. Use the incoming webhook service with delayed processing</strong></p><p>The same as option 2, but webhooks are not processed immediately when they are received. Instead, they are automatically queued and picked up by the task scheduling service. This option is only necessary if option 2 is failing to process webhooks after 3 attempts due to rate limits, i.e. the webhook result is returning 429 too many requests.</p><p><br></p><p>Logic has been added to the task scheduler to retrieve webhook resource data in batches. This greatly reduces the number of requests made to the third-party API, thus reducing the chance of hitting third-party rate limits. This logic is always used for option 3, and is used before retrying webhooks when using option 2.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjIxYjMzNmRkLTI2MWMtNDFiNS1hYTllLWY3ZmYwZjA1ZWI5NyJ9.Qy_bymSFAss4ylS3-_p9RpwIG9sEu5wEQHjpS0ovZuk" class="fr-fic fr-fil fr-dib" width="1461" height="282"></p><p><strong><span style="font-size: 10pt;">Fig 23. Webhook method options.</span></strong></p><p><br></p><p>Logs for these new methods will be available in a new "Incoming Webhook Log" tab is available in Configuration > Advanced > Backend Monitoring, and can be used to view inbound webhooks for any integration that has enabled the incoming webhook service. For a full explanation of switching, check out the "<a href="https://usehalo.com/halopsa/guides/2615/" target="_blank" rel="noopener noreferrer"><strong>Incoming Webhook Processing Service</strong></a>" guide. The Invoice POST will now be stored in the "IntegrationRequest" table.</p><p><br></p><p><strong>Allow Xero Purchase Order Status to be updated from Halo</strong> - When this is enabled purchase order statuses will update the PO in Xero when changed in Halo. </p><p><br></p><p><strong>Default Invoice Tax Status </strong>- Here you can set a default tax status for your invoices, but the tax status can be overridden against each recurring and standalone invoice.</p><p><br></p><p><strong>Default Credit Note Tax Status</strong> - 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.</p><p><br></p><p><strong>Allow Products to be linked to other Products</strong>- 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.</p><p><br></p><p><strong>Show Xero fields on the Billing tab of Products</strong> - When enabled Xero fields will appear against a product under the 'Billing' tab. When disabled they will not show. The Xero product ID field will also be hidden when cloning an item if setting is off. </p><p><br></p><p><strong>Use Xero for sending Invoices</strong> - 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. </p><p><br></p><p><strong>Enable Xero Tracking Categories</strong> - 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. </p><p><br></p><p><strong><span style="font-size: 12pt;">Syncing Customers</span></strong></p><p>When you are creating a new customer in Halo, or syncing a customer that was not imported from Xero there are some fields that must be completed for the sync to be successful, 'Xero Tenant' and 'The Xero Customer ID', these fields are located on the Billing tab of a customer in Halo. </p><p><br></p><p><strong>Xero Tenant</strong> - This should contain the Xero tenant this customer should/does exist in. If you have chosen a default Xero tenant, then this field will already be populated for you. </p><p><br></p><p><strong>Xero Customer ID</strong> - This is only used if you would like to sync this customer in Halo with an existing customer in Xero and you would not like them to match using the customer name providing a new unique identifier for customers to be matched on. This should be populated with the accounts ID of the customer in Xero you would like this Halo customer to be linked to, this is used to match the Halo customer to the correct Xero customer (without relying on name). The accounts ID is set manually against customers in Xero. If you leave this field empty, then a new customer will be created in Xero upon saving the Halo customer. </p><p><br></p><p><strong>The Xero customer ID GUID</strong> - This will be populated automatically once the customer is synced to Xero. </p><p><br></p><p><strong><em>Note: If you have imported the customer from Xero these fields (excluding Xero Customer ID as this is not required) will be populated for you. </em></strong></p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjllYzJmNGUxLTBkZmUtNDgxNS1hN2I2LThjZDhiMzIxMTE2ZSJ9.9yVS7yOg2iCy6fbEbUUOtV2WY7bFB5VYvlCsD1DwMeI" class="fr-fic fr-fil fr-dib" width="864" height="412"></p><p><strong><span style="font-size: 10pt;">Fig 24. Tenant and generating an account number.</span></strong></p><p><br></p><p>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. If auto-generation is enabled you will need to copy the value generated by Halo and add this to the customer profile in Xero. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZjYzAxNTU2LTQ3ZDUtNDg0Ni05OWVhLTc0NDYyMjViMWMxOCJ9.Ab_yFjrnr22m1unAAzKggTbest6CsAcXfsPwJ4G1Cto" class="fr-fic fr-fil fr-dib" width="541" style="width: 543px; height: 405.416px;" height="405"></p><p><strong><span style="font-size: 10pt;">Fig 25. Auto generate option.</span></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Syncing Products</span></strong></p><p>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.</p><p><br></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY5MDUzYTdkLWY2YWItNGJhNS04NjUzLTI5YmI1YTc5NDc2YSJ9.wmmIS26uc2KEROS8yqembz_0_qpDdHrHmMMmmOEG46I" alt="" width="427" height="217" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 26. Default account codes.</span></strong></p><p><br></p><p>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.</p><p><br></p><p><strong><span style="font-size: 12pt;">Syncing Invoices</span></strong></p><p>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.</p><p><br></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjExYjhlYWQyLTNhNTQtNDFiMy04ZWM1LTA5ZDgwMWUyZTM4OSJ9.12uIidB9bzieH-074cLYUiH7lfPBCacUOzmz8B-cm9Q" alt="" width="260" height="137" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 27. Status on an invoice.</span></strong></p><p><br></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjMyNzZlOWI1LTBjYWEtNDhjZi04MWM3LThlZDgzN2IyNjAwYiJ9.4o6Axi6XnZBOf7KKZyuUU3UoC0aLuHZPq9-bnQdX--M" alt="" width="260" height="371" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 28. Branding theme dropdown.</span></strong></p><p><br></p><p>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.</p><p><br></p><p>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.</p><p><br></p><p>When first adding a product to an invoice, the product code will be displayed on the invoice line.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU3ODRhZGJjLWZlODMtNDA3Zi05ODdlLTMxYjc5ZWYxNzY5OSJ9.wSN2bGLj6MUgsRXGxyuKtpnTm37eK91sfy6e6nrFJ-E" alt="" width="1120" height="166" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 29. Product code on an invoice.</span></strong></p><p><br></p><p>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. </p><p><br></p><p>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.</p><p><br></p><p>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.</p><p><br></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijk1ODU5Yzg1LWZlNGQtNDU5OS05N2YxLWVkMjRiZWMzMGIxOSJ9.gZLiBYah8g1L0BOD98hoDjWIJL7DtobeCzI__Jva4M0" alt="" width="269" height="126" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 30. Invoice number in the Xero details.</span></strong></p><p><br></p><p>The "Reference" field will sync over to Xero's reference field, and variables can populate here upon syncing.</p><p><br></p><p>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.</p><p><br></p><p>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.</p><p><br></p><p><strong>Syncing invoices in Bulk</strong></p><p>Multiple invoices can be selected, when viewing in a list, and synced to Xero from here.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjQ3ZDY3MzE2LTQ2ZWMtNGYwZS05ZTY4LTc5ZjMxZmE2ZWZhNiJ9.4vZeY-L6TtgYpQRfB_9Aj8JA9iv2l8BL4QTR2X8iUIo" class="fr-fic fr-fil fr-dib" width="812" height="453"></p><p><strong><span style="font-size: 10pt;">Fig 31. Sync invoices to Xero in bulk </span></strong></p><p><br></p><p>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. </p><p><br></p><p>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. </p><p><br></p><p><strong><em>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. </em></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Syncing Bills</span></strong></p><p>Bills function in a similar way to invoices, and sync the same way. Each bill will have a Xero status set against it, and it will sync upon creation.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImMwZmNjNjhmLWM0ZjItNDA2ZC1iNTFiLWM3ZjI5NjVjNDA4YiJ9.zw3mA64mNygXG-bWmZanlQcpe742rCcyUpt42N9kZIo" class="fr-fic fr-fil fr-dib" width="1552" height="804"></p><p><strong><span style="font-size: 10pt;">Fig 32. Xero status on a bill.</span></strong></p><p><br></p><p>You can include the PO number or supplier reference when syncing bills to Xero. This can be enabled in the "Syncing to Xero" tab.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjI5NDhmMDVjLTAwMzUtNDg3ZC04YjQwLWI4ZjI4YmQ3NTAzYiJ9.ZCco2jztOPlb1G5ojLYTlPi2emcAJ1-iNKR6J8qe2xM" class="fr-fic fr-fil fr-dib" width="429" height="123"></p><p><strong><span style="font-size: 10pt;">Fig 33. PO syncing to bills options.</span></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Syncing Suppliers and Purchase Orders</span></strong></p><p>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.</p><p><br></p><p>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'. </p><p><br></p><p id="isPasted">Purchase orders can be pushed to Xero using the selected currency and conversion amount if "Apply currency and conversion for Purchase Orders" is enabled in the "Syncing to Xero" tab.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU3NGU0MThjLTljYmUtNDU5OS1iMjZhLTBmMTQ3OWQ4NTkyMiJ9.kt_pX9DiWepPzgDWiPgSXkwQAwdjGbERC4R-pCZAp5M" class="fr-fic fr-fil fr-dib" width="520" style="width: 522px; height: 424.076px;" height="424"></p><p><strong><span style="font-size: 10pt;">Fig 34. Allow status change option.</span></strong></p><p><br></p><p><strong><em>Note: </em></strong><em><strong>Due to current limitations, the address field of a supplier does not get synced back to Xero.</strong></em></p><p><br></p><p>Purchase orders also have the exact same requirements as invoices.</p><p><br></p><p><strong><span style="font-size: 12pt;">Xero Webhooks</span></strong></p><p>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. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjhkYmYyNmQxLWQzOTktNDYxNi1iN2VlLTk3NWU4NWZhN2VmZSJ9.gtSQpxp33mGKtpSbJmuoFNjQB-rZTl6UdtzDJ0ceSkI" class="fr-fic fr-fil fr-dib" width="1033" height="349"></p><p><strong><span style="font-size: 10pt;">Fig 35. Webhooks configuration. </span></strong></p><p><br></p><p>When the 'Invoices (Created)' webhook is enabled a Invoice will be created in Halo each time an invoice is created in Xero. However, you can prevent invoices in Xero with the 'Draft' status being created in Halo using the 'Don't create Invoices in Draft status' checkbox. This will prevent invoices syncing over until they have moved out of the Draft status. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImZmMDFjYWI0LWIwYTgtNGY3MS1hM2M1LTgyMjBhMmQxYWM1MiJ9.58dnndj-95so-JEqz2dhRi-FepGhoAgv5To8Op_ocAU" class="fr-fic fr-fil fr-dib" width="258" style="width: 260px; height: 101.239px;" height="101"></p><p><strong><span style="font-size: 10pt;">Fig 36. Prevent invoices being created in Halo when the Xero invoice is still in Draft status</span></strong></p><p><br></p><p><strong><span style="font-size: 11pt;"><em>Note: Xero webhooks are not supported if you are using the 'custom developer app' authentication method. </em></span></strong><em><span style="font-size: 11pt;"><br></span></em></p><p><br></p><p>Sync Payments</p><p>If the 'Invoices (Updated)' webhook is enabled, when the invoice in Xero is fully paid this will update the invoice in Halo. Adding a payment record for the full amount to the invoice in Halo and marking it as fully paid. </p><p><br></p><p>You will have an additional option under the 'Webhooks' tab to 'Allow payments to be created in Halo when receiving Invoice webhooks from Xero'.</p><p>Allow payments to be created in Halo when receiving Invoice webhooks from Xero- When enabled payments to invoices in Xero will sync to Halo, adding a payment record to the invoice in Halo. This includes partial payments. </p><p><br></p><p><strong><span style="font-size: 12pt;">Sync Reversed Payments</span></strong></p><p>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. </p><p><br></p><p>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 payments to be reversed in Halo when receiving Invoice webhooks from Xero'. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4MWQyYTg3LWIyMWMtNDQ5Yi05MmMwLTkwNTQwM2FhZDA4ZiJ9.s3atX8_m_1NuHU0zjqDRh5IMJDStnwMVmvwBcppZv90" class="fr-fic fr-fil fr-dib" width="778" height="285"></p><p><strong><span style="font-size: 10pt;">Fig 37. Reverse payment option.</span></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Only import customers that have at least one invoice</span></strong></p><p>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. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjFjMjBhYWRiLWUxMjQtNDMyMy1iZGI2LWJhMjNjMzQxZjJmMyJ9.XvzZCVxVbvZwpc28c5V-X5wkxD2DV7qlgq9PRe6TPWg" class="fr-fic fr-fil fr-dib" width="843" style="width: 845px; height: 352.284px;" height="352"></p><p><strong><span style="font-size: 10pt;">Fig 38. Import customer records option.</span></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Errors</span></strong></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZiOGEyODFkLWRkYjItNGFjZC1iMGIwLTgyN2JjNzlmYzU4OCJ9.rcv1ogXJ0eFhAJ2QjSedx3E-NDEx-j6JzDnl3dOzSLw" alt="" width="710" height="304" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 39. Error log.</span></strong></p><p><br></p><p>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.</p><p><br></p><p>We can also decide the invoice line data shown in Xero when the invoice is created in Halo and synced to Xero.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjAxY2M0NDFiLTdjZTctNDA0ZS1hZGVlLWViYjQ5ODdjNTM1NSJ9._wLmd2587aoxjDw8z2ZARH0KMkyJABHK81ShFS46W0g" class="fr-fic fr-fil fr-dib" width="445" height="93"></p><p><strong><span style="font-size: 10pt;">Fig 40. Invoice description option.</span></strong></p><p><br></p><p><em><strong>Note: Payment References</strong></em><em><strong> will be included in the data pushed to Xero Payments.</strong></em></p>
