Workflows

A workflow is an automation that responds to an event in Nash and runs a series of actions. Workflows let you encode operational logic — “when an order is created, if it’s high value, apply the white-glove dispatch strategy and notify the team” — so the platform handles decisioning instead of your application. Workflows are how Nash determines which dispatch strategy an order flows into, and how it automates order-level decisions using attributes like order value, product type, destination, SLA, or merchant-defined metadata.

​

What workflows are

A workflow is built from nodes connected by edges, plus a trigger that defines when it runs.

• Nodes are the steps of the workflow. Each node has a type:
  • trigger — the entry point that starts the workflow
  • filter — evaluates conditions and branches the flow
  • action — performs an operation
  • switch — routes execution based on a value
• Edges connect nodes and define execution order. An edge type of default is used for trigger and action nodes. For filter nodes, success follows when the condition is met and negative follows when it is not.
• A trigger defines the event that activates the workflow.

A workflow moves through a lifecycle of statuses: draft, active, inactive, archived, and template. New workflows are created in draft by default and must be set to active to run. Updating a workflow’s structure (nodes, edges, and trigger together) creates a new version.

​

Actions

Action nodes perform operations on the order or delivery, or send notifications. Supported actions include:

• Apply a dispatch strategy or an optimization strategy
• Modify order price or tip — set a value outright, or bound one: At least raises anything under a floor, At most caps anything over a ceiling, and both leave a value already inside the bound alone
• Add a tag or extract a metadata field
• Flag a delivery, auto-reassign, cancel a delivery, cancel an order, or remove an order from a route
• Raise, update, resolve, or assign a route flag so a detected condition becomes durable work on the Execute page rather than a notification someone has to catch
• Add requirements to an order
• Send a notification by email, SMS, Slack, or Teams channel message
• Summarize, run an agent call or browser automation, or emit a custom event
• Hand the step to a Custom Agent and branch on what it reports back

​

Triggers & conditions

A workflow’s trigger specifies what activates it. Trigger types include event, manual, webhook, and cron. Event triggers listen for a named event in Nash — for example order.created or order.creating. (Currently, the REST API for creating workflows supports the event trigger type; other trigger types exist in the platform but are not all exposed through that endpoint.) Conditions are expressed with filter nodes. Each filter holds one or more conditions made up of a field, an operator, and a value. When the filter evaluates true, execution follows the success edge; otherwise it follows the negative edge — letting you branch a workflow based on order attributes. The available fields and operators are returned by GET /v1/workflows/schema.

​

Branching on whether a field is there

Two operators take no value at all. Is set and Is missing ask whether a field or a metadata key is present, which is a different question from what it contains. Only null and genuinely absent values count as missing. 0, an empty string, and an empty list are all set — so a condition asking whether someone filled in a tip doesn’t quietly treat a deliberate zero as a blank. A presence check against context the workflow doesn’t have yet, such as a delivery on an order that hasn’t been dispatched, resolves to missing rather than failing the step.

​

Fields worth branching on

The field catalog spans the order, its packages, the job (delivery), and the delivery attempt, and it is served live by GET /v1/workflows/schema — the Portal’s workflow editor reads it from there, so new fields appear without a Portal release. Alongside the address, value, tag, and requirement fields, it carries the numbers a routing or escalation decision usually turns on:

​

Running a workflow by hand

Triggers cover the routine cases. Sometimes you need to run one yourself — to apply a workflow to orders that predate it, or to check a change before you turn it on. Start a workflow on demand with the Trigger Workflow endpoint (POST /v1/workflows/{id}/trigger), passing entity references (such as the ID of a job, i.e. a delivery) and optional input data, in synchronous or asynchronous mode. A manual run works on a workflow in either active or inactive status. That’s the useful part of inactive: a workflow you’ve switched off no longer fires on its own, but you can still run it deliberately. Workflows in draft, archived, or template status are rejected. In the Portal, select the orders you want on the Orders page and choose Run Workflow from the action bar. Pick the workflow, add trigger input if it needs any, and Nash starts one run per selected order — each independent, each with its own result you can open. Selecting orders row by row is what’s supported here; a workflow run needs a concrete order to reference, so “select all results” across pages isn’t.

​

Test a workflow before you activate it

Running a workflow tells you what it does. Testing one tells you what it would do, which is what you want while you’re still writing it. The alternative is activating a workflow against live orders to find out whether a filter matches. Test a saved workflow with POST /v1/workflows/{id}/test, passing the jobId or orderId of the entity to evaluate it against. The response reports per-node status, so you can see which filters passed and which branch execution took. This is the same dry run behind the Test drawer in the Portal’s workflow editor, so a workflow an agent or a script builds can be checked the same way a person would check it.

​

Hand a step to an agent

Filters and actions cover the decisions you can write down in advance. Some steps aren’t like that — read the notes on this order and decide whether anyone needs to be called, look at what the provider has done so far and judge whether the delivery is still recoverable. An agent node hands that step to one of your custom agents and lets the rest of the graph branch on what comes back. The agent receives the entity the workflow was triggered on, the trigger’s own metadata, and the output of every node upstream of it. It does the work — pulls the data it needs, calls the tools it’s allowed to use — and returns a written report, plus the structured fields that go with it if you’ve given the agent an output format. In the API it’s the invoke_agent action; in the Portal’s workflow editor it’s Run Custom Agent. Either way you pick the agent, write the task context for this particular step, and choose what the workflow branches on.

​

Branching on what it reports

The node writes its result into the workflow’s variables in two shapes: The typed per-field variables are the ones worth branching on: a number can be compared, a boolean tested, an enum matched, the same as any other filter field. The full report is the fallback for an agent with no output format — useful to carry into a notification, less useful to filter on.

​

What an agent node can’t do

• It can’t take actions. Only report-only agents can be selected. An agent that acts would put its actions behind its own confirmation gate, and the workflow would carry on as though they had happened.
• It can’t sit on a synchronous run. Workflows that run synchronously while an order is being created reject agent nodes, because the order would wait on the agent. Nash refuses the combination when you save the workflow, and again if a run attempts it.
• It can’t run unbounded. Each node carries its own timeout and a choice of what the workflow does when the agent fails or runs out of time.

​

How workflows relate to dispatch strategies

Workflows and dispatch strategies are complementary:

• A dispatch strategy answers “given this job, which provider should fulfill it?” — it defines the eligible providers, selection rule, and failover behavior.
• A workflow answers “given this event and these conditions, what should happen?” — including which dispatch strategy to apply.

A common pattern is a workflow triggered on order creation, with filter nodes that branch on order value or destination, and dispatch_strategy action nodes that apply the right strategy to each branch. This is the same role served by Automations, which map account-level business rules to dispatch strategies; workflows generalize that idea to a broader set of triggers, conditions, and actions.

​

Next steps