CCM-13080: Event payloads (part 1) (#108)

tdroza-nhs · web-flow · commit bfe82721aef7 · 2025-11-17T09:23:05.000Z
* Update diagrams with latest event names
* Add event payload for MESH events
* Added PDM event data payloads
* Dev container
* Fix dataschema references in event schemas to point to specific data schemas
  instead of generic base schema
* Add missing properties to PDM resource event data schemas:
** Add nhsNumber and odsCode to PDMResourceAvailable
** Add retryCount to PDMResourceRetriesExceeded and PDMResourceUnavailable
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -0,0 +1,10 @@
+{
+  "containerEnv": {
+    "GITHUBMONITOR": "false",
+    "MAKECONFIG": "true",
+    "SHOWWELCOME": "true",
+    "UPDATEFROMTEMPLATE": "false"
+  },
+  "image": "ghcr.io/nhsdigital/nhs-notify-devcontainer-loaded-codespaces:main",
+  "name": "Codespaces Online Development"
+}
diff --git a/README.md b/README.md
diff --git a/docs/collections/_diagrams/c4code-core-notifier.md b/docs/collections/_diagrams/c4code-core-notifier.md
@@ -9,12 +9,16 @@ architecture-beta
     group coreNotifier(cloud)[CoreNotifier]
     service meshDownloaded(aws:res-amazon-eventbridge-event)[PDMResourceAvailable Event]
     service sqs(logos:aws-sqs)[CoreNotifier Queue] in coreNotifier
-    service coreNotified(aws:res-amazon-eventbridge-event)[NotifyCoreRequestSubmitted Event]
+    service coreNotified(aws:res-amazon-eventbridge-event)[MessageRequestSubmitted Event]
+    service coreFailed(aws:res-amazon-eventbridge-event)[MessageRequestFailed Event]
     service notifier(logos:aws-lambda)[CoreNotifier] in coreNotifier
     service notify(server)[NHS Notify Core]
+    junction j1
 
     meshDownloaded:R --> L:sqs
     sqs:R -->  L:notifier
     notifier:B --> T:notify
-    notifier:R --> L:coreNotified
+    notifier:R --> L:j1
+    j1:R -- L:coreNotified
+    j1:B --> L:coreFailed
 ```
diff --git a/docs/collections/_diagrams/c4code-mesh-statusreporter-sender.md b/docs/collections/_diagrams/c4code-mesh-statusreporter-sender.md
@@ -13,12 +13,20 @@ architecture-beta
     service clientConfig(aws:res-aws-systems-manager-parameter-store)[Client Configuration] in reportSender
     service reportSenderLambda(logos:aws-lambda)[Report Sender] in reportSender
     service s3(logos:aws-s3)[Reports] in reportSender
+    service reportSent(aws:res-amazon-eventbridge-event)[StatusReportSent Event]
     service mesh(server)[MESH]
+    junction j1
+    junction j2
+    junction j3
 
     reportGenerated:R --> L:sqs
     sqs:R --> L:reportSenderLambda
     clientConfig:B --> T:reportSenderLambda
     reportSenderLambda:B <-- T:s3
-    reportSenderLambda:R --> L:mesh
+    reportSenderLambda:R -- L:j1
+    j1:T -- B:j2
+    j2:R --> L:mesh
+    j1:B -- T:j3
+    j3:R --> L:reportSent
 
 ```
diff --git a/docs/collections/_diagrams/c4code-pdm-upload.md b/docs/collections/_diagrams/c4code-pdm-upload.md
@@ -9,7 +9,7 @@ description: PDM Upload
 architecture-beta
     service meshDownloaded(aws:res-amazon-eventbridge-event)[MESHInboxMessageDownloaded Event]
     service pdmSaved(aws:res-amazon-eventbridge-event)[PDMResourceSubmitted Event]
-    service pdmFailed(aws:res-amazon-eventbridge-event)[PDMResourceSubmssionFailed Event]
+    service pdmFailed(aws:res-amazon-eventbridge-event)[PDMResourceSubmssionRejected Event]
     group uploadToPdm(cloud)[UploadToPDM]
     service uploadQueue(logos:aws-sqs)[UploadToPDM Queue] in uploadToPdm
     service uploadLambda(logos:aws-lambda)[UploadToPDM] in uploadToPdm
diff --git a/docs/collections/_diagrams/c4code-printer-removefromqueue.md b/docs/collections/_diagrams/c4code-printer-removefromqueue.md
@@ -13,7 +13,7 @@ architecture-beta
    service manageDb(aws:arch-amazon-dynamodb)[ItemsWithTTL] in manageTTL
    service ttlStream(aws:res-amazon-dynamodb-stream) in manageTTL
    service manageTtlExpiry(logos:aws-lambda)[HandleTTLExpiry] in manageTTL
-   service printTTLExpired(aws:res-amazon-eventbridge-event)[ItemReady Event]
+   service printTTLExpired(aws:res-amazon-eventbridge-event)[ItemDequeued Event]
 
    pollEvent:R -- L:manageLambda
    manageLambda:R -- L:manageDb
diff --git a/docs/collections/_diagrams/c4code-printer-sendtoprint.md b/docs/collections/_diagrams/c4code-printer-sendtoprint.md
@@ -7,12 +7,13 @@ title: c4code-printer-sendtoprint
 
 ```mermaid
 architecture-beta
-    service itemReady(aws:res-amazon-eventbridge-event)[ItemReady Event]
+    service itemReady(aws:res-amazon-eventbridge-event)[MESHInboxMessageDownloaded Event]
     service printQueue(logos:aws-sqs)[UploadToPDM Queue] in sendToPrint
     service printLambda(logos:aws-lambda)[Print] in sendToPrint
     service docRefBucket(logos:aws-s3)[DocumentReference] in sendToPrint
     service digLtrsBucket(logos:aws-s3)[DigitalLetters] in sendToPrint
-    service printEvent(aws:res-amazon-eventbridge-event)[PrintReady Event TBC]
+    service pdmSubmitted(aws:res-amazon-eventbridge-event)[PDMResourceSubmitted Event]
+    service pdmFailed(aws:res-amazon-eventbridge-event)[PDMResourceSubmissionFailed Event]
     group sendToPrint(cloud)[UploadToPDM]
     junction j1
 
@@ -22,6 +23,7 @@ architecture-beta
     printLambda:B <-- T:docRefBucket
     printLambda:T --> B:digLtrsBucket
     printLambda:R -- L:j1
-    j1:R --> L:printEvent
+    j1:R --> L:pdmSubmitted
+    j1:B --> L:pdmFailed
 
 ```
diff --git a/docs/collections/_diagrams/c4code-printer-sendtoqueue.md b/docs/collections/_diagrams/c4code-printer-sendtoqueue.md
@@ -5,7 +5,7 @@ description: PDM Upload
 
 ```mermaid
    architecture-beta
-    group createTtl(cloud)[Time_To_Live]
+    group createTtl(cloud)[QueueAdder]
 
     service db(aws:arch-amazon-dynamodb)[ItemsWithTTL] in createTtl
     service createLambda(logos:aws-lambda)[CreateTTL] in createTtl
diff --git a/docs/collections/_diagrams/sequence-expire-print-ttl.md b/docs/collections/_diagrams/sequence-expire-print-ttl.md
@@ -23,5 +23,5 @@ sequenceDiagram
     stream ->> processTTLExpiry:
   end
   processTTLExpiry ->> processTTLExpiry: Filter unread attachments
-  processTTLExpiry ->> eb: ItemReady Event
+  processTTLExpiry ->> eb: ItemDequeued Event
 ```
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-mesh-inbox-message-downloaded-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-mesh-inbox-message-downloaded-data.schema.yaml
@@ -0,0 +1,16 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: MESHInboxMessageDownloaded Data
+description: Data payload of the MESHInboxMessageDownloaded event
+type: object
+additionalProperties: false
+properties:
+  messageReference:
+    $ref: ../defs/requests.schema.yaml#/properties/messageReference
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  messageUri:
+    $ref: ../defs/requests.schema.yaml#/properties/messageUri
+required:
+  - messageReference
+  - senderId
+  - messageUri
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-mesh-inbox-message-received-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-mesh-inbox-message-received-data.schema.yaml
@@ -0,0 +1,14 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: Placeholder Data
+description: Base data for digital letters - a placeholder until all data schemas are defined
+type: object
+additionalProperties: false
+properties:
+  meshMessageId:
+    type: string
+    minLength: 1
+    description: Id of the message in the MESH inbox
+    examples:
+      - "20200601122152994285_D59900"
+required:
+  - meshMessageId
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-pdm-resource-available-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-pdm-resource-available-data.schema.yaml
@@ -0,0 +1,21 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: PDMResourceAvailable Data
+description: Base data of the PDMResourceAvailable event
+additionalProperties: false
+properties:
+  messageReference:
+    $ref: ../defs/requests.schema.yaml#/properties/messageReference
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  resourceId:
+    $ref: ../defs/pdm.schema.yaml#/properties/resourceId
+  nhsNumber:
+    $ref: ../defs/requests.schema.yaml#/properties/nhsNumber
+  odsCode:
+    $ref: ../defs/requests.schema.yaml#/properties/odsCode
+required:
+  - messageReference
+  - senderId
+  - resourceId
+  - nhsNumber
+  - odsCode
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-pdm-resource-retries-exceeded-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-pdm-resource-retries-exceeded-data.schema.yaml
@@ -0,0 +1,18 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: PDMResourceRetriesExceeded Data
+description: Base data of the PDMResourceRetriesExceeded event
+additionalProperties: false
+properties:
+  messageReference:
+    $ref: ../defs/requests.schema.yaml#/properties/messageReference
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  resourceId:
+    $ref: ../defs/pdm.schema.yaml#/properties/resourceId
+  retryCount:
+    $ref: ../defs/pdm.schema.yaml#/properties/retryCount
+required:
+  - messageReference
+  - senderId
+  - resourceId
+  - retryCount
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-pdm-resource-submission-rejected-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-pdm-resource-submission-rejected-data.schema.yaml
@@ -0,0 +1,12 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: PDMResourceSubmissionRejected Data
+description: Base data of the PDMResourceSubmissionRejected event
+additionalProperties: false
+properties:
+  messageReference:
+    $ref: ../defs/requests.schema.yaml#/properties/messageReference
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+required:
+  - messageReference
+  - senderId
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-pdm-resource-submitted-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-pdm-resource-submitted-data.schema.yaml
@@ -0,0 +1,19 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: PDMResourceSubmitted Data
+description: Base data of the PDMResourceSubmitted event
+type: object
+additionalProperties: false
+properties:
+  messageReference:
+    $ref: ../defs/requests.schema.yaml#/properties/messageReference
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  resourceId:
+    $ref: ../defs/pdm.schema.yaml#/properties/resourceId
+  retryCount:
+    $ref: ../defs/pdm.schema.yaml#/properties/retryCount
+required:
+  - messageReference
+  - senderId
+  - resourceId
+  - retryCount
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-pdm-resource-unavailable-data.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-pdm-resource-unavailable-data.schema.yaml
@@ -0,0 +1,18 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: PDMResourceUnavailable Data
+description: Base data of the PDMResourceUnavailable event
+additionalProperties: false
+properties:
+  messageReference:
+    $ref: ../defs/requests.schema.yaml#/properties/messageReference
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  resourceId:
+    $ref: ../defs/pdm.schema.yaml#/properties/resourceId
+  retryCount:
+    $ref: ../defs/pdm.schema.yaml#/properties/retryCount
+required:
+  - messageReference
+  - senderId
+  - resourceId
+  - retryCount
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/defs/pdm.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/defs/pdm.schema.yaml
@@ -0,0 +1,17 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: PDM data
+description: Reusable types for NHS Notify payload schemas.
+type: object
+properties:
+  resourceId:
+    type: string
+    format: uuid
+    description: Identifier returned by PDM to the uploaded FHIR resource
+    examples:
+      - "f5524783-e5d7-473e-b2a0-29582ff231da"
+  retryCount:
+    type: integer
+    minimum: 1
+    description: Number of times that PDM has been polled while waiting for document processing to complete
+    examples:
+      - 2
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/defs/requests.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/defs/requests.schema.yaml
@@ -0,0 +1,34 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: Request data
+description: Reusable types for NHS Notify payload schemas.
+type: object
+properties:
+  messageReference:
+    type: string
+    description: Globally unique reference for each message, provided by the sender
+    examples:
+      - "19cd1d01-98c3-4ab8-a7b8-c1adabda7641"
+  senderId:
+    type: string
+    description: Identifier that the sender provided during onboarding. Provided in the body of each FHIR resource submitted by the sender.
+    examples:
+      - ""
+  messageUri:
+    type: string
+    format: uri
+    description: Uri to the storage location of the FHIR resource relating to this message request
+    examples:
+      - "s3://my-bucket/path/to/my-object"
+  nhsNumber:
+    type: string
+    description: Unique identifier of the intended recipient of the digital letter
+    pattern: '^\d{10}$'
+    minLength: 10
+    maxLength: 10
+    examples:
+      - "4857773456"
+  odsCode:
+    type: string
+    description: The ODS Code of the sending organisation. Used to identify the sender in NHS App
+    examples:
+      - ""
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.mesh.inbox.message.downloaded.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.mesh.inbox.message.downloaded.v1.schema.yaml
@@ -15,10 +15,9 @@ properties:
 
   dataschema:
     type: string
-    const: ../data/digital-letter-base-data.schema.yaml
+    const: ../data/digital-letters-mesh-inbox-message-downloaded-data.schema.yaml
     description: Canonical URI of the example event's data schema.
     examples:
-      - digital-letter-base-data.schema.yaml
+      - digital-letters-mesh-inbox-message-downloaded-data.schema.yaml
   data:
-    $ref: ../data/digital-letter-base-data.schema.yaml
-    description: Example payload wrapper containing notify-payload.
+    $ref: ../data/digital-letters-mesh-inbox-message-downloaded-data.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.mesh.inbox.message.received.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.mesh.inbox.message.received.v1.schema.yaml
@@ -15,10 +15,9 @@ properties:
 
   dataschema:
     type: string
-    const: ../data/digital-letter-base-data.schema.yaml
+    const: ../data/digital-letters-mesh-inbox-message-received-data.schema.yaml
     description: Canonical URI of the example event's data schema.
     examples:
-      - digital-letter-base-data.schema.yaml
+      - digital-letters-mesh-inbox-message-received-data.schema.yaml
   data:
-    $ref: ../data/digital-letter-base-data.schema.yaml
-    description: Example payload wrapper containing notify-payload.
+    $ref: ../data/digital-letters-mesh-inbox-message-received-data.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.pdm.resource.available.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.pdm.resource.available.v1.schema.yaml
@@ -15,10 +15,9 @@ properties:
 
   dataschema:
     type: string
-    const: ../data/digital-letter-base-data.schema.yaml
+    const: ../data/digital-letters-pdm-resource-available-data.schema.yaml
     description: Canonical URI of the example event's data schema.
     examples:
-      - digital-letter-base-data.schema.yaml
+      - digital-letters-pdm-resource-available-data.schema.yaml
   data:
-    $ref: ../data/digital-letter-base-data.schema.yaml
-    description: Example payload wrapper containing notify-payload.
+    $ref: ../data/digital-letters-pdm-resource-available-data.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.pdm.resource.retries.exceeded.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.pdm.resource.retries.exceeded.v1.schema.yaml
@@ -15,10 +15,9 @@ properties:
 
   dataschema:
     type: string
-    const: ../data/digital-letter-base-data.schema.yaml
+    const: ../data/digital-letters-pdm-resource-retries-exceeded-data.yaml
     description: Canonical URI of the example event's data schema.
     examples:
-      - digital-letter-base-data.schema.yaml
+      - digital-letters-pdm-resource-retries-exceeded-data.yaml
   data:
-    $ref: ../data/digital-letter-base-data.schema.yaml
-    description: Example payload wrapper containing notify-payload.
+    $ref: ../data/digital-letters-pdm-resource-retries-exceeded-data.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.pdm.resource.submission.rejected.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.pdm.resource.submission.rejected.v1.schema.yaml
@@ -0,0 +1,24 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+
+title: PDMResourceSubmissionRejected
+type: object
+allOf:
+  - $ref: ../digital-letters-pdm-profile.schema.yaml
+properties:
+  type:
+    type: string
+    const: uk.nhs.notify.digital.letters.pdm.resource.submission.rejected.v1
+    description: Concrete versioned event type string for this example event (.vN suffix).
+  source:
+    type: string
+    pattern: ^/nhs/england/notify/(production|staging|development|uat)/(primary|secondary|dev-[0-9]+)/data-plane/digitalletters/pdm
+    description: Event source for digital letters  examples.
+
+  dataschema:
+    type: string
+    const: ../data/digital-letters-pdm-resource-submission-rejected-data.schema.yaml
+    description: Canonical URI of the example event's data schema.
+    examples:
+      - digital-letters-pdm-resource-submission-rejected-data.schema.yaml
+  data:
+    $ref: ../data/digital-letters-pdm-resource-submission-rejected-data.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.pdm.resource.submitted.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.pdm.resource.submitted.v1.schema.yaml
@@ -1,4 +1,5 @@
 $schema: https://json-schema.org/draft/2020-12/schema
+
 title: PDMResourceSubmitted
 type: object
 allOf:
@@ -15,10 +16,9 @@ properties:
 
   dataschema:
     type: string
-    const: ../data/digital-letter-base-data.schema.yaml
+    const: ../data/digital-letters-pdm-resource-submitted-data.schema.yaml
     description: Canonical URI of the example event's data schema.
     examples:
-      - digital-letter-base-data.schema.yaml
+      - digital-letters-pdm-resource-submitted-data.schema.yaml
   data:
-    $ref: ../data/digital-letter-base-data.schema.yaml
-    description: Example payload wrapper containing notify-payload.
+    $ref: ../data/digital-letters-pdm-resource-submitted-data.schema.yaml
diff --git a/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.pdm.resource.unavailable.v1.schema.yaml b/src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.pdm.resource.unavailable.v1.schema.yaml
diff --git a/src/cloudevents/readme-index.yaml b/src/cloudevents/readme-index.yaml
