Inputs and Tools

Inputs and tools make Actions useful in real business flows.

Together, they define what data an Action can receive and what external capabilities it can use.

Inputs

Inputs are data provided when an Action runs. These can come from API calls or other external sources.

Examples:

• files,
• invoice details,
• invoice image,
• metadata values,
• user-provided JSON.

Define input types carefully so Action Flows can validate required data before a run.

Input Design Principles

• Keep input names descriptive and stable.
• Use explicit required/optional semantics.
• Prefer predictable structures over free-form payloads.
• Test with realistic sample data, not idealized examples.

Well-defined inputs reduce runtime errors and make Actions easier to reuse.

Tools

Tools let steps call external capabilities, such as APIs or custom logic.

Use tools when an Action Flow needs information or operations outside the model itself.

Typical tool scenarios include:

• looking up reference data,
• sending or updating records in external systems,
• calling internal APIs,
• and enriching step outputs with trusted system data.

Runtime Files and File References

Every file that enters an Action run becomes a runtime file in the run context: files uploaded to a manual run or sent with the trigger, email attachments, files uploaded through a Human Task, files fetched by inputs such as Read_Context_File, Read_Data_File or Download_Sftp_File, and files produced by tools such as Extract_PDF_Pages, Render_Document_To_PDF or Convert_To_PDF. Runtime files stay in the run for its whole duration, so any later step can use them without downloading or re-uploading anything.

Each runtime file carries metadata that you can both read and select by:

Field	Meaning
fileId	Unique id of the file within the run.
fileName	Original or generated file name.
contentType	MIME type, for example application/pdf.
sizeBytes	File size.
inputTypeName	Name of the input that loaded the file, for example Read_Gateway_Email_Attachment.
sourceStepName	Step that loaded or produced the file.
sourceToolName	Tool that produced the file, for example Extract_PDF_Pages.

You can see these values in two places. Each step's input includes a files list with the metadata of the files visible to that step, which is also available to templates as {{inputs.files...}}. Inputs and tools that add a file to the run return the same metadata in their output under file for reading, together with a ready-to-use reference under runtimeFile for passing the file on.

Where file references are accepted

Any parameter that expects a file takes a file reference instead of file content. The most common places are:

• the file parameter of the Read_Context_File input,
• the runtimeFile parameter of Read_Excel_Sheet and of the built-in file tools, including Extract_PDF_Pages, Convert_To_PDF, Convert_Excel_To_CSV, Write_Blob, Write_File_Share_File, Upload_Sftp_File and the Data Files Write_File tool. These also accept the parameter under the aliases contentFile and file,
• the htmlRuntimeFile and markdownRuntimeFile parameters of Render_Document_To_PDF,
• entries in the attachments array of Send_Gateway_Email, optionally with a fileName or contentType override for the outgoing attachment,
• file (binary) form fields of your own OpenAPI tools that post multipart/form-data.

Reference forms

All forms below resolve to a single file. When several files match, the most recently added one wins.

latest picks the newest file in the run, whatever its type. It is the easiest form and the right one when the run holds exactly one relevant file. It is also the trap to watch for: OCR results, JSON inputs and other intermediate outputs are runtime files too, so in a longer Action Flow the newest file is often not the PDF you meant. A tool that receives the wrong file typically fails on the receiving end with a confusing error, for example an HTTP 415 from an API that expected a PDF.

A file id points to one exact file. Use runtimeFile:<id> or file:<id>; a bare id works as well. The id comes from the files list of the step input or from the file.id value in the output of the input or tool that created the file. This is the form to prefer inside Agent steps: the agent sees the ids of the files available to it, so ask it in the prompt to pass the id of the specific file rather than latest whenever more than one file is present.

A selector object narrows the choice with metadata filters. Any combination of the fields above can be used, all given filters must match, comparisons ignore case, and the newest matching file is returned:

{ "fileId": "latest", "contentType": "application/pdf" }

selects the newest PDF regardless of what else has been added since, and

{ "sourceToolName": "Extract_PDF_Pages" }

selects the file the Extract_PDF_Pages tool produced. Other useful filters are fileName, inputTypeName (the newest file loaded by a given input, for example { "inputTypeName": "Read_Data_File" }) and sourceStepName. A selector object may also carry runtimeFile or fileId with an exact id. An object that contains only these selector fields is always treated as a file reference, while an object with any other fields is treated as literal content, so a payload that happens to have a fileName property is never mistaken for a reference.

The runtimeFile object of an earlier output is the most robust form when one step produces a file and a later step consumes it. Inputs and tools that add a file return a runtimeFile object that already contains the file id, so passing it through a template resolves to exactly that file. A Tool Call step exposes the tool result under data, so a later tool parameter can reference the file produced by an earlier Tool Call step named "Extract invoice pages" as:

{ "runtimeFile": "{{steps.Extract invoice pages.data.runtimeFile}}" }

The same works for the runtimeFile object returned by download tools such as Download_Sftp_File and Get_Gateway_Email_Attachment. Pass the runtimeFile object, not the file metadata object: file is for reading names and sizes and is not accepted as a reference.

Behavior notes

• Matching is case-insensitive for ids, names, content types and step or tool names.
• A reference that does not match any file fails the step or tool with an error that lists the files currently in the run, so an incorrect reference never silently sends the literal reference text as file content.
• In a Loop Over, the files loaded by a step's own inputs are refreshed on every round, so latest and per-input references follow the current round's file rather than the first round's.
• The OCR step does not take a reference. It reads the file loaded by its own inputs first, then files tagged with one of its input types, and finally untagged run files such as manual uploads. Load the intended document through an input such as Read_Context_File when the run contains more than one candidate.

Practical guidance

• Use latest for short flows with a single document.
• Add a contentType or sourceToolName filter as soon as a flow produces more than one file, or pass the producing step's runtimeFile object through a template.
• In Agent steps, instruct the agent to reference files by id and to inspect the files list before choosing.
• When a downstream API rejects a file with an unexpected format error, check which runtime file the reference resolved to before debugging the API.

Built-in File Tools

Studio ships standard tools every tenant can use without configuration. Some of them work on the run's context files:

• Extract_PDF_Pages creates a smaller PDF from selected pages of a PDF already in the run context. Page selection uses the same syntax as the OCR step — 1-10, 1,2,3, or 1,4-8 — and the last keyword selects the document's last page wherever a page number fits, so 1-3,last extracts the first three pages together with the final page (where totals often appear) without scanning everything in between. Pages beyond the end of the document are simply skipped, so extracting 1-10 from a 7-page document yields a 7-page PDF without an error. A common pattern: a Tool Call step fetches a large PDF and extracts just the pages you need, and the following OCR step reads the trimmed file through a Read_Context_File input with file latest or a selector such as { "sourceToolName": "Extract_PDF_Pages" } (see Runtime Files and File References). This keeps large documents fast and inexpensive to process.
• Render_Document_To_PDF renders HTML or Markdown produced by earlier steps into a PDF file.
• Convert_To_PDF turns a file already in the run context into a PDF file, whatever its type. It detects the file type from the extension, the content type or the file's own signature and picks the conversion for you, so it works for email attachments and uploads whose type you do not know in advance. A file that is already a PDF is passed through unchanged. Word documents (.docx) and Excel workbooks (.xlsx) are converted with full fidelity, including headers, footers, images and the workbook's own print setup, in environments with the LibreOffice conversion service; elsewhere Studio's built-in layout engine takes over, where headings, text formatting, lists, tables, embedded images and page breaks come through while headers, footers, charts and complex floating layout are simplified or left out, and workbooks render as one table per worksheet (the sheets, showSheetNames, maxRowsPerSheet and culture parameters control that rendering). HTML, Markdown and plain-text files are rendered like Render_Document_To_PDF, and PNG or JPEG images are placed on a page scaled to fit. Every other format that LibreOffice can open, such as PowerPoint, legacy .doc/.xls, OpenDocument, RTF, CSV, EPUB, Visio, TIFF or SVG, is converted through the LibreOffice conversion service; where the service is not available the tool explains that instead of producing a broken PDF. Files it cannot convert at all, such as ZIP archives or JSON, are rejected with a clear message. The result reports the detected sourceFormat, the conversion that was applied and the engine used (the engine parameter lets you force one), and the resulting PDF can be written to storage, attached to a Send_Gateway_Email, or read by the next step through a Read_Context_File input with file latest or a { "contentType": "application/pdf" } selector.
• Convert_Excel_To_CSV, Read_Excel_Sheet, and Write_Excel_Sheet move data between Excel workbooks and Action Flow steps.

Mapping Inputs to Tools

Most production Action Flows map input values into tool requests. Keep this mapping explicit.

Example pattern:

1. Validate input values in early steps.
2. Transform values into the expected API format.
3. Call a tool with only required fields.
4. Handle tool failures with clear fallback or error behavior.

Output Filters (JSONPath-like)

Input and Tool responses are often larger than what an LLM step actually needs.

To reduce prompt size and noise, each Step Input assignment and Step Tool assignment supports an optional outputFilter field.

When set, the filter is applied to JSON responses before the data is added to step context/output.

In Action Studio, outputFilter is shown as a separate field, while being stored as part of the step assignment configuration JSON.

Why use output filters

• Reduce token usage by keeping only relevant fields.
• Improve model focus by removing unrelated response data.
• Make step outputs easier to inspect in logs.

Supported syntax

The filter uses a JSONPath-like subset (not full JSONPath):

• $.field
• $.field.nested
• $.arrayField.0
• $.arrayField[*]
• $.arrayField[*].{fieldA,fieldB} (projection extension)
• field.nested (without $)
• $ (keep full JSON as-is)
• $.a.x, $.b.y (several expressions, see below)

Examples:

• $.data.items -> returns the items node under data
• $.data.items.0.id -> returns the first item id
• $.phoneNumbers[*].{number,country} -> returns each phone number with only number and country
• result.total -> returns total under result

Projection example:

{
  "userId": "user789",
  "name": "Bob K.",
  "phoneNumbers": [
    { "type": "home", "number": "555-0201", "country": "+358" },
    { "type": "mobile", "number": "555-0202", "country": "+358" }
  ]
}

Filter:

$.phoneNumbers[*].{number,country}

Result:

[
  { "number": "555-0201", "country": "+358" },
  { "number": "555-0202", "country": "+358" }
]

Another projection example:

Multiple expressions

One expression can only keep values under a single parent. To keep fields from different branches of the response, list several expressions separated by commas or spaces:

$.invoice.num, $.audit_log.created

With several expressions the result is the original JSON pruned down to the selected values, so each value keeps its place in the structure:

{
  "invoice": { "num": "123", "date": "2026-09-09", "sum": 123.12 },
  "audit_log": { "created": "2026-09-09T23:23:23Z" }
}

becomes

{
  "invoice": { "num": "123" },
  "audit_log": { "created": "2026-09-09T23:23:23Z" }
}

Notes:

• Projections can be combined with other expressions: $.items[*].{id,name}, $.total. Commas inside {...} are part of the projection, not separators.
• When one expression keeps a whole value (for example $.invoice) and another keeps part of it, the whole value wins.
• Partially selected arrays keep only the selected elements, in their original order.
• Expressions that match nothing are skipped. If none match, the result is null.
• A single expression still returns the selected value itself (for example $.invoice.num returns "123"), which keeps existing filters working unchanged.

Output Filter Wizard

Instead of typing the expression, use the Wizard button next to the Output Filter field. It shows a sample of the response (from a previous run, the example output, or JSON you paste) as a tree of checkboxes:

• Tick or untick fields to keep or drop them. Everything is kept until you untick something.
• Use Open to pick fields inside an object or list. Fields inside a list are projected with [*].
• Selections are remembered while you navigate between branches. A parent with only some of its fields kept is shown as partially selected.
• The preview shows the filter expression and the resulting JSON live. Several branches produce several expressions, combined with commas.

Behavior notes

• Filtering is applied only to JSON-like response payloads.
• Binary responses (for example PDFs/images) are not filtered.
• If outputFilter is empty, full response data is kept.
• If path does not match, the filtered result is null.
• If response is plain text/non-JSON, filtering is skipped and original data is kept.
• Date-like strings are kept exactly as they appear in the response.

Practical guidance

• Start with the smallest field that still gives the next step enough context.
• Prefer stable paths that do not depend on optional branches.
• Avoid filtering out fields needed by downstream prompt templates or tools.
• Validate filters using realistic response examples before production rollout.

Best Practices

• Keep input contracts stable and descriptive.
• Mark required inputs clearly.
• Use least-privilege credentials for tool connections.
• Handle tool errors gracefully and expose useful logs.

Common Pitfalls

• Passing large raw payloads between many steps without normalization.
• Making tool calls with ambiguous or unvalidated identifiers.
• Treating model output as trusted input for external writes without checks.

---