Using Environment Variables

Environment variables are cluster-level configuration values that workflows can reference at runtime. Use them for non-sensitive values that vary by environment, such as service URLs, regions, feature flags, thresholds, and JSON configuration blocks. Keep secrets in secrets instead.

Creating environment variables

Use the Create or update environment variable API (PUT /environment/{key}) or go to Definitions > Environment Variables, select + New environment variable, and enter the following parameters:

Parameter	Description	Required/Optional
Name	A unique identifier for the variable. This name will be used to reference the variable in workflow definitions. Can contain only letters, numbers, underscores, and hyphens.	Required.
Value	The value to be stored as the variable.	Required.
Value Type	Select Plain Text or JSON.	Required.

For repeatable deployments, use the API and manage values per cluster or environment.

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.$}

Updating environment variables

Updating a variable changes the value used by future workflow executions without changing the workflow definition.

Use the same Create or update environment variable API with the existing variable name, or go to Definitions > Environment Variables, select the variable, enter the new value in Value, and select Edit.

Before changing a value used by production workflows, check which workflows reference it and verify the expected shape. JSON variables are especially easy to break if a field is renamed.

When to use environment variables vs secrets

Use	Environment variable	Secret
API base URL	Yes	No
Feature flag	Yes	No
Region or tenant code	Yes	No
Numeric timeout or threshold	Yes	No
API token	No	Yes
Password or private key	No	Yes
Webhook signing secret	No	Yes

Examples

Using environment variables in a workflow

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

{
  "name": "sample-url",
  "value": "https://orkes-api-tester.orkesconductor.com/api"
}

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 the workflow runs, Conductor replaces ${workflow.env.sample-url} with the stored value. To confirm, open the workflow execution, select the HTTP task, and check its Input, where the uri shows the resolved value:

{
  "http_request": {
    "uri": "https://orkes-api-tester.orkesconductor.com/api",
    "method": "GET",
    "connectionTimeOut": 3000,
    "readTimeOut": "3000",
    "accept": "application/json",
    "contentType": "application/json",
    "encode": true
  }
}

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:

Name: api-config
Value Type: JSON
Value:

{
  "baseUrl": "https://orkes-api-tester.orkesconductor.com/api",
  "timeout": 5000
}

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": {
        "http_request": {
          "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.

When the workflow runs, Conductor replaces both expressions with the values stored in api-config. To confirm, open the workflow execution, select the HTTP task, and check its Input, where the uri and both timeouts show the resolved values:

{
  "http_request": {
    "uri": "https://orkes-api-tester.orkesconductor.com/api",
    "method": "GET",
    "connectionTimeOut": 5000,
    "readTimeOut": 5000,
    "accept": "application/json",
    "contentType": "application/json",
    "encode": true
  }
}