Our platform lets you easily add and quickly configure a one-way synchronization of form-captured data to Xero.
After adding and authenticating a Xero Connection, Xero Form Connectors can be added to Data Entry Forms to push data when a form is uploaded, which is what this article is about.
Adding the Connector
Follow these steps to add the connector to your specific form:
- Navigate to App Workshop > Forms.
- Hover over your desired form and click the Connect icon.
- Click the Add Connector button (top-right).
- Select Xero from the options.
Note: The page will refresh with the connector added. Changes are not live until you click Save.
Quick Access Tip
If you are already inside the Form Builder or Settings view, you don’t need to go back to the main menu. Simply click the Connectors tab located directly under the form title at the top of the screen.
Configuring the Connector
Once the Connector is added, you can select what you want to create or update in Xero.
Specify an operation, such as accounting or payroll, and then, more specifically, endpoints, such as contacts, invoices, tracking categories, and timesheets within these areas, where form-captured data will be pushed.
After selecting an operation and endpoint, respective properties become available that can be dynamically driven from field-captured data by referencing field datanames or using a formula.
Depending on the operation and endpoint selected, some properties might require identifiers (IDs) from your Xero account to push data successfully when updating or creating.
The following table contains links to Xero documentation to help you identify ID values. However, obtaining these ID values might be tricky, depending on which ones you need.
| Operation | Endpoint | Property | Xero Docs |
|---|---|---|---|
| Accounting | Contacts | Contact ID | Accounting API Contacts |
| Accounting | Invoices | Invoice Type Invoice ID Line Items | Accounting API Types and Codes Accounting API Invoices Accounting API Invoices |
| Accounting | Tracking Categories | Tracking Category ID | Accounting API Tracking Categories |
| Accounting | Accounts | Account ID | Accounting API Accounts |
| Accounting | Items | Item ID | Accounting API Items |
| Payroll AU | Timesheet | Timesheet ID | Payroll AU API Employees |
| Payroll AU | Employee | Employee ID | Payroll AU API |
| Payroll UK | Timesheet | Calendar ID Timesheet ID | Payroll UK API Pay Run Calendars Payroll UK API Timesheets |
| Payroll UK | Employee | Employee ID | Payroll UK API Employees |
However, if a property you’re looking for isn’t initially available, select the Optional Fields text box, which provides a list of additional fields that can be added for further configuration.
Furthermore, add a Run Condition if you only need this connector to trigger due to a specific condition based on form-captured data. When a formula entered returns a true result on upload, it will trigger the Connector instead of every upload.
Once you’re done configuring, hit Save at the top right. This will enable the Connector to push data to your Xero account when forms are submitted.
Creating vs Updating Xero Data
Certain properties are required when you’re updating or creating new data in Xero with the form connector.
For example, a contact name will be required if you’re creating a new contact, as opposed to a contact name and ID for updating.
| Property | Creating | Updating |
|---|---|---|
| Accounting > Contacts | Name | Name Contact ID |
| Accounting > Invoices | Type Contact ID Contact Name Line Item – Description | Type Invoice ID Contact ID Contact Name Line Item – Description |
| Accounting > Tracking Category | Name | Name Tracking Category ID |
| Accounting > Accounts | Code Name Type | Account ID |
| Accounting > Items | Code | Code |
| Payroll AU > Timesheet | Employee ID Start Date End Date | Timesheet ID Employee ID Start Date End Date |
| Payroll AU > Employee | Employee ID | Employee ID |
| Payroll UK > Timesheet | Payroll Calendar ID Employee ID Start Date End Date | Payroll Calendar ID Employee ID Timesheet ID Start Date End Date |
| Payroll UK > Employee | Employee ID | Employee ID |
Obtaining Xero IDs
There are three options available. Options one and two work to obtain most ID values, whereas option three can acquire them all.
Note that with option two, if your operation is Accounting and you need a Contact ID, Invoice ID, or Tracking Category ID, you should be able to get them from the URL.
Option One (recommended)
Use Xero – Data Source Connectors to pull data into the platform from Xero for use on screens and their connector properties.
Option Two
Navigate your Xero account and obtain an ID from the URL when viewing a contact, invoice, tracking category, or employee.
For example, an Employee ID is obtained from the URL when viewing the Employee’s details in Xero.
Option Three (advanced)
Use a Xero Developer account’s API Explorer feature to GET endpoint data and obtain an ID from a response from your connected organization’s Xero account.
The exact details you use to log into your Xero organizational account can be used to log into your Xero Developer account.
For example, a request to get employee data.
The response with employee IDs.
Managing Repeatable Data
Some endpoints will require you to submit repeatable data in fields that might appear to be for single instances of data. This is best seen on the Payroll endpoints for instance, where you will need to enter values for say, Monday, but the timesheet may cover multiple weeks, so you will have more than one Monday for that particular timesheet payroll period.
Below is a list of all the endpoints that can handle repeatable values ie, values that are either from within a table or on a repeatable page:
Accounting API –> Contacts
Addresses
Phones
Contact Persons
SalesTrackingCategories
PurchasesTrackingCategories
Accounting API –> Invoices
LineItems
Payroll AU -> Timesheets
TimesheetLines
NumberOfUnits (Inside TimesheetLines and also repeatable)
Payroll UK/NZ -> Timesheets
TimesheetLines
In this section, we’ll examine the use of repeatable data in two endpoints: the Payroll AU and Payroll NZ endpoints.
Payroll AU
The Timesheet Line can have one or multiple entries. If multiple entries need to be submitted, it is better to put them inside a table (repeatable) and map the fields, e.g., Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, and Sunday.
This would allow for scenarios where a pay period is set to fortnightly and the user will need to enter 2 rows for the pay period, to cater for the 2 weeks in the fortnight period.
The image below shows what a form would look like to cater for a multi-week pay period:
Below is a screenshot of how you map those day fields from the table (shown above) to the connector, allowing the connector to iterate through your rows as required by the pay period specified.
Payroll NZ/UK
This endpoint abides by the same structural conditions as the Payroll AU endpoint, i.e., the start date and End Date need to be the same period as specified in Xero, and the Timesheet Line can have one or multiple entries. When multiple entries need to be submitted, it is best to put these fields inside a table and map the fields in the form to the connector fields.
This endpoint requires two additional parameters to be included, though, and these are:
- Number of Units – this is the number of hours worked on a particular date.
- Date – is the specific date when the work took place.
