Every automation is made of steps, and every step belongs to one of four families: sources bring data in, transforms reshape it, commands change something, and control steps decide which steps run and how often. The editor groups its list of steps by these families. A step's family tells you what it is allowed to do, how it behaves in a dry run, and whether it can feed a widget or a report.
Steps pass values to each other along connections. Each input and output has a type, such as a number, a piece of text, a date or a list of entries, and the editor lets you connect an output only to an input that can take it. Where a value converts safely, such as a whole number into text, Pyron converts it; where it cannot, the run stops at that step rather than guessing. For every step in each family, see the automation steps catalog. For the editor itself, see building an automation.
Sources: where data comes from
A source step is where data enters the flow. The values an automation starts with, filled in by its trigger, are available to every step as well, so a flow that only needs those values can begin without a source at all.
Reading from Pyron
The source you will use most reads things held in Pyron. You choose the kind of thing to read, such as entries, items in the directory or people, and the step hands on every one the run is allowed to see. When the automation runs on its trigger, that is what its service account can see. In a dry run from the editor, it is what you can see.
Narrow a read with the transforms that follow it. A filter, sort or slice placed straight after the read is worked out as part of the read itself, so Pyron fetches only the items that match instead of loading every item first.
Outside systems and the web
Other sources reach beyond Pyron:
- A web request calls an outside system's API, usually through one of your organisation's outbound connections, and hands on its reply. You describe the shape of the reply: fields you did not describe are dropped, and a reply missing a field you marked as required stops the run at that step.
- Fetching every page pulls a list that an outside system returns a page at a time, and hands back the whole set as one list.
- Reading a web page loads a public page made for people. One step passes on what the page shows; another reads the page and brings back the details you ask for, as data.
- The clock gives the date and time at the moment the step runs.
Use a web request for an address that already answers with data, such as an outside system's API. The web page steps are for pages written for people to read, where there is no API to call.
Transforms: shaping it
Transforms take data and hand on a reshaped copy. They never change anything stored, which is why they run for real in a dry run and can feed widgets and reports. A typical chain reads entries and then:
- Filters them to the ones that matter, such as open issues.
- Works out a date range, such as this month, and keeps the entries inside it.
- Summarises what is left, such as a count of entries per site.
- Sorts the result, largest first.
What transforms can do
Transforms fall into a few groups:
- Narrow and order: filter, sort, keep a range by position, take the first item, remove duplicates and count.
- Group and summarise: totals, averages, counts, medians and percentiles, pivots that turn rows into columns for a chart, and ranks or running totals within groups.
- Combine lists: match two lists on a shared value, stack lists with the same fields, pair them up, or look up a related item and add its fields.
- Shape fields: add a computed column from a formula, keep, drop or rename fields, build text, do arithmetic, round a date to a period, take one part of a date, or choose a value by condition.
A filter treats an empty field as not matching, so items with no value in that field drop out. A summary works with numbers held in entry fields directly, and averaging a yes-or-no field gives a rate, such as the share of inspections that passed.
Work values out in a transform
When every item needs a value worked out, such as a duration or a full name, add a computed column instead of repeating steps for each item. The column is worked out for the whole list in one step, which keeps the flow short and easy to read. Keep the loop described under Control for steps that act on each item.
For a calculation that no ready-made step covers, an expression step sits in a collapsed advanced section at the end of the list of steps. Reach for the ready-made steps first: they are typed, and the canvas describes each one in plain words, which makes a flow easier to check and to hand over.
Commands: making changes
Commands are the steps with real effects. They create, update and delete entries, move entries through lifecycles, change the directory, generate reports, send emails and webhooks, and start other automations. Each command does the same thing as the matching action a person takes in Pyron, and is checked against the same permission.
Whose permissions a command uses
An automation's commands act with the permissions of the service account it runs as, not those of the person who built it or the person who set it off. If any of its steps need a permission, an automation with a schedule, event or web request trigger cannot be turned on until it has a service account to run as. A command the service account has no permission for fails when it runs. To see what each role allows, see roles and permissions.
Commands in a dry run
A dry run does not carry out commands. Each one hands on sample output in the shape it would produce, so you can check the rest of the flow without sending a single email or changing an entry. If a command would be refused for lack of permission, the dry run shows a warning at that step instead.
The AI and run-code steps are the exception. They cannot change anything in Pyron, so they run for real in a dry run and show you their real output.
A command inside a loop acts once for every item, and a scheduled automation acts on every run. Because a dry run skips commands, check the list that feeds the loop in a dry run before you turn the automation on.
Commands cannot feed what people view
Widgets and reports run their automation again every time someone looks at them, so the automation behind one cannot contain a command: it would make its change on every view. To send out a finished report on a schedule, build a separate automation around a report step; see report schedules.
Running other automations
One automation can hand work to another. One command runs another automation and waits for it to finish before carrying on; another starts one in the background and carries on without waiting.
AI and code steps
The AI step hands its input to an AI model, with instructions written on the step. It can read your workspace while it answers, but it cannot change anything, and it returns either text or a value in the shape you define. Give it files to read too, as many as the AI reads at once (five documents, and photos besides): a document or photo in Files, or the files in a record's file field, such as the photo on an incident. It reads them as the assistant reads a file you attach (a PDF's pages, a scan, a photo), and only the files the automation can open. It runs on the model your organisation chooses for AI steps in automations — see AI models.
To reuse the same AI work in several places, make it an automation that runs on request: give it the inputs it needs and a line saying when it is useful, and people or other automations can start it whenever they need it. See automations that run on request.
The run-code step runs Python, JavaScript or TypeScript that you write, in an isolated sandbox. It sits in the collapsed advanced section at the end of the list of steps. To set one up:
- Describe the shape of what the code returns, and the shape of its inputs if it takes any.
- Connect the steps that supply those inputs.
- Write the code. It receives the inputs, and its result is checked against the output shape before the flow moves on.
The sandbox has no network access unless a person lists the websites the step may reach (over https); an AI assistant can never add them. To bring in data from anywhere else, use a web request step and connect its reply to the code's inputs. Each run of the step has a time limit, and code that runs past it fails the step.
Running code needs a permission of its own: to run code in an automation, at the administer level. The service account the automation runs as must hold it, and being able to edit an automation does not include it.
Control: branching and loops
Control steps shape the run itself rather than the data: how often a group of steps repeats, which path the flow takes, when it waits, and what happens when something fails.
Repeating for each item
The loop step repeats a group of steps once for every item in a list, such as moving each overdue entry to its next state and emailing its owner. The steps inside the loop's group run once per item; steps connected after the loop run once, when every item is done.
Items are worked through one after another unless you choose to work on several at a time. That speeds up steps that wait on other systems, such as sending emails or calling an outside address. If one item fails, the loop carries on with the rest, and the run history shows how many items were processed, how many succeeded and how many failed.
Branching on a condition
The branch step sends the run down exactly one path. It checks its conditions in order and takes the first one that matches, or its default path when none do. Only the steps connected to that path run. Steps on the other paths are skipped, along with everything that depends only on them, but a step fed from more than one path still runs while any of its paths is live.
Choosing a value, under transforms, works differently: it picks one of several fixed values by the first matching condition, and every step after it still runs. Use a branch when different cases need different steps, and choose a value when only the value differs, such as a label or a priority.
Waiting for a person
One control step pauses the automation and asks a person a question. The run waits, then carries on down one of two paths: one when the person answers, carrying their answer, and one when the question lapses unanswered. In a dry run nobody is asked; the step previews the answered path with a sample answer.
Only some runs can wait. A run started by a schedule, an event, or a web request that does not wait for a reply can pause; a run started by hand, or by a web request waiting for an answer, fails at this step. The step also cannot sit inside a loop, or in an automation that another automation runs and waits for.
Handling failures
When a step fails, the run stops there unless you have said what should happen. There are two ways to say it:
- A failure connection on the step. Every step that runs has an output for failures. Connect it to the steps that should deal with that step's failure, such as an email to the person who looks after the automation. Steps that need the failed step's result do not run, but the rest of the flow carries on.
- A failure handler for the whole flow. This control step catches any failure that has no failure connection of its own, and runs the steps connected to it. A flow can hold one.
Either way, the run counts as partly successful rather than failed, and the error is kept with the run. Neither one runs the failed step again.
Setting the order
A step runs once every step it takes values from has finished. To make one step wait for another without passing it anything, such as sending a summary only after the entries are updated, connect the first step's completion output to the second step's run input. No value crosses that connection; it only sets the order.