Skip to main content

Notification Profile

The Notification Profile represents configuration how notifications are handled when used:

  • Who should receive notification (recipients)
  • How notification should be delivered (internal/external)
  • When and how often notification should be sent
  • Which notification provider to use for external delivery (like email, webhook, etc.)

Notification Profile has the following properties:

ParameterDescription
NameThe distinctive label assigned to the Notification Profile
UUIDThe universally unique identifier uniquely representing the Notification Profile
DescriptionA concise yet informative explanation detailing the purpose and characteristics of the Notification Profile
Recipient typeWhich notification recipient type should be used
RecipientsList of specific recipients of chosen type. Applicable with user, groups and roles
Notification instanceDefines which notification provider and instance should be used. It represents notification channel
Internal notificationIndicates if internal notification should be executed or not
FrequencyUsed when notifying in context of monitoring events. It specifies interval between consecutive notifications and controls how often to repeat notification from the time when it was created
RepetitionsUsed when notifying in context of monitoring events. It specifies maximum number of notification repetitions
Event dataCategories of data about the event's object to include in external notifications. All disabled by default. See Event data
note

Notification Profile is versioned to ensure that already pending notifications are not influenced by configuration changes. The description and the event data categories belong to the profile rather than to a version: changing them creates no new version and applies at once, also to pending notifications.

In case of notifying in context of monitoring events, notification system controls how often and how many notifications are sent to prevent spamming user with notifications carrying the same information. Frequency and maximum repetitions are checked per notification profile, object and event that defines notification event.

Example of monitoring event

When certificate expiring event is raised for certificate X, notification system will mark the time of lst notification of the event for certificate X through notification profile X and increment notification counter.

Send notifications on events​

A notification profile is used only when an event trigger sends it. To send notifications when an event occurs:

  1. Create the notification profile with its recipients and, for external delivery, its notification instance and the event data to include.
  2. Create an execution of the type Send Notification that uses the profile, and add the execution to an action.
  3. Create a trigger of the type Event for the event, and add the action to it. A trigger without rules applies to every object of the event; add rules to notify only about some of them.
  4. Associate the trigger with the event: in the platform events settings for every object of the event, or on an RA profile, a group or a discovery for its objects only. The supported events list which objects can carry triggers for each event.

The Event Viewer shows each trigger evaluation and any notification that failed to send. A notification held back by the frequency or repetitions of the profile still shows as sent.

Event data​

A notification profile can add data about the object an event concerns to its external notifications. Each category is enabled separately, and all are disabled by default:

CategoryIncluded data
Custom attributesContent of the custom attributes assigned to the object
MetadataConnector-sourced metadata of the object, grouped by the connector and source object that produced it
AssociationsThe owner and groups of the object and, for certificates, its RA profile
Object contentThe content of the object when its type has one: for certificates, the Base64-encoded DER data

The data describes the event's subject: for approval and comment events, the object the approval or comment is about; for every other event, the event's own object. A category adds data only where the subject supports it, and nothing elsewhere: custom attributes and metadata where its resource has attributes, the owner and groups where its resource has them, and the RA profile and content for certificates.

The data is sent to the notification provider as the objectData part of the notification request, next to the event's own data. It is loaded when the notification is sent, and reflects the object at that time. Loading is best effort, and the notification is sent in any case: a category that cannot be loaded or is too large is left out, and a long value is cut short and ends with ...[truncated]. Treat every part of objectData as optional; the templates of the Email Notification Provider and the Webhook Notification Provider show how.

Object data never contains the values of secret or credential attributes, or the content of protected attribute definitions, whichever categories are enabled. This applies to object data only: the event's own data can carry a secret, such as the one-time credential of the Certificate registered event.

Required permissions

Enabling a category authorizes sending the object data to the notification instance of the profile. These categories therefore require additional permissions, without object-level restrictions, of the user who enables them, or who changes the notification instance while they are enabled:

  • Custom attributes requires the Members action on the Attribute resource.
  • Object content requires the Detail action on the Certificate resource and the Members action on the RA Profile resource.

The permissions are checked only at that time: losing them later does not disable a configured profile.

Trust boundary

Enable event data only for notification instances whose connector you trust with the data. A connector reached through a proxy receives its requests through the message broker, which is then part of that trust boundary.