Pathway Data Model

(For the most up-to-date definitions of the data model, see /src/types/pathways-model.d.ts)

Pathway

A Pathway is represented as a directed acyclic graph (DAG) comprised of states and transitions between those states.

• name: string - the simple name of the pathway; should be unique and meaningful
• description: string - human readable description of the pathway
• library: string - the name of a CQL library that this pathway references. In most cases this will likely be the mCODE_Libray.cql
• criteria: list<Criteria> - list of prerequisite criteria that a patient should have, in terms of mCODE data, in order for the current pathway to be applicable
• states : object - named key/value pairs of State objects

Criteria

• elementName: string - friendly name of the mCODE element in question
• expected: string - friendly name of the expected value for the patient to have
• cql: string - CQL string to fetch data from the patient, must return a tuple with 2 fields:
  • value - the actual value from the patient
  • match - boolean flag indicating whether value is a match for expected. (i.e, there will be many instances where equivalence is more broad than equality. The CQL should check for code matching within hierarchies, among other things)

State

State is abstract - all instances must either be Guidance states or Branch states.

• label: string - the title of the State, a short description of what this state represents. This should always be visible in the UI, even if the node is collapsed.
• transitions: list<Transition> - list of transitions out from this state. Branch states will always have multiple options, Guidance states may have a single option, or multiple options representing a "choice" - i.e., the pathway guidance allows for either option but the final decision is left to the clinician

Guidance State

A Guidance state represents actions within the pathway which the oncologist may accept or decline, such as procedures, prescriptions, etc.

A guidance state will transition out to one or more states, where during execution only one path will be chosen. If multiple transitions are provided, these represent "treatment options" within the pathway where the choice is left up to the user.

• action: list<Action> : list of all actions involved with this guidance. For example a drug regimen may contain multiple MedicationRequests, etc. The intent of these is that there is no inherent sequence necessary and all may be initiated in parallel. All of these actions must be represented in the cql such that the state is identified as complete if and only if all the actions within the state have been completed.
• cql: string - a CQL snippet which will produce a Documentation Resource pointing to the relevant FHIR resource(s) that this action creates. For instance if the state represents a procedure to be performed, this CQL will fetch and return the corresponding Procedure FHIR resource.

Action

(inspired by CDS Hooks -- see https://cds-hooks.org/specification/1.0/#action)

• type: string - "create" or "update"
• description: string - human readable description of what the action represents
• resource: object - template FHIR resource(s) to be added to or updated on the patient record

Branch State

A Branch state represents a "fork in the road" where the flow of the module is directed by some logical condition. A branch state will transition out to two or more states, where during execution only one path will be chosen.

Transition

• transition: string - the key of the state to transition to
• condition: object? - (optional: only transitions from branch states will have conditions)
  • description: string - human readable description of the condition that would lead to this transition being taken
  • cql: string - CQL snippet that returns a Documentation Resource pointing to documentation of the given query, if this transition should be taken. (for example, if the transition should be taken for patients with tumor marker of HER2+, the CQL should return the TumorMarkerTest Observation for documentation)

Documentation Resource

The impetus for the documentation resource is that the CQL execution engine does not work with raw FHIR but with FHIR-like models, and as such does not return raw FHIR from queries. The idea here is that instead of trying to rebuild the FHIR using a complex CQL query, we will instead just query enough information to re-fetch the relevant FHIR if necessary. (ex, the resourceType and ID)

• resourceType: string - The resourceType of the FHIR resource that was returned (ex, Procedure, MedicationRequest, etc)
• id: string - The id field from the FHIR resource that was returned, to allow for a query to fetch the full resource.
• status: string - Status code from the FHIR resource. (TODO: there may need to be some processing on this)
• state: string - Name of the state for which this resource was fetched

Criteria Evaluation Results

• elementName: string - friendly name of the mCODE element
• expected: string - friendly human readable description of the expected value
• actual: string - result from the patient's record indicating the actual value of the selected mCODE element
• match: boolean - whether or not expected matches actual. Note that in most cases strict string/number equality checking is insufficient

Pathway Evaluation Results

• patientId: string - identifier for the patient (ie, the id field from the Patient FHIR resource)
• currentState: string - the current state along the pathway that the patient is in
• currentStatus: string - the status of the current state, derived from the FHIR status. For example if the current state represents a medication regimen, the status may be in-progress, etc.
• nextRecommendation: (string | object) -
• documentation: list<(Documentation Resource | string)> -
• path: list<string> - the sequence of state names indicating the path the patient has taken so far through the pathway