Running PowerShell on the xMatters Agent

The xMatters online help provides some helpful code that allows an xMatters Agent to invoke the basic command shell on Windows installations to execute commands.

But if you need or want to use PowerShell instead, this article describes how an agent can send commands to powershell.exe and receive the output for use in other scripts.

Invoking PowerShell from an xMatters Agent

The help includes the following code snippet to illustrate how to invoke the Windows command shell (cmd.exe) to execute commands:

var script = Shell.script(function () {/* REM #### PLACE YOUR .BAT SCRIPT HERE ##### 
cd c:\
echo This user ${user} from ${company}
REM ##### AND HERE #### */}, {user: "Mary McBride", company: "xMatters"});

var result = Shell.exec('cmd', script);

You can use similar syntax to invoke PowerShell.exe instead, as shown in this modified version of the same code block:

var script = Shell.script(function () {/* 
C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -c "& {dir ${pathName} }"
*/},{ "pathName":"c:\\temp\\*.zip" })

var result = Shell.exec('cmd', script);
console.log("Output is:\n" + result.output());

Notes on syntax

The arguments are in a quoted string, the format of which is specified in the PowerShell help text:

 "& {dir ${pathName} }"

Use the "powershell /h" command for information on this format.

The closing forward slash (*/) must be on a new line in the Shell.script instruction. If there is no new line character, the PowerShell command will not execute or provide output. 

Backslashes in the main body of the Shell.script function are not escaped:


However, backslashes in the parameters section are escaped:


This is not a typo! The code must be written this way.


The expected output of the new code block includes a banner from the Windows operating system and the command that was executed:

Output is:
Microsoft Windows [Version 10.0.19042.1586]
(c) Microsoft Corporation. All rights reserved.

C:\Program Files\xa> C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -c "& {dir c:\temp\*.zip }"

Directory: C:\temp

Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 6/13/2017 1:41 PM 13658

C:\Program Files\xa>More?

Unfortunately, this is a result of invoking PowerShell via cmd.exe and can't be avoided. You'll need to provide code when using this output that filters out the unwanted content.

Invoking PowerShell without using cmd

It's possible to invoke PowerShell directly, without using cmd.exe as an intermediary:

var script = Shell.script(function () {/* dir ${pathName} */},{ "pathName":"d:\\temp\\*.jar" });
var result = Shell.exec('C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe -NonInteractive -NoLogo ', script);

Invoking PowerShell directly has pros and cons when compared with the cmd.exe approach:

  • It might provide better performance, and can eliminate some resource constraints such as available RAM, etc. 
  • It allows multiple threads to be allocated to PowerShell scripts.
  • It reduces (though does not eliminate) the number of unwanted lines of output.
  • It may not be possible to invoke a .ps1 script stored on the filesystem.

Note on syntax

As shown in the example, all backslashes must be escaped when invoking PowerShell directly.

Other notes

  • It is not possible to access or invoke PowerShell from a script executed on the xMatters cloud. Refer to the online help documentation for instructions on how to run your Flow Designer script on an xMatters Agent.
  • If you are using PowerShell to invoke a script (e.g., "c:\temp\somescript.ps1"):
    • The path and the script or file name cannot contain spaces.
    • The PowerShell script must be written to accept parameters, and not arguments.


Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk