Localized workflows

Only organization or space admins can create a localized workflow definition.

Localized workflows introduce two new concepts:

Variables: placeholders for actors (users or teams) and locales.
Variable value presets: named sets of variable values that define actor–locale pairings.

When you enable localization for a workflow in the workflow configuration page, the system automatically creates two variables:

translator (type: subject)
locale (type: locale)

Each translator–locale pairing configured in the Localization settings corresponds to a variableValuePreset. These presets ensure that workflow permissions can adapt dynamically depending on the language and translator assigned.

A localized workflow must have at least one of these pairings.

Creating a workflow for a given preset (known as locale in the frontend), you cannot delete the configuration for that preset as long as that workflow is active. A maximum of 3 steps can rely on variables.

Create a localized workflow definition

Creates a new workflow definition with optional variables and variable value presets.

Key points

Variables are defined in the appliesTo[].variables array.
Variable value presets are defined in the appliesTo[].variableValuePresets array.
Each preset must provide values for all variables defined in the workflow definition.
Variables can be referenced in step permissions using WorkflowVariable links.

Variable types:

subject: Used for actors in permissions, values must be User or Team links
locale: Used for locale in permissions, values are locale strings (e.g., “de-DE”)

Update a localized workflow definition

Updates an existing workflow definition. Variable and preset modifications have restrictions.

Variable and preset update rules:

Cannot change variable types once defined.
Cannot add variables if the definition previously had none.
Cannot remove variables from existing definitions.
Cannot remove all presets if variables are defined.
Can add new presets to existing definitions.
Cannot remove presets that are currently used by active workflows.

Create a localized workflow instance

Creates a localized workflow instance, optionally specifying a variable value preset.

Behavior with variables

If the workflow definition has variables and presets, you must provide a variableValuePreset.
The specified preset determines the actual values for variables used in permissions.
The preset ID must match one of the presets defined in the workflow definition.
Automatic workflow start is disabled when variables and presets are present.

WorkflowSteps.permissions with variables

Permission structure

Permissions can reference variables in two places:

Actors (for subject variables)

{
  "type": "entity_permission",
  "configuration": {
    "action": "edit",
    "effect": "allow",
    "actors": [
      {
        "sys": {
          "type": "Link",
          "linkType": "WorkflowVariable",
          "id": "translator-variable-id"
        }
      }
    ]
  }
}

Locale (for locale variables)

{
  "type": "entity_permission",
  "configuration": {
    "action": "edit",
    "effect": "allow",
    "actors": ["all"],
    "locale": {
      "sys": {
        "type": "Link",
        "linkType": "WorkflowVariable",
        "id": "locale-variable-id"
      }
    }
  }
}

Validation rules

Variables

Variable IDs must be unique within a workflow definition.
Variable types (subject or locale) cannot be changed after creation.
Variables cannot be added to or removed from existing workflow definitions.

Variable value presets

Maximum of 80 presets per workflow definition.
Each preset must provide values for all variables defined in the workflow definition.
Preset IDs must be unique within a workflow definition.
Values must match variable types:
- subject variables: User or Team links
- locale variables: Locale strings (e.g., “en-US”, “de-DE”)

Errors

422 Validation Error: Missing preset values or invalid variable types.
400 Bad Request: Invalid preset ID.
403 Forbidden: Variables feature not enabled for the space.
422 Unprocessable Entity: Attempted removal of variables/presets from active definitions.

Example response:

{
  "message": "Preset \"German Translation\" must have a value for each variable defined in the workflow definition.",
  "details": {
    "code": "CmaError.Workflows.WorkflowDefinition.PresetMustHaveAllVariables",
    "parameters": {
      "presetName": { "type": "string", "value": "German Translation" }
    }
  }
}

Frontend behavior of Localized workflows

When users check “I want to localize this workflow”, two variables are automatically created: translator and locale.
Each translator–locale pairing in Localization settings generates a variableValuePreset.
In workflow steps, rules referencing translators automatically link to the translator variable, and permissions automatically include the locale variable.