Running local scripts on the xMatters 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 xMatters 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, xMatters restricts the users who can modify Integration Builder scripts and define logic that runs on the host system. Shell scripts can be only be used with integrations that are configured to run on an xMatters Agent. They cannot be used with integrations that run in the xMatters cloud.

There are different methods for configuring shell scripts depending on whether the xMatters Agent is hosted on a Windows or Linux system. If you are hosting xMatters Agents on both Windows and Linux systems, you'll need to ensure your Integration Builder scripts detect which platform the agent is running on and use the appropriate format. Additionally, if you later configure the integration to run in the cloud instead of on an xMatters Agent, it will no longer be able to run shell scripts.

The following steps describe the process of configuring the xMatters 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 an alert status change and logs information about it to a file that exists locally on the system that hosts the xMatters 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 xMatters Agent.

//Create a shell by requiring the xm-shell library.
//If the integration is running in the cloud then this call will fail.

 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.");

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

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: "xMatters"});

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