Automation Actions
A JavaScript based automation action step is a method to perform custom actions to automate complex tasks and perform custom logic within a larger automation workflow.
We provide a rich API to report the status and details of the step that has been executed. Within an action script, we also have access to powerful APIs to access the monitored system and perform complex actions. In addition, we always have access to the following building blocks:
-
Access parameters set in Avantra for the monitored object this action is run on to control the logic.
-
Access to a simple HTTP client to call web services to validate operations or perform actions.
Code Walkthrough
The action API is very simple to use and is only present to allow you to log details of your logic to tell your users what the step did and to report the outcome of the step, whether it was successful or not.
Check out the building blocks relevant to the monitored system this action is run on for details of affecting the system in question.
Reporting Status
There are three simple properties of the action global variable that allow developers to pass status back to the user. This example shows how to use each:
// The message should be concise as it is displayed on the
// `Execution Output` of the step in the Avantra UI.
action.message = "This is a message from an action";
// Set the success of the action. The default is true = OK
action.success = true;
// If an error occurs set this to false like below:
// action.success = false;
// We use this to generate 100 lines of log output
// - The format is `This is log line 1` etc.
// in real automation actions, this could be the output from
// an SAP RFC call, or an Operating System program execution.
const log = Array.apply(null, Array(100))
.map((line, i) => `This is log line ${i+1}`)
.join("\n");
// The action details can be displayed in the `Details` tab
// when displaying the Automation Execution and can be much
// longer to give more details on what was performed:
action.details = log;
Using Parameters
When running in the Automation Step Library, actions have access to two additional
variables action.input
and action.output
. These variables allow the developer
to programmatically read the parameters configured in the JavaScript step.
const fileToRead = action.input.myFile;
if (fileToRead) {
// ... do something
}
// Output results:
action.output.fileName = "myFile";
Best practice is for parameters to be named with alphanumeric characters and
starting with a letter. This is so we can use the dot notation above to access
their values. Starting a variable with a number requires the developer to use
bracket notation, e.g. |
Examples
The example uses the SAP API to call a remote function module (RFC) to unlock a user in the system.
// Read the user to unlock and the client from our input variables
// -- or take the defaults chosen.
const sapClient = action.input.sapClient || "001";
const userName = action.input.userName || "TESTUSER";
// Execute the function module BAPI_USER_UNLOCK
const unlockFn = sap.login(sapClient)
.getFunction("BAPI_USER_UNLOCK")
.withParameter("USERNAME", userName)
.execute();
// This function module returns messages through RETURN table
const msgs = unlockFn.result("RETURN");
// To work out if we had an error, we look at the TYPE column
const hasError = msgs.map(msg => msg.TYPE)
// Filter out those that are success messages or warnings (S/W)
.filter(type => type != "S" && type != "W")
// If we have any messages left, we have an error!
.length > 0;
// Set the success of the action as the opposite of hasError!
action.success = !hasError;
// Output a high-level message depending on if we have errors
if (hasError) {
action.message = "BAPI_USER_UNLOCK had errors!";
} else {
action.message = "BAPI_USER_UNLOCK succesful!"
}
// Loop again through the logs and extract only the MESSAGE
// table field. Then join together with newlines for the log.
const msgLog = msgs.map(msg => msg.MESSAGE).join("\n");
action.details = "Messages:\n" + msgLog;
API Reference
Global Variable action
The action global variable allows access to set the result of the action. Use the properties to influence the outcome of the automation.
setDetails(..)
setDetails(details: string): void
Use this to set detailed information (available in the logs) for debugging and analysis of the automation step.
- Parameters
-
-
details
: stringfurther details of the step
-
- See Also
setMessage(..)
setMessage(message: string): void
Use this to set a message to inform users of what happened in the automation step.
- Parameters
-
-
message
: stringinformation to report back to the user about what happened
-
- See Also
setSuccess(..)
setSuccess(success: boolean): void
Use this to set the outcome of the automation step. Always set a message to inform users of why this status was set.
The default value is true
.
- Parameters
-
-
success
: booleanfalse only if the automation step failed
-
- See Also
details
details: string
Use this to set detailed information (available in the logs) for debugging and analysis of the automation step.
- See Also
- Type
-
string
input
readonly input: object
Access the values of the input parameters of an automation step.
This object holds the input parameter values that have been passed to this workflow step as constants or workflow inputs or values from previous steps.
This object is accessed as a regular JSON object with the objects keys as the parameter names.
For example, when the input parameters systemType
, tableName
and
tableData
are configured for the step, this is how they can be accessed
in the script:
// Check if we are running on HANA:
if (action.input.systemType === "HANA") {
// ... do HANA specific logic
}
// Read the required table from parameters or use the default:
const table = action.input.tableName || "Z_DEFAULT_TABLE";
// Read any input table data:
const data = JSON.parse(action.input.tableData);
- Type
-
object
- Modifiers
-
Readonly
- Since
-
21.11.4
message
message: string
Use this to set a message to inform users of what happened in the automation step.
- See Also
- Type
-
string
output
readonly output: object
Set the values of the output parameters (result) of an automation step.
This object holds the values that will be returned to the automation workflow and can be used in subsequent steps or as an output of the workflow itself.
This object is accessed as a regular JSON object with the objects keys as the parameter names.
For example, when the output parameters tableData
and tableCount
are
configured for the step, this is how they can be accessed in the script:
const records = [];
// ... Query SAP and fill the records array ...
// Output the number of records found:
action.output.tableCount = records.length;
// Output the record information for further processing
action.output.tableData = JSON.stringify(records);
Note the object is a read only property which means you cannot directly
assign a new JavaScript object in your script to action.output
. However
you can change property values on the object as described above.
Care should be taken to match the variable type of the output parameters.
You can use |
- Type
-
object
- Modifiers
-
Readonly
- Since
-
21.11.4
Global Variable log
Log utilities for automation steps.
log(..)
log(msg: string): void
Output a log message to this Workflow’s execution log.
The execution log is updated while a step is executing, so it’s an ideal way to show the progress of a long-running step to a step user while it’s running.
log.log('Step 4 of 5 completed!')
- Since
-
23.1
- Parameters
-
-
msg
: stringthe message to log
-