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.

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.

//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;
}

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();

if (osname === 'Linux')
{
 //add Linux-specific code
 return;
}

if (osname === 'Windows')
{
 //add Windows-specific code
 return;
}

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 #### */},
 {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 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 #####
 cd c:\
 dir echo
 echo This user ${user} from ${company}
 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(Shell.exec('cmd', script).error());
console.log(Shell.exec('cmd.exe /k echo hello'));
}

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')); 
}