SFM Datadeling API Implementation Guide

Drug review

Planned feature for SFM version 4

SFM will provide access to drug review information for patients through the DrugReviewInfo endpoint. This allows querying based on parameters such as the number of treatments, last drug review date, and planned medication review date.

Endpoint

The endpoint is accessed via:

GET /api/Basic?_query=drugReviewInfo

Purpose

The purpose of this endpoint is to provide a detailed view of drug review information, including the number of treatments, last review date, planned review date, and other relevant details.

Query Parameters

Parameter	Type	Required	Description
numberOfTreatments	int	No	Minimum number of active treatments a patient must have.
lastDrugReview	datetime	No	ISO 8601 format. Patient filter, last drug review dates before this date.
plannedDrugReview	datetime	No	ISO 8601 format. Patient filter, planned drug review dates after this date.

Profile

Sfm Drug Review Info

SfmDrugReviewInfo (Extension)	I		Extension	Element id Extension Short description Comprehensive drug review information for a patient Definition An extension to capture detailed information about a patient's drug review, including treatment counts, review dates, and comments, within the SFM framework. Data type Extension Constraints ele-1: All FHIR elements must have a @value or children `hasValue() or (children().count() > id.count())` ext-1: Must have either extensions or value[x], not both `extension.exists() != value.exists()` Mappings rim: n/a rim: N/A
id		0..1	string	There are no (further) constraints on this element Element id Extension.id Short description Unique id for inter-element referencing Definition Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces. Data type string Mappings rim: n/a
extension		6..*	Extension	There are no (further) constraints on this element Element id Extension.extension Short description Additional content defined by implementations Alternate names extensions, user content Definition May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Comments There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. Data type Extension Sliced: Unordered, Open, by url(Value) Extensions are always sliced by (at least) url Mappings rim: n/a
patientFhirId		1..1	Extension	Element id Extension.extension:patientFhirId Short description Unique FHIR ID of the patient Alternate names extensions, user content Definition The unique identifier assigned to the patient within the FHIR system, used to associate drug review information with the correct patient record. Comments There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. Data type Extension Mappings rim: n/a
id		0..1	string	There are no (further) constraints on this element Element id Extension.extension:patientFhirId.id Short description Unique id for inter-element referencing Definition Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces. Data type string Mappings rim: n/a
extension		0..0	Extension	There are no (further) constraints on this element Element id Extension.extension:patientFhirId.extension Short description Additional content defined by implementations Alternate names extensions, user content Definition May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Comments There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. Data type Extension Sliced: Unordered, Open, by url(Value) Extensions are always sliced by (at least) url Mappings rim: n/a
url		1..1	Fixed Value	Element id Extension.extension:patientFhirId.url Short description identifies the meaning of the extension Definition Source of the definition for the extension code - a logical name or a URL. Comments The definition may point directly to a computable or human-readable definition of the extensibility codes, or it may be a logical URI as declared in some other specification. The definition SHALL be a URI for the Structure Definition defining the extension. Fixed value patientFhirId Mappings rim: N/A
value[x]		0..1		There are no (further) constraints on this element Element id Extension.extension:patientFhirId.value[x] Short description Value of extension Definition Value of extension - must be one of a constrained set of the data types (see Extensibility for a list). Mappings rim: N/A
valueString			string	Data type string
numberOfMedications		1..1	Extension	Element id Extension.extension:numberOfMedications Short description Total number of medications Alternate names extensions, user content Definition The total count of medications currently prescribed to the patient, reflecting the scope of their treatment plan. Comments There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. Data type Extension Mappings rim: n/a
id		0..1	string	There are no (further) constraints on this element Element id Extension.extension:numberOfMedications.id Short description Unique id for inter-element referencing Definition Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces. Data type string Mappings rim: n/a
extension		0..0	Extension	There are no (further) constraints on this element Element id Extension.extension:numberOfMedications.extension Short description Additional content defined by implementations Alternate names extensions, user content Definition May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Comments There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. Data type Extension Sliced: Unordered, Open, by url(Value) Extensions are always sliced by (at least) url Mappings rim: n/a
url		1..1	Fixed Value	Element id Extension.extension:numberOfMedications.url Short description identifies the meaning of the extension Definition Source of the definition for the extension code - a logical name or a URL. Comments The definition may point directly to a computable or human-readable definition of the extensibility codes, or it may be a logical URI as declared in some other specification. The definition SHALL be a URI for the Structure Definition defining the extension. Fixed value numberOfMedications Mappings rim: N/A
value[x]		0..1		There are no (further) constraints on this element Element id Extension.extension:numberOfMedications.value[x] Short description Value of extension Definition Value of extension - must be one of a constrained set of the data types (see Extensibility for a list). Mappings rim: N/A
valueInteger			integer	Data type integer
numberOfFixedUsageMedications		1..1	Extension	Element id Extension.extension:numberOfFixedUsageMedications Short description Count of fixed usage medications Alternate names extensions, user content Definition The number of medications prescribed with a fixed usage regimen, indicating treatments that have specific dosing schedules. Comments There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. Data type Extension Mappings rim: n/a
id		0..1	string	There are no (further) constraints on this element Element id Extension.extension:numberOfFixedUsageMedications.id Short description Unique id for inter-element referencing Definition Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces. Data type string Mappings rim: n/a
extension		0..0	Extension	There are no (further) constraints on this element Element id Extension.extension:numberOfFixedUsageMedications.extension Short description Additional content defined by implementations Alternate names extensions, user content Definition May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Comments There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. Data type Extension Sliced: Unordered, Open, by url(Value) Extensions are always sliced by (at least) url Mappings rim: n/a
url		1..1	Fixed Value	Element id Extension.extension:numberOfFixedUsageMedications.url Short description identifies the meaning of the extension Definition Source of the definition for the extension code - a logical name or a URL. Comments The definition may point directly to a computable or human-readable definition of the extensibility codes, or it may be a logical URI as declared in some other specification. The definition SHALL be a URI for the Structure Definition defining the extension. Fixed value numberOfFixedUsageMedications Mappings rim: N/A
value[x]		0..1		There are no (further) constraints on this element Element id Extension.extension:numberOfFixedUsageMedications.value[x] Short description Value of extension Definition Value of extension - must be one of a constrained set of the data types (see Extensibility for a list). Mappings rim: N/A
valueInteger			integer	Data type integer
lastReview		1..1	Extension	Element id Extension.extension:lastReview Short description Date of the last drug review Alternate names extensions, user content Definition The date and time when the most recent drug review was conducted for the patient, providing a timeline for treatment evaluation. Comments There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. Data type Extension Mappings rim: n/a
id		0..1	string	There are no (further) constraints on this element Element id Extension.extension:lastReview.id Short description Unique id for inter-element referencing Definition Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces. Data type string Mappings rim: n/a
extension		0..0	Extension	There are no (further) constraints on this element Element id Extension.extension:lastReview.extension Short description Additional content defined by implementations Alternate names extensions, user content Definition May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Comments There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. Data type Extension Sliced: Unordered, Open, by url(Value) Extensions are always sliced by (at least) url Mappings rim: n/a
url		1..1	Fixed Value	Element id Extension.extension:lastReview.url Short description identifies the meaning of the extension Definition Source of the definition for the extension code - a logical name or a URL. Comments The definition may point directly to a computable or human-readable definition of the extensibility codes, or it may be a logical URI as declared in some other specification. The definition SHALL be a URI for the Structure Definition defining the extension. Fixed value lastReview Mappings rim: N/A
value[x]		0..1		There are no (further) constraints on this element Element id Extension.extension:lastReview.value[x] Short description Value of extension Definition Value of extension - must be one of a constrained set of the data types (see Extensibility for a list). Mappings rim: N/A
valueDateTime			dateTime	Data type dateTime
lastReviewComment		1..1	Extension	Element id Extension.extension:lastReviewComment Short description Comments on the last review Alternate names extensions, user content Definition A summary or remarks provided by the healthcare provider during the last drug review, offering insights into the patient's response to treatment. Comments There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. Data type Extension Mappings rim: n/a
id		0..1	string	There are no (further) constraints on this element Element id Extension.extension:lastReviewComment.id Short description Unique id for inter-element referencing Definition Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces. Data type string Mappings rim: n/a
extension		0..0	Extension	There are no (further) constraints on this element Element id Extension.extension:lastReviewComment.extension Short description Additional content defined by implementations Alternate names extensions, user content Definition May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Comments There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. Data type Extension Sliced: Unordered, Open, by url(Value) Extensions are always sliced by (at least) url Mappings rim: n/a
url		1..1	Fixed Value	Element id Extension.extension:lastReviewComment.url Short description identifies the meaning of the extension Definition Source of the definition for the extension code - a logical name or a URL. Comments The definition may point directly to a computable or human-readable definition of the extensibility codes, or it may be a logical URI as declared in some other specification. The definition SHALL be a URI for the Structure Definition defining the extension. Fixed value lastReviewComment Mappings rim: N/A
value[x]		0..1		There are no (further) constraints on this element Element id Extension.extension:lastReviewComment.value[x] Short description Value of extension Definition Value of extension - must be one of a constrained set of the data types (see Extensibility for a list). Mappings rim: N/A
valueString			string	Data type string
plannedReview		1..1	Extension	Element id Extension.extension:plannedReview Short description Scheduled date for the next review Alternate names extensions, user content Definition The planned date and time for the patient's upcoming drug review, ensuring regular monitoring and adjustment of treatment plans. Comments There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. Data type Extension Mappings rim: n/a
id		0..1	string	There are no (further) constraints on this element Element id Extension.extension:plannedReview.id Short description Unique id for inter-element referencing Definition Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces. Data type string Mappings rim: n/a
extension		0..0	Extension	There are no (further) constraints on this element Element id Extension.extension:plannedReview.extension Short description Additional content defined by implementations Alternate names extensions, user content Definition May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Comments There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. Data type Extension Sliced: Unordered, Open, by url(Value) Extensions are always sliced by (at least) url Mappings rim: n/a
url		1..1	Fixed Value	Element id Extension.extension:plannedReview.url Short description identifies the meaning of the extension Definition Source of the definition for the extension code - a logical name or a URL. Comments The definition may point directly to a computable or human-readable definition of the extensibility codes, or it may be a logical URI as declared in some other specification. The definition SHALL be a URI for the Structure Definition defining the extension. Fixed value plannedReview Mappings rim: N/A
value[x]		0..1		There are no (further) constraints on this element Element id Extension.extension:plannedReview.value[x] Short description Value of extension Definition Value of extension - must be one of a constrained set of the data types (see Extensibility for a list). Mappings rim: N/A
valueDateTime			dateTime	Data type dateTime
url		1..1	Fixed Value	Element id Extension.url Short description identifies the meaning of the extension Definition Source of the definition for the extension code - a logical name or a URL. Comments The definition may point directly to a computable or human-readable definition of the extensibility codes, or it may be a logical URI as declared in some other specification. The definition SHALL be a URI for the Structure Definition defining the extension. Fixed value http://hl7.org/fhir/StructureDefinition/SfmDrugReviewInfo Mappings rim: N/A
value[x]		0..0		Element id Extension.value[x] Short description Value of extension Definition Value of extension - must be one of a constrained set of the data types. Mappings rim: N/A

Retrieval on Datashare

The actual retrieval of drug review data is performed using a named query on Basic. Parameters may include the registered patient identifier or a combination of treatments and timestamps:

GET [base]/Basic?_query=drugReviewInfo&numberOfTreatments=(min count)
GET [base]/Basic?_query=drugReviewInfo&lastDrugReview=lt(timestamp)
GET [base]/Basic?_query=drugReviewInfo&plannedDrugReview=gt(timestamp)

Note that SFM will return all matching entries based on the given parameters, and the number of items may grow during a typical session.

Example Request

GET /api/Basic?_query=drugReviewInfo&numberOfTreatments=3&lastDrugReview=2023-01-01T00:00:00Z&plannedDrugReview=2024-01-01T00:00:00Z

Example Response

{
  "total": 1,
  "entry": [
    {
      "resourceType": "Basic",
      "id": "patient-id",
      "meta": {
        "profile": [
          "<http://hl7.org/fhir/StructureDefinition/SfmDrugReviewInfo>"
        ],
        "lastUpdated": "2024-06-20T10:00:00Z"
      },
      "extension": [
        {
          "url": "<http://hl7.org/fhir/StructureDefinition/SfmDrugReviewInfo>",
          "extension": [
            {
              "url": "patientFhirId",
              "valueString": "patient-fhir-id"
            },
            {
              "url": "numberOfMedications",
              "valueInteger": 3
            },
            {
              "url": "numberOfFixedUsageMedications",
              "valueInteger": 1
            },
            {
              "url": "lastReview",
              "valueDateTime": "2023-06-15T00:00:00Z"
            },
            {
              "url": "lastReviewComment",
              "valueString": "Patient is responding well to the treatment."
            },
            {
              "url": "plannedReview",
              "valueDateTime": "2024-06-15T00:00:00Z"
            }
          ]
        }
      ]
    }
  ]
}

Usage Examples

Search by Number of Treatments

GET /Basic?_query=drugReviewInfo&numberOfTreatments=(nrOfTreatments)

Search by Number of Treatments and Minimum Last Drug Review Date

GET /Basic?_query=drugReviewInfo&numberOfTreatments=(nrOfTreatments)&lastDrugReview=(lastDrugReview)

Search by Number of Treatments and Maximum Planned Drug Review Date

GET /Basic?_query=drugReviewInfo&numberOfTreatments=(nrOfTreatments)&plannedDrugReview=(plannedDrugReview)

Search by Number of Treatments, Minimum Last Drug Review Date, and Maximum Planned Drug Review Date

GET /Basic?_query=drugReviewInfo&numberOfTreatments=(nrOfTreatments)&lastDrugReview=(lastDrugReview)&plannedDrugReview=(plannedDrugReview)

All requests require appropriate authorization headers:

Host: (host)
Content-Type: application/json
Accept: application/json
Authorization: Bearer (token)