Display alerts (#2482)

* Display Alerts : Recording new display events and Reporting.
Fixes xibosignage/xibo#3364
* Display Alerts : Command input
Fixes xibosignage/xibo#3399
* XMDS tests : add test to register a completely new Display.

db/migrations/20240408121908_display_alerts_migration.php

@@ -0,0 +1,50 @@
+<?php
+/*
+ * Copyright (C) 2024 Xibo Signage Ltd
+ *
+ * Xibo - Digital Signage - https://xibosignage.com
+ *
+ * This file is part of Xibo.
+ *
+ * Xibo is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * any later version.
+ *
+ * Xibo is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Xibo.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+use Phinx\Migration\AbstractMigration;
+
+/**
+ * Migration for adding more columns to displayevent table.
+ * Add a new column on Command table for createAlertOn.
+ * Add a new column on lkcommanddisplayprofile for createAlertOn.
+ * @phpcs:disable PSR1.Classes.ClassDeclaration.MissingNamespace
+ */
+class DisplayAlertsMigration extends AbstractMigration
+{
+    public function change(): void
+    {
+        $this->table('displayevent')
+            ->changeColumn('start', 'integer', ['null' => true])
+            ->addColumn('eventTypeId', 'integer', ['null' => false, 'default' => 1])
+            ->addColumn('refId', 'integer', ['null' => true, 'default' => null])
+            ->addColumn('detail', 'text', ['null' => true, 'default' => null])
+            ->save();
+
+        $this->table('command')
+            ->addColumn('createAlertOn', 'string', ['null' => false, 'default' => 'never'])
+            ->save();
+
+        $this->table('lkcommanddisplayprofile')
+            ->addColumn('createAlertOn', 'string', ['null' => true, 'default' => null])
+            ->save();
+    }
+}

lib/Controller/Command.php

@@ -369,6 +369,14 @@ public function deleteForm(Request $request, Response $response, $id)
      *      type="string",
      *      required=false
      *   ),
+     *  @SWG\Parameter(
+     *      name="createAlertOn",
+     *      in="formData",
+     *      description="On command execution, when should a Display alert be created?
+     * success, failure, always or never",
+     *      type="string",
+     *      required=false
+     *   ),
      *  @SWG\Response(
      *      response=201,
      *      description="successful operation",
@@ -398,6 +406,7 @@ public function add(Request $request, Response $response)
         $command->userId = $this->getUser()->userId;
         $command->commandString = $sanitizedParams->getString('commandString');
         $command->validationString = $sanitizedParams->getString('validationString');
+        $command->createAlertOn = $sanitizedParams->getString('createAlertOn', ['default' => 'never']);
         $availableOn = $sanitizedParams->getArray('availableOn');
         if (empty($availableOn)) {
             $command->availableOn = null;
@@ -476,6 +485,14 @@ public function add(Request $request, Response $response)
      *      type="string",
      *      required=false
      *   ),
+     *  @SWG\Parameter(
+     *      name="createAlertOn",
+     *      in="formData",
+     *      description="On command execution, when should a Display alert be created?
+     * success, failure, always or never",
+     *      type="string",
+     *      required=false
+     *   ),
      *  @SWG\Response(
      *      response=200,
      *      description="successful operation",
@@ -496,6 +513,7 @@ public function edit(Request $request, Response $response, $id)
         $command->description = $sanitizedParams->getString('description');
         $command->commandString = $sanitizedParams->getString('commandString');
         $command->validationString = $sanitizedParams->getString('validationString');
+        $command->createAlertOn = $sanitizedParams->getString('createAlertOn', ['default' => 'never']);
         $availableOn = $sanitizedParams->getArray('availableOn');
         if (empty($availableOn)) {
             $command->availableOn = null;
@@ -552,7 +570,7 @@ public function delete(Request $request, Response $response, $id)
             throw new AccessDeniedException();
         }
 
-        $this->getDispatcher()->dispatch(CommandDeleteEvent::$NAME, new CommandDeleteEvent($command));
+        $this->getDispatcher()->dispatch(new CommandDeleteEvent($command), CommandDeleteEvent::$NAME);
 
         $command->delete();
 

lib/Controller/Display.php

@@ -2474,6 +2474,8 @@ public function validateDisplays($displays)
                     $event = $this->displayEventFactory->createEmpty();
                     $event->displayId = $display->displayId;
                     $event->start = $display->lastAccessed;
+                    // eventTypeId 1 is for Display up/down events.
+                    $event->eventTypeId = 1;
                     $event->save();
                 }
 

lib/Controller/DisplayProfile.php

@@ -466,6 +466,7 @@ public function edit(Request $request, Response $response, $id)
                 // Set and assign the command
                 $command->commandString = $parsedParams->getString('commandString_' . $command->commandId);
                 $command->validationString = $parsedParams->getString('validationString_' . $command->commandId);
+                $command->createAlertOn = $parsedParams->getString('createAlertOn_' . $command->commandId);
 
                 $displayProfile->assignCommand($command);
             } else {

lib/Entity/Command.php

@@ -1,8 +1,8 @@
 <?php
 /*
- * Copyright (c) 2022 Xibo Signage Ltd
+ * Copyright (C) 2024 Xibo Signage Ltd
  *
- * Xibo - Digital Signage - http://www.xibo.org.uk
+ * Xibo - Digital Signage - https://xibosignage.com
  *
  * This file is part of Xibo.
  *
@@ -126,6 +126,21 @@ class Command implements \JsonSerializable
      */
     public $availableOn;
 
+    /**
+     * @SWG\Property(
+     *  description="Define if execution of this command should create an alert on success, failure, always or never."
+     * )
+     * @var string
+     */
+    public $createAlertOn;
+
+    /**
+     * @SWG\Property(
+     *     description="Create Alert On specific to the provided DisplayProfile."
+     * )
+     */
+    public $createAlertOnDisplayProfile;
+
     /**
      * @SWG\Property(description="A comma separated list of groups/users with permissions to this Command")
      * @var string
@@ -174,7 +189,19 @@ public function getCommandString()
      */
     public function getValidationString()
     {
-        return empty($this->validationStringDisplayProfile) ? $this->validationString : $this->validationStringDisplayProfile;
+        return empty($this->validationStringDisplayProfile)
+            ? $this->validationString
+            : $this->validationStringDisplayProfile;
+    }
+
+    /**
+     * @return string
+     */
+    public function getCreateAlertOn(): string
+    {
+        return empty($this->createAlertOnDisplayProfile)
+            ? $this->createAlertOn
+            : $this->createAlertOnDisplayProfile;
     }
 
     /**
@@ -210,18 +237,24 @@ public function isReady()
     public function validate()
     {
         if (!v::stringType()->notEmpty()->length(1, 254)->validate($this->command)) {
-            throw new InvalidArgumentException(__('Please enter a command name between 1 and 254 characters'),
-                'command');
+            throw new InvalidArgumentException(
+                __('Please enter a command name between 1 and 254 characters'),
+                'command'
+            );
         }
 
         if (!v::alpha('_')->NoWhitespace()->notEmpty()->length(1, 50)->validate($this->code)) {
-            throw new InvalidArgumentException(__('Please enter a code between 1 and 50 characters containing only alpha characters and no spaces'),
-                'code');
+            throw new InvalidArgumentException(
+                __('Please enter a code between 1 and 50 characters containing only alpha characters and no spaces'),
+                'code'
+            );
         }
 
         if (!v::stringType()->length(0, 1000)->validate($this->description)) {
-            throw new InvalidArgumentException(__('Please enter a description between 1 and 1000 characters'),
-                'description');
+            throw new InvalidArgumentException(
+                __('Please enter a description between 1 and 1000 characters'),
+                'description'
+            );
         }
     }
 
@@ -251,22 +284,44 @@ public function save($options = [])
      */
     public function delete()
     {
-        $this->getStore()->update('DELETE FROM `command` WHERE `commandId` = :commandId', ['commandId' => $this->commandId]);
+        $this->getStore()->update(
+            'DELETE FROM `command` WHERE `commandId` = :commandId',
+            ['commandId' => $this->commandId]
+        );
     }
 
     private function add()
     {
         $this->commandId = $this->getStore()->insert('
-            INSERT INTO `command` (`command`, `code`, `description`, `userId`, `commandString`, `validationString`, `availableOn`) 
-            VALUES (:command, :code, :description, :userId, :commandString, :validationString, :availableOn)
+            INSERT INTO `command` (
+                `command`,
+                `code`,
+                `description`,
+                `userId`,
+                `commandString`,
+                `validationString`,
+                `availableOn`,
+                `createAlertOn`
+            ) 
+            VALUES (
+                :command,
+                :code,
+                :description,
+                :userId,
+                :commandString,
+                :validationString,
+                :availableOn,
+                :createAlertOn
+            )
         ', [
             'command' => $this->command,
             'code' => $this->code,
             'description' => $this->description,
             'userId' => $this->userId,
             'commandString' => $this->commandString,
             'validationString' => $this->validationString,
-            'availableOn' => $this->availableOn
+            'availableOn' => $this->availableOn,
+            'createAlertOn' => $this->createAlertOn
         ]);
     }
 
@@ -280,7 +335,8 @@ private function edit()
               `userId` = :userId,
               `commandString` = :commandString, 
               `validationString` = :validationString,
-              `availableOn` = :availableOn
+              `availableOn` = :availableOn,
+              `createAlertOn` = :createAlertOn
              WHERE `commandId` = :commandId
         ', [
             'command' => $this->command,
@@ -290,7 +346,8 @@ private function edit()
             'commandId' => $this->commandId,
             'commandString' => $this->commandString,
             'validationString' => $this->validationString,
-            'availableOn' => $this->availableOn
+            'availableOn' => $this->availableOn,
+            'createAlertOn' => $this->createAlertOn
         ]);
     }
 }