For the complete documentation index, see llms.txt. This page is also available as Markdown.

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_SUCCESS

Triggers

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:

BEFORE_SAVE
AFTER_SAVE

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.

  1. Edit the existing active parent workflow to create a successor draft.

  2. 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.

  3. In the parent draft, add a Sub-workflow element (SUB_WORKFLOW) for each task and select the active sub-workflow.

  4. 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.

  5. 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:

Property
Description

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:

Method
Description

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:

vqlService.queryAll() returns a List<Map>. Access fields directly by their attribute path: results[0].id, results[0].number.


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?