Help centre

How DocketBridge matches dockets to Xero invoices

DocketBridge attaches a docket only when a Xero invoice and a ServiceM8 job match on number and total. If anything does not line up, it skips that invoice and nothing is attached.

Each check, step by step

  1. Read recent invoices. DocketBridge reads your sales invoices in Xero, newest changes first. Every check reads the first page Xero returns, your 100 most recently updated invoices. After a pause, an ended trial, a payment problem or an outage it also catches up on invoices updated since its last check, and it checks any invoice queued to be checked again. See which invoices are checked again. Supplier bills are never read. It does not filter by invoice status, so draft, awaiting payment and paid invoices are all checked.
  2. Check the invoice number. Invoices with no invoice number, or with an apostrophe in the number, are skipped.
  3. Find the job. The Xero invoice number must be exactly the same as the ServiceM8 job number. Invoice 1001 matches job 1001, but invoice INV-1001 does not. Exactly one ServiceM8 job must have that number. If none does, the invoice is skipped and not listed, because most Xero invoices that did not come from ServiceM8 have no job. If more than one does, it is skipped and Recent activity shows "Skipped: job number used more than once".
  4. Apply your client rule. An invoice for a client your rule leaves out shows as "Skipped: client rule". See client rules.
  5. Compare the totals. The Xero invoice total and the ServiceM8 job total must agree to within 4 cents. A difference of 6 cents or more never matches. A job with no total counts as zero. If they do not agree, Recent activity shows "Skipped: totals differ" with both totals.
  6. Find the dockets. Completed forms on that job that have a PDF, limited to the forms you ticked. See choose forms.
  7. Check what is already there. Dockets DocketBridge has already handled for this invoice are left alone. If a file with the same name is already on the invoice, the docket is recorded as "Already on the invoice" (skipped_exists) and not uploaded.
  8. Attach. The PDF passes from ServiceM8 to Xero through memory and is never stored. It is attached with "Include with online invoice" ticked, so it goes out when you email the invoice from Xero.

Timing

DocketBridge does not react to events in ServiceM8 or Xero. It checks every 5 minutes, plus the time the previous check took, so a docket is attached on the next check after its form PDF and its Xero invoice both exist. Run once now on your dashboard checks straight away. If you email invoices as soon as they sync, press Run once now first, or check Recent activity shows Attached for that invoice.

Checks of one account never overlap. If Run once now is pressed while a scheduled check is running, it waits a few seconds and otherwise says "A check is already running. Refresh in a minute to see the result.", so the same docket is never uploaded twice.

Which invoices are checked again

  • Your most recent invoices, every check. Every check looks at your 100 most recently updated invoices again, not just new ones. So a docket completed after its invoice synced to Xero is still attached on a later check while the invoice is among them.
  • Catching up. When more invoices were updated in Xero since the last successful check than that first page holds, for example after a pause, an ended trial, a failed payment or an outage, DocketBridge also reads the invoices updated since that check, oldest first. It takes up to 50 of them a check and goes back up to 90 days, so a long gap can take a few checks to catch up. With no finished check to start from (for example when no check has ever finished for your account), it starts with your 100 most recently updated invoices instead.
  • Invoices queued to be checked again. Pressing Attach again or Check again in Recent activity, saving new client rules, or an upload that failed while catching up queues the invoice. Queued invoices are checked at the next check wherever they are in Xero, up to 25 a check. They wait for that check however long it takes, for example while paused or until you subscribe, and one that keeps failing is tried up to 6 times.
  • Any other invoice is not looked at again unless it is updated in Xero. For example, a docket completed during a pause for an invoice that did not change in Xero is only picked up while that invoice is among your 100 most recently updated invoices. Catching up can also attach dockets to invoices up to 90 days old, which you may already have emailed.

Changes after an invoice syncs

  • If someone edits the invoice in Xero so the totals no longer agree, DocketBridge skips it and shows "Skipped: totals differ". It attaches the docket automatically once the totals agree again. Editing the invoice in Xero updates it, so it is checked again. After fixing the ServiceM8 side, press Check again.
  • If Xero has other invoices with the same number from another source, each is checked on its own. Each still needs exactly one matching ServiceM8 job and totals within 4 cents.

Never attached twice

Each ServiceM8 docket is attached to a given Xero invoice at most once. If someone deletes an attached docket from the Xero invoice, DocketBridge does not attach it again by itself, and an Attached row has no Attach again button. Attach it by hand in Xero if you need it back. Attach again is for dockets that did not attach: "Not attached" and "Already on the invoice" results. See Attach again.

What you check

DocketBridge saves the download, drag and tick for each docket, but you remain responsible for checking invoices and attachments before you send them.

Still need help?

Email laurits@specializedcg.com.au. DocketBridge is supported by its developer, not by ServiceM8 or Xero, so please contact us rather than ServiceM8 or Xero support. If it is about a docket, include the invoice number.