OpenCDS Functional Introduction

Owned by SalvadorR
Last updated: Jan 25, 2017 by David Shields

Introduction

  • OpenCDS uses the following as defaults: 
    • HL7 vMR 1.0 logical model for both transport and inferencing data structures,
    • the HL7 Decision Support Service (DSS) messaging standard (which is based on SOAP), and
    • Drools 5. 
  • OpenCDS also includes support for other standards:
    • Payloads:
      • full HL7 FHIR
      • partial support for HL7 C-CDA using 3rd party extensions
      • custom input data structures using plug-ins
    • Messaging standard:
      • REST, when using the FHIR Decision Support messages
    • Inferencing using:
      • several releases of Drools 6 (KIE)
      • custom inferencing using Java via plug-ins
      • Weka adapter
  • This introduction will stick to the vMR 1.0 standard for the payload, DSS with SOAP, and rules written for Drools 5. 

SOAP

The SOAP envelope which contains the content consists of the following code.


<?xml version="1.0" encoding="UTF-8"?>
 <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-envelope"
     xmlns:dss="http://www.omg.org/spec/CDSS/201105/dss">
     <SOAP-ENV:Header/>
     <SOAP-ENV:Body>

    ....dss content here....

    </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

DSS Standard

Background

The full DSS implementation guide can be found here. 

OpenCDS application 

Currently OpenCDS implements a subset of the DSS standard, which consists of Evaluate and EvaluateAtSpecifiedTime. The difference between these two standards is the inclusion of the specifiedTime child element.

Breaking down an example

We will be using the following example to understand the DSS standard:

        <dss:evaluateAtSpecifiedTime>
           <interactionId scopingEntityId="edu.utah" interactionId="123"  submissionTime="2012-01-20T07:59:35.123"/>
           <specifiedTime>2012-01-01T00:00:00.000</specifiedTime>
              <evaluationRequest clientLanguage="" clientTimeZoneOffset="">
                <kmEvaluationRequest>
                    <kmId scopingEntityId="edu.utah" businessId="AcuteBloodLoss" version="1.0.0"/>
                </kmEvaluationRequest>
                <dataRequirementItemData>
                    <driId itemId="testPayload">
                        <containingEntityId scopingEntityId="edu.utah" businessId="ABLData"  version="1.0.0"/>
                    </driId>
                    <data>
                        <informationModelSSId scopingEntityId="org.opencds.vmr" businessId="VMR"   version="1.0"/>
                        <base64EncodedPayload>BASE64ENCODEDPAYLOAD</base64EncodedPayload>
                    </data>
                </dataRequirementItemData>
            </evaluationRequest>
        </dss:evaluateAtSpecifiedTime>


evaluateAtSpecifiedTime

This defines the time the knowledge module (KM) needs to be evaluated. This may be either a point in time that is in the past, a point in time that is in the future, or the current time. 

It is common to have Quality Measures evaluated at point in the past, such as the end of the previous year.  A time in the past is also often used for validation data, where constructed data is used to verify that rules are continuing to work correctly after updates or changes were made.

It is common to have patient care rules evaluated at the current time.

There may also be times where rules will be evaluated at a point in the future.  This is particularly useful when evaluating the need for a patient appointment, or preventive care of some kind that needs to be done on a regularly scheduled basis.  For example, the patient (or their provider) can be reminded that they will need to have a screening test performed by the beginning of the next month.

interactionID

This consists of a unique identifier of the CDS request provided by the CDS requester. The client supplies this information, all attributes are required. 

   scopingEntityID- A unique identifier (string) used to identify scoping entities. e.g. edu.utah.bmi or com.cdsvendor.  The DSS standard specifies that these should be in domain name format, as used on the internet.

   interactionID- A client-generated unique identifier (string) for the request. e.g. 123

   submissionTime- The submission of the request using the ISO datetime data type. e.g. 2012-01-20T07:59:35.123

specifiedTime

The client-specified evaluation time consists of the evaluation time to be used by the DSS provider using the datetime data type. e.g. 2012-01-01T00:00:00.000. 

evaluationRequest

This is a wrapper for the request for evaluation. Both attributes are required.

   clientLanguage- The language used in the evaluation request. Use ISO 639-1 language code. See implementation guide for more details. e.g. "en", "en-US", "en-GB" 

   clientTimeZoneOffset- The client's time zone is offset from Universal Coordinated Time (UTC) in the form “±[hh]:[mm]”. e.g., “-05:00”.

kmEvaluationRequest

kmID

Identifies knowledge modules (KMs) to use for the evaluation. The following attributes 

    scopingEntityID-  A unique identifier (string) used to identify scoping entities for the KM (i.e. not necessarily the scoping entity of the client). e.g. com.cdsvendor

    businessID- Identifies which KMs will be evaluated. e.g. DiabetesMellitusNeedForPnuemoccalVaccination

    version- The version of the KM to use. e.g. 1.0.0

dataRequirementItemData

This is a wrapper for the patient data payload. This element may repeat.

driId

Each KM specifies a set of data requirements. Required data are specified in terms of data requirement items (DRIs). The DSS provider identifies each DRI.

  itemID- The identifier of the DRI e.g. "SoleDataRequirementItemForKM"

containingEntityId

The identifier of the KM to which the DRI applies.

    scopingEntityID- A unique identifier (string) used to identify scoping entities for the KM in this case, not the client. e.g. com.cdsvendor

    businessID- KM identifier indicating which KMs will be evaluated. e.g. DiabetesMellitusNeedForPnuemoccalVaccination

    version- The version of the KM to use. e.g. 1.0.0

data

A wrapper for the patient data needed for CDS.

informationModelSSId

Identifies the format used for providing the payload of patient clinical data.

    scopingEntityID- Indicates the entity that defines the information model being used. e.g. org.hl7.cds

    businessID- The identifier of the information model used to represent the data. e.g. cdsinput:r2:CDSInput

    version- The version of the information model used. e.g. 2.0

BASE64PAYLOAD

Current OpenCDS only supports CDSInput and CDSOutputAsVMR to receive and send data, respectively. The content is encoded and transmitted using base64 format. You can use a free web encoder/decoder such as http://www.base64encode.org/ to make this conversion.

An example CDSInput payload will look like:

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxDRFNJbnB1dD4NCjx2bXJJbnB1dD4NCjxwYXRpZW50Pg0KPGJpcn
RoVGltZSB2YWx1ZT0iMTk2MzA1MjUiLz4NCjxnZW5kZXIgY29kZVN5c3RlbT0iMi4xNi44NDAuMS4xMTM4ODMuMS4xMS4xIiBjb2RlU3lzd
GVtTmFtZT0iSEw3IiBjb2RlPSJNIi8+DQo8Y2xpbmljYWxTdGF0ZW1lbnQgeHNpOnR5cGU9IlByb2JsZW0iPg0KPHRlbXBsYXRlSWQgcm9
vdD0iMi4xNi44NDAuMS4xMTM4ODMuMy4xODI5LjExLjcuMi40IiBpZGVudGlmaWVyTmFtZT0iQWN0aXZlUHJvYmxlbUxpc3RFbnRyeUNv
ZGVPbmx5Ii8+DQo8cHJvYmxlbUNvZGUgY29kZVN5c3RlbT0iT0lEIGZvciBJQ0Q5Q00iIGNvZGVTeXN0ZW1OYW1lPSJJQ0Q5Q00iIGNvZ
GU9IjI1MC4wMCI+DQo8ZGlzcGxheU5hbWUgdmFsdWU9IkRpYWJldGVzIG1lbGxpdHVzIi8+DQo8L3Byb2JsZW1Db2RlPg0KPC9jbGluaW
NhbFN0YXRlbWVudD4NCjwvcGF0aWVudD4NCjwvdm1ySW5wdXQ+DQo8L0NEU0lucHV0Pg==

Which decodes to:

<?xml version="1.0" encoding="UTF-8"?>
<CDSInput>
   <vmrInput>
    <patient>
     <birthTime value="19630525"/>
     <gender codeSystem="2.16.840.1.113883.1.11.1" codeSystemName="HL7" code="M"/>
     <clinicalStatement xsi:type="Problem">
     <templateId root="2.16.840.1.113883.3.1829.11.7.2.4" identifierName="ActiveProblemListEntryCodeOnly"/>
     <problemCode codeSystem="OID for ICD9CM" codeSystemName="ICD9CM" code="250.00">
       <displayName value="Diabetes mellitus"/>
     </problemCode>
    </clinicalStatement>
   </patient>
  </vmrInput>
</CDSInput>


An example CDSOutputAsVMR payload will look like:

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxDRFNPdXRwdXRBc1ZNUj4NCjx2bXJPdXRwdXQ+DQo8cGF0aWVudD4N
CjxjbGluaWNhbFN0YXRlbWVudCB4c2k6dHlwZT0iSW1hZ2luZ1Byb3Bvc2FsIj4NCjxpZCByb290PSI5YTZkMWJhYy0xN2QzLTQxOTUtODlj
NC0xMTIxYmM4MDliNWEiLz4NCjxwcm9jZWR1cmVDb2RlIGNvZGU9IjE2ODczMTAwOSIgY29kZVN5c3RlbT0iMi4xNi44NDAuMS4xMTM4ODMu
Ni45NiIgY29kZVN5c3RlbU5hbWU9IlNOT01FRC1DVCI+DQo8ZGlzcGxheU5hbWUgdmFsdWU9IkNoZXN0IFgtUmF5Ii8+DQo8L3Byb2NlZHVy
ZUNvZGU+DQo8cHJvcG9zZWRQcm9jZWR1cmVUaW1lPjxsb3cgdmFsdWU9IjIwMTIwODI2Ii8+PGhpZ2ggdmFsdWU9IjIwMTIwODI2Ii8+PC9w
cm9wb3NlZFByb2NlZHVyZVRpbWU+DQo8L2NsaW5pY2FsU3RhdGVtZW50Pg0KPC9wYXRpZW50Pg0KPC92bXJPdXRwdXQ+DQo8L0NEU091dHB1
dEFzVk1SPg==

Which decodes to:

<?xml version="1.0" encoding="UTF-8"?>
<CDSOutputAsVMR>
  <vmrOutput>
   <patient>
    <clinicalStatement xsi:type="ImagingProposal">
     <id root="9a6d1bac-17d3-4195-89c4-1121bc809b5a"/>
     <procedureCode code="168731009" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SNOMED-CT">
       <displayName value="Chest X-Ray"/>
     </procedureCode>
     <proposedProcedureTime>
       <low value="20120826"/>
       <high value="20120826"/>
     </proposedProcedureTime>
    </clinicalStatement>
   </patient>
  </vmrOutput>
</CDSOutputAsVMR>

Putting it all together

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-envelope"
    xmlns:dss="http://www.omg.org/spec/CDSS/201105/dss">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>

        <dss:evaluateAtSpecifiedTime>
           <interactionId scopingEntityId="edu.utah" interactionId="123"  submissionTime="2012-01-20T07:59:35.123"/>
           <specifiedTime>2012-01-01T00:00:00.000</specifiedTime>
              <evaluationRequest clientLanguage="" clientTimeZoneOffset="">
                <kmEvaluationRequest>
                    <kmId scopingEntityId="edu.utah" businessId="AcuteBloodLoss" version="1.0.0"/>
                </kmEvaluationRequest>
                <dataRequirementItemData>
                    <driId itemId="testPayload">
                        <containingEntityId scopingEntityId="edu.utah" businessId="ABLData"  version="1.0.0"/>
                    </driId>
                    <data>
                        <informationModelSSId scopingEntityId="org.opencds.vmr" businessId="VMR"   version="1.0"/>
                        <base64EncodedPayload>
                                 PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxDRFNJbnB1dD4NCjx2bXJJbnB1dD4NCjxwYXRpZW50Pg0KPGJpcn
                                 RoVGltZSB2YWx1ZT0iMTk2MzA1MjUiLz4NCjxnZW5kZXIgY29kZVN5c3RlbT0iMi4xNi44NDAuMS4xMTM4ODMuMS4xMS4xIiBjb2RlU3lzd
                                 GVtTmFtZT0iSEw3IiBjb2RlPSJNIi8+DQo8Y2xpbmljYWxTdGF0ZW1lbnQgeHNpOnR5cGU9IlByb2JsZW0iPg0KPHRlbXBsYXRlSWQgcm9
                                 vdD0iMi4xNi44NDAuMS4xMTM4ODMuMy4xODI5LjExLjcuMi40IiBpZGVudGlmaWVyTmFtZT0iQWN0aXZlUHJvYmxlbUxpc3RFbnRyeUNv
                                 ZGVPbmx5Ii8+DQo8cHJvYmxlbUNvZGUgY29kZVN5c3RlbT0iT0lEIGZvciBJQ0Q5Q00iIGNvZGVTeXN0ZW1OYW1lPSJJQ0Q5Q00iIGNvZ
                                 GU9IjI1MC4wMCI+DQo8ZGlzcGxheU5hbWUgdmFsdWU9IkRpYWJldGVzIG1lbGxpdHVzIi8+DQo8L3Byb2JsZW1Db2RlPg0KPC9jbGluaW
                                 NhbFN0YXRlbWVudD4NCjwvcGF0aWVudD4NCjwvdm1ySW5wdXQ+DQo8L0NEU0lucHV0Pg==
                        </base64EncodedPayload>
                    </data>
                </dataRequirementItemData>
            </evaluationRequest>
        </dss:evaluateAtSpecifiedTime>

    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


Testing the service

Instructions can be found at R-T Installation Guide - (v2.x and up)#TInstallationGuide-(v2.xandup)-TesttheInstallation