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.

[ashligersky]

Where do I run this command from? /api/source/list/

[JoelSchibsted]

You only tell us how to post/create an email notification.
But if I wanna list (GET) all my email notification. How do I do that?

[hari13589]

Is any one facing issue in receiving mails when a new user is onboarded/provisioned as per workflow in sailpoint?

[Carlatto]

Here is how you can see if the Source AccountCreateNotification settings.

GET  {api-url}/cc/api/emailTemplate/getAccountCreateNotificationOptions/<sourceExternalID>

[dakota_heintschel]

Since the APIs above are deprecated, the new beta APIs to do this are as follows:

Operation: PATCH

URL: {{api-url}}/beta/sources/SOURCE_ID

Body:
    {
        "op": "replace",
        "path": "/connectorAttributes/accountCreateNotification",
        "value": {
            "notifyAccountManager": true,
            "accountIdAttribute": "distinguishedName",
            "notifyList": [
                "Distribution.List@demo.com"
            ],
            "notifyAccountOwner": true,
            "enabled": true,
            "notifyAccountOwnerAltEmail": false
        }
    }
]

NOTE: Change the body as needed for your settings. The settings in this body are similar to the what the document calls out even though its a different API call.

[BhimaMS1]

Team,

Is there a way to send two separate email to user on account creation? One email with sAMAccountName and other one with "password"? Please let me know

[ChristopherSerpa]

Hi all,

I'm having issues locating these new endpoints in the developer site and cannot find the current configuration within the source config in the connectorAttributes object. Can someone kindly point me to the updated APIs on the developer site to update account creation notifications within a source?

Thanks!

[ts_fpatterson]

The cc endpoint is for internal use, or not documented if I'm correct.

The documentation is valid. Someone referenced that the API is deprecated, but it still works.

If you have the vscode IDN extension, you can insert the below into the source. Make a backup first.

“accountCreateNotification”: {
“notifyAccountManager”: true,
“accountIdAttribute”: “distinguishedName”,
“notifyList”: [
“sampleDistributionList@example.com”
],
“notifyAccountOwner”: false,
“enabled”: true,
“notifyAccountOwnerAltEmail”: false
},

[jacob_islas]

This method works with the default email template "New Account Provisioned"??