Invoice tabs and Send all ready

The Invoices page has seven tabs, left to right: Pending, Ready, Draft, Approved, Sent, Non-chargeable and Void. Earlier names: Problem is now Pending, Drafts is gone (a clean draft is Ready), and Finalised is split into Draft, Approved and Sent. Code: server/core/sending.js, server/api/invoicing.js (invoiceTabs) and server/integrations/xero/reconcile.js (stageOf).

The list starts with Number, Client, Reference, Date, Total, Status and Linked. + at the end of the head adds more: Due (the invoice's due date), the invoice's job's Case, Practitioner and Shipped date, and each custom field (the job's value, docs/CUSTOM_FIELDS.md). The columns, their order and widths stay with the person's account (docs/DESIGN.md, Columns).

A Ready invoice can go to the accounting system at any time. It then moves to Draft, the lowest stage Xero takes. Draft, Approved and Sent follow Xero's own status and its SentToContact flag, read from Flow's copy of Xero (no extra Xero calls). An invoice in that copy from before the sent_to_contact column (Xero migration 0009) shows as Approved until Xero changes it and Flow reads it again.

Ready #

A draft with no problem is in Ready. A saved change keeps it there while the checks pass. A draft with a problem is in Pending until the problem is fixed; then it goes to Ready by itself. There is no half-made Flow draft: every invoice before it is sent is Pending (a check fails) or Ready (every check passes). Draft is the accounting system's word for an invoice it holds.

On the invoice the buttons are, left to right, Delete (a draft that was never issued; an owner or admin), Preview, Save, then Send to Xero (accounting system on) or Approve (no accounting system). A Pending draft has no send button. Delete asks first, removes the draft, and frees its job: the lab's rules then decide whether Flow drafts it again. The result stays until the person closes it. An issued invoice whose accounting copy is a draft also has Delete (owner or admin), before Void. The confirm says Also deletes the draft in Xero. Flow reads that invoice live, deletes it there while it is still a draft, then voids it in Flow. The issued versions stay, and the job is freed the same way. Delete is hidden when the copy says Approved or Paid. With no accounting system, Delete of an issued invoice, including one opened to revise, is refused and the invoice stays as it is.

The Problem banner gives the first sentence of each problem: what is wrong. The field the failed check reads glows red, like a required field (fieldError, problem.fields): a rule on the Reference marks the Reference box, a line with no price item marks its item. Typing in the field clears the red.

Save is the check, like CI: it saves, and Flow runs every check again (its own, the lab's rules, the accounting system's). A Pending invoice that now passes moves to Ready: a toast says so and the next invoice of the list opens. One that still fails stays Pending, with the toast giving the problem and its red fields. While the draft's job changed after it was made (below), send and Approve are off: fix the job at its source, or accept the change.

Bulk bar #

Ticking rows on any tab of the Invoices list brings up the bulk bar (server/ui/bulk-bar.js). It floats at the foot of the page, and the tabs, search stay at the top while the rows scroll under them. The bar shows N selected × (× or Esc clears the ticks), then the tab's actions in groups, then More, a searchable menu of every action plus Tick all shown, Invert ticks and Clear ticks. An icon-only action shows its name on hover.

Checks #

Flow checks its own data first. The Problem column shows a short fact for each failed check; the full text is its hover title.

When an accounting system is on and connected, its own checks are added (checkDrafts). For Xero these come from Flow's copy of Xero, so they cost no Xero calls: the customer matches one Xero contact (Client not in Xero, Client twice in Xero), and every item is in Xero (CODE not in Xero). With Create missing clients on, Client not in Xero offers Create, which adds the client in Xero from the Flow contact (docs/CONTACTS.md). With it off, add the client in Xero, then sync. Owners and admins see Create. Staff see the flag.

An issued invoice that the accounting system refused is in Pending (Send failed). It shows the refusal until a person sends it again.

Send all ready #

On the Ready tab, an owner or admin ticks the rows (the head tick takes every row shown), then presses Send to Xero (or Approve) in the bulk bar. It asks first. There is no separate send bar. Then:

1. Flow stops before it issues anything when the accounting system is on but not connected, or does not take writes (XERO_ALLOW_LIVE_WRITES).
2. Read before act (issue #141): the job behind each ready draft whose work system report is over two hours old is read again from the work system, one call per job, at most 20 a press. A job that changed after its draft, or that the work system deleted or no longer bills, goes to review and its draft to Pending. A draft whose job could not be read waits for the next press (waiting in the answer). Jobs past the 20-read cap are not read on this press; they count in waiting too. Then the accounting system reads its latest changes (issue #45, see XERO.md). When that read cannot run, nothing is issued and every draft in the press waits. A ticked press, including a bulk press, answers not_ready and names the cause (for example "the accounting copy has more changes than one read takes"): that one read covers them all. Send on one invoice is all or nothing: if that job cannot be confirmed, nothing is sent (not_ready), and the answer names the cause and the count (for example "1 job could not be read from the work system"). A bulk press (more than one ticked invoice) sends the ones Flow confirmed. The rest stay in Ready, or move to Pending when the job went to review, and the toast names how many could not be confirmed. When a bulk press confirms none, it answers not_ready with that count (for example "3 jobs could not be read from the work system"). A danger toast for a stopped press stays until the person closes it. Every draft check then runs again, the lab's pending rules and skip rules (INVOICE_RULES.md) included. A draft that fails one now stays on Pending and is not sent. When a person ticked drafts, the rest go and the answer counts the ones held (held); when every ticked draft fails, nothing is sent and the answer names the first problem.
3. Each ready draft is issued and gets its number. One press takes up to 100 drafts; the rest wait for the next press.
4. Each issued invoice is queued for the accounting system, and shows in Draft with the status Sending.
5. The send worker sends the queue in the background, every 30 seconds, on the job queue. For Xero, each invoice goes as a Xero draft by default; the customer's send mode can make it an approved invoice that Xero emails.
6. A sent invoice leaves the queue. A refused invoice moves to Pending. The send worker reports that refusal once: how many, each invoice's number and id (five at most), and the accounting system's code and short message. The report has no customer name and no email address. An invoice that waits for Xero's call limits stays queued.
7. With an integration on, every tab has a Linked column: one icon for each connected system (Seazona, Xero), never one column per system. A dot gives the state of this invoice's link: green linked and in step, amber not in Xero yet, red out of step with Xero. A dashed grey icon means no link. The Xero icon shows on issued and void invoices; its title gives Xero's number and state. An icon with a link opens the record there.
8. One invoice's page has a Linked card with the same systems: the work system row gives the order number, the accounting row gives Xero's number and state, and each has Open. A separate Xero card shows only when Xero differs from what Flow sent.

With no accounting system on, the button is Approve all N ready: it issues the ready drafts only, and they go to Approved.

One ready invoice has its own Send to Xero button (Send to Xero and email when the customer's send mode is approve and email). It does the same steps for that invoice only. With no accounting system on, Approve gives the invoice the next number and locks it, and sends nothing. It is greyed until the invoice has a client and a due date, and while the draft's job change is open.

New invoice from a job #

A new invoice can start blank or from a job. From a job, in the page header, lists the jobs with no invoice yet (client, practitioner, shipped date, total), with a search. Picking one makes its draft the way the invoicing rules do (POST /api/invoicing/jobs/:id/draft): the client, the Reference from the Reference rule, and the job's lines, linked to the job. A job the rules refuse is not drafted, and the toast names the reason. An invoice with no job stays allowed.

After a send, the next invoice of the list opens. The count in the bar holds (1 of 35, then 2 of 35): the sent invoice stays in the bar's list until the person goes back. Previous opens it again, issued, with a greyed Sent to Xero button: an invoice that is queued, sent, or found in Xero cannot be sent twice. Back reloads the list, where the sent invoice is under Draft. After the last invoice of the list, the list opens.

Approve, and a Save that makes a Pending invoice Ready, open the next invoice of the list too, so a person reviews invoices one after another without going back. Accept change stays on the invoice, to show the result. An invoice opened from somewhere else (the job board, search, a link) steps through its own tab.

Records #

invoices.send_state is queued, sent or failed (null when the invoice was never queued). send_error holds { code, message } while failed. Revising an issued invoice clears both. xero_invoices.sent_to_contact holds Xero's SentToContact flag.

API #

• GET /api/invoicing/invoices?status=pending|ready|draft|approved|sent|void lists a tab. The old names problem, to_check and issued still work. Each invoice carries tab, sending and problems. counts has one number per tab. The list is one page: offset and limit (default 200, at most 500) cut it, filter (the Filter chip's view as JSON, the rules of server/ui/job-view.js), sort (number, client, reference, date, total) with dir (asc or desc) and today (the person's day, for date filters) run over every invoice of the tab first. The answer has total and totalCents of every match and clients (the tab's clients, for the Filter's choices). One invoice (GET /invoices/:id) carries the same tab, view (problem or ready, for a draft) and problems, and, for a draft, sendsTo and sendMode (this customer's mode, and whether the accounting system is connected and takes writes).
• POST /api/invoicing/invoices/mark-ready and mark-not-ready stay for older pages; they no longer change the tab.
• POST /api/invoicing/invoices/send-ready { issueDate, invoiceIds? }: with invoiceIds, only those drafts. One id is all or nothing (not_ready when it is not ready, or its job cannot be confirmed; the message names the cause). More than one id sends the ones that are ready and confirmed; held counts drafts that failed a check, and waiting counts jobs that could not be confirmed. When none can go, the answer is not_ready and names the cause and the count.
• POST /api/invoicing/invoices/send-again { invoiceIds? }.
• DELETE /api/invoicing/invoices/:id (owner or admin) removes a draft that was never issued (status draft and issuedVersion 0). Its job's billing obligation is freed, so the job is ready again and the lab's rules decide whether to draft it. An invoice that was issued is deleted only when its accounting adapter deletes the draft there, or reports it already gone: Flow then voids the invoice (the issued versions stay) and frees the job. Approved or paid answers accounting_approved (Approved in Xero. Void it in Xero first. when the adapter is Xero) and changes nothing. Not connected or writes off answers accounting_not_connected or accounting_writes_off, and changes nothing. With no accounting system, or when a connected adapter cannot delete it, the answer is accounting_unavailable and the invoice stays as it is. A timeout leaves the invoice as it was.
• POST /api/invoicing/jobs/:id/use-new-lines { accept? }: the draft takes the work system's lines. With accept: true it also replaces lines changed in both places, while the invoice is not sent.
• POST /api/invoicing/jobs/:id/recheck: reads this one job from the work system now (at most once per job every 10 seconds), runs the checks again, and answers the invoice.

The job changed after the draft was made #

When the work system's job changes after Flow made its draft (docs/DATA_SPINE.md, three-way compare), the draft is in Pending and the invoice page shows a banner: one row for each changed fact (client, a line's item, description, quantity or price, an added or removed line, and the total), with what it Was when the draft was made and what it is Now in the work system. Flow never writes to the work system.

A fix made in the work system closes the problem when Flow next reads the job.

The Jobs page shows the same review. Each problem a job must fix is a chip beside its stage, such as Job changed, so the panel keeps one layout with or without a fix. A chip is a toggle. A click opens the panel's sidecar on the right (in place of Activity) on its Fix tab, for that problem, and shows the chip pressed; a second click closes the sidecar. For Job changed the tab has this banner and its buttons, so a person checks and accepts the change without leaving the job. For another problem it says what is wrong, what to do, and has one button to the place to fix it. The sidecar has tabs (Activity, Fix) and closes with ×; closed, the job's details take the full width. The panel icon at the top reopens it.

The job and its draft hold one fact: the job is in review. Flow stores it once (the job's hold, and one open review item for each job; a second report updates that item). The panel shows it once: the draft's copy of the hold (job_review) is left out, as on the invoice page. Accept change, a recheck that matches, or a fix in the work system clears the hold and closes the item.