Rules Editor

This topic is for AquilaCRS

Introduction

• AquilaCRS contains a sophisticated rules-based validation engine.
• The rules are authored by the dataset designers for each clinical speciality and are stored in the database.
• Rules can be remotely updated from data files provided via the Internet.
• The Rules Editor software can be used to create & edit these files.

File Operations

Basic operations

Namely: File New, Open, Save, Save As, Close & Exit

• Allows the user to open rules files in the editor.
• Each file opens in a new tab.
• New files will prompt for a filename on first saving
• File > Save As will ask for confirmation before saving to a file that already exists. If you agree, then the existing file will be overwritten. There is no undo
• To make a copy of a file open it in the Rules Editor, and then immediate choose File > Save As & give the file a new name/location.

Merging Two Rules Files

It can be useful to isolate your rules in two or more files for the purpose of clarity & authoring. Ultimately you will need to supply the rules as a single file, and this is where merge comes in. It's best to start with a new, empty rules file and merge it with the other files.

The process is:

• Select File > New to create a blank rules file.
• Select File > Save As to give this file a new name, e.g. "All Rules.json"
• Select Tools > Merge rules file and select an existing Rules file
• Repeat the above step for each file you wish to merge.
• Once you have merged all your required files, choose File > Save.

Importing from F_Importance files

• F_Importance files are a tab delimited file defining Importance Rules & originate from the F_Importance table in the IBID Design database
• F_Importance files consist of 3 columns, in order:
  • [Table Name]
  • [Field Name]
  • [Importance]
• Importance is an integer value betwee 1 & 3.

Select Tools > Import F_IMPT file from the menu and select the file you wish to convert. It will appear as a normal rules file in the editor. You will be asked to choose a file name when you first save the file.

Rules Display

• The rules are displayed in a tree format.
• The first level node is the name of the set of rules.
• The second level nodes are the tables.
• Grouped beneath the table nodes are the fields for that table
• Beneath the fields nodes, are the rules for that field.

Nodes can be expanded or collapsed by clicking on the triangle icon next to the node, or by double clicking on the node. There are also Collapse all and Expand all options

Rules Header

• Click on the top-level node and the Rules Header information will be shown.
• The rules header consists of various tags.
• The Version tag is mandatory. This is checked by the AquilaCRS clinical application when checking online for new rule versions.
• The ImportanceVersion tag is mandatory for files that are imported from F_Importance files. This is the version from the F_Importance file.
• The Title tag is optional, and is just for display purposes in the rules editor.
• Additional tags can be created for your own use - use sparingly as they will increase file size, and thus download size.

Sets of Rules in Aquila

There are 3 sets of rules within the Aquila Care Records System:

• iBID Importance Rules
• AquilaCRS Validation Rules
• Custom Rules

As the application loads, these rule sets are loaded in the above order and merged with each other.

The exception to this is the Importance Rule type; there can be only one Importance Rule type for any given field.

For example; an Importance Rule for ADMISSIONDATE in the AquilaCRS Validation Rules will overwrite the importance rule from the IBID Importance Rules set.

iBID Importance Rules

• This set of rules is directly controlled by the IBID Design Database team.
• It is remotely updated and cannot be edited, as the whole set of rules could be overwritten with any new release.

AquilaCRS Validation Rules

• This set of rules forms part of the core application.
• This set is remotely updated and should not be edited, as the whole set could be overwritten with any new release.

Custom Validation Rules

• Supplied empty with a new system.
• System Administrators can create new rules to implement the trusts own validation logic.

Creating and Editing Rules

Rules Properties Common To All Rule Types

Every rule will have the following properties:

• Table and Field name: the name of the objects in the database that define the field that requires validation against this rule.
  • It is vital that there are no typos or other mistakes. The validation engine will not warn if a specified field does not exist.
  • Aliases for table names are allowed in some cases - please contact technical support for more info.
• Category: defines the level of validation message that is raised in the event of a validation failure. E.g. Critical, Error, Warning or Information/Hint.
  • Note that in come cases, Critical level rules could prevent the user from closing a data-entry form
• Conditions: See below.

Rule-Conditions

• A set of rules that refer to other fields in the record. The
• If the conditions evaluate to TRUE, then the Field Rule will validated.
• You can specify if all conditions must be met (logical AND), or any of the conditions (logical OR) before the rule is run.
• E.g. the rule may specify that Admission Date is a required value. You may make this rule conditional on the fact that the Initial Action was "Accept for Admission", (or some other indication that the record type is an admission).
• CAUTION: whilst the editor allows reference to any combination of fields in the list of conditions, clearly you must restrict your conditions to fields that exist within the same logical record structure.
  • For example, it's okay to have a field rule for IBID Admission Date, and have this conditional on an IBID Causation, or IBID Record Type field (for example).
  • But it's not okay to have a field rule for IBID Admission Date and have this conditional on an Image type of JPEG. (as there's no actual link between the two).
  • See "Authoring Conditions or Field Comparisons" below for more specific information.

All rule types have the above properties. The following sections go into the specific properties for each rule type.

Editing Conditions

• Create a new condition by clicking on the New ▼ button & selecting the type of condition. This can be changed later.
• To edit an existing condition, click on the Edit... button at the end of the row.

The Condition Editor

The condition editor has the following fields:

• Table Name' & Field Name: specifies the exact name of the database object to test. See Authoring Conditions or Field Comparisons below for important information on these properties.
• Operator: select the method of comparison
• Unary Op: select if this condition is to be a logical NOT. Leave as Default otherwise.
• Value Type:
  • Character Value : compares the field against a single string of any UTF-8 allowed characters. Leave empty to test for an empty string. (Note, this is not NULL)
  • Numeric Value : compares the field against any single decimal or integer value.
  • Null Value : compares the field against NULL. This is the way to test if a field is NULL. Use the NOT unary operator to test for NOT NULL.
  • Multiple Values: Compares the field against any of a number of character values. Very useful to test if a lookup field is any one of a number of values. (Can also be used for numerical values). Enter one value per line. Empty lines are ignored - please use a separate condition for NULL & Empty Str.

• The copy and paste buttons (lower left) can be used to copy specific conditions between rules.
  • Click the copy button to copy the current contents of the condition rule to the Windows clipboard.
  • Pressing the Paste button *will* overwrite the contents of the condition editor with the clipboard contents.

Rule Types

Importance Rules

• There can be only one Importance Rule per field in the database.
• The last importance rule loaded for a field will take precedence.
  • Rules are loaded in the following order:
    • IBID Importance Rules
    • Aquila Validation Rules
    • Custom Rules

The importance rule has one additional property over the common rule properties outlined above:

• Importance, that defines whether a field value is required or not, and to what level.

Pattern Match Rule

• Standard Reg Ex: specify the name of a built-in expression by selecting from the lookup list.
• Custom Reg Ex: specify a custom regular expression. If you don't know what a regular expression is, then don't use this field.

Date Range Rule

• Offset Days Min: specifies the allowable number of days in the past (using the current date as the starting point). For years, use the drop down calculator to multiple by 365.25. E.g. 125 years is roughly 45656 days.
• Offset Days Max: same principle as the Offset Days Min, but allows dates to be a certain number of days in the future. To disallow future dates, set this to be zero.

If the Offset Days Min and Max are zero, then the rule will use the Static Date limits (see below)

• Static Date Min: sets a fixed date in the past that the field entry is not allowed to exceed. To ensure the date does not occur before or after another field in the record, use the Compare Field Rule. The date must be entered in the ISO 8601 format: YYYYMMDD. E.g. 19860513 for 13th October 1986.
• Static Date Max: sets a fixed date in the future that the field entry is not allowed to exceed. Use the same ISO-8601 format as Static Date Min.
• Use of the Offset Days will render the Static Dates unused. To ensure use of the Static Dates please set the Offset Days Min and Max to zero.

Number Range Rule

• Min: sets a minimum value for a field. Can be whole numbers or decimal. Useful for measurement recording & scoring fields
• Max: sets a maximum value for a field.

Compare Field Rule

• Table Name: the name of the table object in the database in which the field to compare exists.
• Field Name: the name of the field object within the table specified. Exact table and field names are required.
• Operator: the type of comparison to use, e,g. greater-than.
• This rule is useful for ensuring valid data in two fields that may be related. For example the Systolic and Diastolic BP, or the Admission and Discharge Dates. You can use this type of rule to raise and error (or worse) if one value is greater than the other (or vice versa).
• See "Authoring Conditions or Field Comparisons" below for more specific information.

Condition Rule

• Implements pass or fail logic based on comparing the field value with a static condition. E.g. must be greater than 2.
• Can be combined with the rules own run-conditions (see earlier) to produce rules such as "Must be greater than 2 if <another-field> is less than 1"
• See "Authoring Conditions or Field Comparisons" below for more specific information on writing conditions.

Appendix A: Limitations

Authoring Conditions or Field Comparisons

Please note that it is not possible to compare fields outside of the context of the current record. Relational links must exist between the core field and the comparison (target) field must be at the same or higher relational level in the hierarchy.

Examples

• Compare IBID_REFERRAL fields with IBID_CAUSATION fields: TRUE - the source and target field are at the same relational level & links exist.
• Compare IBID_REFERRAL fields with PATIENTS_NAME fields: TRUE - the target field is higher up the hierarchy & links exist between them.
• Compare IBID_REFERRAL fields with EPR_MEDIA (images) fields: FALSE - there is no direct relational link between the two tables.
• Compare DEPENDENCY fields with IBID_REFERRAL: TRUE - there is a direct relational link and the target is higher up the hierarchy.
• Compare IBID_REFERRAL fields with DEPENDENCY: FALSE - there is a direct relational link, but the target is lower down the hierarchy and so there could be multiple records to compare against. (In this case it could be possible to reverse the logic and implement the checking at the Dependency level)

Appendix B: Dynamic (Calculated) Fields

All of the iBID Analysis is done on the application server only after the iBID record is closed so is not available for real-time validation. Some of the more useful analysis type data is available in software version 2.7 and up.

Date/Time Combination Fields

The date and time values in iBID are typically recorded in separate fields. The "Date/Time" fields below combine the values into a single date/time value that is very useful in field comparison rules to ensure correct chronology down to the minute.

Count of Yes/No Fields

An iBID record has many yes/no fields that are often related, for example the Causation Association section. The fields below provide a count of the Yes values within those sections. In some cases, there are multiple calculated fields provided for the same section differentiated by severity or other attribute. These fields can be used to enforce a type of rule that states "at least one value from this section must be selected" by using a "Field > 0" type rule.

Other Fields

An iBID record has many fields that can indicate a patients death (26 fields in total). This makes creating rules based on this impractical. The DEATH_CALC field consolidates those fields into a single 1 or 0 value.

The following fields were introduced in version 2.7

Table Name	Field Name	Data Type	Details
IBID_CAUSATION	DATETIMEOFINJURY_CALC	Date/Time	Combines the DATEOFINJURY and TIMEOFINJURY values into a single field containing a single date/time value.as ADMISSIONDATETIME_CALC
IBID_REFERRAL	ASSESSMENTDATETIME_CALC	Date/Time	Combines the ASSESSMENTDATE and ASSESSMENTTIME into a single field.
IBID_REFERRAL	REFERRALDATETIME_CALC	Date/Time	Combines the REFERRALDATE and REFERRALTIME into a single field.
IBID_ADMISSIONDISCHARGE	ADMISSIONDATETIME_CALC	Date/Time	Combines the ADMISSIONDATE and ADMISSIONTIME into a single field.
IBID_ADMISSIONDISCHARGE	SEENBYDATETIME_CALC	Date/Time	Combines the SEENBYDATE and SEENBYTIME into a single field.
IBID_ADMISSIONDISCHARGE	CONSULTANTSEENBYDATETIME_CALC	Date/Time	Combines the SEENBYCONSDATE and SEENBYCONSTIME into a single field.
IBID_ADMISSIONDISCHARGE	DISCHORDEATHDATETIME_CALC	Date/Time	Combines the DISCHORDEATHDATE and DISCHORDEATHTIME into a single field.
IBID_ADMISSIONDISCHARGE	DEATH_CALC	Integer	This field returns 1 if either the Death field is true, the Post Mortem field is true, the Discharge Destination = Mortuary or any Cause of Death has been selected. If none of the previous are true, it will return 0 indicating "no death".
IBID_CAUSATION	ASSOCIATION_CALC	Integer	A count of all the Yes values in the Causation > Association group. E.g. 2 fields are Yes, this field will have a value of "2".
IBID_CAUSATION	CONTRIBUTOR_CALC	Integer	A count of all the Yes values in the Causation > Contributor group.
IBID_CO_DISORDERS	EXDIS_RESUSC_CALC	Integer	A count of the Yes values in the Co-existing Disorders section, that have a resuscitation implication.
IBID_CO_DISORDERS	EXDIS_COMPLIC_CALC	Integer	A count of the Yes values in the Co-existing Disorders section, that are a possible complication.
IBID_CO_DISORDERS	EXDIS_PSYCH_CALC	Integer	A count of the Yes values in the Co-existing Disorders section, that have a psychological nature.
IBID_CO_DISORDERS	EXDIS_MINOR_CALC	Integer	A count of the Yes values for minor conditions in the Co-existing Disorders section.
IBID_CO_DISORDERS	EXDIS_SIG_CALC	Integer	A count of the Yes values in the Co-existing Disorders section that are deemed significant. This is the combination of resusc and complications.
IBID_CO_DISORDERS	EXDIS_TOTAL_CALC	Integer	A count of all the Yes values in the Co-existing Disorders section.
IBID_INHALATION	AIRWAY_SYMPTOMS_CALC	Integer	A count of all the Yes values in the Airway > Signs & Symptoms section.
IBID_RESUSCITATION	RESUSC_PROCEDURES_CALC	Integer	A count of all the Yes values in the Resuscitation > Procedures Used During Resusc section.
IBID_RESUSCITATION	RESUSC_COMPLICATIONS_CALC	Integer	A count of all the Yes values in the Resuscitation > Complications of Resusc section.
IBID_COMPLICATIONS	COMPLICATIONS_MODERATE_CALC	Integer	A count of all the Yes values in the Complications section that are deemed of moderate severity
IBID_COMPLICATIONS	COMPLICATIONS_SEVERE_CALC	Integer	A count of all the Yes values in the Complications section that are deemed severe.
IBID_COMPLICATIONS	COMPLICATIONS_INFECTIVE_CALC	Integer	A count of all the Yes values in the Complications section that are of an infective nature.
IBID_COMPLICATIONS	COMPLICATIONS_TOTAL_CALC	Integer	A count of all the Yes values in the Complications section.
IBID_COD	COD_INFECTIVE_CALC	Integer	A count of all the Yes values in the Discharge > Causes of Death section, that are of an infective nature.
IBID_COD	COD_OTHER_CALC	Integer	A count of all the Yes values in the Discharge > Causes of Death section
IBID_COD	COD_TOTAL_CALC	Integer	A count of all the Yes values in the Co-existing Disorders section.

The following fields were introduced in version 2.13

Table Name	Field Name	Data Type	Details
IBID_INHALATION	INTUBATEDDATETIME_CALC	Date/Time	Date and time of intubation combined
IBID_FOLLOWUP	FOLLOWUPDATETIME_CALC	Date/Time	Date and time of follow up appointment combined
IBID_INHALATION	BLOODGASDATETIME_CALC	Date/Time	Date and time of blood gas tests
IBID_INHALATION	CYANATEBLDDATETIME_CALC	Date/Time	Date and time of Cyanate Blood test
IBID_INHALATION	BS_BLOODGASDATETIME_CALC	Date/Time	Date and time of first Burn Service blood gas test
IBID_RESUSCITATION	RESUSCSTARTDATETIME_CALC	Date/Time	Date and time of start of resuscitation