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.
The API call to set a reminder and escalation policy is:
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.
After a successful call, you'll see results similar to the following:
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|
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.
"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.