Workflow

What is a Workflow

The Workflow resource is a resource that bundles a trigger, tasks, and controls (similar to if statements) inside of a single file. The trigger initiates the tasks, following the flow of the controls.

For example, a trigger may be executed by a completion of a survey, which will initiate the task of sending an email if the control logic evaluates to true.

If you would like to join the early access program for XM Solution Plugins, then please let us know by taking this survey.

Not generally available

This feature is in Early Access and is not yet generally available. Functionality, APIs, and documentation may change before general availability.

Context

The Workflow resource will generate two fields:

• id
• workspaceId

The id will be your Workflow's id (WF__***) and can be accessed with <step.id>.id. The workspaceId is the workspace identifier for this workflow. This is usually a Survey id (SV_***) or an Outcome id (OC_***) and can be called with <step.id>.workspaceId.

How to Import it into an XM Solution

Using the XM Solution CLI

You can import a Workflow resource along with its associated Survey using the CLI import command as long as the imported Survey is linked to the Workflow.

Start by running the following command:

solution import

Next, a project category list should be displayed.

Select "basicSurvey" to view all potential Surveys to import:

1. AgileVideoDiscovery
2. BrandTracker
3...
11. basicSurvey
12...

Then a list of all your basic Survey projects will render, and you can select one to import.

1. [basicSurvey] Survey1
2. [basicSurvey] Survey2
3. [basicSurvey] Survey3
4...

Now you should have your Survey project and all of its dependencies downloaded into a src/Resources_**** folder of your solution plugin. This will include any Workflow resources that are attached to your Survey project.

Workflows Are Imported as Dependencies

When you import a Survey, any Workflows linked to that survey are automatically included in the import. You do not need to import them separately. The generated Solution Execution file will already contain the correct steps and dependency order for creating the survey before the workflow.

Solution Execution

Workflow resources are created using a "Create" step in the Solution Execution file. The step must declare the Survey as a dependency so that the workflow is created after the survey and the correct survey ID is available.

{
  "id": "workflow",
  "type": "Create",
  "config": {
    "apiVersion": "workflow.v1",
    "templateFilePath": "Resources_ab12/workflow.json"
  },
  "dependencies": [
    "survey"
  ]
}

The current apiVersion for Workflow resources is "workflow.v1".

No Transformation File Required

You no longer need to provide a transformationFilePath for Workflow resources. The fields contextId, workspaceId, and name are now automatically set during solution execution based on the linked survey. Only add a transformation file if you need custom logic beyond what is automatically applied.

Standalone vs. Non-Standalone Workflows

The import and execution behavior differs depending on whether the workflow is standalone (not linked to a survey) or a regular workflow (linked to a survey).

Regular Workflow (Linked to a Survey)

A regular workflow is one that has an associated survey. When this type of workflow is imported and executed:

• A "Create" step is generated for both the survey and the workflow.
• The workflow step lists the survey as a dependency, ensuring the survey is created first.
• The workspaceId and contextId inside the workflow are automatically set to reference the newly created survey's id.
• The workflow name is automatically set from the solution import metadata.
• After the setup assistant completes, the user is redirected to the survey, not to the workflow.

Standalone Workflow (Not Linked to a Survey)

A standalone workflow is one that has no associated survey — it runs independently. When this type of workflow is executed:

• Only a "Create" step for the workflow is generated; no survey step is created.
• The workspaceId is automatically set to the global workspace identifier (GWS_111111111111111).
• After the setup assistant completes, the user is redirected to the workflow itself via a navigation step added automatically during execution.
• No dependency on a survey step is set.

warning

Do Not Manually Add setLocation Steps

The navigation step that redirects the user after setup is automatically generated for standalone workflows. You do not need to add a setLocation step manually. Adding one at the workflow level for a non-standalone workflow will cause users to be redirected to the workflow instead of their survey, which is the incorrect behavior.

Fields Updated Automatically

When a Workflow is executed as part of a solution, the following fields are set automatically. You do not need to handle these in a transformation file:

Field	Behavior
name	Set from the workflow's title in the solution import metadata
workspaceId	Set to the linked survey's id (regular workflow) or GWS_111111111111111 (standalone)
contextId (trigger)	Set to the linked survey's id for regular workflows

Fields You Still Need to Update

Workflow resources may contain other fields with values matching the pattern {{template_caller_defined_*}}. These are fields with values you define, such as control branch names or custom task parameters.

Be Careful Updating Fields

Only update fields whose values contain caller_defined. Fields containing template_defined are replaced automatically when the workflow is created — leave those unchanged.