PI-1574: Document 'Manage POM Cases and Delius' service

projects/manage-pom-cases-and-delius/README.md

@@ -1,3 +1,45 @@
-# manage-pom-cases-and-delius
+# Manage POM Cases and Delius
 
-// TODO Describe the service
+## Business Need
+
+Service that manages data exchange between Delius and the 'Manage POM Cases' service, which is part of the Offender Management in Custody (OMiC) model. Allocation of a Prison Offender Manager (POM) within 'Manage POM Cases' uses information from the probation case stored in Delius. All Prison Offender Manager allocations and handover dates must be reflected in the Delius supervision record.
+
+## Context Map
+
+![Context Map](./tech-docs/source/img/manage-pom-cases-and-delius-context-map.svg)
+
+## Interfaces
+
+The service manages three integration points between 'Manage POM Cases' and Delius.
+
+1. Providing an API endpoint for probation case information held in Delius
+2. Consuming a domain event raised by 'Manage POM Cases' when handover dates are changed
+3. Consuming a domain event raised by 'Manage POM Cases' when POM allocation is updated
+
+The domain events are raised by the [Manage POM Cases](https://github.com/ministryofjustice/offender-management-allocation-manager) service when significant changes are made to case allocation in custody.
+
+### Domain Event Triggers
+
+The service responds to an HMPPS Domain Event message via an
+[SQS Queue](https://github.com/ministryofjustice/cloud-platform-environments/blob/main/namespaces/live.cloud-platform.service.justice.gov.uk/hmpps-probation-integration-services-prod/resources/manage-pom-cases-and-delius-queue.tf).
+
+Example [messages](./src/dev/resources/messages/) are in the development source tree
+
+| Business Event                                           | Message Class      | Message Event Type / Filter          |
+|----------------------------------------------------------|--------------------|--------------------------------------|
+| POM to COM handover of responsibility dates have changed | HMPPS Domain Event | offender-management.handover.changed |
+| The POM allocated to the case has changed                | HMPPS Domain Event | offender-management.pom.allocated    |
+
+## Workflows
+
+### Prison Offender Manager Handover Dates
+
+![Handover Dates Workflow](./tech-docs/source/img/manage-pom-cases-workflow-handover-dates.svg)
+
+### Responsibility Change
+
+![Responsibiliy Change Workflow](./tech-docs/source/img/manage-pom-cases-workflow-responsibility.svg)
+
+## Delius Case Allocation
+
+Delius records details of POM allocations, COM allocations and handover dates for a probation case. It also has the concept of a 'Responsible Officer' which is the member of staff currently responsible for the case. A case may have a number of POM and COM records in Delius, indicating the allocation history, however there can only be one Responsible Officer at any one time. This will be one of the currently active POM or COM. The integration service will update POM allocations and handover dates in Delius. It will not change the Responsible Officer in Delius unless the current responsible officer is the active POM and this is changed by the MPC allocation.

projects/manage-pom-cases-and-delius/src/main/kotlin/uk/gov/justice/digital/hmpps/api/resource/ProbationRecordResource.kt

@@ -1,15 +1,43 @@
 package uk.gov.justice.digital.hmpps.api.resource
 
+import io.swagger.v3.oas.annotations.Operation
+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 org.springframework.security.access.prepost.PreAuthorize
 import org.springframework.web.bind.annotation.GetMapping
 import org.springframework.web.bind.annotation.PathVariable
 import org.springframework.web.bind.annotation.RestController
+import uk.gov.justice.digital.hmpps.advice.ErrorResponse
 import uk.gov.justice.digital.hmpps.services.Identifier
 import uk.gov.justice.digital.hmpps.services.ProbationRecordService
 
 @RestController
 class ProbationRecordResource(val prService: ProbationRecordService) {
     @PreAuthorize("hasRole('ROLE_MANAGE_POM_CASES')")
     @GetMapping(value = ["/case-records/{identifier}"])
-    fun handle(@PathVariable("identifier") identifier: String) = prService.findByIdentifier(Identifier(identifier))
+    @Operation(
+        summary = "Background information on the probation case",
+        description = """<p>Background details of the probation case for the purposes
+            of allocating a new Prison Offender Manager. The service will return
+            case information for either the CRN or NOMS number supplied in the
+            request.</p>
+            <p>Requires `ROLE_MANAGE_POM_CASES`.</p>
+        """,
+        responses = [
+            ApiResponse(responseCode = "200", description = "OK"),
+            ApiResponse(
+                responseCode = "404",
+                description = """No probation case found with the given identifier.
+                    For a prison identifier this could mean the Prison and Probation cases
+                    have not been linked yet.""",
+                content = [
+                    Content(schema = Schema(implementation = ErrorResponse::class))
+                ]
+            )
+        ]
+    )
+    fun handle(
+        @PathVariable("identifier") identifier: String
+    ) = prService.findByIdentifier(Identifier(identifier))
 }

projects/manage-pom-cases-and-delius/tech-docs/diag/manage-pom-cases-and-delius-context-map.d2

@@ -0,0 +1,49 @@
+
+style {
+  fill: "#ffffff"
+}
+
+context-manage-offences: Manage POM Cases Context {
+  link: https://github.com/ministryofjustice/offender-management-allocation-manager
+
+  entities: Entities {
+    grid-columns: 3
+    prison: Prison
+    pom: Prison Offender Manager (POM)
+    com: Community Offender Manager (COM)
+    officer: Officer
+    responsiblity: Responsibility
+    handover: Handover
+  }
+
+  interface: Manage POM Cases API {
+    type: Open Host Service
+  }
+}
+
+context-delius: Delius Context {
+  link: https://github.com/ministryofjustice/delius
+  style.stroke-width: 8
+
+  entities: Entities {
+    grid-columns: 3
+    institution: Institution
+    pom: Prison Offender Manager (POM)
+    com: Community Offender Manager (COM)
+    responsible-officer: Responsible Officer (RO)
+    staff: Probation Staff Member
+    local-delivery-unit: Local Delivery Unit
+    mappa: MAPPA Registration
+    victim-liason-officer: Victim Liason Officer
+  }
+  interface: Manage POM Cases and Delius {
+    link: https://ministryofjustice.github.io/hmpps-probation-integration-services/tech-docs/projects/manage-pom-cases-and-delius/
+    type: Anti-Corruption Layer
+  }
+}
+
+context-manage-offences.interface--context-delius.interface: Upstream\n\n\nDownstream
+
+*.style.border-radius: 10
+*.*.style.border-radius: 10
+*.*.style.stroke-width: 2

projects/manage-pom-cases-and-delius/tech-docs/diag/manage-pom-cases-workflow-handover-dates.d2

@@ -0,0 +1,29 @@
+# Manage POM Cases Workflow: Update Delius POM to COM Handover Dates
+
+direction: right
+
+style {
+  fill: "#ffffff"
+}
+
+# What triggers the workflow?
+mpc: Manage POM Cases {
+     style.font-size: 15
+     mpc_responsibility: POM to COM handover\ndates updated {
+         shape: oval
+     }
+}
+
+# What happens in Delius?
+delius: Delius {
+    style {
+        font-size: 20
+    }
+    d_key_dates: Update key dates
+}
+
+mpc -> delius
+
+*.style.border-radius: 10
+*.*.style.border-radius: 10
+*.*.style.stroke-width: 2

projects/manage-pom-cases-and-delius/tech-docs/diag/manage-pom-cases-workflow-responsibility.d2

@@ -0,0 +1,33 @@
+# Manage POM Cases Workflow: Update Delius POM Responsibility
+
+direction: right
+
+style {
+  fill: "#ffffff"
+}
+
+# What triggers the workflow?
+mpc: Manage POM Cases {
+     style.font-size: 15
+     mpc_responsibility: POM responsibility\nupdated {
+         shape: oval
+     }
+}
+
+# What happens in Delius?
+delius: Delius {
+    style {
+        font-size: 20
+    }
+    d_allocate_pom: Update allocated POM
+    d_allocation_reason: Set POM allocation reason
+
+    d_allocate_pom -> d_allocation_reason
+}
+
+mpc -> delius
+
+*.style.border-radius: 10
+*.*.style.border-radius: 10
+*.*.style.stroke-width: 2
+*.*.style.font-size: 12

projects/manage-pom-cases-and-delius/tech-docs/source/async-api-reference.html.md.erb

@@ -0,0 +1,9 @@
+---
+title: AsyncAPI Reference
+source_url: 'https://github.com/ministryofjustice/hmpps-probation-integration-services/blob/main/projects/manage-pom-cases-and-delius/tech-docs/source/async-api-reference.html.md.erb'
+weight: 30
+---
+
+# ASyncAPI Reference
+
+<iframe width="100%" onload="this.height=screen.height" frameborder=0 src="https://studio.asyncapi.com/?url=https://raw.githubusercontent.com/ministryofjustice/hmpps-probation-integration-services/main/projects/manage-pom-cases-and-delius/tech-docs/spec/async-api.yaml&readOnly" title="ASync-API Spec"></iframe>