CDSS Definitions
Last updated
Last updated
Starting with SanteDB 3.0, a new, more robust CDSS XML format has been introduced which greatly improves the re-use of decision logic blocks in CDSS rules. CDSS definitions are contained in an XML or text file structure known as a CDSS Library. The CDSS library contains different definition sections as illustrated below.
Metadata: Descriptive information about the CDSS library including the version, its current status, and authors, etc.
Includes: Allow a CDSS library to import definitions from other CSS libraries (including the system library)
Logic Blocks: Blocks of definition assets which apply to a particular context.
Context: Allows for the limiting of rules, protocols, and facts to a particular resource type, and even a subset of resource types.
Facts: Defines a discrete piece of information which is extracted from the context in the CDSS
Rules: Structures which trigger a series of actions when a series of facts are true
Protocols: A more structured version of a rule which includes metadata for the CDSS engine, including the steps in a care plan package.
Data Blocks: Allow a CDSS author to include reference data which rules may use. For example, an author may include pre-computed z-scores for a particular type of observation which is then used to set the interpretation of an observation.
CDSS definitions are transpiled into an XML format from the CDSS source files. The CDSS source files are text files which can be created with any text editor. CDSS library definitions are uploaded to the SanteDB server or loaded into the SanteDB business rules debugger.
The structure of the CDSS and its equivalent XML structure are provided below.
CDSS files are always placed in the protocols/ folder of your applet. This folder can contain XML or text-based definitions for your libraries.
There are two types of strings which are supported in the CDSS definition file, a single line string is enclosed in double quotes such as "This is a string", a string can be escaped with a double quote such as "This is a ""string"" that is escaped".
Strings which cross multiple lines or strings which need to use lots of quotes (which would require a lot of escaping) are represented as multi-line strings. These strings are enclosed in $$ indicators such as $$ This is a "string" too $$ , these are useful for representing C#, HDSI or even large JSON objects such as:
Dotted identifiers allow for direct, unambiguous references to objects in the CDSS subsystem. Dotted identifiers are enclosed in < marks. The use of these are illustrated in references such as include <org.santedb.example> where org.santedb.example is the dotted identifier.
Block definitions include all of: libraries, logic, data, facts, protocols, rules, models, proposals, etc. Blocks are multiple lines which encapsulate the modifiers and instructions for the blocks. Block definitions always have the pattern:
Comments can be added to any of part of your CDSS file. Comments differ from metadata documentation in that comments are stripped from the transpiled source, and are only visible to developers. Any line or part of line following a double-slash // is a comment.
The status of an object will be used to determine whether the object is to be referenced or used in the evaluation of rules in the library. The status is indicated on an element with <status> element on the object.
trial-use
The object is for trial use only.
The library, logic block, rule, etc. is only used in debugging and testing contexts.
active
The object is active and available for system use.
The library, logic block, rule, etc. is used for all clinical encounters and when the CDSS engine is called.
retired
The object was active, and can continue to be used, however should not be used for new care plans.
Patients which have care plans which were generated using the CDSS logic will continue to have the logic applied. However, new care plans will not be generated with this library asset.
dont-use
The object should not be used.
Effective immediately (when the state is indicated) no furher proposals will be generated with the assets in the library.
All library objects carry a metadata section which is used to provide information about the logic block, library, etc. Metadata is placed onto an object using the with metadata indicator or in the <meta> element.
Logic blocks are sections of the CDSS rule file which define one or more facts, rules, protocols, or other computable decision support assets. Logic blocks contain metadata which specify the context to which the contents of the block apply.
Logic blocks have the following contents:
Context: The object/resource to which the contents of the logic block applies
When Block: Which is used to further restrict the type of objects to which the logic block applies (for example, only apply to Female patients)
Definitions: Which are the facts, models, rules, and protocols of the logic block.
Logic blocks are defined with define logic ... end logic or the <logic> element, and have a format as illustrated below:
A fact represents a single piece of information which is known to be true based on data passed to it. A fact represents an instruction which can be used to extract information or make a determination about the state of data. Examples of facts can be:
The patient's gender
If the patient is under 5 years old
If an observation was not made within a time period
A fact is defined with the define fact ... end fact or XML element <fact> , and must carry either an ID or NAME. A fact can be computed using any of the Computable Expressions documented.
Facts can also be used to extract data in a consistent form, for example, a fact defining the age of the patient in years may be defined as:
Facts can be normalized according to one or more normalization rules. Normalization is useful when you need a fact to be translated from one format to another using a computation. Take, for example, a rule which may need to determine if an observation made was out of range, however needs to change units (for example weight). Such a fact should be normalized, for example:
Models are used when you wish to define a template of data which is reused. These are usually referenced from proposals, and they represent a fact which has a static, complex structure. Models are defined in the logic block with define model ... end model or the <model> element in XML.
Rules are defined within a logic blocks and represent a simple logic construct using when/then semantics. Rules are defined using the define rule ... end rule or the <rule> element in XML. The when block represents the trigger and is comprised of any computable expression. The then block is a collection of output actions which should be undertaken when the condition is true.
The structure of the rules is illustrated below.
When the CDSS engine's Execute() or Analyze() methods are invoked, all rules which are contained in the relevant logic blocks (which apply to the object being executed or analyzed). Rules are selectively applied when a ComputeProposal() call or GenerateCarePlan() methods are called based on the protocols which apply.
A protocol is a specialized form of a rule. A protocol has identical metadata to a rule, with the exception that a protocol can define one or more encounter scopes to which the protocol applies, and a protocol explicitly marks a rule as an "entry point" for a more complex series of care which result in the creation of a care plan.
Protocols can be used to represent:
Regular nutritional counseling for patients based on their weight/history
Regular vaccination recommendations for patients based on their age/history
A protocol always applies to PATIENT , protocols cannot be applied to contexts other than PATIENT.
Protocols are defined with the define protocol ... end protocol or <protocol> element.
Computable expressions are those expressions which are used to:
Extract data from a resource as the basis for a fact
Determine a boolean logic output for a when condition in a rule or protocol or as a block on a logic block.
Computable expressions are made against either the context (which is the input data) or the scopedObject which is the current action object. The scopedObject represents:
The input context object for facts
The output object of a proposal
The Health Data Service Interface Query computable expression uses the Health Data Service Query grammar to extract data or make decisions. HDSI queries are encapsulated in the hdsi() qualifier in CDSS text file or the <hdsi> element in XML.
The HDSI expression is either scoped to context meaning the input object to the analysis or the proposal which is the currently scoped object. HDSI expressions which are negated are those which have a NOT() operation applied to them.
Multiline expression:
Singleline expression:
There arise some instances in your decision logic where you must execute more advanced operations such as calculations, date subtraction, and string formatting. The CDSS engine allow the execution of a limited subset of expressions using the C# language. The subset allows for CDSS rule developers to:
Cast objects from the context as base types or resources
Perform mathematical operations
Perform Date calculations
Array functions (like Find, FirstOrDefault, etc.)
The C# expression handler has access to reflection disabled, and late object binding disabled. While this increases the security of the C# expressions, it does mean that all variables must be cast prior to use.
The current CDSS context object can be accessed with the context variable. context can be used to lookup facts and the output of rules which have been (or will be) executed. Context is used in the following manners
Lookup a fact from the current execution context.
context["name of fact"]
Get the value of a fact with a specified type
context.Int("name of fact")
context.String("name of fact")
context.Real("name of fact")
context.Date("name of fact")
context.Bool("name of fact")
Lookup a dataset from the context (see Querying Data Blocks)
context.DataSets["name of dataset"]
Cast a fact as a RIM based object
(Patient)context["name of fact"]
Access the input object (context's current execution target)
context.Target.DateOfBirth
Set a value of a fact on the context
context["name of fact"] = value of fact
There are other special variables which can be accessed in the C# interpreter including:
scopedObject which is of type IdentifiedData and always points to the current "in scope" object. If the C# appears in a fact definition this is the same as context.Target , if it appears in a propose statement it is the value of the proposal (the object that is being proposed)
value which is used when a normalize computation is written in C#.
There are three aggregate logic expressions which can be used to combine the result of multiple computable expressions. These are identiifed in the table below:
any(...)
OR
Returns TRUE when any of the contained facts or statements return TRUE or a non-null value.
all(...)
AND
Returns TRUE when all of the contained facts or statements return TRUE or a non-null value.
none(...)
NAND
Returns TRUE only when all of the contained statements are not TRUE or are a null value.
These logic statements can be combined to represent decision logic structures, for example, if we want to define a fact that is true when:
The Patient is Under 18 Months AND received the first dose of an antigen in their 17 months, OR
The Patient is Over 18 Months AND has NOT received any dose of the antigen
Facts can be referenced and combined using fact references. In the CDSS text file syntax, this is done by referencing the name of the fact in quotes. In XML this is done using the <fact ref="Name of Fact"/> element or <fact ref="#id.of.fact"/>.
Actions are used in rules and protocols as a series of steps which should be taken. These actions can:
Propose that some action or course of treatment be performed
Assign a value (such as an interpretation, or flag) on the existing object in scope
Raise an end-user alert which must be cleared prior to completing the encounter
Apply another rule or decision tree
Repeat certain actions for a specified number of iterations or until a condition is true.
The propose action is used to emit a proposal onto the current context. A proposal represents an Act which should occur (with a mood code of Propose).
Proposals are represented in CDSS text files with the propose ... end propose statement or in XML with <propose>. Proposals must carry a model (see models) and optionally a series of assign (see assign) statements to modify the model.
Actions can also assign computed, fixed values, or facts to a property on the scopedObject. When an assignment exists outside of a propose this means the assignment occurs on context.Target however within a propose the assignment is against the scoped (proposed) object.
Assignments are made using the assign ... to path syntax or the <assign> element in XML.
There are often times where a CDSS rule may wish to raise an alert to an end-user in the context of an encounter based on some clinical status of the patient or a previously observed value. This is done with the raise statement in CDSS or the <raise> element in XML.
The raise alert function will do three things:
When the CDSS engine is being called as part of analysis for a captured value (via Analyze()) it will be displayed to the user in their encounter capture screen.
When the CDSS engine is being called as part of a care plan generation, the issue is added to the care plan in the http://santedb.org/extensions/core/safetyConcernIssue extension.
When the CDSS engine is being called prior to discharge of the patient, the end user must clear (or acknowledge) the alert before discharging the patient.
One rule may be chained to another via an explicit call. This is useful for protocols where a series of rules needs to be executed in a specific order to create an appropriate care plan. Applying rules is performed via the apply statement or <apply> in XML.
Any action (proposals, assignment, raising, etc.) can be repeated a specific number of iterations (like a for loop) or until a certain fact becomes true or not null (like a while loop). Repeat actions are defined with the repeat ... end repeat statements or the <repeat> element in XML.
There arise occasions where a CDSS rules will need to reference pre-computed tables. Examples may include:
Standardized Z-Scores for "acceptable" observation values
Standardized age ranges for dosing and/or procedure schedules
Computation of offsets or unit conversion tables
In the SanteDB CDSS rule format, you can specify these reference sets in your library using a data block. Data blocks are defined with the define data ... end data or <data> element in XML.
All data blocks in the text CDSS rule format are uncompressed comma-separated-values. Data blocks in XML may either be a raw format CSV data block, or a base-64 blob representing the compressed CSV data using algorithm @compression.
Data blocks in a CDSS library are referenced in C# Computable Expressions by calling the DataSets property on the context object passing the dotted identifier or name of the dataset into the parameter as a reference. This can be done via:
Name of the data block such as context.DataSets["name of the data block"]
Id of the data block prefixed with a hash such as context.DataSets["#dotted.id.of.the.data.block"]
The data block reference will load the CSV data into the data context where the data can be filtered. Filtering is performed via a streaming reader on the CSV data so it is important that your data is sorted in the manner you're filtering. The operations which are available on the data set object are enumerated below.
Lookup up a row is performed with the Lookup(columnName, value), where columnName is the name of the column as it appears in the first row of the CSV data. For example, to look-up a gender based on a fact of Patient Gender the filter: context["Reference Ranges"].Lookup("gender", context["Patient Gender"]) .
The result of a lookup row is a filtered streaming reader. This can be chained with another lookup, for example, to filter on gender for those records matching Patient Gender and then filter on ageInWeeks on fact Patient Age in Weeks the C# expression: context.DataSets["Reference Ranges"].Lookup("gender", context["Patient Gender"]).Lookup("ageInWeeks", context["Patient Age in Weeks"])
The Between(columnName, lowerValue, upperValue) function can be used to filter the input reader for any rows where columnName is between the lowerValue and upperValue.
To select a column, the Select(columnName) function is used. This returns a numerator which can be used with any of the System.Linq operators (such as Average(), Sum(), Min(), Max(), etc.).
The expression evaluator used in SanteDB currently does not support generics. Use the functions SelectInt(columnName), SelectReal(columnName), or SelectLong(columnName) as an alternate to Select(columnName).OfType<>().
For example, to compute a fact for Patient Weight Below Average one may write:
LINQ aggregation functions which are useful for CDSS rules are enumerated in the table below.
Last()
Return the last non-null object in the reader, throw an error if no matching records exist.
LastOrDefault()
Return the last non-null object in the reader, return the default null if none found.
First()
Return the first non-null object in the reader, throw an error if no matching records exist.
FirstOrDefault()
Return the first non-null object in the reader, return null if none found.
.Select("column").FirstOrDefault()
Average()
Compute the average of all the matching column values.
.SelectReal("nominal").Average()
Sum()
Compute the sum of all matching column values.
.SelectInt("column").Sum()
Min()
Select the minimum value of matching columns.
.SelectLong("column").Min()
Max()
Select the maximum value of matching columns.
.Select("column").Max()
Single()
Select a single matching value from the result set, throw an error if more than one matching row exists, or if no row exists.
SingleOrDefault()
Select a sinle matching value from the result set, thow an error if more than one matching row exists, if no row exists return null.
