Automation Engine Overview
The Automation Engine is a feature within Common that allows for the registration and execution of logic that can be executed from events on DSP® pages. This logic is driven based on the runtime substitution of variables before execution and is designed to abstract the execution of logic across different technologies, e.g., Oracle, SQL Server and SAP Data Services.
NOTE: This article applies to BackOffice Associates® Solutions versions 6.0 and later.
Intended Audience
This article is for developers who are using the automation engine feature. It assumes advanced knowledge of DSP navigation and functionality.
Support
Custom development using the automation engine is permitted; however, it is not covered by standard Product Support. Refer to a technical lead for customization troubleshooting. If you believe there is a bug in the feature as implemented in the delivered product, report the bug to Product Support using the standard Support notification process.
This article contains the following sections:
Configure the Automation Engine
To configure the Automation Engine:
Add Instructions
An automation instruction is a single unit of work to be performed by the engine. Some examples of instructions are create a table, add a column to a table, update data, and create a view. To create an instruction, add a record to the Automation Instructions page (Common > Automation Engine > Automation Instructions). The automation instruction record serves as a generic representation of a step to perform.
NOTE: If the DSP Supplied column is checked for an instruction, it was installed with the platform and cannot be edited.
After adding the record, define the instruction by type. (Currently the only supported type is SQL). Click the SQL icon on the Automation Instructions page to access the Automation Engine - SQL page, where PreCheck SQL and SQL are defined.
- Pre Check SQL – SQL that is used to determine if the instruction execution should proceed. The engine will execute the Pre Check SQL and if 1 or more records are returned, it will NOT execute the statement in the SQL field. This Pre Check SQL allows a user to provide checks and control if SQL is run.
- SQL – The SQL instruction that is run to perform the action.
Regardless of Pre Check SQL or SQL, the user can use the ## dynamic substitution syntax in order to provide runtime values to the rule. As an example:
CREATE VIEW [web#TableName#Sel]
AS
SELECT * FROM #TableName#
Add Tasks
A task is a grouping of instructions that are run in order. When the automation engine is run, it is run for a task, task group, or automation engine action.
Instructions are registered to a task and execute in priority order.
To create a task, add a record to the Automation Instruction Task page (Common > Automation Engine > Automation Instruction Task). Enter a Name and a Description for the task, then register a Data Rule Data Source ID and a Data Rule and/or a Data View Data Source ID and Data View to it.
The Data Rule Data Source ID defines the Data Source in which the Data Rule exists. When a task is executed, the automation engine executes the Data Rule in the Data Rule Data Source. To this rule, it passes the unique Execution ID of the automation engine execution as well as any parameter values that match the column names from the DSP page from which the plugin is called.
For example, a DSP page contains the columns CustomerID, Name, and Address. The Data Rule contains the parameters @ExecutionID uniqueidentifier and @CustomerID int. When the automation engine runs, it passes in the unique ExecutionID as well as the CustomerID to the rule. The purpose of this rule is to populate the AutomationEngineData table. It is from this table that the engine retrieves the dynamic substitution #Name# | #Value# pairs.
Alternatively, the user can use a Data View and a Data View Data Source ID. If using a Data View, the automation engine selects the values from the view that match the binding criteria + keys from the calling pages. It then executes each found row in the view as a unique set of Key|Value pairs through the engine. This means if there are 5 rows, the task runs 5 times using the data from each row in an execution. When executing using the Data View, the Key value of the substitution is the column name and the Value is the value for that column.
Add Task Groups
A task group is a grouping of tasks that execute in a particular order. Task groups are used if multiple tasks need to be strung together in one execution of the automation engine. They also allow for the reuse of a task among different task groups. After adding a task group on the Automation Instruction Task Groups page (Common > Automation Engine > Automation Instruction Task Group), register one or many tasks to the group.
Add Automation Engine Actions
An automation engine action is the method by which the execution of a task or task group is abstracted from a DSP page. The automation engine action represents a registration that ties a task or a task group to a generic action. When an automation engine execution occurs, the calling page can pass in the ID of an action, at which point the engine reads the AEID and performs the execution of the task or task group represented by that ID. Refer to the Execution section for more details.
Execute the Automation Engine
To execute the automation engine, register the automation engine’s public plugin [DSP: Automation Engine Execution Adapter] to a DSP page and add the input columns to the page.
NOTE: These columns can be hidden but must be named exactly for the input parameters.
The plugin has the following inputs:
- AEID — ID value of the task or task group to execute
- AEActionID — ID value of the automation engine action to execute
NOTE: AEID and AEActionID are not both required. One or the other must be passed through the plugin.
- AETargetDataSourceID — DataSourceID against which the instructions should be run
- AEExecutionID — Uniqueidentifier that uniquely identifies the execution of the automation engine
- AEFormStatementOnly — Bit flag that, if true, forms the instructions, but does not execute the logic. The text of the instruction is stored in Common and can be extracted using the apiAutomationEngineHistorySql view. If not passed, the value defaults to FALSE.
- AEContinueOnError — Bit flag that, if true, causes the automation engine to continue processing after an error in execution has occurred. If not passed, the value defaults to FALSE.
- AEReplaceBooleanAsInt — Bit flag that, if true, causes the automation engine to replace Boolean values as integers when performing the dynamic replacement. As an example, if set to TRUE the following replacements occur:
IF(shouldExecute = #ExecuteFlag#) è IF(shouldExecute = 1)If not passed, this value defaults to TRUE
When the shared plugin is called, it first checks to see if an Automation Engine Action ID has been passed. If it has, then the engine reads the AEID and other settings from the Automation Engine Action page. If an Automation Engine Action ID has not been passed, the AEID is read from the passed in value. The engine takes the AEID and looks up the registrations for the task or task group and performs the execution of the instructions in priority order. Each instruction that is executed has the logic that is executed written to the Automation Engine History table.
In order to allow for the creation of Data Rules, two API procedures have been provided:
- apiAutomationEngineDataDel — This procedure deletes AutomationEngineData records for a given ExecutionID
- apiAutomationEngineDataIns — This procedure inserts data into AutomationEngineData for execution by the engine
In order to view the history of the Automation Engine execution, the below API view has been created:
- apiAutomationEngineHistorySel — API view used to select out the history from the AE.
Example
See below for an example of how to insert records into a table using the automation engine.
Instruction
Task
View
