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.
To understand workflows, it helps to understand the parts that go into creating a workflow, and the language used to define it.
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.
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.
You can learn more about the Goessner implementation of JSONPath, which SailPoint uses, at goessner.net. You can use the evaluator at jsonpath.com to practice and test your JSONPath expressions against sample inputs.
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:
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.
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 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.
Building a Workflow
To build an automated workflow in SailPoint's cloud services, you can use visual builder or you can configure a workflow using JSON.
To begin building a workflow:
From the Admin interface, go to Workflows.
The list of workflows is displayed.
Select + New Workflow.
To base your new workflow on an existing workflow, refer to Duplicating a workflow.
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. This feature is subject to change.
- 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.
Building a Workflow from a Template
To start a workflow based on a template, create a workflow and choose Start with a Template.
Choose which template you'd like to start with.
This list of templates is subject to change.
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.
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.
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
To configure a new a workflow using the visual builder, create a workflow and choose Start in the Workflow Builder.
The visual workflow builder allows complex workflows to be built with a minimal amount of code.
After creating a workflow as described in To begin building a workflow, 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.
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 let go of 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.
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 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 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.
If you chose Enter Value, type the value in the field. If you selected Choose Variable, you can review Selecting a Value Using the Variable Selector for details on how to select a field.
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.
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.
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.
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.
In the Operator field, choose how you want to compare Value 1 to Value 2.
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
truepath. If a match isn't found, the workflow takes the
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
statusattribute 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.
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
truenode to the next step you want your workflow to take if it finds a match, and drag from the
falsenode 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.
Remember that each branch of your workflow must have an end step.
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.
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.
After saving your workflow, it can be tested. Be sure to test your workflow before enabling it.
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.
In the Workflow Builder, select the step that has the field you need to fill in.
In the dropdown list beside the field name, select the down carat and select Choose Variable.
Select Open Variable Selector.
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.
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.
Select the radio button next to the attribute you want to use.
When your workflow runs, the value of the attribute you selected in step 5 is used in that field.
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 Goessner implementation.
The following examples filter workflow triggers:
||The trigger will fire only when the identity's name attribute is
||Causes the Identity Attribute Changed trigger to fire only when the department attribute has changed.|
||Causes the Identity Attribute Changed trigger to fire when either the cloudLifecycleState attribute has changed or when the department attribute has changed.|
||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.|
||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.|
||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.|
For more information and examples, review our Event Trigger Filter Syntax.
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 it 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.
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
stepsobject 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:
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.
Select Save, then select the Download icon . Select the Download Script option.
Open the workflow script in the editor of your choice and make changes.
When you've finished editing, save your workflow file.
In your browser, in the list of workflows, select the name of the workflow you want to edit.
Select Upload New Script. Choose the file you edited in step 3.
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.
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:
Select the workflow you want to test from the list of workflows and select Edit Workflow.
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.
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.
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.
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.
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.
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.
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.
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.
From the Admin interface, go to Workflows.
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.
Select the Executions tab to review details about the last 50 times the workflow was executed.
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.
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.
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.
You can view additional options while editing a workflow.
Select the workflow you want to edit and select Edit Workflow.
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.