BAT

Summary

This enhancement to BAT extends the functionality of the Backend Automation Tool (BAT) to allow customers to implement Backend Automation Task (BAT) "scripts" to implement advanced RIS workflows without requiring source code changes.

Background

Previously, Feature #31786: Backend Automation Tool (BAT) Phase One introduced the concept of automation rules and the BATCollection RIS lookup table editor.

This initial phase of BAT functionality delivered the functionality necessary to support Feature #3168 - Electronic Lay Letter distribution, which allowed sending a Lay Letter via Print+Mail to a patient who did not access their electronic version of the letter. For additional background on this feature, review the eRAD RIS Service Release Notes 3.2022.6.20 document.

Additionally, Feature #32920 - Enhanced BATCollection RIS lookup table editor included in this release introduces an enhanced editor for the BATCollection RIS lookup table to improve the user experience when creating Backend Automation Task scripts.

The related Feature #34399 - Configurable delay before forwarding reports to Darena's BlueButtonPRO, also included in this release, serves as excellent example of a simple Backend Automation Task, and its implementation should be reviewed as a training exercise.

Intended Audience

The Backend Automation Tool is an extremely powerful and flexible utility. However, because these automation scripts are capable of directly reading and writing data to the database, implementing any script requires extreme caution and exhaustive testing.

Scripts should not be created or altered without explicit involvement and review by the:

·         Workflow owner, in consultation with the responsible business unit.

·         System Administrator.

·         Service Team, in consultation with the Development Team.

Feature Description

With this change, users can create custom SQL-based workflows as Backend Automation Task (BAT) scripts via the BATCollection RIS lookup table to implement advanced RIS workflows without requiring source code changes.

These workflows can be initiated by any number of events that occur in RIS, and can complete multiple actions without any user intervention either immediately or as a series of scheduled actions.

The Backend Automation Tool processes the workflow steps defined in the BATCollection RIS lookup table when triggered a RIS action identified in the QueueSubscription RIS lookup table.

A BAT "script" is a series of steps initiated by a RIS action.

Each of these workflows (can be thought of as a script) is composed of three elements:

1.       Queue Subscription - One or more RIS actions that will initiate processing of the BAT Collection.

2.       BAT Collection - A workflow.

3.       BAT Steps - A series of rules and actions to complete or continue the workflow.

Queue Subscription

The Queue Subscription defines all the RIS actions (events) that can "trigger" the initial execution of BAT Collections (scripts).

BAT Collection

Once a BAT Collection is triggered, its Inclusion Rule is evaluated to determine if all conditions are met to enter the workflow, and the initial BAT Step action is determined. It is important that the rule confirms that the triggering RIS action is correct.

Overview of the BAT Collection workflow.

BAT Steps

Each step begins by determining the scheduled time for the step's main logic to begin by processing the step's:

·         Parameter Calculation Rule - Optional logic initialize any @parameters (e.g. @patient_key) which may then be referenced by subsequent steps. Note that once initialized, these read-only values persist for the life of the BAT Collection.

·         Available Datetime Rule - Logic to define a scheduled time for the step to begin processing (it may be immediate).

Processing then waits until this time is reached and performs the step's:

·         Pre Workflow Rule - Optional logic that is executed prior to processing the action to determine if the Action should still be executed of if the workflow is aborted.

·         Action - The logic to be executed, after which the step's status is considered Complete.

·         Post Workflow Rule - Optional logic that is executed after the action has completed to determine the next step in the workflow. Note that this facilitates logic flow; for example, step 3 may identify step 1 as the next step. If blank, then the next step in the sequence is used.

Processing continues by initializing the scheduled time for the next step, and continues as long as a next BAT Step is identified (or an error occurs).

Overview of the BAT Steps workflow.

Operation

The Queue Subscription defines all the RIS actions (events) that can "trigger" the initial execution of BAT Collections (scripts).

Queue Subscriptions are created in the QueueSubscription Lookup Table, as child entries of the BAT Queue Name (which is named to match the value given to the BATQueueName service-level setting).

When adding subscriptions from the l_queue_subscription tab for BAT:

·         queue_name - Always use BAT.

·         main_action - Use <All> if necessary, but be as specific as possible.

·         Db_action - Use <All> if necessary, but be as specific as possible.

·         exclusion_flag - Use N.

As a performance consideration, note that all main_action and db_action items listed under this queue subscription will be picked up by the BAT service, but beware that some main actions fire much more frequently than others (e.g. UI_StudyUpdated)

Be as concise as possible when specifying which actions kick off the BAT workflow. Either specify a db_action for the corresponding main_action, or join the c_action table into your inclusion rule and check the main/db_actions manually in your query (e.g. where db_action not in ('…', …)).

A separate BAT Collection is defined for each workflow. The BAT Collection includes the rules necessary to enter the workflow.

When any subscribed RIS event occurs, it triggers each BAT Collection's Inclusion Rule to be evaluated to determine if all conditions are met to begin the workflow. The rule would typically include logic to:

·         Confirm the Queue Subscription action that trigged the rule is relevant for the workflow.

·         Evaluate any other business rules to determine if the workflow should begin.

·         Determine which Step (integer) the workflow should begin with.

If the rule returns a valid Step integer, it triggers the workflow to begin with that step.

When adding a BAT Collection:

·         Bat Collection Code - Uniquely identifies the BAT Collection that will complete the task.

·         Description - In addition to identifying the purpose of the rule, it is recommended to identify the owner/manager of the rule and reference any external documentation.

·         Inclusion Rule - SQL that determines if the BAT Collection should be executed (by returning the initial BAT Step to be executed as a positive integer), or not (by returning a negative integer).

·         Active - When N, both the collection and all BAT Steps currently in process are disabled.

Each BAT Collection includes one or more BAT Steps. Each BAT Step includes the rules and actions necessary to complete or continue the workflow.

BAT Steps do not need to run sequentially. Each step can include validations to determine if the task should execute or abort, branch and loop, and potentially even create additional follow-up tasks.

The BAT Steps rules and actions are scripted in SQL. The SQL code not only drives the logic of the script itself, but can also perform database-level actions. Scripts have full access to run any TSQL statements, stored procedures, scalar functions, and can select/update/delete data directly from the database.

This makes the BAT framework an extremely powerful tool that allows the Service Team to implement and modify custom RIS functionality without modifications to the RIS source code.

Each BAT Step first evaluates its Available Datetime Rule to calculates when its Action should occur, performs that Action, and then evaluates its Post Workflow Rule to determine what the next step in the workflow should be.

Additionally, the BAT Step may evaluate a Parameter Calculation Rule to cache or pre-calculate values to be referenced later, and a Pre Workflow Rule with additional logic.

When adding BAT Steps:

·         Bat Collection Code - Ties the BAT Step to the BAT Collection.

·         Step - Uniquely identifies the BAT Step. Note that step numbers do not necessarily determine execution sequence.

·         Description - Documents the step's logic.

·         Active - When N, the step is disabled.

·         Available Datetime Rule - Identifies the time the step is scheduled for execution. If not specified, the Action will execute immediately.

·         Parameter Calculation Rule - Optional SQL code to cache or pre-calculate any @parameters (e.g. @patient_key) to be referenced by the step's Action or rules (including Available Datetime Rule). Note that these values are calculated when the BAT Step is initialized, rather than at the time the Action is executed (as determined by the Available Datetime Rule).

·         Action - The SQL code to be executed at the pre-determined datetime.

·         Pre Workflow Rule - Optional SQL code executed prior to processing the action. Typically, the rule determines if conditions are still appropriate and the Action should be executed (by returning a positive integer), or if the workflow should be aborted (e.g., the patient has cancelled their exam), skipping the Post Workflow Rule and all subsequent BAT Steps (by returning a negative integer).

·         Post Workflow Rule - Optional SQL code executed after the Action has completed that typically includes identifying the next step to be executed (by returning the next Step as a positive integer) or discontinuing the script (by returning a negative integer).

Known Limitations

The following new Known Limitations have been identified and should be communicated to affected users:

·         Known Limitation (from #31787) - Column width display issue with BATCollection lookup

o    Issue: Each time the BATCollection lookup is opened, column widths revert to a very narrow setting.

o    Impact: Display issue.

o    Workaround: Manually resize columns.

Service Team Upgrade Instructions

Configuration Instructions

System Administrators must complete the following actions to enable this feature and Service Team assistance is required for some actions:

RIS Client

Changes to QueueSubscription Lookup Table Settings

Create a queue subscription to define the specific RIS action(s) that will initiate the workflow:

1.       Confirm the following row exists in the QueueSubscription RIS Lookup Table, or add it if not:

1.1.     Queue Name = BAT

1.2.     Description = Actions that will initiate BAT Collection workflows.

1.3.     Queue Rows to Acquire = 10

Changes to BATCollection Lookup Table Settings

Summary

This enhancement to BAT introduces an enhanced editor for the BATCollection RIS lookup table for editing Inclusion Rules and Actions. The editor adds functionality to select the rule type (currently limited to SQL), select a rule template, edit rule text, and insert predefined parameters into the rule.

Background

Previously, Feature #31786: Backend Automation Tool (BAT) Phase One introduced the concept of automation rules and the BATCollection RIS lookup table. However, this feature did not supply an editor for rules.

With the introduction of Feature # 31787 - Backend Automation Tool (BAT) Phase Two - Rules, the ability to more easily create and edit advanced rules was desired.

Feature Description

The enhanced editor for the BATCollection RIS lookup table can be accessed by right-clicking an Inclusion Rule, Parameter Calculation Rule, Available Datetime Rule, Pre Workflow Rule, Action, or Post Workflow Rule:

The BAT Rule Editor offers more functionality than the grid's edit in place or the Edit in Popup options.

The BAT Rule Editor editor includes functionality to select the rule type (currently limited to SQL), select a rule template, edit rule text, and to insert predefined parameters into the rule:

1.       Rule Type - Although currently limited to SQL, future enhancements may support other options such as JavaScript or C#.

2.       Template - Pre-defined rules that may be loaded. The list of available templates is currently hard-coded, although future enhancements may allow customization. Note that the scripts provided as templates are a convenience; these scripts can easily be manually created instead and are typically modified once inserted.

3.       Rule text editor - A simple scrollable text editor window.

4.       Parameters - Double-clicking any of the pre-defined parameter fields will insert them at the cursor position.

5.       Format - Reflows the rule text with appropriate indentation for improved readability.

Note that a Post Message Template for each of the available parameters has been created as a basis for new scripts.

The Post Message Template for Inclusion Rule.

Known Limitations

The following significant limitations have been identified and should be communicated to affected users:

·         Expected behavior by design (from #32920) - The list of templates cannot be customized

o    The list of available templates is currently hard-coded, although future enhancements may allow new templates to be added by administrators.

Configuration Instructions

No System Administrator actions are necessary to enable this feature; however, optional configuration is available:

RIS Client

Changes to RIS AccessString Lookup Table Settings

·         Grant Config.LookupEditor.BATCollection permissions as necessary.