Windows PowerShell Connector Guide


Windows PowerShell lets you automate tasks and create configuration management scripts. The Anypoint Connector for Windows PowerShell connector enables Windows OS administration tasks to be integrated into Mule applications. PowerShell scripts may be executed on a remote Windows machine using the Windows Gateway Service and the result processed within Mule.

Questions? See the Frequently Asked Questions - FAQ.


Software Version

Mule ESB

3.5 and later

Anypoint Studio

October 2014 and later

Windows PowerShell

v3 or higher

.NET Framework



7 or 8

Windows Server

2008, 2012


This guide draws on information from the Windows Gateway Services Guide and assumes you are using Windows and Anypoint Studio. You can download the Windows version of Studio from the Anypoint Studio site.

Installing the PowerShell Connector

  1. Download and install the Windows Gateway Services software.

  2. You can install a connector in Anypoint Studio using the instructions in To Install a Connector from Anypoint Exchange.

  3. Search for powershell and drag the Windows PowerShell connector to the Canvas to the right of the HTTP connector.

  4. Click the Powershell connector, click the green plus symbol, and set these values:

Field Description

Gateway Service Address

Required. Windows Gateway Service IP address. Format: ip_addr:port. URLs are not supported. Example: ` `

Gateway Access Token

Required. Windows Gateway Service access token. Find the configured token in the Windows Service configuration file (c:\Program Files(x86)\Anypoint Gateway for Windows\Mule.SelfHost.exe.config) under the appSettings key mule-auth-token.


Optional. Username on Windows Gateway Service. Provide if a call must be impersonated.


Optional. Password on Windows Gateway Service. Provide if a call must be impersonated.

Ignore SSL Warnings

Optional. Click the checkbox if you are using a self-signed SSL certificate.

Test Connection

Click to test that the connection to Windows Gateway Service is working.

  1. Click OK. Ensure that the Connector Configuration is set to Powershell.

  2. In the PowerShell connector properties, set the Script property to the following value:

    Get-Service -Name #[message.inboundProperties['http.query.params']['name']]

    This command invokes the Get-Service command to return information about a Windows Service. The -Name argument resolves us ing the query string parameter name set by the HTTP Connector. For example, the following URL gets information about the ASP.NET Session State service: http://localhost:8081/?name=aspnet_state

  3. Search for object and drag the Object to JSON transformer to the Canvas to the right of the PowerShell connector icon. No settings are necessary. The Canvas appears as:


The completed XML Mule flow appears as:

<mule xmlns:http="" xmlns:powershell="" xmlns="" xmlns:doc=""
    <powershell:config name="Powershell" serviceAddress="localhost:9333" accessToken="test-token" ignoreSSLWarnings="true" doc:name="Powershell"/>
    <http:listener-config name="HTTP_Listener_Configuration" host="" port="8081" doc:name="HTTP Listener Configuration"/>
    <flow name="ps-sampleFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
        <powershell:send config-ref="Powershell" script="Get-Service -Name #[message.inboundProperties['http.query.params']['name']]"/>
        <json:object-to-json-transformer doc:name="Object to JSON"/>

Running the Flow

  1. Click Run > Run As > Mule Application.

  2. Check the console to see that the application starts and that there are no errors.

  3. Open in a browser: http://localhost:8081/?name=aspnet_state

    Note: This sample assumes there is an aspnet_state windows service running on the host, but any other Windows service can also be used.

  4. The following JSON response should be rendered.

        "CanPauseAndContinue":  false,
        "CanShutdown":  false,
        "CanStop":  false,
        "DisplayName":  "ASP.NET State Service",
        "DependentServices":  [ ],
        "MachineName":  ".",
        "ServiceName":  "aspnet_state",
        "ServicesDependedOn":  [ ],
        "ServiceHandle":  null,
        "Status":  1,
        "ServiceType":  16,
        "Site":  null,
        "Container":  null,
        "Name":  "aspnet_state",
        "RequiredServices":  [ ]

Solution Overview

The PowerShell connector uses a client-server architecture with two tiers, the connector or client running in the Mule ESB, and the Windows Services Gateway running on the server side. The latter exposes an HTTP Web API for receiving and executing PowerShell commands.

The Windows Gateway leverages the following technologies and frameworks:

  • ASP.NET Web API to expose an HTTP Web API that send and receive raw messages.

  • OWIN as the HTTP layer. OWIN is an open specification for decoupling applications from web server functionality. It provides a layer for making all the HTTP concerns independent of the hosting platform.

  • Katana as the OWIN Microsoft implementation, which provides self and IIS hosting for OWIN applications.

High-Level Use Cases

The PowerShell connector supports two primary use cases.

  • Send a single inline command/script and wait for the response.

  • Send a complex command/script from a file with arguments and wait for the response.

In the first scenario, the Mule ESB uses the connector to send a simple inline script via HTTP to the Windows Gateway. The message is sent as an HTTP Post. The payload of the HTTP request represents the command. The Web API running on the Windows Gateway executes the PowerShell script locally. The following message illustrates the structure of the HTTP Request.

Request Message:

POST: https://localhost:9333/powershell
Authorization: mule test-token
Mule-Api-Version: 1
get-service -name aspnet_state

Response Message:

    "CanPauseAndContinue":  false,
    "CanShutdown":  false,
    "CanStop":  false,
    "DisplayName":  "ASP.NET State Service",
    "DependentServices":  [ ],
    "MachineName":  ".",
    "ServiceName":  "aspnet_state",
    "ServicesDependedOn":  [ ],
    "ServiceHandle":  null,
    "Status":  1,
    "ServiceType":  16,
    "Site":  null,
    "Container":  null,
    "Name":  "aspnet_state",
    "RequiredServices":  [ ]

In the second scenario, the script is read from a file and can optionally contain arguments and variables that need to be resolved. The connector reads the script content from the file and sends that to the Gateway via HTTP in the request payload.

Request Message:

POST: https://localhost:9333/powershell
Authorization: mule test-token
Mule-Api-Version: 1
mule-ps-param-servicename: aspnet_state
 param (
  [string] $servicename = $null
get-service $servicename

Response Message:

    "CanPauseAndContinue":  false,
    "CanShutdown":  false,
    "CanStop":  false,
    "DisplayName":  "ASP.NET State Service",
    "DependentServices":  [ ],
    "MachineName":  ".",
    "ServiceName":  "aspnet_state",
    "ServicesDependedOn":  [ ],
    "ServiceHandle":  null,
    "Status":  1,
    "ServiceType":  16,
    "Site":  null,
    "Container":  null,
    "Name":  "aspnet_state",
    "RequiredServices":  [ ]

The connector uses HTTP headers with the prefix mule-ps-param- for sending command arguments, which are mapped to the expected parameters in the script. In the example above, the header mule-ps-param-servicename *is mapped to the parameter *servicename.

The response is also returned as a JSON message.

Configuration of the powershell:send Element

The powershell:send element is the only element used by the two scenarios described earlier in the document.

This following table shows the supported properties in this element:

Property Usage


Inline PowerShell script. It could also represent the call to a command passed from a file.


Path a file containing a PowerShell script.


The name of the user that is used to impersonate the call when executing the powershell script in the Gateway. Overrides the user name set in the Global element. Optional.


The password of the user that is used to impersonate the call when executing the powershell script in the Gateway. Overrides the password set in the Global element. Optional.


A number for controlling the JSON serialization deep level for the PowerShell script output.


A collection of parameters to be passed to the PowerShell script. Each parameter represents a key value pair.

Configuring a PowerShell Script with Parameters

The connector supports PowerShell scripts with top level parameters declared with the “param” keyword. For example,

# Do something with $computerName and $filePath

The computerName and filePath values are two different parameters that can be passed to the script.

The parameters are configured in the connector using the parameters collection. The value for a parameter can be resolved with MEL. In the previous example, these two parameters can be configured as follows:

<powershell:send config-ref="Powershell" doc:name="Powershell" scriptFile="myscript.ps1">
<powershell:parameter key="computerName">#[computer]</powershell:parameter>
<powershell:parameter key="filePath">c://mydocument.txt</powershell:parameter>

Inline Execution of Scripts Defined in a File

The script and scriptFile properties can be both combined to execute a function defined in a file. The file specified in ` scriptFile ` represents a PowerShell script with one or more callable functions, and script represents the function call. The call in script should contain all the expected arguments by the function. The following example shows how the two properties are combined.

The script is defined in the external Get-RemoteProgram.ps1 file.

Function Get-RemoteProgram {
  $ComputerName = $env:COMPUTERNAME,
  # Function body

Connector Configuration

<powershell:send config-ref="Powershell" doc:name="Powershell" scriptFile="Get-RemoteProgram.ps1" script="Get-RemoteProgram -ComputerName MyComputer">

The function invocation Get-RemoteProgram is done as part of the inline script specified in the script property. The optional argument ComputerName is also passed as part of the invocation.

Controlling the Serialization Depth

The PowerShell output is usually represented by a complex object graph with multiple dependency levels (an object referencing another object). In some cases, these dependencies may be circular references making serialization a complex process.

The serialization depth controls how deep the serialization must happen in the object hierarchy. For example, a value 2 means two levels must serialized only (the root objects and a single association).

This value must be set in the depth property:

<powershell:send config-ref="Powershell"  doc:name="Powershell" scriptFile="myscript.ps1" depth="2"/>

Frequently Asked Questions - FAQ

What can I do with the PowerShell connector?

Any arbitrary PowerShell script may be executed on a target Windows OS host, with the resultant object graph being returned to Mule for processing.

Can I use the PowerShell connector on a non-Windows platform?

Yes, the PowerShell connector passes the script contents to the Windows Gateway Service for execution so can be run on any platform.

Do I have to install the Windows Gateway Service on each machine I wish to run PowerShell scripts on?

Yes, you must install the Windows Gateway Service on the machine you wish to execute PowerShell scripts on.

How do I consume the object graph returned by PowerShell in my Mule application?

Results from executing PowerShell scripts are serialized into a Map<string, string> making it simple to consume using MEL or DataMapper.

Can I use parameterized PowerShell scripts or function libraries?

Yes, parameters are supported and automatically map from the message properties if not manually supplied in the parameters collection.

How do I run a script under the security context of different users?

Specifying the username and password for impersonation lets you run a script as a specific user. By default, a script runs as the identity of the Windows Gateway Service agent.

How do I specify the domain of the provided username?

The proper way for specifying a fully-qualified domain user is using the username@domain syntax, at the username field.