PingIDM

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.

Changes to the notification property name

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.

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 or 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 Ping 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, refer to Router configuration.

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