notification/transport configuration docs refresh after 4.5 changes

Evolveum · Nov 2, 2022 · 87e31e7 · 87e31e7
1 parent 84a828a
commit 87e31e7
Show file tree

Hide file tree

Showing 2 changed files with 51 additions and 29 deletions.
diff --git a/docs/misc/notifications/configuration.adoc b/docs/misc/notifications/configuration.adoc
@@ -14,8 +14,22 @@ For a basic introduction to notifications, please see this xref:..[general overv
 
 Here we describe detailed information on how to configure the notifications as a system administrator.
 
+Notification and transport configuration is specified with `notificationConfiguration` and `messageTransportConfiguration`
+containers inside xref:/midpoint/reference/concepts/system-configuration-object/[System Configuration Object].
+
 == Configuring transports
 
+[NOTE]
+====
+In 4.5 the new container for transport configuration was introduced - `messageTransportConfiguration`.
+You can still place the transport configuration inside `notificationConfiguration` but that style
+will be eventually deprecated, depending on the GUI support for the new configuration style.
+
+There is just one noteble difference in both styles.
+The "old" style supports `name` _attribute_ to distinguish between multiple transports of the same
+type - while the new style uses `name` _element_ which is more idiomatic for midPoint configuration.
+====
+
 Currently, there are a couple of transports available: *mail, sms*, *custom* and *file*.
 
 They have to be configured to work properly.
@@ -82,40 +96,43 @@ An example:
 
 [source,xml]
 ----
-   <notificationConfiguration>
-      <handler>
-         <simpleUserNotifier>
+<notificationConfiguration>
+    <handler>
+        <simpleUserNotifier>
             ...
             <transport>mail</transport>
-            <transport>file:users</transport>
-         </simpleUserNotifier>
-         <simpleWorkflowNotifier>
+            <transport>users</transport>
+        </simpleUserNotifier>
+        <simpleWorkflowNotifier>
             ...
             <transport>mail</transport>
             <transport>file</transport>
-         </simpleWorkflowNotifier>
-         <simpleCampaignNotifier>
+        </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>
+        </simpleCampaignNotifier>
+        ...
+    </handler>
+    ...
+</notificationConfiguration>
+<messageTransportConfiguration>
+    <file>
+        <name>users</name>
+        <file>notifications-users.txt</file>
+    </file>
+    <file>
+        <name>file</name>
+        <file>notifications-other.txt</file>
+    </file>
+    <mail>
+        <name>mail</name>
+        ...
+    </mail>
+</messageTransportConfiguration>
 ----
 
-[TIP]
-====
-"File" transport is available since 3.6.1.
-====
-
 === "SMS" transport
 
 SMS transport assumes the existence of HTTP-based SMS gateway.
@@ -126,7 +143,8 @@ Some examples:
 [source,xml]
 ----
 <!-- there can be more SMS configurations, distinguished by their name -->
-<sms name="method1">
+<sms>
+    <name>method1</name>
     <!-- there can be one or more gateways; if one fails, the next one is tried -->
     <gateway>
         <urlExpression>
@@ -137,7 +155,8 @@ Some examples:
     </gateway>
 </sms>
 
-<sms name="with-post">
+<sms>
+    <name>with-post</name>
     <gateway>
         <method>post</method>
         <urlExpression>
@@ -159,7 +178,8 @@ Some examples:
     </gateway>
 </sms>
 
-<sms name="test">
+<sms>
+    <name>test</name>
     <!--
     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
@@ -188,7 +208,7 @@ If not specified, "get" is assumed.
 | headersExpression
 | 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.
+Each value is in the form of "name: value", i.e. a header name followed by colon, 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.
 | since 3.7.1
 

diff --git a/docs/misc/notifications/index.adoc b/docs/misc/notifications/index.adoc
@@ -49,7 +49,7 @@ There many prepared notifier types to handle the basic situations and many thing
 Examples are shown later in this document.
 
 * *Message template* (added in version 4.5) is an object containing predefined message.
-The message template can have multiple localizations and optionally contain attachments.
+The xref:../message-templates/[message template] can have multiple localizations and optionally contain attachments.
 In versions 4.4 and lower, the content of the notifiaction message could be specified only
 directly in the notifier (which is still an option, but localization is very cumbersome).
 
@@ -574,6 +574,8 @@ the page also documents the xref:/midpoint/reference/misc/notifications/configur
 
 To send HTML emails, set `<contentType>text/html; charset=UTF-8</contentType>` and put to `<bodyExpression>` escaped HTML in single quote.
 
+// TODO show debug logging to troubleshoot notifications/transport
+
 === Custom notifications
 
 These are briefly described in the xref:/midpoint/reference/misc/notifications/sending-custom-notifications/[Sending custom notifications HOWTO].