Skip to content

Workflow Operators

Operators allow you to choose the path your workflow should take. Use choice operators to compare two items, or use a loop to perform a set of actions on every item in a list. Operators also include the end steps, used to mark the end of a workflow. Review the operators listed below for more information.

Compare Boolean

A Compare Boolean operator is a type of choice operator. It compares two boolean (true or false) values.

Field Required? Description
Value 1 No A JSONPath expression to a TRUE or FALSE value in the step's input, to be compared with Value 2.
Comparison Operator Yes The operator Equals.
Value 2 No A static value or a JSONPath expression to another value in the input, to be compared with Value 1.

Compare Numbers

A Compare Numbers operator is a type of choice operator. It compares two numerical values.

Field Required? Description
Value 1 No A JSONPath expression to an integer value in the step's input, to be compared with Value 2.
Comparison Operator Yes The operator to use to compare Value 1 to Value 2.
Value 2 No A static value or JSONPath expression to another value in the input, to be compared with Value 1.

Compare Strings

A Compare Strings operator is a type of choice operator. It compares two text, or string, values.

Field Required? Description
Value 1 Yes A JSONPath expression to a string value in the step's input, to be compared with Value 2.
Comparison Operator Yes The operator to use to compare Value 1 to Value 2.
Value 2 Yes A static value or a JSONPath expression to another value in the input, to be compared with Value 1.

Compare Timestamps

A Compare Timestamps operator is a type of choice operator. It compares two timestamp values, or the number of days between a single timestamp value and the date a workflow is executed.

Field Required? Description
Value 1 Yes A JSONPath expression to a timestamp value in the step's input, to be compared with Value 2.
Comparison Operator Yes The operator to use to compare Value 1 to Value 2.
Value 2 No A static value or a JSONPath expression to a value in the input, to be compared with Value 1. This value must be either a date and time in ISO 8601 format that can be formatted to RFC 3339 such as yyyy-MM-dd'T'HH:mm:ss.SSSZ, or an integer representing a number of days.

The comparison operators Is on the Date, Is Before, Is After, Is On or Before, and Is On or After require a date and time in the Value 2 field.

The comparison operators More Than X Days Ago, Fewer Than X Days Ago, More Than or Exactly X Days Ago, and Fewer Than or Exactly X Days Ago require an integer representing a number of days. Do not include the word "days" or any other unit.

Define Variable

The Define Variable operator allows you to create dynamic values to use in the workflow. This allows users to apply string operators and date transforms to existing values to create a custom variable.

All variable output types are string unless the last applied operation is Get Index. If Get Index is the last operation, the output type is an integer.

If you are currently using the “Beta” Define Variable operator in existing workflows, that operator will continue to work in enabled workflows. However, you will no longer be able to select the “Beta” operator from the left side palette in the workflows builder to use in new workflows.

Each defined variable can have a maximum of 50 operations. Operations are executed in sequential order starting with the initial text or attribute value.

Define Variable supports the following operators:

Operator Description
Operator tab:
Substring Takes the inner portion of a string from the value in Variable A. In the Starts From field, select the number of the first character you want to use in the substring. In the Length field, select the number of characters in the segment you want to use in the substring.
Concatenate Strings Adds a static string to a variable. You must enter a static string in the Variable B field to be added to Variable A.
Trim Trims whitespace from the beginning and ending of input strings. Select the Prefix checkbox to remove whitespace from the beginning of the string. Select the Postfix checkbox to remove whitespace from the end of the string. You can select both.
Replace Finds patterns of characters and replaces them with alternate values. Enter the character patterns you want to find in the Pattern field. Enter the desired alternate values in the Replacement field.
Get Index Finds the location of a specific substring. Enter the substring into the Pattern field.
Date Transforms tab:
Add Time Adds a selected amount of time to Variable A when Variable A is a date. Select a number in the Length field. This is the number of your selected units. In the Unit field, select from Seconds, Minutes, Hours, Days, or Months. The transformed date cannot be more than a year from the original date.
Subtract Time Subtracts a selected amount of time from Variable A when Variable A is a date. Select a number in the Length field. This is the number of your selected units. In the Unit field, select from Seconds, Minutes, Hours, Days, Months, or Years.

The Basic Editor allows users to create custom variables by adding text or attributes and applying operators to the values.

To define a variable using the Basic editor:

  1. Select Create New Variable.

  2. Add a name and select the Editor tab.

  3. Select + Add to add your first value, which is Variable A.

  4. From the Data tab:

    • Select Attribute to enter or choose an attribute.
    • Select Text to enter a text value.

  5. Select Apply.

  6. Select + Add to select an operator.

    • From the Operator tab, choose from:

      • Substring
      • Concatenate Strings
      • Trim
      • Replace
      • Get Index

    • From the Date Transforms tab, choose from:

      • Add Time
      • Subtract Time

  7. Make any necessary selections and select Apply.

    As you make your selections, an example of what your variable will look like appears under each operation and the Variable Preview is updated with the JSON for the variable. You can drag and drop the operations into a different order to change the sequence and how they impact the variable. The examples and preview are updated as you make changes.

  8. Select Save to save your variable.

After you have configured your variable, you can select the Copy icon to copy the JSON for the variable.

The Advanced editor allows more advanced JSON users to create more complex custom variables using JSON.

To define a variable using the Advanced editor:

  1. Select Create New Variable.

  2. Add a name and select the Editor tab.

  3. Switch the toggle to Advanced.

  4. Use JSON to create your custom variable.

  5. Select Save to save your variable.

You can switch the toggle back to Basic and see examples of what your variable looks like. You can drag and drop the operations into a different order to change the sequence and how they impact the variable. The examples and preview are updated as you make changes. If you switch the toggle back to Advanced, the JSON will be updated to show any changes you made in the Basic editor.

After you have configured your variable, you can select the Copy icon to copy the JSON for the variable.

Note

For guidance on supported operator expressions, refer to JSONPath expressions.

Loop

The Loop operator allows you to choose a set of steps to perform on a list of items.

To use the Loop operator, drag a set of steps into the canvas inside the tile. This set of steps can include actions and operators, including choice operators. It must meet many of the same requirements as the workflow itself.

Within the Loop step:

  • All steps must be connected to at least one other step.
  • Each branch within the Loop step must have an end step, so that the loop knows when to finish with an object and restart the set of steps on a new object.
  • This end step within the loop does not replace the end step outside of the loop, which signifies the end of the entire workflow instead of the loop itself.

The steps in a loop are executed on items from the input list in parallel with each other. Items are not guaranteed to be processed in any specific order.

Later actions and operators in the workflow can begin before the loop step has finished iterating over all objects in the list. However, the workflow itself can't end until the loop has finished executing. For this reason, adding additional steps outside of the loop between the Loop operator and the end step is not recommended.

Field Required? Description
Loop Input Yes A JSONPath expression to an array, or list, type attribute from the output of a previous step. The Loop operator will iterate through the objects in this array and perform the steps in the loop on these objects.
Context No A JSONPath expression to another step in the workflow that contains additional data you need to use within the loop. This field allows you to select data from outside of the loop that isn't the loop input.

Refer to the information below for details on the requirements and syntax for the loop's input and context fields.

Loop Input Information

The Loop operator performs a series of steps on a list of items you select using the Loop Input field. When configuring steps within a loop, you can only select data from this Loop Input or from other steps in the loop.

In the Loop Input field, be sure to select an array containing the type of input required by the first step of the loop. For example, if the first step in your loop is Manage Access, select an array of access items such as the accessItems object returned by the Get Access step. The array you select can contain no more than 250 items.

To use this data within the loop's steps, it must be referenced using a JSONPath expression beginning with $.loop.loopInput. You can add attributes to this expression to specify the data from the input the field needs. For example, use $.loop.loopInput.id to select an ID from the array in the Loop Input field.

Loop Context Information

The Context field within the loop step allows you to select data from an additional node prior to the loop so that that data can be used within the loop. Steps that aren't included in the context field or the input can't be used within a loop.

You can reference data from the Context field within the loop's steps using the JSONPath expression $.loop.context. For example, if you selected $.getIdentity within the context field, in reference to a previous Get Identity step, you could use $.loop.context.name to reference the name attribute within the loop.

Take care to select only the data you need for use within the loop to avoid slowing down your workflow's execution.

The loop operator returns a JSON blob when it completes successfully. The results are divided into objects that successfully completed the steps in the loop and objects that failed.

Open "Loop" JSON Sample 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "loopOutput":{
        "failureItems":null,
        "successfulItems":[
            {
                "loopInput":"2c91503771f099950171e65c874d02cd"
            },
            {
                "loopInput":"2c91903771f099950571f65c8ac402fe"
            }
        ]
    }
}

Verify Data Type

The Verify Data Type operator allows you to confirm that the data in a field you select is a specific type, or that it exists at all.

Field Required? Description
Value Yes A JSONPath expression to a variable in the step's input to validate against what you select in Data Type.
Data Type Yes The type of data. At runtime, the attribute in the Value field is compared to the type selected here.

This step can validate whether the value in the selected attribute:

  • Exists
  • Is a boolean
  • Is a number
  • Is a string
  • Is a timestamp
  • Is null

Comparison Operators

In each choice step, two values are compared. You'll see the following options for the Compare Strings and Compare Numbers steps:

  • Contains
  • Equals
  • Is Greater Than
  • Is Greater Than or Equal To
  • Is Less Than
  • Is Less Than or Equal To

Note that the Contains operator is only available for Compare Strings steps.

End Steps

Each workflow must have at least one end step. These steps can be added to stop your workflow and categorize its execution as a success or a failure. Each branch of your workflow must finish with an end step.

The Executions tab on a workflow's details reflects whether each execution ended in success or failure.

Success

Add this step to your workflow to stop the workflow and mark its execution as a success.

It doesn't have any unique fields.

Failure

Add this step to your workflow to stop the workflow and mark its execution as a failure. This step is used to signify that the workflow ended with an error, and workflow tests that end in this step are considered failed tests.

Field Required? Description
Failure Name Yes The name of the step, used for linking steps together.
Failure Details No Details or notes to be included in the workflow's execution results to explain its failure.

To learn more about the process of building a workflow, either in the visual builder or using JSON, visit Building Workflows.

You can also review our lists of triggers and actions for more information about the other steps you can add to your workflow.

Documentation Feedback

Feedback is provided as an informational resource only and does not form part of SailPoint’s official product documentation. SailPoint does not warrant or make any guarantees about the feedback (including without limitation as to its accuracy, relevance, or reliability). All feedback is subject to the terms set forth at https://developer.sailpoint.com/discuss/tos.