Automations
An automation is a Flow routine that moves Flow's own records on. Each one is
on or off and has its own settings. No other system's status is part of a
Flow stage: an automation reads that status and changes the Flow stage. The
code is in server/core/automations.js. An organisation's choices are in the
automations table, and at /api/invoicing/automations.
flowchart LR ws[Work system status] -- Mark ready to invoice --> ready[Flow: ready to invoice] person[A person on the Jobs board] --> ready ready -- Draft when ready --> draft[Flow draft invoice] draft -- Ready when drafted --> send[Invoices: Ready] draft --> rules[docs/INVOICING_RULES.md]
The pipeline (server/core/pipeline.js) runs the automations that are on
after it reads the integrations and runs the matcher, every two minutes.
| Automation | Key | Shown on | Default | Does |
|---|---|---|---|---|
| Add new clients | add_contacts |
The Seazona integration page | On | Makes a Flow contact for each work system client no contact is named like, and links it (docs/CONTACTS.md, "New clients"). Runs before the jobs are read, so they find their customer |
| Add Xero clients | add_xero_contacts |
The Xero integration page, Contacts | Off | Makes a Flow contact for each active Xero client no contact is named like, and links it (docs/CONTACTS.md, "Xero clients"). A Xero supplier only is left out |
| Two-way edits | sync_contact_edits |
The Xero integration page, Contacts | Off | A contact edit in Flow reaches the linked Xero contact, and one in Xero reaches Flow. A field changed on both sides waits for a person (docs/CONTACTS.md, "Two-way edits"). Runs on the Xero worker, not the pipeline |
| Mark ready to invoice | mark_ready_from_work_status |
The Seazona integration page | On; statuses shipped, delivered | Marks a job in work ready to invoice when its work system status is one of the chosen statuses, in any case |
| Draft when ready | draft_when_ready |
Settings, Automations | On | Drafts the invoice of each ready job that passes the invoicing rules. A job whose work system report is over two hours old is read again first (issue #141); one that cannot be read waits. Xero's latest changes are read once before the first draft (issue #45); when that read cannot run, nothing is drafted. With no accounting integration, Flow's own records are the check |
| Reference from the rule | reference_from_rule |
Settings, Automations | On | Gives each draft made from a job the Reference from the Reference rule (docs/INVOICING_RULES.md, "Reference"). A Reference a person typed stays. The draft's status does not change |
| Ready when drafted | ready_when_drafted |
Settings, Automations | On | Puts each draft that "Draft when ready" made in Ready on the Invoices page, so "Send all ready" sends it. A draft a person changed or moved back to Drafts stays with people. A draft with a problem shows in Problem |
Each automation shows on the screen of the data that triggers it (place).
The ready statuses are picked from a menu, not typed. The menu lists each
status the work system has reported for the lab's jobs, with the number of
jobs at each (GET /api/invoicing/work-statuses). Each lab's Seazona can use
its own statuses, so the menu follows the lab's data. A status picked earlier
stays in the menu when no job has it now.
People decide first
- A person can mark a job ready, or put it back in work, at
POST /api/invoicing/jobs/:id/ready. A job with an invoice cannot go back in work. - When a person puts a job back in work, "Mark ready to invoice" leaves that job alone from then on. A person marks it ready again.
- Each change is an event on the job (
ready,in_work) with its actor:person:<id>orautomation:<key>.
Later
Two-way stages: when a person moves a job in Flow, Flow sets the matching status in the work system. Seazona cannot change a job's status by its API yet, so this waits on Seazona.