fix(ccr0316): correct $send-message return type and document preconditions

input/pagecontent/changelog.md

@@ -7,7 +7,7 @@ This is the log of changes made to the eHealth Implementation Guide.
 ### Custom operations
 #### System operations
 #### Instance operations
-- Added `Appointment/$send-message` instance operation for sending an SMS reminder to a RelatedPerson participant of a video appointment (CCR0316). The recipient must be a RelatedPerson listed as a participant on the target Appointment; only the `sms` channel is currently supported.
+- Added `Appointment/$send-message` instance operation for sending an SMS reminder to a RelatedPerson participant of a video appointment (CCR0316). The recipient must be a RelatedPerson participant on the target Appointment; only the `sms` channel is currently supported. The operation returns the created [ehealth-message](StructureDefinition-ehealth-message.html) Communication, with `status` `completed` on success or `stopped` when the downstream gateway rejected the send. Validation preconditions (appointment profile/status, participant status, RelatedPerson active/period/telecom-purpose) are documented on the [OperationDefinition](OperationDefinition-Appointment-send-message.html).
 ### Code systems
 - Re-added `http://ehealth.sundhed.dk/cs/poa-privilege` (Power of Attorney Privilege) CodeSystem. Content is `not-present` — codes are vendor-specific and externally governed.
 - Added `http://ehealth.sundhed.dk/cs/telecom-purpose` for telecom contact point purpose codes.

input/resources/OperationDefinition-Appointment-send-message.json

@@ -6,9 +6,10 @@
   "title": "Send message",
   "status": "active",
   "kind": "operation",
-  "description": "Sends a message to a related person associated with an appointment via the specified channel. The recipient must be a RelatedPerson listed as a participant on the target Appointment. The created ehealth-message resource is system-generated; its `sender` is expected to be a Device reference (typically a contained Device representing the issuing system).",
+  "description": "Sends a message to a [RelatedPerson](StructureDefinition-ehealth-relatedperson.html) associated with a video appointment ([ehealth-videoappointment](StructureDefinition-ehealth-videoappointment.html) or [ehealth-group-videoappointment](StructureDefinition-ehealth-group-videoappointment.html)) via the specified channel. The recipient must be a RelatedPerson listed as a participant on the target Appointment. The created [ehealth-message](StructureDefinition-ehealth-message.html) resource is system-generated; its `sender` is a contained Device representing the issuing system.",
   "affectsState": true,
   "code": "send-message",
+  "comment": "The following preconditions must be satisfied — otherwise the operation returns `HTTP 400 Bad Request` with an OperationOutcome describing the violated rule:\n\n* `Appointment.meta.profile` is [ehealth-videoappointment](StructureDefinition-ehealth-videoappointment.html) or [ehealth-group-videoappointment](StructureDefinition-ehealth-group-videoappointment.html).\n* `Appointment.status` is `booked` or `pending`.\n* The `recipient` RelatedPerson is on `Appointment.participant[]` with `status` `accepted`, `tentative`, or `needs-action`.\n* `RelatedPerson.active` = `true`.\n* `RelatedPerson.period` has begun and has not ended.\n* `RelatedPerson.telecom[]` has exactly one element with `system` = `sms` and an [ehealth-telecom-purpose](StructureDefinition-ehealth-telecom-purpose.html) extension bound to `video-appointment-reminder-sms`.\n\nThe operation is synchronous and idempotent only from the FHIR caller's point of view: every successful call dispatches a new outbound message and creates a new Communication. The returned Communication has `status` = `completed` on successful dispatch or `status` = `stopped` when the downstream gateway rejected the send (the resource is still persisted so the failed attempt is auditable).",
   "resource": [
     "Appointment"
   ],
@@ -21,7 +22,7 @@
       "use": "in",
       "min": 1,
       "max": "1",
-      "documentation": "The related person to receive the message.",
+      "documentation": "The related person to receive the message. Must be listed as a participant on the target Appointment.",
       "type": "Reference",
       "targetProfile": [
         "http://ehealth.sundhed.dk/fhir/StructureDefinition/ehealth-relatedperson"
@@ -44,11 +45,8 @@
       "use": "out",
       "min": 1,
       "max": "1",
-      "documentation": "A reference to the created message resource.",
-      "type": "Reference",
-      "targetProfile": [
-        "http://ehealth.sundhed.dk/fhir/StructureDefinition/ehealth-message"
-      ]
+      "documentation": "The created Communication resource, conforming to the [ehealth-message](StructureDefinition-ehealth-message.html) profile. `Communication.status` is `completed` on successful dispatch or `stopped` when the downstream gateway rejected the send.",
+      "type": "Communication"
     }
   ]
 }