Common CQL Artifacts for FHIR (US-Based)
2.0.0-cibuild - Informative 2 - CI Build United States of America flag

Common CQL Artifacts for FHIR (US-Based), published by HL7 International / Clinical Decision Support. This guide is not an authorized publication; it is the continuous build for version 2.0.0-cibuild built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/us-cql-ig/ and changes regularly. See the Directory of published versions

Claim Patterns

Page standards status: Informative

Claim data in FHIR is represented with the Claim and ExplanationOfBenefit resources.

The Claim resource represents a claim for a product or service provided from the provider perspective, whereas the ExplanationOfBenefit resource represents an adjudicated claim from the payer perspective.

NOTE: US Core does not define profiles for either of these resources. QI-Core defines a Claim profile to represent the claim for a service from the provider perspective, and CARIN BlueButton defines ExplanationOfBenefit profiles to represent adjudicated claims from the payer perspective. The content here treats these resources from the base FHIR perspective.

Modifier Elements

The Claim resource defines the following modifier elements:

  • status

The ExplanationOfBenefit resource defines the following modifier elements:

  • status

In addition to being modifiers, the status elements of these resources are required with a required binding.

Search Parameters

The base FHIR specification defines multiple search parameters for both of these resources; feedback is sought on which of the defined search parameters are likely to be available.

NOTE: For discussion on how to manage search parameters with terminology, see the Terminology Considerations discussion in the Architectural Guidance topic.

NOTE: For discussion on how to manage optional search parameters, see the Performant Data Access discussion in the Architectural Guidance topic.

Cross-Version Considerations

Not applicable

Common Elements and Functions

Status, Use, and Type

define fluent function isProfessional(claim Claim):
  claim.type ~ "professional"

define fluent function isInstitutional(claim Claim):
  claim.type ~ "institutional"

define fluent function isActcive(claim Claim):
  claim.status = 'active'

define fluent function isClaim(claim Claim):
  claim.use = 'claim'

define fluent function isProfessional(eob ExplanationOfBenefit):
  claim.type ~ "professional"

define fluent function isInstitutional(eob ExplanationOfBenefit):
  claim.type ~ "institutional"

define fluent function isActcive(eob ExplanationOfBenefit):
  claim.status = 'active'

define fluent function isClaim(eob ExplanationOfBenefit):
  claim.use = 'claim'

Principal Diagnosis

/*
@description: Returns the claim diagnosis elements for the given encounter
@comment: See the QICore 6 Authoring Patterns discussion on [Principal Diagnosis and Present on Admission](https://github.com/cqframework/CQL-Formatting-and-Usage-Wiki/wiki/Authoring-Patterns-QICore-v6.0.0#conditions-present-on-admission-and-principal-diagnoses) for more information
*/
define fluent function claimDiagnosis(encounter Encounter):
  encounter E
    let 
      claim: ([Claim] C where C.status = 'active' and C.use = 'claim' and exists (C.item I where I.encounter.references(E))),
      claimItem: (claim.item I where I.encounter.references(E))
    return claim.diagnosis D where D.sequence in claimItem.diagnosisSequence

/*
@description: Returns the claim diagnosis element that is specified as the principal diagnosis for the encounter
 @comment: See the QICore 6 Authoring Patterns discussion on [Principal Diagnosis and Present on Admission](https://github.com/cqframework/CQL-Formatting-and-Usage-Wiki/wiki/Authoring-Patterns-QICore-v6.0.0#conditions-present-on-admission-and-principal-diagnoses) for more information
*/
define fluent function principalDiagnosis(encounter Encounter):
singleton from (
     (encounter.claimDiagnosis()) CD
       where CD.type.includesCode("Principal Diagnosis")
   )

/*
 @description: Returns the condition that is specified as the principal diagnosis for the encounter and has a code in the given valueSet.
 @comment: See the QICore 6 Authoring Patterns discussion on [Principal Diagnosis and Present on Admission](https://github.com/cqframework/CQL-Formatting-and-Usage-Wiki/wiki/Authoring-Patterns-QICore-v6.0.0#conditions-present-on-admission-and-principal-diagnoses) for more information
 */
 define fluent function hasPrincipalDiagnosisOf(encounter Encounter, valueSet ValueSet):
   (encounter.principalDiagnosis()) PD
     return PD.diagnosis in valueSet
       or PD.diagnosis.getCondition().code in valueSet

define "Encounter With Principal Diagnosis Of Asthma":
  [Encounter] E
    where E.hasPrincipalDiagnosisOf("Asthma")

Present On Admission

/*
 @description: Returns true if the given diagnosis is present on admission, based on the given poaValueSet
 @comment: See the QICore 6 Authoring Patterns discussion on [Principal Diagnosis and Present on Admission](https://github.com/cqframework/CQL-Formatting-and-Usage-Wiki/wiki/Authoring-Patterns-QICore-v6.0.0#conditions-present-on-admission-and-principal-diagnoses) for more information
 */
 define fluent function isDiagnosisPresentOnAdmission(encounter Encounter, diagnosisValueSet ValueSet, poaValueSet ValueSet):
   exists (
     (encounter.claimDiagnosis()) CD
       where CD.onAdmission in poaValueSet
         and (
           CD.diagnosis in diagnosisValueSet
             or CD.diagnosis.getCondition().code in diagnosisValueSet
         )
   )

define "Encounter With Asthma Present On Admission":
  [Encounter] E
    where E.isDiagnosisPresentOnAdmission("Asthma", "Present On Admission Indicators")

Principal Procedure

/*
@description: Returns the claim procedure elements for the given encounter
*/
define fluent function principalProcedure(encounter Encounter):  	  
  	 encounter E
  	 let 
        claim: [Claim] C where C.status = 'active' and C.use = 'claim' and exists (C.item I where I.encounter.references(E)),
        claimItem: claim.item I where I.encounter.references(E),
        princProcedure: singleton from (claim.procedure P where P.sequence in claimItem.procedureSequence and P.type.includesCode("Primary procedure"))
    return princProcedure

define fluent function hasPrincipalProcedureOf(encounter Encounter, procedureValueSet ValueSet):
   encounter E
   let
        PPx: E.principalProcedure(),
        CPx: singleton from ([Procedure] P where PPx.procedure.references(P.id))
     return PPx.procedure in procedureValueSet
       or CPx.code in procedureValueSet

define "Encounters With Principal Procedure of General Surgery":
  [Encounter] E
    where E.hasPrincipalProcedureOf("General Surgery")

Claim Items

define "Claim Item":
  [Claim] C
    where C.isActive()
      and C.isClaim()
      and (C.isInstitutional() or C.isProfessional())
    return C.item

EoB Items

define "EoB Item":
  [ExplanationOfBenefit] E
    where E.isActive()
      and E.isClaim()
      and (E.isInstitutional() or E.isProfessional())
    return E.item

Mammography Claim

define "Mammography Claim":
  "Claim Item" I
    where I.serviced.toInterval() during "Measurement Period"
      and I.productOrService in "Mammography"

define "Mammography EoB":
  "EoB Item" I
    where I.serviced.toInterval() during "Measurement Period"
      and I.productOrService in "Mammography"

NOTE: Content for this page was adapted from the QICore Authoring Patterns - topic as well as the Cooking with CQL Session 90 - Claim Diagnosis and Principal Procedure topic.