Workflow Variables

WorkflowClosed A workflow is a series of steps necessary to complete a process. In Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store. variables store data generated during workflow execution and make that data available to subsequent steps. Variables may contain simple values or structured data returned from REST requests or PowerShell steps, enabling workflows to pass information, evaluate conditions, and perform dynamic actions.

What Variables Are (vs Tokens)

These appear similar at first glance:

Think of it this way:

Tokens = system-provided values

Workflow variables = step-generated values

How Variables are Created

Variables are created when a workflow step returns one or more named outputs. The two most common ways to create them are:

REST Request Step

When you configure a REST request step:

  • You set Variable to Store Response in (e.g., MyResponse).

  • The response body (typically JSON) is stored in that named variable for use by subsequent steps.

Example:

Variable to Store Response in: MyResponse

This creates a workflow variable named MyResponse that contains the API response.

PowerShell Step

When you return output from a PowerShell step (either a Set Variable Data step or a Use Custom PowerShell step):

  • PowerShell outputs a hashtable.

  • Each key in the hashtable becomes a named workflow variable when returned.

Example snippet:

$result = @{ "Query" = $Query }

return $result

This returns a variable named Query with whatever data you put in $Query in the PowerShell step.

Variable Naming Rules

  • Variable names are defined by the step author.

  • Names should be unique within a workflow to avoid overwriting values.

  • Keys returned from PowerShell become variable names exactly as returned (case matters when accessing them).

  • When REST responses are stored, the name you choose becomes the variable.

Using Variables in Subsequent Steps

Once a variable exists, it can be referenced in later workflow steps. For example:

  • REST URLs

  • REST request content

  • Conditional logic

  • Email subject and body

Workflow variables may contain either simple values (such as strings or numbers) or structured data (such as JSON objects or collections).

Structured data can originate from:

  • A REST request step, which stores an API response in a variable, or

  • A PowerShell step, which returns a hashtable or object.

Example use in a URL:

https://server/Endpoint?query=$(Query)

Example use in an email:

Certificate CN: $(MyResponse.Name)

If the stored response is structured (like JSON), properties may be accessed using dot-notation syntax in substitution strings. For example, $(MyResponse.someProperty) in email or request content.

Accessing Structured Workflow Variables

When Workflow variables contain structured data, such as JSON returned from a REST request or objects returned from a PowerShell step, individual properties can be accessed using dot notation. Arrays can be accessed using index notation.

Accessing a Single Property

If a REST step stores a response in a variable named MyResponse (GET /MetadataFields/{id} in this example):

Copy

JSON

{
  "Id": 10,
  "Name": "BusinessUnit",
  "Description": "Unit of business responsible for certificate",
  "DataType": 5,
  "Hint": "",
  "Validation": "",
  "Enrollment": 1,
  "Message": "",
  "Options": "Accounting,E-Business,Executive,HR,IT,Marketing,R&D,Sales",
  "DefaultValue": "R&D",
  "AllowAPI": false,
  "ExplicitUpdate": false,
  "DisplayOrder": 7,
  "CaseSensitive": false,
  "ExemptFromActionedCount": false
}

You can reference individual properties using dot notation:

Copy
Variables
$(MyResponse.Name)
$(MyResponse.Options)
Accessing Properties Within an Array of Objects

If the response contains an array of objects (GET /Certificates in this example) and is placed in a variable called CertificatesResponse:

Copy

JSON

[
  { "Id": 9913, "Thumbprint": "...", ... "DetailedKeyUsage": { ... } ... },
  { "Id": 10063, "Thumbprint": "...", ... "DetailedKeyUsage": { ... } ... }
]

Because the response is an array, access elements using zero-based indexing:

Copy

Variables for the First Certificate

$(CertificatesResponse[0].Id)
$(CertificatesResponse[0].Thumbprint)
$(CertificatesResponse[0].SerialNumber)

To access the second certificate:

Copy

Variables for the Second Certificate

$(CertificatesResponse[1].Id)
$(CertificatesResponse[1].Lifespan)

Remember:

  • Array indexing is zero-based.

  • [0] is the first item.

  • [1] is the second item.

Note:  The GET /Certificates operation returns an array at the root.
Accessing Nested Properties
If the response includes nested objects such as DetailedKeyUsage (see GET /Certificates example, above):
Copy

JSON

"DetailedKeyUsage": {
  "CrlSign": false,
  "DigitalSignature": false
}

Access nested values using chained dot notation:

Copy

Nested Variables for the First Certificate

$(CertificatesResponse[0].DetailedKeyUsage.DigitalSignature)
$(CertificatesResponse[0].DetailedKeyUsage.CrlSign)
Accessing Boolean Properties

If the response includes Boolean values (from GET /Certificates):

Copy

JSON

[
  { "Id": 9913, ... "HasPrivateKey": "True", ... },
  { "Id": 10063, ... "HasPrivateKey": "False", ... }
]

These can be used in decision logic.

Copy

Variable

$(CertificatesResponse[0].HasPrivateKey)
Note:  Limitation with Array Responses from REST, Azure Function, or AWS Lambda Function Steps

When a REST, Azure Function, or AWS Lambda Function step in a workflow returns a JSON string representing an array, the entire response can be referenced in subsequent steps using a variable like $(MyResponse). However, you cannot directly extract individual elements or properties from that array in later steps such as email messages. This does not work:

$(MyResponse[0])
$(MyResponse[0].DisplayName)

To extract and use individual values from the array (such as the first object’s DisplayName), you need to process the response first.

Solution: Use a Set Variable Data Step

  1. Add a Set Variable Data step immediately after the a REST, Azure Function, or AWS Lambda Function step and before any step that needs to use parsed values (like an email step).

  2. In the Set Variable Data step, parse the JSON string in the body of the PowerShell script and extract the specific values you need. For example:

    Copy 
    param(
        [string]$MyResponse
    )

    $ObjectResponse = ConvertFrom-Json -InputObject $MyResponse

    $ObjectResponseShortName = $ObjectResponse[0].ShortName
    $ObjectResponseDisplayName = $ObjectResponse[0].DisplayName
    $ObjectResponseDescription = $ObjectResponse[0].Description

    $result = @{
        "ObjectResponseDisplayName" = $ObjectResponseDisplayName
        "ObjectResponseShortName"   = $ObjectResponseShortName
        "ObjectResponseDescription" = $ObjectResponseDescription
    }
    return $result

How to Use the Parsed Values

After this step runs, you'll have access to the following variables in later workflow steps:

$(ObjectResponseDisplayName)
$(ObjectResponseShortName)
$(ObjectResponseDescription)

These variables can now be used safely in email or other steps where individual values are needed.

Boolean and Decision Logic

Conditions can evaluate workflow variables.

Example setting shouldRun from a PowerShell step:

$result = @{ "shouldRun" = $shouldRun; }

return $result

You can then use $(shouldRun) as the condition that determines whether a workflow step should execute.

Edge Cases and Tip Topics
Null Values in Workflow Variables

Workflow variables may contain null or empty values, whether they originate from a REST response (e.g., a JSON property with a value of null) or from a PowerShell step that returns $null or no output. When a null value is referenced, the substitution resolves to an empty value.

If a downstream step requires a value and receives null or empty data, the workflow fails. Review the Keyfactor API log for detailed workflow errors and the step that triggered the failure.

PowerShell Steps with Multiple Keys

What if a step returns multiple keys?

  • Each key becomes its own variable. For example:

    $result = @{ "key1" = $value1; "key2" = $value2 }

    return $result

  • This creates two separate variables, key1 and key2, which can be used as any other variables described above.