Xero Integration - Detailed Data Mapping / Data Workflow Filter Options

  • Updated

Before you start you should know

  • The Xero Integration is implemented via our Integrations Hub, a platform that allows for intuitive & flexible set-up & management of your integrations with 3rd party systems. 
  • This is a paid additional feature of Assignar. Please reach out to your Assignar rep for pricing.

Learn how data is synced, how fields are mapped for each workflow and the available configuration options for each workflow.

 

Workflows that we support through the Xero Integration with Assignar:

 

Screenshot 2024-10-21 at 4.03.38 PM.png

(>> indicates the direction that the data flows)

 

 

Prerequisites for Xero Integration:

  • Please review each Workflow section below in detail for additional Prerequisites/ Configuration. 
  • Please note that the integration will use one (Connected Application Slot) within your Xero Environment. 
    • You can check if you have a (Connected Application Slot) within your Xero Environment by going to (Organization Settings) then (Connected Apps).
  • ***If you wish to use the Projects Workflow, then you must have the Projects add-on in Xero.
  • ***The Timesheets Workflow will only work on the newest version of Timesheets within Assignar.
    • If you are interested in the Timesheets workflow and an existing Assignar customer, please reach out to our Customer Support Team to confirm that you are on the newest version of Timesheets.
    • ***Time recorded in dockets and manually set pay rates are not supported.

Data Syncing

Once your Xero Integration is setup, you can sync your data using automatic time based syncs or manually (if you need to move data across systems sooner).

Automatic Syncs for (Clients, Projects, Workers)
  • 4 Times Per Day, Monday - Friday at approximately 12:00 AM, 6:00 AM, 12:00 PM, and 6:00 PM Local Time.  Local time is determined during the setup process.
  • Once Daily on Weekends
Manual Syncs
  • By pushing the Sync Now option, the Sync job will enter the queue, this job will start in 1 hour or less.
Timesheet and Account Codes Syncs
  • The Automatic Timesheet workflow will only work if you do not use Assignar's (Overtime Rules).
    • If you do not use (Overtime Rules) then the automatic sync will sync once per day at 12:00AM 7 days a week. 
  • If you choose to use (Overtime Rules) in Assignar, then Timesheets will need to be manually synced at the end of each pay period (once a week)
  • Account Codes can be synced automatically once per day at 12:00AM or run manually.

 

Integration Workflows

 

Xero Payroll Employees → Assignar Fieldworkers

***The Integration will pull Payroll Employees from Xero when Employees are created under (Payroll > Employee Management > Employees)***

Screenshot 2024-10-21 at 3.32.03 PM.png

 

Configuration / Prerequisites:

  • By default only (Active status Payroll Employees) from Xero will sync to Assignar. 
  • ***If there is not an email address entered on the Payroll Employee in Xero, then the Assignar Username will be set to first.last@tenantName.com
  • ***If you plan to use the Timesheet Workflow, then any Payroll Employee that you wish to have time tracked against must have a (Payroll Calendar) assigned to the Payroll Employee in Xero.
    • In order to assign a (Payroll Calendar) to a Payroll Employee, you must first create a (Payroll Calendar)
      • (Payroll Calendars) are created under the (Payroll Frequencies) section under (Payroll Setting) in Xero.
    • Once the (Payroll Calendar) has been created you will need to go to your (Payroll Employee) and then select the (Employment) tab, then scroll down to the (Payroll Calendar) and assign one of your previous created (Payroll Calendars).
  • ***Please note that if you (Delete or End Employment) on a (Payroll Employee) in Xero, then you will need to mark the (Worker) as (Inactive or archived) in Assignar as well.

Employee / Worker Key Data Fields

***(Do not update these fields within Assignar, Xero is the source of truth)***

Xero (Employees)

Assignar (Workers)

First Name

First Name

Last Name

Last Name

Email

Username

Email

Email

Date of Birth

DOB

Mobile Number

Mobile

Status (Active/Deleted)

Status (Active/Inactive)

--

User Type: Fieldworker

--

Full-Time

employeeID

integration_id

 

Xero Contacts → Assignar Clients

***The Integration will pull Contacts from Xero when Contacts are created under (Contacts > All Contacts)***

Screenshot 2024-10-21 at 3.34.50 PM.png

  • The Xero Contacts that will be pulled from through the Integration are located under (Contacts), then (All Contacts). 
    • ***Unless the (Filter by Group) option is selected on the Workflow in Assignar. If the (Filter by Group) option is selected, then the Integration will only pull Contact records from the specific (Contact Group) or (Contact Groups) that you have created and selected. 

Configuration / Prerequisites:

  • By default only (Active Contacts) from Xero will sync to Assignar. 
  • Should you not want all of your (Active Contacts) from Xero to show up in Assignar, then you can choose to filter your (Contacts) based on the following conditions.
      • All Active Client - This filter will sync any Xero Contacts marked as Active to Assignar.
        • This would include any Customers and Suppliers
      • Active Clients with Active Projects - This filter will only sync (Active Contacts) when they are assigned to an (Active Project).
        • ***In order to use this filter, you must have the Projects add-on in Xero and have Project workflow enabled in Assignar.
      • Filter by Group - The last filter option is to filter your (Active Contacts) based on a pre-assigned (Contact Group). (Recommended)
        • If you wish to use the Filter by Group option, then you will need to create the (Contact Group) within Xero and assign that (Contact Group) to all (Active Contacts) that you wish to see within Assignar. 
          • A (Contact Group) can be created by going to (Contacts), then (All Contacts) then select the (Group) tab and click (+ New Group).
          • Once your new (Contact Group) has been created, you will need to assign the (Contact Group) to your (Active Contacts) that you wish to see within Assignar. 
            • This can be done by going to (Contacts) > (All Contacts) > then find the Contact(s) that you want, click the check box next to them, then click (Add to Group), select your new (Contact Group) and click (add).

 

Contacts / Client Key Data Fields

***(Do not update these fields within Assignar, Xero is the source of truth)***

Xero (Contact)

Assignar (Client)

Name

Client Name

ABN

ABN

Primary Person - Email

Email

Phone

Office

Mobile

Mobile

Street Address

Address

City/Town

Suburb

State/Region

State

Postal/Zip Code

Postcode

GUID

Integration_ID

 

Xero Project → Assignar Project

***The Integration will pull Projects from Xero when Projects are created under (Projects > All Projects > In Progress)***

Screenshot 2024-10-21 at 3.37.17 PM.png

  • This workflow will take Project records from Xero and create a copy in the Assignar platform as a Project. 
  • The Xero Projects that will be pulled through the Integration are located under (Projects), then (All Projects), then (In Progress).  

Configuration / Prerequisites:

  • ***If you wish to use the Projects Workflow, then you must have the Projects add-on in Xero.
  • ***Only "In Progress Projects" from Xero will sync to Assignar. 
  • ***If you plan to utilize the Tracking Category / Account Code workflow, then you will be required to (manually) assign the Account Codes to your Projects in Assignar, but the Project does not have to originate from Xero.

 

Project Key Data Fields

***(Do not update these fields within Assignar, Xero is the source of truth)***

Xero (Project)

Assignar (Project)

Project Contact

Client Name

Project Name

Project Name

Deadline

End Date

ID/GUID

Integration ID

 

 

Xero Tracking Category Options/Items → Assignar Account Codes

***The Integration will pull Tracking Category Options/Items from Xero when Tracking Category Options/Items are created under (Accounting > Advanced > Tracking Categories)***

 

Screenshot 2024-10-21 at 3.40.52 PM.png

  • This workflow will take Tracking Category Options/Items from Xero and create a copy as an Account Code in Assignar.
  • The Xero Tracking Category and Tracking Category Options that will be pulled through the Integration are located in Xero under (Accounting), then (Advanced), then (Tracking Categories).

Configuration / Prerequisites:

  • ***If you plan to utilize the Tracking Category / Account Code workflow, then you will be required to (manually) assign the Account Codes to your Projects in Assignar, but the Project does not have to originate from Xero.
    • Do not create Account Codes within Assignar as this will break the Workflow. 
  • Xero Tracking Category and Tracking Category Options can created in Xero by going to (Accounting), then (Advanced), then (Tracking Categories)

 

Tracking Category Options / Account Codes Key Data Fields

***(Do not update these fields within Assignar, Xero is the source of truth)***

Xero (Tracking Category Option/Item)

Assignar (Account Code)

Tracking Category Option

Account Code

Tracking Category Name

 Account Code + Account Code + Category Name

 
Below is a screenshot of the Tracking Category and Tracking Category Options in Xero on the left, and on the right you will see how they will will be mapped in Assignar.

Screenshot 2024-09-05 at 3.45.25 PM.png

 

 

Assignar Timesheets → Xero Timesheets

***The Integration will push Employee Timesheets from Assignar into Xero where they can be viewed under (Payroll ? Employee Management > Timesheets)***

Screenshot 2024-10-21 at 3.47.41 PM.png

 

Prerequisite / Key Information: 

  • ***The Timesheets workflow will only work on the newest version of Timesheets within Assignar.
    • If you are interested in the Timesheets workflow and an existing Assignar customer, please reach out to our Customer Support Team to confirm that you are on the newest version of Timesheets.
  • ***In order to use the Timesheets workflow the Employee/Worker Workflow must be enabled as it is a requirement of the Integration API.
    • ***If you plan to use the Timesheet Workflow, then any Payroll Employee that you wish to have time tracked against must have a (Payroll Calendar) assigned to the Payroll Employee in Xero.
  • ***If you plan to utilize the Tracking Category / Account Code workflow, then you will be required to (manually) assign the Account Codes to your Projects in Assignar, but the Project does not have to originate from Xero.
    • Do not create Account Codes within Assignar as this will break the Workflow. 

  • ***Time recorded in dockets and manually set pay rates are not supported.

  • ***Only (Approved Timesheets) from Assignar will sync to Xero.
  • ***All (Approved) Timesheets must be made with a Worker that was originally created in Xero and sent through the Integration into Assignar.
  • ***If you choose to create your own (Default Earnings Rate), this must be completed prior to the Timesheet Workflow being enabled. 
  • Once a Timesheet has been Approved and sent through the Integration into Xero, the Integration will then mark the Timesheet as (Processed) within Assignar so that you know that it has successfully been sent.
  • Once (Processed), Timesheets will not sync again, even if they are edited within Assignar.
  • ***NZ - The default earnings rate selected in the slide-out will be used for all synched time

 

Timesheet Configuration (No Overtime Rules Selected)

  • If you do not choose to use (Overtime Rules) within Assignar, then you will have the option to sync your Approved Timesheets manually or to be run on the Automatic sync.
    • The Automatic sync will run once per day at 12:00AM 7 days a week.
    • However, there is always the option to Manually sync your Timesheets for a faster sync that will enter the queue and start in 1 hour or less.
  • When configuring the Integration, we will need to select a (Default Earnings Rate)
    • The (Default Earnings Rate) filter is used when there is no (Default Earnings Rate) set up on the Payroll Employee within Xero.
      • You can use the default Xero (Earning Rates) 
      • Or you can create your own in Xero by going to (Payroll Settings), then (Pay Items), then (Earnings)
        • ***If you choose to create your own (Default Earnings Rate), this must be completed prior to the Timesheet Workflow being enabled. 
    • AU - If an employee does not have a default earnings rate assigned, we will use the one selected in the slide-out for all synched time
    • ***NZ - The default earnings rate selected in the slide-out will be used for all synched time
  • Lastly, any Timesheet that is Approved will be sent to Xero based on the (Payroll Calendar) that is set up on the Employee within Xero. 

 

Timesheet Configuration [Overtime Rules Selected]

  • ***If you choose to use (Overtime Rules) within Assignar, then you be required to Manually sync Timesheets from the Integration Hub due to the Integration API.
  • ***With (Overtime Rules) selected, the Integration can only support (Weekly) and (Fortnightly) (Pay Calendars)
    • If you would like to use the (Fortnightly) (Pay Calendar), you will be required to manually send 2 Timesheets, each for 1 week at a time. 
      • In Assignar you will be exporting 2 Timesheets each for 1 week, however once the Timesheets reach Xero, they will show up as 1 Timesheet.
  • ***If you choose to use (Overtime Rules) within Assignar, then you will be required to match the (Xero Pay Calendar) to start on the same day in both Xero and in Assignar otherwise Timesheets will fail to sync. 
  • ***If you choose to use (Overtime Rules) within Assignar, then you will be required to set up all Payroll Employees in Xero with the same (Payroll Calendar).
    • Example: (Weekly)

 

  • When configuring the Integration, we will need to select a (Regular Time Earning Rate) 
    • The (Regular Time Earning Rate) can be set to one the default Xero (Earning Rates)
      • Or you can create your own in Xero by going to (Payroll Settings), then (Pay Items), then (Earnings)
        • ***If you choose to create your own (Earnings Rate), this must be completed prior to the Timesheet Workflow being enabled. 
  • When configuring the Integration, we will need to select a (Overtime Earning Rate)
    • The (Overtime Earning Rate) can be set to one the default Xero (Earning Rates)
      • Or you can create your own in Xero by going to (Payroll Settings), then (Pay Items), then (Earnings)
        • ***If you choose to create your own (Earnings Rate), this must be completed prior to the Timesheet Workflow being enabled. 
      • Or your 3rd option would be to create your own (Overtime Earning Rate) within Assignar.
        • Xero Earning Rates can be mapped to Assignar Pay types (RT, OT, OT2)
        • If you have questions about (Overtime Rules) within Assignar, please reach out to our Customer Support Team. 

 

Timesheet / Timesheet Entries Key Data Fields

Assignar (Timesheet)

Xero (Timesheet Entries)

Employee

Employee

Pay Type

Earning Rate

Total Time

Time

Was this article helpful?

0 out of 0 found this helpful