HMAI -237 Cancelled - POST /v1/visit/{visitReference}/cancel (#765)

* add CancelVisitRequest model and sendCancelVisit to VisitQueueService

* service tests

* add more tests for queue service and controller logic

* add controller tests for cancel visit

* remove prisonerId from cancelVisitRequest; adjust service to use getVisitInformationByReference service

* use visitReference parameter from url instead of request body

* add integration tests

---------

Co-authored-by: BushraAbdullahi <bushra.abdullahi@digital.justice.gov.uk>

Author: emmalanigan

src/main/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/controllers/v1/VisitsController.kt

@@ -16,6 +16,7 @@ import org.springframework.web.bind.annotation.RequestBody
 import org.springframework.web.bind.annotation.RequestMapping
 import org.springframework.web.bind.annotation.RestController
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.exception.EntityNotFoundException
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.CancelVisitRequest
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.CreateVisitRequest
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.DataResponse
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.HmppsMessageResponse
@@ -131,7 +132,66 @@ class VisitsController(
       throw ValidationException("Either invalid prisoner or prison id.")
     }
 
-    auditService.createEvent("POST_VISIT", mapOf())
+    auditService.createEvent("POST_VISIT", mapOf("prisonerId" to createVisitRequest.prisonerId, "clientVisitReference" to createVisitRequest.clientVisitReference, "clientName" to clientName.orEmpty()))
+
+    return DataResponse(response.data)
+  }
+
+  @Operation(
+    summary = "Cancel visit.",
+    description = "<br><br><b>Applicable filters</b>: <ul><li>prisons</li></ul>",
+    responses = [
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully wrote to visit queue."),
+      ApiResponse(
+        responseCode = "400",
+        content = [
+          Content(
+            schema =
+              io.swagger.v3.oas.annotations.media
+                .Schema(ref = "#/components/schemas/BadRequest"),
+          ),
+        ],
+      ),
+      ApiResponse(
+        responseCode = "404",
+        content = [
+          Content(
+            schema =
+              io.swagger.v3.oas.annotations.media
+                .Schema(ref = "#/components/schemas/PersonNotFound"),
+          ),
+        ],
+      ),
+      ApiResponse(
+        responseCode = "500",
+        content = [
+          Content(
+            schema =
+              io.swagger.v3.oas.annotations.media
+                .Schema(ref = "#/components/schemas/InternalServerError"),
+          ),
+        ],
+      ),
+    ],
+  )
+  @PostMapping("/{visitReference}/cancel")
+  fun postCancelVisit(
+    @Valid @RequestBody cancelVisitRequest: CancelVisitRequest,
+    @Parameter(description = "The visit reference number relating to the visit.") @PathVariable visitReference: String,
+    @RequestAttribute clientName: String?,
+    @RequestAttribute filters: ConsumerFilters?,
+  ): DataResponse<HmppsMessageResponse?> {
+    val response = visitQueueService.sendCancelVisit(visitReference, cancelVisitRequest, clientName.orEmpty(), filters)
+
+    if (response.hasError(UpstreamApiError.Type.ENTITY_NOT_FOUND)) {
+      throw EntityNotFoundException("Could not find prisoner")
+    }
+
+    if (response.hasError(UpstreamApiError.Type.BAD_REQUEST)) {
+      throw ValidationException("Either invalid prisoner or prison id.")
+    }
+
+    auditService.createEvent("POST_CANCEL_VISIT", mapOf("visitReference" to visitReference, "clientName" to clientName.orEmpty()))
 
     return DataResponse(response.data)
   }

src/main/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/models/hmpps/CancelVisitRequest.kt

@@ -0,0 +1,53 @@
+package uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps
+
+import io.swagger.v3.oas.annotations.media.Schema
+
+@Schema(description = "Private prison visit cancellation request")
+data class CancelVisitRequest(
+  @Schema(description = "Outcome status and description", required = true)
+  val cancelOutcome: CancelOutcome,
+  @Schema(description = "Username for user who actioned this request", required = false)
+  val actionedBy: String?,
+) {
+  fun toHmppsMessage(who: String): HmppsMessage =
+    HmppsMessage(
+      eventType = HmppsMessageEventType.VISIT_CANCELLED,
+      messageAttributes = modelToMap(),
+      who = who,
+    )
+
+  private fun modelToMap(): Map<String, Any?> =
+    mapOf(
+      "cancelOutcome" to this.cancelOutcome,
+      "actionedBy" to this.actionedBy,
+    )
+}
+
+data class CancelOutcome(
+  val outcomeStatus: OutcomeStatus,
+  val text: String,
+)
+
+enum class OutcomeStatus {
+  ADMINISTRATIVE_CANCELLATION,
+  ADMINISTRATIVE_ERROR,
+  BATCH_CANCELLATION,
+  CANCELLATION,
+  COMPLETED_NORMALLY,
+  ESTABLISHMENT_CANCELLED,
+  NOT_RECORDED,
+  NO_VISITING_ORDER,
+  PRISONER_CANCELLED,
+  PRISONER_COMPLETED_EARLY,
+  PRISONER_REFUSED_TO_ATTEND,
+  TERMINATED_BY_STAFF,
+  VISITOR_CANCELLED,
+  VISITOR_COMPLETED_EARLY,
+  VISITOR_DECLINED_ENTRY,
+  VISITOR_DID_NOT_ARRIVE,
+  VISITOR_FAILED_SECURITY_CHECKS,
+  VISIT_ORDER_CANCELLED,
+  SUPERSEDED_CANCELLATION,
+  DETAILS_CHANGED_AFTER_BOOKING,
+  BOOKER_CANCELLED,
+}

src/main/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/services/VisitQueueService.kt

@@ -5,6 +5,7 @@ import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.stereotype.Service
 import software.amazon.awssdk.services.sqs.model.SendMessageRequest
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.exception.MessageFailedException
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.CancelVisitRequest
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.CreateVisitRequest
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.HmppsMessageResponse
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.Response
@@ -18,6 +19,7 @@ class VisitQueueService(
   @Autowired private val getPersonService: GetPersonService,
   @Autowired private val hmppsQueueService: HmppsQueueService,
   @Autowired private val objectMapper: ObjectMapper,
+  @Autowired private val getVisitInformationByReferenceService: GetVisitInformationByReferenceService,
 ) {
   private val visitsQueue by lazy { hmppsQueueService.findByQueueId("visits") as HmppsQueue }
   private val visitsQueueSqsClient by lazy { visitsQueue.sqsClient }
@@ -54,4 +56,36 @@ class VisitQueueService(
       throw MessageFailedException("Could not send Visit message to queue", e)
     }
   }
+
+  fun sendCancelVisit(
+    visitReference: String,
+    visit: CancelVisitRequest,
+    who: String,
+    consumerFilters: ConsumerFilters?,
+  ): Response<HmppsMessageResponse?> {
+    val visitResponse = getVisitInformationByReferenceService.execute(visitReference, consumerFilters)
+
+    if (visitResponse.errors.isNotEmpty()) {
+      return Response(data = null, errors = visitResponse.errors)
+    }
+
+    val hmppsMessage = visit.toHmppsMessage(who)
+
+    try {
+      val stringifiedMessage = objectMapper.writeValueAsString(hmppsMessage)
+      val sendMessageRequest =
+        SendMessageRequest
+          .builder()
+          .queueUrl(visitsQueueUrl)
+          .messageBody(stringifiedMessage)
+          .eventTypeMessageAttributes(hmppsMessage.eventType.toString())
+          .build()
+
+      visitsQueueSqsClient.sendMessage(sendMessageRequest)
+
+      return Response(HmppsMessageResponse(message = "Visit cancellation written to queue"))
+    } catch (e: Exception) {
+      throw MessageFailedException("Could not send Visit cancellation to queue", e)
+    }
+  }
 }

src/main/resources/application-integration-test.yml

@@ -112,6 +112,7 @@ authorisation:
         - "/v1/persons/.*/visitor/.*/restrictions"
         - "/v1/visit/[^/]*$"
         - "/v1/visit"
+        - "/v1/visit/.*/cancel"
         - "/v1/prison/.*/visit/search[^/]*$"
         - "/v1/contacts/[^/]*$"
         - "/v1/persons/.*/contacts[^/]*$"

src/main/resources/application-test.yml

@@ -115,6 +115,7 @@ authorisation:
         - "/v1/persons/.*/visitor/.*/restrictions"
         - "/v1/visit/[^/]*$"
         - "/v1/visit"
+        - "/v1/visit/.*/cancel"
         - "/v1/prison/.*/visit/search[^/]*$"
         - "/v1/contacts/[^/]*$"
         - "/v1/persons/.*/contacts[^/]*$"

src/main/resources/globals.yml

@@ -36,4 +36,5 @@ globals:
         - "/v1/prison/.*/visit/search[^/]*$"
         - "/v1/visit/[^/]*$"
         - "/v1/visit"
+        - "/v1/visit/.*/cancel"
         - "/v1/contacts/[^/]*$"

src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/controllers/v1/VisitsControllerTest.kt

@@ -15,8 +15,11 @@ import org.springframework.test.web.servlet.MockMvc
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.exception.MessageFailedException
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.extensions.removeWhitespaceAndNewlines
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.helpers.IntegrationAPIMockMvc
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.CancelOutcome
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.CancelVisitRequest
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.CreateVisitRequest
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.HmppsMessageResponse
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.OutcomeStatus
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.Response
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.UpstreamApi
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.UpstreamApiError
@@ -173,7 +176,7 @@ class VisitsControllerTest(
           verify(
             auditService,
             times(1),
-          ).createEvent("POST_VISIT", mapOf())
+          ).createEvent("POST_VISIT", mapOf("prisonerId" to createVisitRequest.prisonerId, "clientVisitReference" to createVisitRequest.clientVisitReference, "clientName" to clientName))
         }
 
         it("Calls the visit queue service and gets a response") {
@@ -211,5 +214,73 @@ class VisitsControllerTest(
           result.response.status.shouldBe(HttpStatus.INTERNAL_SERVER_ERROR.value())
         }
       }
+
+      describe("/v1/visit/{visitReference}/cancel") {
+        val visitReference = "1234567"
+        val path = "/v1/visit/$visitReference/cancel"
+        val filters = null
+        val message = "Visit Message"
+        val postResponse = HmppsMessageResponse(message = message)
+        val clientName = "automated-test-client"
+        val cancelVisitRequest =
+          CancelVisitRequest(
+            cancelOutcome =
+              CancelOutcome(
+                outcomeStatus = OutcomeStatus.VISIT_ORDER_CANCELLED,
+                text = "Visitor has informed us they cannot make the visit.",
+              ),
+            actionedBy = "someUser",
+          )
+
+        beforeTest {
+          Mockito.reset(visitQueueService)
+
+          whenever(visitQueueService.sendCancelVisit(visitReference, cancelVisitRequest, clientName, filters)).thenReturn(Response(data = postResponse))
+        }
+
+        it("logs audit") {
+          mockMvc.performAuthorisedPost(path, cancelVisitRequest)
+
+          verify(
+            auditService,
+            times(1),
+          ).createEvent("POST_CANCEL_VISIT", mapOf("visitReference" to visitReference, "clientName" to clientName))
+        }
+
+        it("Calls the visit queue service and gets a response") {
+          val result = mockMvc.performAuthorisedPost(path, cancelVisitRequest)
+          result.response.status.shouldBe(HttpStatus.OK.value())
+          result.response.contentAsString shouldBe (
+            """
+            {
+              "data": {
+                "message": "$message"
+              }
+            }
+          """.removeWhitespaceAndNewlines()
+          )
+        }
+
+        it("returns a 400 when upstream returns 400") {
+          whenever(visitQueueService.sendCancelVisit(visitReference, cancelVisitRequest, clientName, filters)).thenReturn(Response(data = null, errors = listOf(UpstreamApiError(causedBy = UpstreamApi.MANAGE_PRISON_VISITS, type = UpstreamApiError.Type.BAD_REQUEST))))
+
+          val result = mockMvc.performAuthorisedPost(path, cancelVisitRequest)
+          result.response.status.shouldBe(HttpStatus.BAD_REQUEST.value())
+        }
+
+        it("returns a 404 when upstream returns 404") {
+          whenever(visitQueueService.sendCancelVisit(visitReference, cancelVisitRequest, clientName, filters)).thenReturn(Response(data = null, errors = listOf(UpstreamApiError(causedBy = UpstreamApi.MANAGE_PRISON_VISITS, type = UpstreamApiError.Type.ENTITY_NOT_FOUND))))
+
+          val result = mockMvc.performAuthorisedPost(path, cancelVisitRequest)
+          result.response.status.shouldBe(HttpStatus.NOT_FOUND.value())
+        }
+
+        it("gets a 500 when visit queue service throws MessageFailedException") {
+          whenever(visitQueueService.sendCancelVisit(visitReference, cancelVisitRequest, clientName, filters)).thenThrow(MessageFailedException("Could not send Visit message to queue"))
+
+          val result = mockMvc.performAuthorisedPost(path, cancelVisitRequest)
+          result.response.status.shouldBe(HttpStatus.INTERNAL_SERVER_ERROR.value())
+        }
+      }
     },
   )

src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/integration/VisitsIntegrationTest.kt

@@ -13,7 +13,10 @@ import org.springframework.test.web.servlet.result.MockMvcResultMatchers.status
 import software.amazon.awssdk.services.sqs.model.Message
 import software.amazon.awssdk.services.sqs.model.PurgeQueueRequest
 import software.amazon.awssdk.services.sqs.model.ReceiveMessageRequest
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.CancelOutcome
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.CancelVisitRequest
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.CreateVisitRequest
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.OutcomeStatus
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.VisitRestriction
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.VisitStatus
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.VisitType
@@ -169,4 +172,67 @@ class VisitsIntegrationTest : IntegrationTestBase() {
         .andExpect(status().isNotFound)
     }
   }
+
+  @DisplayName("POST /v1/visit/{visitReference}/cancel")
+  @Nested
+  inner class PostCancelVisit {
+    private val visitReference = "123456"
+    private val path = "/v1/visit/$visitReference/cancel"
+    private val cancelVisitRequest =
+      CancelVisitRequest(
+        cancelOutcome =
+          CancelOutcome(
+            outcomeStatus = OutcomeStatus.VISIT_ORDER_CANCELLED,
+            text = "visit order cancelled",
+          ),
+        actionedBy = "test-consumer",
+      )
+
+    @Test
+    fun `post the visit cancellation, get back a message response and find a message on the queue`() {
+      val requestBody = asJsonString(cancelVisitRequest)
+
+      postToApi(path, requestBody)
+        .andExpect(status().isOk)
+        .andExpect(
+          content().json(
+            """
+            {
+              "data": {
+                  "message": "Visit cancellation written to queue"
+              }
+            }
+            """,
+          ),
+        )
+
+      val queueMessages = getQueueMessages()
+      queueMessages.size.shouldBe(1)
+
+      val messageJson = queueMessages[0].body()
+      val expectedMessage = cancelVisitRequest.toHmppsMessage(defaultCn)
+      messageJson.shouldContainJsonKeyValue("$.eventType", expectedMessage.eventType.eventTypeCode)
+      messageJson.shouldContainJsonKeyValue("$.who", defaultCn)
+      val objectMapper = jacksonObjectMapper()
+      val messageAttributes = objectMapper.readTree(messageJson).at("/messageAttributes")
+      val expectedMessageAttributes = objectMapper.readTree(objectMapper.writeValueAsString(expectedMessage.messageAttributes))
+      messageAttributes.shouldBe(expectedMessageAttributes)
+    }
+
+    @Test
+    fun `return a 404 when prison not in filter`() {
+      val requestBody = asJsonString(cancelVisitRequest)
+
+      postToApiWithCN(path, requestBody, limitedPrisonsCn)
+        .andExpect(status().isNotFound)
+    }
+
+    @Test
+    fun `return a 404 when no prisons in filter`() {
+      val requestBody = asJsonString(cancelVisitRequest)
+
+      postToApiWithCN(path, requestBody, noPrisonsCn)
+        .andExpect(status().isNotFound)
+    }
+  }
 }