Engine Client.ts

Ein NodeJS basierter Client zur Kommunikation mit der ProcessCube Engine.

Schnelleinstieg

``ts
import { EngineClient } from '@5minds/processcube_engine_client';

const engineUri = 'http://localhost:10560';

const client = new EngineClient(engineUri);

const processInstancesInCorrelation = await client.processInstances.query({
correlationid: 'my-correlation-id',
});
`

Wie kann ich den Client verwenden?

Man benötigt lediglich die URL der anzusteuernden Engine.
Mit dieser lässt sich eine Instanz des Clients anlegen, die direkt verwendbar ist.

Es gibt verschiedene Wege sich Clients anzulegen.

$3

Man kann eine Instanz des EngineClients direkt anlegen, welche die API der ProcessCube Engine vollständig abdeckt.

`ts
import { EngineClient } from '@5minds/processcube_engine_client';

const engineUri = 'http://localhost:10560';

const client = new EngineClient(engineUri);

const processInstancesInCorrelation = await client.processInstances.query({
correlationid: 'my-correlation-id',
});
`

$3

Oder man kann sich über die Client Factory einen feature-spezifischen Client anlegen, der nur einen besimmten fachlichen Aspekt der ProcessCube Engine abdeckt.

Beispiel:

`ts
import { ClientFactory } from '@5minds/processcube_engine_client';

const engineUri = 'http://localhost:10560';

const processInstanceClient = ClientFactory.createProcessInstanceClient(engineUri);

const processInstances = await processInstanceClient.query({
correlationid: 'my-correlation-id',
});
`

Hier wird eine Client Instanz angelegt, welche lediglich die Interaktion mit Prozessinstanzen abdeckt.

Anwendungsbeispiele

Nachfolgend werden ein paar der am häufigsten verwendeten Use Cases demonstriert.

$3

Das Starten von Prozessinstanzen kann über die EngineClient.processModels Fachlichkeit realisiert werden.

Prozesse lassen sich auf mehrere Arten starten.

#### Einfacher Prozessstart

`ts
import { EngineClient } from '@5minds/processcube_engine_client';

const engineUri = 'http://localhost:10560';

const client = new EngineClient(engineUri);

await client.processModels.startProcessInstance({ processModelId: 'myProcessModelId' });
`

Die processModelId ist der einzige erforderliche Parameter für diesen Request.

Der Client wartet in diesem Szenario nur, bis die Engine den _Start_ des Prozesses bestätigt hat.

#### Konfigurierter Prozessstart

Neben der processModelId können folgende Paramter mitgegeben werden:

- startEventId: Die ID des Start Events von welchem aus der Prozess losgehen soll
- Hinweis: Bei Prozessen mit mehreren Start Events ist dieser Parameter ebenfalls erforderlich!
- correlationId: Gibt an, in welcher Correlation die Prozessinstanz laufen soll
- initialToken: Der JSON-formatierte Prozess-Token, den die Prozessinstanz zu beginn besitzen soll

`ts
import { EngineClient } from '@5minds/processcube_engine_client';

const engineUri = 'http://localhost:10560';

const client = new EngineClient(engineUri);

await client.processModels.startProcessInstance({
processModelId: 'myProcessModelId',
startEventId: 'StartEvent_1',
correlationId: 'MyCorrelatioNid',
initialToken: {
hello: 'world',
},
});
`

#### Prozess starten und auf dessen Ende warten

`ts
import { EngineClient } from '@5minds/processcube_engine_client';

const engineUri = 'http://localhost:10560';

const client = new EngineClient(engineUri);

await client.processModels.startProcessInstanceAndAwaitEndEvent({ processModelId: 'myProcessModelId' });
`

Hier wartet der Client, bis die Engine den Prozess bis zum Ende ausgeführt hat.

Die Methode akzeptiert dieselben Parameter wie processModels.startProcessInstance.

Query UserTasks

Abfragen aller User Tasks eines bestimmten Prozesses, die sich in einem "suspended" State befinden:

`ts
import { EngineClient, DataModels } from '@5minds/processcube_engine_client';

const engineUri = 'http://localhost:10560';

const client = new EngineClient(engineUri);

const userTasks = await client.userTasks.query({
processModelId: 'myProcessModelId',
state: DataModels.FlowNodeInstances.FlowNodeInstanceState.suspended,
});

console.log(userTasks);
`

External Task Worker

External Task Worker werden dazu benutzt, um die an einer Prozessinstanz anfallenden External Service Tasks zu verarbeiten.

Ein Worker benötigt minimal die folgenden 3 Einstellungen

- Die URL der Ziel-Engine
- Das Topic der abzuarbeitenden External Tasks
- Eine Handler Funktion zum Verarbeiten der External Tasks

Beispiel:

`ts
import { ExternalTaskWorker } from '@5minds/processcube_engine_client';

interface AddPayload {
number1: number;
number2: number;
}

interface AddResult {
sum: number;
}

const engineUri = 'http://localhost:10560';
const topic = 'sum_numbers';

const externalTaskWorker = new ExternalTaskWorker(url, topic, doAdd, config);

externalTaskWorker.start();

async function doAdd(payload: AddPayload, externalTask: DataModels.ExternalTasks.ExternalTask): Promise {
const result: AddResult = {
sum: payload.number1 + payload.number2,
};

return result;
}
`

Der Worker lässt sich mit folgendem Befehl starten:

`ts
externalTaskWorker.start();
`

und mit folgendem Befehl stoppen:

`ts
externalTaskWorker.stop();
``

Ein ausführbares Code-Beispiel findet sich hier.