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:
[jurisdiction].protocol.[type].[class].xml
Given that, if we're in Elbonia (our fake jurisdiction) the filename would be
el.protocol.vacc.hepabdvalent.xml
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:
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:
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:
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.
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.
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
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:
First we want to open our clinical protocol:
Then we want to test it against a patient. To this we either have to use the scope data query command:
Or, we can load a patient from JSON or XML:
Or we can create an instance of an anonymous patient:
Once the scope is set, we can verify the scope by dumping the scope (ds) as XML or JSON
As JSON the command is:
Now we can run our clinical protocol to see what is generated
If you want to look at the care plan generated use either "dump scope" (ds) or "dump scope as JSON" (dv or dj)
Last updated