CDS Hooks

EncounterDischargeContext

Bases: BaseHookContext

Workflow: This hook is triggered during the discharge process for typically inpatient encounters. It can be invoked at any point from the start to the end of the discharge process. The purpose is to allow hook services to intervene in various aspects of the discharge decision. This includes verifying discharge medications, ensuring continuity of care planning, and verifying necessary documentation for discharge processing.

ATTRIBUTE	DESCRIPTION
userId	REQUIRED. The ID of the current user, expected to be a Practitioner or PractitionerRole. For example, 'Practitioner/123'. TYPE: str
patientId	REQUIRED. The FHIR Patient.id of the patient being discharged. TYPE: str
encounterId	REQUIRED. The FHIR Encounter.id of the encounter being ended. TYPE: str

Documentation: https://cds-hooks.org/hooks/encounter-discharge/

Source code in healthchain/models/hooks/encounterdischarge.py

class EncounterDischargeContext(BaseHookContext):
    """
    Workflow:
    This hook is triggered during the discharge process for typically inpatient encounters. It can be invoked
    at any point from the start to the end of the discharge process. The purpose is to allow hook services to
    intervene in various aspects of the discharge decision. This includes verifying discharge medications,
    ensuring continuity of care planning, and verifying necessary documentation for discharge processing.

    Attributes:
        userId (str): REQUIRED. The ID of the current user, expected to be a Practitioner or PractitionerRole.
                      For example, 'Practitioner/123'.
        patientId (str): REQUIRED. The FHIR Patient.id of the patient being discharged.
        encounterId (str): REQUIRED. The FHIR Encounter.id of the encounter being ended.

    Documentation: https://cds-hooks.org/hooks/encounter-discharge/
    """

    userId: str = Field(
        default_factory=id_generator.generate_random_user_id,
        pattern=r"^(Practitioner|PractitionerRole)/[^\s]+$",
        description="The ID of the current user, expected to be in the format 'Practitioner/123'.",
    )
    patientId: str = Field(
        default_factory=id_generator.generate_random_patient_id,
        description="The FHIR Patient.id of the patient being discharged.",
    )
    encounterId: str = Field(
        default_factory=id_generator.generate_random_encounter_id,
        description="The FHIR Encounter.id of the encounter being ended.",
    )

    @model_validator(mode="before")
    @classmethod
    def check_unexpected_keys(cls, values):
        allowed_keys = {"userId", "patientId", "encounterId"}
        unexpected_keys = set(values) - allowed_keys
        if unexpected_keys:
            raise ValueError(f"Unexpected keys provided: {unexpected_keys}")
        return values

OrderSelectContext

Bases: BaseHookContext

Workflow: The order-select hook occurs after the clinician selects the order and before signing. This hook occurs when a clinician initially selects one or more new orders from a list of potential orders for a specific patient (including orders for medications, procedures, labs and other orders). The newly selected order defines that medication, procedure, lab, etc, but may or may not define the additional details necessary to finalize the order.

ATTRIBUTE	DESCRIPTION
userId	REQUIRED. An identifier of the current user, in the format [ResourceType]/[id], where ResourceType is either 'Practitioner' or 'PractitionerRole'. Examples: 'PractitionerRole/123', 'Practitioner/abc'. TYPE: str
patientId	REQUIRED. The FHIR Patient.id representing the current patient in context. TYPE: str
encounterId	OPTIONAL. The FHIR Encounter.id representing the current encounter in context, if applicable. TYPE: Optional[str]
selections	REQUIRED. A list of the FHIR id(s) of the newly selected orders, referencing resources in the draftOrders Bundle. Example: 'MedicationRequest/103'. TYPE: [str]
draftOrders	REQUIRED. A Bundle of FHIR request resources with a draft status, representing all unsigned orders from the current session, including newly selected orders. TYPE: object

Documentation: https://cds-hooks.org/hooks/order-select/

Source code in healthchain/models/hooks/orderselect.py

class OrderSelectContext(BaseHookContext):
    """
    Workflow: The order-select hook occurs after the clinician selects the order and before signing.
    This hook occurs when a clinician initially selects one or more new orders from a list of
    potential orders for a specific patient (including orders for medications, procedures, labs
    and other orders). The newly selected order defines that medication, procedure, lab, etc,
    but may or may not define the additional details necessary to finalize the order.

    Attributes:
        userId (str): REQUIRED. An identifier of the current user, in the format [ResourceType]/[id],
                      where ResourceType is either 'Practitioner' or 'PractitionerRole'. Examples: 'PractitionerRole/123',
                      'Practitioner/abc'.
        patientId (str): REQUIRED. The FHIR Patient.id representing the current patient in context.
        encounterId (Optional[str]): OPTIONAL. The FHIR Encounter.id representing the current encounter in context,
                                     if applicable.
        selections ([str]): REQUIRED. A list of the FHIR id(s) of the newly selected orders, referencing resources
                            in the draftOrders Bundle. Example: 'MedicationRequest/103'.
        draftOrders (object): REQUIRED. A Bundle of FHIR request resources with a draft status, representing all unsigned
                              orders from the current session, including newly selected orders.

    Documentation: https://cds-hooks.org/hooks/order-select/
    """

    # TODO: validate selection and FHIR Bundle resource

    userId: str = Field(
        default_factory=id_generator.generate_random_user_id,
        pattern=r"^(Practitioner|PractitionerRole)/[^\s]+$",
        description="An identifier of the current user in the format [ResourceType]/[id].",
    )
    patientId: str = Field(
        default_factory=id_generator.generate_random_patient_id,
        description="The FHIR Patient.id representing the current patient in context.",
    )
    encounterId: Optional[str] = Field(
        default_factory=id_generator.generate_random_encounter_id,
        description="The FHIR Encounter.id of the current encounter, if applicable.",
    )
    selections: List[str] = Field(
        ..., description="A list of the FHIR ids of the newly selected orders."
    )
    draftOrders: Dict[str, Any] = Field(
        ..., description="A Bundle of FHIR request resources with a draft status."
    )

    @model_validator(mode="before")
    @classmethod
    def check_unexpected_keys(cls, values):
        allowed_keys = {
            "userId",
            "patientId",
            "encounterId",
            "selections",
            "draftOrders",
        }
        unexpected_keys = set(values) - allowed_keys
        if unexpected_keys:
            raise ValueError(f"Unexpected keys provided: {unexpected_keys}")
        return values

    @model_validator(mode="after")
    def validate_selections(self) -> Self:
        for selection in self.selections:
            if "/" not in selection:
                raise ValueError(
                    "Each selection must be a valid FHIR resource identifier in the format 'ResourceType/ResourceID'."
                )
        return self

OrderSignContext

Bases: BaseHookContext

Workflow: The order-sign hook is triggered when a clinician is ready to sign one or more orders for a patient. This includes orders for medications, procedures, labs, and other orders. It is one of the last workflow events before an order is promoted from a draft status. The context includes all order details such as dose, quantity, route, etc., even though the order is still in a draft status. This hook is also applicable for re-signing revised orders, which may have a status other than 'draft'. The hook replaces the medication-prescribe and order-review hooks.

ATTRIBUTE	DESCRIPTION
userId	REQUIRED. The ID of the current user, expected to be of type 'Practitioner' or 'PractitionerRole'. Examples include 'PractitionerRole/123' or 'Practitioner/abc'. TYPE: str
patientId	REQUIRED. The FHIR Patient.id representing the current patient in context. TYPE: str
encounterId	OPTIONAL. The FHIR Encounter.id of the current encounter in context. TYPE: Optional[str]
draftOrders	REQUIRED. A Bundle of FHIR request resources with a draft status, representing orders that aren't yet signed from the current ordering session. TYPE: dict

Documentation: https://cds-hooks.org/hooks/order-sign/

Source code in healthchain/models/hooks/ordersign.py

class OrderSignContext(BaseHookContext):
    """
    Workflow:
    The order-sign hook is triggered when a clinician is ready to sign one or more orders for a patient.
    This includes orders for medications, procedures, labs, and other orders. It is one of the last workflow
    events before an order is promoted from a draft status. The context includes all order details such as
    dose, quantity, route, etc., even though the order is still in a draft status. This hook is also applicable
    for re-signing revised orders, which may have a status other than 'draft'. The hook replaces the
    medication-prescribe and order-review hooks.

    Attributes:
        userId (str): REQUIRED. The ID of the current user, expected to be of type 'Practitioner' or 'PractitionerRole'.
                      Examples include 'PractitionerRole/123' or 'Practitioner/abc'.
        patientId (str): REQUIRED. The FHIR Patient.id representing the current patient in context.
        encounterId (Optional[str]): OPTIONAL. The FHIR Encounter.id of the current encounter in context.
        draftOrders (dict): REQUIRED. A Bundle of FHIR request resources with a draft status, representing orders that
                            aren't yet signed from the current ordering session.

    Documentation: https://cds-hooks.org/hooks/order-sign/
    """

    # TODO: validate draftOrders

    userId: str = Field(
        default_factory=id_generator.generate_random_user_id,
        pattern=r"^(Practitioner|PractitionerRole)/[^\s]+$",
        description="The ID of the current user in the format [ResourceType]/[id].",
    )
    patientId: str = Field(
        default_factory=id_generator.generate_random_patient_id,
        description="The FHIR Patient.id representing the current patient in context.",
    )
    encounterId: Optional[str] = Field(
        default_factory=id_generator.generate_random_encounter_id,
        description="The FHIR Encounter.id of the current encounter, if applicable.",
    )
    draftOrders: Dict[str, Any] = Field(
        ..., description="A Bundle of FHIR request resources with a draft status."
    )

    @model_validator(mode="before")
    @classmethod
    def check_unexpected_keys(cls, values):
        allowed_keys = {"userId", "patientId", "encounterId", "draftOrders"}
        unexpected_keys = set(values) - allowed_keys
        if unexpected_keys:
            raise ValueError(f"Unexpected keys provided: {unexpected_keys}")
        return values

PatientViewContext

Bases: BaseHookContext

Workflow: The user has just opened a patient's record; typically called only once at the beginning of a user's interaction with a specific patient's record.

ATTRIBUTE	DESCRIPTION
userId	An identifier of the current user, in the format [ResourceType]/[id], where ResourceType is one of 'Practitioner', 'PractitionerRole', 'Patient', or 'RelatedPerson'. Examples: 'Practitioner/abc', 'Patient/123'. TYPE: str
patientId	The FHIR Patient.id representing the current patient in context. TYPE: str
encounterId	The FHIR Encounter.id representing the current encounter in context, if applicable. This field is optional. TYPE: Optional[str]

Documentation: https://cds-hooks.org/hooks/patient-view/

Source code in healthchain/models/hooks/patientview.py

class PatientViewContext(BaseHookContext):
    """
    Workflow: The user has just opened a patient's record; typically called only once at the beginning of a user's
    interaction with a specific patient's record.

    Attributes:
        userId (str): An identifier of the current user, in the format [ResourceType]/[id],
                      where ResourceType is one of 'Practitioner', 'PractitionerRole', 'Patient',
                      or 'RelatedPerson'. Examples: 'Practitioner/abc', 'Patient/123'.
        patientId (str): The FHIR Patient.id representing the current patient in context.
        encounterId (Optional[str]): The FHIR Encounter.id representing the current encounter in context,
                                     if applicable. This field is optional.

    Documentation: https://cds-hooks.org/hooks/patient-view/
    """

    # TODO: more comprehensive validator? for now regex should suffice

    userId: str = Field(
        default_factory=id_generator.generate_random_user_id,
        pattern=r"^(Practitioner|PractitionerRole|Patient|RelatedPerson)/[^\s]+$",
        description="The ID of the current user, expected to be in the format 'Practitioner/123'.",
    )
    patientId: str = Field(
        default_factory=id_generator.generate_random_patient_id,
        description="The FHIR Patient.id of the patient.",
    )
    encounterId: Optional[str] = Field(
        None, description="The FHIR Encounter.id of the encounter, if applicable."
    )

    @model_validator(mode="before")
    @classmethod
    def check_unexpected_keys(cls, values):
        allowed_keys = {"userId", "patientId", "encounterId"}
        unexpected_keys = set(values) - allowed_keys
        if unexpected_keys:
            raise ValueError(f"Unexpected keys provided: {unexpected_keys}")
        return values

https://cds-hooks.org/specification/current/#discovery

CDSService

Bases: BaseModel

A model representing a CDS service configuration.

ATTRIBUTE	DESCRIPTION
hook	The hook this service should be invoked on. This should correspond to one of the predefined hooks. TYPE: str
title	The human-friendly name of this service. It is recommended to provide this for better usability. TYPE: Optional[str]
description	A detailed description of what this service does and its purpose within the CDS framework. TYPE: str
id	The unique identifier of this service. It forms part of the URL as {baseUrl}/cds-services/{id}. TYPE: str
prefetch	Optional FHIR queries that the service requests the CDS Client to perform and provide on each service call. Keys describe the type of data and values are the actual FHIR query strings. TYPE: Optional[Dict[str, str]]
usageRequirements	Human-friendly description of any preconditions for the use of this CDS service. TYPE: Optional[str]

Documentation: https://cds-hooks.org/specification/current/#response

Source code in healthchain/models/responses/cdsdiscovery.py

class CDSService(BaseModel):
    """
    A model representing a CDS service configuration.

    Attributes:
        hook (str): The hook this service should be invoked on. This should correspond to one of the predefined hooks.
        title (Optional[str]): The human-friendly name of this service. It is recommended to provide this for better usability.
        description (str): A detailed description of what this service does and its purpose within the CDS framework.
        id (str): The unique identifier of this service. It forms part of the URL as {baseUrl}/cds-services/{id}.
        prefetch (Optional[Dict[str, str]]): Optional FHIR queries that the service requests the CDS Client to perform
                                            and provide on each service call. Keys describe the type of data and values are the actual FHIR query strings.
        usageRequirements (Optional[str]): Human-friendly description of any preconditions for the use of this CDS service.

    Documentation: https://cds-hooks.org/specification/current/#response
    """

    hook: str
    description: str
    id: str
    title: Optional[str] = None
    prefetch: Optional[Dict[str, Any]] = None
    usageRequirements: Optional[str] = None

CDSServiceInformation

Bases: BaseModel

A CDS Service is discoverable via a stable endpoint by CDS Clients. The Discovery endpoint includes information such as a description of the CDS Service, when it should be invoked, and any data that is requested to be prefetched.

Source code in healthchain/models/responses/cdsdiscovery.py

class CDSServiceInformation(BaseModel):
    """
    A CDS Service is discoverable via a stable endpoint by CDS Clients. The Discovery endpoint includes information such as a
    description of the CDS Service, when it should be invoked, and any data that is requested to be prefetched.
    """

    services: List[CDSService] = []

This is not compulsary

https://cds-hooks.org/specification/current/#feedback

CDSFeedback

Bases: BaseModel

A feedback endpoint enables suggestion tracking & analytics. A CDS Service MAY support a feedback endpoint; a CDS Client SHOULD be capable of sending feedback.

ATTRIBUTE	DESCRIPTION
card	The card.uuid from the CDS Hooks response. Uniquely identifies the card. TYPE: str
outcome	The outcome of the action, either 'accepted' or 'overridden'. TYPE: str
acceptedSuggestions	An array of accepted suggestions, required if the outcome is 'accepted'. TYPE: List[AcceptedSuggestion]
overrideReason	The reason for overriding, including any coding and comments. TYPE: Optional[OverrideReason]
outcomeTimestamp	The ISO8601 timestamp of when the action was taken on the card. TYPE: datetime

Documentation: https://cds-hooks.org/specification/current/#feedback

Source code in healthchain/models/responses/cdsfeedback.py

class CDSFeedback(BaseModel):
    """
    A feedback endpoint enables suggestion tracking & analytics.
    A CDS Service MAY support a feedback endpoint; a CDS Client SHOULD be capable of sending feedback.

    Attributes:
        card (str): The card.uuid from the CDS Hooks response. Uniquely identifies the card.
        outcome (str): The outcome of the action, either 'accepted' or 'overridden'.
        acceptedSuggestions (List[AcceptedSuggestion]): An array of accepted suggestions, required if the outcome is 'accepted'.
        overrideReason (Optional[OverrideReason]): The reason for overriding, including any coding and comments.
        outcomeTimestamp (datetime): The ISO8601 timestamp of when the action was taken on the card.

    Documentation: https://cds-hooks.org/specification/current/#feedback
    """

    card: str
    outcome: OutcomeEnum
    outcomeTimestamp: str
    acceptedSuggestion: Optional[Dict[str, Any]] = None
    overriddeReason: Optional[OverrideReason] = None