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.
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
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:
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.