This guide provides information on the EzeScan connectivity with XERO. It details the available options and how to configure an EzeScan job into XERO.

Developed for Ezescan Release: 4.3

System Requirements

There are two connection options to connect to Xero.

  • OAuth 2.0 – This is current method for new connections.
  • OAuth (legacy) This is for already configured clients. Please see below for more information.

Configuring Connection Settings

OAuth 2.0


Create a new app on Xero developer portal

 Login to https://developer.xero.com/myapps

Click “New app” button on top right corner

Fill in the details as below:

App details

App name

EzeScan (OAuth 2.0)

Company or application URL

https://ezescan.com.au

Privacy policy URL (optional)

 

App details

OAuth 2.0 redirect URI

http://localhost:5000/

(https can be used on newer windows 10 platforms, if an unsupport browser message appears please use http)

 

 Creating Client id and Client Secret for the app

After creating a new app copy Client Id from the screen.

Generate Client secret 1 and copy secret to safe location for future use.

EzeScan Connector Configuration

When configuring a Job, KFI or Upload the Xero connection settings panel must be filled in. If using a single Xero connection, it is recommended that the connection settings are configured globally. This means that when configuring a new KFI and UPLOAD the settings can be inherited from here.

To do this:

  1. Click the Admin menu, choose Workstation Options.
  2. Click the EDRMS tab and choose the Xero option from the drop-down list that appears.
  3. Enter the following information:Client ID: (use the Client id generated from Xero Portal)

Client Secret: (use the Client secret generated from Xero Portal)

Redirect URI: http://localhost:5000/

OAuth Sign-In: (click the browse button and sign-in Xero OAuth 2.0 authentication page to generate access token)

Tenant: (If your Xero account is connected to multiple tenant database, select and choose a tenant using the browse button)

OAuth Legacy


NOTE

From March 2021 this connection method will be no longer support. Please see here for more information. https://developer.xero.com/documentation/oauth2/overview

This integration works with Xero using their Private Application method.

This method requires that an SSL certificate be generated and the Private Application be registered in Xero for the required Organisation.

Generate SSL Certificate

You will need to generate an SSL Certificate to begin with, as specified on Xero documentation: https://developer.xero.com/documentation/api-guides/create-publicprivate-key

We recommend the following procedure:

  1. Download and install the recommended OpenSSL package from here http://slproweb.com/products/Win32OpenSSL.html
  2. Now open Command Prompt as Administrator navigate to the OpenSSL bin directory (i.e. CD "C:\OpenSSL\bin") Execute the following command but substitute the correct OpenSSL path   SET OPENSSL_CONF=C:\OpenSSL\bin\openssl.cfg
  3. Execute the following commands (excluding comments in green) in the order they appear
  4. openssl genrsa -out privatekey.pem 1024 // This will generate a private certificate (.pem)                            openssl req -new -x509 -key privatekey.pem -out publickey.cer -days 365 

    NOTE

    This will generate a public certificate (.cer) with 365 days duration; we recommend a minimum of 730 days.

  5. Execute the following  openssl pkcs12 -export -out public_privatekey.pfx -inkey privatekey.pem -in publickey.cer 

    NOTE

    This will combine the private and public certs into a package with an optional password. The last method will prompt for a password, leave this blank.

  6. Finally, rename the certificate files to something meaningful (i.e. "EzeScan Xero App.cer")

NOTE

Please make a note of the expiry date of your certificate, as you will need to upload a replacement in the Xero Developer Center before the expiry date to ensure uninterrupted service. To recreate a new certificate repeat the steps from 1 to 5.

Register Private Application in Xero

The next Step is to register EzeScan as a private application under the target organization, you will need to repeat this step for each Organisation within Xero you wish to use EzeScan with.

  1. Login to the following site using the credentials with access to the target Organisation -https://api.xero.com/Application/
  2. Click on the Add option
  3. Select the "Private - just for use with my own organisation" option
  4. Enter a name for the Private Application (i.e. "EzeScan Xero App")

    NOTE

    If using EzeScan with multiple organisations you will need to name appropriately (relate to organisation name).

  5. Select the public certificate (.cer) file that was generated in the previous step
  6. Once you have entered a name for the application and uploaded the public key, the API token and secret values are returned.
  7. Click the Save option
  8. If successful Xero will generate Consumer Key and Consumer Secret

These values, along with the application name, will need to be entered into the connection options, make sure this information is recorded and kept with the SSL certificate generated in section 2.2 OAuth Legacy.

EzeScan Connector Configuration

To configure a KFI Field to use the Xero connector, the connector should be selected in the KFI Form -> EDRMS tab, or alternatively in the KFI Field Form -> Alternative EDRMS tab, and the connection settings filled in.

To configure an Upload to use the XERO connector, the connector should be selected in the Upload To option and the connection settings filled in.

The Xero connection settings are as follows –

Field

Description

Application Name

Enter the name for the application used in Section 3.

Consumer Key

Enter Consumer key for this organization generated in Section 3

Consumer Secret

Enter Consumer Secret for this organization generated in Section 3

X509 Certificate

Select the SSL Certificate generated in Section 2. (use the .PFX extension)

Passphrase

Enter the passphrase (if used in Section 2 otherwise leave blank)

If only connecting to the one organisation, it is recommended that the XERO connection settings be configured globally. To configure the connection settings globally:

  1. Click the Admin menu, choose Workstation Options.
  2. Click the EDRMS tab and choose the XERO Banking or Invoice (depending on what you are doing) option from the drop down list that appears.
  3. Enter Xero connection settings.
  4. Click save button

When the connection settings are configured globally a Use Global Connection Settings option will appear on the connection settings in KFI and Upload. Check this option to use the global settings instead of the existing settings.

KFI Field Settings

The KFI Field Settings allow the operator to browse/search the XERO organisation File for an Account, Contact, Currency, etc. during KFI indexing.

NOTE

The following functionality requires that the EzeScan workstation be licensed for the EDRMS as well as KFI and UPLOAD modules.

Enabling browse options


The XERO settings must be configured before a KFI field can use the XERO browse functionality.

  1. Press F7 to display the KFI form.
  2. Click the EDRMS
  3. Select the XERO from the list of available options.
  4. If using one environment tick “Use Global Connection Settings” or enter the connection settings as per the instructions in section 2 Configuring connection settings
  5. Click the Fields
  6. To enable a field to access XERO you need to:
  7. Click the edit link under Properties for the field.
  8. Click the XERO
  9. Select the Enable XERO Browse Button checkbox

The browse parameters will become active –

Configuring browse parameters


Browse Mode

Choose from one of the following options:

Option

Description

Browse Mode

This option determines the lookup type to perform when the Browse button (F3) is pressed during indexing. The options are: Select Account; Select Contacts; Select Currency; Select Inventory Item; Select Invoice; Select Purchase Order;  Select Tax Rate; Select Tracking Category; and Select Tracking Category Options.

Primary Query

Specify a LINQ Where clause to be used to find one or more objects of the specified lookup type.

The following query can be used to lookup a supplier by ABN where Field1 contains the ABN number: “TaxNumber != NULL and TaxNumber.Replace(“ ”,””) = “<<F1>>”

Query Result Type

Select the return type for search results.

Options are: First Item and All Items.

Query Fallback Action

Select Fallback action to use when primary query has no results.

Options are: Ignore and Show Available Items

Existing Value Action

Select action to use when a field already has a value.

Options are: Keep Existing, Replace Existing and Sow Available Options.

Display As List

Check this option to display search results in a drop-down list, or leave unchecked to display in search form (default).

Display Value Format

Specify the format to use for the display value returned from selected item (ie. “AccountNo:{Code}”

Output Value Format

Specify the format to use for the output value returned from selected item (ie. “{Code}”

Use Caching

Check this to cache data from the server to limit the number of API transactions .

Note: This is highly recommended for high volume sights due to the 1000 connection limit in place on the Xero API.

Select Account Browse Mode

Use this browse mode to lookup or browse for an Account to assign to the invoice line at upload. The default functionality is for the Search for Account form to be displayed when the Browse button (F3) is pressed. However, when the Primary Query option is specified this will be executed first and if successful the matched item(s) will be returned and the search form is bypassed. If the Display As List option is enabled all results will be returned as a list to the field or cell.

Select Contacts Browse Mode

Use this browse mode to lookup or browse for a Contact to assign to the invoice at upload. The default functionality is for the Search for Contacts form (shown below) to be displayed when the Browse button (F3) is pressed. However, when the Primary Query option is specified this will be executed first and if successful the matched item(s) will be returned and the search form is bypassed. If the Display As List option is enabled all results will be returned as a list to the field or cell.

Select Currency Browse Mode

Use this browse mode to lookup or browse for a Currency to assign to the invoice line at upload. The default functionality is for the Search for Currency form (shown below) to be displayed when the Browse button (F3) is pressed. However, when the Primary Query option is specified this will be executed first and if successful the matched item(s) will be returned and the search form is bypassed. If the Display As List option is enabled all results will be returned as a list to the field or cell.

Select Inventory Item Browse Mode

Use this browse mode to lookup or browse for an Inventory Item to assign to the invoice line at upload. The default functionality is for the Search for Inventory Item form (shown below) to be displayed when the Browse button (F3) is pressed. However, when the Primary Query option is specified this will be executed first and if successful the matched item(s) will be returned and the search form is bypassed. If the Display As List option is enabled all results will be returned as a list to the field or cell.

Select Invoice Browse Mode

Use this browse mode to lookup or browse for a Invoice number to assign to the invoice at upload. The default functionality is for the Search for Invoice form (shown below) to be displayed when the Browse button (F3) is pressed. However, when the Primary Query option is specified this will be executed first and if successful the matched item(s) will be returned and the search form is bypassed. If the Display As List option is enabled all results will be returned as a list to the field or cell.

Select Purchase Order Browse Mode

Use this browse mode to lookup or browse for a Purchase Order to assign to the invoice line at upload. The default functionality is for the Search for Purchase Order form (shown below) to be displayed when the Browse button (F3) is pressed. However, when the Primary Query option is specified this will be executed first and if successful the matched item(s) will be returned and the search form is bypassed. If the Display As List option is enabled all results will be returned as a list to the field or cell.

Select Tax Code Browse Mode

Use this browse mode to lookup or browse for a Tax Code to assign to the invoice line at upload. The default functionality is for the Search for Tax Code form (shown below) to be displayed when the Browse button (F3) is pressed. However, when the Primary Query option is specified this will be executed first and if successful the matched item(s) will be returned and the search form is bypassed. If the Display As List option is enabled all results will be returned as a list to the field or cell.

Select Tracking Browse Mode

Use this browse mode to lookup or browse for a Tracking Code to assign to the invoice line at upload. The default functionality is for the Search for Tracking Code form (shown below) to be displayed when the Browse button (F3) is pressed. However, when the Primary Query option is specified this will be executed first and if successful the matched item(s) will be returned and the search form is bypassed. If the Display As List option is enabled all results will be returned as a list to the field or cell.

Select Tracking Option Browse Mode

Use this browse mode to lookup or browse for a Tracking Options to assign to the invoice line at upload. The default functionality is for the Search for Tracking Options form (shown below) to be displayed when the Browse button (F3) is pressed. However, when the Primary Query option is specified this will be executed first and if successful the matched item(s) will be returned and the search form is bypassed. If the Display As List option is enabled all results will be returned as a list to the field or cell.

XERO – Primary Query Examples


Below are some examples of Primary Queries that can be used to return results from a Company within Xero.

Select Supplier based on ABN

TaxNumber != NULL and TaxNumber.Replace(" ","") = "<<F1>>"

Select Invoice Number

(Contact.ContactID.ToString("D") == "<<F4>>") AND (Status != "DELETED") AND (InvoiceNumber == "<<F11>>")

Select Supplier Account Name

Code == "<<F5>>"

Upload Settings

The UPLOAD module will obtain the KFI output data to pass into XERO.

NOTE

The following functionality requires that the EzeScan workstation be licensed for the EDRMS as well as KFI and UPLOAD modules.

Configuring connection parameters


  1. Open the Upload Form (F8).
  2. Choose the Upload Type you want to configure.
  3. On the left hand side in the Upload Properties panel, choose Xero in the Upload to

If using a single environment tick use Global Connection Settings.

Configuring built-in upload fields


Xero – Invoice Upload Fields

The common invoice header and line item upload fields will appear after choosing the XERO – Invoice option in the Upload Properties pane (See screenshot below).

The invoice header fields, Line Item Fields and Payment Fields are listed below. Each field can have its input set using the Source Field cell.

Target Field

Description

Invoice Type

Sets the type of Invoice being processed.

Default: ACCPAY

Status Code

Sets the status of the invoice.

Default: SUBMITTED

Attach Document

Specifies whether to attach a Document to this Invoice Record.

Contact ID

Sets the Xero Identifier for the Account

Currency Code

Sets the Currency AUD/NZD etc.

Currency Rate

 

Invoice Number

Sets the number of the invoice being uploaded.

Reference

Sets the Invoice Reference (ACCREC only - additional reference number)

Invoice Date

Sets the date of the Invoice being processed.

Due Date

Sets the due date of payment for the Invoice being processed.

Net Total

Sets the Net total of the Invoice being processed.

Tax Total

The total of all tax amounts applicable for the Invoice being processed.

Gross Total

Sets the Gross total the Invoice being processed.

Is Tax Inclusive

Sets whether Tax is Included in the Invoice being processed.

Attach Document to Invoice

Attaches document to a specific invoice record based on Invoice GUID

Pay invoice

Sets whether this Invoice is to be paid once uploaded

Payment: Account Code

Sets the Account the payment was made from.

Payment: Account ID

Sets the Account GUID the payment was made from.

Payment: Amount

Sets the payment amount. Must be less than or equal to the outstanding amount owing on the invoice.

Payment: Currency Rate

Exchange rate when payment is received. Only used for non-base currency invoices and credit notes e.g. 0.7500

Payment: Date

Date the payment is being made (YYYY-MM-DD) e.g. 2009-09-06

Payment: Is Reconciled

An optional parameter for the payment.

Payment: Reference

An optional description for the payment e.g. Direct Debit

Payment: Status

The status of the payment.

The below upload fields support two modes for populating the invoice line items:

  1. Invoices with single line item – static values or input fields are mapped directly into line item fields. The ‘Line Items Index Path’ field must be blank to use this mode.
  2. Invoices with multiple line items – CSV column names are mapped into line item fields and values are read in from a Line Items CSV file at upload. The ‘Line Items Index Path’ field must be populated with a valid path to use this mode.

Target Field

Description

Line Items Index Path

Path to where the Index File for Line Items is being stored.

Line: Skip Line

Sets whether to skip this Line in the Line Items Index.

Line: Account Code

Sets the Account Code for the current Line in Line Items

Line: Description

Sets the Description for the current Line in Line Items

Line: Total

Sets the Total for the current Line in Line Items

Line: Tax Amount

Sets the Tax Amount for the current Line in Line Items

Line: Tax Rate

Sets the Tax Rate for the current Line in Line Items

Line: Item Code

Sets the Item Code for the current Line in Line Items

Line: Quantity

Sets the Quantity for the current Line in Line Items

Line: unit Amount

Sets the unit Amount for the current Line in Line Items

Line Items Index Path

Path to where the Index File for Line Items is being stored.

Xero – Bank Transaction Upload Fields

The header fields, Line Item Fields and Payment Fields are listed below. Each field can have its input set using the Source Field cell.

Target Field

Description

Transaction Type

Sets the type of Transaction.

Default: RECEIVE

Status Code

Sets the status of the transaction.

Default: AUTHORISED

Contact ID

Sets the source for the transaction.

Bank Account

Sets the Xero Identifier for the Account

Is Reconciled

An optional parameter for the payment.

Date

Date the payment is being made (YYYY-MM-DD) e.g. 2009-09-06

Reference

Sets the transaction Reference

Currency Code

Sets the Currency AUD/NZD etc.

Currency Rate

Exchange rate to base currency when money is spent or received. e.g. 0.7500 Only used for bank transactions in non base currency. Setting currency is only supported on overpayments.

URL

URL link to a source document

Is Tax Inclusive

Sets whether Tax is Included in the bank transaction being processed.

Net Total

Sets the Net total of the bank transaction being processed.

Tax Total

The total of all tax amounts applicable for the bank transaction being processed.

Gross Total

Sets the Gross total the bank transaction being processed.

Is Tax Inclusive

Sets whether Tax is Included in the bank transaction being processed.

The below upload fields support two modes for populating the bank transaction line items:

  1. Bank transactions with single line item – static values or input fields are mapped directly into line item fields. The ‘Line Items Index Path’ field must be blank to use this mode.
  2. Bank transactions with multiple line items – CSV column names are mapped into line item fields and values are read in from a Line Items CSV file at upload. The ‘Line Items Index Path’ field must be populated with a valid path to use this mode.

Target Field

Description

Line Items Index Path

Path to where the Index File for Line Items is being stored.

Line: Account Code

Sets the Account Code for the current Line in Line Items

Line: Description

Sets the Description for the current Line in Line Items

Line: Total

Sets the Total for the current Line in Line Items

Line: Tax Rate

Sets the Tax Rate for the current Line in Line Items

Line: Item Code

Sets the Item Code for the current Line in Line Items

Line: Quantity

Sets the Quantity for the current Line in Line Items

Line: Unit Amount

Sets the unit Amount for the current Line in Line Items

Applying KFI Output Data to Target Field Data


To pass through the KFI output data into the Upload module the operator is required to set the source field data to the target field data.

  1. In the Upload type, set the Column names from option to the name of the KFI job Type.
  2. In the Field Mappings Grid the operator can apply the Source Field settings to the Target Field settings.
    In the example below the XERO  Target Field Supplier is being populated by the KFI Source Field Supplier ID. The XERO  Target Field Invoice Number is set to a static value of “1234”.
  3. When all the mappings are complete, click Apply.
  4. Click OK to save the changes.

Appendix

Troubleshooting Xero Connector


API Connection limit Error

When reaching the API daily connection limit, you may encounter an error similar to this.

This is due to reaching the maximum number of connection allowed by the Xero API (1000)

To avoid this issue, it is highly recommended the Use Cache check box be enabled on fields that require interaction with Xero. (Refer to Section 5.1)

NOTE

This is a Xero API limitation, Once the limit has been reached EzeScan will no longer be able to process until the connection limit is reset.

Lookup Xero Type Properties


The following links can be used to check what properties are supported by each of the available lookup types.