Workflow Instance Variables

This topic covers various services and API endpoints available for listing and managing the variables of a workflow instance.

Programmatic Access

Listing

You can use the IWorkflowInstanceVariableManager service to retrieve all variables of a workflow instance. The following example demonstrates how to read the variables:

                var workflowInstanceId = "some-workflow-instance-id";
                var variables = await _workflowInstanceVariableManager.GetVariablesAsync(workflowInstanceId,
                cancellationToken);

                // Print each variable.
                foreach (var variable in variables)
                {
                    Console.WriteLine($"Id: {variable.Id}, Name: {variable.Name}, Value: {variable.Value}");
                }
            

Each variable retrieved is represented by a unique ID, a name, and a value.

Updating

You can also use the IWorkflowInstanceVariableManager service to update one or more variables of a workflow instance. Below is an example of how to perform the update:

                var variablesToUpdate = [
                {
                    new VariableUpdateValue("some-variable-id", "Some variable value"),
                    new VariableUpdateValue("another-variable-id", 42)
                }];

                // Update the variables. This returns a complete list of variables, including both unchanged and changed variables.
                var variables = await _workflowInstanceVariableManager.SetVariablesAsync(workflowInstanceId, variablesToUpdate, cancellationToken);

                // Print each variable.
                foreach (var variable in variables)
                {
                    Console.WriteLine($"Id: {variable.Id}, Name: {variable.Name}, Value: {variable.Value}");
                }
            

Updating variables in a workflow instance can be particularly useful for dynamically adjusting the workflow's behavior based on changing data inputs or conditions during execution.

API Access

Listing

The workflow instance API also provides an endpoint for retrieving a list of all variables for a specified workflow instance. You can make a GET request to the following endpoint:

                curl --location
                'https://localhost:5001/elsa/api/workflow-instances/{your-workflow-instance-id}/variables' \
                --header 'Authorization: ApiKey {your-api-key}'
            

The API returns a JSON object containing the variables associated with the workflow instance. Below is an example response:

                {
                    "items": [
                        {
                            "id": "ff1c0b14864811ea",
                            "name": "Message",
                            "value": "Hello, World!"
                        },
                        {
                            "id": "ea1bbdf90ea22ca7",
                            "name": "Sender",
                            "value": "Elsa"
                        }
                    ],
                    "count": 2
                }
            

Each item in the response includes the variable's unique id, name, and value, allowing you to inspect the current state of the workflow instance's variables.

Updating

To update one or more variables in a workflow instance via the API, send a POST request to the following endpoint:

                curl --location
                'https://localhost:5001/elsa/api/workflow-instances/{your-workflow-instance-id}/variables' \
                --header 'Content-Type: application/json' \
                --header 'Authorization: ApiKey {your-api-key}' \
                --data '{
                "variables": [
                    {
                        "id": "ff1c0b14864811ea",
                        "value": "Hello, Elsa!"
                    },
                    {
                        "id": "ea1bbdf90ea22ca7",
                        "value": "World"
                    }
                ]
                }'
            

The request payload specifies the id of each variable to update, along with the new value. Ensure the variable IDs match those in the workflow instance to prevent accidental data mismatches.

Last modified: 09 November 2024