For a basic introduction to notifications, please see this general overview.
Here we describe detailed information pertaining to configuring the notifications from the point of view of system administrator.
Currently, there are a couple of transports available: mail, sms, custom and file.
They have to be configured to work properly. For the time being, here we show a sample configuration, hopefully self-explanatory enough:
<mail> <server> <host>smtp.gmail.com</host> <port>587</port> <!-- specify port: 25, 587 (e.g. MS Exchange and TLS) or other based on your mail server --> <!-- you can skip the port definition altogether to use default --> <username>firstname.lastname@example.org</username> <password> <clearValue>abcdef</clearValue> </password> <transportSecurity>starttlsRequired</transportSecurity> <!-- other possibilities: none, starttlsEnabled, starttlsRequired --> </server> <!-- there can be more servers if necessary; they are tried in the order specified --> <server> <!-- Second server --> . . . </server> <server> <!-- Third server --> . . . </server> <defaultFrom>email@example.com</defaultFrom> <debug>true</debug> <!-- standard javax.mail debugging; it is going to stdout (catalina.out)! --> <logToFile>mail-notifications.log</logToFile> <!-- All notifications are logged to this file IN ADDITION TO sending them via mail. They are logged in all cases: even if they eventually cannot be send. Implemented since 3.6.1. --> </mail>
Ensure your SMTP server will accept multiple connection (message rate limit) as midPoint notifications are being sent as the objects are created, e.g. one user can have 15 accounts or one organization 40 entitlements created at the same time. This is especially important for Microsoft Exchange, where the default limit seems to be very low (5 connections per minute).
Also please note that SSL-related settings for mail messaging are currently experimental (e.g. there is no support for setting certificate validation-related properties; default behavior of javax.mail implementation is used). You may also need to store the mail server self-signed SSL certificate in your Java "cacerts" keystore.
For Microsoft Exchange, we've successfully tested the configuration with port=587, transportSecurity=starttlsRequired and a valid username/password combination.
This transport can be used to diagnose notifications. It works in a similar way as "redirectToFile" option, but:
<notificationConfiguration> <handler> <simpleUserNotifier> ... <transport>mail</transport> <transport>file:users</transport> </simpleUserNotifier> <simpleWorkflowNotifier> ... <transport>mail</transport> <transport>file</transport> </simpleWorkflowNotifier> <simpleCampaignNotifier> ... <transport>mail</transport> <transport>file</transport> </simpleCampaignNotifier> ... </handler> ... <file name="users"> <file>notifications-users.txt</file> </file> <file> <file>notifications-other.txt</file> </file> </notificationConfiguration>
"File" transport is available since 3.6.1.
SMS transport assumes the existence of HTTP-based SMS gateway. The administrator basically configures how to construct the HTTP request to send the SMS.
<sms name="method1"> <!-- there can be more SMS configurations, distinguished by their name --> <gateway> <!-- there can be one or more gateways; if one fails, the next one is tried --> <urlExpression> <script> <code>"https://my-sms-gateway.com/send?number=" + encodedTo + "&text=" + encodedMessageText</code> </script> </urlExpression> </gateway> </sms> <sms name="with-post"> <gateway> <method>post</method> <urlExpression> <value>https://gw.com/send</value> </urlExpression> <headersExpression> <value>Content-Type: application/x-www-form-urlencoded</value> <value>X-Custom: test</value> </headersExpression> <bodyExpression> <script> <code>"Body=\"$encodedMessageText\"&To=$encodedTo&From=$encodedFrom".toString()</code> </script> </bodyExpression> <username>a9038321</username> <password>5ecr3t</password> <logToFile>target/sms.log</logToFile> <!-- Logs messages to a file IN ADDITION TO being sent via gateway. Useful for debugging. --> </gateway> </sms> <sms name="test"> <redirectToFile>sms-notifications.log</redirectToFile> <!-- when used, logs all notifications to a file INSTEAD OF sending them via gateway; this element can be used also within definition of a gateway - in that case the computed URL is logged as well. --> </sms>
The following items can be configured for a gateway:
Which HTTP method is used to send SMS. Currently, "get" and "post" are supported. If not specified, "get" is assumed.
|urlExpression||Expression that returns URL used to send SMS.||since 3.7.1 (up to 3.7, this item was called |
Expression that returns HTTP request headers. The expression should return 0, 1 or more string values that will be used as request HTTP headers. Each value is in the form of "name: value", i.e. a header name followed by comma, space and a header value. If one header has to have more values, such name-value pair should be present more times for the given header name.
|bodyExpression||Expression that returns request body used to send SMS (as a string).||since 3.7.1|
Encoding to be used for the message body. ISO 8859-1 is the default. Note that if you use any other encoding, your responsibility is to provide appropriate Content-Type header (see headersExpression item). This requirement might change in the future.
|username, password||How to authenticate to the SMS gateway.||since 3.7.1|
|redirectToFile||Instead of opening HTTP connection, writes the URL and other parameters to this file. Useful for debugging.|
|logToFile||In addition to executing the expression, writes all messages to a file. Useful for debugging.||since 3.7.1|
Expressions specified in urlExpression (url), headersExpression, bodyExpression can use the following variables:
|from||The message sender: Either message.from, smsConfiguration.defaultFrom or an empty string (in that order).|
|to||List of message recipients.|
|messageText||Message text (body).|
|encodedFrom||URL-encoded version of the |
|encodedTo||URL-encoded version of the |
|encodedMessageText||URL-encoded version of the |
|message||The whole message (|
It can accept any event and produce any notification(s). All is directed by parameters and expressions, as described in the following table. Please note that the following parameters can be used in any kind of notifier.
|name (attribute)||String||0..1||Name of the notifier - just a help to the administrator in order to increase readability of the configuration.|
|description||String||0..1||Description of the notifier - also just a help to the admin.|
Recipient(s) that should get the notifications. (TODO: Exact form is to be determined yet, but here may be mail addresses, phone numbers, etc. We need to think how to distinguish these kinds of destinations.) Default: mail address of the requestee - user that is being dealt with by repository object change or within a workflow; or account owner.
Recipient(s) that should get the notifications (as Cc). Only for mail transport.
Recipient(s) that should get the notifications (as Bcc). Only for mail transport.
|subjectExpression||ExpressionType||0..1||How to construct the subject of the message that is to be sent.|
Simpler alternative to subjectExpression: the subject itself will be constructed by the notifier (applicable to concrete kinds of notifiers, like e.g. userPasswordNotifier), but it will be prefixed by value specified here.
|bodyExpression||ExpressionType||0..1||How to construct the body (text) of the message that is to be sent.|
Whether to send a notification when only auxiliary attributes (namely: validityStatus, validityChangeTimestamp, effectiveStatus, disableTimestamp, modifyChannel, modifyTimestamp, modifierRef and maybe others) are modified. Default value: false. This setting also influences the list of modifications that is shown within the notification when using simpleUserNotifier and simplePasswordNotifier - if set to false, modifications of auxiliary attributes are not listed among account/user modifications.
|showModifiedValues||Boolean||0..1||Whether to show modified values (or only names of changed attributes). Default: true. (NOT IMPLEMENTED YET. THE NAME MIGHT CHANGE.) Applies to concrete notifiers, not to the general one.|
|showTechnicalInformation||Boolean||0..1||Whether to show technical information (e.g. model context or account operation details) in the notification. Applies to concrete notifiers, not to the general one.|
|transport||String||0..N||To what transport(s) should the message be sent.|
Sends out a notification about the change of a user. It has no special parameters in addition to parameters of a general notifier.
Sends out a notification about the change of a resource object.It has one parameter:
Whether to send a notification when only auxiliary attributes related to synchronization situation (synchronizationSituationDescription, synchronizationSituation) are modified. Default: false.
Send a notification when a user/account password is generated or changed. No special parameters.
Send a notification when a process instance or work item is started or completed. No special parameters.
Passes events that are of one of the specified categories. There are the following categories available:
|userEvent||event.isUserRelated()||Event connected to a user object in repository.|
|resourceObjectEvent||event.isAccountRelated() (TODO: change this in code and in docs)||Event connected to an object on a resource.|
|workItemEvent||event.isWorkItemRelated()||Start/completion of a work item.|
|workflowProcessEvent||event.isWorkflowProcessRelated()||Start/completion of a workflow process instance.|
|workflowEvent||event.isWorkflowRelated()||workItemEvent or workflowProcessEvent|
(Expressions are used in scripts connected to event processing, see below.)
Passes events that can be described by one of specified status descriptions. This has a slightly different meaning depending on the event category:
|Name||Expression||Meaning for user events||Meaning for account events||Meaning for workflow events****|
|success||event.isSuccess()||All modifications were carried out successfully*.|
The operation was successful.
|The request was approved.|
|alsoSuccess||event.isAlsoSuccess()||At least one modification was carried out successfully*.|
|onlyFailure||event.isOnlyFailure()||All modifications failed**.||The operation was unsuccessful.||The request was denied.|
|failure||event.isFailure()||At least one modification failed**.|
|inProgress||event.isInProgress()||At least one modification is in progress***.||The operation is in progress.||The result of request is not known.|
(*) The result is either SUCCESS, WARNING, or NOT_APPLICABLE.
(**) The result is either FATAL_ERROR, PARTIAL_ERROR or NOT_APPLICABLE.
(***) The result is IN_PROGRESS.
Please note that we take into account only user (i.e. focus) modifications, not modifications of user's accounts.
(****) Alternatively, it is possible to use the following expressions for workflow events: event.isApproved(), event.isRejected(), event.isResultKnown().
Filters events based on operation that was executed (or attempted to execute).
|Name||Expression||Description for user and account events.||Description for workflow events.|
|add||event.isAdd()||User/account is created.||Work item or process instance is started.|
|modify||event.isModify()||User/account is modified.||N/A|
|delete||event.isDelete()||User/account is deleted.||Work item or process instance has been competed.|
Passes events based on arbitrary expression. Some examples:
<expressionFilter> <!-- passes 'new account' events requested by user named "security-admin" --> <script><code>event.isAccountRelated() && event.isAdd() && "security-admin".equals(requester?.getName()?.getOrig())</code></script> </expressionFilter>
Any expressions supported by midPoint can be used.
Variables that are available are:
|event||com.evolveum.midpoint.notifications.events.Event||The event that is being processed.|
The user who requested the operation (if known).
|requestee||ObjectType||The object (typically a user) that is modified by the operation, or the owner of an account that is modified by the operation (if known).|
|assignee||UserType||The user who is assigned the work item (only for WorkItemEvent).|
|transportName||String||Name of transport (e.g. "mail", "sms", etc.). Available in expressions for getting recipient(s), message subject and body. Not available in expressionFilters.|
You need to put certificate to midPoint keystore, please see this. You can download cert over:
openssl s_client -connect smtp.office365.com:587 -starttls smtp
<password> <clearValue>password</clearValue> </password>
<!-- <redirectToFile>mail-notifications.log</redirectToFile> -->
This section describe how to configure black/white address list, which give option of filtering recipients addresses.
Variables that are available are:
|blackList||String||Addresses that are on a "black list". If a message contains one or more addresses that are blacklisted, it is stored into file specified in "redirectToFile" and either not sent at all (if no other addresses remain) or sent without blacklisted addresses.|
|whiteList||String||Addresses that are on a "white list". If specified, then all addresses are blacklisted, except for those that match a white list entry.|
|recipientFilterExpression||ExpressionType||An expression that decides whether the recipient address is allowed to pass through or it should be blacklisted. The expression expects input value in "recipientAddress" variable (usually a String), and should provide a boolean value: "true" means "pass through", "false" means "block".|
An address can contain "*" character, that matches any substring, e.g. "*@example.org".
At most one of "blackList", "whiteList" and "recipientFilterExpression" can be used.
When is defined redirectToFile and one of whiteList, blackList or recipientFilterExpression, the messages for allowed recipient are sended, and the messages for forbidden recipients are writed to a file.
<mail> <whiteList>firstname.lastname@example.org</whiteList> <whiteList>*@example.com</whiteList> <redirectToFile>/opt/example/example-mail-notifications.log</redirectToFile> </mail>
When white list is specified, then all addresses are blacklisted, except for those that match a white list entry. For this example, emails for email@example.com or *@example.com (for example firstname.lastname@example.org, email@example.com, firstname.lastname@example.org) will be sended, and emails for other address will be writed to file /opt/example/example-mail-notifications.log.