Skip to main content

Using Environment Variables

In Orkes Conductor, environment variables help manage frequently used values across multiple workflows. These variables are stored at the cluster level and can be reused across workflows to improve maintainability.

Creating environment variables​

To create an environment variable:

  1. Go to Definitions > Environment Variables from the left navigation menu on the Conductor cluster.
  2. Select + New environment variable.
  3. Enter the following details:
  • Name: A unique identifier for the variable. This name will be used to reference the variable in workflow definitions.
  • Value: The value to be stored as the variable.
  • Value Type: Select Plain Text or JSON.
  1. Select Add to save the variable.

Using environment variables in workflow​

To use an environment variable in a workflow, use the following expression:

${workflow.env.variable-name}

Replace variable-name with the actual environment variable name. This expression dynamically retrieves the variable during workflow execution. Ensure that the referenced environment variable exists on the cluster before using it in a workflow.

If the environment variable is a JSON value, use dot notation to access its fields:

${workflow.env.variable-name.fieldName}

You can also use standard JsonPath notation:

${workflow.env.variable-name.$.fieldName}

Both forms are equivalent. To retrieve the entire JSON object, use:

${workflow.env.variable-name.$}

The expression is validated when saving the workflow definition. An invalid field path will result in a validation error and the workflow cannot be saved.

Updating environment variables​

To update an environment variable:

  1. Go to Definitions > Environment Variables, and select the variable to update.
  2. In Value, enter the updated value.
  3. Select Edit to confirm.

Editing an environment variable in Orkes Conductor

Example​

Using environment variables in a workflow

To illustrate the use of environment variables in a workflow, consider the following variable stored in Orkes Conductor.

Sample environment variable

The following example defines a workflow that references the stored environment variable:

{
 "name": "sample-workflow",
 "description": "Workflow to demonstrate passing variables through environment variables",
 "version": 1,
 "tasks": [
   {
     "name": "http",
     "taskReferenceName": "http_ref",
     "inputParameters": {
       "http_request": {
         "uri": "${workflow.env.sample-url}",
         "method": "GET",
         "connectionTimeOut": 3000,
         "readTimeOut": "3000",
         "accept": "application/json",
         "contentType": "application/json",
         "encode": true
       }
     },
     "type": "HTTP"
   }
 ],
 "schemaVersion": 2
}

When this workflow runs, the expression ${workflow.env.sample-url} is dynamically replaced with the actual variable value.

To verify that the stored variable is passed correctly, go to the workflow execution page, select the HTTP task, and check the Input.

Verifying sample environment variable used in workflow definition

Using JSON environment variables in a workflow

This example shows how to use a JSON environment variable in a workflow. Assume the following environment variable is stored in Orkes Conductor:

Environment variable stored as JSON

The following workflow references the stored JSON environment variable.

{
  "name": "json-env-example",
  "description": "Workflow demonstrating use of a JSON environment variable",
  "version": 1,
  "tasks": [
    {
      "name": "http",
      "taskReferenceName": "http_ref",
      "inputParameters": {
        "uri": "${workflow.env.api-config.$.baseUrl}",
        "method": "GET",
        "connectionTimeOut": "${workflow.env.api-config.$.timeout}",
        "readTimeOut": "${workflow.env.api-config.$.timeout}",
        "accept": "application/json",
        "contentType": "application/json",
        "encode": true
      },
      "type": "HTTP"
    }
  ],
  "schemaVersion": 2
}

In this example:

  • ${workflow.env.api-config.$.baseUrl} accesses the baseUrl field of the JSON environment variable using dot notation.
  • ${workflow.env.api-config.$.timeout} accesses the timeout field.

Run the workflow.

To verify that the stored variable is passed correctly, open the workflow execution, select the HTTP task, and confirm that the resolved values appear in the Input tab.

Environment variable parsed as JSON in workflow