Docs · Automating

Workflows

What Mosaic does about what it finds — a workflow drawn once as nodes and wires, started by a check, a schedule, a call or by hand.

A Check tells you that Store 014's sales did not reach the ERP last night. A workflow is what happens next, drawn once so nobody has to do it by hand: send the batch again, restart the job, mail the store, post in the channel.

Something done the same way each time, drawn once as a workflow: mail the team when a check finds differences, copy the export to a share every morning, install a store's machines when you press Execute.

This is also where Mosaic's line on reading sits. A Check only reads. Its data sources go through a read-only connection, and nothing in a Check can change a system. Mosaic changes something only through a workflow an administrator built, and the workflow does the steps that were drawn and nothing else.

Workflows is in the sidebar. It drills into New workflow, Import workflow, Your workflows — a green dot beside each one that is active — and Executions, every run of every workflow.

#Who can do what

A viewer opening a workflow is told "You can read this workflow and its runs; an administrator can change and run it."

Workflows are the one place where running is not a viewer's right. Running a Check reads; running a workflow may act. That is why it is an administrator's, like a trigger.

#Starting one

New workflow offers a name and somewhere to start:

A template is an ordinary workflow once it is made. Change any of it.

A check's tree also has a Workflows group, listing the workflows its runs start and the ones its rows can be sent to, with Add a workflow.

#The canvas

A workflow is nodes joined by wires, read left to right. The first node is the trigger, which starts the run. Each node after it is handed items — a run, a row, a file, a store — does its work on each, and hands items on down its wires. The count on a wire is how many items went along it last time.

• Drag from a node's right edge to wire it to another.
• Tab adds a node; Delete removes what is selected.
• The + on a wire puts a node in the middle of it.
• Add a sticky note writes a note on the canvas, in Markdown, for whoever reads it next.
• Tidy up lays the nodes out again; Fit to view brings them all on screen; Undo and Redo do what they say.
• Ctrl+S saves, as it does on every screen that has a Save button. Ctrl+E executes.

Some wires are refused, and the canvas says why. A node cannot lead into itself, nothing can lead into a trigger, and a wire that would go round in a circle is refused:

That would go round in a circle. To go over items again and again, use a Loop over items node.

A node can be deactivated from its menu. A deactivated node passes its items straight through, which is the quick way to try a workflow without, say, its email.

#What starts a workflow

A workflow is Active or Inactive, switched at the top of the editor:

Active, its triggers listen: a check's run, a schedule, a call to its webhook or through the API. Inactive, it runs only when you run it here.

A new, imported or duplicated workflow starts switched off.

#When a check finishes

The default is when it finds differences or a rule fails, with one item for the run. That item holds what a message about the run needs, under short names:

A row's item is the row as the check's table shows it: its columns under their headings on screen, so {{ $json["Store"] }} reads the Store column, with _status, _missingIn and _key beside them.

#When run by hand

Pressing Execute workflow runs it now. Ask for these first lists values to ask for before it runs — a store's code, a machine's name — each with a starting value. The answers become the item the trigger hands on, so a store code asked for as store is {{ $json.store }} from then on.

#On a schedule

The same four kinds as a trigger: every few minutes, daily, weekly, monthly. It keeps the workspace's time zone, and the trigger shows when it fires next. Like any schedule, it fires only while Mosaic is running. Installed as a service, that is always.

#When called

The trigger shows its Address, with Copy and New address:

Call it with GET or POST: what was sent becomes the item — its body, query and headers. The address is the key, so share it as you would a password.

It answers at once with 202 and runs the workflow after, so a caller with a short timeout, which is most chat platforms and monitoring tools, is never kept waiting. An address that nothing listens at, and the address of a workflow switched off, both answer 404, deliberately the same. New address stops the old one working at once.

#When called through the API

For a pipeline that should start something and, if it wants, hear what it found. See Calling a workflow on the API page.

#When rows are sent from a check

A check's result table has a workflow button on each row, for administrators. It lists the workflows that take rows from that check and offers New workflow for these rows. Tick several rows and a bar offers Send to a workflow for all of them, up to 1,000 at once.

Mosaic asks first — Run "Reprice store" on the 12 selected rows now? — then runs it and says how it went, with a link to the run. Each row arrives as one item, read again from the stored run rather than from the screen, so the rows must come from a run that is still kept.

#Items and expressions

A field in a node can hold {{ … }}, filled in for each item the node is given:

Store {{ $json.store }} is {{ $json.qty_diff }} units out on {{ $json.business_date }}

The spelling is n8n's, because many people building workflows already know it. The language is not JavaScript. It has paths, arithmetic, comparisons, ? :, and a short list of helpers for text, numbers, lists and dates — toUpperCase(), trim(), padStart(), replaceAll(), split(), join(), round(), formatDate(), Math.max(), JSON.stringify() and the like. It cannot reach anything it was not given, so a text box can never run code.

The editor previews what a field will become, against the items of the last run.

#The node's window

Opening a node shows three panes:

• Input: what reached the node last time, as Schema, Table or JSON. Drag a field from here into a parameter to use it there.
• Parameters and Settings: what the node does.
• Output: what it handed on.

Execute step runs the workflow up to this node and shows its output. Execute previous nodes fills the input pane when nothing has run yet.

Pin keeps a node's output as it is, so the next executions from the editor use those items instead of running the node. That is how you try the end of a workflow without sending the mail at its start again. Pinned items can be edited as JSON. Runs started by a check, a schedule or a webhook always run every node for real.

Every node has the same Settings:

#Workflow settings

From the workflow's ⋮ menu:

The same menu has Duplicate, Export to a file and Delete.

#Executions

Every run is recorded: its status (Running, Succeeded, Failed or Stopped), what started it (Check, Schedule, Webhook, By hand, Rows sent or API), when, and how long it took.

Choose one and the canvas shows the workflow as it ran, with each node's input and output at that moment. A failed run names the node it failed at and why. A run under way can be stopped, and an old one deleted. Each workflow keeps its newest 300 runs.

#Workflow files

Export to a file writes the workflow as a JSON file. Import workflow, in the sidebar and on the Workflows page, reads one back, whether it was exported here or from another Mosaic.

What travels is the nodes, the wires, the notes, the description and the time limit. What stays behind: the environment, pinned items (they are somebody's rows), and the webhook address. The import gets new ids and arrives switched off.

#Commands, scripts, code and files

Most nodes reach Mosaic's own data, or call out over the network. Ten reach the machine Mosaic is installed on, with the account Mosaic runs as: Execute a command, Run a script, Code, the six file and folder nodes, and Run on another machine. So does an HTTP request's binary body, which sends a file from that machine.

Those are behind a switch the operator sets where Mosaic is started, not in the product:

Where they are off, the nodes are still on the canvas, marked Off on this server, and a workflow that uses one says it cannot run yet and why.

It is an environment variable rather than a setting, deliberately. A switch somebody can flip from a browser is a switch a stolen session can flip, and this one decides whether a browser can run commands on a server.

#Deleting one

A deleted workflow goes to the bin for 30 days. Restored, it comes back switched off.

#Related

• Workflow nodes: every node, and what it asks for.
• Monitors: a page drawn from a workflow's last answer.
• Triggers: the simpler way to schedule a check and send its result.