Step execution scripts
Summarize
Summary of Step execution scripts
Step execution scripts in ServiceNow define the behavior of individual steps within a step configuration record. These scripts control how steps process inputs, produce outputs, and determine success or failure during execution. They are essential for customizing automated workflows and integrations to meet specific operational needs.
Show less
Step Inputs and Outputs
- Inputs: Defined in the inputs related list of the step configuration, input variables are accessible within the script via the
inputsparameter (e.g.,inputs.var1). - Outputs: Defined in the outputs related list, output variables are accessed and set through the
outputsparameter (e.g.,outputs.out1), enabling the step to pass data forward.
Controlling Step Result
The stepResult parameter provides an API to control the step's outcome:
stepResult.setSuccess()marks the step as successful.stepResult.setFailed()marks the step as failed.stepResult.setOutputMessage(message)sets a log message for the step; if called multiple times, the last message overrides previous ones.
Example Scripts
- Record Query Step: This script queries a specified table with encoded query conditions from inputs. It passes the step if records are found, sets outputs with the table name and first record ID, and logs a message indicating the number of matching records. If no records are found or if required inputs are missing, it fails the step with an appropriate message.
- Custom Scripted Step with Timeout: This script waits asynchronously for a condition (e.g., completion of asynchronous logic) up to a specified timeout. It polls once per second, logging wait progress. If the condition is met, the step passes; if the timeout is exceeded, the step fails with a timeout message.
Practical Application for ServiceNow Customers
By leveraging step execution scripts, customers can implement complex logic within automated test frameworks, workflows, or integration steps. The ability to handle inputs, outputs, and execution results programmatically enables precise control over process automation and error handling. Examples provided demonstrate how to query records or manage asynchronous operations effectively.
Additionally, the note clarifies that for server-side scripts outside step executions, success and failure can be indicated by returning true or false, respectively, instead of using stepResult methods.
In a step configuration record, the step execution script field determines what a step with this configuration does when it runs.
Step inputs
The input variables to a step are determined by the inputs related list in the step
configuration record. The inputs parameter to
executeScript() gives the script access to these variables. For example, if
the inputs related list contains two records, var1 and
var2, the script can reference var1 with the expression
inputs.var1 and can reference var2 with
inputs.var2.
Step outputs
The output variables to a step are determined by the outputs related list in the step
configuration record. The outputs parameter to
executeScript() gives the script access to these variables. For example, if
the outputs related list contains two records, out1 and
out2, the script can reference out1 with the expression
outputs.out1 and can reference out2 with
outputs.out2.
Step result
The stepResult parameter provides access to an API that controls whether the step passes or fails. It also determines the message the step writes to the log.
The method stepResult.setSuccess() causes the step to succeed. The method
stepResult.setFailed() causes the step to fail.
The method stepResult.setOutputMessage() sets the message to write to the log
when the step succeeds or fails. It takes one parameter: the string to write to the log. If the
script calls stepResult.setOutputMessage() more than once, the most recent
value set overwrites any previous value.
Record Query step execution script
(function executeStep(inputs, outputs, stepResult) {
if (gs.nil(inputs.table)) {
stepResult.setOutputMessage(gs.getMessage("The '{0}' input variable was not specified",
'table'));
stepResult.setFailed();
return;
}
var query = new GlideRecord(inputs.table);
query.addEncodedQuery(inputs.field_values);
query.query();
if (!query.next()) {
stepResult.setOutputMessage(gs.getMessage("No records matching query:\n{0}",
inputs.field_values));
stepResult.setFailed();
} else {
stepResult.setSuccess();
outputs.table = inputs.table;
outputs.first_record = query.getUniqueValue();
stepResult.setOutputMessage(gs.getMessage("Found {0} {1} records matching query:\n{2}",
[query.getRowCount(),
inputs.table,
inputs.field_values]));
}
}(inputs, outputs, stepResult));
Custom scripted step configs
((function executeStep(inputs, outputs, stepResult, timeout) {
// Waits up to the timeout for some asynchronous logic to finish
// This script checks for completion once a second for up to 60 seconds
var counter = 1;
// Try for up to 60 seconds
while (counter <= timeout) {
// If the asynchronous logic is finished, return "true" to pass the step
// isMyAsyncLogicFinished() can be replaced with any asynchronous event that needs to be tested
if (isMyAsyncLogicFinished()) {
stepResult.setOutputMessage("Success!");
stepResult.setSuccess();
return;
}
// Wait one second, and log the total number of seconds waited
gs.info("Waited " + counter + " seconds for asynchronous logic to finish");
sn_atf.AutomatedTestingFramework.waitOneSecond();
counter++;
}
// If this point is reached, the retry loop ran out of tries; return false to fail the step
stepResult.setOutputMessage("FAILURE: Timed out after waiting for " + timeout + " seconds");
stepResult.setFailed();
}(inputs, outputs, stepResult, timeout));
stepResult.setSuccess()” and stepResult.setFailed() with
return true and return false.