Running local scripts on the agent
This section describes how to customize Integration Builder transformation scripts to run shell commands on the system that hosts an xMatters Agent. For general information on writing scripts for the Integration Builder (not including shell commands), see Transformation scripts.
Shell scripts provide a powerful way to access the system that hosts the agent. They allow you to work with the local file system, start and stop processes, access network resources, and perform any other task that can be typed into a command prompt. Because shell scripts are so powerful, agents restrict the users who can modify scripts and define logic that runs on the host system. Shell scripts can be only be used with steps and integrations that are configured to run on an agent. They cannot be used with integrations that run in the cloud.
The xm-shell function is provided and required to execute scripts via the agent, and takes two arguments: the first is a function that allows the execution of bash-style scripts; the second is optional, and comprises the parameters or variables you want to pass to that function. When the script runs, you have access to three outputs:
- outputs: contains any outputs you have defined in the script function (stdout)
- exitCode: the standard exit code for the shell you are using to execute the script
- error: the contents of stderror
There are different methods for configuring shell scripts depending on whether the agent is hosted on a Windows or Linux system. If you are hosting agents on both Windows and Linux systems, you'll need to ensure your scripts detect which platform the agent is running on and use the appropriate format. Additionally, if you later configure the step or integration to run in the cloud instead of on an agent, it will no longer be able to run shell scripts.
The following steps describe the process of configuring the agent to run shell scripts.
Step 1: Check to see if the integration is running in the cloud
Ensure that the integration is running on an agent and is not running in the cloud. Integrations that run in the cloud cannot execute code locally in a shell.
// Use the xm-shell library to create a command shell on the xAgent host, and run a few example commands.
// If the script is being executed in the cloud (i.e., not on an agent), it will fail.
try
{
var Shell = require ('xm-shell');
}
catch (e)
{
console.log ("Could not load library: " + e);
console.log ("Running in cloud - exiting.");
}
if ( Object.getOwnPropertyNames(Shell).length === 0 )
{
// Integration is running in the cloud, not on xAgent
console.log ("Running in cloud - exiting.");
return;
}
Determine the host operating system so you know what kind of syntax to use when you open a shell. It is especially important to make this check when you have multiple agents running on both Windows and Linux operating systems.
// Request the operating system name from the shell
var osname = Shell.osname();
console.log ( "Operating system is: " + osname );
if (osname === 'Linux') {
// Add Linux-specific code
}
if ( osname.startsWith( 'Windows' ) ) {
// Add Windows-specific code
}If your agent is running on a version of Linux such as Ubuntu, Debian, RedHat, or Centos, create and execute a bash script. You can pass parameters into the bash script when you execute it.
This example passes parameters into a shell, executes it, and logs output to the console. You can replace the bash script with any valid shell commands.
if (osname === 'Linux') {
// Create a script and pass some parameters into it.
var script = Shell.script( function () {/*#### PLACE YOUR BASH SCRIPT BETWEEN HERE ####
echo hello world
echo This script was called with the following input parameters:
echo Param1: ${param1}
echo Param2: ${param2}
#### AND HERE #### */},
// Use parameters to pass values in to the shell script.
{param1: 'This is a parameter.', param2: 'This is also a parameter'});
// Execute the script.
var result = Shell.exec('/bin/bash', script);
console.log ( "\nOutput from the shell script is:\n\n" + result.output() );
console.log ( "\nExit code from the shell script is: " + result.exitCode() );
if ( result.error() ) {
console.log ( "Error from the shell script is:\n" + result.error() );
} else {
console.log ( "There were no errors." );
}
}If your agent is running Windows, create and execute a .bat script. You can pass parameters into the .bat script when you execute it.
This example passes parameters into a shell, executes it, and logs output to the console. You can replace the .bat script with any valid shell commands.
if ( osname.startsWith( 'Windows' ) ) {
// create a script and pass some parameters into it.
var script = Shell.script( function () {/* REM #### PLACE YOUR .BAT SCRIPT BETWEEN HERE #####
echo Files in the root of the filesystem are:
dir /w \
echo.
echo User is ${user} from ${company}.
REM ##### AND HERE #### */},
// Use parameters to pass values in to the shell script.
{user: "Mary McBride", company: "ExampleCo"});
// Execute it
var result = Shell.exec('cmd.exe', script);
console.log ( "\nOutput from the shell script is:\n\n" + result.output() );
console.log ( "\nExit code from the shell script is: " + result.exitCode() );
if ( result.error() ) {
console.log ( "Error from the shell script is:\n" + result.error() );
} else {
console.log ( "There were no errors." );
}
}
Example: Putting it all together with the xm-shell library
// Use the xm-shell library to create a command shell on the agent host, and run a few example commands.
// If the script is being executed in the cloud (i.e., not on an agent), it will fail.
try
{
var Shell = require ('xm-shell');
}
catch (e)
{
console.log ("Could not load library: " + e);
console.log ("Running in cloud - exiting.");
}
if ( Object.getOwnPropertyNames(Shell).length === 0 )
{
// Integration is running in the cloud, not on xAgent
console.log ("Running in cloud - exiting.");
return;
}
// Request the operating system name from the shell
var osname = Shell.osname();
console.log ( "Operating system is: " + osname );
if (osname === 'Linux') {
// Create a script and pass some parameters into it.
var script = Shell.script( function () {/*#### PLACE YOUR BASH SCRIPT BETWEEN HERE ####
echo hello world
echo This script was called with the following input parameters:
echo Param1: ${param1}
echo Param2: ${param2}
#### AND HERE #### */},
// Use parameters to pass values in to the shell script.
{param1: 'This is a parameter.', param2: 'This is also a parameter'});
// Execute the script.
var result = Shell.exec('/bin/bash', script);
console.log ( "\nOutput from the shell script is:\n\n" + result.output() );
console.log ( "\nExit code from the shell script is: " + result.exitCode() );
if ( result.error() ) {
console.log ( "Error from the shell script is:\n" + result.error() );
} else {
console.log ( "There were no errors." );
}
}
if ( osname.startsWith( 'Windows' ) ) {
// create a script and pass some parameters into it.
var script = Shell.script( function () {/* REM #### PLACE YOUR .BAT SCRIPT BETWEEN HERE #####
echo Files in the root of the filesystem are:
dir /w \
echo.
echo User is ${user} from ${company}.
REM ##### AND HERE #### */},
// Use parameters to pass values in to the shell script.
{user: "Mary McBride", company: "ExampleCo"});
// Execute it
var result = Shell.exec('cmd.exe', script);
console.log ( "\nOutput from the shell script is:\n\n" + result.output() );
console.log ( "\nExit code from the shell script is: " + result.exitCode() );
if ( result.error() ) {
console.log ( "Error from the shell script is:\n" + result.error() );
} else {
console.log ( "There were no errors." );
}
}
return