cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 

API to set global reminders and escalation policies for access request approvals

API to set global reminders and escalation policies for access request approvals

If an approver assigned to an access request has not taken action on it, you need the ability to automatically remind them that their review is required. If too much time passes, you need to be able to escalate the issue by sending information to someone who can enforce your approval policy.

This document describes how to set these reminders and escalations globally for your IdentityNow site.

NOTES:

  • By default, no reminders or escalations are sent.

  • If you're making these API calls, you'll need to use on of our supported authentication methods. As a best practice SailPoint recommends using OAuth 2. For details, see Authentication Method for API Calls​.

  • The endpoint you use must be changed slightly based on the authentication method. For guidance, see Endpoint URLs Based on Authentication Method​.

 

CONTENTS:

 

API

 

The API call to set a reminder and escalation policy is:

PATCH    /v2/org

The following JSON should be included:

  • daysTillEscalation - Number of days from when the request is created to when the reminder/escalation process begins.

  • daysBetweenReminders - Number of days between reminders or escalations.

  • maxReminders - Maximum number of reminders sent before starting the escalation process.

  • fallbackApprover - The alias of the identity that will review the request if no one else reviews it. Typically this is the SailPoint user name of the identity but in some cases, you might need to provide the UID. To determine the correct value for any particular identity, use the identities API described in IdentityNow Platform APIs​.

A task runs in the background on a daily basis at 12 am UTC to determine if any approvals meet the criteria for sending a reminder or an escalation.

For example:

{

  "approvalConfig": {

        "daysTillEscalation": 3,

        "daysBetweenReminders": 2,

        "maxReminders": 2,

        "fallbackApprover": "support"

    }

 

}

After a successful call, you'll see results similar to the following:

escalationJSON.png

 

IMPORTANT: Specifying a value of 0 for any of these escalation policy parameters will generate the following results: 

daysTillEscalation No reminder will be sent and no escalation  will occur
daysBetweenReminder After first reminder, no additional reminders will be sent and no escalation will occur
maxReminders No reminder will be sent before escalation

 

Escalation Pattern

When the criteria for an escalation has been met, the escalation email is sent to the following people in the system in order:

  • Approver 2 - Manager of the original approver

  • Approver 3 - 2nd level manager of the original approver

  • Fallback Approver - An individual designated by this API to complete the request if all previous approvers fail to meet the deadline

NOTE: If you define an escalation policy to enforce approvals in IdentityNow, it may result in a unique workflow where a request gets escalated to the original person who requested the access (for themself, or on behalf of another), essentially overriding the restriction in place to prevent this from happening.

Example System Response

When your policy settings are as follows, you'll see reminders generated on a schedule defined in the table below.

"approvalConfig": {

    "daysTillEscalation"        :    3,

    "daysBetweenReminders"    :    1,

  "maxReminders"            :    3,

    "fallbackApprover"        :    "support"

 

Reminder and Escalation Schedule

 

Day Action Escalation or Reminder
0 An initial email is generated asking the designated approver to review the request NA
3 An email is sent to the approver after the period defined by daysTillEscalation First reminder
4 An email is sent to the approver Second reminder
5 An email is sent to the approver Final reminder
6 An escalation email is sent to Approver 2 First escalation
7 An email is sent to Approver 2 First reminder
8 An email is sent to Approver 2 Second reminder
9 An email is sent to Approver 2 Final reminder
10 An escalation email is sent to Approver 3 Second escalation
11 An email is sent to Approver 3 First reminder
12 An email is sent to Approver 3 Second reminder
13 An email is sent to Approver 3 Final reminder
14 An escalation email is sent to the Fallback Approver Final escalation

 

No additional emails are sent after this point and the approval continues to wait for the Fallback Approver indefinitely.

Labels (1)
Version history
Revision #:
9 of 9
Last update:
‎Apr 09, 2020 11:47 AM
Updated by: