Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 9 Next »

Introduction

This mechanism is used to notify users about relevant changes in midPoint and/or connected resources. For example, a user (or user's boss, or the person who requested the operation, the security manager, etc) may be notified when one of user's accounts is created, modified, or removed. Or, when the midPoint user record is created, when the password is changed, or when he has a new work item to process. There are many such situations imaginable.

Currently there are three basic kinds of notifications:

  1. User notifications. These are related to midPoint user record, e.g. its creation, modification or removal.
  2. Account notifications. These are related to accounts on resources, e.g. creation, modification, or removal of such an account.
  3. Workflow notifications. These are generated e.g. when a work item is created or completed, or when a workflow process instance is started or finished.

Some simple examples

Configuration of notifications is currently done within SystemConfiguration object (see the schema in SVN trunk). Some examples are shown below:

<notificationConfiguration>

    <!-- this event handler sends accounts passwords (when created or changed) via SMS to the account owner telephone number, if known -->
    <accountPasswordNotifier>
        <recipientExpression>
            <script><code>requestee.getTelephoneNumber()</code></script>
        </recipientExpression>
        <transport>sms:default</transport>
    </accountPasswordNotifier>

    <!-- this event handler sends *user* passwords (when created or changed) via SMS to the user's telephone number, if known -->
    <userPasswordNotifier>
        <recipientExpression>
            <script><code>requestee.getTelephoneNumber()</code></script>
        </recipientExpression>
        <transport>sms</transport>
    </userPasswordNotifier>

	<!-- this event handler sends notifications about successful account creation to the account owner mail, if known -->
    <simpleAccountNotifier>
        <statusFilter>
            <status>success</status>		<!-- only successful operations! -->
        </statusFilter>
        <transport>mail</transport>
    </simpleAccountNotifier>

    <!-- configurations suitable for testing - they redirect all notifications to log files; some more real configurations are show below -->
    <mail>
        <redirectToFile>mail-notifications.log</redirectToFile>
    </mail>
    <sms>
        <redirectToFile>sms-notifications.log</redirectToFile>
    </sms>
</notificationConfiguration>

A bit of theory related to event handling

When something potentially of interest occurs, an event is generated. This event is then processed by one or more event handlers, as prescribed in <notificationConfiguration> section.

Event handler can be one of the following:

  1. A notifier - i.e. a module that transforms an event to zero, one or more notifications. Examples are:
    1. simpleUserNotifier (generates notifications about user records),
    2. simpleAccountNotifier (notifies about accounts),
    3. userPasswordNotifier, accountPasswordNotifier (specialized notifiers that prepare messages about user/account passwords),
    4. workItemNotifier (notifications about start/completion of a work item), 
    5. workflowNotifier (the same for workflow process instances),
    6. and generalNotifier (general purpose notifier that is driven by expressions that transform an event into a notification).
     
  2. A filter - does not generate notifications, but passes (and filters) defined subsets of notifications. A filter can be defined in relation to a notifier - in that case it defines, which classes of events get processed by that notifier. Or a filter can be part of a handler chain (see below). Examples of filters:
    1. categoryFilter - passes one or more defined categories of events: account-related events, user-related events, work item-related events, workflow-related events;
    2. statusFilter - passes or filters events based on their status: success, failure, in-progress. Please note that user-related events are currently only with status = success (failures are not transformed into events). In workflow related events, success means approval, failure means refusal;
    3. operationFilter - passes or filters events based on the kind of operation that was executed or attempted to: add, modify, or delete;
    4. expressionFilter - a generic filter that evaluates an expression and passes/filters event based on the result.

  3. A handler chain - contains sequentially ordered event handlers (notifiers, filters, forks, other chains). Processing within a chain continues until an event is filtered out. (Please note that filtering is done only by filters; all notifiers simply pass all events along.)

  4. A fork - splits processing of an event into more handlers "in parallel". (We expect this kind of handler will be used only occassionally.)

Handlers defined at the level of <notificationConfiguration> are executed in parallel.

An example:

<notificationConfiguration>

    <!-- a notifier with an embedded filter -->
    <accountNotifier name="newAccounts">
        <expressionFilter>
            <expression>
                <script><code>event.isAccountRelated() &amp;&amp; event.isAdd() &amp;&amp; event.isSuccess()</code></script>
            </expression>
        </expressionFilter>
        <transport>mail</transport>
     </accountNotifier>

    <!-- a handler chain: first, it filters out all events except for "add account" events;
         second, it notifies the account owner via mail;
         and at the same time, it filters out all events except for "success" ones and notifies security admin -->

    <handlerChain name="new accounts with traditional filters, dummy and simpleAccount notifiers">
        <categoryFilter>
            <category>accountOperation</category>
        </categoryFilter>
        <operationFilter>
            <operation>add</operation>
        </operationFilter>
        <fork>
            <simpleAccountNotifier name="newAccounts">
                <transport>mail</transport>
            </simpleAccountNotifier>
            <handlerChain name="now notify the security admin, but only in case of success">
        		<statusFilter>
		            <status>success</status>
		        </statusFilter>
		        <simpleAccountNotifier name="newAccountsToSecurityAdmin">
        		    <recipientExpression>
						<value>security-admin@my.org</value>
		            </recipientExpression>
        		    <subjectExpression>
        		    	<script><code>"Changed account for " + requestee.getName().getOrig()</code></script>
		            </subjectExpression>
		            <transport>mail</transport>
		        </simpleAccountNotifier>
			</handlerChain>
		</fork>
    </handlerChain>

	<!-- actually, the previous notification scheme can be written more efficiently (and more concisely) in this way: -->

    <handlerChain name="new accounts with traditional filters, dummy and simpleAccount notifiers">
        <categoryFilter>
            <category>accountOperation</category>
        </categoryFilter>
        <operationFilter>
            <operation>add</operation>
        </operationFilter>
        <simpleAccountNotifier name="newAccounts">
            <transport>mail</transport>
        </simpleAccountNotifier>
        <simpleAccountNotifier name="newAccountsToSecurityAdmin">
       		<statusFilter>
	            <status>success</status>
	        </statusFilter>
  		    <recipientExpression>
				<value>security-admin@my.org</value>
            </recipientExpression>
   		    <subjectExpression>
  		    	<script><code>"Changed account for " + requestee.getName().getOrig()</code></script>
            </subjectExpression>
            <transport>mail</transport>
        </simpleAccountNotifier>
    </handlerChain> 

	<!-- ... -->

</notificationConfiguration>

Configuring transports

Currently, there are two transports available: mail and SMS.

Both 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>
		<username>abc@gmail.com</username>				<!-- it is possible to configure port as well -->
        <password>abcdef</password>
        <transportSecurity>ssl</transportSecurity>		<!-- other possibilities: none, starttlsEnabled, starttlsRequired -->
	</server>											<!-- there can be more servers if necessary; they are tried in the order specified -->
	<defaultFrom>abc@gmail.com</defaultFrom>
	<debug>true</debug>									<!-- stardard javax.mail debugging; it is going to stdout -->
</mail>

<sms name="default">		<!-- 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 -->
		<url>				<!-- for the time being we expect gateways accessible via HTTP(S), GET method ... other mechanisms have to be implemented -->
			<script>
				<code>"https://my-sms-gateway.com/send?number=" + to + "&amp;text=" + encodedMessageText</code>
			</script>
		</url>
	</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 SMS transport implementation is very simple for now; it even does not allow for specifying username and password for http connection. If necessary, it can be augmented in com.evolveum.midpoint.notifications.transports.SimpleSmsTransport class (or you can add another class, and register it under transport name other than "sms").

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

Expressions

TODO

 

  • No labels