Skip to content

Creating and Managing Workflows

A workflow is a set of steps that are completed every time a specific event occurs. Workflows do work for you, automatically performing a series of actions within IdentityNow that you can configure in response to a trigger.

Workflows offer enormous flexibility, allowing you to configure a workflow to take very specific actions each time it runs.

Behind the scenes, workflows are managed using JSON, but most parts of a workflow can be created and managed in the user interface.

This document describes basic information about workflows and details the process of putting one together.

Workflow Terminology

To understand workflows, it helps to understand the parts that go into creating a workflow, and the language used to define it.

  • Data Flow

    Workflows start with a JSON input delivered by the trigger. As this input moves through the workflow, some steps will add additional JSON to it. This JSON that moves between steps is known as data flow.

  • Input

    Each workflow has an input in JSON format, provided by the trigger. This JSON data moves through each step in the workflow. When data enters a step, it becomes input. You can reference any part of this input in most steps using JSONPath, which you can create using the Variable Selector.

  • Steps

    Each workflow is made of a set of discreet steps that are executed chronologically. Each step can add additional data to the workflow in the form of JSON, and that data can be used in future steps.

    There are 3 types of steps:

    • Triggers

      A trigger determines when the workflow runs and provides the initial input used by the rest of the steps in the workflow. Each workflow must have exactly one trigger.

      Some examples of triggers include Account Aggregation Completed, Identity Created, and Source Deleted.

    • Actions

      An action is any task a workflow performs outside of the workflow itself or change it makes to its JSON data. All workflows must have at least one action.

      Some examples of actions include Create Campaign, Get Identity, and Send Email.

    • Operators

      Operators are a broader category of steps that act on the workflow itself by directing the data flow or making conditional choices.

      Any operator that compares two values and makes a choice based on the results of that comparison is known as a choice or comparison step. Some examples of choice operators include Compare Strings and Compare Numbers.

      The Success and Failure end steps are also operators.

  • Inline Variable

    When filling out the fields in a workflow step, most fields allow you to enter a static value or choose a variable from a previous step to use as the complete value for that field. However, in fields that accept text values, you can choose to include a variable from a previous step in your static text value using an inline variable. Review Adding Inline Variables to Text Fields for details.

Building a Workflow

To build an automated workflow in SailPoint's cloud services, you can use the visual builder or you can configure a workflow using JSON.

To begin building a workflow:

  1. From the Admin interface, go to Workflows.

    The list of workflows is displayed.

  2. Select + New Workflow.

    The file upload utility at the top of the screen, with a file uploaded. A name and description are displayed in fields below.

    To base your new workflow on an existing workflow, refer to Duplicating a workflow.

  3. Choose how you'd like to build your workflow.

    • Start with a Template allows you to choose a pre-configured set of steps and make changes to them based on the needs of your business.
    • Start in the Workflow Builder brings you to a canvas where you can drag and drop individual steps to create a brand new workflow.
    • Start with a JSON File lets you upload a workflow in JSON format. You can reuse the JSON from another workflow using this option. In some cases, you can modify workflows created using this method in the workflow builder.

The maximum allowed size for a workflow definition is 400KB. The maximum allowed size for a workflow definition plus its input is 1.5MB.

Building a Workflow from a Template

To start a workflow based on a template, create a workflow and choose Start with a Template.

  1. Choose which template you'd like to start with.

    This list of templates is subject to change. Some templates require integration with SaaS Management or Data Intelligence. For more information about Workflows and SaaS Management, refer to SaaS Management's documentation.

  2. Enter a unique name and description for your workflow.

    Select Continue to Builder.

    The workflow builder is displayed, containing the workflow you chose in the list of templates.

  3. Select each step in the workflow and configure its fields. Review Tips for Navigating the Workflow Builder for details about using this interface.

    You can remove or add steps as necessary.

  4. Select Save to save your workflow.

    Your new workflow is saved independent of the template. The original template can be reused to create additional new workflows. Any future changes SailPoint makes to this template do not impact workflows you have already created.

Building a Workflow in the Visual Builder

The visual workflow builder allows complex workflows to be built with a minimal amount of code.

The workflow visual builder. There are panels on either side of a canvas.

  1. To configure a new a workflow using the visual builder, create a workflow and choose Start in the Workflow Builder.

  2. Enter a unique name and description for your workflow.

    Select Save. The Workflow Builder is displayed.

    On the left, a list of steps is displayed. You can use the tabs to view all steps or a list of triggers, actions, or operators.

  3. Select the trigger you want to use to kick off your workflow and drag it into the canvas in the middle. Refer to Triggers for a list of the triggers you can choose and descriptions of when they are fired.

    Some triggers require you to fill out one or more additional fields before proceeding. This list appears in the right panel when you place the step on the canvas.

    The Filter field is always optional. This field allows you to narrow down the circumstances under which this workflow will run. Review Using Trigger Filters for details.

  4. Select the Actions tab and choose one or more actions to take place when your workflow is triggered.

    Refer to Actions for a list of the actions you can choose from, as well as the fields required in each action.

    To fill out the fields for each action, select whether you want to use a static value every time the workflow runs or a variable that comes from a previous step.

    • If you select Choose Variable, you'll be able to choose an attribute added by any previous step in your workflow. At runtime, the value of that attribute will be used in this field. To review the JSON that each step can add to workflows, read Workflow Steps and Definitions. Review Selecting a Value Using the Variable Selector for details on how to select a field.
    • If you choose Enter Value, you'll type in a static value that will be used in this step every time it's executed. If you select this option, type the value into the field. When entering a value in a string field, you can use JSONPath to include a variable within that field. Review Adding Inline Variables to Text Fields for details.
  5. To connect the trigger to the first action, select the dot below the trigger on your canvas and drag your mouse toward the action. A line appears between them, indicating the two steps are connected.

    Be sure to drag from one step to the step that comes next in your workflow, chronologically. The direction of the line determines the chronological order in which the steps will be executed.

    Two steps, with an arrow pointing from the trigger to an action to represent dragging.

    All steps in your workflow must be connected to at least one other step. Each branch must merge back into the main flow or end in a Success or Failure step.

  6. Select the Operators tab and add operators where applicable.

    Comparison operators let you configure two potential paths for your workflow to take based on the data present in a workflow during any given execution.

  7. In the Value 1 field, select a variable using the Variable Selector or enter a JSONPath expression to choose the field you want to use. When your workflow is run, the value of this field will be compared to what you choose for Value 2.

  8. In the Operator field, choose how you want to compare Value 1 to Value 2.

  9. In the Value 2 field, you can enter a value two different ways:

    • Select the Enter Value option in the dropdown list and enter the value that should be used every time this step runs.
    • In the dropdown list, select Choose Variable. You can use this field in two ways:
      • Select another variable from the input using the Variable Selector
      • Enter a JSONPath expression to choose another variable from the step's input

    When your workflow runs, if the operator finds a match based on the criteria you configured, the workflow takes the true path. If a match isn't found, the workflow takes the false path.

    Example

    Following the action Get Certification, you might want to start the campaign if it's in the STAGED state, but generate it if it's in the SAVED state.

    In this example, you'd choose a Compare Strings operator. In the Value 1 field, select the status of the campaign you retrieved in a previous step. Select the Open Variable Selector button and choose the Get Certification Campaign step in the dropdown list. Select the status attribute in the list on the right. This allows you to compare the status of the campaign in the workflow to a value you enter in Value 2. In this example, in the Operator field, you'd choose one of the comparison operators available for Compare Strings.

    If the value of the status attribute is STAGED, the result of the comparison is True. If not, the result of the comparison is False.

    The details panel of a comparison operator, with all fields completed.

    Once you've entered the values to compare in your operator, add steps to your workflow for both branches after this operator. Click and drag from the true node to the next step you want your workflow to take if it finds a match, and drag from the false node to the step you want to take if there isn't a match.

    For example, you can choose an Activate Campaign step to follow the Get Campaign step if the campaign's status is STAGED. If the campaign's status is anything else, you can choose to send the workflow to a Failure step so that it doesn't continue.

    A workflow step with two paths leading away from it.

    Remember that each branch of your workflow must have an end step.

  10. Continue adding and connecting actions and operators until your workflow has the steps it needs to accomplish its task.

    Review Tips for Navigating the Workflow Builder for details about using this interface.

    A completed workflow must have:

    • Exactly one trigger
    • One or more actions
    • One or more end steps - a success or failure step for each branch of your workflow

    All steps in your workflow must be connected to the main workflow.

    Each step can have exactly one parent step leading in to it, with the exception of End Steps. If you need to use data from multiple steps in an action or operator, those steps can be executed prior to the action or operator in which you need them. That data will be included in all future steps.

    As you work, you might see validation errors at the bottom of your screen. All validation errors must be resolved before you can test or enable your workflow.

  11. Select Save.

    After saving your workflow, it can be tested. Be sure to test your workflow before enabling it.

    Note

    Workflows with validation errors such as missing fields or syntax errors can be saved, but not tested. This allows you to save and return to a workflow while building it.

Selecting a Value Using the Variable Selector

Most workflow steps have fields you'll need to fill out in order for your workflow to run correctly.

You can use dynamic data for each field by choosing a JSON attribute from any previous step in the workflow. When the workflow runs, the value of that attribute will be used as the value of the field.

You can choose which attribute to use in the Variable Selector.

  1. In the Workflow Builder, select the step that has the field you need to fill in.

  2. In the dropdown list beside the field name, select the down carat and select Choose Variable.

  3. Select Open Variable Selector.

  4. In the Select Step dropdown list, select the step that added the data you want to use. Review Workflow Steps and Definitions for a list of all possible steps. The JSON samples provided with the steps reflect the attributes displayed in step 5.

    Note

    You can only reference data provided by steps that occur earlier in the workflow than the step you're working with. Steps that take place later in the workflow are not displayed in this list.

    A list of attributes is displayed on the right. These are the attributes provided by the step you selected.

  5. Select the radio button next to the attribute you want to use.

  6. Select Save.

    When your workflow runs, the value of the attribute you selected in step 5 is used in that field.

The Variable Selector generates a JSONPath expression. You can learn more about the Goessner implementation of JSONPath, used in actions and operators, at goessner.net. You can use the evaluator at jsonpath.com to practice and test your JSONPath expressions against sample inputs. Note that this implementation is not used for trigger filters.

Adding Inline Variables to Text Fields

You can add variables inline to any field that uses a string input. For example, you can add an inline variable to the Send Email step to include the user's username in the email, or add an account name to the body of the HTTP Request step.

In general, when placing an inline variable, use JSONPath format: {{ $.stepName.variableName }}. Each inline variable requires two sets of curly braces, as well as the $ and the period immediately after it. If any of these characters are missing, or if more than one variable is included in a single set of braces, the string might render as plain text at runtime. The spaces on either side of the variable are optional. Each step's technical name can be found in the workflow's execution history.

When using a variable that comes from the same step you're working in, it's not necessary to include the step name.

Example Variable Description
{{$.recipientEmailList}} Adds the list of email recipients from the Send Email step to a text field within the same step.
{{$.hTTPRequest.Body}} Adds the complete contents of the Body field in the HTTP Request step to a text field in any later step in the workflow.
{{$.trigger.identityId}} Adds the technical ID of an identity provided by the trigger to a field.

SailPoint's variable selector can be used in any field to choose variables. Those variables can be copied and added to the plain text field inside of curly brackets to use as inline variables.

Using Trigger Filters

You can narrow down the circumstances under which your workflow will be triggered.

When you select the trigger for your workflow, the Filter field is displayed. Enter a JSONPath expression using the Jayway implementation. Note that this is not the same implementation used to select values in actions and operators.

For more information and examples of trigger filters, review our Event Trigger Filter Syntax.

The following examples filter workflow triggers:

Example Description
$[?($.identity.name == "john.doe")] The trigger will fire only when the identity's name attribute is john.doe.
$.changes[?(@.attribute == "department")] Causes the Identity Attribute Changed trigger to fire only when the department attribute has changed.
$.changes[?(@.attribute == "cloudLifecycleState" || @.attribute == "department")] Causes the Identity Attribute Changed trigger to fire when either the cloudLifecycleState attribute has changed or when the department attribute has changed.
$[?($.attributes.isManager == "false")] Causes the trigger to fire when the relevant identity is not a manager. This filter applies to identity-focused triggers such as Identity Created or Identity Deleted.
$[?($.attributes.isManager == "false" && $.attributes.department == "Sales")] Causes the trigger to fire when the relevant identity is not a manager and is in the Sales department. This filter applies to identity-focused triggers such as Identity Created or Identity Deleted.
$[?($.attributes.isManager == "false" || $.attributes.inactive == "true")] Causes the trigger to fire when the relevant identity is not a manager, or if the identity is in an inactive state. This filter applies to identity-focused triggers such as Identity Created or Identity Deleted.

Tips for Navigating the Workflow Builder

  • To move a step after you've placed it on the canvas, select the Drag Handle icon to drag the step.
  • To move your view around the canvas, select a blank part of the canvas with your mouse and drag.
  • To recenter your workflow on the canvas and align the steps, select the Center button at the bottom of the screen.

  • Select the + or - icons to zoom in or out of your workflow.

  • To delete a step, select it in the canvas and press the Delete button on your keyboard.
  • To delete a connection between two steps, select the line connecting them and press the Delete button on your keyboard.
  • To undo an action, press Control-Z or Command-Z on your keyboard. You can also select the Undo and Redo buttons at the bottom of the canvas.
  • To include a loop in your workflow, use the Loop operator.

Building a Workflow in JSON

Once you've created a workflow and chosen Start with a JSON File, you can build your workflow manually using JSON.

All workflows are made of JSON. They can be edited manually in the JSON file and re-uploaded, so you can create extremely flexible workflows to fit your organization's needs.

JSON Workflow Requirements

Your JSON workflow must meet the following criteria:

  • It must begin with the appropriate metadata, including a unique name and description, as found in Workflow Steps and Definitions.
  • It must contain exactly one trigger.
  • All steps, excluding the trigger, must be within the steps object of the workflow JSON.
  • It must contain at least one action.
  • Each step, besides the trigger and any end steps, must specify a next step using the name of the step that should be executed next.
  • Each branch of the workflow after choice steps must specify an end step.

Some parts of a workflow are required under certain conditions.

  • If your workflow contains a choice operator, it must specify a default step to execute next if the input doesn't meet any of the criteria specified in the choice step.

After uploading a metadata file and selecting Continue as described in Building a Workflow, the Workflow Builder is displayed.

To create a workflow using JSON:

  1. Obtain the JSON for each step you want to include in your workflow by dragging each step into the canvas as described in Building a Workflow in the Visual Builder.

  2. Select Save, then select the Download icon . Select the Download Script option.

  3. Open the workflow script in the editor of your choice and make changes.

    When you've finished editing, save your workflow file.

  4. In your browser, in the list of workflows, select the name of the workflow you want to edit.

  5. Select Upload New Script. Choose the file you edited in step 3.

  6. Select Save.

    After saving your workflow, you can test it to make sure it works the way you want it to. Be sure to test your workflow before enabling it.

Adding Inline Variables to Text Fields

You can add variables inline to any field that uses a string input. For example, you can add an inline variable to the Send Email step to include the user's username in the email, or add an account name to the body of the HTTP Request step.

In general, when placing an inline variable, use JSONPath format: {{ $.stepName.variableName }}. Each inline variable requires two sets of curly braces, as well as the $ and the period immediately after it. If any of these characters are missing, or if more than one variable is included in a single set of braces, the string might render as plain text at runtime. The spaces on either side of the variable are optional. Each step's technical name can be found in the workflow's execution history.

When using a variable that comes from the same step you're working in, it's not necessary to include the step name.

Example Variable Description
{{$.recipientEmailList}} Adds the list of email recipients from the Send Email step to a text field within the same step.
{{$.hTTPRequest.Body}} Adds the complete contents of the Body field in the HTTP Request step to a text field in any later step in the workflow.
{{$.trigger.identityId}} Adds the technical ID of an identity provided by the trigger to a field.
owner.name:{{$.getIdentity.name}} Adds a search query to the field that returns all access items that belong to the identity returned by the Get Identity step. For example, this can be used in the Get Access step.

SailPoint's variable selector can be used in any field to choose variables. Those variables can be copied and added to the plain text field inside of curly brackets to use as inline variables.

Testing a Workflow

When you test a workflow, the test uses the data you've provided to execute the workflow in its entirety. This includes creating any accounts, sending any emails, or starting any certification campaigns depending on the workflow's steps. This allows you to be sure your workflow is executing correctly before enabling it in your site.

If your workflow has validation errors, those must be resolved before you can test your workflow.

To test a workflow:

  1. Select the workflow you want to test from the list of workflows and select Edit Workflow.

  2. Select Test Workflow at the top of the editor.

    The Test Workflow overlay is displayed.

    You can also test your workflow while you're working on it, after selecting Save.

  3. In the Test Workflow overlay, find all IDs within the Trigger Input.

    These IDs must be replaced with valid IDs from your site and they must be the correct kind of data. For example, identity IDs must be replaced with the technical IDs of identities, and the IDs of access items must be replaced with valid access items from your site.

    You can create test data in your site to use when testing workflows. You can find these IDs in Search. If the technical IDs aren't displayed when you open Search, open the Column Chooser and make sure the ID checkbox is selected.

    If your workflow doesn't take any destructive actions such as deleting access or disabling accounts, you can also choose to use your own identity ID in place of any identity IDs in you workflow.

    Important

    Testing your workflow executes the actions based on the data provided, including completing the actions listed. Use caution to avoid adding, changing, or removing any access from live identities.

  4. When you are ready, select Start Test.

    A confirmation dialog is displayed. Select Continue.

    Your workflow test begins. You can track its progress by following the blue line on your workflow diagram to see which steps have been executed, which are in progress, and the path your workflow test is taking.

  5. When your workflow test completes with a Success step, you can review the overall results of your workflow in the panel on the right.

    You can also select individual steps from the canvas to review the data that was input to the step, as well as the output of the step once it was completed.

    When testing a workflow loop, you can see the results of the loop on each item in its list of inputs by selecting the Loop operator. You can select the individual items from the list to review additional details.

    Click anywhere on the canvas outside of any steps, or select the Test Overview button to refer back to the results of the workflow test as a whole.

The Test Workflow screen. Sample input is in a box above the Start Test button.

If your workflow test succeeds, you can enable your workflow from the list of workflows.

If your test fails, the step the workflow failed on is highlighted and an error is displayed. If your workflow error was related to the test input, select Start New Test to edit your test input and run your test again.

If your workflow error is related to a step's configuration, select the X icon to go back to the workflow builder and keep working.

When your workflow test completes with a Failure step, the test is considered a failed test and the results of the failure step are displayed.

Validation Errors

As you build a workflow in the visual builder, validation errors related to the workflow construction are displayed at the bottom of your screen.

All validation errors must be resolved before you can save, test, or enable your workflow.

Reviewing and Maintaining Workflows

From the Workflows page, you can review some data about each workflow in your site. This includes information such as the number of times each workflow has run successfully and the rate of errors for each workflow. From this page, you can download the workflow's script or enable and disable it.

You can also view and edit individual workflows, as well as delete them.

To view and edit a workflow:

Workflows must be disabled before they can be edited.

  1. From the Admin interface, go to Workflows.

  2. Select the name of the workflow you want to view.

    You can review a number of details about the workflow, including the uploaded file, its name and description, when it was created, and who created it.

  3. Select the Executions tab to review details about the last 50 times the workflow was executed.

    These details include the rendered text for any valid inline variables, as well as the variable itself.

  4. To edit the workflow, select its name and go to the Details tab. You can edit the workflow's name and description here. Select Upload New Script to replace the workflow's JSON file with an updated version, or select Edit Workflow to go to the visual builder.

  5. When you have finished making your changes, select Save.

    Your changes are incorporated the next time the workflow begins running.

To download workflow metadata:

You can download a record of your workflow's steps at any time.

  1. From the Admin interface, go to Workflows.

    You can select the Download icon beside the name of the workflow you want to edit to download the workflow's JSON directly.

    The list of workflows. In the Actions column, the Download Workflow Definition button is highlighted.

    You can view additional options while editing a workflow.

  2. Select the workflow you want to edit and select Edit Workflow.

  3. Select the Download icon and choose whether to download an image of the workflow diagram as it appears on the canvas below, or the JSON body of the workflow.

To duplicate a workflow:

From the list of workflows, select the Duplicate Workflow icon beside the workflow you want to copy.

A new workflow appears at the top of the list of workflows, titled Copy of followed by the original workflow's name. You can then edit this workflow to meet your needs.

To delete a workflow:

  • Select the Delete icon beside the workflow you want to delete on the Workflows page.
  • Select the name of the workflow you want to delete, then select the Delete icon on the Details page.