Connect Xero

The Account›Integrations tab connects your workspace to Xero. It can export invoices and finalised payroll amounts into draft Xero records and reconcile invoice settlement history. The provider owner sees the tab and needs Settings edit access to connect, disconnect or save payroll mappings.

Connect the organisation

1. Check Xero is on under Workspace features. When off, the connection row reads Xero is turned off in Features.
2. Open Account > Integrations and select Connect to Xero beside Not connected.
3. Complete Xero sign-in and approve access for the intended organisation in the tab that opens. If you can access several organisations, check which organisation you authorise.
4. Return to OneForce Care. The connected confirmation explains automatic new-invoice export and the restricted manual export of existing unpaid invoices. It confirms success and the row shows Connected and Disconnect. Refresh another open tab if its state has not updated.

If connection fails, the app shows Xero connection failed. Try again, or check the Xero app configuration. Correct the cause before retrying.

Enlarge screenshot

Swipe across the enlarged image to read each part of the screen.

View full-size screenshot

Invoice exports

Invoice sales account and GST choices are worked out from the connected organisation. There is no invoice account or GST mapping form here. New invoice exports create draft invoices. Credits against an unchanged unpaid draft adjust that draft; Authorised or Paid originals use a separate draft credit note. Existing local credits are not exported as historical documents. Review these in Xero before authorising them. Retry failed batch exports from Invoicing.

Set payroll pay-item mappings

With Xero connected, a Xero connection checks table checks Billing and invoicing and Payroll independently. Read Ready, Off or Needs attention and What to fix for each. A working invoice connection does not prove payroll access is ready.

When Payroll is Ready, select its row or Payroll pay item mappings arrow to open the Payroll pay item mappings drawer. You need Settings edit access to save.

For each pay item, choose the matching compatible Xero item. Exact name matches are selected automatically. An unselected item shows Select a Xero pay item, and a group without compatible items says No compatible Xero pay items available. Select Save payroll mappings; success shows Xero payroll mappings saved.

Mapping group	Items
Ordinary and shift hours	Ordinary hours, Afternoon shift, Night shift, Saturday, Sunday and Public holiday
Overtime	Overtime, first period; Overtime, after first period; Public holiday overtime; Rest break overtime; Broken shift beyond 12 hours
Allowances	Vehicle allowance, Sleepover allowance and Broken shift allowance

Use active Rate per unit worked earnings items for hours and Fixed amount allowance items for allowances. Public holiday overtime has its own mapping; mapping Public holiday alone does not cover it. Review each item’s tax, super and leave treatment in Xero. Manual payroll items match their description to a Xero pay item, so check those descriptions too.

Prepare a draft payroll export

Before using Push payroll to Xero from Payroll:

• Match the workers to their Xero employees.
• Use a Monday-start weekly or fortnightly employee payroll calendar.
• Create one draft Xero pay run covering the period, with employee payslips ready.
• Finalise every included OneForce week. A fortnightly pay run needs both weeks finalised.
• Clear or reconcile earnings for the same mapped items already present on the draft payslips. Existing earnings or timesheets can block the export to prevent duplicate pay.

The export uses the finalised snapshot’s hours, rates and allowance dollars, including manual items. Later rate edits do not recalculate that frozen week. Different rates on one mapped item, rounding differences or negative adjustments can block export and need review.

OneForce Care attempts an automatic export after finalisation when the integration is ready. If export fails, the week remains finalised; fix the stated problem and retry Push payroll to Xero. A missing payroll-access message can require disconnecting and reconnecting Xero to renew consent.

Disconnect or pause

Select Disconnect, read Disconnect Xero?, then confirm Disconnect Xero to unlink it. Success shows Xero disconnected. and the row returns to Not connected. To pause its actions while keeping the connection, turn off Account > Features > Integrations > Xero instead.

Check the first connected invoice

New eligible invoices generated after connection can export automatically in the background. Existing historical invoices require a deliberate row-cloud action in Finance > Invoicing and must be fully unpaid with no payment or credit history. Older receipts and credits remain locally managed. Read the row’s restriction instead of expecting connection to migrate historical accounts.

After an invoice is admitted for Xero export, record its cash in Xero and use Sync to Xero to reconcile here. For a linked invoice correction, follow Create a credit and correct an invoice so the issued local history and Xero correction stay traceable.

Read the connection row before acting

Not connected means the OneForce workspace has no active connection; it does not describe whether an individual invoice is paid. Connected means the connection exists, while the separate connection checks determine whether Billing and Payroll can perform their own work. Keep the organisation used for existing linked invoices when renewing access.

For payroll mappings, choose the item by its purpose and compatible type, not just a similar name. An ordinary-hours mapping does not cover vehicle allowance or public-holiday overtime. Save the mappings, then review the prepared draft payslip and export result for the intended worker and period. Do not create a second earnings item or a second pay run merely because the first export is pending or reported a specific blocker.