Xero Integration Services (XIS) Installation and Setup Instructions

This guide is to take you through the basic setup of the Xero Integration Services tool (XIS).

Any additional requirements that do not fit into these instructions, such as mass creation and mass syncing of Invoices, the use of Multi-Currency, the use of Multi-Org (with Xero), etc... you will need to reach out to the Metisphere team to support with more advanced setup options and what the capabilities are.

1. Pre-setup steps for testing the tool in a Salesforce Sandbox

If you do not have a Xero Demo Org/Trial Environment, please follow the below Scribe, which will take you through the steps you need to take to set up a new Xero Instance for testing, if you do already have a Xero instance for testing, skip this and move onto the next step.

WARNING

We do NOT advise using your live Xero Org when testing in a Sandbox, data can and will be modified, which can cause issues. Please ONLY use a Trial Instance or your "Demo Company". If you are unsure what to do please reach out to the Metisphere team who can support.

Create a Xero Trial Org so you can test the integration before going live, use the necessary Scribe below, depending on whether you are a new or existing customer:

Once you have created your Org, you will need to go the Xero Developer login to create a "Connected App", this will be the "gatekeeper" into your Xero Org and is required when integrating with Xero:

2. Installation of the XIS Managed Package

Go to the Salesforce AppExchange and search for "Xero Integration Services", where you will be able to find the XIS Application. Follow the instructions on the AppExchange for the initial installation.

Once the installation has completed and you have received an Email notifying you that the installation has completed, please continue onto step 3 below.

3. Setup of XIS, allowing you to sync data outbound

Xero Setup App

Once your installation is complete, you will need to change the "App" that you are currently viewing to ensure you are on the "Xero Setup" App.

To do this click on the App Launcher (9 dots in a 3x3 box top left), type in "Xero Setup" and click on the "Xero Setup" App, which you can see below with the Xero Logo next to it.

Please note, all of the instructions within this step will assume you are using the "Xero Setup" App. If you are not on the Xero App at any point, please ensure you switch back to it to continue with the setup.

Setup Login to Xero

Complete the steps in the below Scribe to set up and log into Xero from Salesforce.

Syncing Xero Connected Organizations

Now you have connected your Salesforce and Xero Instances, you will need to tell Salesforce which Xero Orgs you want to sync with.

Configuring Xero App Settings and Sync Fields

If you would like to leave the default setup for testing, skip this step, otherwise use the Scribe below to change the settings of your Application.

Test Xero Connection

Now you bi-direction integration has been set up, it's probably a good time to confirm that Salesforce is able to communicate with Xero properly.

4. Setup of Xero Webhooks and how to allow Bi-Directional Sync

To receive updates from Xero when records are created and updated, you will need to set up "Webhooks" in Xero. These are small messages that will be sent from Xero to Salesforce to notify Salesforce that a change has been made.

At that point Salesforce will go back out to Xero to retrieve the relevant record and will store the updates in Salesforce.

Please note - Xero only supports Contact and Invoice Webhooks.

Advanced setup

If you have changed any of the Integration Mapping records, then it would be worth following the below Scribe. If you have not changed any, or are not doing an advanced setup, then you can ignore this.

5. Granting App Permissions to a Users

We would advise to follow Salesforces best practices with Profile Vs Permission Set usage in order to grant permissions to Users within your Salesforce Org, which is to use Permission Sets to grant access.

For Field specific information, please see the next section "6. Add Xero Fields & Buttons to Standard Page Layouts" below.

Using Permission Sets

We have not created a Scribe for creating or updating Permission Sets, as Salesforce has this documented really well here.

The advice would be to create at least 2 separate Permission Sets for your Users;

1. Read Only Access

2. Edit Access

The Objects, as well as their Fields, that you will need to include in the Permission Sets are:

1. Invoice

2. Invoice Line Item

3. Purchase Order (if applicable)

4. Purchase Order Line Item (if applicable)

5. Credit Note (if applicable)

6. Credit Note Line Item (if applicable)

7. Credit Note (if applicable)

8. Credit Note Line Item (if applicable)

Please note only Invoices and Invoice Line Items come as a standard within the Package, all other Objects will be available during your Trial Period only, or until any addons are purchased.

Once you have created your Permission Set(s), you can either directly assign them to the necessary Users, or you can assign them to Permission Set Groups, then assign those to Users.

Using Profiles

We have not created a Scribe for creating or updating Profiles, as Salesforce has this documented really well here.

Specifically see how to "Edit Object Permissions in Profiles" here.

If you are using Profiles, please check the list of Objects above and grant the necessary level of permissions to all Profiles that need access to those Objects.

6. Add Xero Fields & Buttons to Standard Page Layouts

Below all fields on Standard Objects have been outlined with a short description, some of them you will not need to, nor want to, show on a Record Page. Any Custom Objects with the page will already come with a Page Layout out of the box and will only need to be modified if you required a more advanced setup.

Read through the below to determine whether you need any of the fields on a Page layout for a Standard Object or not. Any field with a R on the end is recommended to add to layouts, whether it's read only or not is a business decision. Any field with a T on the end is recommended to add to layouts for testing to ensure that the sync is running correctly but are not needed on the layout in Production. All those fields without a letter are optional.

Where you place the fields on Page Layouts in Salesforce will not affect any of the functionality.

For a full ERD please see this LucidChart, please note this is subject to change as and when new functionality and features are released.

Please Note - Fields do not have to be on the layout for a User to allow them to sync data to Xero. As long as Users have permissions to fields, or an automated process is run using System Mode to modify certain fields, then the syncs should run without issues.

Account Fields

• Billing Contact (xis__Contact__c) - R

  • Primary Billing Contact which is the First and Last Name on the Xero Contact

• Billing Email (xis__Billing_Email__c) - R

  • Primary Xero Contact Email

• Bills Payment Terms Days (xis__Bills_Payment_Terms_Days__c) - R

  • Define the Days/Date of Payment Terms, E.G the 30 of Net30

• Bills Payment Terms Type (xis__Bills_Payment_Terms_Type__c) - R

  • Define the Type value of Payment Terms, E.G the Net of Net30

• Company Registration Number (xis__Company_Registration_Number__c)

  • Company Reg No.

• Contact Id (xis__Contact_Id__c) - T

  • The Record Id of the Xero Contact

• Contact Status (xis__Contact_Status__c)

  • Status of the Contact as defined in Xero

• Default Purchases Account (xis__Default_Purchases_Account__c) - R

  • Default Accounting Code used for Purchases

• Default Sales Account (xis__Default_Sales_Account__c) - R

  • Default Accounting Code used for Sales

• Has Attachment (xis__Has_Attachments__c)

  • System field from Xero that determines whether an Attachment has been added to the Contact in Xero

• Has Validation Error (xis__Has_Validation_Errors__c)

  • System field from Xero that determines whether the last sync had validation errors or not

• Invoice Tax Rate (xis__Invoice_Tax_Rate__c) - R

  • Default Tax Rate used for Invoices

• Is Customer (xis__Is_Customer__c)

  • System field from Xero that determines whether the Xero Contact is a Customer or not

• Is Supplier (xis__Is_Supplier__c)

  • System field from Xero that determines whether the Xero Contact is a Supplier or not

• Last Sync Requested (xis__Last_Sync_Requested__c) - T

  • Date/Time the last sync was requested, this is also used by default as the trigger point in Salesforce to trigger subsequent syncs of records out to Xero

• Open In Xero (xis__Open_In_Xero__c) - R

  • Formula field that displays a hyperlink to the Xero record once it has been synced successfully and there is a Xero Id again the record in Salesforce.

  • The output of the hyperlink will be determined by a Short Code being added to the Xero Util Custom Setting or not, if it has been added then it generates a "deeplink" direct into the Xero Record + Org, otherwise it just links to the Xero Record, however, if the user is in a different Xero Org, then this could flag as a missing/unknown record.

• Purchase Order Tax Rate (xis__Purchase_Order_Tax_Rate__c) - R

  • Default Tax Rate used for Purchase Orders

• Sales Payment Terms Days (xis__Sales_Payment_Terms_Days__c) - R

  • Define the Days/Date of Payment Terms, E.G the 30 of Net30

• Sales Payment Terms Type (xis__Sales_Payment_Terms_Type__c) - R

  • Define the Type value of Payment Terms, E.G the Net of Net30

• Start Sync to Xero (xis__Start_Sync_to_Xero__c) - T

  • Checkbox used as the initial trigger point used to start syncs out to Xero

• Sync Error (xis__Sync_Error__c)

  • Sync error from the last request if there was one

• Tax Number (xis__Tax_Number__c)

  • A Companies Tax Number

• Updated Date UTC (xis__Updated_Date_UTC__c) - T

  • Xeros version of the "Last Modified Date"

Account Buttons

• Sync with Xero

  • Allows a User to manually trigger a Sync with Xero, either to request an update from Xero or to push the current record to Xero

Contact Fields

• Include in Xero Emails (xis__Include_in_Xero_Emails__c) - R

  • Should the Contact be included in Email sent from Xero, for things like Invoices being emailed out.

• Xero Contact (xis__Xero_Contact__c) - R

  • Checkbox to determine whether the Contact should be synced to Xero or not. Xero will only allow 5 Contact Persons max to sync, the XIS tool does not block this count due to data syncing from Xero.

Contact Buttons

There are currently no buttons on the Contact Object, if a sync needs to be triggered, then this must be done from the Account itself.

Product Fields

• Default Purchases Account (xis__Default_Purchases_Account__c) - R

  • Default Accounting Code used for Purchases of the Product

• Default Purchases Tax Rate (xis__Default_Purchases_Tax_Rate__c) - R

  • Default Tax Rate used for Purchases

• Default Sales Account (xis__Default_Sales_Account__c) - R

  • Default Accounting Code used for Sales of the Product

• Default Sales Tax Rate (xis__Default_Sales_Tax_Rate__c) - R

  • Default Tax Rate used for Sales

• Inventory Asset Account (xis__Inventory_Asset_Account__c)

  • Default Inventory Asset Accounting Code

• Is Purchased (xis__Is_Purchased__c)

  • Determines whether this is a purchasable Product/Service or not

• Is Sold (xis__Is_Sold__c)

  • Determines whether this is a sellable Product/Service or not

• Is Tracked As Inventory (xis__Is_Tracked_As_Inventory__c)

  • Determines whether this has trackable Inventory or not

• Item Id (xis__Item_Id__c) - T

  • The Record Id of the Xero Item

• Last Sync Requested (xis__Last_Sync_Requested__c) - T

  • Date/Time the last sync was requested, this is also used by default as the trigger point in Salesforce to trigger subsequent syncs of records out to Xero

• Start Sync to Xero (xis__Start_Sync_to_Xero__c) - R

  • Checkbox used as the initial trigger point used to start syncs out to Xero

• Sync Error (xis__Sync_Error__c) - R

  • Sync error from the last request if there was one

• Updated Date UTC (xis__Updated_Date_UTC__c)

  • Xeros version of the "Last Modified Date"

Product Buttons

• Sync with Xero

  • Allows a User to manually trigger a Sync with Xero, either to request an update from Xero or to push the current record to Xero

7. Creation and syncing of a Salesforce Account/Xero Contact and an Invoice

Now you have your full integration set up, follow the below scribe to show you how to sync an Account, Invoice, and Product to Xero.

Please Note - All Objects that come with the XIS Tool have a "Sync with Xero" button, as long as you're data is correct you should be able to simply sync anything

8. Optional Advanced config

Additional Fields on Credit Notes, Invoices, or Purchase Orders New/Edit Screens

If you have a business use case where you have additional fields on Credit Note, Invoice, or Purchase Order Objects in Salesforce, which could be; fields that do not come out of the box with the Managed Package, or fields that do come out of the box with the Managed Package, however you would like to view them on the layout in the custom New/Edit Screens.

We have set up some functionality to allow you to do that. In the below Scribe it will show you how you you can add an Opportunity lookup onto the Invoice Object, then pull the Amount field and have this displayed on the Invoice in New/Edit Screens.

These steps can be taken on any Standard or Custom Object, if you need to raise an Invoice from a Contract, Quote, Service Contract, etc... all you need to do is follow the below but with the correct Field Name/Object selection.

Note - The steps that have been taken above can also be taken on the Credit Note, as well as the Purchase Order New/Edit Screens also. The logic will work all the same.

Add Tracking Categories to an Invoice Line Item

If you use Tracking Categories in Xero, you will want them ideally to sync bi-directionally between both platforms. To do this follow the below Scribe, which will show you how to create a new Tracking Category field in Salesforce, then how to show this on the Invoice Line Item in the New/Edit Screen.

Please note - This does not cover data mapping between Salesforce and Xero. Once you have everything setup and you are happy with your Configuration, please reach out to the Metisphere Support Team who can help you complete the necessary steps and to advise on best practices.

Feature Roadmap + Known Issues

For the Feature Roadmap + Known Issues, please see the below Google Sheet:

https://docs.google.com/spreadsheets/d/15T5e5E5YtbgpjOaxjCAip2im_W5HoSLR5_k6Ti7DBgw/edit?gid=0#gid=0