PND Alerts endpoint (#437)

* Create PND Alert endpoint

* Remove regular alerts for PND authorization

---------

Co-authored-by: popey2700 <alex.pope@madetech.com>

Author: chiaramapellimt

openapi.yml

@@ -340,6 +340,50 @@ paths:
                 NoQueryParametersBadRequestError:
                   $ref: "#/components/examples/InternalServerError"
 
+  /v1/persons/{hmppsId}/alerts/pnd:
+    get:
+      tags:
+        - persons
+        - alerts
+      summary: Returns alerts associated with a person.
+      parameters:
+        - $ref: "#/components/parameters/HmppsId"
+        - $ref: "#/components/parameters/Page"
+        - $ref: "#/components/parameters/PerPage"
+      responses:
+        "200":
+          description: Successfully found alerts for a person with the provided HMPPS ID.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    minItems: 0
+                    items:
+                      $ref: "#/components/schemas/Alert"
+                  pagination:
+                    $ref: "#/components/schemas/Pagination"
+        "404":
+          description: Failed to find alerts a person with the provided HMPPS ID.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              examples:
+                PersonNotFoundError:
+                  $ref: "#/components/examples/PersonNotFoundError"
+        "500":
+          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              examples:
+                NoQueryParametersBadRequestError:
+                  $ref: "#/components/examples/InternalServerError"
+
   /v1/persons/{hmppsId}/sentences:
     get:
       tags:

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

@@ -36,4 +36,20 @@ class AlertsController(
     auditService.createEvent("GET_PERSON_ALERTS", mapOf("hmppsId" to hmppsId))
     return response.data.paginateWith(page, perPage)
   }
+
+  @GetMapping("{encodedHmppsId}/alerts/pnd")
+  fun getPersonAlertsPND(
+    @PathVariable encodedHmppsId: String,
+    @RequestParam(required = false, defaultValue = "1", name = "page") page: Int,
+    @RequestParam(required = false, defaultValue = "10", name = "perPage") perPage: Int,
+  ): PaginatedResponse<Alert> {
+    val hmppsId = encodedHmppsId.decodeUrlCharacters()
+    val response = getAlertsForPersonService.getAlertsForPnd(hmppsId)
+
+    if (response.hasError(UpstreamApiError.Type.ENTITY_NOT_FOUND)) {
+      throw EntityNotFoundException("Could not find person with id: $hmppsId")
+    }
+    auditService.createEvent("GET_PERSON_ALERTS_PND", mapOf("hmppsId" to hmppsId))
+    return response.data.paginateWith(page, perPage)
+  }
 }

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

@@ -3,7 +3,6 @@ package uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps
 data class UpstreamApiError(val causedBy: UpstreamApi, val type: Type, val description: String? = null) {
   enum class Type {
     ENTITY_NOT_FOUND,
-    ATTRIBUTE_NOT_FOUND,
     BAD_REQUEST,
     FORBIDDEN,
     INTERNAL_SERVER_ERROR,

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

@@ -5,6 +5,8 @@ import org.springframework.stereotype.Service
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.gateways.NomisGateway
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.Alert
 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
 
 @Service
 class GetAlertsForPersonService(
@@ -25,4 +27,41 @@ class GetAlertsForPersonService(
       errors = nomisAlerts.errors + personResponse.errors,
     )
   }
+
+  fun getAlertsForPnd(hmppsId: String): Response<List<Alert>> {
+    val personResponse = getPersonService.execute(hmppsId = hmppsId)
+    val nomisNumber = personResponse.data?.identifiers?.nomisNumber
+    var nomisAlerts: Response<List<Alert>> = Response(data = emptyList())
+
+    if (nomisNumber != null) {
+      val allNomisAlerts = nomisGateway.getAlertsForPerson(nomisNumber)
+      val filteredAlerts =
+        allNomisAlerts.data?.filter {
+          it.code in
+            listOf(
+              "BECTER", "HA", "XA", "XCA", "XEL", "XELH", "XER", "XHT", "XILLENT",
+              "XIS", "XR", "XRF", "XSA", "HA2", "RCS", "RDV", "RKC", "RPB", "RPC",
+              "RSS", "RST", "RDP", "REG", "RLG", "ROP", "RRV", "RTP", "RYP", "HS", "SC",
+            )
+        }.orEmpty()
+      if (filteredAlerts.isEmpty()) {
+        return Response(
+          data = emptyList(),
+          errors =
+            listOf(
+              UpstreamApiError(
+                causedBy = UpstreamApi.PRISONER_OFFENDER_SEARCH,
+                type = UpstreamApiError.Type.ENTITY_NOT_FOUND,
+              ),
+            ),
+        )
+      }
+      nomisAlerts = Response(data = filteredAlerts, errors = allNomisAlerts.errors)
+    }
+
+    return Response(
+      data = nomisAlerts.data,
+      errors = nomisAlerts.errors + personResponse.errors,
+    )
+  }
 }

src/main/resources/application-dev.yml

@@ -59,7 +59,7 @@ authorisation:
       - "/v1/persons"
       - "/v1/persons/\\.*+[^/]*$"
       - "/v1/persons/.*/addresses"
-      - "/v1/persons/.*/alerts"
+      - "/v1/persons/.*/alerts/pnd"
       - "/v1/persons/.*/sentences"
       - "/v1/persons/.*/sentences/latest-key-dates-and-adjustments"
       - "/v1/persons/.*/risks/scores"

src/main/resources/application-local-docker.yml

@@ -32,6 +32,7 @@ authorisation:
       - "/v1/persons/.*/addresses"
       - "/v1/persons/.*/offences"
       - "/v1/persons/.*/alerts"
+      - "/v1/persons/.*/alerts/pnd"
       - "/v1/persons/.*/sentences"
       - "/v1/persons/.*/sentences/latest-key-dates-and-adjustments"
       - "/v1/persons/.*/risks/scores"

src/main/resources/application-local.yml

@@ -39,6 +39,7 @@ authorisation:
       - "/v1/persons/.*/addresses"
       - "/v1/persons/.*/offences"
       - "/v1/persons/.*/alerts"
+      - "/v1/persons/.*/alerts/pnd"
       - "/v1/persons/.*/sentences"
       - "/v1/persons/.*/sentences/latest-key-dates-and-adjustments"
       - "/v1/persons/.*/risks/scores"

src/main/resources/application-test.yml

@@ -47,6 +47,7 @@ authorisation:
       - "/v1/persons/.*/addresses"
       - "/v1/persons/.*/offences"
       - "/v1/persons/.*/alerts"
+      - "/v1/persons/.*/alerts/pnd"
       - "/v1/persons/.*/sentences"
       - "/v1/persons/.*/sentences/latest-key-dates-and-adjustments"
       - "/v1/persons/.*/risks/scores"

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

@@ -39,6 +39,7 @@ internal class AlertsControllerTest(
       val hmppsId = "9999/11111A"
       val encodedHmppsId = URLEncoder.encode(hmppsId, StandardCharsets.UTF_8)
       val path = "/v1/persons/$encodedHmppsId/alerts"
+      val pndPath = "/v1/persons/$encodedHmppsId/alerts/pnd"
       val mockMvc = IntegrationAPIMockMvc(springMockMvc)
 
       describe("GET $path") {
@@ -188,5 +189,94 @@ internal class AlertsControllerTest(
           )
         }
       }
+      describe("GET $pndPath") {
+        beforeTest {
+          Mockito.reset(getAlertsForPersonService)
+          Mockito.reset(auditService)
+          whenever(getAlertsForPersonService.getAlertsForPnd(hmppsId)).thenReturn(
+            Response(
+              data =
+                listOf(
+                  Alert(
+                    offenderNo = "A1111BB",
+                    type = "B",
+                    typeDescription = "Security again",
+                    code = "BBB",
+                    codeDescription = "For Release",
+                    comment = "IS83",
+                    dateCreated = LocalDate.parse("2022-09-01"),
+                    dateExpired = LocalDate.parse("2023-09-01"),
+                    expired = false,
+                    active = false,
+                  ),
+                ),
+            ),
+          )
+        }
+
+        it("returns a 200 OK status code for PND") {
+          val result = mockMvc.performAuthorised(pndPath)
+          result.response.status.shouldBe(HttpStatus.OK.value())
+        }
+
+        it("returns paginated results for PND") {
+          whenever(getAlertsForPersonService.getAlertsForPnd(hmppsId)).thenReturn(
+            Response(
+              data =
+                List(20) {
+                  Alert(
+                    offenderNo = "B0000ZZ",
+                    type = "Z",
+                    typeDescription = "Threat",
+                    code = "BBB",
+                    codeDescription = "Not For Release",
+                    comment = "IS91",
+                    dateCreated = LocalDate.parse("2022-09-01"),
+                    dateExpired = LocalDate.parse("2023-10-01"),
+                    expired = false,
+                    active = false,
+                  )
+                },
+            ),
+          )
+
+          val result = mockMvc.performAuthorised("$pndPath?page=1&perPage=10")
+
+          result.response.contentAsString.shouldContainJsonKeyValue("$.pagination.page", 1)
+          result.response.contentAsString.shouldContainJsonKeyValue("$.pagination.totalPages", 2)
+        }
+
+        it("returns an empty list embedded in a JSON object when no alerts are found for PND") {
+          val hmppsIdForPersonWithNoAlerts = "1111/22334A"
+          val encodedHmppsIdForPersonWithNoAlerts =
+            URLEncoder.encode(hmppsIdForPersonWithNoAlerts, StandardCharsets.UTF_8)
+          val alertPath = "/v1/persons/$encodedHmppsIdForPersonWithNoAlerts/alerts/pnd"
+
+          whenever(getAlertsForPersonService.getAlertsForPnd(hmppsIdForPersonWithNoAlerts)).thenReturn(
+            Response(
+              data = emptyList(),
+            ),
+          )
+
+          val result = mockMvc.performAuthorised(alertPath)
+
+          result.response.contentAsString.shouldContain("\"data\":[]".removeWhitespaceAndNewlines())
+        }
+
+        it("logs audit for PND") {
+          mockMvc.performAuthorised(pndPath)
+
+          verify(
+            auditService,
+            VerificationModeFactory.times(1),
+          ).createEvent("GET_PERSON_ALERTS_PND", mapOf("hmppsId" to hmppsId))
+        }
+
+        it("gets the alerts for PND for a person with the matching ID") {
+          mockMvc.performAuthorised(pndPath)
+
+          verify(getAlertsForPersonService, VerificationModeFactory.times(1)).getAlertsForPnd(hmppsId)
+        }
+      }
     },
   )

src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/services/GetAlertsForPersonServiceTest.kt

@@ -2,6 +2,7 @@ package uk.gov.justice.digital.hmpps.hmppsintegrationapi.services
 
 import io.kotest.core.spec.style.DescribeSpec
 import io.kotest.matchers.collections.shouldHaveSize
+import io.kotest.matchers.shouldBe
 import org.mockito.Mockito
 import org.mockito.internal.verification.VerificationModeFactory
 import org.mockito.kotlin.verify
@@ -30,7 +31,8 @@ internal class GetAlertsForPersonServiceTest(
       val hmppsId = "1234/56789B"
       val prisonerNumber = "Z99999ZZ"
       val deliusCrn = "X777776"
-      val alert = Alert()
+      val alert = Alert(code = "XA", codeDescription = "Test Alert XA")
+      val nonMatchingAlert = Alert(code = "INVALID", codeDescription = "Invalid Alert")
 
       val person =
         Person(firstName = "Qui-gon", lastName = "Jin", identifiers = Identifiers(nomisNumber = prisonerNumber, deliusCrn = deliusCrn))
@@ -47,6 +49,7 @@ internal class GetAlertsForPersonServiceTest(
             data =
               listOf(
                 alert,
+                nonMatchingAlert,
               ),
           ),
         )
@@ -108,5 +111,46 @@ internal class GetAlertsForPersonServiceTest(
         val response = getAlertsForPersonService.execute(hmppsId)
         response.errors.shouldHaveSize(1)
       }
+
+      it("records errors when it cannot find PND alerts for a person") {
+        whenever(nomisGateway.getAlertsForPerson(id = prisonerNumber)).thenReturn(
+          Response(
+            data = emptyList(),
+            errors =
+              listOf(
+                UpstreamApiError(
+                  causedBy = UpstreamApi.NOMIS,
+                  type = UpstreamApiError.Type.ENTITY_NOT_FOUND,
+                ),
+              ),
+          ),
+        )
+
+        val response = getAlertsForPersonService.getAlertsForPnd(hmppsId)
+        response.errors.shouldHaveSize(1)
+      }
+
+      it("returns PND filtered data") {
+        val response = getAlertsForPersonService.getAlertsForPnd(hmppsId)
+
+        response.data.shouldHaveSize(1)
+        response.data[0].code shouldBe "XA"
+        response.data[0].codeDescription shouldBe "Test Alert XA"
+      }
+
+      it("returns an error when the alert code is not in the allowed list") {
+        whenever(personService.execute(hmppsId = deliusCrn)).thenReturn(Response(person))
+        whenever(personService.execute(hmppsId = hmppsId)).thenReturn(Response(person))
+        whenever(nomisGateway.getAlertsForPerson(prisonerNumber)).thenReturn(
+          Response(
+            data = listOf(nonMatchingAlert),
+          ),
+        )
+
+        val response = getAlertsForPersonService.getAlertsForPnd(hmppsId)
+
+        response.errors.shouldHaveSize(1)
+        response.data.shouldHaveSize(0)
+      }
     },
   )

src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/smoke/AuthoriseConfigTest.kt

@@ -27,6 +27,7 @@ class AuthoriseConfigTest : DescribeSpec(
           "/v1/persons/.*/addresses",
           "/v1/persons/.*/offences",
           "/v1/persons/.*/alerts",
+          "/v1/persons/.*/alerts/pnd",
           "/v1/persons/.*/sentences",
           "/v1/persons/.*/sentences/latest-key-dates-and-adjustments",
           "/v1/persons/.*/risks/scores",

src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/smoke/person/AlertsSmokeTest.kt

@@ -20,6 +20,39 @@ class AlertsSmokeTest : DescribeSpec(
     it("returns alerts for a person") {
       val response = httpClient.performAuthorised(basePath)
 
+      response.statusCode().shouldBe(HttpStatus.OK.value())
+      response.body().shouldEqualJson(
+        """
+        {
+          "data": [
+            {
+              "offenderNo": "G3878UK",
+              "type": "X",
+              "typeDescription": "Security",
+              "code": "XER",
+              "codeDescription": "Escape Risk",
+              "comment": "Profession lock pick.",
+              "dateCreated": "2019-08-20",
+              "dateExpired": "2020-08-20",
+              "expired": true,
+              "active": false
+            }
+          ],
+            "pagination": {
+              "isLastPage": true,
+              "count": 1,
+              "page": 1,
+              "perPage": 10,
+              "totalCount": 1,
+              "totalPages": 1
+            }
+          }
+          """.removeWhitespaceAndNewlines(),
+      )
+    }
+    it("returns PND alerts for a person") {
+      val response = httpClient.performAuthorised("$basePath/pnd")
+
       response.statusCode().shouldBe(HttpStatus.OK.value())
       response.body().shouldEqualJson(
         """