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.

Example: Putting it all together with the xm-shell library

The following example shows how to write a script that processes a status change and logs information about it to a file that exists locally on the system that hosts the agent. You can copy and paste the following code into the script editor of any outbound integration that is triggered by an alert status update and is configured to run in an agent.

//Create a shell by requiring the xm-shell library. 

//If the integration is running in the cloud then this call 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
console.log("Running in cloud - exiting.");
return;
}

// request the operating system name from the shell
var osname = Shell.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}
date +"%x %r : Hostname is: $HOSTNAME"
#### AND HERE #### */},
{param1: 'This is a parameter.', param2: 'This is also a parameter'});

// Execute the script.
var result = Shell.exec('bash', script);

console.log(result.output());
console.log(result.exitCode());
console.log(result.error());
}

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 #####
cd c:\
dir echo
echo This user ${user} from ${company}
echo %date% %time% : Hostname is %computername%
REM ##### AND HERE #### */},
{user: "Mary McBride", company: "Example"});


// Execute it
var result = Shell.exec('cmd', script);
console.log("Output:");
console.log( result.output());
console.log("ExitCode:");
console.log( result.exitCode());
console.log("Error:");
console.log( result.error());
console.log(Shell.exec('cmd.exe /k echo hello'));
}