From d200e9125c8682bbf465bb140de63aa61f99a455 Mon Sep 17 00:00:00 2001 From: Kennan Keim <144141792+kckeim@users.noreply.github.com> Date: Mon, 18 Dec 2023 14:24:10 -0600 Subject: [PATCH] Updated MedicationRequest R4 Resource (#1019) * Updated MedicationRequest R4 Resource - Formatting changes throughout, including capitalizing/punctuation, and backticks to flip elements to code. - Overview paragraph updated slightly. - Condensed disclaimer to single instance. - Overhauled Custom Extension section. - Linked from the fields list. - Verified that anchor list changes were safe; no other pages in the repository reference this location at all). - Re-formatted the common extensions into a table format (like they appear on most other resources). - Swedish-specific extensions are still there, and separated out from the common ones. - Removed `intent` notes that appeared in a few places. - All the necessary details are listed alongside details for the `intent` parameter/field anyways. - Parameter Table + Implementation Notes re-written for clarity and to match standards for our recent resources. - Added the common "only listed elements are supported" disclaimer for the Create section. - Updated X-Request-Id to anonymized UUID and added opc-request-id to responses for Create and Patch sections. * Added hidden links for Custom Extensions * Added a couple periods * PRODOC-203564: Style edits. * Punctuation edits following conflict resolution * _revinclude text matches other resources now --------- Co-authored-by: Deitrich, Casey --- .../medications/medication-request.md | 144 +++++++++--------- lib/resources/r4/medication_request.yaml | 30 ++-- ...dication_request_contained_medication.yaml | 4 +- 3 files changed, 90 insertions(+), 88 deletions(-) diff --git a/content/millennium/r4/clinical/medications/medication-request.md b/content/millennium/r4/clinical/medications/medication-request.md index c503c89bf..8be17cd69 100644 --- a/content/millennium/r4/clinical/medications/medication-request.md +++ b/content/millennium/r4/clinical/medications/medication-request.md @@ -9,17 +9,18 @@ title: MedicationRequest | R4 API ## Overview -The MedicationRequest resource provides orders for all medications along with administration instructions for a patient in both the inpatient and outpatient setting (orders/prescriptions filled by a pharmacy and discharge medication orders). This resource also includes a patient's historical or documented home medications reported by the patient, significant other or another provider. +The MedicationRequest resource provides orders for all medications with administration instructions for a patient in both the inpatient and outpatient settings (orders or prescriptions filled by a pharmacy and discharge medication orders). This resource also includes a patient's historical or documented home medications reported by the patient, significant other, or another provider. -If the MedicationRequest represents a prescription (something the patient takes at home), the start, stop, and other data may not be a representation of when the medication was taken. For example, the system may not know if the patient ever filled or took the prescribed medication, or when the prescription was filled. Documented historical/past/home medications are commonly captured when taking the patient’s medical history. +If the medication request represents a prescription the patient takes at home, then the start, stop, and other information may not be a representation of when the medication was taken. For example, the system may not know if the patient ever filled or took the prescribed medication, or when the prescription was filled. Documented historical, past, and home medications are commonly captured when taking the patient’s medical history. -The following [HL7® FHIR® US Core Implementation Guide STU 4.0.0](https://hl7.org/fhir/us/core/STU4/){:target="_blank"} Profiles are supported by this resource: +This resource supports the following [HL7 FHIR US Core Implementation Guide STU 4.0.0](https://hl7.org/fhir/us/core/STU4/){:target="_blank"} profiles: * [US Core MedicationRequest Profile](https://hl7.org/fhir/us/core/STU4/StructureDefinition-us-core-medicationrequest.html){:target="_blank"} The following fields are returned if valued: -* [MedicationRequest id]( https://hl7.org/fhir/r4/resource-definitions.html#Resource.id){:target="_blank"} +* [MedicationRequest ID](https://hl7.org/fhir/r4/resource-definitions.html#Resource.id){:target="_blank"} +* [Extensions](#extensions) * [Status](https://hl7.org/fhir/r4/medicationrequest-definitions.html#MedicationRequest.status){:target="_blank"} * [Status Reason](https://hl7.org/fhir/r4/medicationrequest-definitions.html#MedicationRequest.statusReason){:target="_blank"} * [Intent](https://hl7.org/fhir/r4/medicationrequest-definitions.html#MedicationRequest.intent){:target="_blank"} @@ -72,6 +73,12 @@ The following fields are returned if valued: * [Allowed Boolean](https://hl7.org/fhir/r4/medicationrequest-definitions.html#MedicationRequest.substitution.allowed_x_){:target="_blank"} * [Prior Prescription](https://hl7.org/fhir/r4/medicationrequest-definitions.html#MedicationRequest.priorPrescription){:target="_blank"} +<%= disclaimer %> + +### Errors + +The common [errors] and [OperationOutcomes] may be returned. + ## Terminology Bindings <%= terminology_table(:medication_request, :r4) %> @@ -82,60 +89,74 @@ The following fields are returned if valued: ## Extensions +* [clinical-instruction] +* [pharmacy-verification-status] * [NLLPrescriptionFormat](https://simplifier.net/guide/swedishnationalmedicationlist/MedicationRequest) * [NLLRegistrationBasis](https://simplifier.net/guide/swedishnationalmedicationlist/MedicationRequest) * [NLLDosePackaging](https://simplifier.net/guide/swedishnationalmedicationlist/MedicationRequest) -All URLs for Swedish extensions are defined as `http://electronichealth.se/fhir/StructureDefinition/{id}` +### Custom Extensions - ID | Value\[x] Type | Description ------------------------------------------------------------|------------------------------------------------------------------|---------------------------------------------------------------- - `NLLPrescriptionFormat` | Coding | Current prescription format - `NLLRegistrationBasis` | Coding | Format for prescription registration - `NLLDosePackaging` | valueBoolean | Dose dispensed prescription +All URLs for custom extensions are defined as `https://fhir-ehr.cerner.com/r4/StructureDefinition/{id}` -## Custom Extensions + ID | Value\[x] Type | Description +---------------------------------|---------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------- + `clinical-instruction` | [String](https://hl7.org/fhir/r4/datatypes.html#string) | Extension to MedicationRequest.dosageInstruction. Represents instructions for an order that are intended for healthcare providers. + `pharmacy-verification-status` | [CodeableConcept](https://hl7.org/fhir/r4/datatypes.html#CodeableConcept) | Represents whether a medication request was verified by a pharmacist. Supported values are `Does not need pharmacy verification`, `Needs pharmacy verification`, or `Rejected by pharmacy`. -* Clinical Instruction: Is an extension on MedicationRequest.dosageInstruction with type of valueString. It represents instructions for an order that are intended for healthcare providers. URL for this extension is defined as: `https://fhir-ehr.cerner.com/r4/StructureDefinition/clinical-instruction`. +### Swedish Extensions -* Pharmacy Verification Status: Is an extension on MedicationRequest.extension with type of CodeableConcept. It represents whether a MedicationRequest has been verified by a pharmacist. Supported values are Does not need pharmacy verification, Needs pharmacy verification or Rejected by pharmacy. - URL for this extension is defined as: `https://fhir-ehr.cerner.com/r4/StructureDefinition/pharmacy-verification-status`. +All URLs for Swedish extensions are defined as `http://electronichealth.se/fhir/StructureDefinition/{id}` + + ID | Value\[x] Type | Description +-------------------------|-------------------------------------------------------------|----------------------------------------------------------- + `NLLPrescriptionFormat` | [Coding](https://hl7.org/fhir/r4/datatypes.html#codesystem) | Current prescription format. + `NLLRegistrationBasis` | [Coding](https://hl7.org/fhir/r4/datatypes.html#codesystem) | Format for prescription registration. + `NLLDosePackaging` | [Boolean](https://hl7.org/fhir/r4/datatypes.html#boolean) | Dose dispensed prescription. ## Search -Search for MedicationRequests that meet supplied query parameters: +Search for medication requests that meet supplied query parameters. GET /MedicationRequest?:parameters -_Implementation Notes_ - -We use the intent field to determine if a medication is an authorization or a medication reported by a patient. In the reported field, we support "Plan" and "Order" in accordance with the US Core Profile changes. - ### Authorization Types <%= authorization_types(provider: true, patient: true, system: true) %> ### Parameters - Name | Required? | Type | Description -------------------------|--------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - `_id` | This, or `patient` | [`token`] | The logical resource id associated with the resource. Example: `12345` - `patient` | This, or `_id` | [`reference`] | The specific patient to return MedicationRequests for. Example: `12345` - `status` | N | [`token`] | The [status] of the medication, may be a list separated by commas. Example: `active,completed` - `intent` | N | [`token`] | Whether the medication is an authorization or a medication reported by a patient. Example: `order,plan` - `-timing-boundsPeriod` | N | [`token`] | The date-time which should fall within the `dosageInstruction.timing.repeat.boundsPeriod` the medication should be given to the patient. Must be prefixed by `ge`. Example: `ge2014-05-19T20:54:02.000Z` - `_lastUpdated` | N | [`date`] | An explicit or implied date-time range within which the most recent clinically relevant update was made to the medication. Must include a time, and must be prefixed by `ge` or `le`. Example: `ge2014-05-19T20:54:02.000Z` - `_count` | N | [`number`] | The maximum number of results to include in a page. Example: `50` - `_revinclude` | N | [`token`] | Provenance resource entries to be returned as part of the bundle. Example:_revinclude=Provenance:target - -Notes: - -* `_revinclude` parameter may be provided once with the value `Provenance:target`. Example: `_revinclude=Provenance:target` -* `_revinclude` parameter may be provided with the `_id/patient/subject/account` parameter. Example: `_id=74771957,4732066&_revinclude=Provenance:target` + Name | Required? | Type | Description +------------------------|---------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + `_id` | Conditionally | [`token`] | The logical resource ID associated with the resource. Example: `_id=1234` + `patient` | Conditionally | [`reference`] | The specific patient to return medication requests for. Example: `patient=5678` + `status` | No | [`token`] | The [status] of the medication. May be a list separated by commas. Example: `status=active,completed` + `intent` | No | [`token`] | Whether the medication is an authorization or a medication reported by a patient. Example: `intent=order,plan` + `-timing-boundsPeriod` | No | [`token`] | The date and time which should fall within the `dosageInstruction.timing.repeat.boundsPeriod` when the medication should be given to the patient. Example: `-timing-boundsPeriod=ge2014-05-19T20:54:02.000Z` + `_lastUpdated` | No | [`date`] | The date and time range within which the most recent clinically relevant update was made to the medication. The time component is required. Example: `_lastUpdated=ge2014-05-19T20:54:02.000Z` + `_count` | No | [`number`] | The maximum number of results to include on a page. Example: `_count=50` + `_revinclude` | No | [`token`] | The Provenance resource entries to be returned as part of the bundle. Example: `_revinclude=Provenance:target` + +_Notes_ + +* When searching with the `_id` parameter: + * It must not be provided with any other parameters, except with the `_revinclude` parameter as indicated below. +* When searching with the `-timing-boundsPeriod` parameter: + * It must be provided with a `ge` prefix to imply the date range for the medications search. + * The time component is optional. + * Example: `-timing-boundsPeriod=ge2014-05-19T20:54:02.000Z` +* When searching with the `_lastUpdated` parameter: + * For a single `_lastUpdated` occurence: + * It must be provided with a `le` or `ge` prefix to imply the date range for the medications search. + * Example: `_lastUpdated=ge2014-05-19T20:54:02.000Z` + * For two `_lastUpdated` occurences: + * It must be provided with the `le` and `ge` prefixes to search for medications within the given upper and lower timestamps, respectively. + * Example: `_lastUpdated=ge2014-05-19T20:54:02.000Z&_lastUpdated=le2014-05-20T12:00:00.000Z` +* When searching with the `_revinclude` parameter: + * It can be provided once with the `Provenance:target` value. Example: `_revinclude=Provenance:target` + * It can be provided with the `_id` or `patient` parameter. Example: `_id=74771957,4732066&_revinclude=Provenance:target` + * When `_revinclude` is provided in a request to the closed endpoint, the OAuth2 token must include the scope corresponding to the Authorization Type, such as `user/Provenance.read`, `patient/Provenance.read` or `system/Provenance.read`. -* The `_lastUpdated` parameter may be provided: - * once with a prefix `ge` or `le` representing the earliest date or latest date. (e.g. `date=ge2015-01-01`, `date=le2016-01-01`) - * twice with the prefixes `ge`, `le` to indicate a specific range. (e.g. `date=ge2015-01-01&date=le2016-01-01`) ### Headers @@ -151,7 +172,6 @@ Notes: <%= headers status: 200 %> <%= json(:R4_MEDICATION_REQUEST_BUNDLE) %> -<%= disclaimer %> ### Example with RevInclude @@ -176,22 +196,13 @@ Notes: <%= headers status: 200 %> <%= json(:R4_MEDICATION_REQUEST_PATIENT_BUNDLE) %> -<%= disclaimer %> -### Errors - -The common [errors] and [OperationOutcomes] may be returned. +## Retrieve by ID -## Retrieve by id - -List an individual MedicationRequest by its id: +List an individual medication request by its ID. GET /MedicationRequest/:id -_Implementation Notes_ - -We use the intent field to determine if a medication is an authorization or a medication reported by a patient. In the reported field, we support "Plan" and "Order" in accordance with the US Core Profile changes. - ### Authorization Types <%= authorization_types(provider: true, patient: true, system: true) %> @@ -210,7 +221,6 @@ We use the intent field to determine if a medication is an authorization or a me <%= headers status: 200 %> <%= json(:R4_MEDICATION_REQUEST_ENTRY) %> -<%= disclaimer %> #### Patient Authorization Request For Active Status @@ -220,7 +230,6 @@ We use the intent field to determine if a medication is an authorization or a me <%= headers status: 200 %> <%= json(:R4_MEDICATION_REQUEST_PATIENT_ENTRY) %> -<%= disclaimer %> #### Patient Authorization Request For Entered in Error Status @@ -230,18 +239,17 @@ We use the intent field to determine if a medication is an authorization or a me <%= headers status: 200 %> <%= json(:R4_MEDICATION_REQUEST_ENTERED_IN_ERROR) %> -<%= disclaimer %> - -### Errors - -The common [errors] and [OperationOutcomes] may be returned. ## Create -Create an individual MedicationRequest. +Create an individual medication request. POST /MedicationRequest +_Notes_ + +* Only the body fields mentioned below are supported. Unsupported fields are ignored. + ### Authorization Types <%= authorization_types(provider: true, patient: false, system: true) %> @@ -276,24 +284,19 @@ Etag: W/"0" Last-Modified: Wed, 27 Mar 2019 15:59:30 GMT Location: https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/MedicationRequest/4595905 Vary: Origin -X-Request-Id: 1638e30e497b93ff4383b2ff0eaeea68 +X-Request-Id: 11111111-1111-1111-1111-111111111111 +opc-request-id: /11111111111111111111111111111111/11111111111111111111111111111111 -<%= disclaimer %> - -### Errors - -The common [errors] and [OperationOutcomes] may be returned. - ## Patch Patch an existing medication request. PATCH /MedicationRequest/:id -_Implementation Notes_ +_Notes_ -* This implementation follows the [JSON PATCH](https://tools.ietf.org/html/rfc6902) spec. +* This implementation follows the [JSON PATCH](https://tools.ietf.org/html/rfc6902) specification. * Only operations on the paths listed below are supported. ### Authorization Types @@ -329,15 +332,12 @@ Date: Tue, 26 Mar 2019 15:42:29 GMT Etag: W/"10" Last-Modified: Tue, 26 Mar 2019 15:42:27 GMT Vary: Origin -X-Request-Id: 47306a14c8a2c3afd4ab85aa9594101d +X-Request-Id: 11111111-1111-1111-1111-111111111111 +opc-request-id: /11111111111111111111111111111111/11111111111111111111111111111111 The `ETag` response header indicates the current `If-Match` version to use on subsequent updates. -### Errors - -The common [errors] and [OperationOutcomes] may be returned. - [`token`]: http://hl7.org/fhir/R4/search.html#token [`reference`]: http://hl7.org/fhir/R4/search.html#reference [`date`]: http://hl7.org/fhir/R4/search.html#date @@ -345,3 +345,5 @@ The common [errors] and [OperationOutcomes] may be returned. [status]: https://www.hl7.org/fhir/r4/valueset-medicationrequest-status.html [errors]: ../../../#client-errors [OperationOutcomes]: ../../../#operation-outcomes +[clinical-instruction]: #custom-extensions +[pharmacy-verification-status]: #custom-extensions diff --git a/lib/resources/r4/medication_request.yaml b/lib/resources/r4/medication_request.yaml index 5612aecfe..8776deda6 100644 --- a/lib/resources/r4/medication_request.yaml +++ b/lib/resources/r4/medication_request.yaml @@ -32,10 +32,10 @@ fields: - name: statusReason required: 'No' type: CodeableConcept - description: Reason for the current status + description: Reason for the current status. action: get binding: - description: Reason for the current status + description: Reason for the current status. terminology: - display: MedicationRequest Status Reason Codes system: http://terminology.hl7.org/CodeSystem/medicationrequest-status-reason @@ -63,10 +63,10 @@ fields: - name: category required: 'No' type: CodeableConcept - description: Type of Medication Request + description: Type of Medication Request. action: get binding: - description: Type of Medication Request + description: Type of Medication Request. terminology: - display: Medication Request Category Codes system: http://terminology.hl7.org/CodeSystem/medicationrequest-category @@ -80,10 +80,10 @@ fields: - name: priority required: 'No' type: code - description: Medication Request Priority + description: Medication Request Priority. action: get binding: - description: Medication Request Priority + description: Medication Request Priority. terminology: - display: Request Priority system: http://hl7.org/fhir/request-priority @@ -101,7 +101,7 @@ fields: - name: reported[x] required: 'Yes' type: boolean - description: Indicates if this record was captured as a secondary 'reported' record rather than as an original primary source-of-truth record. + description: Indicates if this record was captured as a secondary `reported` record rather than as an original primary source-of-truth record. action: create note: Must be of type boolean and must be set to `true`. example: | @@ -112,7 +112,7 @@ fields: required: 'Yes' type: CodeableConcept description: A code that defines the medication - note: Must be of type CodeableConcept. `text` and/or one `coding` with a `system` and `code` must be provided. + note: Must be of type CodeableConcept. Either `text`, or one `coding` with a `system` and `code` must be provided. example: | { "medicationCodeableConcept": { @@ -126,7 +126,7 @@ fields: } } binding: - description: A code that defines the medication + description: A code that defines the medication. terminology: - display: RxNorm system: http://www.nlm.nih.gov/research/umls/rxnorm @@ -149,7 +149,7 @@ fields: - name: encounter required: 'No' type: Reference (Encounter) - description: The Encounter this medication request was created or to which the creation of this record is tightly associated. + description: The `Encounter` this medication request was created or to which the creation of this record is tightly associated. action: create example: | { @@ -160,10 +160,10 @@ fields: - name: reasonCode required: 'No' type: CodeableConcept - description: Reason why medication is/was taken + description: Reason why medication is/was taken. action: get binding: - description: Reason why medication is/was taken + description: Reason why medication is/was taken. terminology: - display: SNOMED CT system: http://snomed.info/sct @@ -214,7 +214,7 @@ fields: type: string description: The supplemental instruction or warnings to the patient. url: https://www.hl7.org/fhir/r4/dosage-definitions.html#Dosage.additionalInstruction - note: If provided, can only be provided once. `text` is only supported. + note: If provided, can only be provided once. Only `text` supported. action: create example: | { @@ -319,7 +319,7 @@ fields: - name: code required: 'No' type: CodeableConcept - description: Code for a known/defined timing pattern + description: Code for a known/defined timing pattern. note: | url: https://www.hl7.org/fhir/r4/datatypes-definitions.html#Timing.code binding: - description: Code for a known/defined timing pattern + description: Code for a known/defined timing pattern. terminology: - display: TimingAbbreviation system: http://terminology.hl7.org/CodeSystem/v3-GTSAbbreviation diff --git a/lib/resources/r4/medication_request_contained_medication.yaml b/lib/resources/r4/medication_request_contained_medication.yaml index 3cbaa24db..0c023f4b6 100644 --- a/lib/resources/r4/medication_request_contained_medication.yaml +++ b/lib/resources/r4/medication_request_contained_medication.yaml @@ -5,9 +5,9 @@ fields: - name: code required: 'No' type: CodeableConcept - description: A code that defines the medication + description: A code that defines the medication. binding: - description: A code that defines the medication + description: A code that defines the medication. terminology: - display: RxNorm system: http://www.nlm.nih.gov/research/umls/rxnorm