Invoices, Advances and MYOB

These jobs move money records between the web app and MYOB and keep the accounts screens honest. Nothing here creates a new invoice out of thin air: invoices and advances are created by staff or by job progress, and these jobs push them to MYOB, pull payment information back and tidy the statuses. All times are Brisbane time. For the full timetable see the Scheduled Tasks Overview.

Invoice statuses are the ones on the Invoices screens: Suggested, Pending, Sent, Paid and Hidden. Advance statuses are Suggested, Pending, Approved, Invoice Returned and Paid (see Advances).

The MYOB user

Every MYOB call is made as the one web app user whose account is connected to MYOB (see Settings > MYOB). If that connection is broken, every job on this page silently does nothing or logs an error, and invoices pile up in Pending.

Customer invoices

Approve scheduled invoices (invoice:approve)

• Runs: daily at 07:00.
• Selects: invoices whose Invoice On date is today, that are not yet in MYOB, are not marked “exclude from MYOB”, and belong to a job that is not Cancelled.
• Changes: creates each invoice in MYOB and records the MYOB invoice number and approval time on the invoice. From the customer’s point of view this is the moment the invoice is issued.
• Where to see it: Scheduled Invoices shows what is queued for future dates; once approved the invoice moves to the sent list and shows a MYOB number.

Resend pending invoices to MYOB (resend:pending:invoices)

• Runs: daily at 03:00.
• Selects: invoices in Pending status on non-cancelled jobs that have no MYOB number and are not excluded from MYOB. These are invoices that should have gone to MYOB but did not (a connection failure, for example).
• Changes: clears any stale MYOB reference and approval time, then re-creates each invoice in MYOB one at a time. Failures are logged and retried the next night.
• Where to see it: Pending Invoices. An invoice that sits in Pending for several days is a sign the MYOB push keeps failing; check Settings > Log Viewer.

Mark invoices paid from MYOB (myob:paid:invoices)

• Runs: hourly.
• Selects: two sets from MYOB:
  1. Closed MYOB invoices dated within the last two years that have a payment date. Any matching web app invoice (by MYOB number) on a non-cancelled job that is not already Paid is marked Paid with MYOB’s last payment date.
  2. Open MYOB invoices where the balance due differs from the total (partly paid). The matching web app invoice is split: the original is marked Paid for the amount received, with “ prt1” added to its PO number, and a new Pending invoice called “Invoice Split Automatically” is created for the remaining balance (PO number “ prt2”, excluded from MYOB so it is not sent twice). Further part payments split again.
• Changes: invoice status, paid date, price and PO number as above.
• Where to see it: Invoices and the job’s invoices tab. A Paid deposit is also what stops the pending deposit reminder and feeds the deposits paid summary.
• Background: ROCH-1564 (mark paid from MYOB) and ROCH-1567 (split part payments).

Unpaid jobs email to PMs (unpaid_job_check)

• Runs: Mondays at 08:00.
• Selects: jobs completed more than two weeks ago that still have an invoice not in Paid status.
• Sends: each PM gets “Rochele: N Unpaid Jobs” listing their affected jobs with addresses and invoice details so they can follow up the customer.
• Changes: nothing.

Repayment plan report (send:repayment-plan)

• Runs: monthly, midnight at the start of the 1st, covering the previous calendar month.
• Selects: jobs whose accepted proposal had a repayment plan or maintenance plan selected, and that had at least one invoice approved last month.
• Sends: “Repayment Plan Report” to the Repayment Plan Report group in CC Emails, listing the jobs and the invoices approved in the month so the accounts team can reconcile plan instalments. Nothing is sent if there were none.
• Background: ROCH-350. The plan forecast charts are described under Dashboard metrics.

Tradesperson advances and small jobs

Send pending advances to MYOB (send:pending:advances)

• Runs: daily at 03:30.
• Selects: advances in Pending status that have no MYOB reference and whose tradesperson invoice has status Uploaded (the tradesperson has supplied their invoice through the app).
• Changes: creates each advance in MYOB as a Spend Money transaction against the tradesperson’s supplier card and records the MYOB reference. If a push fails, the failure is logged and an alert email goes to the developer so the tradesperson is not left unpaid (ROCH-1932).
• Where to see it: Pending Advances and Advances Sent.

Auto-complete small jobs (send:auto-advance-invoice)

• Runs: daily at 07:30.
• Selects: sub jobs on In Progress jobs where both the job and the sub job are priced at $3,000 or less, in two groups:
  • Sub jobs that started on the Monday of last week: the tradesperson is warned.
  • Sub jobs that started on the Monday of two weeks ago and are still In Progress: the job is auto-completed.
• Sends:
  • Warning: “Job #REF - Submit Progress Photos Before Auto-Invoicing” to the tradesperson, saying the job will be invoiced automatically next week unless they submit a progress photos report from the trades app.
  • Auto-complete: the customer receives the standard “Thank you for choosing Rochele Painting. Please tell us how we performed.” feedback email; the PM (or service inbox) and customer receive the normal sub job completed notices; the tradesperson receives “Job #REF - Auto Completed”.
• Changes (auto-complete): creates a progress report at 100% with the note “Auto-completed by system”, sets the sub job to Completed at 100%, updates the job’s completion percentage and feedback sent date, and fires the same completion flow a real 100% report would (which raises the suggested advance for the tradesperson).
• Where to see it: the report appears in the job’s reports and Report Gallery; the advance appears in Suggested Advances.
• Gotcha: the selection uses exact Monday dates. A sub job that started mid-week is picked up when its start date equals the Monday being checked, so in practice only sub jobs that started on a Monday are handled by this job.

MYOB connection and reference data

Refresh MYOB connection (myob:refreshToken)

• Runs: every 15 minutes.
• Changes: exchanges the stored MYOB refresh token for a fresh access token for every connected MYOB account and saves it. Output is appended to a dedicated log file, visible in the Log Viewer, so connection problems can be traced.
• Where to see it: Settings > MYOB. If this job fails repeatedly the connection expires and the other MYOB jobs stop working until someone reconnects.

Refresh MYOB tax codes (hydrate:myob:taxcodes)

• Runs: daily at 23:50.
• Changes: downloads the tax code list from MYOB and updates the local copy (code, description and MYOB identifier). The codes are used when invoices and bills are created.
• Where to see it: the tax codes page under Settings > MYOB.

Reporting data

Refresh dashboard statistics (update:quoteJobStats)

• Runs: daily at 23:00.
• Selects: quotes updated today, and quotes whose job or variations were updated today.
• Changes: rewrites the statistics rows used by the dashboard charts: one row per quote (using its conversion price), one per job (using the job price) and one per customer-facing variation, each tagged with estimator, PM, quote type, source and a region worked out from the postcode (45xx Sunshine Coast, 42xx Gold Coast, everything else Brisbane). Rows for quotes, jobs and variations deleted today, and jobs cancelled today, are removed.
• Where to see it: Dashboard metrics, the sales, report and repayment plan stats pages, and KPI. Because this runs at night, figures on those screens are as of the previous evening.

Tips and gotchas

• An invoice that must not go to MYOB (for example a manual adjustment) needs the exclude from MYOB flag, otherwise the 03:00 job keeps trying to send it.
• Marking an invoice paid by hand in the web app is safe; the hourly job only touches invoices that are not already Paid.
• When MYOB shows a part payment, expect to see two invoices on the job the next hour: the paid part and an automatically created Pending remainder.
• Scheduled invoices are approved at 07:00 on their Invoice On date. To hold one back, change the date before then (ROCH-1507 and ROCH-1573 covered clean-ups of the scheduled list).