Filter Steps

A Filter Step checks a set of conditions and decides whether the Action run continues.

When the conditions say the run should not continue, the Filter Step stops the run. No later step runs, and the run still finishes normally with the Completed status. A stopped run is not an error.

Common uses in an accounts-payable Action Flow:

• continue only for invoices, and stop for receipts, delivery notes, and other documents,
• stop when the vendor is blocked or the invoice was already processed,
• stop for invoices below an amount threshold,
• stop when a required value, such as a purchase order number, is missing.

For general step concepts, see Step Types.

When to Use a Filter Step

• Filter Step or Switch Step: use a Filter Step when some runs should simply end early. Use a Switch Step when different data needs different processing. You don't need a Switch with an empty branch to stop a run.
• Filter Step or the Action's Filter Configuration: when the check only needs the trigger data, and the Action's Filter Configuration supports it (Company & Vendor filters, workflow step filters, or webhook filter rules), prefer the Filter Configuration. It decides whether the Action runs at all, so no run and no credits are used. Use a Filter Step when the decision depends on step outputs, such as an OCR or Agent result, or on data loaded by an Input.
• Filter Step or a failing step: a stopped run completes normally, so error handling Actions and failure notifications do not run. If the situation is an error that someone must look at, let the run fail instead. For example, use the Raise_Error tool.

Adding a Filter Step

When you add a step, choose Filter Step in the step type picker. A new Filter Step starts with one empty condition. Fill in its field path before you run the Action.

The step configuration has three parts.

When the conditions match

• Continue only if (default): the run continues when the conditions match, and stops otherwise.
• Stop the run if: the run stops when the conditions match, and continues otherwise.

Pick the option that reads like your business rule. "Continue only if the document type equals Invoice" and "Stop the run if the vendor status equals Blocked" are both easy to read later.

Conditions to match

• all conditions match (default): every condition must match.
• any condition matches: at least one condition must match.

Conditions

Select Add Condition to add a condition. A Filter Step can have up to 20 conditions. Each condition has:

• Field Path: the value to test. It uses the same syntax as a Switch Step field path:

  • a previous step's output: Classify Document.documentType or steps.Classify Document.documentType,
  • a structured Agent output field: Classify Document.structured.documentType,
  • trigger data: inputs.triggerPayload.amount,
  • data loaded by an Input assigned to the Filter Step: inputs.Get_Vendor.vendor.blocked,
  • the files the step can see: inputs.files.0.fileName.

  Step names with spaces are supported. Use the exact step name.

  As you type, the field suggests real field paths from the Action's latest run, or from the run you pick in the Previous Run tab of the Inputs column. This lets you pick List Orgs.value.0.name instead of guessing. Before the Action has run, it suggests step names. The Switch Step and Loop Over Step field paths offer the same suggestions.

• Operator: how the value is compared. See the table below.

• Value: the value to compare against. For the Regex operator, this is the pattern.

  The value can include {{..}} references, like Tool Call parameters. They are resolved when the step runs. For example, field path Extract Invoice.structured.total with operator Greater Than and value {{Approval Limits.maxAmount}} compares the invoice total with another step's output. Type {{ in the field to get suggestions. A reference that does not resolve stays as text, so the condition does not match.

• Description (optional): what the condition checks. It is shown in the step output.

• Case sensitive: whether text comparisons respect upper and lower case. Off by default.

Operators

Filter Steps use the same operators as Switch Step cases.

Operator	Matches when the field value...
Equals	equals the value. Numbers are compared as numbers, so 2 equals 2.0.
Not Equals	does not equal the value.
Starts With	starts with the value.
Ends With	ends with the value.
Contains	contains the value.
Not Contains	does not contain the value.
Greater Than	is a number greater than the value.
Less Than	is a number less than the value.
Regex	matches the regular expression in the value, for example ^INV-\d+$.
Is Null or Empty	is missing, empty, or only whitespace. The value is not used.
Is Not Null or Empty	has content. The value is not used.

Tips:

• Greater Than and Less Than never match when the field value or the comparison value is not a number. Write decimals with a dot, for example 1000.50.
• A field path that does not resolve is treated as an empty value. It is not an error. Use Is Null or Empty to check for a missing value on purpose.

Inputs and Tools

A Filter Step can have Inputs. The Inputs run before the conditions are checked, so you can fetch data and filter on it. For example, assign an Input that fetches the vendor and stop the run when inputs.Get_Vendor.vendor.blocked equals true.

A Filter Step cannot have Tools.

What Happens When the Run Stops

When a Filter Step stops the run:

• the run status is Completed,
• the steps after the Filter Step are not run. The run log shows them as Skipped, with the reason "Run stopped by Filter step" and the Filter Step's name,
• the run details show a Stopped by filter badge with the Filter Step's name,
• the run gets the stoppedByFilterStep metadata field, with the Filter Step's name as its value. Filter the run history by this field to find runs that a filter stopped,
• the run's final output is the Filter Step's output, which explains why the run stopped.

A Filter Step inside a Switch case or a Loop Over route stops the whole run, not only that branch or batch. Inside a Loop Over, the remaining batches and the Done route are not run. To skip only some items of a loop, remove them from the array before the loop, for example in a Code Step.

A stopped run is billed only for the steps that actually ran. See Credits. Place the Filter Step as early in the Action Flow as its data allows, so stopped runs do less work.

Step Output

Later steps can read the Filter Step output like any other step output, for example {{Only invoices.message}}. A later step only runs when the Filter Step did not stop the run, so it always sees stopped as false.

Field	Description
stopped	Whether this step stopped the run.
conditionsMatched	Whether the conditions matched as a whole: all of them for all conditions match, or at least one for any condition matches.
mode	ContinueIf or StopIf.
matchMode	All or Any.
message	A short explanation of the outcome.
conditionResults	One entry per condition, with its fieldPath, operator, value, the resolved actualValue, and whether it matched. When the configured value contains {{..}} references, value is the resolved value and valueTemplate is the configured one.

Example output of a Filter Step that stopped a run:

{
  "stopped": true,
  "conditionsMatched": false,
  "mode": "ContinueIf",
  "matchMode": "All",
  "message": "Filter conditions did not match; the action run was stopped.",
  "conditionResults": [
    {
      "fieldPath": "Classify Document.documentType",
      "operator": "Equals",
      "value": "Invoice",
      "actualValue": "Receipt",
      "matched": false,
      "description": "Only invoices continue"
    }
  ]
}

When a Filter Step Fails

A Filter Step fails the run, with the Failed status, when:

• it has no conditions,
• a condition has no field path,
• a Regex condition takes longer than one second to evaluate. This can happen with a pattern that backtracks heavily on long text, such as OCR output. Simplify the pattern.

Studio does not save a Filter Step with an unknown operator, mode, or match mode, an invalid regular expression, or more than 20 conditions.

Example: Process Only Invoices

An Email Received Action reads every attachment, but only invoices should be posted:

1. OCR Step Read Document extracts the text.
2. Agent Step Classify Document returns a structured documentType.
3. Filter Step Only invoices:
   • When the conditions match: Continue only if
   • Conditions to match: all conditions match
   • Condition: field path Classify Document.structured.documentType, operator Equals, value Invoice
4. Agent Step Post Invoice posts the invoice to Dooap.

For a receipt, the run stops after Only invoices and Post Invoice is skipped. The run history shows the run as Completed, with stoppedByFilterStep: Only invoices in its metadata.

Testing and Troubleshooting

• Run the Action with a sample that should pass and one that should stop. Then compare the conditionResults in the Filter Step output.
• When a condition does not match as you expect, check its actualValue in conditionResults. An empty actualValue usually means that the field path does not point to the field you meant.
• To let every run through while you test later steps, disable the Filter Step. A disabled Filter Step is skipped and never stops the run.
• Name the Filter Step after its rule, for example Only invoices or Skip blocked vendors. The name appears in the Stopped by filter badge and in the stoppedByFilterStep metadata.

Shepherd can design Filter Steps too. Describe the rule, for example "stop the run when the vendor is blocked", and Shepherd adds a Filter Step with matching conditions to the Action Preview.

---