TSK-1530: Add a REST endpoint to cancel a task

rest/taskana-rest-spring/src/docs/asciidoc/rest-api.adoc

@@ -23,6 +23,7 @@ include::{snippets}/TaskControllerRestDocTest/claimTaskDocTest/auto-section.adoc
 include::{snippets}/TaskControllerRestDocTest/selectAndClaimTaskDocTest/auto-section.adoc[]
 include::{snippets}/TaskControllerRestDocTest/cancelClaimTaskDocTest/auto-section.adoc[]
 include::{snippets}/TaskControllerRestDocTest/completeTaskDocTest/auto-section.adoc[]
+include::{snippets}/TaskControllerRestDocTest/cancelTaskDocTest/auto-section.adoc[]
 include::{snippets}/TaskControllerRestDocTest/transferTaskDocTest/auto-section.adoc[]
 include::{snippets}/TaskControllerRestDocTest/deleteTaskDocTest/auto-section.adoc[]
 include::{snippets}/TaskControllerRestDocTest/deleteTasksDocTest/auto-section.adoc[]

rest/taskana-rest-spring/src/main/java/pro/taskana/common/rest/RestEndpoints.java

@@ -44,6 +44,7 @@ public final class RestEndpoints {
   public static final String URL_TASKS_ID_CLAIM = API_V1 + "tasks/{taskId}/claim";
   public static final String URL_TASKS_ID_SELECT_AND_CLAIM = API_V1 + "tasks/select-and-claim";
   public static final String URL_TASKS_ID_COMPLETE = API_V1 + "tasks/{taskId}/complete";
+  public static final String URL_TASKS_ID_CANCEL = API_V1 + "tasks/{taskId}/cancel";
   public static final String URL_TASKS_ID_TRANSFER_WORKBASKET_ID =
       API_V1 + "tasks/{taskId}/transfer/{workbasketId}";
 

rest/taskana-rest-spring/src/main/java/pro/taskana/task/rest/TaskController.java

@@ -316,6 +316,34 @@ public class TaskController {
     return result;
   }
 
+  /**
+   * This endpoint cancels a Task. Cancellation marks a Task as obsolete. The actual work the Task
+   * was referring to is no longer required
+   *
+   * @param taskId Id of the requested Task to cancel.
+   * @return the cancelled Task
+   * @throws TaskNotFoundException if the requested Task does not exist.
+   * @throws InvalidStateException if the task is not in state READY or CLAIMED
+   * @throws NotAuthorizedException if the current user has no read permission for the Workbasket
+   *     the Task is in
+   * @title Cancel a Task
+   */
+  @PostMapping(path = RestEndpoints.URL_TASKS_ID_CANCEL)
+  @Transactional(rollbackFor = Exception.class)
+  public ResponseEntity<TaskRepresentationModel> cancelTask(@PathVariable String taskId)
+      throws TaskNotFoundException, NotAuthorizedException, InvalidStateException {
+    LOGGER.debug("Entry to cancelTask(taskId= {})", taskId);
+
+    Task cancelledTask = taskService.cancelTask(taskId);
+    ResponseEntity<TaskRepresentationModel> result =
+        ResponseEntity.ok(taskRepresentationModelAssembler.toModel(cancelledTask));
+    if (LOGGER.isDebugEnabled()) {
+      LOGGER.debug("Exit from cancelTask(), returning {}", result);
+    }
+
+    return result;
+  }
+
   /**
    * This endpoint creates a persistent Task.
    *

rest/taskana-rest-spring/src/test/java/pro/taskana/task/rest/TaskControllerIntTest.java

@@ -751,6 +751,36 @@ class TaskControllerIntTest {
     con.disconnect();
   }
 
+  @Test
+  void should_CancelTask_when_CallingCancelEndpoint() {
+
+    final String claimed_task_id = "TKI:000000000000000000000000000000000026";
+
+    // retrieve task from Rest Api
+    ResponseEntity<TaskRepresentationModel> responseGet =
+        TEMPLATE.exchange(
+            restHelper.toUrl(RestEndpoints.URL_TASKS_ID, claimed_task_id),
+            HttpMethod.GET,
+            new HttpEntity<>(restHelper.getHeadersUser_1_2()),
+            TASK_MODEL_TYPE);
+
+    assertThat(responseGet.getBody()).isNotNull();
+    TaskRepresentationModel theTaskRepresentationModel = responseGet.getBody();
+    assertThat(theTaskRepresentationModel.getState()).isEqualTo(TaskState.CLAIMED);
+
+    // cancel the task
+    responseGet =
+        template.exchange(
+            restHelper.toUrl(RestEndpoints.URL_TASKS_ID_CANCEL, claimed_task_id),
+            HttpMethod.POST,
+            new HttpEntity<>(restHelper.getHeadersUser_1_2()),
+            TASK_MODEL_TYPE);
+
+    assertThat(responseGet.getBody()).isNotNull();
+    theTaskRepresentationModel = responseGet.getBody();
+    assertThat(theTaskRepresentationModel.getState()).isEqualTo(TaskState.CANCELLED);
+  }
+
   @Test
   void testCancelClaimTask() {
 

rest/taskana-rest-spring/src/test/java/pro/taskana/task/rest/TaskControllerRestDocTest.java

@@ -83,6 +83,14 @@ class TaskControllerRestDocTest extends BaseRestDocTest {
         .andExpect(MockMvcResultMatchers.status().isOk());
   }
 
+  @Test
+  void cancelTaskDocTest() throws Exception {
+    mockMvc
+        .perform(
+            post(RestEndpoints.URL_TASKS_ID_CANCEL, "TKI:000000000000000000000000000000000026"))
+        .andExpect(MockMvcResultMatchers.status().isOk());
+  }
+
   @Test
   void createTaskDocTest() throws Exception {
     final Task task = taskService.newTask("WBI:100000000000000000000000000000000004");