Workflow Step Reference

Step reference

This page lists every step in the workflow editor's palette: 66 steps in nine groups, in the order the palette shows them. Each step also has a How to use button in the editor, with setup steps, an example and tips.

Two settings apply to many steps:

• Run (on the step's Settings tab): Once for each item or Once with all items. Steps marked "Run: your choice" below offer both. See Expressions for how items work.
• Test runs: steps that change things outside DataMagik hold back on a test run unless you tick their "Really…" box. Steps that do not hold back are called out below. See Testing workflows.

Triggers (7)

What starts the workflow. A workflow has exactly one trigger. See Triggers for details.

Step	What it does	Key options and gotchas
Manual / API	Starts the workflow when someone presses Run, or when another system calls it through the API with an API key.	Sample input is only for test runs. Callers get a Respond to Caller answer only when they call with ?wait=sync.
Schedule	Runs the workflow by the clock.	When is a five-part schedule (minute, hour, day of month, month, day of week); Time zone defaults to America/Chicago. Saving sets up the schedule; removing the step removes it.
File Arrives	Runs when a matching file lands on a file endpoint (FTP, SFTP, a share, or the hosted gateway).	Files matching must start with /; * matches within a folder, ** across folders. Afterwards: leave, move to the archive folder, or delete.
Email Arrives	Runs when an email reaches one of your DataMagik inbound addresses.	Create addresses and safe senders under Script Engine › Email Intakes. Attachments too large to carry are listed in attachmentsTooLarge.
Platform Hook	Runs when someone makes a transaction on DataMagik Mobile or the shop floor, before it goes to Plex or after Plex accepts it.	A Before hook can stop or change the transaction; keep it fast (Time limit up to 30 seconds). End it with Allow or Veto.
Tag Crosses a Limit	Runs when a shop-floor machine tag moves above a high limit or below a low one.	The low limit must be below the high limit. Settle margin stops a value hovering at the limit from firing again and again.
When a Workflow Fails	Runs when another workflow or script fails.	Watch everything, every workflow, or only the names you list. Test runs and this workflow's own failures never start it.

Plex (3)

Step	What it does	Key options and gotchas
Plex Data Source	Runs a classic Plex data source: a read that returns rows, or a write that returns output values such as Result_Code.	Run: your choice. Result decides what comes out; the default "Automatic" gives the rows, or else the output values, or else the item as it was. "One item per row (no rows: nothing goes on)" stops the flow when nothing comes back. A write is held on test runs unless you tick Use Plex test or Really write to production Plex on test runs. It runs once per item, so filter first.
Plex API	Calls any Plex Connect REST operation: customers, parts, jobs, purchase orders and more.	Run: your choice. Search for the operation, then fill in its fields. Anything other than a read is held on test runs unless you tick Use Plex test (test.connect.plex.com) or Really write to production Plex on test runs. Leave PCN empty to use the credential's own.
ODBC Query	Runs a query you saved in the SQL Editor against Plex ODBC. Each row becomes an item.	Run: your choice. Only saved queries run here; write and test the SQL in the SQL Editor first. Parameters fill the query's @name placeholders.

Systems (4)

Step	What it does	Key options and gotchas
HTTP Request	Calls any web API, with sign-in from a credential (including OAuth 2.0), JSON, form or file bodies, and paging.	Register the host under Script Engine › Settings › Allowed Domains. It calls the API on test runs too, so point writes at a sandbox while building. Most pages stops paging (up to 1000); Most requests per second respects rate limits.
Database	Runs SQL on one of your own databases (PostgreSQL, MySQL, SQL Server) through the connector agent.	Run: your choice. Use the database's own placeholders for values; never put {{ }} in the SQL. Statements that change data are shown, not run, on test runs unless you tick Really write on test runs.
PLC / Shop Floor	Reads or writes a machine value (rate, part count, state…) through the connector agent.	Writes need the OT-write licence. A write is shown, not sent, on test runs unless you tick Really write on test runs.
Send EDI	Builds an outbound EDI transaction (810, 856…) for a trading partner, validates it and delivers it.	On test runs it is built, validated and logged but not delivered unless you tick Really send on test runs. Check {{ $json.edi.issues }} after a test.

Logic (10)

Step	What it does	Key options and gotchas
Allow or Veto	Answers a Platform Hook: lets the transaction go ahead (optionally changing request fields) or stops it with a reason the person sees.	Only Before hooks can stop or change a transaction.
Console Log	Writes a line to the run's log and passes the items on unchanged.	Run: your choice. Only on test runs keeps scheduled and API runs quiet. Fields that look like secrets are masked.
Filter	Keeps only the items that match the conditions.	Filter early so later steps do less work. Use IF when the other items need handling too.
IF	Sends each item to true or false.	It tests each item on its own. Numbers stored as text compare as numbers. Both branches can rejoin later at any step.
Loop Over Items	Runs the steps on its loop output for one batch of items at a time.	Wire the last step of the loop back into its next input. Most steps already run per item, so you only need a loop when steps must finish for one item before the next starts.
Merge	Combines branches: append, match by fields, pair by position, combine every pair, or pass one input.	2 to 10 inputs. "Only input 1 items with no match" finds what is missing. Wait for every connected branch skips Merge unless every input has items.
Run Script / Workflow	Calls an existing Script Engine script or another workflow and carries on with what it returns.	Call it once per item or once with every item. A child workflow on a test run runs as a test too. If the child fails, this step fails.
Stop with Error	Fails the run on purpose with your message.	The run shows as failed in Executions and Integrations, and When a Workflow Fails workflows hear about it.
Switch	Routes each item to the output of the first rule it matches (or every rule, if chosen).	Without a fallback output, items that match no rule are dropped. Rules are checked top to bottom.
Wait	Pauses the run for a while, or until a time.	The longest wait is 45 minutes. Raise the workflow's timeout in Workflow settings for long waits. Don't wait on test runs skips the pause while testing.

Data (17)

Step	What it does	Key options and gotchas
Calculate	Arithmetic on each item without expressions: totals, percentages, rounding.	A value that is not a number fails the step; "Convert to a number" strips commas, $ signs and spaces first. Dividing by zero fails the step.
Code	JavaScript, for anything the other steps cannot do.	Run: your choice. Return an object, a list of objects, or nothing. See Workflows and JavaScript.
Compare Datasets	Lines up two lists by a key and sorts them into only in A, same, different, and only in B.	"Compare numbers as numbers" is on by default. Tick "Ignore upper / lower case…" for keys typed by hand.
Date & Time	Formats, shifts and compares dates on each item, in any time zone.	A blank time zone means UTC, which can put late-evening dates on the next day.
Find & Replace	Cleans up text: swap codes, strip characters, fix spellings, or translate values from a lookup table.	Rules run in order, each on the result of the one before. Numbers stay numbers if the result still is one.
JSON Template	Builds exact JSON (an API body, a webhook reply) by writing it out with {{ }} placeholders.	Run: your choice. A value that is only one {{ }} keeps its type. An $each block repeats for every entry in a list.
Limit	Keeps only the first or last items, optionally skipping some first.	Sort first, or "first" and "last" follow arrival order.
Lookup Table	Reads and writes a User Defined Table: add a matching row to each item, get, save, delete or list rows.	Run: your choice. Saves and deletes happen on test runs too. An empty key fails the step.
No Operation	Passes items through unchanged.	Use it as a named meeting point where branches join.
Only New Items	Lets through only items that earlier runs have not handled, by a key or by a newer date or number.	By default the first run sends nothing out; it only remembers what is there. Test runs do not change what is remembered unless you tick Remember on test runs too. Keeps up to 15,000 keys.
Remove Duplicates	Removes items that repeat, comparing chosen fields or whole items.	Only within this run; use Only New Items across runs.
Set Fields	Adds or changes fields on each item. Dotted names such as address.city make nested fields.	Turn off "Keep the item's other fields" to trim items to just the fields you set.
Set Variable	Saves values any later step can read as {{ $vars.name }}, and passes items through.	Run: your choice. In "Once for each item" mode the last item's value wins. For fixed values, use constants.
Sort	Sorts items by one or more fields.	Empty values go last. Compare as Numbers for numbers stored as text.
Split Out	Turns a list inside each item (order lines, serials) into separate items.	An item without the list gives no items.
Summarize	Totals, counts, averages, minimums and maximums, optionally grouped.	With no grouping, one item comes out. "List of values" and "Joined text" collect values per group.
Text	Changes text on each item: case, trim, replace, pad, split, join, patterns.	To change a field in place, write to the field you read from.

AI (5)

AI steps use the model set under Settings › AI Provider Keys unless you name one. Each has Most calls per run, a safety cap: the step fails rather than call the model more than that.

Step	What it does	Key options and gotchas
AI Classify	Sorts each item into one of your categories and sends it down that category's output.	Items the model cannot place go to Other, so always connect it.
AI Extract	Pulls the fields you list out of text, such as a PO number, ship date and quantities.	A required field the model leaves out gets one retry, then the step fails. For scans, use OCR / Read Document.
AI Prompt	Asks your AI model a question about each item (or all of them) and keeps the answer.	Run: your choice. Answer as text or as JSON fields. Temperature 0 gives the most consistent answers.
AI Write	Ready-made writing jobs: summarize items, translate, draft an email reply, or rewrite.	Run: your choice. Very large item lists are cut off when summarized; filter first.
OCR / Read Document	Reads a scanned or photographed document: its text, the fields you list, or a saved extraction profile.	For PDFs that already have text, Read PDF Text is faster. "Never send the document to a cloud model" keeps documents on site.

Files (11)

Step	What it does	Key options and gotchas
File Action	Moves, copies or deletes a file on a file endpoint.	It runs on test runs too. Put it last, so a failed file stays in the inbound folder.
Fill Excel Template	Fills a formatted .xlsx you prepared (named cells and a table) with this run's data.	Each item becomes a table row; formatting and formulas are kept.
Read EDI	Reads an X12 or EDIFACT file: one item per transaction.	The full inbound pipeline also checks for duplicates and builds the acknowledgment.
Read Excel / CSV	Turns a spreadsheet or CSV into one item per row.	Set Delimiter for files that use ; or |. Without column names, values are in columns.
Read File	Reads one file from a file endpoint, or lists a folder (one item per file).	Pair a list with Only New Items or File Action so a file is not handled twice.
Read PDF Text	Pulls the text out of a PDF.	Scans have no text; such items get scanned: true. Send them to OCR / Read Document.
Read XML	Turns XML into data: the whole document, or one item per repeated element.	Attributes become fields starting with @.
Write Excel / CSV	Turns the items into an Excel workbook or CSV file.	One file for all items, ready to email, save or return.
Write File	Saves a file or text to an FTP / SFTP server or a share.	It writes on test runs too, so use a test folder while building.
Write XML	Builds XML from the items.	Run: your choice. "@name" fields become attributes, "#text" an element's text.
Zip / Unzip	Packs files into one .zip, or opens a .zip into one item per file.	Zipping with no files fails the step.

Documents (5)

Step	What it does	Key options and gotchas
Generate Document	Makes a PDF, Excel, CSV or text file from one of your document templates.	Run: your choice. The file is in {{ $json.document }}. "Queue it and move on" is faster but gives no link to use later.
Generate Documents (batch)	Makes one document per item, all together, optionally merged into one PDF.	Much faster than one at a time. If any document fails, the step fails and says which item.
Merge PDFs	Joins PDFs, in item order, into one file, with an optional first and last page.	Sort the items first.
Print Label	Prints a label template on a label printer, with serial numbers filled in.	Run: your choice. On test runs the label is shown, not printed, and no real serials are used, unless you tick Really print on test runs.
Serial Numbers	Takes the next serial number(s) from a series for each item.	On test runs the next number is previewed, not taken, unless you tick Use up real numbers on test runs.

Messages (4)

Step	What it does	Key options and gotchas
Request Approval	Asks a person (or anyone in a role) to approve. The workflow pauses for that item and carries on down approved or rejected.	On test runs it pretends the item was approved (or rejected) unless you choose "Create a real approval task". Save the workflow before a real run.
Respond to Caller	Chooses what an API caller gets back: JSON, text, or a file.	Only for callers using ?wait=sync. Only X-… headers and Cache-Control are passed on. Files over 10 MB cannot be returned.
Send Email	Sends a saved email template or a plain message, with attachments.	Run: your choice. "Once for each item" sends one email per item; "Once with all items" sends one. Test runs capture the email instead of sending it.
Teams / Slack Message	Posts a message card (title, text, facts, a button) to a Teams or Slack channel.	Run: your choice. On test runs the card is shown, not posted, unless you tick Really send on test runs.

Settings every step has

Open a step and choose the Settings tab:

• When this step fails: Stop the workflow; Continue, with the error as the output; or Send the item to an error output. The error output can lead anywhere.
• Retry before failing: up to 5 tries, with a wait between them.
• Always output an item, even when there are no results: keeps the flow going when a step finds nothing.
• Save to variables: stores values for later steps as {{ $vars.name }}.
• Notes: shown when you hover over the step.
• Pinned data and Breakpoint: for test runs. See Testing workflows.

The step's header also has Duplicate, Disable and Delete. A disabled step passes its items through untouched.