Build a script function

A function is a reusable snippet of Python you author once and call from any number of processes. Use one for the deterministic in-between work — formatting a date the way your ERP expects, summing line items with a custom tax rule, computing a risk score from a handful of inputs. (The surface is labelled Functions; “script function” means the same thing.)

A function isn’t a substitute for a connector (which reaches an external system) or an agent (which handles unstructured input) — it’s for the few lines of logic you’d rather not duplicate across every process that needs them.

Before you start

• You have at least the editor role in the project.
• You know what the function takes in and what it returns — a clear signature is what makes it reusable.
• The logic is small and self-contained: the sandbox has no network or file access.

Steps

1. Open Functions. In the project sidebar, go to Build → Functions, then click New function.

   Screenshot placeholderThe Functions editor — a Python execute() body with input/output schemasReplace with real capture from app.superagent.studio

2. Name and categorise it. Give it a name (compute_tax_total), pick a Category (Data Transformation, Validation, Calculation, …), and add any tags.

3. Declare the input and output schemas. Define the inputs the function accepts and the shape it returns, using the schema builder. Types are enforced at design time and at run time.

4. Write the body — in Python. The editor starts you with:

   def execute(input_data: dict) -> dict:
       # your logic here
       return {"result": ...}

   Read from input_data, do your arithmetic or string work, and return a dict matching the output schema. The sandbox is intentionally restrictive — standard Python, but no network calls and no file I/O.

5. Test it. On the Test tab, fill in sample input and run; the output and timing appear. Iterate until it’s right.

6. Save. The function is saved to the project. Set its visibility — private (this project) or organization (shared across the org).

7. Use it in a process. In the designer, add a Script task, pick this function and a published version, and map process variables to its inputs and its output back to a variable.

Common variations

• Versioning. Publish a version when the function is ready; a Script task pins a published version, so editing the function later doesn’t change a running process. Change the signature carefully — removing an input breaks existing callers.
• Validation helpers. Encode a business rule once (“is this PO number well-formed?”) and call it from any process that needs the check. (For a whole table of rules, reach for a Decision instead.)

Troubleshooting

• The function times out. The sandbox enforces a per-invocation timeout (default 30 s, max 60). A legitimately long computation should be split up or moved to a connector; otherwise check for an infinite loop.
• An import isn’t available. The sandbox restricts what you can import, and network and file access aren’t allowed. Move that work to a connector.
• Test passes but production fails. Production inputs have edge cases you didn’t try — a null where you expected a value, an empty string, an unexpected decimal. Handle them at the top of execute.

Related

Build a processAdd the script task that calls a function.

DecisionsFor a table of rules rather than code.

BPMN paletteThe script task element.