Added endpoint to return NOMS number.

Author: stevomcallister

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

@@ -1,6 +1,9 @@
 package uk.gov.justice.digital.hmpps.hmppsintegrationapi.controllers.v1
 
+import io.swagger.v3.oas.annotations.Operation
+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
@@ -10,6 +13,7 @@ import uk.gov.justice.digital.hmpps.hmppsintegrationapi.exception.EntityNotFound
 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.HmppsId
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.NomisNumber
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.UpstreamApiError
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.GetHmppsIdService
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.internal.AuditService
@@ -37,4 +41,34 @@ class HmppsIdController(
 
     return DataResponse(response.data)
   }
+
+  @GetMapping("{encodedNomisNumber}/nomis-number")
+  @Operation(
+    summary = "Return NOMS number for a given hmpps Id",
+    description = """Accepts a HMPPS Id (hmppsId) and looks up the corresponding NOMS number.
+    """,
+    responses = [
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true),
+      ApiResponse(responseCode = "404", description = "NOMS number could not be found."),
+      ApiResponse(responseCode = "400", description = "Invalid hmppsId."),
+    ],
+  )
+  fun getNomisNumberByHMPPSID(
+    @PathVariable encodedNomisNumber: String,
+  ): DataResponse<NomisNumber?> {
+    val hmppsId = encodedNomisNumber.decodeUrlCharacters()
+
+    val response = getHmppsIdService.getNomisNumber(hmppsId)
+
+    if (response.hasError(UpstreamApiError.Type.ENTITY_NOT_FOUND)) {
+      throw EntityNotFoundException("Could not find nomis number for HMPPS ID: $hmppsId")
+    }
+    if (response.hasError(UpstreamApiError.Type.BAD_REQUEST)) {
+      throw ValidationException("Invalid HMPPS ID: $hmppsId")
+    }
+
+    auditService.createEvent("GET_NOMIS_NUMBER_BY_HMPPS_ID", mapOf("hmppsId" to hmppsId))
+
+    return DataResponse(response.data)
+  }
 }

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

@@ -0,0 +1,5 @@
+package uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps
+
+data class NomisNumber(
+  val nomisNumber: String? = null,
+)

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

@@ -3,6 +3,7 @@ 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.models.hmpps.HmppsId
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.NomisNumber
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.Response
 
 @Service
@@ -17,4 +18,13 @@ class GetHmppsIdService(
       errors = personResponse.errors,
     )
   }
+
+  fun getNomisNumber(hmppsId: String): Response<NomisNumber?> {
+    val nomisResponse = getPersonService.getNomisNumber(hmppsId = hmppsId)
+
+    return Response(
+      data = NomisNumber(nomisNumber = nomisResponse.data?.nomisNumber),
+      errors = nomisResponse.errors,
+    )
+  }
 }

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

@@ -4,9 +4,12 @@ import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.stereotype.Service
 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.NomisNumber
 import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.OffenderSearchResponse
 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
 
 @Service
 class GetPersonService(
@@ -19,6 +22,68 @@ class GetPersonService(
     return Response(data = personFromProbationOffenderSearch.data, errors = personFromProbationOffenderSearch.errors)
   }
 
+  enum class IdentifierType {
+    NOMS,
+    CRN,
+    UNKNOWN,
+  }
+
+  fun identifyHmppsId(input: String): IdentifierType {
+    val nomsPattern = Regex("^[A-Z]\\d{4}[A-Z]{2}$")
+    val crnPattern = Regex("^[A-Z]{2}\\d{6}$")
+
+    return when {
+      nomsPattern.matches(input) -> IdentifierType.NOMS
+      crnPattern.matches(input) -> IdentifierType.CRN
+      else -> IdentifierType.UNKNOWN
+    }
+  }
+
+  /**
+   * Identify whether the hmppsId is a noms number or a crn
+   * When it is a noms number then return it.
+   * When it is a CRN look up the prisoner in probation offender search and then return it
+   */
+  fun getNomisNumber(hmppsId: String): Response<NomisNumber?> {
+    return when (identifyHmppsId(hmppsId)) {
+      IdentifierType.NOMS -> Response(data = NomisNumber(hmppsId))
+
+      IdentifierType.CRN -> {
+        val personFromProbationOffenderSearch = probationOffenderSearchGateway.getPerson(id = hmppsId)
+        val nomisNumber = personFromProbationOffenderSearch.data?.identifiers?.nomisNumber
+        val errors = personFromProbationOffenderSearch.errors.toMutableList()
+
+        if (nomisNumber == null) {
+          errors.add(
+            UpstreamApiError(
+              description = "NOMIS number not found",
+              type = UpstreamApiError.Type.ENTITY_NOT_FOUND,
+              causedBy = UpstreamApi.PROBATION_OFFENDER_SEARCH,
+            ),
+          )
+        }
+
+        Response(
+          data = nomisNumber?.let { NomisNumber(it) },
+          errors = errors,
+        )
+      }
+
+      IdentifierType.UNKNOWN ->
+        Response(
+          data = null,
+          errors =
+            listOf(
+              UpstreamApiError(
+                description = "Invalid HMPPS ID: $hmppsId",
+                type = UpstreamApiError.Type.BAD_REQUEST,
+                causedBy = UpstreamApi.NOMIS,
+              ),
+            ),
+        )
+    }
+  }
+
   fun getCombinedDataForPerson(hmppsId: String): Response<OffenderSearchResponse> {
     val probationResponse = probationOffenderSearchGateway.getPerson(id = hmppsId)