Skip to main content
Version: 6.12

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​

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.

Example Billing Customer
Example Billing Customer

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.

Client Default Customer
Client Default Customer

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

Xero Contact Information
Xero Contact Information

Product Code​

The product and ledger codes can be used to link Patriot Master Charges to item code in Xero Products and Services.

Product and Ledger Code
Product and Ledger Code

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​

Steps to set up authentication:

  1. Using your Xero credentials (Administrator) sign in to the Xero Developer Portal and select 'My Apps'.

  2. 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/ (you may change the port as required). The trailing slash is mandatory here.

  3. Note down the Client ID and Client Secret for later.

  4. Rename applicationSettings.config.example to applicationSettings.config and edit the following values in it:

    • Patriot server: base URL of Patriot server, e.g. https://patriot-server:8002/.
    • Patriot login/password: Must be a user account with billing access.
    • Xero client ID/secret: The Client ID and Secret values noted earlier.
note

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>

  1. Navigate to the folder where the Billing program has been installed (e.g. C:\Program Files (x86)\Patriot Systems\Patriot Xero Billing Utilities). Run the following command in your terminal: PatriotXeroBilling.exe authorise -p 5001 (change the port to match the App 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 you back to localhost.

  2. Back in the program, select your company/organisation (if required) and check that authentication succeeds.

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

Task Arguments Examples​

Batch Generation​

Generate command:

C:\Program Files (x86)\Patriot Systems\Patriot Xero Billing Utilities\PatriotXeroBilling.exe

Generate command 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}

Batch Committing​

Commit command:

C:\Program Files (x86)\Patriot Systems\Patriot Xero Billing Utilities\PatriotXeroBilling.exe

Commit command arguments:

commit --batchId {batchID} --emailInvoices false

note

If "emailInvoices" is set to true, any created invoices will be emailed to the Xero customer upon committing a batch and a link will be provided to view the attachments online. This value is not required and defaults to false. To use this link in an email template, add the following code to the email template:

[Online Invoice Link]

Click here to read more about the Xero email template.

External Billing Integration