PI-2127: Add documentation for 'Create and Vary a Licence and Delius' (…

…#3695)

projects/create-and-vary-a-licence-and-delius/README.md

@@ -1,3 +1,59 @@
-# create-and-vary-a-licence-and-delius
+# Create and Vary a Licence and Delius
 
-// TODO Describe the service
+Supports integration between [Create and Vary a Licence](https://github.com/ministryofjustice/create-and-vary-a-licence) and [Delius](https://github.com/ministryofjustice/delius). This service listens to domain events raised when a licence is activated in _Create and Vary a Licence_, determines the licence conditions that will now apply to person on probation and creates these licence conditions in _Delius_ for the purposes of managing the licence supervision. Licence conditions are modelled differently across the two services and therefore this service uses a mapping defined in the _Delius_ database to determine the type of licence condition to create. The service also provides API endpoints providing probation case management information to _Create and Vary a Licence_.
+
+## Business Need
+
+Reducing re-keying of licence conditions across _Create and Vary a Licence_ and _Delius_ saving probation practitioners time and improving data quality
+
+## Data Dependencies
+
+_Create and Vary a Licence_ depends on _Delius_ data for background on the relevant **Person on Probation** and the specific **Probation Case** as well as which areas of the probation service have responsibility for the case. The API also enables _Create a Vary a Licence_ to add a specific **Role** to a _Delius_ **User**, which supports onboarding to the service without the need for manual work to update permissions.
+
+### Context Map - Probation Data
+
+![Context Map](./tech-docs/source/img/create-and-vary-a-licence-api-context-map.svg)
+
+**Case Responsibility** is not a single concept in _Delius_ and therefore _Create and Vary a Licence_ uses a number of _Delius_ entities to determine which cases to show to it's users.
+
+## Workflows
+
+### Licence Condition Workflows
+
+Licence conditions are managed in _Create and Vary a Licence_ and supervised by probation practitioners using _Delius_. Workflows across the two systems reduce the need for manual re-keying of the licence condition information.
+
+#### Context Map - Licence Conditions
+
+![Context Map](./tech-docs/source/img/create-and-vary-a-licence-activation-workflow-context-map.svg)
+
+#### Workflow: Licence Activation
+
+Activation of a licence on release from prison triggers creation of licence conditions in _Delius_. There are three types of licence condition **Standard Conditions**, **Additional Conditions** and **Bespoke Conditions**. The mapping process between _Create and Vary a Licence_ and _Delius_ determines how each licence condition is created in Delius. If the mapping between the _Create and Vary a Licence_ and _Delius_ conditions cannot be found the incoming domain event message will fail to process and the licence condition will not be automatically created.
+
+| Business Event     | Message Event Type / Filter                 |
+|--------------------|---------------------------------------------|
+| Licence Activation | create-and-vary-a-licence.licence.activated |
+
+![Workflow Map](./tech-docs/source/img/create-and-vary-a-licence-workflow-create-licence-condition.svg)
+
+## Interfaces
+
+### Message Formats
+
+The service responds to HMPPS Domain Event messages via the
+[Create and Vary a Licence and Delius Queue](https://github.com/ministryofjustice/cloud-platform-environments/blob/main/namespaces/live.cloud-platform.service.justice.gov.uk/hmpps-probation-integration-services-prod/resources/create-and-vary-a-licence-queue.tf).
+The events are raised by the [Create and Vary a Licence Service](https://github.com/ministryofjustice/create-and-vary-a-licence-api)
+to communicate activation of the licence.
+
+Example [messages](./src/dev/resources/messages/) are in the development source tree.
+
+Incoming messages are filtered on `eventType` by the [SQS queue policy](https://github.com/ministryofjustice/cloud-platform-environments/blob/main/namespaces/live.cloud-platform.service.justice.gov.uk/hmpps-probation-integration-services-prod/resources/create-and-vary-a-licence-queue.tf#L5-L9)
+
+### API Access Control
+
+API endpoints are secured by roles supplied by the HMPPS Auth client used in
+the requests
+
+| API Endpoint | Required Role                                    |
+|--------------|--------------------------------------------------|
+| All          | ROLE_PROBATION\_API_\_CVL_\_CASE_DETAIL |

projects/create-and-vary-a-licence-and-delius/tech-docs/diag/create-and-vary-a-licence-activation-workflow-context-map.d2

@@ -0,0 +1,37 @@
+
+style {
+  fill: "#ffffff"
+}
+
+context-create-and-vary-a-licence: Create and Vary a Licence Context {
+  entities: Entities {
+    grid-columns: 3
+    pop: Person on Probation
+    licence-condition: Licence Condition
+  }
+}
+
+context-delius: Delius Context {
+
+  interface: Create and Vary a Licence\n and Delius {
+    type: Anti-Corruption\nLayer
+  }
+
+  entities: Entities {
+    grid-columns: 3
+    pop: Person on Probation
+    event: Event
+    disposal: Disposal
+    licence-condition: Licence Condition
+    licence-condition-mapping: Licence Condition\nMapping
+    licence-condition-manager: Licence Condition\nManager
+    key-date: Key Date
+    contact: Contact
+  }
+}
+
+context-create-and-vary-a-licence--context-delius.interface: Upstream\n\n\nDownstream
+
+*.style.border-radius: 10
+*.*.style.border-radius: 10
+*.*.style.stroke-width: 2

projects/create-and-vary-a-licence-and-delius/tech-docs/diag/create-and-vary-a-licence-api-context-map.d2

@@ -0,0 +1,43 @@
+
+style {
+  fill: "#ffffff"
+}
+
+context-delius: Delius Context {
+
+  entities: Entities {
+    grid-columns: 3
+    provider: Probation Provider
+    PDU: Probation Delivery Unit
+    LAU: Local Admin Unit
+    team: Team
+    PDU-head: PDU Head
+    staff: Staff
+    user: Delius User
+    role: Delius User Role
+    pop: Person on Probation
+    caseload: Caseload
+    provider--PDU--LAU--team
+  }
+
+
+  interface: Create and Vary a Licence\n and Delius {
+    type: Anti-Corruption\nLayer
+  }
+}
+
+context-create-and-vary-a-licence: Create and Vary a Licence Context {
+  entities: Entities {
+    grid-columns: 2
+    pop: Person on Probation
+    responsibility: Case Responsibility
+    user: HMPPS User
+    role: HMPPS User Role
+  }
+}
+
+context-delius.interface--context-create-and-vary-a-licence: Upstream\n\n\nDownstream
+
+*.style.border-radius: 10
+*.*.style.border-radius: 10
+*.*.style.stroke-width: 2

projects/create-and-vary-a-licence-and-delius/tech-docs/diag/create-and-vary-a-licence-workflow-create-licence-condition.d2

@@ -0,0 +1,57 @@
+# Create and Vary a Licence Workflow: Create Licence Condition
+
+direction: right
+
+style {
+  fill: "#ffffff"
+}
+
+# What triggers the workflow?
+create-and-vary-a-licence: Create and Vary a Licence {
+     style.font-size: 24
+
+     explanation: |md
+     ## Licence Activitation
+     - On licence activition licence conditions\
+       are supervised by probation practitioners
+     |
+
+     licence_activated: Licence Activated
+}
+
+domain_event: "create-and-vary-a-licence\n.licence.activated" {
+    style.font-size: 12
+    shape: queue
+}
+
+# What happens in Delius?
+delius: Delius {
+    style.font-size: 24
+    grid-columns: 2
+
+    d_licence_condition_1: Map to Delius\nLicence Condition
+    d_licence_condition_2: Create Delius\nLicence Condition
+    d_contact: Create Contact
+
+    d_licence_condition_1 -> d_licence_condition_2 -> d_contact
+
+    explanation: |md
+    ## Licence Creation
+    - Delius is used to log and track the supervision\
+      of all licence conditions
+    - A licence condition entity must be\
+      created in Delius for each condition being supervised
+    - Delius licence condition wording and terminology differs from\
+      that of Create and Vary a Licence
+    - A static mapping exists in the Delius database\
+      between CVL licence conditions and Delius licence conditions
+    |
+
+}
+
+create-and-vary-a-licence -> domain_event -> delius
+
+*.style.border-radius: 10
+*.*.style.border-radius: 10
+*.*.style.stroke-width: 2
+*.*.style.font-size: 12