Module health.fhir.cds
ballerinax/health.fhir.cds Ballerina library
Ballerina package containing CDS data models compliant with https://cds-hooks.hl7.org/2.0/ implementation guide.
CDS package
Package Overview
| CDS | 2.0 |
| Implementation Guide | http://hl7.org/fhir/ |
Capabilities and features
CDS resource types
| 1). CdsService | [Definition] |
| 2). CdsRequest | [Definition] |
| 3). FhirAuthorization | [Definition] |
| 4). OrderSignContext | [Definition] |
| 5). OrderSelectContext | [Definition] |
| 6). OrderDispatchContext | [Definition] |
| 7). AppointmentBookContext | [Definition] |
| 8). PatientViewContext | [Definition] |
| 9). EncounterStartContext | [Definition] |
| 10). EncounterDischargeContext | [Definition] |
| 11). CdsResponse | [Definition] |
| 12). Card | [Definition] |
| 13). Source | [Definition] |
| 14). Suggestion | [Definition] |
| 15). Action | [Definition] |
| 16). Link | [Definition] |
| 17). Feedback | [Definition] |
| 18). AcceptedSuggestion | [Definition] |
| 19). OverrideReason | [Definition] |
Functions
cdsErrorToHttpResponse
function cdsErrorToHttpResponse(CdsError cdsError) returns ResponseCreate HTTP response from a CDS error record.
Parameters
- cdsError CdsError - CDS error record.
Return Type
- Response - return HTTP response.
createCdsError
function createCdsError(string message, int statusCode, string? description, error? cause) returns CdsErrorCreate a CDS type error.
Parameters
- message string - Message to be added to the error.
- statusCode int - Http status code.
- description string? (default ()) - Human readable description about the issue.
- cause error? (default ()) - (optional) original error.
Return Type
- CdsError - CDS error record
validateAndProcessPrefetch
function validateAndProcessPrefetch(CdsRequest cdsRequest, CdsService cdsService) returns CdsRequest|CdsErrorValidate and fetch missing prefetch FHIR data for a CdsRequest.
Parameters
- cdsRequest CdsRequest - Cds request payload
- cdsService CdsService - Cds hook/ service definition
Return Type
- CdsRequest|CdsError - return CdsError, if there are any issues while processing the prefetch templates, otherwise CdsRequest payload with newly fetched FHIR data
validateContext
function validateContext(CdsRequest cdsRequest, CdsService cdsService) returns CdsError?This method will validate the context data attached in the Cds request against it's respective Cds service definition.
Parameters
- cdsRequest CdsRequest - Cds request payload
- cdsService CdsService - Cds hook/ service definition
Return Type
- CdsError? - return CdsError, if there are any context validation issues
Enums
health.fhir.cds: ActionType
The type of action being performed. Allowed values are: create, update, delete.
Members
health.fhir.cds: FeedbackOutcome
Members
health.fhir.cds: Hook
As a specification, CDS Hooks does not prescribe a default or required set of hooks for implementers. Rather, the set of hooks defined here are merely a set of common use cases that were used to aid in the creation of CDS Hooks.
PATIENT_VIEW - https://cds-hooks.hl7.org/hooks/patient-view/STU1/patient-view/ ORDER_SIGN - https://cds-hooks.hl7.org/hooks/order-sign/STU1/order-sign/ ORDER_SELECT - https://cds-hooks.hl7.org/hooks/order-select/STU1/order-select/ ORDER_DISPATCH - https://cds-hooks.hl7.org/hooks/order-dispatch/STU1/order-dispatch/ ENCOUNTER_START - https://cds-hooks.hl7.org/hooks/encounter-start/STU1/encounter-start/ ENCOUNTER_DISCHARGE - https://cds-hooks.hl7.org/hooks/encounter-discharge/STU1/encounter-discharge/ APPOINTMENT_BOOK - https://cds-hooks.hl7.org/hooks/appointment-book/STU1/appointment-book/
Members
health.fhir.cds: Indicator
Urgency/importance of what this card conveys.
Members
health.fhir.cds: LinkType
The type of the given URL. There are two possible values for this field. A type of absolute indicates that the URL is absolute and should be treated as-is. A type of smart indicates that the URL is a SMART app launch URL and the CDS Client should ensure the SMART app launch URL is populated with the appropriate SMART launch parameters.
Members
health.fhir.cds: SelectionBehavior
Describes the intended selection behavior of the suggestions in the card.
Members
Configurables
health.fhir.cds: cds_services
Records
health.fhir.cds: AcceptedSuggestion
The CDS Client can inform the service when one or more suggestions were accepted by POSTing a simple JSON object. https://cds-hooks.hl7.org/2.0/#suggestion-accepted
Fields
- id string - The card.suggestion.uuid from the CDS Hooks response. Uniquely identifies the suggestion that was accepted.
health.fhir.cds: Action
Description. https://cds-hooks.hl7.org/2.0/#action
Fields
- 'type ActionType - The type of action being performed. Allowed values are: create, update, delete.
- description string - Human-readable description of the suggested action MAY be presented to the end-user.
- 'resource? DomainResource - A FHIR resource.
- resourceId? string - A relative reference to the relevant resource.
health.fhir.cds: AppointmentBookContext
Describe the set of contextual data used by appoinment-book hook.
Fields
- userId string - The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole. For example, PractitionerRole/123 or Practitioner/abc.
- patientId string - The FHIR Patient.id of the current patient in context.
- encounterId? string - The FHIR Encounter.id of the current encounter in context.
- appointments Appointment[] - FHIR Bundle of Appointments in 'proposed' state.
health.fhir.cds: Card
Cards can provide a combination of information (for reading), suggested actions (to be applied if a user selects them), and links (to launch an app if the user selects them). https://cds-hooks.hl7.org/2.0/#card-attributes
Fields
- uuid? string - Unique identifier of the card.
- summary string - One-sentence, <140-character summary message for display to the user inside of this card.
- detail? string - Optional detailed information to display; if provided MUST be represented in (GitHub Flavored) Markdown.
- indicator Indicator - Urgency/importance of what this card conveys. Allowed values, in order of increasing urgency, are: info, warning, critical.
- 'source Source - Grouping structure for the Source of the information displayed on this card.
- suggestions? Suggestion[] - Allows a service to suggest a set of changes in the context of the current activity.
- selectionBehavior? SelectionBehavior - Describes the intended selection behavior of the suggestions in the card. Allowed values are: at-most-one, any
- overrideReason? Coding[] - Override reasons can be selected by the end user when overriding a card without taking the suggested recommendations.
- links? Link[] - Allows a service to suggest a link to an app that the user might want to run for additional information or to help guide a decision.
health.fhir.cds: CdsErrorDetails
CDS error details record.
Fields
- message string - Message to be added to the error.
- code int - Http status code/ error code.
- cause error? - (optional) original error.
- description string? - Description or insight about the error that can be used to reslove the issue.
health.fhir.cds: CdsRequest
A CDS Client SHALL call a CDS Service by POSTing a JSON document to the service as described below.
Fields
- hook Hook - The hook this service should be invoked on.
- hookInstance string - A universally unique identifier (UUID).
- fhirServer? string - The base URL of the CDS Client's FHIR server.
- fhirAuthorization? FhirAuthorization - A structure holding an OAuth 2.0 bearer access token granting the CDS Service access to FHIR resources, along with supplemental information relating to the token.
- context Context - Hook-specific contextual data that the CDS service will need.
- prefetch? map<DomainResource> - The FHIR data that was prefetched by the CDS Client.
health.fhir.cds: CdsResponse
For successful responses, CDS Services SHALL respond with a 200 HTTP response with an object containing a cards array and optionally a systemActions array as described below. Each card contains decision support guidance from the CDS Service. Cards are intended for display to an end user. The data format of a card defines a very minimal set of required attributes with several more optional attributes to suit a variety of use cases, such as: narrative informational decision support, actionable suggestions to modify data, and links to SMART apps. https://cds-hooks.hl7.org/2.0/#cds-service-response
Fields
- cards Card[] - Cards can provide a combination of information (for reading), suggested actions (to be applied if a user selects them), and links (to launch an app if the user selects them).
- systemActions? Action[] - An array of Actions that the CDS Service proposes to auto-apply.
health.fhir.cds: CdsService
Defines a CDS service according to the spec - https://cds-hooks.hl7.org/2.0/#response.
Fields
- hook Hook - The hook this service should be invoked on.
- title? string - The human-friendly name of this service.
- description string - The description of this service.
- id string - The {id} portion of the URL to this service which is available at {baseUrl }/cds -services/{id}.
- usageRequirements? string - Human-friendly description of any preconditions for the use of this CDS Service.
health.fhir.cds: EncounterDischargeContext
Describe the set of contextual data used by encounter-discharge hook.
Fields
- userId string - The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole. For example, PractitionerRole/123 or Practitioner/abc.
- patientId string - The FHIR Patient.id of the current patient in context.
- encounterId string - The FHIR Encounter.id of the current encounter in context.
health.fhir.cds: EncounterStartContext
Describe the set of contextual data used by encounter-start hook.
Fields
- userId string - The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole. For example, PractitionerRole/123 or Practitioner/abc.
- patientId string - The FHIR Patient.id of the current patient in context.
- encounterId string - The FHIR Encounter.id of the current encounter in context.
health.fhir.cds: Feedback
A CDS Client provides feedback by POSTing a JSON document. The feedback endpoint can be constructed from the CDS Service endpoint and a path segment of "feedback" as {baseUrl}/cds-services/{service.id}/feedback. The request to the feedback endpoint SHALL be an object containing an array. https://cds-hooks.hl7.org/2.0/#feedback
Fields
- card string - The card.uuid from the CDS Hooks response. Uniquely identifies the card.
- outcome FeedbackOutcome - A value of accepted or overridden.
- acceptedSuggestions? AcceptedSuggestion[] - An array of json objects identifying one or more of the user's AcceptedSuggestions. Required for accepted outcomes.
- overrideReason? OverrideReason - A json object capturing the override reason as a Coding as well as any comments entered by the user.
- outcomeTimestamp dateTime - ISO8601 representation of the date and time in Coordinated Universal Time (UTC) when action was taken on the card, as profiled in section 5.6 of RFC3339. e.g. 1985-04-12T23:20:50.52Z
health.fhir.cds: Feedbacks
Array of Feedback.
Fields
- feedback Feedback[] - field description
health.fhir.cds: FhirAuthorization
The access token is specified in the CDS Service request via the fhirAuthorization request parameter. This parameter is an object that contains both the access token as well as other related information as specified below.
Fields
- access_token string - This is the OAuth 2.0 access token that provides access to the FHIR server.
- token_type string(default "Bearer") - Fixed value: Bearer
- expires_in int - The lifetime in seconds of the access token.
- scope string - The scopes the access token grants the CDS Service.
- subject string - The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server.
- patient? string - If the granted SMART scopes include patient scopes (i.e. "patient/"), the access token is restricted to a specific patient. This field SHOULD be populated to identify the FHIR id of that patient.
health.fhir.cds: Link
Allows a service to suggest a link to an app that the user might want to run for additional information or to help guide a decision. https://cds-hooks.hl7.org/2.0/#link
Fields
- label string - Human-readable label to display for this link.
- url uri - URL to load (via GET, in a browser context) when a user clicks on this link. Note that this MAY be a "deep link" with context embedded in path segments, query parameters, or a hash.
- 'type LinkType - The type of the given URL. There are two possible values for this field. A type of absolute indicates that the URL is absolute and should be treated as-is. A type of smart indicates that the URL is a SMART app launch URL and the CDS Client should ensure the SMART app launch URL is populated with the appropriate SMART launch parameters.
- appContext? string - An optional field that allows the CDS Service to share information from the CDS card with a subsequently launched SMART app. The appContext field should only be valued if the link type is smart and is not valid for absolute links. The appContext field and value will be sent to the SMART app as part of the OAuth 2.0 access token response, alongside the other SMART launch parameters when the SMART app is launched.
health.fhir.cds: OrderDispatchContext
Describe the set of contextual data used by order-dispatch hook.
Fields
- patientId string - The FHIR Patient.id of the current patient in context.
- dispatchedOrders string[] - Collection of the FHIR local references for the Request resource(s) for which fulfillment is sought E.g. ServiceRequest/123
- performer string - The FHIR local reference for the Practitioner, PractitionerRole, Organization, CareTeam, etc. who is being asked to execute the order. E.g. Practitioner/456
- fulfillmentTasks? Task[] - DSTU2/STU3/R4/R5 - Collection of the Task instances (as objects) that provides a full description of the fulfillment request - including the timing and any constraints on fulfillment. If Tasks are provided, each will be for a separate order and SHALL reference one of the dispatched-orders.
health.fhir.cds: OrderSelectContext
Describe the set of contextual data used by order-select hook.
Fields
- userId string - The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole. For example, PractitionerRole/123 or Practitioner/abc.
- patientId string - The FHIR Patient.id of the current patient in context.
- encounterId? string - The FHIR Encounter.id of the current encounter in context.
- selections string[] - field description
- draftOrders Bundle - FHIR Bundle of DeviceRequest, MedicationRequest, NutritionOrder, ServiceRequest, VisionPrescription (typically with draft status).
health.fhir.cds: OrderSignContext
Describe the set of contextual data used by order-sign hook.
Fields
- userId string - The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole. For example, PractitionerRole/123 or Practitioner/abc.
- patientId string - The FHIR Patient.id of the current patient in context.
- encounterId? string - The FHIR Encounter.id of the current encounter in context.
- draftOrders Bundle - FHIR Bundle of DeviceRequest, MedicationRequest, NutritionOrder, ServiceRequest, VisionPrescription (typically with draft status).
health.fhir.cds: OverrideReason
A CDS Client can inform the service when a card was rejected by POSTing an outcome of overridden along with an overrideReason to the service's feedback endpoint. https://cds-hooks.hl7.org/2.0/#overridereason
Fields
- reason? Coding - The Coding object representing the override reason selected by the end user. Required if user selected an override reason from the list of reasons provided in the Card (instead of only leaving a userComment).
- userComment? string - The CDS Client may enable the clinician to further explain why the card was rejected with free text. That user comment may be communicated to the CDS Service as a userComment
health.fhir.cds: PatientViewContext
Describe the set of contextual data used by patient-view hook.
Fields
- userId string - The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole. For example, PractitionerRole/123 or Practitioner/abc.
- patientId string - The FHIR Patient.id of the current patient in context.
- encounterId? string - The FHIR Encounter.id of the current encounter in context.
health.fhir.cds: Services
The response to the discovery endpoint SHALL be an object containing a list of CDS Services. https://cds-hooks.hl7.org/2.0/#response
Fields
- services CdsService[] - Array of CDS hooks.
health.fhir.cds: Source
Grouping structure for the Source of the information displayed on this card. The source should be the primary source of guidance for the decision support the card represents. https://cds-hooks.hl7.org/2.0/#source
Fields
- label string - A short, human-readable label to display for the source of the information displayed on this card. If a url is also specified, this MAY be the text for the hyperlink.
- url? uri - An optional absolute URL to load (via GET, in a browser context) when a user clicks on this link to learn more about the organization or data set that provided the information on this card.
- icon? string - An absolute URL to an icon for the source of this card.
- topic? Coding - A topic describes the content of the card by providing a high-level categorization that can be useful for filtering, searching or ordered display of related cards in the CDS client's UI.
health.fhir.cds: Suggestion
Allows a service to suggest a set of changes in the context of the current activity (e.g. changing the dose of a medication currently being prescribed, for the order-sign activity). https://cds-hooks.hl7.org/2.0/#suggestion
Fields
- label string - Human-readable label to display for this suggestion.
- uuid? string - Unique identifier, used for auditing and logging suggestions.
- isRecommended? boolean - When there are multiple suggestions, allows a service to indicate that a specific suggestion is recommended from all the available suggestions on the card.
- actions? Action[] - Array of objects, each defining a suggested action. Within a suggestion, all actions are logically AND'd together, such that a user selecting a suggestion selects all of the actions within it.
Errors
health.fhir.cds: CdsError
CDS error type
Union types
health.fhir.cds: Context
Context
Describe the set of contextual data used by this hook. Only data logically and necessarily associated with the purpose of this hook should be represented in context.