[ESWE-1080] Expression-of-interest API

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

@@ -0,0 +1,56 @@
+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.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 org.springframework.beans.factory.annotation.Autowired
+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.Response
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.PutExpressionInterestService
+
+@RestController
+@RequestMapping("/v1/persons")
+@Tag(name = "persons")
+class ExpressionInterestController(
+  @Autowired val putExpressionInterestService: PutExpressionInterestService,
+) {
+  @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 = "400",
+        description = "Bad Request",
+        content = [Content(schema = Schema(ref = "#/components/schemas/BadRequest"))],
+      ),
+      ApiResponse(
+        responseCode = "403",
+        description = "Access is forbidden",
+        content = [Content(schema = Schema(ref = "#/components/schemas/ForbiddenResponse"))],
+      ),
+      ApiResponse(
+        responseCode = "404",
+        content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))],
+      ),
+    ],
+  )
+  fun submitExpressionOfInterest(
+    @Parameter(description = "A HMPPS identifier", example = "A1234AA") @PathVariable hmppsId: String,
+    @Parameter(description = "A job identifier") @PathVariable jobid: String,
+  ): Response<Unit> {
+    putExpressionInterestService.sendExpressionOfInterest(hmppsId, jobid)
+
+    return Response(data = Unit, errors = emptyList())
+  }
+}

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/HmppsMessage.kt

@@ -0,0 +1,8 @@
+package uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps
+
+data class HmppsMessage(
+  val messageId: String,
+  val eventType: HmppsMessageEventType,
+  val description: String? = null,
+  val messageAttributes: Map<String, String> = emptyMap(),
+)

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

@@ -0,0 +1,15 @@
+package uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps
+
+import com.fasterxml.jackson.annotation.JsonValue
+
+enum class HmppsMessageEventType(
+  val type: String,
+  @JsonValue val eventTypeCode: String,
+  val description: String,
+) {
+  EXPRESSION_OF_INTEREST_CREATED(
+    type = "mjma-jobs-board.job.expression-of-interest.created",
+    eventTypeCode = "ExpressionOfInterestCreated",
+    description = "An expression of interest has been created",
+  ),
+}

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

@@ -0,0 +1,76 @@
+package uk.gov.justice.digital.hmpps.hmppsintegrationapi.services
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import jakarta.validation.ValidationException
+import org.slf4j.Logger
+import org.slf4j.LoggerFactory
+import org.springframework.stereotype.Component
+import software.amazon.awssdk.services.sqs.model.SendMessageRequest
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.exception.EntityNotFoundException
+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.HmppsMessage
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.HmppsMessageEventType
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.models.hmpps.UpstreamApiError
+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 getPersonService: GetPersonService,
+  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 }
+
+  companion object {
+    private val logger: Logger = LoggerFactory.getLogger(this::class.java)
+  }
+
+  fun sendExpressionOfInterest(
+    hmppsId: String,
+    jobid: String,
+  ) {
+    val personResponse = getPersonService.getNomisNumber(hmppsId = hmppsId)
+
+    if (personResponse.hasError(UpstreamApiError.Type.ENTITY_NOT_FOUND)) {
+      logger.debug("ExpressionOfInterest: Could not find nomis number for hmppsId: $hmppsId")
+      throw EntityNotFoundException("Could not find person with id: $hmppsId")
+    }
+
+    if (personResponse.hasError(UpstreamApiError.Type.BAD_REQUEST)) {
+      logger.debug("ExpressionOfInterest: Invalid hmppsId: $hmppsId")
+      throw ValidationException("Invalid HMPPS ID: $hmppsId")
+    }
+
+    val nomisNumber = personResponse.data?.nomisNumber ?: run { throw ValidationException("Invalid HMPPS ID: $hmppsId") }
+    val expressionOfInterest = ExpressionOfInterest(jobid, nomisNumber)
+
+    val eventType = HmppsMessageEventType.EXPRESSION_OF_INTEREST_CREATED
+    try {
+      val hmppsMessage =
+        objectMapper.writeValueAsString(
+          HmppsMessage(
+            messageId = UUID.randomUUID().toString(),
+            eventType = eventType,
+            messageAttributes = with(expressionOfInterest) { mapOf("jobId" to jobId, "prisonNumber" to prisonNumber) },
+          ),
+        )
+
+      eoiQueueSqsClient.sendMessage(
+        SendMessageRequest
+          .builder()
+          .queueUrl(eoiQueueUrl)
+          .messageBody(hmppsMessage)
+          .eventTypeMessageAttributes(eventType.type)
+          .build(),
+      )
+    } catch (e: Exception) {
+      throw MessageFailedException("Failed to send message to SQS", e)
+    }
+  }
+}

src/main/resources/application-dev.yml

@@ -148,6 +148,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/[^/]*$"
@@ -80,3 +81,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,66 @@
+package uk.gov.justice.digital.hmpps.hmppsintegrationapi.controllers.v1.person
+
+import io.kotest.core.spec.style.DescribeSpec
+import io.kotest.matchers.shouldBe
+import jakarta.validation.ValidationException
+import org.mockito.kotlin.any
+import org.mockito.kotlin.doNothing
+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.exception.EntityNotFoundException
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.helpers.IntegrationAPIMockMvc
+import uk.gov.justice.digital.hmpps.hmppsintegrationapi.services.PutExpressionInterestService
+
+@WebMvcTest(controllers = [ExpressionInterestController::class])
+@ActiveProfiles("test")
+class ExpressionInterestControllerTest(
+  @Autowired var springMockMvc: MockMvc,
+  @MockitoBean val expressionOfInterestService: PutExpressionInterestService,
+) : DescribeSpec({
+    val mockMvc = IntegrationAPIMockMvc(springMockMvc)
+    val basePath = "/v1/persons"
+    val validHmppsId = "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") {
+        validHmppsId.let { id ->
+          whenever(expressionOfInterestService.sendExpressionOfInterest(id, jobId)).thenThrow(EntityNotFoundException("Could not find person with id: $id"))
+        }
+
+        val result = mockMvc.performAuthorisedPut("$basePath/$validHmppsId/expression-of-interest/jobs/$jobId")
+        result.response.status.shouldBe(HttpStatus.NOT_FOUND.value())
+      }
+
+      it("should throw ValidationException if an invalid hmppsId is provided") {
+        invalidHmppsId.let { id ->
+          whenever(expressionOfInterestService.sendExpressionOfInterest(id, jobId)).thenThrow(ValidationException("Invalid HMPPS ID: $id"))
+        }
+
+        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") {
+        validHmppsId.let { id ->
+          doNothing().whenever(expressionOfInterestService).sendExpressionOfInterest(id, jobId)
+        }
+
+        val result = mockMvc.performAuthorisedPut("$basePath/$validHmppsId/expression-of-interest/jobs/$jobId")
+        result.response.status.shouldBe(HttpStatus.OK.value())
+      }
+
+      it("should return 500 Server Error if an exception occurs") {
+        whenever(expressionOfInterestService.sendExpressionOfInterest(any(), any())).thenThrow(RuntimeException("Unexpected error"))
+
+        val result = mockMvc.performAuthorisedPut("$basePath/$validHmppsId/expression-of-interest/jobs/$jobId")
+        result.response.status.shouldBe(HttpStatus.INTERNAL_SERVER_ERROR.value())
+      }
+    }
+  })

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

@@ -17,6 +17,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,