Monitoring/Commands: Add help messages to the custom notification form

refs #4524

library/Icinga/Protocol/Commandpipe/CommandPipe.php

@@ -648,31 +648,31 @@ class CommandPipe
     }
 
     /**
-     * Send a custom host or service notification
+     * Send custom host and/or service notifications
      *
-     * @param $objects              monitoring objects to send this notification to
+     * @param array                 $objects        Affected monitoring objects
-     * @param Comment $comment      comment to use in the notification
+     * @param CustomNotification    $notification
-     * @param int [$...]            Optional list of Notification flags which will be used as the option parameter
      */
-    public function sendCustomNotification($objects, Comment $comment, $optionsVarList = 0/*, ...*/)
+    public function sendCustomNotification(array $objects, CustomNotification $notification)
     {
-        $args = func_get_args();
+        foreach ($objects as $hostOrService) {
-        // logical OR for all notification options
+            if (isset($hostOrService->service_description) && isset($hostOrService->host_name)) {
-        for ($i = 3; $i < count($args); $i++) {
+                // Assume service
-            $optionsVarList |= $args[$i];
+                $command = sprintf(
-        }
+                    $notification->getFormatString(self::TYPE_SERVICE),
-
+                    $hostOrService->host_name,
-        foreach ($objects as $object) {
+                    $hostOrService->service_description
-            $type = $this->getObjectType($object);
+                );
-            $msg = 'SEND_CUSTOM_'.(($type == self::TYPE_SERVICE) ? 'SVC' : 'HOST' ).'_NOTIFICATION';
+            } elseif (isset($hostOrService->host_name)) {
-            $msg .= ';'.$object->host_name;
+                // Assume host
-            if ($type == self::TYPE_SERVICE) {
+                $command = sprintf(
-                $msg .= ';'.$object->service_description;
+                    $notification->getFormatString(self::TYPE_HOST),
+                    $hostOrService->host_name
+                );
+            } else {
+                continue;
             }
-            $msg .= ';'.$optionsVarList;
+            $this->send($command);
-            $msg .= ';'.$comment->author;
-            $msg .= ';'.$comment->comment;
-            $this->send($msg);
         }
     }
 

library/Icinga/Protocol/Commandpipe/CustomNotification.php

@@ -0,0 +1,109 @@
+<?php
+// {{{ICINGA_LICENSE_HEADER}}}
+// {{{ICINGA_LICENSE_HEADER}}}
+
+namespace Icinga\Protocol\Commandpipe;
+
+/**
+ * Custom notification about hosts or services sent to Icinga's command pipe
+ */
+class CustomNotification
+{
+    /**
+     * Notification comment
+     *
+     * @var string
+     */
+    private $comment;
+
+    /**
+     *  Notification author
+     *
+     *  @var string
+     */
+    private $author;
+
+    /**
+     * Whether to force the notification to be sent out, regardless of the time restrictions, whether or not
+     * notifications are enabled, etc.
+     *
+     * @var bool
+     */
+    private $forced;
+
+    /**
+     * Whether the notification is sent out to all normal (non-escalated) and escalated contacts
+     *
+     * @var bool
+     */
+    private $broadcast;
+
+    /**
+     * 1 = Broadcast (send notification to all normal and all escalated contacts for the host)
+     */
+    const NOTIFY_BROADCAST = 1;
+
+    /**
+     * 2 = Forced (notification is sent out regardless of current time, whether or not notifications are enabled, etc.)
+     */
+    const NOTIFY_FORCED = 2;
+
+    /**
+     * Constructor
+     *
+     * @param string    $author     Notification author
+     * @param string    $comment    Notification comment
+     * @param bool      $forced     Whether to force the notification to be sent out, regardless of the time
+     *                              restrictions, whether or not notifications are enabled, etc.
+     * @param bool      $broadcast  Whether the notification is sent out to all normal (non-escalated) and escalated
+     *                              contacts
+     */
+    public function __construct($author, $comment, $forced = false, $broadcast = false)
+    {
+        $this->author = $author;
+        $this->comment = $comment;
+        $this->forced = $forced;
+        $this->broadcast = $broadcast;
+    }
+
+    /**
+     * Get Custom Notification command format string according to if its sent to a host or a service
+     *
+     * @param   string $type Identifier for either host or service
+     *
+     * @return  string
+     *
+     * @throws  InvalidCommandException When the given type is unknown
+     * @see     \Icinga\Protocol\Commandpipe\CommandPipe::TYPE_HOST
+     * @see     \Icinga\Protocol\Commandpipe\CommandPipe::TYPE_SERVICE
+     */
+    public function getFormatString($type)
+    {
+        switch ($type) {
+            case CommandPipe::TYPE_HOST:
+                $format = '%s';
+                break;
+            case CommandPipe::TYPE_SERVICE:
+                $format = '%s;%s';
+                break;
+            default:
+                throw new InvalidCommandException('Custom Notifications can only apply on hosts and services');
+        }
+
+        $options = 0;
+        if ($this->forced) {
+            $options |= self::NOTIFY_FORCED;
+        }
+        if ($this->broadcast) {
+            $options |= self::NOTIFY_BROADCAST;
+        }
+
+        // Build the command
+        $command = 'SEND_CUSTOM_' . $type . '_NOTIFICATION;'
+            . $format . ';'
+            . $options . ';'
+            . $this->author . ';'
+            . $this->comment;
+        return $command;
+    }
+}

modules/monitoring/application/controllers/CommandController.php

@@ -431,12 +431,7 @@ class Monitoring_CommandController extends ModuleActionController
         $this->setForm($form);
 
         if ($form->IsSubmittedAndValid() === true) {
-            $author = $this->getRequest()->getUser()->getUsername();
+            $this->target->sendCustomNotification($this->view->objects, $form->getCustomNotification());
-            $this->target->sendCustomNotification(
-                $this->view->objects,
-                new Comment($author, $form->getComment()),
-                $form->getOptions()
-            );
         }
     }
 

modules/monitoring/application/forms/Command/CustomNotificationForm.php

@@ -28,7 +28,8 @@
 
 namespace Monitoring\Form\Command;
 
-use Zend_Form_Element_Hidden;
+use \Icinga\Web\Form\Element\Note;
+use \Icinga\Protocol\Commandpipe\CustomNotification;
 
 /**
  * For for command CustomNotification
@@ -36,11 +37,23 @@ use Zend_Form_Element_Hidden;
 class CustomNotificationForm extends CommandForm
 {
     /**
-     * Interface method to build the form
+     * Create the form's elements
-     * @see CommandForm::create
      */
     protected function create()
     {
+        $this->addElement(
+            new Note(
+                array(
+                    'name'  => 'commanddescription',
+                    'value' => t(
+                        'This command is used to send a custom notification about hosts or services. Useful in '
+                        . 'emergencies when you need to notify admins of an issue regarding a monitored system or '
+                        . 'service.'
+                    )
+                )
+            )
+        );
+
         $this->addElement($this->createAuthorField());
 
         $this->addElement(
@@ -52,14 +65,38 @@ class CustomNotificationForm extends CommandForm
                 'required' => true
             )
         );
+        $this->addElement(
+            new Note(
+                array(
+                    'name'  => 'commentnote',
+                    'value' => t(
+                        'If you work with other administrators, you may find it useful to share information '
+                        . 'about a host or service that is having problems if more than one of you may be working on '
+                        . 'it. Make sure you enter a brief description of what you are doing.'
+                    )
+                )
+            )
+        );
 
         $this->addElement(
             'checkbox',
-            'force',
+            'forced',
             array(
                 'label' => t('Forced')
             )
         );
+        $this->addElement(
+            new Note(
+                array(
+                    'name'  => 'forcenote',
+                    'value' => t(
+                        'Custom notifications normally follow the regular notification logic in Icinga. Selecting this '
+                        . 'option will force the notification to be sent out, regardless of the time restrictions, '
+                        . 'whether or not notifications are enabled, etc.'
+                    )
+                )
+            )
+        );
 
         $this->addElement(
             'checkbox',
@@ -68,26 +105,36 @@ class CustomNotificationForm extends CommandForm
                 'label' => t('Broadcast')
             )
         );
+        $this->addElement(
+            new Note(
+                array(
+                    'name'  => 'broadcastnote',
+                    'value' => t(
+                        'Selecting this option causes the notification to be sent out to all normal (non-escalated) '
+                        . ' and escalated contacts. These options allow you to override the normal notification logic '
+                        . 'if you need to get an important message out.'
+                    )
+                )
+            )
+        );
 
-        $this->setSubmitLabel(t('Send custom notification'));
+        $this->setSubmitLabel(t('Send Custom Notification'));
 
         parent::create();
     }
 
-    public function getComment()
+    /**
+     * Create Custom Notification from request data
+     *
+     * @return \Icinga\Protocol\Commandpipe\CustomNotification
+     */
+    public function getCustomNotification()
     {
-        return $this->getValue('comment');
+        return new CustomNotification(
-    }
+            $this->getAuthorName(),
-
+            $this->getValue('comment'),
-    public function getOptions()
+            $this->getValue('forced'),
-    {
+            $this->getValue('broadcast')
-        $value = 0;
+        );
-        if ($this->getValue('force')) {
-            $value |= 2;
-        }
-        if ($this->getValue('broadcast')) {
-            $value |= 1;
-        }
-        return $value;
     }
 }