Engine SDK

Das Engine SDK stellt Typen und Schnittstellen bereit, um Extensions für die Engine zu entwickeln.

Verwendung des SDKs

Das SDK kann über npm bezogen werden:

npm i --save @5minds/processcube_engine_sdk

Beispiel:

import { Engine, EngineEvent, OnLoad } from '@5minds/processcube_engine_sdk';

export const onLoad: OnLoad = (engine: Engine) => {
  engine.registerEventMiddleware(onEngineEvent);
};

function onEngineEvent(event: EngineEvent): Promise<void> {
  return Promise.resolve();
}

Extensions in die Engine einbinden

Standardmäßig werden Extensions aus dem Ordner ${HOME}/.processcube/engine/extensions geladen. Der Pfad lässt sich mit dem Startup-Parameter --extensionsDir ändern.

Sowohl beim Start über die CLI:

processcube-engine --extensionsDir '/my/custom/extensions/dir'

Als auch beim Start als embedded Software:

await Engine.launch({
  extensionsDir: '/my/custom/extensions/dir',
});

Aufbau einer Extension

Jede zu ladende Extension muss in einem eigenen Unterordner von extensionsDir liegen und mindestens eine package.json und eine nach JavaScript transpilierte Einstiegspunkt-Datei enthalten, die in der package.json als main angegeben ist.

tree -L 2 ${HOME}/.processcube/engine/extensions
├── extension01
│   ├── index.js
│   └── package.json
└── extension02
    ├── index.js
    └── package.json

Jede Extension muss mindestens eine eigene package.json mit name, version und main enthalten.

{
  "name": "extension01",
  "version": "1.0.0",
  "main": "index.js",
  "dependencies": {
    "@5minds/processcube_engine_sdk": "^3.3.0"
  }
}

main muss auf eine gültige JavaScript-Datei zeigen, in welcher die Extension gehostet wird.

In der main-Datei können Extensions eine onLoad-Funktion exportieren, die von der Engine beim Laden mit einem Engine-Objekt als Parameter aufgerufen wird. In diesem Objekt finden sich alle Engine Funktionen, die von einer Extension genutzt werden können.

export const onLoad: OnLoad = (engine: Engine) => {
  engine.registerEventMiddleware(onEngineEvent);
};

Interaktion mit der Engine

Der Engine Typ stellt Schnittstellen zur Interaktion mit der Engine bereit.

registerEventMiddleware

registerEventMiddleware erlaubt es einer Extension sich auf Log Events der Engine zu subscriben.

Der hier angegebene Callback wird dann bei jedem eingehenden Log Event ausgeführt.

import { Engine, EngineEvent, OnLoad } from '@5minds/processcube_engine_sdk';

export const onLoad: OnLoad = (engine: Engine): void => {
  // Die Funktion `onEngineEvent` wird als Event-Middleware registriert
  engine.registerEventMiddleware(onEngineEvent);
};

// Gibt den Typen jedes empfangenen Events auf der Konsole aus
function onEngineEvent(event: EngineEvent): void {
  console.log(`Received event ${event.eventType}`);
}

EngineActions

Die Engine erlaubt mittels EngineActions ein Eingreifen in die Prozessausführung. Eine Middleware kann eine, keine oder mehrere EngineActions zurückgeben, die dann von der Engine nacheinander ausgeführt werden, bevor die Prozessausführung fortgesetzt wird.

Eine EngineAction ist ein Datenobjekt, dass mindestens eine Id enthält, die die Art der EngineAction festlegt und weitere EngineAction-spezifische Properties, die für die Ausführung der EngineAction benötigt werden.

import { Engine, EngineEvent, LogEventType, OnLoad } from '@5minds/processcube_engine_sdk';

export const onLoad: OnLoad = (engine: Engine): void => {
  // Die Funktion `onEngineEvent` wird als Event-Middleware registriert
  engine.registerEventMiddleware(onEngineEvent);
};

// Gibt den Typen jedes empfangenen Events auf der Konsole aus
function onEngineEvent(event: EngineEvent): void {
  console.log(`Received event ${event.eventType}`);

  if (event.eventType === LogEventType.OnFlowNodeExited) {
    // Gibt die EngineAction 'ModifyTokenPayload' zurück
    return {
      id: 'ModifyTokenPayload',
      tokenPayload: { result: 'token was modified' },
    };
  }
}

Folgende EngineActions werden derzeit unterstützt:

ModifyTokenPayload Action

Die ModifyTokenPayload Action kann verwendet werden um den Payload des aktuellen Tokens zu verändern. Daher kann die ModifyTokenPayload Action nur verwendet werden, wenn das auslösende EngineEvent zu einer FlowNode gehört. Solche Events fangen immer mit OnFlowNode an (bspw.: OnFlowNodeEntered). Sollte eine ModifyTokenPayload Action für ein Event das nicht zu einer FlowNode gehört zurückgegeben wird, wird die Action nicht ausgeführt und ein Fehler wird gelogt.

Eine ModifyTokenPayload Action besteht aus 2 Eigenschaften:

1. Die id, die immer ModifyTokenPayload entspricht
2. Die tokenPayload, der den payload des aktuellen Tokens der entsprechenden FlowNode ersetzt.

{
  id: 'ModifyTokenPayload',
  tokenPayload: {example: 'token payload'},
}

Werden mehrere ModifyTokenPayload Actions zurückgegeben, überschreibt der letzte TokenPayload immer die Vorherigen.

Weiterführende Links

• Engine
• TS Client