Custom Notifications

Notifications are configured in files named notification-event.json, where event refers to the event that triggers the notification.

By default, IDM sends notifications for password updates and profile updates. These notifications are configured in conf/notification-passwordUpdate.json and conf/notification-profileUpdate.json, respectively. You can use these default notification configuration files as the basis for setting up custom notifications.

The following excerpt from the notification-passwordUpdate.json file shows the structure of a notification configuration:

{
    "enabled" : true,
    "path" : "managed/user/*",
    "methods" : [
        "update",
        "patch"
    ],
    "condition" : {
        "type" : "groovy",
        "globals" : {
            "propertiesToCheck" : [
                "password"
            ]
        },
        "file" : "propertiesModifiedFilter.groovy"
    },
    "target" : {
        "resource" : "managed/user/{{response/_id}}"
    },
    "notification" : {
        "notificationType": "info",
        "message": "Your password has been updated."
    }
}

enabled boolean, true or false

Specifies whether notifications will be triggered for that configured event.

path string

Specifies where the filter listens on the router. For user notifications, this is typically managed/user/*.

methods array of strings (optional)

One or more ForgeRock REST verbs, specifying the actions that should trigger the notification. These can include create, read, update, delete, patch, action, and query. If no methods are specified, the default is to listen for all methods.

condition string or object

An inline script or a path to a script file that specifies the condition on which the notification is triggered. The passwordUpdate notification configuration references the groovy script, /path/to/openidm/bin/defaults/script/propertiesModifiedFilter.groovy. This script monitors the properties listed in the propertiesToCheck array, and sends a notification when those properties are changed. The script also checks whether a modified property is the child (or parent) of a watched property.

To specify additional properties to watch, add the property names to the array of propertiesToCheck. The properties that you can specify here are limited to existing user properties defined in your managed.json file. For example, the following excerpt of the notification-profileUpdate.json file shows the properties that will trigger notifications if their values are changed:

...
    "condition" : {
        "type" : "groovy",
        "globals" : {
            "propertiesToCheck" : [
                "userName",
                "givenName",
                "sn",
                "mail",
                "description",
                "accountStatus",
                "telephoneNumber",
                "postalAddress",
                "city",
                "postalCode",
                "country",
                "stateProvince",
                "preferences"
            ]
        },
        "file" : "propertiesModifiedFilter.groovy"
    },
...

target object

The target resource to which notifications are sent, typically managed/user/{{response/_id}}.

The target.resource field supports {{token}} replacement with contextual variables. The following variables are in scope:

request
context
resourceName
response

notification

The actual notification, including the notificationType (info, warning, or error) and the message that is sent to the user.

The notification.message field supports {{token}} replacement with contextual variables, as described previously for target.resource.

Notification configuration files follow the format of the router.json file. For more information about how filtering is configured in router.json, see Router Configuration.

Additional sample notification configuration files can be found in the /path/to/openidm/samples/example-configurations/conf directory:

notification-newReport.json: This configuration notifies managers when a new direct reporting employee is assigned to them.
notification-termsUpdate.json: This configuration notifies all users who have accepted Terms and Conditions of any updates to those Terms and Conditions.

To use these files (or create your own notifications based on these files), copy them to your project's conf/ directory.