Workflows
Event-driven scripts that react to entity lifecycle events in the ERP.
VARIO Cloud Workflows let you run server-side JavaScript in response to entity lifecycle events in the ERP — an account being saved, a document being created, a CRM deal changing state, and more. Workflows are the primary mechanism for automating business processes, validating data before it is persisted, and orchestrating multi-step logic with user interactions.
Workflow Structure
A parent workflow consists of a trigger and a chain of elements connected by successors. A sub-workflow contains connected elements and is invoked by a Sub-workflow element; it has no trigger of its own:
Trigger (e.g. account.BEFORE_SAVE)
→ START_EVENT
→ SCRIPT_TASK
→ EXCLUSIVE_SPLIT_GATEWAY
→ SCRIPT_TASK (Branch A)
→ SCRIPT_TASK (Branch B)
→ EXCLUSIVE_JOIN_GATEWAY
→ END_EVENT_SUCCESSTriggers
The trigger determines when a VARIO Cloud workflow runs and what data is available to your scripts.
One Active Parent Workflow per Trigger
VARIO Cloud allows at most one active parent workflow per trigger. Activating a second, unrelated workflow for the same trigger is rejected and leaves the existing workflow active. This is intentional behavior.
A successor version of the existing workflow can be activated; it replaces and deactivates its predecessor. A successor is a new version of the same automation, not an additional subscriber to the trigger.
For several automations reacting to the same trigger, extend the existing parent workflow and compose the individual tasks as sub-workflows. See Sub-Workflows for Multiple Automations.
BEFORE_SAVE vs AFTER_SAVE
This is the most important distinction in VARIO Cloud workflow scripting — it determines whether your script can modify the entity directly or must read and update it via service calls:
Execution
Synchronous — blocks the save
Asynchronous — runs after save completes
Input
The entity to save (e.g. accountToSave) and its previous version
The saved entity's ID (e.g. accountId) and previous version
Can modify entity
Yes — changes to the ToSave entity are persisted automatically
Yes — but must read by ID and update via service methods
Can cancel save
Yes — throw 'message' aborts with an error shown to the user
No
BEFORE_SAVE scripts receive the entity object directly and can modify it in place — every change is persisted with the save. AFTER_SAVE scripts only receive the entity's ID, so they must read the entity via its service, apply changes, and explicitly call the update method.
Other Triggers
Beyond BEFORE_SAVE and AFTER_SAVE, triggers exist for specific lifecycle events such as document.CREATE, document.TRANSFER, and document.BEGIN_EDITING. These behave like AFTER_SAVE — they run asynchronously and provide IDs rather than entity objects.
The data available to each trigger is accessible via ctx.availableInput and ctx.parameters. The exact fields depend on the trigger and are visible in the workflow editor.
Sub-Workflows for Multiple Automations
Use one parent workflow to coordinate all tasks for a trigger. Keep each reusable task in its own sub-workflow, with conditions and execution order defined in the parent flow.
Edit the existing active parent workflow to create a successor draft.
Create each additional workflow with the Sub-workflow option enabled (German UI: Unter-Workflow). A sub-workflow has no trigger of its own. Configure its start, processing and end elements, then activate it.
In the parent draft, add a Sub-workflow element (
SUB_WORKFLOW) for each task and select the active sub-workflow.Connect the elements in the required order. Use conditions to route past a task when it is not applicable, then continue with the next task.
Check the complete flow, including the previous automation, before activating the parent draft.
For a defined sequence:
Do not deactivate an existing parent merely to activate an additional automation for its trigger: that would stop the previous automation from receiving the event. Extend its successor draft instead. The handbook setup guide describes the UI steps.
Execution and Shared Context
A sub-workflow runs inside the same workflow instance as its parent. It shares the trigger input (ctx.availableInput) and parameter context (ctx.parameters). Changes can affect subsequent elements, so use distinct parameter names for unrelated tasks and coordinate writes to the same entity.
The parent's connected next element runs after the sub-workflow reaches its successful end. Connecting A → B explicitly establishes that sequence; separate branches should not be used to imply a fixed execution order.
Sub-workflows provide modular composition within one flow. They are not independently triggered or failure-isolated runs. An unhandled exception puts the common workflow instance into an error state. An error end in a sub-workflow aborts its invoking SUB_WORKFLOW element and any enclosing sub-workflow elements; their successors do not continue automatically. Account for this when deciding which steps depend on each other.
Synchronous Compatibility
The parent trigger determines whether execution is synchronous or asynchronous. A sub-workflow has no separate execution mode.
For a synchronous parent, all invoked sub-workflows must use elements that support synchronous execution. In particular, USER_TASK, TIMER and INTERMEDIATE_EVENT are not permitted in a synchronous flow. A sub-workflow without these elements can also be used by an asynchronous parent. Check nested sub-workflows as well when preparing a synchronous flow.
Script Structure
Every workflow script in VARIO Cloud starts with an import that determines its type. Scripts can be written inline in each element or saved centrally as Script Modules and referenced by name.
SCRIPT_TASK
You can optionally add a guard to skip the element, and a prepare step to set up variables before the action:
EXCLUSIVE_SPLIT_GATEWAY
The returned string must match a key in the element's successors map.
The Context Object (ctx)
Every script in a VARIO Cloud workflow receives a context object ctx with the following properties:
ctx.availableInput
Trigger-specific data — the entity being saved, IDs, previous versions
ctx.services
All available scripting services
ctx.parameters
Workflow parameters and user task results
Reading and Modifying Data
How you read and modify ERP data in VARIO Cloud depends on the trigger type.
BEFORE_SAVE — Direct Modification
In BEFORE_SAVE triggers, ctx.availableInput contains the entity object that is about to be saved, named with a ToSave suffix — e.g. accountToSave, documentToSave, or crmDealToSave. This is the actual object being persisted. Any property you set on it is automatically included in the save without calling a service method. Because the save is still in progress, you can also cancel it by throwing an error.
AFTER_SAVE — Read, Modify, Update
In AFTER_SAVE triggers, read the entity by ID, modify it, and call the service's update method:
Document Updates
When updating documents via service (e.g. in AFTER_SAVE or CREATE triggers), documentService requires a request wrapper. In document.ON_MERGE_CHANGES triggers, the document is available as documentToSave and can be modified directly — like any other BEFORE_SAVE entity.
Validation and Cancellation
In BEFORE_SAVE triggers, throw an error to cancel the save:
The error message is displayed to the user and the save operation is aborted.
Logging
Use ctx.services.logger to write log entries:
logger.info(msg)
Informational message
logger.warn(msg)
Warning
logger.error(msg)
Error
Log entries are visible in the workflow execution log in the ERP.
VQL in Workflows
Use ctx.services.vqlService to query ERP data within scripts:
User Tasks
VARIO Cloud workflows support user interaction through USER_TASK elements. A user task pauses workflow execution and prompts the user for input. The user's response is available in subsequent scripts via ctx.parameters:
Custom Fields
VARIO Cloud Custom Fields are accessed directly on entity objects in scripts:
Comparing with Previous State
Both BEFORE_SAVE and AFTER_SAVE triggers in VARIO Cloud provide the previous version of the entity. Use it to detect field-level changes and react only when specific values have changed:
Last updated
Was this helpful?