HMAI-307 Add Prisons filter to /v1/persons/{hmppsId}/protected-characteristics so can be used by kilco (#745)

* remove encodedhmppsid from controller and add filters

* add filtering to service layer

* add /v1/persons/.*/protected-characteristics to private prison role

Author: emmalanigan

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

@@ -6,16 +6,18 @@ import io.swagger.v3.oas.annotations.media.Content
 import io.swagger.v3.oas.annotations.media.Schema
 import io.swagger.v3.oas.annotations.responses.ApiResponse
 import io.swagger.v3.oas.annotations.tags.Tag
+import jakarta.validation.ValidationException
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.web.bind.annotation.GetMapping
 import org.springframework.web.bind.annotation.PathVariable
+import org.springframework.web.bind.annotation.RequestAttribute
 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.extensions.decodeUrlCharacters
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.DataResponse
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.PersonProtectedCharacteristics
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.UpstreamApiError
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.roleconfig.ConsumerFilters
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.GetProtectedCharacteristicsService
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.internal.AuditService
 
@@ -26,24 +28,29 @@ class ProtectedCharacteristicsController(
   @Autowired val getProtectedCharacteristicsService: GetProtectedCharacteristicsService,
   @Autowired val auditService: AuditService,
 ) {
-  @GetMapping("{encodedHmppsId}/protected-characteristics")
+  @GetMapping("{hmppsId}/protected-characteristics")
   @Operation(
     summary = "Returns protected characteristics of a person.",
+    description = "<b>Applicable filters</b>: <ul><li>prisons</li></ul>",
     responses = [
       ApiResponse(responseCode = "200", useReturnTypeSchema = true),
+      ApiResponse(responseCode = "400", content = [Content(schema = Schema(ref = "#/components/schemas/BadRequest"))]),
       ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],
   )
-  fun getPersonAddresses(
-    @Parameter(description = "A URL-encoded HMPPS identifier", example = "2008%2F0545166T") @PathVariable encodedHmppsId: String,
+  fun getProtectedCharacteristics(
+    @Parameter(description = "The HMPPS ID of the person", example = "G2996UX") @PathVariable hmppsId: String,
+    @RequestAttribute filters: ConsumerFilters?,
   ): DataResponse<PersonProtectedCharacteristics?> {
-    val hmppsId = encodedHmppsId.decodeUrlCharacters()
-    val response = getProtectedCharacteristicsService.execute(hmppsId)
+    val response = getProtectedCharacteristicsService.execute(hmppsId, filters)
 
     if (response.hasError(UpstreamApiError.Type.ENTITY_NOT_FOUND)) {
       throw EntityNotFoundException("Could not find person with id: $hmppsId")
     }
+    if (response.hasError(UpstreamApiError.Type.BAD_REQUEST)) {
+      throw ValidationException("Invalid id: $hmppsId")
+    }
     auditService.createEvent("GET_PERSON_PROTECTED_CHARACTERISTICS", mapOf("hmppsId" to hmppsId))
     return DataResponse(response.data)
   }

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

@@ -2,26 +2,51 @@ package uk.gov.justice.digital.hmpps.hmppsintegrationapi.services
 
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.stereotype.Service
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.common.ConsumerPrisonAccessService
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.gateways.NomisGateway
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.gateways.PrisonerOffenderSearchGateway
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.gateways.ProbationOffenderSearchGateway
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.PersonProtectedCharacteristics
 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
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.roleconfig.ConsumerFilters
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.GetPersonService.IdentifierType
 
 @Service
 class GetProtectedCharacteristicsService(
   @Autowired val probationOffenderSearchGateway: ProbationOffenderSearchGateway,
   @Autowired val prisonerOffenderSearchGateway: PrisonerOffenderSearchGateway,
   @Autowired val nomisGateway: NomisGateway,
+  @Autowired val consumerPrisonAccessService: ConsumerPrisonAccessService,
+  @Autowired val getPersonService: GetPersonService,
 ) {
-  fun execute(hmppsId: String): Response<PersonProtectedCharacteristics?> {
+  fun execute(
+    hmppsId: String,
+    filters: ConsumerFilters?,
+  ): Response<PersonProtectedCharacteristics?> {
+    val hmppsIdType = getPersonService.identifyHmppsId(hmppsId)
+    if (hmppsIdType == IdentifierType.UNKNOWN) {
+      return Response(
+        data = null,
+        errors = listOf(UpstreamApiError(causedBy = UpstreamApi.NOMIS, type = UpstreamApiError.Type.BAD_REQUEST)),
+      )
+    }
+
     val probationOffender = probationOffenderSearchGateway.getOffender(hmppsId)
 
     if (probationOffender.data != null) {
-      val result = probationOffender.data.toPersonProtectedCharacteristics()
       val prisonOffender =
         probationOffender.data.otherIds.nomsNumber
           ?.let { prisonerOffenderSearchGateway.getPrisonOffender(it) }
+      if (filters != null) {
+        val consumerPrisonFilterCheck = consumerPrisonAccessService.checkConsumerHasPrisonAccess<PersonProtectedCharacteristics>(prisonOffender?.data?.prisonId, filters)
+        if (consumerPrisonFilterCheck.errors.isNotEmpty()) {
+          return consumerPrisonFilterCheck
+        }
+      }
+
+      val result = probationOffender.data.toPersonProtectedCharacteristics()
       if (prisonOffender?.data != null) {
         result.maritalStatus = prisonOffender.data.maritalStatus
 
@@ -31,7 +56,6 @@ class GetProtectedCharacteristicsService(
       }
       return Response(data = result, errors = probationOffender.errors)
     }
-
     return Response(data = null, errors = probationOffender.errors)
   }
 }

src/main/resources/globals.yml

@@ -18,6 +18,7 @@ globals:
         - "/v1/persons/.*/cell-location"
         - "/v1/persons/.*/risks/categories"
         - "/v1/persons/.*/sentences"
+        - "/v1/persons/.*/protected-characteristics"
         - "/v1/persons/.*/reported-adjudications"
         - "/v1/prison/prisoners"
         - "/v1/prison/prisoners/[^/]*$"

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

@@ -23,8 +23,6 @@ import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.UpstreamApi
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.UpstreamApiError
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.GetProtectedCharacteristicsService
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.internal.AuditService
-import java.net.URLEncoder
-import java.nio.charset.StandardCharsets
 
 @WebMvcTest(controllers = [ProtectedCharacteristicsController::class])
 @ActiveProfiles("test")
@@ -34,16 +32,16 @@ internal class ProtectedCharacteristicsControllerTest(
   @MockitoBean val auditService: AuditService,
 ) : DescribeSpec(
     {
-      val hmppsId = "9999/11111A"
-      val encodedHmppsId = URLEncoder.encode(hmppsId, StandardCharsets.UTF_8)
-      val path = "/v1/persons/$encodedHmppsId/protected-characteristics"
+      val hmppsId = "A1234AA"
+      val filters = null
+      val path = "/v1/persons/$hmppsId/protected-characteristics"
       val mockMvc = IntegrationAPIMockMvc(springMockMvc)
 
       describe("GET $path") {
         beforeTest {
           Mockito.reset(getProtectedCharacteristicsService)
           Mockito.reset(auditService)
-          whenever(getProtectedCharacteristicsService.execute(hmppsId)).thenReturn(
+          whenever(getProtectedCharacteristicsService.execute(hmppsId, filters)).thenReturn(
             Response(
               data =
                 PersonProtectedCharacteristics(35, "Female", "Unknown", "British", "British", "None", emptyList()),
@@ -60,7 +58,7 @@ internal class ProtectedCharacteristicsControllerTest(
         it("gets the offences for a person with the matching ID") {
           mockMvc.performAuthorised(path)
 
-          verify(getProtectedCharacteristicsService, VerificationModeFactory.times(1)).execute(hmppsId)
+          verify(getProtectedCharacteristicsService, VerificationModeFactory.times(1)).execute(hmppsId, filters)
         }
 
         it("returns the offences for a person with the matching ID") {
@@ -95,12 +93,10 @@ internal class ProtectedCharacteristicsControllerTest(
         }
 
         it("returns an empty list embedded in a JSON object when no offences are found") {
-          val hmppsIdForPersonWithNoOffences = "0000/11111A"
-          val encodedHmppsIdForPersonWithNoOffences =
-            URLEncoder.encode(hmppsIdForPersonWithNoOffences, StandardCharsets.UTF_8)
-          val offencesPath = "/v1/persons/$encodedHmppsIdForPersonWithNoOffences/protected-characteristics"
+          val hmppsIdForPersonWithNoOffences = "A1234AA"
+          val offencesPath = "/v1/persons/$hmppsIdForPersonWithNoOffences/protected-characteristics"
 
-          whenever(getProtectedCharacteristicsService.execute(hmppsIdForPersonWithNoOffences)).thenReturn(
+          whenever(getProtectedCharacteristicsService.execute(hmppsIdForPersonWithNoOffences, filters)).thenReturn(
             Response(
               data = null,
             ),
@@ -112,7 +108,7 @@ internal class ProtectedCharacteristicsControllerTest(
         }
 
         it("returns a 404 NOT FOUND status code when person isn't found in the upstream API") {
-          whenever(getProtectedCharacteristicsService.execute(hmppsId)).thenReturn(
+          whenever(getProtectedCharacteristicsService.execute(hmppsId, filters)).thenReturn(
             Response(
               data = null,
               errors =
@@ -131,7 +127,7 @@ internal class ProtectedCharacteristicsControllerTest(
         }
 
         it("fails with the appropriate error when an upstream service is down") {
-          whenever(getProtectedCharacteristicsService.execute(hmppsId)).doThrow(
+          whenever(getProtectedCharacteristicsService.execute(hmppsId, filters)).doThrow(
             WebClientResponseException(500, "MockError", null, null, null, null),
           )
 

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

@@ -8,8 +8,26 @@ import uk.gov.justice.digital.hmpps.hmppsintegrationapi.integration.IntegrationT
 class ProtectedCharacteristicsIntegrationTest : IntegrationTestBase() {
   @Test
   fun `returns protected characteristics for a person`() {
-    callApi("$basePath/$pnc/protected-characteristics")
+    callApi("$basePath/$nomsId/protected-characteristics")
       .andExpect(status().isOk)
       .andExpect(content().json(getExpectedResponse("person-protected-characteristics")))
   }
+
+  @Test
+  fun `returns a 400 if the hmppsId is invalid`() {
+    callApi("$basePath/$invalidNomsId/protected-characteristics")
+      .andExpect(status().isBadRequest)
+  }
+
+  @Test
+  fun `returns a 404 for if consumer has empty list of prisons`() {
+    callApiWithCN("$basePath/$nomsId/protected-characteristics", noPrisonsCn)
+      .andExpect(status().isNotFound)
+  }
+
+  @Test
+  fun `returns a 404 for prisoner in wrong prison`() {
+    callApiWithCN("$basePath/$nomsId/protected-characteristics", limitedPrisonsCn)
+      .andExpect(status().isNotFound)
+  }
 }