# 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.

### EngineClient

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',
});
```

### Client Factory

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.

### Prozesse starten

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<AddPayload, AddResult>(url, topic, doAdd, config);

externalTaskWorker.start();

async function doAdd(payload: AddPayload, externalTask: DataModels.ExternalTasks.ExternalTask<AddPayload>): Promise<AddResult> {
  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](./samples/external_task_worker/).