minimal Common Oncology Data Elements (mCODE) Implementation Guide
2.1.0 - Pre-STU 3 Development United States of America flag

minimal Common Oncology Data Elements (mCODE) Implementation Guide, published by HL7 International Clinical Interoperability Council. This is not an authorized publication; it is the continuous build for version 2.1.0). This version is based on the current content of https://github.com/HL7/fhir-mCODE-ig/ and changes regularly. See the Directory of published versions

Identifying In-Scope Patients

To facilitate conformance testing, testing software must be able to determine which patients are “in-scope” (meaning cancer patients whose data is presented or exchanged with the intention of conforming to mCODE). In FHIR terms, these are patients who have a Condition where Condition.code is a member of the value set PrimaryCancerDisorderVS and Condition.verificationStatus is confirmed.

However, due to technical, organizational, or legal reasons, mCODE Data Senders MAY exclude some cancer patients from mCODE. In that case, the mCODE Data Sender MUST define a Group resource to identify ALL in-scope patients in their system. This Group resource MUST set Group.code to C19700 with code system http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl (this is the NCI code for concept “Cancer Patient”). Data Senders that do not exclude any cancer patients from mCODE MAY still populate a Group resource.

All mCODE Data Senders MUST respond to GET [base]/Group?code=C19700 with either zero or one Group resource. If no Group resource is returned, all patients with cancer diagnoses (as defined above) will be considered to be in-scope. If a Group resource is returned, patients not referenced in the Group resource are assumed to be out of scope, independent of any cancer diagnosis. This requirement is reflected in ALL CapabilityStatements referenced in this section.

The following CapabilityStatements define the various methods participants can use to identify in-scope Patients. Participants implementing a pull architecture MUST support at least one of the CapabilityStatements listed from most to least preferable, below.

Patients-in-Group Approach

In this approach, Senders respond to the following request with a Group resource referencing the Patient resources for all in-scope Patients, AND allow the Receiver to retrieve a Bundle of the Patient resources referenced in the first response using composite search parameters:

GET [base]/Group?code=C19700

GET [base]/Patient?_id=some_patient_id_1,some_patient_id_2,...,some_patient_id_n

CapabilityStatements:

Identifying mCODE Patients: Patients-in-group approachmCODE Data ReceivermCODE Data SenderGet Patients via_profileGET [base]/Group/mcode-patientsHTTP response containing Group referencing relevant PatientsReceiver extracts referencesto Patients from Group togenerate a second request:GET [base]/Patient?_id=id_1,id_2,...,id_nHTTP response containing Bundle of Patients

Patients-With-Cancer-Condition Approach

In this approach, Senders respond to the following request with a FHIR Bundle of Patient resources for all in-scope Patients. This method is preferred over the approaches below UNLESS reverse chaining is entirely unsupported on the system.

GET [base]/Patient?_has:Condition:subject:code:in=http://hl7.org/fhir/us/mcode/ValueSet/mcode-primary-or-uncertain-behavior-cancer-disorder-vs

Capability Statements:

Identifying mCODE Patients: Patients-with-cancer-condition approachmCODE Data ReceivermCODE Data SenderGet Patients via reverse chainingGET [base]/Patient?_has:Condition:subject:code:in=...HTTP response containing Bundle of relevant Patients

Patient-Then-Cancer-Conditions Approach

In this approach, Senders can respond to a request using _include to get a Bundle of the relevant Patient resources along with the subset of Condition resources with Condition.code in Primary Cancer Disorder Value Set in a single request. Preferred over the approach below UNLESS _include is entirely unsupported on the system.

GET [base]/Condition?code:in=http://hl7.org/fhir/us/mcode/ValueSet/mcode-primary-or-uncertain-behavior-cancer-disorder-vs&_include=Condition:subject

Capability Statements:

Identifying mCODE Patients: Patients-and-cancer-conditions approachmCODE Data ReceivermCODE Data SenderGet Patients via reverse chainingGET [base]/Condition?_has:Condition:subject:code:in=...HTTP response containing Bundle of relevant Patients

Conditions-Then-Patients Approach

In this approach, Senders return a Bundle with the subset of Condition resources with a code in the Primary Cancer Disorder Value Set in a single request, AND allow the Receiver to retrieve a Bundle of the Patient resources referenced in the first response using composite search parameters:

GET [base]/Condition?code:in=http://hl7.org/fhir/us/mcode/ValueSet/mcode-primary-or-uncertain-behavior-cancer-disorder-vs

GET [base]/Patient?_id=some_patient_id_1,some_patient_id_2,...,some_patient_id_n

Capability Statements:

Identifying mCODE Patients: Conditions-then-patients approachmCODE Data ReceivermCODE Data SenderGet Conditions, then PatientsGET [base]/Condition?code:in=...HTTP response containing Bundle of relevant ConditionsReceiver extracts uniquepatient IDs from Conditions togenerate a second request:GET [base]/Patient?_id=id_1,id_2,...,id_nHTTP response containing Bundle of Patients