Enabling the Xero Integration - SPA

Introduction

Practifi's Xero integration allows you to easily create a client in Xero and access paid invoices within a client record in Practifi.  High level information about  Xero invoices linked to Practifi Clients are recorded in Practifi, from where they may be accessed to be viewed directly in Xero. Clients not already in Xero can be created from Practifi.

THESE INSTRUCTIONS ARE DETAILED AND TECHNICAL IN NATURE.  PLEASE DISCUSS YOUR INTEGRATION INSTALLATION PLANS WITH YOUR PRACTIFI CUSTOMER SUPPORT TEAM FOR THEIR ASSISTANCE.

Xero has changed the method of authentication with their systems to use the OAuth 2.0.  These instructions refer to this method of integrating with Practifi.

Before You Start

Contact your Practifi Customer Success Manager let them know your firm's plans to integrate the two systems.  The preparation required for these steps are:

1. A Xero subscription
2. Practifi System Administrator permissions to install and configure the Xero integration
3. Consideration for a name of the Xero-Practifi integration App in Xero, and preparation to copy a Call Back URL, and Consumer Key and Secret, created at Step 2 
4. URL of a website users should be taken to when clicking on a more information link within Xero at Step 2.

Installation Steps

The following steps are required to enable the Xero Integration 

1. Create Auth Provider (performed by Practifi)
2. Create the App link in Xero
3. Create Named Credential
4. Supply Xero Credentials details
5. Create the Xero Tenant ID
6. Enable Xero Integration
7. Synchronise Data
8. Importing Existing Xero Client Data

1. Create Auth Provider

Under the OAuth 2.0 authentication method the Authentication Provider is set up between Xero and Practifi for all Client Orgs.  It is the same reference for all Client Orgs, and is only set up once by Practifi.

Go to Salesforce Setup, and using the Quick Find/Search bar, search for and click on Auth. Providers

Click on New

Complete the details on the new Auth Provider panel, as follows:

Supply the following:

Provider Type: Open ID Connect

Name: Xero  

URL Suffix: Follow default

Consumer Key: Use ABC as a temporary Key.  The following step will generate the Key to be pasted here.

Consumer Secret: Use ABC as a temporary Secret.  The following step will generate the Secret to be pasted here.

Authorize Endpoint URL: https://login.xero.com/identity/connect/authorize

Token Endpoint URL: https://login.xero.com/identity/connect/token

Default Scopes: openid profile email offline_access accounting.transactions accounting.contacts  (all scopes are listed at https://developer.xero.com/documentation/oauth2/scopes) 

Copy the Callback URL value at the end of screen for use at the next step.

2. Create the App link in Xero

This step will require logging on as a Xero Administrator to the Xero Developer portal.

Go to https://app.xero.com/, then My Apps, then New app

A new app panel will appear

Supply the following:

App name: Name of your choosing

Integration type: select Web app

Company or application URL: Can be anything, suggest either the Salesforce Org URL or your company public website

OAuth 2.0 redirect URIs: Paste in the Callback URL copied from step 1 above

Accept the Terms and Conditions to continue

On clicking the Create App button a Client id and Client secret will be created.  Copy these, and paste back into the Auth Provider configuration in step 1, as Consumer Key, and Consumer Secret, respectively.

Note that the Client secret will only be shown once.  Ensure this is retained in a safe location.  If the opportunity to capture it is missed, or is otherwise lost, another secret will need to be created using the Generate another secret link.  Completed example below.

3. Create Named Credential

Create a Named Credential for accessing the Xero client system.  

In Salesforce Setup, go to the Quick Find/Search bar, search for and click on Named Credentials

Click on New Named Credential

 

Supply the following:

Label: Xero

Name: Xero

URL: https://api.xero.com

Identity Type: Named Principal

Authentication Protocol: OAuth 2.0

Authentication Provider: Xero (per the Auth. Provider set up above in Step 1)

Scope: leave blank

Start Authentication on Save: Ticked.  Clicking Save will commence the authentication between the systems.  The systems will communicate with each other without user intervention.  On completion the Authentication Status field changes to Authenticated.

4. Supply Xero Credentials details

In Salesforce Setup, go to the Quick Find/Search bar, search for and click on Custom Settings

Look for Xero Credentials in the list.  If it is missing, click New

Supply the following:

Invoice Instalment Type: SITINVOICE

Named Credentials: Xero

The Xero Tenant Id will be populated in the next step

On completion click Save

5. Create the Xero Tenant ID

In Practifi, click on Salesforce Settings

Click on Config

Click on the Get and Update Xero Tenant Id button

This will retrieve a Tenant Id from Xero and populate the Xero Tenant Id field in the Xero Credentials Custom Settings panel.

6. Enable Xero Integration

Under the Practifi Settings panel locate the Xero line under the Integrations heading, and ensure that the Enable Xero tickbox is ticked.  Use the Edit button on the right to switch to Edit mode to make the update.

The setup is completed.

7. Synchronise Data

Client and Contacts

Send/Sync To Xero

Client and Contacts are synched from Practifi to Xero using the Send to Xero button under the Other Actions dropdown under a Practifi Client view.  If the Client does not already exist in Xero it will be created, using the data below from Practifi.   

The details synched are:

Clients	Contacts
Client Name	First Name, Last Name
Entity Number 1 (ABN in Xero)	Work Phone
Shipping Address	Mobile Phone
Postal Address	Email

View Client and Contact in Xero

View the Client and Contact information using the View in Xero button under the Other Actions button on a Client record.

This will require the user to log on to Xero when the Xero panel appears.

Invoices (in Xero), Instalments (in Practifi)

Establish Sync Process between Practifi and Xero

On the Practifi Config section click on the Sync Xero Invoices button.   Note that this action actually creates a Scheduled Job in Practifi, initially occurring 24 hours from time at which it was pressed.  This button will disappear once it has been pressed.  It is a once-off operation.  

The details synched are:

Field	Content
Type	Invoice
Comments	Invoice Synced from Xero: Date Time Reference
Stage	Paid
Effective Date	Due date in Xero
Paid Date	Paid date in Xero
Actual Amount
Related Client

View Instalments/Invoices

Instalments/Invoices for those Clients which have synched data between Practifi and Xero are listed on the Client record under the Instalments side tab

The list of Instalments (Invoices) appear in the table.  

Click on the hyperlinked Number field will open another panel with further details. 

Clicking on the View in Xero button at the top-right will start the process to log on to Xero to view the Invoice/Instalment in Xero, if the user has not already logged on to Xero.  There is no Single Sign On facility with Xero.

8. Importing Existing Xero Client Data

This step is only required if there is an existing Xero account, with data which should be uploaded to a new Practifi system.  This will require synching both Xero and Practifi client data using a Dataloader, and storing the Xero Client IDs in the Practifi client records.  For this, some effort is needed to ensure a reliable match of client names in Xero and Practifi.  Raise a support ticket for instruction with this step.