How to Set up and use the Xero Integration

How to set up and send placement data for Invoices using the Xero Integration.

 

What is Xero?

Xero is an accountancy package that allows businesses to manage their payments and billing via a centralised platform. Using the Firefish Integration for Xero, you can automatically create draft invoices in Xero whenever you confirm a permanent placement or complete a timesheet for a contract placement.

You will need an account with Xero in order to use the integration. For more information, click here.

How to Enable Xero

Xero is available on the Professional and Enterprise plans only. If you would like to upgrade from a Basic plan to access Xero, you can schedule a call with our upgrades team here. 

You can enable Xero in the Integration Settings menu. A super user can go to Settings > Integrations > Pay & Bill and click ‘Enable’ for Xero.

Once you have enabled the integration, you will need to connect to your Xero account. Click the connect button to be redirected to Xero, where you can log in and authorise the connection.

Once you’ve logged in and connected, you’ll be able to link your site to your Xero organisation.

Note that in order to use Xero effectively, you will also need to ensure that you have set default payment terms for invoices, and an available revenue Accounts Code in your Xero Organisation.

Enterprise Customers using Xero

Connecting to an account and any additional organisations in Xero must be done from the Primary Site. Once connected, each secondary site super user can determine which of their organisations are used, and configure Field Properties and Workflow Settings on a site by site basis.

Configuring Contact & Company Field Properties in Xero

Via the integration, Firefish will send Accounts Contact information linked to the Placement in Firefish to Xero in order to create invoices. Using the Field Properties tab, you can choose what information we send in from Firefish.

Firefish will only ever update blank fields in Xero, meaning that if the matched record is already populated in Xero, we will not overwrite it.

Matching Accounts Contacts in Firefish with Contact Records in Xero

Firefish will match an Accounts Contact to Xero using the following steps:

• Search for the Accounts Contact’s email address in Xero
• Search for the Accounts Contact’s company email address in Xero
• Search for the Accounts Contact’s company name in Xero on records with no email address

If Firefish cannot find a matching record after checking all three steps, we will attempt to create a record in Firefish if the Create Contacts setting is enabled for that workflow.

If we are unable to create or match to an existing contact record in Xero, Firefish will not send invoice information.

Note Xero insists on Company Names being unique in Xero. As such if a company already exists in Xero but cannot be matched due to a pre-existing email address, you will need to fix this record manually in Xero.

Configuring Permanent & Contract Workflow Settings in Xero 

The workflow tab allows you to choose if and how invoices are sent for both Permanent and Contract placements. 

All settings are enabled by default, and you will need to set an Accounts Code in Xero for each invoicing workflow. 

The settings menu is also where we enable and lock any other Firefish settings that are needed for the Xero Integration. 

Note: To use contract invoicing, the Timesheets and Timesheet Approver features must be enabled and will be switched on while Contract Invoicing is enabled. 

 

To disable invoices for an entire workflow type, toggle the entire section off.

Permanent Workflow Fields in Xero 

The fields dropdown in the Permanent invoicing workflow allows you to see what information we must have on a placement record, as well as giving you the option to determine what we include in the description we send to Xero for your invoice.  

Any additional fields selected will be included in the Line Item Description on your invoice in the order they appear here. You can also make the field mandatory on the Placement Screen by ticking the mandatory box next to it. This will ensure your users always provide this information before confirming a placement. 

Contract Workflow Fields in Xero 

To generate invoices for contract placements, Firefish uses information on the Contract Placement record and the linked timesheet. The fields dropdown allows you to see what information we must have on each part, as well as giving you the option to determine what we also include in the description we send to Xero for your invoice. 

Any additional fields selected will be included in each Line Item Description on your invoice in the order they appear here. You can also make the field mandatory on the Placement Screen by ticking the mandatory box next to it. This will ensure your users always provide this information before confirming a placement. 

Including Custom Job Fields in Xero

Any custom fields that have been enabled for the job workflow offer stage in System Configuration > Properties will also be available as additional fields. This is particularly useful if you need to include custom references on your invoices, such as Purchase Orders.

Sending Permanent Placements as Invoice Information to Xero 

Invoice information is automatically sent to Xero whenever a permanent placement is confirmed and after any emails have been sent or skipped.

The workflow is completed in the following steps:

• Check for a matching Accounts Contact in Xero
• Create and/or update the Contact record in Xero if necessary.
• Send the Placement Information to Xero to create a draft invoice.

Cancelling the confirmation workflow will also prevent sending the information Xero.

Once you have received the success modal, you can view your Draft Invoice directly in Xero

Sending Terminations as Credit Note information to Xero 

Credit Note information is automatically sent to Xero whenever a termination is confirmed against a permanent placement with a sales amount that is not 0, and after any emails have been sent or skipped. 

The credit note uses the permanent invoice workflow settings and fields to populate the Line Item Description, and will include any additional fields selected for Permanent Invoices. 

Sending Contract Placements as Invoice Information to Xero 

Contract Invoicing is currently available on a timesheet-by-timesheet basis. Invoice information is automatically sent to Xero whenever a Timesheet is completed, and after any accounts emails have been sent or skipped. 

The workflow is completed in the following steps: 

1. Use the associated Contract Placement to check for a matching Accounts Contact in Xero 
2. Create and/or update the Contact record in Xero if necessary 
3. Send the placement and completed Timesheet information to Xero to create a draft invoice 

Saving a timesheet without completing it or aborting the accounts email workflow will also prevent sending the information to Xero. 

Invoices are populated with a separate line item, grouped per rate type, which means that Basic Hours and any standard overtime are itemised and totalled accordingly. 

To include multiple placements on the same invoice, use the merge invoice function in Xero after creating each draft from Firefish.