Template-Pipes

Die CLI ermöglicht es, Kommandos miteinander zu verketten. Dazu wird die Ausgabe eines Kommandos als Eingabe an ein nachfolgendes Kommando weitergeleitet. Diese Verkettung wird als Piping bezeichnet und nutzt den Pipe-Operator (|) der Shell.

Mit Template-Pipes können Sie flexibel auf beliebige Felder der JSON-Ausgabe zugreifen und diese an nachfolgende Kommandos weitergeben.

Grundlagen

Standard-Piping

Im Standard-Verfahren erkennt die CLI automatisch, welche IDs aus der Ausgabe eines Kommandos extrahiert werden sollen:

pc engine lsi --filter-by-state error | pc engine retry-process-instance

Hierbei erkennt retry-process-instance automatisch, dass die Pipe-Eingabe vom Typ process-instances stammt, und extrahiert die processInstanceId aller Ergebnisse. Dieses Verfahren funktioniert weiterhin und ist vollständig rückwärtskompatibel.

Template-Pipes

Template-Pipes ermöglichen den gezielten Zugriff auf beliebige Felder der JSON-Ausgabe:

{{.feldName}}

Der Feldname wird mit einem Punkt (.) eingeleitet und in doppelte geschweifte Klammern eingeschlossen.

pc engine lsi --filter-by-state running | pc engine stop {{.processInstanceId}}

In diesem Beispiel wird {{.processInstanceId}} durch die tatsächliche processInstanceId jedes Ergebnisses ersetzt.

Syntax im Detail

Einfacher Feldzugriff

Greifen Sie auf ein Feld der obersten Ebene zu:

{{.processInstanceId}}
{{.processModelId}}
{{.correlationId}}

Verschachtelter Feldzugriff

Greifen Sie auf verschachtelte Felder zu, indem Sie die Feldnamen mit Punkten trennen:

pc engine lsi | pc engine show {{.correlation.correlationId}}

Mehrere Templates in einem Argument

Kombinieren Sie mehrere Templates innerhalb eines Arguments:

pc engine lsi | echo "{{.processModelId}}/{{.processInstanceId}}"

Template in Optionswerten

Templates können auch in den Werten von Optionen verwendet werden:

pc engine lsi --limit 5 | pc engine lsu --filter-by-correlation-id {{.correlationId}}

Verhalten bei mehreren Ergebnissen

Wenn die Ausgabe des vorangehenden Kommandos mehrere Ergebnisse enthält, wird das Template pro Ergebnis expandiert.

Beispiel

Angenommen, pc engine lsi --filter-by-state running liefert drei Ergebnisse:

{
  "result_type": "process-instances",
  "result": [
    { "processInstanceId": "abc-111", "processModelId": "Bestellung" },
    { "processInstanceId": "abc-222", "processModelId": "Bestellung" },
    { "processInstanceId": "abc-333", "processModelId": "Reklamation" }
  ]
}

Der Befehl:

pc engine lsi --filter-by-state running | pc engine stop {{.processInstanceId}}

wird intern zu:

pc engine stop abc-111 abc-222 abc-333

Wenn das vorangehende Kommando keine Ergebnisse liefert (leeres result-Array), wird die Template-Position entfernt.

Praxisbeispiele

Alle laufenden Instanzen stoppen

pc engine lsi --filter-by-state running | pc engine stop {{.processInstanceId}}

Fehlgeschlagene Instanzen anzeigen

pc engine lsi --filter-by-state error | pc engine show {{.processInstanceId}}

Fehlgeschlagene Instanzen erneut versuchen

pc engine lsi --filter-by-state error | pc engine retry {{.processInstanceId}}

Deployen und direkt starten

pc engine deploy-files mein-prozess.bpmn | pc engine start {{.processModelId}}

User-Tasks nach Correlation filtern

pc engine lsi --limit 1 | pc engine lsu --filter-by-correlation-id {{.correlationId}}

Mehrere Modelle deployen und starten

pc engine deploy-files prozess-a.bpmn prozess-b.bpmn | pc engine start {{.processModelId}}

Verfügbare Felder je Kommando

Die verfügbaren Felder hängen vom vorangehenden Kommando ab.

list-process-instances

list-process-models

list-user-tasks

deploy-files

start-process-model

show-process-instance

Gleiche Felder wie list-process-instances, zusätzlich:

Kurzreferenz: Aliasse und result_type

Häufige Pipe-Kombinationen

Fehlerbehandlung

Unbekanntes Feld

Wenn ein Feld im Template nicht existiert, wird ein Fehler mit allen verfügbaren Feldern angezeigt:

$ pc engine lsi | pc engine stop {{.nichtVorhanden}}

Error: Feld 'nichtVorhanden' nicht gefunden. Verfügbar: correlationId, processInstanceId,
processDefinitionId, processModelId, processModelName, state, createdAt, finishedAt, ...

Template ohne Pipe-Eingabe

$ pc engine stop {{.processInstanceId}}

Error: Template {{.processInstanceId}} verwendet, aber keine Pipe-Eingabe

Zusammenspiel mit dem Standard-Piping

Wenn ein Template verwendet wird, wird der Standard-Mechanismus für diesen Befehl deaktiviert.

Shell-Escaping

In manchen Shells müssen die geschweiften Klammern in Anführungszeichen gesetzt werden:

# Empfohlen: Einfache Anführungszeichen
pc engine lsi | pc engine stop '{{.processInstanceId}}'
 
# Alternative: Doppelte Anführungszeichen
pc engine lsi | pc engine stop "{{.processInstanceId}}"
 
# In den meisten Shells auch ohne Anführungszeichen möglich
pc engine lsi | pc engine stop {{.processInstanceId}}