Script Management: PowerShell-Skripte für den Workspace (ab Release 6.7.0)

Ab Release 6.7.0 bringt ComBinder ein eingebautes Script-Management mit: Eigene PowerShell-Skripte können direkt im Produktbaum aufgerufen werden und bekommen automatisch ein Bearer-Token sowie die Liste der selektierten Produkte übergeben – ohne dass Zugangsdaten manuell im Skript hinterlegt werden müssen. Damit lassen sich wiederkehrende Datenpflegeopierationen (Texte normalisieren, Feldwerte transformieren, Massenimporte prüfen) mit wenig Aufwand automatisieren.

Voraussetzungen

  • ComBinder ab Version 6.7.0
  • Die REST API ist aktiviert (Einstellungen → Tab „Rest API“ → Enabled). Skripte lesen und schreiben Produktdaten ausschließlich über die REST API.
  • Ein Workspace ist geöffnet.
  • PowerShell 5.1 oder höher ist auf dem Rechner installiert (bei Windows 10/11 standardmäßig vorhanden).

Skript-Ordner

ComBinder sucht Skripte im Unterordner input_script des geöffneten Workspace. Der vollständige Pfad wird im Script-Management-Dialog angezeigt und lautet in der Regel:

<Workspace-Verzeichnis>\input_script\

Alle Dateien mit der Endung .ps1 in diesem Ordner werden automatisch erkannt. Der Ordner wird angelegt, wenn er noch nicht existiert. Der schnellste Weg dorthin: Tools → Script Management… → „Ordner öffnen“.

Skripte aufrufen

Es gibt zwei Wege, ein Skript auszuführen:

Weg 1: Rechtsklick im Produktbaum (mit Produktauswahl)

Produkte oder Produktgruppen im Baum auswählen → Rechtsklick → Edit → unterhalb des Trennstrichs erscheinen alle erkannten Skripte. Ein Klick auf den Eintrag startet das Skript mit der aktuellen Auswahl. Gruppen werden dabei rekursiv aufgelöst, sodass alle enthaltenen Produkte übergeben werden. Variantenprodukte werden automatisch auf ihr Basisprodukt zurückgeführt.

Weg 2: Tools → Script Management… (ohne Produktauswahl)

Der Dialog unter Tools → Script Management… listet alle verfügbaren Skripte mit Dateiname und Änderungsdatum. Über „Ausführen“ startet das markierte Skript – in diesem Fall ohne Produktauswahl, d. h. products im Kontext ist eine leere Liste. Dieser Weg eignet sich für workspace-weite Operationen, die keine Selektion im Baum benötigen, oder zum Testen eines neuen Skripts.

Backup-Dialog

Vor jeder Ausführung erscheint ein Sicherheitsdialog mit drei Optionen: Backup erstellen, Ohne Backup fortfahren oder Abbrechen. Da Skripte Produktdaten unwiderruflich ändern können, wird empfohlen, für den ersten Testlauf immer ein Backup zu erstellen.

Aufbau eines Skripts

ComBinder ruft das Skript so auf:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File <skript.ps1> <pfad-zur-kontext.json>

Das Skript erhält als einziges Argument den Pfad zu einer temporären JSON-Datei mit dem sogenannten Invocation Context. Diese Datei enthält alle Informationen, die das Skript braucht, um die REST API anzusprechen:

{
  "apiBaseUrl":    "http://localhost:8765/api",
  "token":         "<automatisch generiertes Bearer-Token>",
  "workspaceName": "Mein Workspace",
  "products": [
    {
      "id":          42,
      "supplierPid": "ART-001",
      "name":        "Akku-Bohrschrauber 18V"
    }
  ]
}

Das Token ist 24 Stunden gültig und wird automatisch für den aktuell in ComBinder angemeldeten Benutzer ausgestellt – das Skript muss sich nicht selbst authentifizieren.

Ein minimales Skript-Grundgerüst:

# Title: Mein Skript-Name (erscheint im Menü)
param(
    [Parameter(Position = 0, Mandatory = $true)]
    [string]$ContextFile
)

$context = Get-Content $ContextFile -Raw | ConvertFrom-Json
$headers = @{ Authorization = "Bearer $($context.token)" }

foreach ($product in $context.products) {
    # Beispiel: Kurztext auf Deutsch lesen
    $texts = (Invoke-RestMethod `
        -Uri "$($context.apiBaseUrl)/product/$($product.id)/texts/short" `
        -Headers $headers -Method Get).data

    Write-Host "$($product.supplierPid): $($texts.Count) Sprachen gefunden"
}

Anzeigename im Menü

Der Eintrag, der im Rechtsklick-Menü und im Script-Management-Dialog erscheint, ergibt sich aus der ersten Zeile der Skriptdatei. Beginnt sie mit # Title:, wird der Text danach als Anzeigename verwendet:

# Title: Zeilenumbrüche in <br> umwandeln (Texte + Merkmale)

Fehlt ein solcher Kommentar, leitet ComBinder den Namen aus dem Dateinamen ab – Unterstriche und Bindestriche werden durch Leerzeichen ersetzt. Empfohlen wird immer ein sprechender # Title:-Kommentar, damit das Menü auch bei vielen Skripten lesbar bleibt.

Wichtiger Hinweis: UTF-8-Kodierung bei PUT-Anfragen

Windows PowerShell 5.1 kodiert den Body von Invoke-RestMethod standardmäßig nicht als UTF-8, sondern nach der System-Codepage. Das führt bei Texten mit Umlauten oder Sonderzeichen zu einem 400 Bad Request von der ComBinder REST API. Der Body muss deshalb immer explizit als UTF-8-Bytes übergeben werden:

function Set-TextValue {
    param($ApiBaseUrl, $Headers, $Path, $Value)
    $jsonBody  = (@{ value = $Value } | ConvertTo-Json)
    $bodyBytes = [System.Text.Encoding]::UTF8.GetBytes($jsonBody)
    Invoke-RestMethod -Uri "$ApiBaseUrl$Path" -Method Put -Headers $Headers `
        -ContentType "application/json; charset=utf-8" -Body $bodyBytes | Out-Null
}

Dieses Muster sollte in jedem Skript verwendet werden, das Texte zurückschreibt.

Log-Ausgabe

Alles, was das Skript auf der Standardausgabe (Write-Host) ausgibt, wird von ComBinder gesammelt und nach Abschluss im Log-Dialog angezeigt. Ein Exit Code von 0 signalisiert Erfolg; jeder andere Wert markiert den Lauf als fehlgeschlagen. Das Skript kann damit gezielte Fehlermeldungen über den Exit Code steuern:

if ($totalErrors -gt 0) { exit 1 }
exit 0

Tipps für die Skript-Entwicklung

  • Idempotenz: Skripte sollten bei einem zweiten Lauf auf denselben Produkten keine unnötigen Änderungen vornehmen und das im Log melden. Das erleichtert Fehlersuche und Wiederholung.
  • Testen ohne Auswahl: Über Tools → Script Management… lässt sich ein Skript ohne Produktselektion starten – die Backup-Logik und die Log-Ausgabe lassen sich so prüfen, ohne echte Daten zu ändern.
  • Skript aktualisieren: Dateien können jederzeit im Ordner bearbeitet werden. ComBinder liest die .ps1-Dateien bei jedem Öffnen des Menüs neu ein – ein Neustart ist nicht erforderlich. Im Dialog steht zusätzlich der Button „Aktualisieren“.
  • Ausführungsrichtlinie: ComBinder startet PowerShell mit -ExecutionPolicy Bypass. Skripte müssen daher nicht signiert sein.

Weiterlesen