Microsoft Powershell Connector

Microsoft Powershell Connector capabilities are build on top of Generic Python Script connector. The functionality is implemented by a powershell-event.py python script, provided by Matrix42 starting from release 2026.1. That script is in charge of calling customers Powershell scripts from remote Windows server over ssh connection. 

When Microsoft Powershell Connector is taken into use, it requires that

• Customer has own Windows server having those Powershell scripts to call
• That same Windows server must have ssh server on, and configured to support private/public key authentication (other authentication methods are not supported)
• Connector details are fulfilled and Event based task is configured for triggering Powershell.
• Workflow must contain Orchestration node, to call that Event based task to trigger it.

Features which are not supported

• Powershell can't be triggered from Scheduled tasks using this powershell-event.py python script

Configure Connector

For accessing connector management, user needs to have permissions to Platform configuration.

1. Open the administration area (a gear symbol).
2. Open connectors view.
3. Choose + new connector 

4. Select Data Source type to be Generic Python Script

5. Fulfill information 

• Fill in unique connector name for the connector
• Select powershell-event.py script from provisioning script field. 
• Parameters encryption password is needed for hiding / revealing parameters, after the connector has been saved (remember to store password on secure place).
  Parameters need to be in this exact format:
  { "ssh": {"private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\nb4ClbnNzaC1rZXktdjEAbbAABG5vbmUAAAAxxxxxxQAAAAAAAAABAAAAMwAAAAtzc2gtZW\nQyNTUxOQAAACB2zQv/80M8ICgv95iT7jCIxnn/YL1tzLvm6S+QaC3bDAAAALBayLNTWsiz\nUwAAAAtzc2gtZWQyNTUxOQAAACB2zQv/80M8ICgv95iT7jCIxnn/YL1tzLvm6S+QaC3bDA\nAAAEAeY5TsWlBuSeX+3Sz/tJTqJU+XgpHHr7QjfRlbr/f7RHbNC//zRXsgKC/3mJPuMIjG\nef9gvW3Mu+bpL5BoLdsMAAABKXJpa3BuaWVtaW5lbkBSaWt1cy1NYWNCb29rLVByby0yMD\nI0LmxvY2FsAQIDAB==\n-----END OPENSSH PRIVATE KEY-----", "user": "MATRIX42\\sshrunneruser", "host": "1.2.3.4", "timeout": 30,    "remote_command": { "executable": "powershell.exe", "arguments": ["-NoProfile" ]  } }, "redirect_stderr_to_stdout": true}

private_key value line breaks must be replaced with \n as in the example above. This private key is for user logging to Windows server over ssh.
  user is user used to login to Windows server and trigger powershell scripts
  host is ip-address or hostname of that Windows server which contains those Powershell scripts
  timeout can be left to default 30 like in this example above
  remote_command should be exactly like in this example above

• WebAPI user is needed when connector is writing data to customers solution
• WebAPI password is needed when connector is writing data to customers solution

6. Save the connector from save button. Now connector is configured and you can move forward to Configure Event based task. 

Configure Event based task

Create new Event based task

1. Set descriptive task name
2. Select Task usage: Event
3. Set Mappings type: Generic Template
4. Set target Template: from which data is send to this event task
5. Set target Folder: from which data is send to this event task

6. Create mappings

You need to always have at least one mapping: ps_script_path_and_name which should be mapped to attribute which contains that information, otherwise Event task don't know which Powershell to trigger.

Additionally you can have 1 or many parameters. You need to set those to mapping table named exactly like in example; parameter1, parameter2, parameter3 etc. depending on how many parameters your Powershell script expects to get.

7. Save Event task.
8. Next you need to create Workflow with Orchestration Node calling this Event task.

Call Event task from WorkFlow

Add Orchestration node to your Workflow

1. Name - set descriptive name
2. Description
3. Orchestrate - Native Connectors
4. Data Source - Generic Python Script
5. Activity - Execure Event task
6. Target - Select event task you previously crated for this purpose
7. Respose - select attribute which is used to store successfully excecuted Powershell output
8. Provisioning Exception: select attribute which is used to store error messages of failed Powershell call

Powershell script format supported by our Microsoft Powershell connector

• Reads script parameters as string parameters (like in example).
• Can contain 0 to n parameters.
• Exit with exit code 0 when script was executed successfully. You can also return ok message as json, to be stored to node response field of datacard.
• Exit with exit code bigger than 0 when there was some error. You can also return error message as json, to be stored provisioning exception field of datacard.

Example stores checks that 2 parameters have been given and then writes those to file on Windows machine. If first parameter was equal to “failuretest”, then it returns error code and message to Workflow.

param (
    [string]$Param1,
    [string]$Param2
)

# Validate required parameters
if ([string]::IsNullOrEmpty($Param1) -or [string]::IsNullOrEmpty($Param2)) {
    $errorJson = @{ error = "Wrong number of attributes for Powershell script" } | ConvertTo-Json -Compress
    Write-Output $errorJson
    exit 1
}

# Folder where this script is located
$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
$file = Join-Path $scriptDir "pstest.txt"

# Failure case
if ($Param1 -eq "failuretest") {
    $errorJson = @{ error = "Calling powershell FAILED" } | ConvertTo-Json -Compress
    Write-Output $errorJson
    exit 1
}

# Success case: write file
"$Param1`n$Param2" | Out-File -FilePath $file -Encoding UTF8 -Force

$successJson = @{ response = "Calling powershell successfull" } | ConvertTo-Json -Compress
Write-Output $successJson
exit 0