...
[Event] has happened
Pre [when] Patient has previously had a
{X:ENUM:<conceptType>.openCdsConceptCode} =
($x: <conceptType>(openCdsConceptCode == "{X}")
and <clinicalStatement>(id == $x.conceptTargetId, subjectIsFocalPerson == true, <clinicalStatementEventTime>.high <= $evalTime ))Definitions of elements in the above pattern:
$x should be expanded to a meaningful name,
<conceptType> represents the name of an OpenCDS Concept Type, such as “EncounterTypeConcept”<clinicalStatement> represents the name of an OpenCDS vMR clinical statement Type, such as “EncounterEvent”
<clinicalStatementEventTIme> represents the name of the relevant event time element in the particular clinical statement Type.
[Event] has happened at least {n} times
[Event] has happened in last {n} [timeUnits]
[Event] has happened at least {n1} times in last {n2} [timeUnits]
[Event] happened between {n1} and {n2} [timeUnits] ago
[Event] as tag {idTag}…
then uses all patterns shown above under Events in General
[Entity] has role {targetRole} to {clinicalStatementClass} identified as tag {idTag}
[Entity] has role {targetRole} to {clinicalStatementType} identified as tag {idTag} during {relationshipTimeInterval}
[Event] is {targetRelationshipToSource} of {clinicalStatementClass} identified as tag {idTag}…
then uses all patterns shown above under Events in General
Entities in General
...
[AdministrableSubstance] {substanceCode} [of type {entityType} ][strength {strength} ][form {form} ][brand {substanceBrandCode} ][generic {substanceGenericCode} ][mfg {manufacturer} ][lot# {lotNo} ]
Only the substanceCode is strictly required, but some use cases may require some or all of the additional elements. More specific patterns will be developed as the need arises.
...
...
- [Entity] [of type {entityType}]
...
- [Facility] [of type {entityType}]
...
- [Organization] [of type {entityType}]
...
- [Person] [of type {entityType}]
...
- [Specimen] [of type {entityType}]
...
- [Entity] as tag {idTag}…
then uses all patterns shown above under Entities in General
...
- [Entity] has role {targetRole} to {entityClass} identified as tag {idTag}
...
- [Entity] has role {targetRole} to {entityClass} identified as tag {idTag} during {relationshipTimeInterval}…
...
Encounters
...
- [Encounter] as tag {x}…
then uses all patterns shown above under Events in General
...
- [Encounter] is {targetRelationshipToSource} of {clinicalStatementClass} identified as tag {idTag}…
then uses all patterns shown above under Encounters and Events in General
...
AdverseEvents
...
- [AdverseEvent] due to {adverseEventAgent}…
then uses all patterns shown above under Events in General
...
- [AdverseEvent] due to {adverseEventAgent} with {criticality} criticality…
then uses all patterns shown above under Events in General
...
- [AdverseEvent] due to {adverseEventAgent} with {severity} severity…
then uses all patterns shown above under Events in General
...
- [AdverseEvent] due to {adverseEventAgent} with {criticality} criticality and {severity} severity…
then uses all patterns shown above under Events in General
...
- [AdverseEvent] as tag {idTag}…
then uses all patterns shown above under Adverse Events and Events in General
...
- [AdverseEvent] is {targetRelationshipToSource} of {clinicalStatementClass} identified as tag {idTag}…
then uses all patterns shown above under Adverse Events and Events in General
...
Observations
...
- [ObservationResult] has {observationValue} (where observationValue may be of any supported datatype)
...
- [ObservationResult] is interpreted as {interpretation}
...
- [ObservationResult] has {observationValue} interpreted as {
...
- interpretation}
...
- [ObservationResult] has {observationValue} using specimen from {targetBodySite}
...
...
- [ObservationResult] using specimen from {targetBodySite} is interpreted as {interpretation}
...
...
- [ObservationResult] has {observationValue} using specimen from {targetBodySite} interpreted as {interpretation}
...
...
- [ObservationResult] as tag {idTag}…
then uses all patterns shown above under Observations and Events in General
...
- [ObservationResult] is {targetRelationshipToSource} of {clinicalStatementClass} identified as tag {idTag}…
then uses all patterns shown above under Observations and Events in General
...
Problems
...
- [Problem] was present on admission to encounter {x}
...
- [Problem] was present on admission as {priority} to encounter {x}
...
- [Problem] was a discharge diagnosis for encounter {x}
...
- [Problem] was {priority} discharge diagnosis for encounter {x}
...
- [Problem] is currently {problemStatus} and {importance}
...
- [Problem] was {problemStatus} at least {n} times
...
- [Problem] was {problemStatus} in last {n} [timeUnits]
...
...
- [Problem] was {problemStatus} at least {n1} times in last {n2} [timeUnits]
...
- [Problem] was {problemStatus} between {n1} and {n2} [timeUnits] ago
...
...
- [Problem] as tag {idTag}…
then uses all patterns shown above under Problems and Events in General
...
- [Problem] is {targetRelationshipToSource} of {clinicalStatementClass} identified as tag {idTag}…
then uses all patterns shown above under Problems and Events in General
...
Procedures
...
- [Procedure] on {targetBodySite}…
then uses all patterns shown above under Events in General
...
...
- [Procedure] by way of {approachBodySite}…
then uses all patterns shown above under Events in General
...
- [Procedure] on {targetBodySite} by way of {approachBodySite}…
then uses all patterns shown above under Events in General
...
- [Procedure] as tag {idTag}…
then uses all patterns shown above under Procedures and Events in General
...
...
- [Procedure] is {targetRelationshipToSource} of {clinicalStatementClass} identified as tag {idTag}…
then uses all patterns shown above under Procedures and Events in General
...
SubstanceAdministrations – Medications
Not all possible patterns are shown. The ones shown cover the use cases listed below. It is expected that some elements in all patterns may not be needed in particular constrained use cases, and that more specific patterns will be created to meet this need.
...
- Current medication list
...
- [Medication] {substanceCode} since {administrationTimeInterval} [reported {documentationTime} ][by {dataSourceType} ][attested by {informationAttestationType} ]
...
- Medication order (prescription)
...
- [Medication] {substanceCode} [strength {strength} ][form {form} ][dose {doseQuantity} ][route {deliveryRoute} ][frequency {dosingPeriod} [interval matters {dosingPeriodIntervalIsImportant} ]][sig {dosingSig} ][# fills {numberFillsAllowed} ][{criticality} ][ordered on {orderEventTime} ]
...
- Medication administration (in clinic or hospital)
...
- [Medication] {substanceCode} [type {doseType} ][strength {strength} ][form {form} ][dose {doseQuantity} ][route {deliveryRoute} ][site {targetBodySite} ][frequency {dosingPeriod} [interval matters {dosingPeriodIntervalIsImportant} ]] from {administrationTimeInterval.low} [thru {administrationTimeInterval.high} ]
...
...
- Medication dispensation by clinic or pharmacy
...
- [Medication] {substanceCode} [type {doseType} ] [strength {strength} ][form {form} ][dose {doseQuantity} ][route {deliveryRoute} ][frequency {dosingPeriod} [interval matters {dosingPeriodIntervalIsImportant} ]][ not to exceed {doseRestriction} ][days supply {daysSupply} ][# {dispensationQuantity} ][ fill# {fillNumber} ][fills left {fillsRemaining} ][dispensed {dispensationTime} ]
...
- [Medication] …
then uses many patterns shown above under Events in General
...
...
- [Medication] as tag {idTag}…
then uses many patterns shown above under Medications and Events in General
...
...
- [Medication] is {targetRelationshipToSource} of {clinicalStatementClass} identified as tag {idTag}…
then uses many patterns shown above under Medications and Events in General
...
SubstanceAdministrations – Immunizations
Not all possible patterns are shown. The ones shown cover the use cases listed below. It is expected that some elements in all patterns may not be needed in particular constrained use cases, and that more specific patterns will be created to meet this need.
...
- Immunization history
...
- [Immunization] {substanceCode} [mfg {manufacturer} ][lot# {lotNo} ][dose# {doseNumber} ][route {deliveryRoute} ][site {targetBodySite} ][valid? {isValid} ] on {administrationTimeInterval.low}
...
- Immunization administration
...
- [Immunization] {substanceCode} [mfg {manufacturer} ][lot# {lotNo} ][dose# {doseNumber} ][route {deliveryRoute} ][site {targetBodySite} ] on {administrationTimeInterval.low}
...
...
- Immunization forecast
...
- [Immunization] {substanceCode} [dose# {doseNumber} ] not before {administrationTimeInterval.low} ideally on {administrationTimeInterval.high}
...
- [Immunization]…
then uses many patterns shown above under Events in General
...
- [Immunization] as tag {idTag}…
then uses many patterns shown above under Immunizations and Events in General
...
- [Immunization] is {targetRelationshipToSource} of {clinicalStatementClass} identified as tag {idTag}…
then uses many patterns shown above under Immunizations and Events in General
...
Supplies
...
- [Supply] on {targetBodySite}…
then uses all patterns shown above under Events in General
...
...
- [Supply] as tag {idTag}…
then uses all patterns shown above under Supplies and Events in General
...
...
- [Supply] is {targetRelationshipToSource} of {clinicalStatementClass} identified as tag {idTag}…
then uses all patterns shown above under Supplies and Events in General
...
Best Practices for Creating Responses from OpenCDS
...
Use Templates for Output
Check the OpenCDS website for output templates that are already defined, and select an appropriate one. Use the templateId(s) assigned to that template in your output response message. This furnishes information to external software to define how your output is structured.
If an appropriate output template does not already exist, create a definition of one or more response message(s) that will suit the needs of your KM(s), and ask OpenCDS to assign new templateId values. This will be done quickly, and will be posted with the OpenCDS documentation so that it can be used by others. Write your definition using the TemplateId Request Form available on the OpenCDS website.
...
One Inference Wrapper per KnowledgeModule
Create an ObservationResult as a “wrapper” for all of the response messages from each KnowledgeModule (aka Drools “Package”, or a “ruleset”) that OpenCDS was requested to apply to the current dataset. Use one of the DSLs whose name begins with “OutputRoot…” as this wrapper.
...
You are not limited to imbedding just ObservationResults in a wrapper. You can imbed any clinical statement(s) in whatever order is useful and meaningful. You can imbed all or portions of the submitted data by creating a ClinicalStatementRelationship to the wrapper element, in the same way that the “OutputNested…” DSLs do it.
...
Include Both Coded Response and Text (if appropriate)
Note that you can return both “typed” values and text values in an ObservationResult, and it is sometimes useful to include both a code, and explanatory text designed for humans (for validation and debugging purposes, even if the output is intended solely for machine processing). For example, you might return something like the “originalText” in the following examples to express the full contextual meaning of the code/codeSystem returned in an observationValue:
...
<interpretation code=”…” codeSystem=”…” originalText=”Extremely high value, further treatment should be considered”/>
...
Include Proposals (if appropriate)
Response messages most commonly include one or more of the following:
...
<Include an example of a response message that includes all of the above elements:>
...
How to Create Return Messages from your Rules
There are two techniques for creating return messages from your rules. They can be combined in rules to create quite complex and specific output patterns.
...
Flag Input in FactLists as “toBeReturned”
Any of the input clinicalStatement and entity data that is present in Drools fact lists can be flagged to be returned in the output message from OpenCDS. By default, the Patient ID and Demographics (and the same thing for OtherEvaluatedPersons) are the only thing that will be returned, but you can add to that from your rules, if required.
You will undoubtedly need to return additional information. In some cases you might want to set some value on an input clinical statement, and return that clinical statement as output. For example, you might want to populate an Interpretation on an ObservationResult and return the input ObservationResult with that one additional element as an output or response. This is easily done by setting the toBeReturned flag to true on that particular clinicalStatement.
...
Create New Output Elements in Global NamedObjects
The basic technique for returning a result is to do the following:Fancy Bullets - create a new ObservationResult or other clinical
...
- statement,
- set appropriate values in it,
- set the flag
...
- toBeReturned (present in all clinical statements) = true (because you
...
- can also use the “namedObjects” as temporary storage for working variables
...
- and intermediate results in your rules without flagging them toBeReturned…), and
- add the clinical statement to the global element
...
- “namedObjects”.
...
Note that other output elements (e.g., ClinicalStatementRelationship, Entity, etc.) can also be returned as a part of the output. These (and any other output elements you create from scratch) must also be added to “namedObjects” in order to appear in the response message from OpenCDS. Examples of how to do this appear in the sample “OutputNested…” DSLs. Remember:You can create an object (of any type), and add it to “namedObjects,” and you can reference the contents of the object in a rule, and/or use it as part of the output response from OpenCDS, but Drools will not fire a rule based on a change to the contents of a global variable (which is what “namedObjects” is). Drools only fires rules based on changes to facts in fact lists.
You can create new facts while running a rule, and reason on them. Changes to these new facts can cause rules to fire (unlike changes to globals). However, new facts will not be returned to OpenCDS to be used as response messages unless they are structured as ClinicalStatements and you also add them to “namedObjects.”
See the sample DSLs whose names begin with “Output…” for examples.
...
Common Patterns for Creating Responses
...
Write me…
asdf
Change Log
Date | Author | Notes |
12-14-2011 | David Shields | Initial document without best practices section |
12-15-2011 | David Shields | Finished first draft of best practices section |
12-20-2011 | Ken Kawamoto | Minor edits |
12-20-2011 | David Shields | Added screen shots that were omitted earlier |
1-12-2012 | David Shields | Added one new “pot-hole” and work-around / fix |
6-28-2012 | David Shields | Edited for Drools Guvnor v5.4 |
7-5-2012 | David Shields | Added more “pot-holes”, worked on DSL Patterns |
...