Run Script
Run Script executes custom JavaScript inside the process engine.
Use it when built-in actions cannot express the required logic.
Typical uses are transformation, validation, parsing, and calculation.
Configure this action in the Builder. See Builder Navigation and Workspace Basics for the surrounding UI.
Status
The current status of the step is shown directly under the Step Type. Specific problems can be seen by expanding the box.
Configuration
Task Name and Add Instructions
Use Task Name to give the step a clear label.
Use Add Instructions to tell the assigned user what to submit.
Keep both fields specific. Good labels make the task easier to find and complete.
Use Role to define who is responsible for the task.
Roles are configured at process level in the Roles tab.
Script and Input
Set script to the .js file the engine should execute.
This field is required.
Use Select Additional Input to pass process symbols into the script.
Map only the values the script actually needs.
This can include system values like Executing-Actor and instanceID, or your own symbols.
When a file is passed into the script, the engine may parse it first.
JSON files are passed as objects. CSV files are parsed into arrays. PDFs and images are passed as Base64 strings.
Return Values
Use Error Message to capture script failures in a text symbol.
Use Logs to store execution output in a file symbol.
Use Select Additional Output to map returned values back into process symbols.
Keep output names and types stable when later steps depend on them.
Map Logs and Error Message while testing.
They make sandbox failures much easier to diagnose.
Details and Delay
Open DETAILS for advanced settings.
Use Add Delay if the task should become active later.
Enable Workdays only if the delay should ignore weekends and non-working days.
Connections
Use Connections to review incoming and outgoing links for this step.
Data
Use Data to manage automatic context modifications and local symbols.
Automatic context modifications update process values when the task is completed.
Local symbols store step-specific values that are only relevant inside this action.
Runtime behavior
Run Script executes automatically.
It does not wait for user input.
The engine uses the ScriptController and its execute function.
Object arrays are resolved before execution and encoded again on output.
The controller also writes execution logs that can be mapped through Logs.
Best practices
Keep scripts small and deterministic.
Prefer explicit input and output mappings.
Validate edge cases inside the script.
Use logs while developing and testing.
Return structured output when later steps depend on fixed fields.
Use cases
Run Script works well for advanced data handling.
- Data cleanup: Normalize dates, phone numbers, or IDs.
- Scoring: Calculate totals, weights, or risk values.
- Payload shaping: Flatten nested API responses for later actions.
- File parsing: Convert structured files into symbols for routing.
Works well with
- Submit Information (Action) to collect raw data or files before transformation.
- Loop over Array to process each item after the script prepares the data.
- Conditional Branching to route by a calculated result.
- Push to Array to collect transformed results across multiple cycles.