# Argo 23: Patient-Provider Messaging Exploration Calls

## Scope

### Summary

FHIR based API for third-party patient-facing apps to authenticate a user with [SMART App Launch](https://www.hl7.org/fhir/smart-app-launch/app-launch.html), and exchange communications on their behalf with providers and other office staff who are using EHR based messaging functionality.

### Requirements for patient messaging MVP (based on [discussion of current messaging implementations](https://confluence.hl7.org/pages/viewpage.action?pageId=161062451#PatientProviderMessagingCallNotes-April5)):
- Recipient list should be based on EHR config, including possibility of messaging to a provider, department, or group of departments
- If providers or patients can send messages with rich text from the EHR or portal, this data must conveyed to clients even if the write API only supports plain text
- Server can respond with an automated message or direct patient to other areas of the portal in response to a message
- Support for chronological "inbox" model and "threaded" model with ability to retrieve just top level messages or full threads
- Messages should have a email style text subject line and may also have a reason coding from a pre-defined list
- Reason list should be configurable in EHR since systems may use this for automated replies or message routing
- Ensure there is a way to differentiate subject from sender to support use by proxies. Also, provide guidance in spec on how proxy support should work from a server perspective.

### Nice to have in MVP (consider whether to actually include in profile):
- Providers can mark messages as "no reply allowed" when sending
- Some systems have message search and others don't, so supporting search params should be possible, but not required
- Some systems support display of read receipts when configured to do so

### Out of scope for MVP:
- Provider's initiation or responding to messages *from* a third party app - all their interactions should happen from the inbox in the EHR. This system should have access to the list of messageable patients and metadata such as the last time an app login with messaging scope occurred using internal APIs.
- Some providers charge per message - these providers should turn off third party API based access to messaging and only allow access via the portal where restrictions can be communicated and payment can be collected if needed
- Some servers may enable the patient or patient proxy sending a message to specify which proxies will be able to see the response from the provider. This is out of scope for v1, however, servers may wish to mandate that registered apps to display a banner to users sending a message indicating that all proxies will be able view the response.
- Communication of EHR defined messaging templates to the app, though apps may use their own templates to collect information and generate the message body
- Support soft deletion of messages from client app - messages shouldn't then show up on the portal or in other apps
- Saving and retrieving draft messages on the server
- Ability for patients or providers to specify message priority (systems surveyed don't support this for patient messaging)
- Setting reply-to when message is sent

## Specification

### Profile on Communication resource:
Updated guidance on the use of the [Communication resource](https://hl7.org/fhir/communication.html): https://jira.hl7.org/browse/FHIR-40760
- [`status`](https://hl7.org/fhir/communication-definitions.html#Communication.status) - a required element in [Communication](https://hl7.org/fhir/communication-definitions.html). Client shall set this element to `in-progress` when creating a new message. The server may set the status to another value once the message has been create or accessed such as `completed`.
- [`sent`](https://hl7.org/fhir/communication-definitions.html#Communication.sent) - Server shall populate dateTime when a resource is created. If this element is populated by the client, the server should replace it.
- [`received`](https://hl7.org/fhir/communication-definitions.html#Communication.received) [0..1] - may be populated by the server when the message is accessed by a client or the server determines that the message has been viewed by a provider.
- [`recipient`](https://hl7.org/fhir/communication-definitions.html#Communication.recipient)[1..n] - shall be populated by the client from a reference in the list retrieved using the [`$get-recipient-choices`](#Communicationget-reason-choicessubject) operation described below. The server may reject messages with multiple recipients if they set `allowMultipleRecipients` to false in their [`$get-recipient-choices`](#Communicationget-reason-choicessubject) output.
- [`sender`](https://hl7.org/fhir/communication-definitions.html#Communication.sender)[1..1] - shall be populated by the server based on the user who authorized the SMART App Launch flow.
- [`subject`](https://hl7.org/fhir/communication-definitions.html#Communication.subject)[1..1] - shall be populated by the server from the patient selected during the SMART App Launch flow (may be the same as user).
- *Note: 'subject' answers "who is the message about?". It's not the email subject line. See `topic.text` for this*.
- [`topic.text`](https://hl7.org/fhir/communication-definitions.html#Communication.topic) [0..1] - free-text "subject line" for this message (populates only the `.text` of this CodeableConcept). Servers may document a maximum length for this element and reject creation of communication resources that exceeed this limit with an appropriate OperationOutcome.
- `reasonCode` [0..1] - may be populated by the client based on values obtained through the `$get-reason-choices` operation described below. For example, this can be used to provide message categories to support proper routing and prioritization.
- [`inResponseTo`](https://hl7.org/fhir/communication-definitions.html#Communication.inResponseTo) [0..1] - element may be optionally used to indicate the message is part of a thread by referencing its immediate parent.
- [`partOf`](https://hl7.org/fhir/communication-definitions.html#Communication.partOf) [0..*] - server may populate this element with a reference to the root message of a thread by walking the tree of `inResponseTo` elements when the message is created. When present, that reference shall have a `message-root` extension with a valueBoolean set to `true`. A message may only have one root message and only one `partOf` reference in each resource may have a `message-root` extension with a value of `true`.
- [`payload.contentAttachment`](https://hl7.org/fhir/communication-definitions.html#Communication.payload.content_x_)
- The message body shall be placed in an attachment with a mime type of `text/plain` OR `text/html`.
- The attachment containing the message body shall have a `message-body` extension with a valueBoolean set to `true`. This extension may only be set on on one attachment per Communicaton resource, and should be omitted if the body of the message is blank.
- When the `text/html` format is used for the message body, only html tags commonly rendered by email clients should be used and the html may not reference external assets.
- When the `text/plain` format is used for the message body, it shall be encoded in UTF-8.
- Servers may set limits on the valid content types, body types, maximum attachment size and maximum number of attachments. These can be communicated to the client through an OperationOutcome message if the Communication resource being saved or updated exceeds these limits and should be clearly described in the server documentation. Servers should reject communications with attachments they plan to discard (i.e., if an EHR will not save an attachment, the message should be rejected).
- Clients that intent to retrieve messages from servers that support a body type of `text/html` shall be able to properly render a message in html format.

### Extensions:
- `no-reply` - valueBoolean indicating if message can't be replied to. May not be set by a third party client. Servers should not allow creation or update of messages with an inResponseTo reference to a message with this flag set. If this extension is not present it should be treated as set to `false`.

- `message-root` - valueBoolean indicating if a partcular reference in the partOf element is a pointer to the root message in the thread.

- `message-body` - valueBoolean indicating if a partcular attachment contains the body of the message.

### Access Control:
- Server shall provide access to requested Communication resources to senders, subjects, and users who have proxy access to the subject. Depending on parameters set on the message on the server and the identity of the logged in user, the server may exclude a subset of the messages from searches and requests (e.g., in the case of an app used by a proxy and a message marked as "patient only" by the provider).

### Workflow:
- After a client has created a Communication resource, the server may reject subsequent requests to update the resource.
- When a client receives a Communication resource for the first time (e.g., via polling or subscriptions), the EHR may populate `Communication.received` with a timestamp.
- Servers should respond to create or update action on resource with an operation outcome indicating success or an error

### Operations:

#### Communication/$get-reason-choices?[subject]

1..n {name: "reason", valueCoding: {} }

- Note that a display value for each coding shall be populated by the server

#### Communication/$get-recipient-choices?[reason],[subject]

1..n {name: "recipient", valueReference: [CareTeam | Device | Group | HealthcareService | Location | Organization | Patient | Practitioner | PractitionerRole | RelatedPerson)]},
1..1 {name: "allowMultipleRecipients", valueBoolean: false}

- Note that a display value for each reference shall be populated by the server

### [Search Parameters](https://hl7.org/fhir/communication-search.html)
- `sent` - required; servers should "eq", "gt", "lt", "ge", "le" prefixes
- `subject` - required
- `in-response-to` - optional, custom - if this parameter is supported, servers must support traversing the message hierarchy using `:below` modifier to fetch threads (e.g. `in-response-to:below=Communication/123`) and the `:missing` parameter to fetch only top level messages
- `part-of` - optional - if supported servers shall use the values of the `inResponseTo` element to return all messages in a thread.
- `_text` - optional - if supported, servers shall search one or more of the following elements: `topic.text`, `reasonCode`, `payload.ContentString`, `payload.contentAttachment`
- Servers may also support other search parameters as defined in the Communication resource

### Optional FHIR subscription support:
- Communication `create` and `update` filtered by subject (or recipient?)