REST API: implement acknowledge

Author: Thomas-Gelf

application/controllers/IssueController.php

@@ -283,7 +283,17 @@ public function acknowledgeAction()
             throw new NotFoundError('Not found');
         }
 
-        // TODO: implement.
+        $this->runForApi(function () {
+            if (! $this->checkBearerToken('issue/acknowledge')) {
+                return;
+            }
+            $uuids = $this->findApiRequestIssues();
+
+            $this->apiRpcRequestForIssues('issue.acknowledge', 'issues', $uuids, [
+                $this->params->getRequired('owner'),
+                $this->params->get('ticket_ref'),
+            ]);
+        });
     }
 
     /**
@@ -295,24 +305,25 @@ public function closeAction()
             throw new NotFoundError('Not found');
         }
         $this->runForApi(function () {
-            $this->closeForApi();
+            if (! $this->checkBearerToken('issue/close')) {
+                return;
+            }
+            $uuids = $this->findApiRequestIssues(true);
+
+            $this->apiRpcRequestForIssues('issue.close', 'closedIssues', $uuids, [
+                $this->params->getRequired('closedBy')
+            ]);
         });
     }
 
-    public function closeForApi()
+    protected function apiRpcRequestForIssues(string $method, string $resultKey, array $issueUuids, ...$rpcParams)
     {
-        if (! $this->checkBearerToken('issue/close')) {
-            return;
-        }
-        $uuids = $this->findApiRequestIssues();
-        $closedBy = $this->params->getRequired('closedBy');
         $client = $this->remoteClient();
         $requests = [];
-        foreach ($uuids as $uuid) {
-            $requests[$uuid] = $client->request('issue.close', [
+        foreach ($issueUuids as $uuid) {
+            $requests[$uuid] = $client->request($method, array_merge([
                 $uuid,
-                $closedBy
-            ]);
+            ], $rpcParams));
         }
         $result = [];
         foreach (awaitAll($requests) as $uuid => $success) {
@@ -328,16 +339,16 @@ public function closeForApi()
             ], 201);
         } else {
             $this->sendJsonResponse((object) [
-                'success'      => true,
-                'closedIssues' => $result
+                'success'  => true,
+                $resultKey => $result
             ]);
         }
     }
 
-    protected function findApiRequestIssues(): array
+    protected function findApiRequestIssues(bool $allowTicketRef = false): array
     {
         $db = $this->db();
-        if ($ticket = $this->params->get('ticket')) {
+        if ($allowTicketRef && ($ticket = $this->params->get('ticket'))) {
             $uuids = $db->fetchCol($db->select()->from('issue', 'issue_uuid')->where('ticket_ref = ?', $ticket));
             foreach ($uuids as $idx => $uuid) {
                 $uuids[$idx] = Uuid::fromBytes($uuid)->toString();

doc/61-REST_API.md

@@ -230,6 +230,46 @@ The `closedBy` parameter is required for all `close` variants.
 }
 ```
 
+### Acknowledge an Issue
+
+To acknowledge an issue, please provide its UUID in an HTTP POST request. Example:
+
+```http
+POST https://monitoring.example.com/icingaweb2/eventtracker/issue/acknowledge?uuid=0f9ab9e0-600a-4e05-8e13-e48b20b1d37e&owner=John&ticker_ref=ITSM0231
+Authorization: Bearer e756ca41-875f-4f92-991c-706dc07af192
+Accept: application/json
+```
+
+Acknowledging issues via `sender_event_id` is also supported:
+
+```http
+POST https://icinga.example.com/icingaweb2/eventtracker/issue/close?sender_event_id=My%20Job%20Name&owner=me
+Authorization: Bearer e756ca41-875f-4f92-991c-706dc07af192
+Accept: application/json
+```
+
+The `owner` parameter is required for all `acknowledge` variants, the `ticket_ref` parameter is optional.
+
+#### Sample Responses
+
+##### Success (200 Ok)
+
+```json
+{
+  "success": true,
+  "issues": ["0f9ab9e0-600a-4e05-8e13-e48b20b1d37e"]
+}
+```
+
+##### No related issue found (201 Unmodified)
+
+```json
+{
+  "success": true,
+  "error": "Found no issue for the given ticket/issue"
+}
+```
+
 Creating Issues
 ---------------
 

library/Eventtracker/Daemon/RpcNamespace/RpcNamespaceIssue.php

@@ -94,6 +94,29 @@ protected function close(UuidInterface $uuid, $reason, $closedBy = null): bool
         return true;
     }
 
+    /**
+     * @param string $issueUuid
+     * @param string $owner
+     * @param string $ticketReference
+     * @return bool
+     */
+    protected function acknowledge(UuidInterface $uuid, string $owner, ?string $ticketReference = null): bool
+    {
+        if ($this->db === null) {
+            throw new RuntimeException('Cannot close the given issue, I have no DB connection');
+        }
+        $db = $this->db;
+        $issue = Issue::load($uuid->getBytes(), $db);
+        $issue->set('status', 'acknowledged');
+        $issue->set('owner', $owner);
+        if ($ticketReference !== null) {
+            $issue->set('ticket_ref', $ticketReference);
+        }
+        $issue->storeToDb($db);
+
+        return true;
+    }
+
     public function initDb(Db $db): ExtendedPromiseInterface
     {
         $this->db = $db;

library/Eventtracker/Web/Form/ApiTokenForm.php

@@ -55,7 +55,7 @@ protected function assemble()
             'required' => true,
             'multiple' => true,
             'options'  => [
-                'issue/acknowledge' => $this->translate('Acknowledge Issues (not yet)'),
+                'issue/acknowledge' => $this->translate('Acknowledge'),
                 'issue/close' => $this->translate('Close Issues'),
                 'issues/fetch' => $this->translate('Fetch Issues'),
                 'host_list/read' => $this->translate('Read permission for Host list'),