⚠️ This is a developmental version of the guide and is under active development. Content may change at any time without notice. No official release has been made. The final base canonical URL and hosting location have not yet been determined. This guide should not be used for production implementations.

2.2. Provider-initiated Trial Matching for an Individual Patient – CDS Hooks-Based Trial Matching Workflow

2.2.1. Overview

In the Provider-initiated Scenario, a Provider System invokes a CTM Service using the CDS Hooks specification to request clinical trial matching support for an individual patient currently under provider review in the context of a clinical workflow. The CTM Service evaluates the available patient data and returns a CDS Hooks response containing one or more cards that communicate potential trial matches, informational messages, or warnings.

The Provider-initiated Scenario is intended to support near-real-time clinical trial matching within provider workflow while keeping the initial implementation simple and interoperable.

2.2.2. Scope

This scenario is limited to provider-initiated trial matching for a single, identified patient in the context of a provider workflow.

This scenario defines:

• The CDS Hooks invocation context for a provider requesting trial matching for an individual patient
• The recommended USCDI+ CTM V1 baseline data set for The Provider-initiated Scenario
• The expected exchange of CTM-relevant data elements
• The use of standard CDS Hooks cards as the response mechanism

This scenario does not define:

• Trial matching logic
• Trial ranking or prioritization
• NLP or machine learning methods
• A standardized structured representation of trial match results beyond standard CDS Hooks cards
• Population-level, cohort-level, or patient-initiated trial search workflows

2.2.3. Actors

• Provider User — views an individual patient’s chart and triggers trial matching workflow for that patient
• Provider System / CDS Client — sends the CDS Hooks request and supplies CTM-relevant prefetch data
• CTM Matching Service / CDS Service — receives the request, evaluates CTM-relevant data, and returns cards

2.2.4. The Provider-initiated Scenario: CDS Hooks-Based Trial Matching Workflow

1. A Provider User opens a patient chart or otherwise initiates a trial matching action within the Provider System.
2. The Provider System discovers available CDS services through the CDS Hooks discovery endpoint at {baseURL}/cds-services.
3. The CTM Service returns available CDS service definitions, which may include example metadata such as service id, hook, and prefetch templates.
4. The Provider System sends a CDS Hooks request to the CTM Service endpoint at /cds-services/{serviceId}.
5. The request includes hook metadata, patient context, and prefetch data containing relevant clinical content.
6. The CTM Service validates the request and performs implementation-specific processing.
7. The CTM Service returns a CDS Hooks response containing cards.
8. The Provider System renders those cards for provider review and potential follow-up action.

2.2.5. CDS Hooks Discovery Endpoint

Prior to invoking a CTM CDS Hooks service, the Provider System discovers available CDS services through the CDS Hooks discovery endpoint located at {baseURL}/cds-services.

The CTM Matching Service SHALL expose a CDS Hooks discovery endpoint so Provider Systems can know which services are available and how to invoke them.

• The CTM service SHALL respond to GET {baseUrl}/cds-services with the list of CDS services it offers, as defined by the CDS Hooks discovery specification.
• Each advertised CTM service SHALL include its hook, id, and a human-readable description, and SHOULD include a title.
• Each CTM service SHOULD advertise the prefetch templates it expects, so Provider Systems know which CTM-relevant data to supply (see Prefetch Model).
• A Provider System SHALL invoke the service at POST {baseUrl}/cds-services/{id} using the id obtained from discovery.

Discovery lets the prefetch templates documented in this guide be communicated by the service itself, keeping the Provider System and CTM Matching Service aligned on the expected CTM-relevant data.

2.2.6. Recommended Hook

The recommended hook is patient-view.

The patient-view hook is invoked when a user opens a patient record. Its standard context includes userId, patientId, and an optional encounterId. This aligns well with the CTM goal of surfacing trial matching information when a clinician is reviewing a patient chart.

2.2.7. Conformance Expectations

A Provider System implementing the Provider-initiated Scenario:

• SHALL invoke the CTM Matching Service using CDS Hooks
• SHOULD use the patient-view hook for USCDI+ CTM V1
• SHOULD supply CTM-relevant data using CDS Hooks prefetch when available and practical
• MAY include optional authorization context for follow-up FHIR queries
• SHALL NOT be required to perform CTM-specific decision logic

A CTM Matching Service implementing the Provider-initiated Scenario:

• SHALL accept a CDS Hooks request containing the agreed context and available CTM-relevant data
• SHALL process prefetch data when present
• SHALL handle incomplete or missing CTM-relevant data gracefully
• SHALL return a valid CDS Hooks response using standard CDS Hooks cards
• MAY perform additional FHIR retrieval only when valid authorization context is supplied

2.2.8. Required Request Elements

A USCDI+ CTM V1 Provider-initiated Scenario request SHALL include:

• hook
• hookInstance
• context.patientId
• context.userId

A USCDI+ CTM V1 Provider-initiated Scenario CDS Hooks request SHOULD include CTM-relevant data using one of the following approaches:

• CDS Hooks prefetch

A USCDI+ CTM V1 Provider-initiated Scenario CDS Hooks request MAY also include:

• context.encounterId
• fhirServer
• fhirAuthorization

2.2.9. Data Delivery in the Provider-initiated Scenario

The Provider-initiated Scenario is prefetch-recommended for USCDI+ CTM V1.

The preferred approach is for the Provider System to execute FHIR queries in advance and include the results using CDS Hooks prefetch. This aligns with standard CDS Hooks behavior and supports lower-latency implementations.

The transmitted data is intended to represent the USCDI+ CTM V1 baseline data elements defined by the USCDI+ CTM Data Mapping.

The examples below illustrate two complete CDS Hooks service definitions that advertise prefetch expectations through the CDS Hooks discovery endpoint. They are intended to show realistic implementation patterns. They are not mandatory, not exhaustive, and not the only valid way to structure CTM prefetch.

Implementations may use fewer keys, different key names, or more specific query patterns, provided the exchanged data remains aligned with the profiles, terminologies, and cardinalities defined in the USCDI+ CTM Data Mapping.

For the supported FHIR resource types, expected profiles, and related search parameters, see the CTM Provider FHIR Server CapabilityStatement.

More specific queries may improve performance and reduce unnecessary data exchange. Where a CTM service needs additional or narrower data after the hook request, the service may use CDS Hooks authorization-token-based FHIR resource access within the authorized scope and dataset boundaries supported by this guide.

2.2.9.1. Minimal Prefetch Template Example

Use a minimal prefetch template like the following example when an implementation wants a lightweight first-pass workflow. This pattern is appropriate when the CTM service only needs core patient demographic context up front and will either return a limited result or request additional in-scope data later through authorized FHIR access when available.

{
  "services": [
    {
      "hook": "patient-view",
      "id": "ctm-demographics-screen",
      "title": "CTM Demographics Screen",
      "description": "Lightweight provider-initiated CTM service for initial screening using patient demographic context.",
      "prefetch": {
        "patient": "Patient/{{context.patientId}}"
      }
    }
  ]
}

2.2.9.2. Example Prefetch Template

Use more extensive prefetch data like the example below when an implementation wants the Provider System to supply a broader but still targeted set of CTM-relevant data during the initial hook request. This pattern is appropriate when the CTM service expects to screen for potential trial matches in one round-trip without relying on broad, unfiltered history retrieval.

{
  "services": [
    {
      "hook": "patient-view",
      "id": "ctm-trial-screen-detailed",
      "title": "CTM Trial Screening Service",
      "description": "Provider-initiated CTM service that screens an individual patient using targeted CTM-relevant data.",
      "prefetch": {
        "patient": "Patient/{{context.patientId}}",
        "conditions-cancer-B-cell-acute-lymphoblastic-leukemia": "Condition?patient={{context.patientId}}&category=http://terminology.hl7.org/CodeSystem/condition-category|problem-list-item&code=http://snomed.info/sct|277571004",
        "observations-performance": "Observation?patient={{context.patientId}}&code=http://loinc.org|89247-1,http://loinc.org|89243-0,http://loinc.org|89246-3",
        "observations-smoking": "Observation?patient={{context.patientId}}&code=http://loinc.org|72166-2",
        "observations-laboratory": "Observation?patient={{context.patientId}}&category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory",
        "observations-pregnancy-status": "Observation?patient={{context.patientId}}&code=http://loinc.org|82810-3",
        "observations-comorbidities": "Observation?patient={{context.patientId}}&code=http://snomed.info/sct|398192003",
        "observations-stage-group": "Observation?patient={{context.patientId}}&code=http://loinc.org|21908-9,http://loinc.org|21902-2,http://loinc.org|21914-7",
        "observations-tnm-t": "Observation?patient={{context.patientId}}&code=http://loinc.org|21905-5,http://loinc.org|21899-0,http://loinc.org|21911-3",
        "observations-tnm-n": "Observation?patient={{context.patientId}}&code=http://loinc.org|21906-3,http://loinc.org|21900-6,http://loinc.org|21912-1",
        "observations-tnm-m": "Observation?patient={{context.patientId}}&code=http://loinc.org|21907-1,http://loinc.org|21901-4,http://loinc.org|21913-9",
        "medication-administrations-oncology-cyclophosphamide": "MedicationAdministration?patient={{context.patientId}}&code=http://www.nlm.nih.gov/research/umls/rxnorm|3002&_include=MedicationAdministration:medication",
        "procedures-radiotherapy": "Procedure?patient={{context.patientId}}&code=http://snomed.info/sct|1217123003",
        "procedures-defib-implant": "Procedure?patient={{context.patientId}}&code=http://www.ama-assn.org/go/cpt|33249"
      }
    }
  ]
}

The exact key names above are illustrative. Implementations MAY use different prefetch key names, but the CTM Matching Service and Provider System SHOULD document the keys they support.

2.2.10. Additional Data Retrieval

If the prefetched content is not sufficient for a particular CTM service, the CTM service may use CDS Hooks authorization-token-based FHIR resource access to request additional data after the hook request. Any such follow-up retrieval should remain within the authorized scope and within the dataset boundaries supported by this guide. See CDS Hooks Guidance for FHIR Resource Access.

This additional retrieval mechanism is optional. Implementations are encouraged to use prefetch for the baseline CTM-relevant content and reserve follow-up FHIR access for cases where additional detail is needed.

2.2.11. Data and Profile Expectations

For each CTM data element included in prefetch:

• The Provider system SHALL send the mapped FHIR resource and element
• The Provider system SHALL preserve the mapped terminology and expected cardinality
• The Provider system SHOULD use the CTM preferred profile when available
• The Provider system MAY use the mapped alternative profile(s) when the preferred profile is not available, provided the semantics remain equivalent

The baseline resource set is outlined in the Capability Statement page.

2.2.12. Response Requirements

The CTM Matching Service SHALL return a standard CDS Hooks response with one or more cards. Guidance and examples for CDS Hooks cards are provided in the IG: CDS Hooks Card Guidance for USCDI+ CTM.

For the Provider-initiated Scenario:

• Cards are the standard output mechanism
• The IG does not need to standardize a structured trial-match payload beyond standard CDS Hooks cards
• Any additional links or actions in cards remain implementation specific unless separately constrained

2.2.13. Missing Data Guidance

The Provider-initiated Scenario SHALL treat missing data as missing, not as a negative clinical assertion.

• If a prefetch key is omitted, the CTM Matching Service SHALL interpret that as not supplied rather than not present in the patient record.
• If a prefetched resource is present but a mapped element is absent, the CTM Matching Service SHOULD treat the element as unknown / unavailable unless the data itself explicitly conveys a negated value.
• If the available data is not sufficient to complete full matching, the CTM Matching Service MAY still return an informational or warning card and SHOULD indicate that the evaluation is limited by incomplete data.
• The Provider system is not required to prove completeness of the prefetch payload.