Xero Integration
Xero is a cloud based system that provides a comprehensive but easy to use accounting and bookkeeping functions suitable for organisations that have a relatively low volume of transactions. For instance a monitoring business with several hundred bureau customers that sends out a thousand or less invoices monthly. Xero has quickly gained global recognition as a benchmark for small business software.
Xero has the ability for reports to be attached to an invoice and emailed out with the invoice. This feature means Xero can be used with Patriot where there may be several hundred bureaus / dealers each owning many sites. A single (or small number of lines) invoice can be sent to the bureau for many sites and a report attached detailing the charge(s) for each site. While less than a thousand invoices may be sent each month to dealers these invoices may be billing tens of thousands of sites.
Prerequisites
- A Patriot Billing License with the AccountingXero module
- Read External Billing Integration
Xero Customer Contact
In the billing section of System Wide Settings make sure the standard billing mode explicitly is set so that billing customers can be assigned for charges. A billing customer is simply any user that has the "Enable Billing" checkbox set. When this check box is set the customer tab will appear on the user's record. Customers in Patriot should be reflected in the in Xero as a contact.
A customer in Patriot does not necessarily have to be assigned to a client site. However at least one customer needs to be assigned the default customer field on the client site billing tab as this is used as the customer to be billed during automatically during charge transaction generation.
The account number field (Account No) on the Patriot Users Customer tab is used to link the Patriot User to the Xero customer contact. To get the link open the contact in Xero and copy the contactID from the Xero contact URL address
Product Code
The product and ledger codes can be used to link Patriot Master Charges to item code in Xero Products and Services.
Ledger Code
In a similar way the ledger code is used to specify the Xero general ledger code for posting sales figures from invoices (i.e. Debit the customer Credit the Sales Revenue General ledger account).
Xero Installation
The Patriot billing interface that connects to your billing system in this case Xero is driven by a separate utility program. If you have purchased a copy of the Xero billing module you will receive from Patriot the Xero utility program which provides the connection between Patriot and Xero. Run the windows installer provided. Note the installation of this interface will usually be carried out by Patriot support as it involves a number technical steps and diagnostics to get the necessary information. The program comes with a sample DLL which can be modified to get the desired customization.
Xero Authentication
xero uses a two factor authentication.
Installation
Authentication
Using your Xero credentials (Administrator) sign in to the Xero Developer Portal and select 'My Apps'
Create a new App with the following details:-
App Name: Can be anything, but must be unique.
Company URL: your company public URL
OAuth2.0 Redirect URI: http://localhost:5001/ (can change port as required). Trailing slash is mandatory here.
Then take a copy the Client ID and Client Secret.
Rename applicationSettings.config.example to applicationSettings.config and edit:
Patriot server: base URL of Patriot server, e.g. https://patriot-server:8002/.
The Server name and port can be obtained from the Patriot Data Service config file
<setting name="ServerName" serializeAs="String">
<value>Patriot_Server</value>
</setting>
<setting name="APIServerPortNo" serializeAs="String">
<value>8002</value>
</setting>
Patriot login/password: Must be a user account with billing access
Xero client ID/secret: From the Xero app created earlier
From the folder location where the Billing program has been installed (e.g. C:\Program Files (x86)\Patriot Systems\Patriot Xero Billing Utilities) Run PatriotXeroBilling.exe authorise -p 5001 (change port to match app config above)
This will open your browser and prompt you to log in to the app you created using your Xero credentials.Accept the prompts until the browser redirects back to localhost
Back in the program, select your company/organisation (if required) and check that authentication succeeds.
Once authenticated, the billing utility should remain linked as long as it is used regularly. If authentication errors occur, re-run the authentication command to re-authorise.
Xero Task Set-up Examples
Examples:
Generate Command: C:\Program Files (x86)\Patriot Systems\Patriot Xero Billing Utilities\PatriotXeroBilling.exe
Generate Arguments: generate --plugin "C:\Program Files (x86)\Patriot Systems\Patriot Xero Billing Utilities\PatriotXeroBilling.mycompany.dll" --pluginArguments "7" --batchDefinitionId {batchDefinitionId} --startDate {startDate:yyyy-MM-dd} --endDate {endDate:yyyy-MM-dd}
Commit Command: C:\Program Files (x86)\Patriot Systems\Patriot Xero Billing Utilities\PatriotXeroBilling.exe
Commit Arguments: --commit --batchId {batchID}