API to Notify Users When a New Account is Provisioned

[#1]

This document describes how to enable, disable, and configure new account email notifications. When a source has this feature enabled, any time a new account is created on that source through provisioning, the recipients you configure in these APIs receive an email notifying them that the account was created.

You can modify the default email that is used to notify users.

IMPORTANT: These APIs are being deprecated in favor of the IdentityNow Platform APIs. While these APIs will continue to be available for the foreseeable future, SailPoint recommends that you transition to the new versions as soon as possible. For detailed information about all new platform APIs, visit the SailPoint API Reference.

This document covers the following tasks:

• Enable Notifications for a Source
• Source Bulk Enable/Disable API

Enable Notifications for a Source

This section describes how to enable or disable notifications of new accounts provisioned on a source.  In addition to source enablement, notification recipients should also be specified.

Notifications can't be sent about new accounts created on non-employee sources.

Prerequisites:

• Sign in to the org as an administrator. Click Admin and strongly authenticate
• Obtain a REST API token
• Get the source ID​. To determine the backend ID of a source, run GET{api-url}/beta/sources and find the value of id for the applicable sources
• Determine which account schema attribute to use for the account ID in the new account email  (e.g., distinguishedName for Active Directory)
• Open your preferred tool for making API calls, and enter the REST API token

Complete the following steps:

1. Make the following call:

POST {api-url}/cc/api/emailTemplate/setAccountCreateNotificationOptions

Replacing {api-url} with the API Gateway for your tenant (e.g., ht‍tps://tenant.api.identitynow.com/)

2. Set enabled to true, and provide values for these required parameters:

• sourceId - The external ID of the source.
• accountIdAttribute - That attribute in the source's account schema that will be used for the account ID in the account notification email.

3. Optionally provide values for the following parameters:

• emailAccountOwner - A true/false value that determines whether a notification should be sent to the owner of the new account.
• emailAccountOwnerAltEmail - A true/false value that determines whether a notification should be sent to the owner's alternate email of the new account.
• emailAccountManager - A true/false value that determines whether a notification should be sent to the user's manager.
• accountNotificationList - Any additional email addresses you would like to receive notifications when an account is provisioned on this source.

NOTE: Attributes have to be sent as a JSON packet for the request. For example, in Postman you would use Body -> Raw, set the type as "JSON (application/json)" and send the following package:

{
		"enabled":true,
	 	"emailAccountOwner":false,
                "emailAccountOwnerAltEmail":false,
	 	"emailAccountManager":false,
                "accountIdAttribute":"distinguishedName",
	 	"sourceId":"<externalId from Source List>",
	 	"accountNotificationList": [
	 		"user_a@yourdomain.com",
	 		"user_b@yourdomain.com"
	 	]
	 }

The API will return an HTTP 200 OK or an appropriate exception.

If you receive an HTTP 400 error, make sure you have at least one user configured to receive these notification emails in the attributes emailAccountOwner, emailAccountManager, or the accountNotificationList.

Source Bulk Enable/Disable API

This section describes how to bulk enable or disable sources for account notifications.

IMPORTANT: For each source specified in this call, a notification configuration must already exist. In other words, each source specified in this call must have users listed in the accountNotificationList that were configured with the API described above.

Prerequisite: Know the source IDs of all sources you plan to edit in this call.

Complete the following steps:

1. Make the following call:

POST {api-url}/cc/api/emailTemplate/setAccountCreateNotificationEnabledSources

Replacing {api-url} with the API Gateway for your tenant (e.g., ht‍tps://tenant.api.identitynow.com/)

2. Provide the source IDs of all sources you want to edit in this call. After each source ID, provide a true or false value to state whether you'd like notifications to be enabled for that source or not.

For example:

{

"2c91808561e3a3900161e7c389501c70":true,

"2c9180846274fddc016286d559536f73":false

}

The response from the server should be an HTTP 200 OK or an appropriate exception.

If you receive an HTTP 400 error, one or more of the sources you enabled using this API didn't have any users configured to receive notifications. Use the Enable Notifications for a Source API to choose one or more users to receive these notifications.