HMAI-306 - Add Prisons filter to /v1/persons/{encodedHmppsId}/reported-adjudications so can be used by kilco (#746)

* update controller and service to take filters

* Fix path adjudications controller

* update controller, service, and integration tests

* fix error in hmppsid integration test

---------

Co-authored-by: wcdkj <will.clark@digital.justice.gov.uk>

Author: BushraAbdullahi

src/main/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/controllers/v1/person/AdjudicationsController.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.RequestParam
 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.Adjudication
 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.GetAdjudicationsForPersonService
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.internal.AuditService
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.util.PaginatedResponse
@@ -28,26 +30,32 @@ class AdjudicationsController(
   @Autowired val auditService: AuditService,
   @Autowired val getAdjudicationsForPersonService: GetAdjudicationsForPersonService,
 ) {
-  @GetMapping("{encodedHmppsId}/reported-adjudications")
+  @GetMapping("{hmppsId}/reported-adjudications")
   @Operation(
     summary = "Returns adjudications associated with a person, sorted by dateTimeOfIncident (newest first).",
+    description = "<b>Applicable filters</b>: <ul><li>prisons</li></ul>",
     responses = [
       ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "OK"),
       ApiResponse(responseCode = "404", description = "Failed to find adjudications for the person with the provided hmppsId.", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
+      ApiResponse(responseCode = "400", description = "Malformed hmppsId.", content = [Content(schema = Schema(ref = "#/components/schemas/BadRequest"))]),
       ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
     ],
   )
   fun getPersonAdjudications(
-    @Parameter(description = "A URL-encoded HMPPS identifier", example = "2008%2F0545166T") @PathVariable encodedHmppsId: String,
+    @Parameter(description = "The HMPPS ID of the person") @PathVariable hmppsId: String,
     @Parameter(description = "The page number (starting from 1)", schema = Schema(minimum = "1")) @RequestParam(required = false, defaultValue = "1", name = "page") page: Int,
     @Parameter(description = "The maximum number of results for a page", schema = Schema(minimum = "1")) @RequestParam(required = false, defaultValue = "8", name = "perPage") perPage: Int,
+    @RequestAttribute filters: ConsumerFilters?,
   ): PaginatedResponse<Adjudication> {
-    val hmppsId = encodedHmppsId.decodeUrlCharacters()
-    val response = getAdjudicationsForPersonService.execute(hmppsId)
+    val response = getAdjudicationsForPersonService.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 or missing HMPPS ID: $hmppsId")
+    }
     auditService.createEvent("GET_PERSON_ADJUDICATIONS", mapOf("hmppsId" to hmppsId))
     return response.data.paginateWith(page, perPage)
   }

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

@@ -5,14 +5,18 @@ import org.springframework.stereotype.Service
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.gateways.AdjudicationsGateway
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.Adjudication
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.Response
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.roleconfig.ConsumerFilters
 
 @Service
 class GetAdjudicationsForPersonService(
   @Autowired val adjudicationsGateway: AdjudicationsGateway,
   @Autowired val getPersonService: GetPersonService,
 ) {
-  fun execute(hmppsId: String): Response<List<Adjudication>> {
-    val personResponse = getPersonService.execute(hmppsId = hmppsId)
+  fun execute(
+    hmppsId: String,
+    filters: ConsumerFilters? = null,
+  ): Response<List<Adjudication>> {
+    val personResponse = getPersonService.getPersonWithPrisonFilter(hmppsId = hmppsId, filters = filters)
     val nomisNumber = personResponse.data?.identifiers?.nomisNumber
 
     var adjudications: Response<List<Adjudication>> = Response(data = emptyList())

src/main/resources/globals.yml

@@ -17,6 +17,7 @@ globals:
         - "/v1/persons/.*/name"
         - "/v1/persons/.*/cell-location"
         - "/v1/persons/.*/sentences"
+        - "/v1/persons/.*/reported-adjudications"
         - "/v1/prison/prisoners"
         - "/v1/prison/prisoners/[^/]*$"
         - "/v1/prison/.*/prisoners/[^/]*/balances$"

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

@@ -17,33 +17,37 @@ import org.springframework.test.web.servlet.MockMvc
 import org.springframework.web.reactive.function.client.WebClientResponseException
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.helpers.IntegrationAPIMockMvc
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.Adjudication
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.Identifiers
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.IncidentDetailsDto
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.Person
 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.services.GetAdjudicationsForPersonService
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.GetPersonService
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.internal.AuditService
-import java.net.URLEncoder
-import java.nio.charset.StandardCharsets
 
 @WebMvcTest(controllers = [AdjudicationsController::class])
 @ActiveProfiles("test")
 internal class AdjudicationsControllerTest(
   @Autowired var springMockMvc: MockMvc,
   @MockitoBean val getAdjudicationsForPersonService: GetAdjudicationsForPersonService,
   @MockitoBean val auditService: AuditService,
+  @MockitoBean val getPersonService: GetPersonService,
 ) : DescribeSpec(
     {
-      val hmppsId = "9999/11111A"
-      val encodedHmppsId = URLEncoder.encode(hmppsId, StandardCharsets.UTF_8)
-      val path = "/v1/persons/$encodedHmppsId/reported-adjudications"
+      val hmppsId = "A1234AA"
+      val path = "/v1/persons/$hmppsId/reported-adjudications"
       val mockMvc = IntegrationAPIMockMvc(springMockMvc)
+      val filters = null
+      val person = Person(firstName = "Qui-gon", lastName = "Jin", identifiers = Identifiers(nomisNumber = hmppsId))
 
       describe("GET $path") {
         beforeTest {
           Mockito.reset(getAdjudicationsForPersonService)
           Mockito.reset(auditService)
-          whenever(getAdjudicationsForPersonService.execute(hmppsId)).thenReturn(
+          Mockito.reset(getPersonService)
+          whenever(getAdjudicationsForPersonService.execute(hmppsId, filters)).thenReturn(
             Response(
               data =
                 listOf(
@@ -56,10 +60,17 @@ internal class AdjudicationsControllerTest(
                 ),
             ),
           )
+
+          whenever(getPersonService.getPersonWithPrisonFilter(hmppsId = hmppsId, filters = filters)).thenReturn(
+            Response(
+              data = person,
+              errors = emptyList(),
+            ),
+          )
         }
 
         it("throws exception when no person found") {
-          whenever(getAdjudicationsForPersonService.execute(hmppsId = "notfound")).thenReturn(
+          whenever(getAdjudicationsForPersonService.execute(hmppsId = "notfound", filters)).thenReturn(
             Response(
               data = emptyList(),
               errors =
@@ -86,7 +97,7 @@ internal class AdjudicationsControllerTest(
         }
 
         it("returns paginated adjudication results") {
-          whenever(getAdjudicationsForPersonService.execute(hmppsId)).thenReturn(
+          whenever(getAdjudicationsForPersonService.execute(hmppsId, filters)).thenReturn(
             Response(
               data =
                 List(20) {
@@ -111,7 +122,7 @@ internal class AdjudicationsControllerTest(
         }
 
         it("fails with the appropriate error when an upstream service is down") {
-          whenever(getAdjudicationsForPersonService.execute(hmppsId)).doThrow(
+          whenever(getAdjudicationsForPersonService.execute(hmppsId, filters)).doThrow(
             WebClientResponseException(500, "MockError", null, null, null, null),
           )
 
@@ -124,6 +135,25 @@ internal class AdjudicationsControllerTest(
             ),
           )
         }
+
+        it("returns a 400 Bad request status code when hmpps id invalid in the upstream API") {
+          whenever(getAdjudicationsForPersonService.execute(hmppsId, filters)).thenReturn(
+            Response(
+              data = emptyList(),
+              errors =
+                listOf(
+                  UpstreamApiError(
+                    causedBy = UpstreamApi.ADJUDICATIONS,
+                    type = UpstreamApiError.Type.BAD_REQUEST,
+                  ),
+                ),
+            ),
+          )
+
+          val result = mockMvc.performAuthorised(path)
+
+          result.response.status.shouldBe(HttpStatus.BAD_REQUEST.value())
+        }
       }
     },
   )

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

@@ -122,7 +122,7 @@ class HmppsIdIntegrationTest : IntegrationTestBase() {
 
   @Test
   fun `gets the nomis, return a 404 when no prisons in filter`() {
-    callApiWithCN("/v1/hmpps/id/nomis-number/by-hmpps-id/$nomsId", limitedPrisonsCn)
+    callApiWithCN("/v1/hmpps/id/nomis-number/by-hmpps-id/$nomsId", noPrisonsCn)
       .andExpect(status().isNotFound)
   }
 

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

@@ -13,4 +13,22 @@ class AdjudicationsIntegrationTest : IntegrationTestBase() {
       .andExpect(status().isOk)
       .andExpect(content().json(getExpectedResponse("person-adjudications"), JsonCompareMode.STRICT))
   }
+
+  @Test
+  fun `adjudications returns a 400 if the hmppsId is invalid`() {
+    callApi("$basePath/$invalidNomsId/reported-adjudications")
+      .andExpect(status().isBadRequest)
+  }
+
+  @Test
+  fun `return a 404 for person in wrong prison`() {
+    callApiWithCN("$basePath/$nomsId/reported-adjudications", limitedPrisonsCn)
+      .andExpect(status().isNotFound)
+  }
+
+  @Test
+  fun `return a 404 when no prisons in filter`() {
+    callApiWithCN("$basePath/$nomsId/reported-adjudications", noPrisonsCn)
+      .andExpect(status().isNotFound)
+  }
 }

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

@@ -28,26 +28,27 @@ internal class GetAdjudicationsForPersonServiceTest(
   private val getAdjudicationsForPersonService: GetAdjudicationsForPersonService,
 ) : DescribeSpec(
     {
-      val hmppsId = "1234/56789B"
+      val hmppsId = "A1234AA"
       val prisonerNumber = "Z99999ZZ"
       val person = Person(firstName = "Qui-gon", lastName = "Jin", identifiers = Identifiers(nomisNumber = prisonerNumber))
       val adjudications = listOf(Adjudication(incidentDetails = IncidentDetailsDto(dateTimeOfIncident = "MockDate")))
+      val filters = null
 
       beforeEach {
         Mockito.reset(getPersonService)
         Mockito.reset(adjudicationsGateway)
 
-        whenever(getPersonService.execute(hmppsId = hmppsId)).thenReturn(Response(person))
+        whenever(getPersonService.getPersonWithPrisonFilter(hmppsId = hmppsId, filters = filters)).thenReturn(Response(person))
         whenever(adjudicationsGateway.getReportedAdjudicationsForPerson(id = prisonerNumber)).thenReturn(Response(adjudications))
       }
 
       it("performs a search according to hmpps Id") {
-        getAdjudicationsForPersonService.execute(hmppsId)
-        verify(getPersonService, VerificationModeFactory.times(1)).execute(hmppsId = hmppsId)
+        getAdjudicationsForPersonService.execute(hmppsId, filters)
+        verify(getPersonService, VerificationModeFactory.times(1)).getPersonWithPrisonFilter(hmppsId = hmppsId, filters = filters)
       }
 
       it("should return a list of errors if person not found") {
-        whenever(getPersonService.execute(hmppsId = "notfound")).thenReturn(
+        whenever(getPersonService.getPersonWithPrisonFilter(hmppsId = "notfound", filters = filters)).thenReturn(
           Response(
             data = null,
             errors =
@@ -59,7 +60,7 @@ internal class GetAdjudicationsForPersonServiceTest(
               ),
           ),
         )
-        val result = getAdjudicationsForPersonService.execute("notfound")
+        val result = getAdjudicationsForPersonService.execute(hmppsId = "notfound", filters)
         result.data.shouldBe(emptyList())
         result.errors
           .first()
@@ -80,7 +81,7 @@ internal class GetAdjudicationsForPersonServiceTest(
               ),
           ),
         )
-        val result = getAdjudicationsForPersonService.execute(hmppsId = hmppsId)
+        val result = getAdjudicationsForPersonService.execute(hmppsId, filters)
         result.data.shouldBe(emptyList())
         result.errors
           .first()
@@ -89,7 +90,7 @@ internal class GetAdjudicationsForPersonServiceTest(
       }
 
       it("should return adjudications from gateway") {
-        val result = getAdjudicationsForPersonService.execute(hmppsId = hmppsId)
+        val result = getAdjudicationsForPersonService.execute(hmppsId, filters)
         result.data
           .first()
           .incidentDetails