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.

By default, no reminders or escalations are sent. This document describes how to set these reminders and escalations globally for your IdentityNow site.

NOTE: If you're making these API calls, you'll need to use one of our supported authentication methods. As a best practice SailPoint recommends using OAuth 2. Also, the endpoint you use must be changed slightly based on the authentication method. For guidance, refer to the Authentication section of the Developer portal.

 

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, refer to the identities APIs in the API Reference of the Developer portal.

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.

Comments

Hi Team &  @rose_cobb @kelly_wells , Even am setting approval Config as below, am getting 1st reminder mail only after 7 days.

"approvalConfig": {
        "daysTillEscalation": 1,
        "daysBetweenReminders": 1,
        "maxReminders"2,
        "fallbackApprover""Ritu Raj Akhauri"
    }
 
Am I missing something in the configuration ?? Please advice.
 
Thanks,
Sasitharan Duraisamy

@Sasi13130203   were you able to successfully configure and get the notifications, I am also in the same situation can you please share the details if the configuration was successful.

 

Thanks

Yeshwanth

In our use case, we would prefer if there was a maximum escalations before fallback, which we could set to 1 before fallback. What is really needed is an Approval Admin role which grants specific admin level, step-up users the ability to see and approve or deny approvals across the entire system.

Any plans to limit the number of approvers this escalates to?

Version history
Revision #:
5 of 5
Last update:
‎Oct 28, 2022 02:17 AM
Updated by: