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.

Template-Pipes erfordern CLI Version 4.2.0 oder höher und eine aktive Verbindung zu einer Engine (pc login).

Grundlagen

Standard-Piping

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


pc list-process-instances --filter-by-state error | pc 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 list-process-instances --filter-by-state running | pc stop-process-instance {{.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 list-process-instances | pc show-process-instance {{.correlation.correlationId}}

Mehrere Templates in einem Argument

Kombinieren Sie mehrere Templates innerhalb eines Arguments:


pc list-process-instances | echo "{{.processModelId}}/{{.processInstanceId}}"

Template in Optionswerten

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


pc list-process-instances --limit 5 | pc list-user-tasks --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 list-process-instances --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 list-process-instances --filter-by-state running | pc stop-process-instance {{.processInstanceId}}

wird intern zu:


pc stop-process-instance 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 lsi --filter-by-state running | pc stop {{.processInstanceId}}

Fehlgeschlagene Instanzen anzeigen


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

Fehlgeschlagene Instanzen erneut versuchen


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

Deployen und direkt starten


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

User-Tasks nach Correlation filtern


pc lsi --limit 1 | pc list-user-tasks --filter-by-correlation-id {{.correlationId}}

Mehrere Modelle deployen und starten


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

Verfügbare Felder je Kommando

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

list-process-instances

Feld	Typ	Beschreibung
`processInstanceId`	string	Eindeutige ID der Prozessinstanz
`processModelId`	string	ID des Prozessmodells
`processModelName`	string	Name des Prozessmodells
`processDefinitionId`	string	ID der Prozessdefinition
`correlationId`	string	ID der Correlation
`state`	string	Status: `running`, `finished`, `error`, `terminated`
`createdAt`	string	Erstellungszeitpunkt (ISO 8601)
`finishedAt`	string	Abschlusszeitpunkt (ISO 8601)
`durationInMilliseconds`	number	Laufzeit in Millisekunden
`ownerId`	string	ID des Besitzers
`parentProcessInstanceId`	string	ID der übergeordneten Instanz (bei CallActivities)
`startEventId`	string	ID des Start-Events
`endEventId`	string	ID des End-Events
`hash`	string	Hash der Prozessdefinition
`engineId`	string	ID der Engine
`correlation.correlationId`	string	Correlation-ID (verschachtelter Zugriff)

list-process-models

Feld	Typ	Beschreibung
`id`	string	ID des Prozessmodells
`name`	string	Name des Prozessmodells
`startEventIds`	array	IDs der Start-Events

list-user-tasks

Feld	Typ	Beschreibung
`flowNodeInstanceId`	string	Eindeutige ID der FlowNode-Instanz
`flowNodeName`	string	Name des User-Tasks
`state`	string	Status des User-Tasks
`processModelId`	string	ID des zugehörigen Prozessmodells
`processInstanceId`	string	ID der zugehörigen Prozessinstanz
`correlationId`	string	ID der Correlation

deploy-files

Feld	Typ	Beschreibung
`success`	boolean	Ob das Deployment erfolgreich war
`filename`	string	Dateiname der deployten BPMN-Datei
`processModelId`	string	ID des deployten Prozessmodells

start-process-model

Feld	Typ	Beschreibung
`success`	boolean	Ob der Start erfolgreich war
`processModelId`	string	ID des gestarteten Prozessmodells
`startEventId`	string	ID des verwendeten Start-Events
`processInstanceId`	string	ID der erzeugten Prozessinstanz
`correlationId`	string	ID der Correlation

show-process-instance

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

Feld	Typ	Beschreibung
`flowNodeInstances`	array	Array der FlowNode-Instanzen mit deren Verlauf

Kurzreferenz: Aliasse und result_type

Kommando	Alias	result_type
`list-process-instances`	`lsi`	`process-instances`
`list-process-models`	`lsp`	`process-models`
`list-user-tasks`	`lsu`	`user-tasks`
`deploy-files`	`deploy`	`deployed-files`
`start-process-model`	`start`	`process-instances`
`stop-process-instance`	`stop`	`process-instances`
`retry-process-instance`	`retry`	`process-instances`
`show-process-instance`	`show`	`process-instances`
`finish-user-task`	`finish`	`user-tasks`
`remove-process-models`	`remove`	`removed-process-model-ids`

Häufige Pipe-Kombinationen

Pipe-Kette	Beschreibung
`pc deploy ... \| pc start {{.processModelId}}`	Deployen und direkt starten
`pc lsi --filter-by-state running \| pc stop {{.processInstanceId}}`	Laufende Instanzen stoppen
`pc lsi --filter-by-state error \| pc retry {{.processInstanceId}}`	Fehlgeschlagene Instanzen wiederholen
`pc lsi --filter-by-state error \| pc show {{.processInstanceId}}`	Fehlgeschlagene Instanzen inspizieren
`pc lsi \| pc lsu --filter-by-correlation-id {{.correlationId}}`	User-Tasks zu Instanzen finden
`pc lsp \| pc remove {{.id}}`	Alle Modelle entfernen

Fehlerbehandlung

Unbekanntes Feld

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


$ pc list-process-instances | pc stop-process-instance {{.nichtVorhanden}}


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

Template ohne Pipe-Eingabe


$ pc stop-process-instance {{.processInstanceId}}


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

Zusammenspiel mit dem Standard-Piping

Schreibweise	Mechanismus	Verhalten
`pc lsi \| pc stop`	Standard	IDs werden automatisch anhand des `result_type` extrahiert
`pc lsi \| pc stop {{.processInstanceId}}`	Template	Das Feld wird explizit extrahiert

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

Empfehlung: Verwenden Sie Template-Pipes für neue Workflows. Sie bieten mehr Flexibilität und machen die Absicht des Befehls explizit lesbar.

Shell-Escaping

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


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