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. Ultimately you will need to supply the rules as a single file, and this is where merge comes in. The process is:

• Select File > New to create a blank rules file.
• Select File > Save As to give this file a new name
• 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.

Editing Rules

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.

Creating Rules

Core Properties

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

All rule types have these properties. The following goes into the specific properties for each rule type.

Importance Rules

Has a single additional property:

• 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).

A Note on Authoring

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)

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"