Update documentation for notification commands.

Fixes #5259

doc/3.02-commands.md

@@ -97,48 +97,71 @@ space).
 
 ### Notification Commands
 
-`NotificationCommand` objects define how notifications are sent to external
+`NotificationCommand` objects define how notifications are delivered to external
 interfaces (E-Mail, XMPP, IRC, Twitter, etc).
 
 > **Note**
 >
 > `NotificationCommand` objects require the ITL template `plugin-notification-command`
-> to support native plugin based checks.
+> to support native plugin-based notifications.
 
 Below is an example using runtime macros from Icinga 2 (such as `$SERVICEOUTPUT$` for
 the current check output) sending an email to the user(s) associated with the
 notification itself (`email` macro attribute provided as `$USERMACRO$`).
 
-Please note the notation for better readability using multiple lines enclosed with
-`{{{ ... }}}`. You can use a single line as argument item as well. If you require
-default macro definitions, you can add a macro dictionary as shown for the
+If you require default macro definitions, you can add a macro dictionary as shown for the
 `CheckCommand` object.
 
     object NotificationCommand "mail-service-notification" inherits "plugin-notification-command" {
-      command = [
-        "/usr/bin/printf",
-        "\"%b\"",
-        {{{\"***** Icinga  *****
-    
-        Notification Type: $NOTIFICATIONTYPE$
-    
-        Service: $SERVICEDESC$
-        Host: $HOSTALIAS$
-        Address: $HOSTADDRESS$
-        State: $SERVICESTATE$
-    
-        Date/Time: $LONGDATETIME$
-    
-        Additional Info: $SERVICEOUTPUT$
-    
-        Comment: [$NOTIFICATIONAUTHORNAME$] $NOTIFICATIONCOMMENT$\"}}},
-        "-s",
-        "\"$NOTIFICATIONTYPE$ - $HOSTDISPLAYNAME$ - $SERVICEDISPLAYNAME$ is $SERVICESTATE$\"",
-        "$USEREMAIL$"
+      command = [ (IcingaSysconfDir + "/icinga2/scripts/mail-notification.sh") ],
+
+      export_macros = [
+        "NOTIFICATIONTYPE",
+        "SERVICEDESC",
+        "HOSTALIAS",
+        "HOSTADDRESS",
+        "SERVICESTATE",
+        "LONGDATETIME",
+        "SERVICEOUTPUT",
+        "NOTIFICATIONAUTHORNAME",
+        "NOTIFICATIONCOMMENT",
+        "HOSTDISPLAYNAME",
+        "SERVICEDISPLAYNAME",
+        "USEREMAIL"
       ]
     }
 
+The command attribute in the `mail-service-notification` command refers to the following
+shell script. The macros specified in the `export_macros` array are exported
+as environment variables and can be used in the notification script:
 
+    #!/usr/bin/env bash
+    template=$(cat <<TEMPLATE
+    ***** Icinga  *****
+
+    Notification Type: $NOTIFICATIONTYPE
+
+    Service: $SERVICEDESC
+    Host: $HOSTALIAS
+    Address: $HOSTADDRESS
+    State: $SERVICESTATE
+
+    Date/Time: $LONGDATETIME
+
+    Additional Info: $SERVICEOUTPUT
+
+    Comment: [$NOTIFICATIONAUTHORNAME] $NOTIFICATIONCOMMENT
+    TEMPLATE
+    )
+
+    /usr/bin/printf "%b" $template | mail -s "$NOTIFICATIONTYPE - $HOSTDISPLAYNAME - $SERVICEDISPLAYNAME is $SERVICESTATE" $USEREMAIL
+
+> **Best Practice**
+>
+> While it's possible to specify the entire notification command right
+> in the NotificationCommand object it is generally advisable to create a
+> shell script in the `/etc/icinga2/scripts` directory and have the
+> NotificationCommand object refer to that.
 
 ### Event Commands