Configure notifications

The customizable notification service sends messages, based on changes to objects. The notification service uses filters to assess incoming requests. If the filter conditions are met, the service sends the corresponding notification. Notification messages are sent to whatever routes you specify.

In a JDBC repository, notifications are stored in the notificationobjects table. The notificationobjectproperties, serves as the index table. In a DS repository, notifications are stored under the DN "ou=notification,ou=internal,dc=openidm,dc=forgerock,dc=com".

The notification service is disabled by default. To enable the service, add openidm.notifications=true to your project’s resolver/boot.properties file. You can perform additional configuration using the conf/notificationFactory.json file.

Default 'notificationFactory.json' Configuration

{
    "enabled" :{
        "$bool" : "&{openidm.notifications|false}"
    },
    "threadPool" : {
        "steadyPoolThreads" : 1,
        "maxPoolThreads" : 2,
        "threadKeepAlive" : 60,
        "maxQueueSize" : 20000
    }
}

Changing the notifications thread pool settings can adversely affect performance.

Notifications for a managed object are injected into a property in that object. The name of this property is specified in the managed object schema, in conf/managed.json. For example, notifications for managed user objects rely on the following construct in the user object definition in managed.json:

{
    "objects" : [
        {
            "name" : "user",
            ...
            "notifications" : {
                "property" : "_notifications"
            },
            ...
        },
        ...
    ]
}

This excerpt indicates that notifications are injected into the _notifications property of the user object by default. The notifications object is mandatory for notifications to be generated for that managed object type. However, you can change the name of the property that is injected into the managed object when notifications are generated. If you omit the property field from the notifications object, notifications are stored in the _notifications field by default.

The ability to tie a specific notification to its corresponding managed object is regarded as an internal object relation. Notifications are therefore also configured in conf/internal.json with the following object:
```
{
    "name" : "notification",
    "properties" : {
        "target" : {
            "reversePropertyName" : "_notifications"
        }
    }
}
```
If you change the property field in managed.json to something other than _notifications, you must also update the corresponding reversePropertyName in internal.json to reflect the change.

The internal object service does not support runtime changes. If you update conf/internal.json over REST, you must restart IDM for the change to take effect.
If you have configured notifications for more than one managed object type, all the object types must use the same notification property name.

Custom notifications

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

By default, IDM doesn’t send any notifications for password or profile updates. To enable these notifications, add the applicable line to your project’s resolver/boot.properties file:

openidm.notifications.passwordUpdate=true
openidm.notifications.profileUpdate=true

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

The default notification-passwordUpdate.json file shows the structure of a notification configuration:

{
    "enabled" : {
        "$bool" : "&{openidm.notifications.passwordUpdate|false}"
    },
    "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. To enable/disable, set the openidm.notifications.passwordUpdate property in the resolver/boot.properties file.

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 the 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.

Limits on notification endpoints

Although notifications are highly configurable, you cannot apply them to services with their own internal routers, including internal objects. This list includes:

workflow/taskinstance
workflow/processdefinition
workflow/processinstance
metrics/api
metrics/prometheus
scheduler/job
scheduler/trigger
scheduler/waitingTriggers
scheduler/acquiredTriggers
info/ping
info/login
info/version
info/uiconfig
info/features
internal/{object}
internal/{object}/{object_id}/relationship
managed/{object}/{object_id}/relationship