Xero Service

1. Xero account configuration

1.1. General

1. Add your organization on https://my.xero.com/!xkcD/Dashboard

   

2. Enter the Company and create a contact in the menu Contacts > All Contacts > Add New Contact.

   

3. Enter the contact and take its ID, it will be needed to specify in the Encodify item you want to sync with Xero document.

   

4. Go to https://developer.xero.com/myapps/ and create a private app for managing connection on Xero side.  Here enter the Company or application URL which is your systems URL. 

   Paste the same URL to the OAuth 2.0 redirect URI field. This field will have to be updated with another URL later during configuration of the connected service.

   

   OAuth 2.0 credentials will be available in the view app page.

   Client id and Client secret will be needed for configuring the service in Encodify.

   Click Generate a secret to get the client secret. 

1. Go to Xero organisation Dashboard page https://my.xero.com/!xkcD/Dashboard, enter Accounting -> Advanced -> Tracking categories
   

2. Add the category tracking and options for it via the Add Tracking category button, for example:
   City: Kyiv, Odessa
   Country: Ukraine, Denmark

Note the category ID which is visible in the browser navigation bar (you must have at least 2 categories to see the ID). This ID will be specified in the corresponding CategoryID field in Encodify Linked Item as well as Category options (they can be just the text values).

Encodify Tracking Category fields must be mapped in Xero service in Encodify (see Mappings section below).

1.3 Currency config

You will configure currencies for the cases where invoices will be posted in currencies other than your organization's default currency.

To set the available currencies for the organizations go to your organization's dashboard (https://go.xero.com/Dashboard/) and under your organization name, click Settings and then select Currencies on the page that opens.

2. Encodify service configuration

Please, note!

-   In case your system has an existing XERO connected service and account, it is required to create a new connected account, while the service itself can be used after upgrade.

Preconditions

- Xero connected service is controlled by the system propeties setting, therefore before configuring the service make sure that enable.connections.xero is set to your site ID or is enabled for all sites.

- Make sure that your site has valid URL  in System configuration > Site edit

2.1. Account configuration

Click Add Service next to the XERO service type on the Add Service tab in Site Configuration > Connections > Connected services

Step 2

1. Select a user that will be used for the integration, remember that selected user whould have API access enabled. Please, note: User mapped in Xero connected service is used only as an agent on behalf of which syncronization is done, but all the access restrictions related to the user(module, ,status, group access) are ignored during syncronization Encodify > XERO > Encodify.

2. Get the Xero Tenant id by performing the following steps:

   1. Go to https://developer.xero.com/myapps/ > select your app and enter it

   2. In the OAuth 2.0 redirect URI field, paste the value that is present in the Callback url field on the current wizard step in Encodify and click Save.

      e.g. https://panda3-ibo.encode.dk/ibo/rest/site/1/connection/121/oauth2/callback

   3. Go back to Encodify system > copy the value that is present in the Authorize url field and open it in the separate browser tab. 

   4. On the XERO authorization page, enter your XERO credentials > confirm access for your application. 

   5. As a result of successful authentication, the following json will be returned

      {"result":"Auth code was successfully processed"}

   6. Copy the value in the Tenants URL field and open it in the new browser tab.

   7. Copy the tenantId value from the returned json

      [{"id":"9f821b4f-d137-44d7-a23b-13a9d74578c7","tenantId":"b9aa9a4e-06e8-459c-88f3-c868eb074ea3","tenantType":"ORGANISATION","createdDateUTC":null,"updatedDateUtc":{"nano":563200000,"year":2020,"monthValue":4,"dayOfMonth":14,"hour":7,"minute":22,"second":24,"dayOfWeek":"TUESDAY","dayOfYear":105,"month":"APRIL","chronology":{"id":"ISO","calendarType":"iso8601"}}}]

3. Paste the just copied tenantID to the Xero Tenant id field

   

4. Select Xero Type (note that only Invoice is currently supported)

5. Select the corresponding Header and Line item modules.

6. Copy the value of the Send notifications to field and save it locally (it will be required to set up Xero > Encodify integration).

Step 3

On this step, you can map the fields from Encodify to the fields in Xero. Click on the Xero field in Available fields section to add one to mapping.

In the Mapped fields section you have to select the corresponding field from the Encodify module to map it to Xero field.

Please note!

The list of required fields that will need to sent to XERO and therefore mapped in the the service depends on the invoice status values. However the following list of fields are mandatory for all types of status:

Required fields in Header module:

• Status

• XERO contact ID

• Invoice date

• Due date

• Currency Code

• Invoice Type

• Line amount type

3. Configure Xero-to-Encodify sync

Please, note the following:

Currently, the Xero > Encodify integration is limited only to the Status field in the Header module. This synchronization will also ignore any actions configured in the module and will update the status of the invoice in Encodify no matter if any actions are configured in the Header module or not. Please, also note that it will not trigger any actions in the Encodify e.g. action with event "Update"

In order to have status synchronization from Xero to Encodify, you have to additionally configure Xero webhook.

1. Go to https://developer.xero.com/myapps/ > select your app and enter it.

2. Switch to the Webhook tab.

3. Paste the URL saved on Step 2 (6.) into the Webhook key field. Alternatively, webhook URL can be copied from the connected service > Step 2 > Send notifications to field.

4. Click Save and copy the webhook key.

5. Go back to the Encodify system > Connections > Connected services > Connected accounts tab.

6. Open the corresponding xero connected account for edit > paste the webhook key copied previously > save the connected account.

7. Test the backward syncronization by going to back to the xero app configuration page > Webhooks and click Send "Intent to receive". Correctly working integration from Xero to Encodify should show the OK status.

Note!

In case Intent to receive request does not return OK, check the following:

- Nginx settings does not reject XERO requests

- Webhook URL is correct with corresponding site and service ids

4. Configure action

If you want Xero records updated when you perform CRUD operations in Encodify, you have to create action for the required event in the Headers modules in Module > Actions. The typical use case is configuring an action triggered on Workflow status change, so when Encodify item is ready, the user is changing the status to e.g. SUBMITTED, and corresponding Xero document will be created.

5. Statuses supported by Xero

• AUTHORISED

• DELETED

• DRAFT

• PAID

• SUBMITTED

• VOIDED

Please, note that the values are case-sensitive.

6. Fields for mapping

Header module

Inline module

Caused by: java.lang.NullPointerException
	at dk.encode.ebms.connections.xero.XeroServiceImpl.getLineItems(XeroServiceImpl.java:432) ~[classes/:?]

message:*SyncConnectedServiceQueueListener*
message:*SyncConnectedServiceWebhookQueueListener*