Legacy CDSS

The CDSS XML Format

Clinical protocols are defined in the protocols/ directory of an applet. When this applet is uploaded to the IMS, it will install the protocol into the IMS and distribute the protocol to all connected clients.

The protocol XML format is described in the ClinicalProtocol.xsd schema distributed with the SDK and can be used by any standard XML editor to provide code completion. In this tutorial we will be using Microsoft Visual Studio to do this editing.

Creating your protocol file

For this tutorial, we're going to do protocol for a fake HepA+HepB dualvalent adult schedule which requires three doses. (Note: This is not medically accurate, and is for illustrative purposes). The dosing schedule looks like this:

  • d1 = p.dob + ('9yr' .. )

  • d2 = d1.time + ('1mo' .. '1yr'),

  • d3 = d2.time + ('1yr' .. '3yr')

Basically in human terms:

  • Dose 1 can occur anytime after the patient's 9th birthday

  • Dose 2 should occur 1 after after dose 1 but is still effective if given up to one year

  • Dose 3 should occur 1 year after Dose 1 but is no longer effective if given 3 years after dose 1.

The first thing we will do is create a new XML file in our applet project under protocols/. The name can be anything but it is good practice to use the format:


Given that, if we're in Elbonia (our fake jurisdiction) the filename would be


The next thing we want to do (to make our editing easier) is to add a reference to the ClinicalProtocol.xsd schema.

We now can create the start of our XML protocol:

<?xml version="1.0" encoding="utf-8" ?>
<ProtocolDefinition xmlns="http://santedb.org/cdss">


Identifying your Protocol

Whenever SanteDB creates an Act based on the suggestion of a clinical protocol, or whenever it is installing your applet, it needs to assign a unique identifier to the protocol for linking. The four attributes that control this behavior are:

  • id - The developer friendly name for the protocol like MyProtocol1

  • name - The human friendly name for the protocol like HepA+HepB Dualvalent

  • uuid - The universally unique name for the protocol (a UUID)

  • version - The version of the protocol represented in the file.

After adding these your protocol should look like this:

<ProtocolDefinition xmlns="http://santedb.org/cdss" 
                    name="Elbonia HepA+HepB 3 Dose Standard Schedule"

Important: The UUID must be unique. Don't just copy/paste them from examples or other protocols. If you change a protocol you must change the UUID.

Identifying Entry Criteria

Next, we have to determine who we even want to apply this protocol to. The entry criteria could be:

  • Mandatory - In which case we want to define the entry criteria for populations which must have the schedule applied (for example: All FEMALES must have HPV)

  • Optional - In which case subsequent doses are based off the first.

For our example, we're going to say that this HepA+HepB vaccination is optional. This means that we only want to schedule Dose #2 and Dose #3 if Dose #1 was given.

Note: Our dosing schedule says that we can only apply it to patients who are 9 or older, however that is validation rather than planning, so that type of validation rule would go in the business rules JavaScript file to prevent administration of that particular vaccination.

To do this we create a <when> tag on our protocol. The WHEN tag can use HDSI expressions or simple LINQ expressions. Our entry criteria is:

  • When the patient was involved in a SubstanceAdministration where the product given was this particular type of vaccine

    • note: You can also base your condition on Consumable rather than Product if you care which brand the previous vaccination was

  • When the dose sequence of that administration was 1.


If the schedule was mandatory we might do something like this:

    <!-- Patient is 9 years old -->
    <linqExpression>now.Subtract(DateOfBirth.Value.Date).TotalDays &gt;= 3285</linqExpression>

Define the rule for Dose #2

Next we have to define a step in our clinical protocol. This is known as a rule. Rules are expressed in common when/then notation. Again the when clauses can use HDSI query or LINQ to filter.

When we look at our Dose 2 logic it was:

d2 = d1.time + ('1mo' .. '1yr'),

So we want to say that when:

  • The time that the patient has received the first dose of the vaccination where

    • The product given was HepA+HepB vaccine, and

    • The dose sequence was 1, and

    • The dose was actually given (not negated)

  • We also don't want to propose duplicates, so we should also make a rule that the patient has not received a vaccination where:

    • The product given was HepA+HepB, and

    • The dose sequence was 1, and

    • The dose was actually given

We could get more fancy to say if they showed up and were explicitly not given Dose #2 (i.e. they showed to an appointment but there was a stock out), or if the patient has a known intolerance we shouldn't schedule this, but for now we'll keep the example simple.

  <rule id="HEPAB_2" name="HepA+HepB Second Dose">
    <when evaluation="and">
      <!-- Patient DID Receive Dose #1 -->
      <!-- Patient DID NOT Receive Dose #2 -->
      <hdsiExpression negationIndicator="true">

Define the "then" if Dose #2 should be proposed

The 'then' logic on a rule indicates what should happen if the "when"condition was successful. Here there are two steps, one where we define a template of something to propose be done, and the other where we set dynamically the properties on that object.

              "$type": "SubstanceAdministration",
              templateModel: {
                  mnemonic: "act.substanceadmin.immunization"
              "moodConcept": "ACF7BAF2-221F-4BC2-8116-CEB5165BE079",
              "typeConcept": "F3BE6B88-BC8F-4263-A779-86F21EA10A47",
              "statusConcept" : "c8064cbd-fa06-4530-b430-1a52f1530c27",
              "doseSequence": 2,
              "doseQuantity" : 1.0,
              "doseUnitModel" : {
                "id": "a4fc5c93-31c2-4f87-990e-c5a4e5ea2e76",
                "mnemonic" : "UnitOfMeasure-Dose"
              "routeModel" : {
                "id": "d594f99f-0151-41a0-a359-282ab54683a1",
                "mnemonic": "RouteOfAdministration-IM"
              "siteModel" : {
                "id": "1edc643d-a93a-47ed-8737-06ede53d0e1f",
                "mnemonic": 'Site-RightArm'
              "participation": {
                "Product": [{
                  "player" : "6CD437C5-E9C2-4259-AA73-6BE768BA3FC0"

Note: The player of 6CD437C5-E9C2-4259-AA73-6BE768BA3FC0 is a fake UUID, you would substitute a valid material's product key here.

This will setup the static object, now we want to have some logic that will update the start/stop time of the dose based on our previous expression. To do this we use <assign>. Be default the current scope of Assign is the same as the when condition (the patient) but we need to change this since we'll be setting properties based on dose 1. To do that we need to set the three properties of assign:

  • propertyName Which identifies the property in the proposed object we want to change

  • scope Which identifies the scope property we want to use

  • where Which allows us to filter to a particular object in the scope array

        <assign scope="Participations" where="participationRole.mnemonic=RecordTarget&amp;source.classConcept=932A3C7E-AD77-450A-8A1F-030FC2855450&amp;source@SubstanceAdministration.doseSequence=1&amp;source.participation[Product].player.typeConcept?.mnemonic=VaccineType-HepAHepB" propertyName="StartTime">Act.ActTime.AddMonths(1)</assign>
        <assign scope="Participations" where="participationRole.mnemonic=RecordTarget&amp;source.classConcept=932A3C7E-AD77-450A-8A1F-030FC2855450&amp;source@SubstanceAdministration.doseSequence=1&amp;source.participation[Product].player.typeConcept?.mnemonic=VaccineType-HepAHepB" propertyName="ActTime">Act.ActTime.AddMonths(1)</assign>
        <assign scope="Participations" where="participationRole.mnemonic=RecordTarget&amp;source.classConcept=932A3C7E-AD77-450A-8A1F-030FC2855450&amp;source@SubstanceAdministration.doseSequence=1&amp;source.participation[Product].player.typeConcept?.mnemonic=VaccineType-HepAHepB" propertyName="StopTime">Act.ActTime.AddMonths(12)</assign>


Testing your Protocol

The SanteDB SDK provides a utility for testing your clinical protocols before deploying in production. In order to run the debugging tool, you will need a copy of Minims (also in the SDK) database. This allows you to debug your protocols against configured data sources. You can obtain these files by:

  • Creating a backup from the SanteDB Disconnected Client mobile application

  • Pointing the database at a configured Minims database (--db=%localappdata%\sdbare\santedb.sqlite). Note this is the default operating mode when launching the application from the start menu.

  • Creating a new database and using anonymous patients (only recommended for simple protocols)

This tooling is provided by the SanteDB Debug (sdb-dbg) and can be executed by running:

> sdb-dbg --db=newdb1.sqlite --xprot

SanteDB Debugger v1.0.0.20334 (Fredericton)
Copyright (C) 2015-2019 Mohawk College of Applied Arts and Technology
[Warning 2018/01/28 11:41:03] OizDebug.Core.DebugApplicationContext : Can't find the SanteDB database, will re-install all migrations
Loading debuggees...
Working Directory: C:\Users\justin\Documents
dbg >

First we want to open our clinical protocol:

dbg >o el.protocol.vacc.hepabdvalent.xml

Then we want to test it against a patient. To this we either have to use the scope data query command:

dbg >sdq Patient name.component.value=~Justin
INF: Patient where o => o.Names.Any(name => name.Component.Any(component => (component.Value.Contains("Justin") == True))) (0..)
INF: 1 set to scope
dbg >xs [0]

Or, we can load a patient from JSON or XML:

dbg >sfv Patient mypatient.json

Or we can create an instance of an anonymous patient:

dbg >ss Patient '{ "dateOfBirth":"2017-01-01" }'

Once the scope is set, we can verify the scope by dumping the scope (ds) as XML or JSON

dbg >dx
<Patient xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://santedb.org/model">
  <version xsi:nil="true" />
  <sequence xsi:nil="true" />
  <statusConcept xsi:nil="true" />
  <template xsi:nil="true" />
  <deceasedDatePrecision xsi:nil="true" />
  <genderConcept xsi:nil="true" />

As JSON the command is:

dbg >dj
  "dateOfBirth": "2017-01-01",
  "language": [],
  "classConcept": "bacd9c6f-3fa9-481e-9636-37457962804d",
  "determinerConcept": "f29f08de-78a7-4a5e-aeaf-7b545ba19a09",
  "relationship": [],
  "$type": "Patient"

Now we can run our clinical protocol to see what is generated

dbg >go
Complete result set to scope

If you want to look at the care plan generated use either "dump scope" (ds) or "dump scope as JSON" (dv or dj)

dbg >dj
  "target": {
    "dateOfBirth": "2017-01-01",
    "language": [],
    "classConcept": "bacd9c6f-3fa9-481e-9636-37457962804d",
    "determinerConcept": "f29f08de-78a7-4a5e-aeaf-7b545ba19a09",
    "relationship": [],
    "$type": "Patient"
  "act": [
      "$type": "SanteDB.Core.Model.Acts.SubstanceAdministration, SanteDB.Core.Model",
      "route": "d594f99f-0151-41a0-a359-282ab54683a1",

Last updated