[ESWE-1080] Expression-of-interest API

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

@@ -0,0 +1,70 @@
+package uk.gov.justice.digital.hmpps.hmppsintegrationapi.controllers.v1.person
+
+import io.swagger.v3.oas.annotations.Operation
+import io.swagger.v3.oas.annotations.Parameter
+import io.swagger.v3.oas.annotations.responses.ApiResponse
+import io.swagger.v3.oas.annotations.tags.Tag
+import org.slf4j.Logger
+import org.slf4j.LoggerFactory
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.http.HttpStatus
+import org.springframework.http.ResponseEntity
+import org.springframework.web.bind.annotation.PathVariable
+import org.springframework.web.bind.annotation.PutMapping
+import org.springframework.web.bind.annotation.RequestMapping
+import org.springframework.web.bind.annotation.RestController
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.ExpressionOfInterest
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.NomisNumber
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.Response
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.UpstreamApiError
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.GetPersonService
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.PutExpressionInterestService
+
+@RestController
+@RequestMapping("/v1/persons")
+@Tag(name = "persons")
+class ExpressionInterestController(
+  @Autowired val getPersonService: GetPersonService,
+  @Autowired val putExpressionInterestService: PutExpressionInterestService,
+) {
+  val logger: Logger = LoggerFactory.getLogger(this::class.java)
+
+  @PutMapping("{hmppsId}/expression-of-interest/jobs/{jobid}")
+  @Operation(
+    summary = "Returns completed response",
+    responses = [
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully submitted an expression of interest"),
+      ApiResponse(responseCode = "403", useReturnTypeSchema = true, description = "Access is forbidden"),
+      ApiResponse(responseCode = "400", useReturnTypeSchema = true, description = "Bade Request"),
+      ApiResponse(responseCode = "404", useReturnTypeSchema = true, description = "Not found"),
+    ],
+  )
+  fun submitExpressionOfInterest(
+    @Parameter(description = "A URL-encoded HMPPS identifier", example = "2008%2F0545166T") @PathVariable hmppsId: String,
+    @Parameter(description = "A job identifier") @PathVariable jobid: String,
+  ): ResponseEntity<Void> {
+    try {
+      val hmppsIdCheck = getPersonService.getNomisNumber(hmppsId)
+
+      if (hmppsIdCheck.hasError(UpstreamApiError.Type.ENTITY_NOT_FOUND)) {
+        logger.info("ExpressionInterestController: Could not find nomis number for hmppsId: $hmppsId")
+        return ResponseEntity.notFound().build()
+      }
+
+      if (hmppsIdCheck.hasError(UpstreamApiError.Type.BAD_REQUEST)) {
+        logger.info("ExpressionInterestController: Invalid hmppsId: $hmppsId")
+        return ResponseEntity.badRequest().build()
+      }
+
+      val verifiedNomisNumber = getVerifiedNomisNumber(hmppsIdCheck) ?: return ResponseEntity.badRequest().build()
+      putExpressionInterestService.sendExpressionOfInterest(ExpressionOfInterest(jobid, verifiedNomisNumber))
+
+      return ResponseEntity.ok().build()
+    } catch (e: Exception) {
+      logger.error("ExpressionInterestController: Unable to send message: ${e.message}", e)
+      return ResponseEntity.status(HttpStatus.BAD_REQUEST).build<Void>()
+    }
+  }
+
+  fun getVerifiedNomisNumber(nomisNumberResponse: Response<NomisNumber?>) = nomisNumberResponse.data?.nomisNumber
+}

src/main/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/exception/MessageFailedException.kt

@@ -0,0 +1,6 @@
+package uk.gov.justice.digital.hmpps.hmppsintegrationapi.exception
+
+class MessageFailedException(
+  msg: String,
+  cause: Throwable? = null,
+) : RuntimeException(msg, cause)

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

@@ -0,0 +1,6 @@
+package uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps
+
+data class ExpressionOfInterest(
+  val jobId: String,
+  val prisonNumber: String,
+)

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

@@ -0,0 +1,12 @@
+package uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps
+
+data class ExpressionOfInterestMessage(
+  val messageId: String,
+  val jobId: String,
+  val prisonNumber: String,
+  val eventType: EventType = EventType.EXPRESSION_OF_INTEREST_MESSAGE_CREATED,
+) {
+  enum class EventType {
+    EXPRESSION_OF_INTEREST_MESSAGE_CREATED,
+  }
+}

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

@@ -0,0 +1,46 @@
+package uk.gov.justice.digital.hmpps.hmppsintegrationapi.services
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import org.springframework.stereotype.Component
+import software.amazon.awssdk.services.sqs.model.SendMessageRequest
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.exception.MessageFailedException
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.ExpressionOfInterest
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.ExpressionOfInterestMessage
+import uk.gov.justice.hmpps.sqs.HmppsQueue
+import uk.gov.justice.hmpps.sqs.HmppsQueueService
+import uk.gov.justice.hmpps.sqs.eventTypeMessageAttributes
+import java.util.UUID
+
+@Component
+class PutExpressionInterestService(
+  private val hmppsQueueService: HmppsQueueService,
+  private val objectMapper: ObjectMapper,
+) {
+  private val eoiQueue by lazy { hmppsQueueService.findByQueueId("jobsboardintegration") as HmppsQueue }
+  private val eoiQueueSqsClient by lazy { eoiQueue.sqsClient }
+  private val eoiQueueUrl by lazy { eoiQueue.queueUrl }
+
+  fun sendExpressionOfInterest(expressionOfInterest: ExpressionOfInterest) {
+    try {
+      val messageBody =
+        objectMapper.writeValueAsString(
+          ExpressionOfInterestMessage(
+            messageId = UUID.randomUUID().toString(),
+            jobId = expressionOfInterest.jobId,
+            prisonNumber = expressionOfInterest.prisonNumber,
+          ),
+        )
+
+      eoiQueueSqsClient.sendMessage(
+        SendMessageRequest
+          .builder()
+          .queueUrl(eoiQueueUrl)
+          .messageBody(messageBody)
+          .eventTypeMessageAttributes("mjma-jobs-board.job.expression-of-interest.created")
+          .build(),
+      )
+    } catch (e: Exception) {
+      throw MessageFailedException("Failed to send message to SQS", e)
+    }
+  }
+}

src/main/resources/application-dev.yml

@@ -149,6 +149,7 @@ authorisation:
         - "/v1/persons/.*/plp-induction-schedule"
         - "/v1/persons/.*/plp-induction-schedule/history"
         - "/v1/persons/.*/plp-review-schedule"
+        - "/v1/persons/[^/]+/expression-of-interest/jobs/[^/]+$"
         - "/v1/hmpps/id/by-nomis-number/[^/]*$"
         - "/v1/hmpps/id/nomis-number/by-hmpps-id/[^/]*$"
       filters:

src/main/resources/application-integration-test.yml

@@ -38,6 +38,8 @@ hmpps.sqs:
   queues:
     audit:
       queueName: "audit"
+    jobsboardintegration:
+      queueName: "jobsboard-integration"
 
 authorisation:
   consumers:
@@ -73,6 +75,7 @@ authorisation:
         - "/v1/persons/.*/plp-induction-schedule"
         - "/v1/persons/.*/plp-induction-schedule/history"
         - "/v1/persons/.*/plp-review-schedule"
+        - "/v1/persons/.*/expression-of-interest/jobs/[^/]*$"
         - "/v1/epf/person-details/.*/[^/]*$"
         - "/v1/hmpps/id/nomis-number/[^/]*$"
         - "/v1/hmpps/id/by-nomis-number/[^/]*$"

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

@@ -47,6 +47,7 @@ authorisation:
         - "/v1/persons/.*/plp-induction-schedule"
         - "/v1/persons/.*/plp-induction-schedule/history"
         - "/v1/persons/.*/plp-review-schedule"
+        - "/v1/persons/.*/expression-of-interest/jobs/[^/]*$"
         - "/v1/epf/person-details/.*/[^/]*$"
         - "/v1/hmpps/id/nomis-number/[^/]*$"
         - "/v1/hmpps/id/by-nomis-number/[^/]*$"
@@ -79,3 +80,5 @@ hmpps.sqs:
   queues:
     audit:
       queueName: "audit"
+    jobsboardintegration:
+      queueName: "jobsboard-integration"

src/main/resources/application-local.yml

@@ -19,6 +19,8 @@ hmpps.sqs:
   queues:
     audit:
       queueName: "audit"
+    jobsboardintegration:
+      queueName: "jobsboard-integration"
 
 authorisation:
   consumers:
@@ -53,6 +55,7 @@ authorisation:
         - "/v1/persons/.*/cell-location"
         - "/v1/persons/.*/plp-induction-schedule"
         - "/v1/persons/.*/plp-review-schedule"
+        - "/v1/persons/[^/]+/expression-of-interest/jobs/[^/]+$"
         - "/v1/epf/person-details/.*/[^/]*$"
         - "/v1/hmpps/id/nomis-number/[^/]*$"
         - "/v1/hmpps/id/by-nomis-number/[^/]*$"

src/main/resources/application-test.yml

@@ -74,6 +74,7 @@ authorisation:
         - "/v1/persons/.*/plp-induction-schedule"
         - "/v1/persons/.*/plp-induction-schedule/history"
         - "/v1/persons/.*/plp-review-schedule"
+        - "/v1/persons/.*/expression-of-interest/jobs/[^/]*$"
         - "/v1/hmpps/id/nomis-number/[^/]*$"
         - "/v1/hmpps/id/.*/nomis-number"
         - "/v1/hmpps/id/by-nomis-number/[^/]*$"

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

@@ -0,0 +1,85 @@
+package uk.gov.justice.digital.hmpps.hmppsintegrationapi.controllers.v1.person
+
+import io.kotest.core.spec.style.DescribeSpec
+import io.kotest.matchers.shouldBe
+import org.mockito.kotlin.verify
+import org.mockito.kotlin.whenever
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest
+import org.springframework.http.HttpStatus
+import org.springframework.test.context.ActiveProfiles
+import org.springframework.test.context.bean.override.mockito.MockitoBean
+import org.springframework.test.web.servlet.MockMvc
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.helpers.IntegrationAPIMockMvc
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.ExpressionOfInterest
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.NomisNumber
+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.GetPersonService
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.PutExpressionInterestService
+
+@WebMvcTest(controllers = [ExpressionInterestController::class])
+@ActiveProfiles("test")
+class ExpressionInterestControllerTest(
+  @Autowired var springMockMvc: MockMvc,
+  @MockitoBean val getPersonService: GetPersonService,
+  @MockitoBean val expressionOfInterestService: PutExpressionInterestService,
+) : DescribeSpec({
+    val mockMvc = IntegrationAPIMockMvc(springMockMvc)
+    val basePath = "/v1/persons"
+    val validHmppsId = "AABCD1ABC"
+    val nomisId = "AABCD1ABC"
+    val invalidHmppsId = "INVALID_ID"
+    val jobId = "5678"
+
+    describe("PUT $basePath/{hmppsId}/expression-of-interest/jobs/{jobId}") {
+      it("should return 404 Not Found if ENTITY_NOT_FOUND error occurs") {
+        val notFoundResponse =
+          Response<NomisNumber?>(
+            data = null,
+            errors =
+              listOf(
+                UpstreamApiError(
+                  type = UpstreamApiError.Type.ENTITY_NOT_FOUND,
+                  description = "Entity not found",
+                  causedBy = UpstreamApi.PRISONER_OFFENDER_SEARCH,
+                ),
+              ),
+          )
+        whenever(getPersonService.getNomisNumber(validHmppsId)).thenReturn(notFoundResponse)
+
+        val result = mockMvc.performAuthorisedPut("$basePath/$validHmppsId/expression-of-interest/jobs/$jobId")
+
+        result.response.status.shouldBe(HttpStatus.NOT_FOUND.value())
+      }
+
+      it("should return 400 if an invalid hmppsId is provided") {
+        val result = mockMvc.performAuthorisedPut("$basePath/$invalidHmppsId/expression-of-interest/jobs/$jobId")
+
+        result.response.status.shouldBe(HttpStatus.BAD_REQUEST.value())
+      }
+
+      it("should return 200 OK on successful expression of interest submission") {
+        val validNomisResponse =
+          Response<NomisNumber?>(
+            data = NomisNumber(nomisId),
+            errors = emptyList(),
+          )
+        whenever(getPersonService.getNomisNumber(validHmppsId)).thenReturn(validNomisResponse)
+
+        val result = mockMvc.performAuthorisedPut("$basePath/$validHmppsId/expression-of-interest/jobs/$jobId")
+
+        verify(expressionOfInterestService).sendExpressionOfInterest(ExpressionOfInterest(jobId, nomisId))
+        result.response.status.shouldBe(HttpStatus.OK.value())
+      }
+
+      it("should return 400 Bad Request if an exception occurs") {
+        whenever(getPersonService.getNomisNumber(validHmppsId)).thenThrow(RuntimeException("Unexpected error"))
+
+        val result = mockMvc.performAuthorisedPut("$basePath/$validHmppsId/expression-of-interest/jobs/$jobId")
+
+        result.response.status.shouldBe(HttpStatus.BAD_REQUEST.value())
+      }
+    }
+  })

src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/helpers/IntegrationAPIMockMvc.kt

@@ -15,6 +15,11 @@ class IntegrationAPIMockMvc(
     return mockMvc.perform(MockMvcRequestBuilders.get(path).header("subject-distinguished-name", subjectDistinguishedName)).andReturn()
   }
 
+  fun performAuthorisedPut(path: String): MvcResult {
+    val subjectDistinguishedName = "C=GB,ST=London,L=London,O=Home Office,CN=automated-test-client"
+    return mockMvc.perform(MockMvcRequestBuilders.put(path).header("subject-distinguished-name", subjectDistinguishedName)).andReturn()
+  }
+
   fun performAuthorisedWithCN(
     path: String,
     cn: String,