Troubleshoot settings and Xero

Use this guide when you cannot save company settings, cannot open an administration screen, cannot connect the app to Xero, or a synchronisation appears stuck. Most settings and Xero controls are restricted to administrators, so ask an administrator to check the problem if the controls are unavailable.

Common problems

• The save does not complete: Check the values that you entered. Global Staff Breaks (hours) accepts values from 0 to 8, and Approvals Required accepts whole numbers from 1 to 5. A half-completed notification redirect is discarded when settings are saved; select both the manager and the delegate before saving.
• The page looks unchanged after saving: Select Save Settings and wait for the confirmation Settings saved successfully. If the confirmation does not appear, refresh the page and try again. If the problem continues, ask an administrator to check History.
• A person is missing from a selector: The available people depend on the setting. For example, quote recipients can be managers or administrators, sales KPI CC recipients can only be administrators, and default-manager choices come from staff. Check that the person has the expected staff role and is active.
• A notification list is empty: Some lists have a deliberate fallback. An empty agenda-recipient list notifies all active Foreman, Manager and Admin staff. An empty management KPI list falls back to active Manager and Admin staff. An empty sales KPI CC list falls back to active Admin staff. An empty quote-recipient list sends the message only to the quote owner.
• You cannot find a settings screen: From Company Settings, use Leave Types, Public Holidays, Role Permissions, Induction Types, Competency Types, or History. Xero controls are under Xero settings, including Sync logs.

Settings that cannot be changed

Company settings, leave types, public holidays, role permissions, and settings history are administrator-only areas. If you are a staff member, foreman, or manager and a control is missing or read-only, this is normally an access restriction rather than a fault.

An administrator can change the following company settings:

• Financial Year Start. The form notes that the New Zealand default is 1 April.
• Global Staff Breaks (hours), from 0 to 8 hours, in quarter-hour steps in the form.
• Default Manager for new jobs and integrations.
• Leave approvals, approvers, notification recipients, account managers, SQIF verifiers and notification recipients.
• Quote, meeting agenda, and KPI recipients.
• Redirect notifications on leave, including the manager and delegate for each redirect.

If an old value keeps returning, an administrator should review History. Each recorded change shows who made it and which fields changed. An administrator can use Revert to this to restore all settings to the point before a change, or Revert field to restore only one field. A revert is recorded as a new history entry; earlier entries are not deleted. Hidden values, such as a changed account key, cannot be reverted from the history screen.

Role and permission problems

Only an administrator can open Role Permissions, change access, or restore the default permissions. In that screen, selecting a permission cycles through Allow, View Only, and Deny. Some permissions are locked and cannot be changed for a role.

If you can open a page but cannot edit its information, the role may have View Only access. If the page is unavailable, the role may have Deny access. Ask an administrator to confirm the role assigned to your account and the access level for the relevant area.

The Role Permissions screen also controls two sensitive capabilities: View Financials (job costs, profit, quote prices, and timesheet totals) and View Wages (staff charge-out or hourly rates). These may be switched off even when a person can access other areas.

After an administrator changes permissions, sign out and back in if the old access still appears. If the problem remains, ask the administrator to save the permissions again and check whether the permission is locked.

Xero connection problems

Open Xero settings and check the Xero Connection card:

1. If it says Not Connected, select Connect to Xero and complete the Xero consent screens, making sure you choose the correct organisation.
2. If the card shows Connected, check the organisation name before starting a synchronisation.
3. To change the linked organisation, select Disconnect, then connect again and choose the new organisation. Existing staff links to the previous organisation may need to be cleared from each staff record before they can be created in the new organisation.

Common connection messages and next steps:

• Sign in expired: Sign in to the app again and retry.
• Permission denied: An administrator must give your account access to Xero settings.
• No Xero organisation: Repeat the connection and select an organisation on the consent screen.
• Xero rejected the request: Check the consent choice and retry. If it repeats, an administrator should investigate.
• Xero credentials missing, Server not configured, or Token exchange failed: These require administrator or system-configuration attention rather than a change in your settings.
• OAuth state mismatch: Retry in a clean browser tab. Blocked cookies, a cross-domain redirect, or a recently changed security setting can cause this message.

When a connection succeeds, reference information such as earning rates, payrun calendars, and leave types may begin synchronising in the background. Wait for those updates before checking whether the lists are current.

Syncs that fail or remain incomplete

Xero settings separates synchronisation into time sheets, employees, earning rates, and payrun calendars. Each area shows its item count and either a last-synchronised time or Never synced. A synchronisation button is unavailable while Xero is disconnected.

For employee synchronisation, active staff must have a date of birth and a complete home address containing line 1, city, and post code. Staff without those details are skipped rather than treated as successfully synchronised. Complete the missing staff details, then select Sync employees again.

If staff are marked as linked to a previous Xero organisation, time-sheet synchronisation skips them. Clear the old Xero link from each staff record, confirm that the correct organisation is connected, and synchronise again. Do not repeatedly retry before correcting the organisation link, because it may not create the employee in the organisation you expect.

Time-sheet synchronisation only considers approved labour that has not already been synchronised and is within the current or previous pay period. Older or unapproved entries therefore may not be included in a manual sync. After selecting Sync time sheets, the run is queued and the result is reported in the sync log; the number shown when starting is the number selected for processing, not a guarantee that every item succeeded.

A run can finish as success, partial, or failure. A partial result means that at least some items were processed but one or more were skipped or failed. Open the run details to distinguish missing information from a Xero rejection. Correct the listed records and retry only the affected work where possible.

If the status is in_progress, leave the page open briefly or return to the logs later. The detail page updates automatically, and it is safe to leave it while the run continues.

How to use sync logs

Select Sync logs from Xero settings. The list shows the time, operation, status, counts for Synced, Skipped, and Failed, duration, and who started the run. The list keeps the most recent 100 entries on this screen, and older activity is automatically removed after 90 days.

Select View beside a run to see its details:

• Total is the number of items considered.
• Synced is the number completed successfully.
• Skipped identifies items that could not be processed because they did not meet the required conditions; read the reason shown for each item.
• Failed identifies items rejected or otherwise unsuccessful; read the individual reason and any Run-level error.
• Expand the Skipped or Failed sections first. Successful records are grouped under Synced and are collapsed initially.

For an active run, the page displays “Sync in progress…” and shows how many items have been processed. If the totals do not change after a reasonable wait, return to Sync logs, open the same run again, and check whether it has changed to success, partial, or failure. Record the operation, time, status, and displayed reason before asking for help.

If the log says No sync activity yet. Trigger a sync from the Xero settings page to see logs here, confirm that you are looking at the correct Xero organisation and that you have started at least one synchronisation.

When to contact an administrator

Contact an administrator when:

• you need access to company settings, Role Permissions, Xero settings, or Sync logs;
• a setting is outside the allowed range or continues reverting after a successful save;
• the correct staff role, active status, address, or date of birth cannot be updated;
• Xero shows Permission denied, Xero credentials missing, Server not configured, Token exchange failed, or Database write failed;
• staff remain linked to a previous Xero organisation after the organisation has been changed;
• a sync remains in_progress without changing, or repeatedly ends in failure;
• a run has failed records that remain after correcting the details.

Include the Xero organisation name, the operation you started, the approximate time, the sync status, and the reason shown after selecting View. Do not send passwords, private account keys, or other confidential credentials in a support message.