How to setup and use the Xero Online Integration

This article will walk you through the configuration and use of the Xero Online Integration in farmerswife available in v7.4. The Xero integration is a separate licensed feature. Please contact sales@farmerswife.com for pricing information.

Before you begin

• Make sure your farmerswife server is running on 7.4 (Beta).
• You need to have a farmerswife license with Xero enabled.
• You need a Xero Online Developer Account. (see quick steps at the end of this article)
  
  

Step-by-step instructions

Step 1: Fetch your Xero Connection Details

In Xero, go to your Apps > Configuration settings:

Redirect URL: 


For standard configurations:
https://[yourdomain]:[ApiPort]/oidc/callback

For Clouded Instances:
https://api.[yourdomain].cloud.farmerswife.com/oidc/callback

[Optional] Webhook Key:
This will allow you to sync the "Paid" status of your invoice from Xero to farmerswife.

Delivery URL:


For standard Configurations
https://[yourdomain]:[ApiPort]/api/v1/callback

For Clouded Instances:
https://api.[yourDomain].cloud.farmerswife.com/api/v1/webhook/xero

You need to specify "Invoices" as the event type that will trigger Webhook notifications.

Step 2: Configure the Connection to Xero in farmerswife

1. In farmerswife Desktop Client as an Admin with access to Server Setup, go to Toolbox > Settings > Server Setup > Financial > Enable Xero Online
2. Click Setup, this is a simple window where administrators enter: Client ID, Client Secret and OAuth2 redirect URI, Webhook Key.
   
   
3. After filling in this information click "Connect to Xero"
4. A browser window will open requesting access to your organisation's data and user account information
   
5. After that Xero is connected
   
   
   
6. In the farmerswife Toolbox, click the 'Fetch Xero Tenants' button
7. Select as default the tenant from your organisation.

Step 3: Add Invoice Custom fields to farmerswife

Add at minimum the following fields

If you are a cloud hosted customer we will add these for you.

• Xero Id (This will be The Xero internal unique identifier for the invoice)
• Xero Number (The invoice number displayed to users in Xero)
  
  

Step 5: Customer mapping

1. The Customer name in Xero Application must be exactly the same as the FW Client/Company
2. When sending an invoice from farmerswife to Xero, the Customer data displayed on the Xero invoice is retrieved directly from the Xero Customer Hub.

Go to Xero > Sales > Customers > Edit

1. In Invoice Creator/Manager select one or multiple invoices. 
2. Editing the description of the items will not change the REF number used for mapping.
3. Right click or click menu.
4. Choose "Send to Xero" for selected invoices to transfer the invoices to Xero

Next, in farmerswife:

1. Validates that "Xero Id" and "Xero Number" custom fields, Customer and Products and Services exist before exporting
2. Prompts for OAuth2 authorization if needed,
3. Then posts each invoice to Xero and writes back the returned identifiers.
4. Updates the transferred status of the invoices 
5. A new Invoice custom field “Xero Number” and "Xero Id" are auto-filled when creating the Xero invoice, but can be used to link existing invoices.
   
   

Invoice Edit Window: When an invoice already has a Xero Id, the editor shows a Xero button that launches the corresponding invoice in Xero, using sandbox or production URLs as configured.

2. Display and filter transferred Invoices

In Invoice Manager, Search results > click the Menu icon > Edit View to add the "Transferred" column

How to add a Xero Developer Account

Follow the steps in the Xero Documentation: https://developer.xero.com/documentation/getting-started-guide/ 

1. Go to this url https://www.xero.com/signup/developers/ to sign up for your free Xero account
2. Next, register the application in `developer.xero.com/app/manage`
3. Proceed by adding a `New App`
4. Choose Web App.
5. Enter the Company or app URL you will use.
   • e.g. https://www.yourdomain.com 
   • and the redirect URL: `https://<yourdomain>/oidc/callback`
6. The client ID is automatically created after the app is created and you need to generate the client secret from the 'Configuration' option inside your application on the developer portal.