Microsoft Powershell Connector

Microsoft Powershell Connector -yhteysmoduulin ominaisuudet on rakennettu Generic Python Script connector. Toiminnallisuus on toteutettu powershell-event.py Python-skriptillä, jonka Matrix42 on tarjonnut versiosta 2026.1 alkaen. Kyseinen skripti vastaa asiakkaan Powershell-skriptien kutsumisesta etäyhteydellä Windows-palvelimelle SSH-yhteyden kautta. 

Kun Microsoft Powershell Connector otetaan käyttöön, se edellyttää, että

• Asiakkaalla on oma Windows-palvelin, jolla kutsuttavat Powershell-skriptit sijaitsevat
• Powershell-skriptit on luotava tavalla, jota tämä yhteysmoduuli tukee (katso ohjeet tältä sivulta)
• Samalla Windows-palvelimella on oltava SSH-palvelin käytössä ja määritettynä tukemaan yksityinen/julkinen avain -todennusta (muita todennusmenetelmiä ei tueta)
• Asiakas on avannut palomuurin SSH-yhteydelle Matrix42 Pro/IGA-ratkaisun ja asiakkaan Windows-palvelimen välillä, jolla SSH-palvelin on käynnissä ja jolla Powershell-skriptit sijaitsevat.
• Asiakas on luonut Windows-käyttäjän, jolla on tarvittavat oikeudet MS Powershell -skriptien suorittamiseen ja palvelimelle kirjautumiseen SSH:n kautta.
• Yhteysmoduulin tiedot on täytetty ja tapahtumapohjainen tehtävä (Event based task) on määritetty käynnistämään Powershell.
• Työnkulussa (Workflow) on oltava Orchestration-solmu, joka kutsuu tätä tapahtumapohjaista tehtävää sen käynnistämiseksi.
• Matrix42 luo yksityinen/julkinen-avainparin ja lähettää julkisen avaimen asiakkaalle. Asiakkaan tulee lisätä tämä julkinen avain SSH-palvelimen määrityksiin sallituksi julkiseksi avaimeksi todennusta varten. Lisäksi Matrix42:n tulee määrittää yksityinen avain yhteysmoduulin asetuksiin.

Ei-tuetut ominaisuudet ja muut rajoitukset

• Powershellia ei voi käynnistää ajastetuista tehtävistä (Scheduled tasks) tällä powershell-event.py Python-skriptillä

Yhteysmoduulin määrittäminen

Yhteysmoduulien hallintaan pääsyä varten käyttäjällä on oltava oikeudet Platform configuration -asetuksiin.

1. Avaa hallintanäkymä (rataskuvake).
2. Avaa yhteysmoduulinäkymä.
3. Valitse + uusi yhteysmoduuli 

4. Valitse Data Source -tyypiksi Generic Python Script

5. Täytä tiedot 

• Anna yhteysmoduulille yksilöllinen nimi
• Valitse powershell-event.py -skripti provisioning script -kentästä. 
• Parametrien salaussalasanaa tarvitaan parametrien piilottamiseen / paljastamiseen sen jälkeen, kun yhteysmoduuli on tallennettu (muista säilyttää salasana turvallisessa paikassa).
  
  Esimerkki Linux-komennosta yksityinen/julkinen-avainparin luomiseksi: 
  ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_ps-connector -C "ps-connector-2026-05-21"
  Jätä salasana tyhjäksi.
  
  Parametrien on oltava tässä täsmällisessä muodossa:
  { "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-arvon rivinvaihdot on korvattava merkinnällä \n kuten yllä olevassa esimerkissä. Tämä yksityinen avain on tarkoitettu käyttäjälle user, joka kirjautuu Windows-palvelimelle SSH:n kautta.
  user on käyttäjä, jota käytetään kirjautumiseen Windows-palvelimelle ja Powershell-skriptien käynnistämiseen
  host on sen Windows-palvelimen IP-osoite tai isäntänimi, jolla Powershell-skriptit sijaitsevat
  timeout voidaan jättää oletusarvoon 30, kuten yllä olevassa esimerkissä. Timeout-arvo on sekunteina, joten tässä esimerkkimäärityksessä se on 30 sekuntia.
  remote_command tulee olla täsmälleen samanlainen kuin yllä olevassa esimerkissä

• WebAPI-käyttäjä tarvitaan, kun yhteysmoduuli kirjoittaa dataa asiakkaan ratkaisuun
• WebAPI-salasana tarvitaan, kun yhteysmoduuli kirjoittaa dataa asiakkaan ratkaisuun

6. Tallenna yhteysmoduuli Tallenna-painikkeesta. Nyt yhteysmoduuli on määritetty ja voit siirtyä tapahtumapohjaisen tehtävän (Event based task) määrittämiseen. 

Tapahtumapohjaisen tehtävän (Event based task) määrittäminen

Luo uusi tapahtumapohjainen tehtävä (Event based task)

1. Aseta kuvaava tehtävän nimi
2. Valitse Task usage: Event
3. Aseta Mappings type: Generic Template
4. Aseta kohde-Template: josta dataa lähetetään tälle tapahtumatehtävälle
5. Aseta kohde-Folder: josta dataa lähetetään tälle tapahtumatehtävälle

6. Luo mappaukset

Sinulla on aina oltava vähintään yksi mappaus: ps_script_path_and_name, joka tulee mapata attribuuttiin, joka sisältää kyseisen tiedon. Muuten tapahtumatehtävä ei tiedä, mitä Powershellia käynnistää.

Lisäksi voit käyttää yhtä tai useampaa parametria. Ne tulee asettaa mappaustauluun täsmälleen esimerkin mukaisesti nimettyinä; parameter1, parameter2, parameter3 jne. sen mukaan, kuinka monta parametria Powershell-skriptisi odottaa saavansa.

7. Tallenna tapahtumatehtävä (Event task).
8. Seuraavaksi sinun tulee luoda työnkulku (Workflow), jossa on Orchestration-solmu, joka kutsuu tätä tapahtumatehtävää.

Tapahtumatehtävän kutsuminen työnkulusta (WorkFlow)

Lisää Orchestration-solmu työnkulkuusi (Workflow)

1. Name – aseta kuvaava nimi
2. Description
3. Orchestrate – Native Connectors
4. Data Source – Generic Python Script
5. Activity – Execute Event task
6. Target – valitse aiemmin tätä tarkoitusta varten luomasi tapahtumatehtävä
7. Response – valitse attribuutti, johon tallennetaan onnistuneesti suoritetun Powershellin tuloste
8. Provisioning Exception: valitse attribuutti, johon tallennetaan epäonnistuneen Powershell-kutsun virheilmoitukset

Microsoft Powershell -yhteysmoduulin tukema Powershell-skriptimuoto

• Lukee skriptin parametrit merkkijonoparametreina (kuten esimerkissä).
• Voi sisältää 0–n parametria.
• Poistu exit-koodilla 0, kun skripti suoritettiin onnistuneesti. Voit myös palauttaa ok-viestin JSON-muodossa, joka tallennetaan datakortin solmun response-kenttään.
• Poistu exit-koodilla, joka on suurempi kuin 0, kun tapahtui virhe. Voit myös palauttaa virheilmoituksen JSON-muodossa, joka tallennetaan datakortin provisioning exception -kenttään.

Alla oleva esimerkki-Powershell-skripti tarkistaa, että kaksi parametria on annettu, ja kirjoittaa ne sitten tiedostoon Windows-koneella. Jos ensimmäinen parametri oli “failuretest”, se palauttaa virhekoodin ja -viestin työnkulkuun (Workflow). Voit käyttää tätä mallina omia Powershell-skriptejäsi kirjoittaessasi. 

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

Vianmääritys

• Jos käytössä on failure-malline (failure template), tarkista virhetiedot oikealta datakortilta
• Tarkista ajastetun tehtävän historia yhteysmoduulien hallinnasta
• Tarkista Matrix42 Native Connectors -lokit, jotka löytyvät Connectors-välilehdeltä, Logs-osiosta
• Tarkista FAQ-dokumentit