HMAI-96 Add Prison Filter to Prison Controller (#568)

* Added prison filter to prisoner query endpoint with unit tests

* Updated how we get our session attributes for filtering in prisoner-details query, additional tests in relevant layers

* Removing unused DI service from get prisoners service

* Fixing unit tests in balances controller

* Revised prisonId config check to reject queries from consumers that have an empty prison property

* Revised prison filter logic and rectified tests

Author: wcdkj

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

@@ -94,6 +94,7 @@ class PrisonController(
     @Parameter(description = "Whether to return results that match the search criteria within the aliases of a person.") @RequestParam(required = false, defaultValue = "false", name = "search_within_aliases") searchWithinAliases: Boolean,
     @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 = "10", name = "perPage") perPage: Int,
+    @RequestAttribute filters: ConsumerFilters?,
   ): PaginatedResponse<Person?> {
     if (firstName == null && lastName == null && dateOfBirth == null) {
       throw ValidationException("No query parameters specified.")
@@ -103,7 +104,7 @@ class PrisonController(
       throw ValidationException("Invalid date format. Please use yyyy-MM-dd.")
     }
 
-    val response = getPrisonersService.execute(firstName, lastName, dateOfBirth, searchWithinAliases)
+    val response = getPrisonersService.execute(firstName, lastName, dateOfBirth, searchWithinAliases, filters)
 
     auditService.createEvent(
       "SEARCH_PERSON",

src/main/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/gateways/PrisonerOffenderSearchGateway.kt

@@ -43,7 +43,59 @@ class PrisonerOffenderSearchGateway(
 
     return when (result) {
       is WebClientWrapperResponse.Success -> {
-        Response(data = result.data.content.map { it.toPerson() }.sortedByDescending { it.dateOfBirth })
+        Response(
+          data =
+            result.data.content
+              .map { it.toPerson() }
+              .sortedByDescending { it.dateOfBirth },
+        )
+      }
+
+      is WebClientWrapperResponse.Error -> {
+        Response(
+          data = emptyList(),
+          errors = result.errors,
+        )
+      }
+    }
+  }
+
+  fun getPrisonerDetails(
+    firstName: String?,
+    lastName: String?,
+    dateOfBirth: String?,
+    searchWithinAliases: Boolean = false,
+    prisonIds: List<String?>?,
+  ): Response<List<Person>> {
+    val maxNumberOfResults = 9999
+
+    val requestBody =
+      mapOf(
+        "firstName" to firstName,
+        "lastName" to lastName,
+        "dateOfBirth" to dateOfBirth,
+        "includeAliases" to searchWithinAliases,
+        "prisonIds" to prisonIds,
+        "pagination" to mapOf("page" to 0, "size" to maxNumberOfResults),
+      ).filterValues { it != null }
+
+    val result =
+      webClient.request<POSGlobalSearch>(
+        HttpMethod.POST,
+        "/prisoner-detail",
+        authenticationHeader(),
+        UpstreamApi.PRISONER_OFFENDER_SEARCH,
+        requestBody,
+      )
+
+    return when (result) {
+      is WebClientWrapperResponse.Success -> {
+        Response(
+          data =
+            result.data.content
+              .map { it.toPerson() }
+              .sortedByDescending { it.dateOfBirth },
+        )
       }
 
       is WebClientWrapperResponse.Error -> {

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

@@ -5,6 +5,9 @@ import org.springframework.stereotype.Service
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.gateways.PrisonerOffenderSearchGateway
 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.models.roleconfig.ConsumerFilters
 
 @Service
 class GetPrisonersService(
@@ -15,19 +18,31 @@ class GetPrisonersService(
     lastName: String?,
     dateOfBirth: String?,
     searchWithinAliases: Boolean = false,
+    filters: ConsumerFilters?,
   ): Response<List<Person>> {
+    val prisonIds = filters?.prisons
     val responseFromPrisonerOffenderSearch =
-      prisonerOffenderSearchGateway.getPersons(
-        firstName,
-        lastName,
-        dateOfBirth,
-        searchWithinAliases,
-      )
+      if (prisonIds == null) {
+        // Hit global-search endpoint
+        prisonerOffenderSearchGateway.getPersons(
+          firstName,
+          lastName,
+          dateOfBirth,
+          searchWithinAliases,
+        )
+      } else {
+        // Hit prisoner-details endpoint
+        prisonerOffenderSearchGateway.getPrisonerDetails(firstName, lastName, dateOfBirth, searchWithinAliases, prisonIds)
+      }
 
     if (responseFromPrisonerOffenderSearch.errors.isNotEmpty()) {
       return Response(emptyList(), responseFromPrisonerOffenderSearch.errors)
     }
 
+    if (responseFromPrisonerOffenderSearch.data.isEmpty()) {
+      return Response(emptyList(), listOf(UpstreamApiError(UpstreamApi.PRISONER_OFFENDER_SEARCH, UpstreamApiError.Type.ENTITY_NOT_FOUND, "Not found")))
+    }
+
     return Response(data = responseFromPrisonerOffenderSearch.data)
   }
 }

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

@@ -53,11 +53,11 @@ class BalancesControllerTest(
     it("gets the balances for a person with the matching ID") {
       mockMvc.performAuthorised(basePath)
 
-      verify(getBalancesForPersonService, VerificationModeFactory.times(1)).execute(prisonId, hmppsId)
+      verify(getBalancesForPersonService, VerificationModeFactory.times(1)).execute(prisonId, hmppsId, null)
     }
 
     it("returns the correct balances data") {
-      whenever(getBalancesForPersonService.execute(prisonId, hmppsId)).thenReturn(
+      whenever(getBalancesForPersonService.execute(prisonId, hmppsId, null)).thenReturn(
         Response(
           data = balance,
         ),
@@ -91,7 +91,7 @@ class BalancesControllerTest(
     }
 
     it("returns a 404 NOT FOUND status code when person isn't found in probation offender search") {
-      whenever(getBalancesForPersonService.execute(prisonId, hmppsId)).thenReturn(
+      whenever(getBalancesForPersonService.execute(prisonId, hmppsId, null)).thenReturn(
         Response(
           data = null,
           errors =
@@ -110,7 +110,7 @@ class BalancesControllerTest(
     }
 
     it("returns a 404 NOT FOUND status code when person isn't found in Nomis") {
-      whenever(getBalancesForPersonService.execute(prisonId, hmppsId)).thenReturn(
+      whenever(getBalancesForPersonService.execute(prisonId, hmppsId, null)).thenReturn(
         Response(
           data = null,
           errors =
@@ -129,7 +129,7 @@ class BalancesControllerTest(
     }
 
     it("returns a 400 BAD REQUEST status code when account isn't found in the upstream API") {
-      whenever(getBalancesForPersonService.execute(prisonId, hmppsId)).thenReturn(
+      whenever(getBalancesForPersonService.execute(prisonId, hmppsId, null)).thenReturn(
         Response(
           data = null,
           errors =
@@ -148,7 +148,7 @@ class BalancesControllerTest(
     }
 
     it("returns a 500 INTERNAL SERVER ERROR status code when balance isn't found in the upstream API") {
-      whenever(getBalancesForPersonService.execute(prisonId, hmppsId)).thenThrow(
+      whenever(getBalancesForPersonService.execute(prisonId, hmppsId, null)).thenThrow(
         IllegalStateException("Error occurred while trying to get accounts for person with id: $hmppsId"),
       )
 

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

@@ -325,7 +325,6 @@ internal class PersonControllerTest(
                    "gender":null,
                    "ethnicity":null,
                    "aliases":[
-
                    ],
                    "identifiers":{
                       "nomisNumber":null,

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

@@ -2,6 +2,7 @@ package uk.gov.justice.digital.hmpps.hmppsintegrationapi.controllers.v1.prison
 
 import io.kotest.core.spec.style.DescribeSpec
 import io.kotest.matchers.shouldBe
+import jakarta.servlet.http.HttpServletRequest
 import org.mockito.Mockito
 import org.mockito.kotlin.anyOrNull
 import org.mockito.kotlin.eq
@@ -22,6 +23,7 @@ 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.hmpps.UpstreamApiError.Type.BAD_REQUEST
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.UpstreamApiError.Type.ENTITY_NOT_FOUND
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.roleconfig.ConsumerFilters
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.GetPersonService
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.GetPrisonersService
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.internal.AuditService
@@ -34,6 +36,7 @@ internal class PrisonControllerTest(
   @MockitoBean val getPersonService: GetPersonService,
   @MockitoBean val auditService: AuditService,
   @MockitoBean val getPrisonersService: GetPrisonersService,
+  @Autowired val request: HttpServletRequest,
 ) : DescribeSpec(
     {
       val hmppsId = "200313116M"
@@ -42,6 +45,7 @@ internal class PrisonControllerTest(
       val firstName = "Barry"
       val lastName = "Allen"
       val dateOfBirth = "2023-03-01"
+      val emptyConsumerFilter = null
 
       describe("GET $basePath") {
       }
@@ -199,15 +203,15 @@ internal class PrisonControllerTest(
 
       it("returns 500 when prison/prisoners throws an unexpected error") {
 
-        whenever(getPrisonersService.execute("Barry", "Allen", "2023-03-01")).thenThrow(RuntimeException("Service error"))
+        whenever(getPrisonersService.execute("Barry", "Allen", "2023-03-01", false, emptyConsumerFilter)).thenThrow(RuntimeException("Service error"))
 
         val result = mockMvc.performAuthorised("$basePath/prisoners?first_name=$firstName&last_name=$lastName&date_of_birth=$dateOfBirth")
         result.response.status.shouldBe(500)
       }
 
-      it("returns 404 when prisoner query gets no result") {
+      it("returns 500 when prisoner query gets no result") {
 
-        whenever(getPrisonersService.execute("Barry", "Allen", "2023-03-01")).thenReturn(
+        whenever(getPrisonersService.execute("Barry", "Allen", "2023-03-01", false, ConsumerFilters(emptyList()))).thenReturn(
           Response(
             data = emptyList(),
             errors =
@@ -222,11 +226,11 @@ internal class PrisonControllerTest(
         )
 
         val result = mockMvc.performAuthorised("$basePath/prisoners?first_name=$firstName&last_name=$lastName&date_of_birth=$dateOfBirth")
-        result.response.status.shouldBe(404)
+        result.response.status.shouldBe(500)
       }
 
       it("returns a 200 OK status code") {
-        whenever(getPrisonersService.execute(firstName, lastName, dateOfBirth)).thenReturn(
+        whenever(getPrisonersService.execute(firstName, lastName, dateOfBirth, false, emptyConsumerFilter)).thenReturn(
           Response(
             data =
               listOf(
@@ -245,7 +249,7 @@ internal class PrisonControllerTest(
               ),
           ),
         )
-        val result = mockMvc.performAuthorised("$basePath/prisoners?first_name=$firstName&last_name=$lastName&date_of_birth=$dateOfBirth")
+        val result = mockMvc.performAuthorised("$basePath/prisoners?first_name=$firstName&last_name=$lastName&date_of_birth=$dateOfBirth&search_within_aliases=false")
 
         result.response.status.shouldBe(HttpStatus.OK.value())
       }

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

@@ -4,6 +4,7 @@ package uk.gov.justice.digital.hmpps.hmppsintegrationapi.services
 
 import io.kotest.core.spec.style.DescribeSpec
 import io.kotest.matchers.shouldBe
+import jakarta.servlet.http.HttpServletRequest
 import org.mockito.Mockito
 import org.mockito.kotlin.whenever
 import org.springframework.boot.test.context.ConfigDataApplicationContextInitializer
@@ -14,13 +15,15 @@ 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.models.roleconfig.ConsumerFilters
 
 @ContextConfiguration(
   initializers = [ConfigDataApplicationContextInitializer::class],
   classes = [GetPrisonersService::class],
 )
 internal class GetPrisonersServiceTest(
   @MockitoBean val prisonerOffenderSearchGateway: PrisonerOffenderSearchGateway,
+  @MockitoBean val request: HttpServletRequest,
   private val getPrisonersService: GetPrisonersService,
 ) : DescribeSpec(
     {
@@ -32,7 +35,7 @@ internal class GetPrisonersServiceTest(
         Mockito.reset(prisonerOffenderSearchGateway)
       }
 
-      it("returns an error when the person queried is not found") {
+      it("returns an error when the person queried is not found and no prisonId filter is applied") {
         whenever(prisonerOffenderSearchGateway.getPersons("Qui-gon", "Jin", "1966-10-25")).thenReturn(
           Response(
             errors =
@@ -43,26 +46,83 @@ internal class GetPrisonersServiceTest(
           ),
         )
 
-        val result = getPrisonersService.execute("Qui-gon", "Jin", "1966-10-25")
+        val result = getPrisonersService.execute("Qui-gon", "Jin", "1966-10-25", false, null)
         result?.errors.shouldBe(
           listOf(
             UpstreamApiError(UpstreamApi.PRISONER_OFFENDER_SEARCH, UpstreamApiError.Type.ENTITY_NOT_FOUND, "MockError"),
           ),
         )
       }
 
-      it("returns the person's data when queried") {
+      it("returns the person's data when queried and no prisonId filter is applied") {
         val people = listOf(Person(firstName = "Qui-gon", lastName = "Jin"), Person(firstName = "John", lastName = "Jin"))
         whenever(prisonerOffenderSearchGateway.getPersons("Qui-gon", "Jin", "1966-10-25")).thenReturn(
           Response(
             data = people,
           ),
         )
 
-        val result = getPrisonersService.execute("Qui-gon", "Jin", "1966-10-25")
+        val result = getPrisonersService.execute("Qui-gon", "Jin", "1966-10-25", false, null)
         result?.data?.shouldBe(
           people,
         )
       }
+
+      it("returns an error when theres a filter prisons property but no values") {
+        val people = listOf(Person(firstName = "Qui-gon", lastName = "Jin"), Person(firstName = "John", lastName = "Jin"))
+        whenever(prisonerOffenderSearchGateway.getPersons("Qui-gon", "Jin", "1966-10-25")).thenReturn(
+          Response(
+            errors =
+              listOf(
+                UpstreamApiError(UpstreamApi.PRISONER_OFFENDER_SEARCH, UpstreamApiError.Type.ENTITY_NOT_FOUND, "MockError"),
+              ),
+            data = emptyList(),
+          ),
+        )
+
+        val result = getPrisonersService.execute("Qui-gon", "Jin", "1966-10-25", false, null)
+        result?.errors.shouldBe(
+          listOf(
+            UpstreamApiError(UpstreamApi.PRISONER_OFFENDER_SEARCH, UpstreamApiError.Type.ENTITY_NOT_FOUND, "MockError"),
+          ),
+        )
+      }
+
+      it("returns an error when the person queried for is not in a prisonId matching their config") {
+        val prisonIds = ConsumerFilters(prisons = listOf("FAKE_PRISON"))
+        whenever(request.getAttribute("filters")).thenReturn(prisonIds)
+        whenever(prisonerOffenderSearchGateway.getPrisonerDetails("Qui-gon", "Jin", "1966-10-25", false, prisonIds.prisons)).thenReturn(
+          Response(
+            errors =
+              listOf(
+                UpstreamApiError(UpstreamApi.PRISONER_OFFENDER_SEARCH, UpstreamApiError.Type.ENTITY_NOT_FOUND, "MockError"),
+              ),
+            data = emptyList(),
+          ),
+        )
+
+        val result = getPrisonersService.execute("Qui-gon", "Jin", "1966-10-25", false, prisonIds)
+        result?.errors.shouldBe(
+          listOf(
+            UpstreamApiError(UpstreamApi.PRISONER_OFFENDER_SEARCH, UpstreamApiError.Type.ENTITY_NOT_FOUND, "MockError"),
+          ),
+        )
+      }
+
+      it("returns the persons data when the person queried for is in a prisonId matching their config") {
+        val people = listOf(Person(firstName = "Qui-gon", lastName = "Jin"), Person(firstName = "John", lastName = "Jin"))
+        val prisonIds = ConsumerFilters(prisons = listOf("VALID_PRISON"))
+        whenever(request.getAttribute("filters")).thenReturn(prisonIds)
+        whenever(prisonerOffenderSearchGateway.getPrisonerDetails("Qui-gon", "Jin", "1966-10-25", false, prisonIds.prisons)).thenReturn(
+          Response(
+            data = people,
+          ),
+        )
+
+        val result = getPrisonersService.execute("Qui-gon", "Jin", "1966-10-25", false, prisonIds)
+        result?.data.shouldBe(
+          people,
+        )
+      }
     },
   )