Domain Specific Language (DSLs)

Owned by David Shields
Last updated: Jul 22, 2016
4 min read

We use DSLs to enable writing rules for all of the following reasons:

  • to create pre-validated constructions of re-usable logic
  • to use logical language more familiar to medical informaticists
  • to reference clinical data constructed as a virtual medical record (vMR)
  • to hide some of the syntactic complexity of Drools

There are 39 DSLs used in this URI example, and they fall into several groups, as follows:

DSLs that create and reference intermediate results

We call these intermediate results "Assertions" and they exist in two forms:

  • Internal Data Model as a class named "Assertion" defined as a String, which can be added to a fact list and used for logical inferencing within Drools.  Note that the same Assertion may exist in working memory multiple times

  • Drools Global named "assertions", which is a java HashSet<String> that can be have values added or referenced within Drools, but changes to it will not trigger rules to fire.  However, it can be referenced outside of Drools, both in the jBPM processes, and by OpenCDS at the end of a stateless Drools session.  We use "assertions" both to create intermediate results that we can pass to subsequent steps in a process, and for debugging, since globals continue to exist once control is passed from Drools back to OpenCDS.  Note that there will be no duplicates among the members of the assertions global.

All of our DSLs that create "Assertions" on the RHS of a rule always create both forms of "Assertions", so that it can both trigger logical inferencing, and be seen outside of Drools.  On the other hand, DSLs that reference "Assertions" in the LHS of a rule always reference the class "Assertion", because that is the form that triggers inferencing in Drools. 

DSLs for the LHS include:

  • Assertion.Exists - references that an Assertion containing an enumerated concept code exists in Drools working memory

  • Assertion.Not.Exists - references that a particular Assertion containing an enumerated concept code does not exist in Drools working memory

  • Assertion.String.Exists - references that an Assertion containing a simple string exists in Drools working memory

DSLs for the RHS include:

  • Assert - creates a string using an enumerated concept code, for standardized assertions, e.g., "C3390" which is enumerated in the OpenCDS Apelon instance as "QM HEDIS-FPC 81-100 Percent"
  • Assert.NamedDate - creates a string of a name value pair, separated by an equal-sign, e.g., "importantDate=20140704", which might be useful for debugging
  • Assert.String - allows you to specify a simple string, e.g."ruleABCfired", or "patientNeedsHbA1cTest"

 

DSLs that control the Concept Determination Methods that you want to use in this Knowledge Module

These DSLs are always used in pairs, and serve to constrain the valuesets (aka mapping files) used to map actual data to the concepts used to write the rules.

  • Concept.Det.Clin.Stmt.Identify - LHS, e.g., "Concept for ClinicalStatement is not determined according to [HEDIS 2014]"
  • Concept.Det.Clin.Stmt.Remove - RHS, e.g., "Remove ClinicalStatement concept without desired concept determination method"
  • Concept.Det.Entity.Identify - LHS
  • Concept.Det.Entity.Remove - RHS
  • Concept.Det.Rship.Identify - LHS
  • Concept.Det.Rship.Remove - RHS

 

DSLs that select patient demographics of interest to this Knowledge Module

These particular DSLs are for the LHS side of a rule, and typically would have an assertion on the RHS, which can then be used to control further steps performed during the execution of the Knowledge Module

  • Dem.Age.Time - one or two instances of this DSL may be used to constrain an age range for the patient
  • Missing.DOB - this is used to determine if the data is bad, and the Knowledge Module should be aborted

 

DSLs that select encounters of interest to this Knowledge Module

 

  • Enc.From.NamedList.After.Med.SubDispense.Count.Id
  • Enc.From.NamedList.After.Med.SubDispense.DaysSupply.Active.Count.Id
  • Enc.From.NamedList.Before.After.Enc.Rship.EncDx.Count.Id
  • Enc.From.NamedList.Rship.EncDx.Not.Multiple.Count.Id
  • Enc.Rship.EncDx.Between.Times.Count.Id
  • Enc.Rship.EncDx.Between.Times.Count.Id
  • Enc.Between.Times.Count.Id
  • Set.EncListId.Add.EncListRefs
  • Set.EncListId.EncListRefs.No.Time.Overlap

 

DSLs that select Medications of interest to this Knowledge Module

 

  • SubDispense.Med.Between.NamedDates.NoTimes


DSLs that create output structures for this Knowledge Module as ObservationResults in working memory

With one exception these DSLs all live in the RHS of a rule, and they create output structures, modeled as a vMR ObservationResult, and containing information that you want OpenCDS to return as the EvaluationResponse to an EvaluationRequest.  Since any new facts that are created within Drools go out of scope when you leave Drools, these DSLs make the output structures that they create available to OpenCDS by adding them to the global "namedObjects". OpenCDS will find them in namedObjects, and process them as output XML.

  • Out.Assertions - creates a list of all the "Assertions" found in working memory for debugging purposes
  • Out.Concepts.All.Read - LHS, used to locate all the OpenCDS Concepts in working memory to enable creating an output with Out.Concepts.All.Write
  • Out.Concepts.All.Write - RHS creates a single output ObservationResult containing a list of all the mapped OpenCDS Concepts that were found in the input data, for debugging purposes
  • Out.Nested.Obs.Num.Denom - creates an ObservationResult containing the actual findings/results of the KM
  • Out.Root.Obs.Focus.EvalpId - This is a wrapper ObservationResult that identifies the Knowledge Module that was executed and the ID of the patient involved.  It is intended to be used with another DSL, such as Out.Nested.Obs.Num.Denom which documents the detail findings of the KM

 

DSLs that initialize variables useful in individual rules

This DSL must be used as the first step in the LHS of all rules that use any other DSLs.  It initializes references for the evaluation time, the focal patient, and the evaluated person (which is same as the patient for this DSL) that can then be used in subsequent steps of the current rule..  Other versions of this DSL can be used to use the same rules to inference over the vMR constructions of "OtherEvaluatedPerson".  All other DSLs that reference vMR data expect the variables to be referenced, and most rules will not validate unless this DSL is the first one in the LHS of the rule.

  • Init.EvalTime.FpId.EvalpId

 

DSLs that create and inference on new generic facts in working memory

There are situations where it is useful to create new types of data that are not part of the vMR for new derivative facts that you want to insert into working memory, and/or into the global "namedObjects", and you need for them to have a name so that you can reference them later.  The new types of data are created as Declarative Data Model types, and the following DSLs create or reference instances of them.

  • Insert.EncListRef.As.NamedList
  • Insert.EncListRef.As.NamedList
  • Insert.NamedDate.After.NamedDate
  • Insert.NamedDate.From.Earliest.Enc.In.NamedList
  • NamedDate.Exists.Not.Null
  • NamedEnc.Exists.Not.Null
  • NamedList.Exists.EncListId
  • NamedList.Exists.Not.Empty