DataMosaicDocs · Automating
Workflow nodes
Every node a workflow can use, grouped as the node picker groups them, with what each one asks for.
The node picker opens on Tab, or on the + at the end of a node or on a wire. It groups the nodes as this page does, and has a search box. For what a workflow is and how items move through one, read Workflows first.
Nodes marked host reach the machine Mosaic is installed on, and are off on Mosaic Cloud and, until the operator says otherwise, on a server. See Commands, scripts, code and files.
Most nodes run once for each item that reaches them. Those that would do something once for the lot, such as a mail or a command, start on Once, for all items and say so in a Run field you can change.
#Triggers
The six ways a workflow starts are described under What starts a workflow. A workflow can have more than one trigger.
#Mosaic
| Node | What it does |
|---|---|
| Run a query | Runs one of the check's or the library's data sources through its read-only connection. Query values fills the query's {{tokens}} from the item, usually {{ $json.field }}. Up to 1,000 rows to start with |
| Run a check | Runs a check now, with Check parameters filled from the item, and hands on the run, or its rows. The run is recorded in the check's history like any other |
| Ask an agent | Hands each item to an agent, which reads its systems and says what it found. Agent inputs fills the agent's inputs; an input not named takes the item's field of the same name. Ten items a run to start with, since each is a model reading systems for a minute |
| Places from Business Locations | One item for each open place a place query chooses, with its server's address as host |
| Show on a monitor | What reaches it becomes a monitor's answer. Passes the items on, so a mail about what went down can follow |
#Messages and requests
#HTTP request
Calls any address: an API, a service desk, a webhook.
| Field | Notes |
|---|---|
| Method | GET, POST, PUT, PATCH, DELETE, HEAD |
| URL | Keep a secret in an environment variable and write {{ NAME }} |
| Query parameters, Headers | Names and values. Header names are suggested as you type |
| Authorization | None · Bearer token · Basic: a user and a password · API key, in a header or the query · OAuth 2.0: client credentials |
| Body | none · form-data · x-www-form-urlencoded · raw (Text, JavaScript, JSON, HTML, XML) · binary · GraphQL |
| Response | Work it out · JSON · Text |
| Fail when the answer is an error | On to start with |
| Keep the item's fields | Add the answer's fields to the item that came in, so what earlier nodes made goes on beside it. Off, only the answer goes on |
The body and Authorization work as Postman's do, in Postman's words, so a request that works there can be copied across. Every method but HEAD can carry a body, GET included. Each body mode keeps its own content when you switch between them, and the two forms share their rows. binary sends a file from the machine Mosaic runs on, so it is a host field. A header typed by hand wins over the same header from Authorization.
For OAuth 2.0, the token is asked for once and kept until it runs out, so a workflow sending a hundred requests asks for one token.
On Mosaic Cloud, a request to an address inside a private network is refused.
#Send an email
To, Cc, Subject and Message, every field taking expressions. One message for all the items to start with, or one for each. It needs a mail server: set MOSAIC_SMTP_HOST, with its user and password, where Mosaic runs. Until then the node says it cannot send yet.
#Post to chat
Microsoft Teams, Slack, Discord or any webhook. Webhook URL is the channel's incoming webhook:
It is a password in the shape of an address: keep it in an environment variable and write
{{ NAME }}.
#Check a port
Whether each item's host answers on a TCP port, as nc -z says it: a connection opened and closed, with no shell, so it works on Windows too. Host is {{ $json.host }} to start with, Port 22, Wait 3 seconds. Each item comes out with status: online, offline, or nohost when it had no host. 32 hosts are tried at once, so four hundred stores take seconds.
#Data
| Node | What it does |
|---|---|
| Edit fields | Adds or changes fields, as text, a number, true or false, JSON, or as it comes. A name with dots, customer.name, sets a field inside another. Other fields: keep them or drop them |
| Filter | Keeps the items that meet the conditions |
| Sort | Orders the items by one or more fields, ascending or descending |
| Limit | Keeps the first or the last few items |
| Remove duplicates | Keeps one item of each that repeats, comparing every field or the ones you name |
| Split out | One item for each entry of a list held in a field, with the other fields dropped or copied onto each |
| Summarize | Count, Count different, Sum, Average, Smallest, Largest, Join as text, First, Last, overall or grouped by fields |
#Conditions
Filter, If and Switch test items with conditions, all of them or any of them, with Ignore upper and lower case as a switch. A condition compares a value, usually an expression, by its type:
| Type | Tests |
|---|---|
| Text | is equal to, is not equal to, is in, is not in, contains, does not contain, starts with, ends with, matches the pattern, does not match the pattern, is empty, is not empty |
| Number | is equal to, is not equal to, is in, is not in, is greater than, is at least, is less than, is at most, is empty, is not empty |
| Date | is equal to, is after, is before, is empty, is not empty |
| True or false | is true, is false, is equal to |
| List | contains, does not contain, has this many entries, has more entries than, has fewer entries than, is empty, is not empty |
| Anything | exists, does not exist, is empty, is not empty, is equal to, is not equal to, is in, is not in |
is in and is not in take a list of values separated by commas: Store type is in Outlet, Concession.
#Flow
| Node | What it does |
|---|---|
| If | Sends each item down true or false |
| Switch | Sends each item down the output its routing rules choose, each rule an output with a name. Items no rule matches go to an Otherwise output or are dropped. Each item goes to the first rule that matches, or, if you ask, to every one that does |
| Merge | Joins two inputs: one after the other, matched on a field (only items that match, every item of input 1, or everything from either), side by side by position, or waiting for both and handing on one |
| Loop over items | Hands items on a batch at a time. Wire the last node of the loop back into it, and done carries on once every item has gone round |
| Wait | Pauses, up to an hour |
| Stop and error | Ends the run as failed, with a message |
| No operation | Does nothing: a place to join wires or mark a point |
#Files and server
All of these are host nodes. Paths are on the machine Mosaic runs on, read and written with the account Mosaic runs as. A path field has a Browse button over that machine's folders.
| Node | What it does |
|---|---|
| Execute a command | Runs a command line. Shell: the default (cmd on Windows, sh elsewhere), PowerShell, Bash or Command Prompt. A time limit of 60 seconds to start with, and it fails when the exit code is not 0 |
| Run a script | Runs a PowerShell, Bash, Python, JavaScript (Node) or batch script, with arguments and a working folder. A time limit of 120 seconds to start with |
| Code | JavaScript over the items: return a list of objects. Once for all items, or once for each. It sees the items, not Mosaic |
| Write a file | Creates a file, replaces one, adds to the end of one, leaves it as it is, or fails. As text or Base64 |
| Read a file | Reads a file as text, JSON, one item per line, or one item per CSV row |
| Copy a file, Move or rename a file | To another folder or name, replacing a file already there only if you say so |
| Delete a file | A file, or a folder and everything in it. Fine if it is not there, to start with |
| List a folder | One item for each file, folder or both, by a name pattern like *.csv, in sub-folders too if you ask, older than so many days if you ask |
| Run on another machine | See below |
#Run on another machine
Runs a script on a store's server or a till, copies a folder there, or starts a long job there and follows it, through PowerShell remoting.
| Do | What happens |
|---|---|
| Run a script, and wait | PowerShell, run there as written. The item is $item: $item.host, $item.register. What it returns is result; what it prints is output. An error stops it |
| Copy a folder or a file there | From the machine Mosaic runs on into a folder there. A folder goes in whole; the next time, only what changed is sent. C:\Packs\Store copied into C:\ lands as C:\Store |
| Start a job that carries on by itself | Starts the script there as a task of its own, so a restart of Mosaic or a closed browser does not end it. It runs in the session of whoever is signed in there, or as the machine's own account (SYSTEM) |
| Look in on a job | Reads how a started job is doing. Job is {{ $json.run }}, or latest for the last one started on that machine |
Wait for it to end takes up to 60 minutes. Starting a job with a wait makes the node wait for it and fail if the job fails or stops, with what the job printed. Looking in with a wait carries on until the job has finished, failed or stopped, through a restart of the machine.
What it needs:
- Mosaic running on Windows.
- PowerShell remoting switched on at the other end (
Enable-PSRemoting). Connect over HTTPS uses port 5986. - User: an administrator of that machine. Left empty, Mosaic connects as the account it runs as, and in a domain nothing more is needed.
- Password: only from a secret variable,
{{ NAME }}. A typed password is refused, because it would be saved with the workflow. It is sent to PowerShell on standard input, never on a command line.