PingOne Advanced Identity Cloud

Workflow nodes

When you define a workflow, you specify each task through a node.

Identity Governance provides several nodes that allow you to customize your workflow.

For information on how to place nodes in a workflow, refer to workflow editor canvas.To use an If/else node or Switch node, you must set outcomes in the script.

For a comprehensive example of using the following nodes, refer to Workflow use cases.

Approval node

Requires a user’s input in the workflow. Define:

  • User(s) to approve the access request

  • What to do when the request expires. The end user defines the expiration when they create the access request.

  • Notifications to send.

Outcomes

  • Approved

  • Reject

Evaluation continues along the Approved outcome path if any of the defined approvers approve the request.

Evaluation continues along the Reject outcome path if any of the defined approvers reject the request.

Properties

Property Usage

Approvers

Select user(s) that must approve the access request.

  1. Select add.

  2. Select the approver type.

  3. Select the approver permissions for the access request.

  4. Click Add.

    To add more users to this task, repeat steps 1-4.

To define custom approvers that aren’t listed in step 2, click define a script > edit and write a JavaScript script.

Form

Select dynamic forms or choose a specific form to present to the reviewer.

  • Dynamic form selection.

  • Choose a form.

Expiration Settings

The end user defines the expiration when they create the access request. Select one of the following:

Reject request

Reject the access request.

Reassign request

Reassign the request to another user or role.

Do nothing

Take no action.

Notification Settings

Select which email notifications to send. By default all notifications are enabled. Select any of the following:

Assignment notification

Initial email to the approver(s) of a resource when an end user submits an access request. The default email template is Request Assigned. Select the email template to send.

Reassignment notification

Email to the new assignee when an approver forwards a request item. The default email template is Request Reassigned. Select the email template to send.

Assignee reminders

Email to the approver(s) as a reminder that they have a request item to act on. The default email template is Request Reminder.

  • Select the email template to send.

  • Define the frequency to send the reminder.

Escalation notification

Email to an individual assigned as the escalation point of contact. The default email template is Request Escalated.

  • Select the email template to send.

  • Define the frequency to send the escalation.

  • Select the user or role to send the escalation to.

Expiration notification

Email to the approver(s) when a request item expires. The default email template is Request Expired.

  • Select the email template to send.

  • Specify when to send the notification to the approvers (in days) before the request expires.

Fulfillment node

The Fulfillment node assigns a fulfillment task to users, requiring them to manually complete of a governance task. In this case, an authorized user reviews the task details and marks it as complete. Workflows using the fulfillment node should also include flows to suspend the process while waiting for a response.

Administrators can use the Fulfillment node in chain tasks or used in conjunction with the Switch node to implement serial or parallel flows.

The Fulfillment node enables the complete orchestration of end-to-end lifecycles and event-driven flows.

Outcomes

  • FULFILL

  • DENY

Properties

Property Usage

Reviewers

Select user(s) that must approve the access request.

  1. Select add.

  2. Select the approver type.

  3. Select the approver permissions for the access request. Options are:

    • Fulfill

    • Reassign

    • Deny

    • Comment

  4. Click Add.

    To add more users to this task, repeat steps 1-4.

To define custom approvers that aren’t listed in step 2, click define a script > edit and write a JavaScript script.

Form

Allow dynamic form selection or choose a specific form to present to the reviewer.

Dynamic form selection

Select a dynamic form.

Choose a form

Select a form.

Expiration Settings

The end user defines the expiration when they create the access request. Select one of the following:

Reject request

Reject the access request.

Reassign request

Reassign the request to another user or role.

Do nothing

Take no action.

Notification Settings

Select which email notifications to send. By default all notifications are enabled. Select any of the following:

Assignment notification

Initial email to the approver(s) of a resource when an end user submits an access request. The default email template is Request Assigned. Select the email template to send.

Reassignment notification

Email to the new assignee when an approver forwards a request item. The default email template is Request Reassigned. Select the email template to send.

Assignee reminders

Email to the approver(s) as a reminder that they have a request item to act on. The default email template is Request Reminder.

  • Select the email template to send.

  • Define the frequency to send the reminder.

Escalation notification

Email to an individual assigned as the escalation point of contact. The default email template is Request Escalated.

  • Select the email template to send.

  • Define the frequency to send the escalation.

  • Select the user or role to send the escalation to.

Expiration notification

Email to the approver(s) when a request item expires. The default email template is Request Expired.

  • Select the email template to send.

  • Specify when to send the notification to the approvers (in days) before the request expires.

If/else node

To use this node, there must be a preceding Script node that sets at least one outcome.

Also referred to as an exclusive gateway, this node has the outcomes validationSuccess and ValidationFailure. Once a condition evaluates to true, the node stops evaluating and takes that outcome.

Outcomes

  • validationSuccess

  • validationFailure

Evaluation continues along the validationSuccess outcome path when the defined condition is met.

Evaluation continues along the validationFailure outcome path when the defined condition is met.

Properties

Property Usage

Outcomes

Specify which outcome (defined in a preceding Script node) meets the condition. Set the following properties:

check validationSuccess

  1. Click validationSuccess.

  2. Add the outcome condition that correlates to valdiationSuccess. For example, if the outcome set in the Script node is failureReason, you could set the script to the following:

    failureReason === null;

    This implies there isn’t a failure with validation since the preceding script didn’t set the failure reason.

  3. Click Update.

close validationFailure

  1. Click validationFailure.

  2. Add the outcome condition that correlates to valdiationFailure. For example, if the outcome set in the Script node is failureReason, you could set the script to the following:

    failureReason != null;

    This implies that the validation failed since the failure reason is present.

  3. Click Update.

Switch node

You must precede this node with a Script node that sets two or more outcomes.

The Switch node (also referred to as an inclusive gateway) lets you script two or more conditional outcomes. Any or all conditions can be true.

The Switch node and If/else node both evaluate conditions. However, the Switch node continues evaluating conditions after one condition is met.

Outcomes

  • Choice 1

    …​

  • Choice n

Properties

Property Usage

Name

The name of the node.

The name must be alphanumeric with no spaces or special characters.

Outcomes

Specify the outcome paths based on the output of the preceding Script node.

  1. Click add.

  2. Enter the following details:

    • Name — Enter a name for the outcome. Name this property to correlate logically to the outcome from the Script node. For example, if an application grant access request has an application glossary attribute called Risk Level` that’s set to High, name this outcome riskLevelHigh``.

    • Script — Define a script to meet the condition. For example, if the preceding Script node retrieves a role’s riskLevel variable, then you can set the Switch node’s outcome to the following:

      high
riskLevel == "high";

      If the condition is met, the Switch node continues down the outcome path and continues evaluating the other conditions set in additional outcomes.

  3. Click Add.

  4. Define the rest of your outcomes by repeating steps 1-3. For example, you can add additional outcomes respectively for riskLevel, so that all riskLevel conditions are met:

    medium
riskLevel == "medium";

low
riskLevel == "low";

null
riskLevel == "null";

Require multiple approvals in parallel

You can use a Switch node to evaluate multiple paths instead of nesting multiple If/else nodes. However, you can also use a Switch node to send multiple approval paths in parallel. For example, you can send an approval to the role owner of a role and to an end user’s manager at the same time. Only when both approvals are approved can the workflow proceed.

To achieve this:

  • There must be a proceeding Script node before the Switch node.

  • A switch node must set two or more outcomes with their respective scripts set to true.

  • Each outcome of the Switch node routes to an Approval node.

  • The Approve outcome of each Approval node must route to an additional Switch node.

  • The additional Switch node must only have one outcome with the script set to true.

An example of using a Script node to have multiple approvals in parallel.

You can find a detailed example of using a Switch node for parallel paths in Role grant workflow example.

Script node

Write custom logic in a workflow with the Script node.

The logic you write depends on the task you are trying to achieve.

For example, you can write a script to set parameters to deny an access request, or you can write a script that sets outcomes you can use in conjunction with an If/else node or Switch node.

Outcomes

Single outcome path; however, you will often set outcomes in the script that you will use with the If/else node or Switch node.

Properties

Property Usage

Script

Define your custom logic by writing a JavaScript script.

  1. Click edit.

  2. Write the script. To use an If/else node or Switch node, you must set outcomes in the script.

    For example, the following sets the outcome failureReason:

    failureReason = "Validation failed: Error reading application with id " + applicationId + ". Error message: " + e.message;

execution.setVariable("failureReason", failureReason);

    Now that the failureReason outcome has been set, use it in the If/else node or Switch node.

When an access request is created, the relevant data is stored in a request object. The data accessible through the script node varies depending on the type of access request. For example, an application grant workflow contains information about the application whereas a role grant workflow contains information about the role.

Potential scenarios

The following scenarios reference the request object. To view all properties available in the request object, use the REST API endpoint iga/governance/requests/requestId. For more information, refer to Identity Governance-related APIs.

Identity Governance attributes can be referenced using PingIDM functions, such as reading a resource using openidm.read or openiam.action. For more information, refer to Functions available in identity-related scripts.

For an application grant request, grab the application ID and name submitted in the request:

var content = execution.getVariables();                                                     1
var requestId = content.get('id');
var app = null;
var applicationName = null;

var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});     2
applicationId = requestObj.application.id;
app = openidm.read("managed/alpha_application/" + applicationId);                           3
applicationName = app.name;                                                                 4

  • 1 To leverage the workflow process variables from when the request was created, grab the variables and put them into the content variable. For an access request, the only variable passed is the id.

  • 2 Obtain information about the access request using a /governance endpoint.

  • 3 Using the openidm.read function, grab all data associated to the application and store it in a local variable, app.

  • 4 Grab the application name.

For an application grant request, grab the value of the custom created glossary attribute, riskLevel:

var content = execution.getVariables();                                                             1
var requestId = content.get('id');
var appId = null;
var appGlossary = null;
var riskLevel = null;

var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});             2
appId = requestObj.application.id;
appGlossary = openidm.action('iga/governance/application/' + appId + '/glossary', 'GET', {}, {});   3
riskLevel = appGlossary.riskLevel;                                                                  4

  • 1 To leverage the workflow process variables from when the request was created, grab the variables and put them into the content variable. For an access request, the only variable passed is the id.

  • 2 Obtain information about the access request using a /governance/requests endpoint.

  • 3 Using the application id grabbed from the iga/governance/requests endpoint, obtain information about the glossasry attributes for the application using the iga/governance/application endpoint.

  • 4 Grab the glossary attribute, riskLevel, and store it in a local variable, riskLevel. The glossary name riskLevel comes from the name that you define when you create a glossary attribute.

For an application grant, access the requester user properties. In this scenario, access the frIndexedString1 property which correlates to a user’s line of business (LOB):

var content = execution.getVariables();                                                     1
var requestId = content.get('id');
var user = null;
var lineOfBusiness = null;

var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});     2

user = openidm.read("managed/alpha_user/" + requestObj.user.id);                            3

lineOfBusiness = user.frIndexedString1;                                                     4

  • 1 To leverage the workflow process variables from when the request was created, grab the variables and put them into the content variable. For an access request, the only variable passed is the id.

  • 2 Obtain information about the access request using a iga/governance/requests endpoint.

  • 3 Using the openidm.read function, put the user;s data into the requester variable.

  • 4 Grab line of business the user is in, which is stored in the property frIndexedString1.

For an entitlement grant request, grab the entitlement ID and name submitted in the request:

var content = execution.getVariables();                                                     1
var requestId = content.get('id');
var requestObj = null;
var entitlementName = null;
var entitlementId = null;

requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});         2
entitlementName = requestObj.descriptor.idx./entitlement.displayName;                       3
entitlementId = requestObj.assignment.id;                                                   4

  • 1 To leverage the workflow process variables from when the request was created, grab the variables and put them into the content variable. For an access request, the only variable passed is the id.

  • 2 Obtain information about the access request using a iga/governance/requests endpoint.

  • 3 Grab the entitlement name from requestObj. The entitlement.displayName is derived from the display name attribute on the application’s entitlement object. For more information, refer to populate entitlement object display name.

  • 4 Grab the entitlement id from the requestObj.

    The assignment.id is unique whereas the entitlement.id isn’t. The entitlement object is raw data from the application. Applications with the same entitlement.id can cause collisions if you reference entitlement.id in your scripts. Therefore, make sure to reference the assignment.id when you want to reference an entitlement.

For a role grant request, grab the role ID and name submitted in the request:

var content = execution.getVariables();                                                 1
var requestId = content.get('id');
var requestObj = null;
var roleId = null;
var role = null;
var roleName = null;

requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});     2
roleId = requestObj.role.id;
role = openidm.read("managed/alpha_role/" + roleId);                                    3
roleName = role.name;                                                                   4

  • 1 To leverage the workflow process variables from when the request was created, grab the variables and put them into the content variable. For an access request, the only variable passed is the id.

  • 2 Obtain information about the access request using a iga/governance/requests endpoint.

  • 3 Using the openidm.read function, grab all data associated to the role and store it in a local variable, role.

  • 4 Grab the role name.

Violation node

Assigns a compliance violation task to users. Workflows using the Violation node can better route violation handling in your company.

You can use the node in chain tasks or used in conjunction with the Switch node to implement serial or parallel flows.

Outcomes

  • Remediate

  • Allow

  • Expiration

Properties

Property Usage

Name

Violation Task

Actors

Select user(s) who acts on the violation.

  1. Click .

  2. Select the actor type. Options are:

    • Role

    • Manager

    • Violation owner

  3. Select the user.

  4. Select the permissions for the access request. Permissions are:

    • Allow

    • Exception

    • Remediate

    • Reassign

    • Comment

  5. Click Add.

    To add more users to this task, repeat steps 1-4.

    To define custom approvers that are not listed in step 2, click define a script > edit, write a JavaScript script, and click Update.

    Click to display a custom script example that returns an array of actors 
    (function() {
    var content = execution.getVariables();
    var requestId = content.get('id');
    var requestIndex = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
    return [{
        "id": "managed/user/" + requestIndex.applicationOwner[0].id,
        "permissions": {
            "approve": true,
            "reject": true,
            "reassign": true,
            "modify": true,
            "comment": true
        }
    }];
})()

Expiration Settings

Define what to do when the violation expires. Options are:

Reject request

Reject the access request.

Reassign request

Reassign the request to another user or role.

Do nothing

Take no action.

Notification Settings

Select which email notifications to send. By default all notifications are enabled. Select any of the following:

Assignment notification

Initial email to the approver(s) of a resource when an end user submits an access request. The default email template is Request Assigned. Select the email template to send.

Reassignment notification

Email to the new assignee when an approver forwards a request item. The default email template is Request Reassigned. Select the email template to send.

Assignee reminders

Email to the approver(s) as a reminder that they have a request item to act on. The default email template is Request Reminder.

  • Select the email template to send.

  • Define the frequency to send the reminder.

Escalation notification

Email to an individual assigned as the escalation point of contact. The default email template is Request Escalated.

  • Select the email template to send.

  • Define the frequency to send the escalation.

  • Select the user or role to send the escalation to.

Expiration notification

Email to the approver(s) when a request item expires. The default email template is Request Expired.

  • Select the email template to send.

  • Specify when to send the notification to the approvers (in days) before the request expires.

Email node

You can add an email node to your Identity Governance workflow that sends an email using a notification template.

Outcomes

  • Success

  • Failed

Properties

Property Usage

Name

Add a display name for the email node.

Notification Template

Select a notification template for the email. To view an email template on the Identity Cloud analytics dashboard, go to: Email > Templates.

  • To: Enter a user ID for the email’s recipient, or click define a script.

  • Cc: Enter a user ID to send a copy of the email to another recipient, or click define a script.

  • Bcc: Enter a user ID to send a blind carbon copy (Bcc) of the email to another recipient, or click define a script.

Message substitution

Pass message variables into your email node template.

You can use the Message substitution field to pass in a variable:

  1. Click Message substitution.

  2. On the Message substitution modal, enter one or more variables in a JSON object. For example, if your email template has a variable:

    One or more certification tasks for {{object.givenName}} have been escalated to you.

    You can pass in the variable:

    {"givenName": "Amy"}

    Or if you have multiple variables in the email template:

    One or more certification tasks for {{object.givenName}} {{object.surName}} have been escalated to you.

    You can pass in variables as follows:

    {
    "givenName": "Amy",
    "surName": "Smith"
}

  3. Click Update.