@5minds/processcube_engine_sdk 3.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-2023 https://processcube.5minds.de/
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# 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:
+
+```sh
+npm i --save @atlas-engine/atlas_engine_sdk
+```
+
+Beispiel:
+
+```ts
+import { Engine, EngineEvent, OnLoad } from '@atlas-engine/atlas_engine_sdk';
+
+export const onLoad: OnLoad = (engine: Engine) => {
+  engine.registerEventMiddleware(onEngineEvent);
+};
+
+function onEngineEvent(event: EngineEvent): Promise<void> {
+  return Promise.resolve();
+}
+```
+
+Unter [./sample/extension](./sample/extension/README.md) ist eine vollständige Beispiel-Implementierung zu finden.
+
+## Extensions in die Engine einbinden
+
+Standardmäßig werden Extensions aus dem Ordner `${HOME}/.atlas/engine/extensions` geladen. Der Pfad lässt sich mit dem Startup-Parameter
+`--extensionsDir` ändern.
+
+Sowohl beim Start über die CLI:
+
+```sh
+atlas-engine --extensionsDir '/my/custom/extensions/dir'
+```
+
+Als auch beim Start als embedded Software:
+
+```ts
+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.
+
+```sh
+tree -L 2 ${HOME}/.atlas/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.
+
+```json
+{
+  "name": "extension01",
+  "version": "1.0.0",
+  "main": "index.js",
+  "dependencies": {
+    "@atlas-engine/atlas_engine_sdk": "1.0.0-alpha.3"
+  }
+}
+```
+
+`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](#Interaktion-mit-der-Altas-Engine) als Parameter aufgerufen wird. In diesem Objekt finden sich alle Engine Funktionen,
+die von einer Extension genutzt werden können.
+
+```ts
+export const onLoad: OnLoad = (engine: Engine) => {
+  engine.registerEventMiddleware(onEngineEvent);
+};
+```
+
+## Interaktion mit der Altas 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.
+
+```ts
+import { Engine, EngineEvent, OnLoad } from '@atlas-engine/atlas_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.
+
+```ts
+import { Engine, EngineEvent, LogEventType, OnLoad } from '@atlas-engine/atlas_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.
+
+```ts
+{
+  id: 'ModifyTokenPayload',
+  tokenPayload: {example: 'token payload'},
+}
+```
+
+Werden mehrere `ModifyTokenPayload` Actions zurückgegeben, überschreibt der letzte TokenPayload immer die Vorherigen.
+
+## Weiterführende Links
+
+- [Engine](https://github.com/atlas-engine/AtlasEngine)
+- [TS Client](https://github.com/atlas-engine/AtlasEngine)

package/dist/DataModels/AnonymousSession.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     AnonymousSession:
+ *       description: Describes a session for an anonymous user.
+ *       type: object
+ *       required:
+ *         - sessionId
+ *         - userId
+ *         - createdAt
+ *       properties:
+ *         sessionId:
+ *           description: The ID of the session.
+ *           type: string
+ *         userId:
+ *           description: The ID of the user that created the session.
+ *           type: string
+ *         createdAt:
+ *           description: The date the anonymous session was created.
+ *           type: string
+ */
+export type AnonymousSession = {
+    sessionId: string;
+    userId: string;
+    createdAt: Date;
+};

package/dist/DataModels/ApplicationInfo.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     ApplicationInfo:
+ *       description: Contains basic information about the running application.
+ *       type: object
+ *       required:
+ *         - name
+ *         - packageName
+ *         - version
+ *         - authorityUrl
+ *         - allowAnonymousRootAccess
+ *         - extraInfo
+ *       properties:
+ *         name:
+ *           type: string
+ *           description: The name of the application.
+ *         packageName:
+ *           type: string
+ *           description: The name of the package the application is running in.
+ *         version:
+ *           type: string
+ *           description: The version of the application.
+ *         authorityUrl:
+ *           type: string
+ *           description: The URL of the IdentityServer that is used for authentication.
+ *         allowAnonymousRootAccess:
+ *           type: boolean
+ *           description: Flag indicating whether or not anonymous users are allowed to access the root route.
+ *         extraInfo:
+ *           type: object
+ *           description: Contains additional information about the application.
+ */
+export type ApplicationInfo = {
+    id?: string;
+    name: string;
+    packageName: string;
+    version: string;
+    authorityUrl: string;
+    allowAnonymousRootAccess: boolean;
+    extraInfo: any;
+};

package/dist/DataModels/Constants.d.ts

@@ -0,0 +1 @@
+export declare const defaultSocketNamespace = "/default";

package/dist/DataModels/Correlation.d.ts

@@ -0,0 +1,83 @@
+import { ProcessInstance } from './ProcessInstance/index';
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     CorrelationList:
+ *       description: A list of Correlations.
+ *       type: object
+ *       required:
+ *         - correlations
+ *         - totalCount
+ *       properties:
+ *         correlations:
+ *           description: The correlations
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/Correlation'
+ *         totalCount:
+ *           description: The total number of correlations
+ *           type: number
+ */
+export declare type CorrelationList = {
+    correlations: Array<Correlation>;
+    totalCount: number;
+};
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     CorrelationMetadata:
+ *       description: Metadata for a correlation.
+ *       type: object
+ *       additionalProperties:
+ *         type: string
+ */
+export declare type CorrelationMetadata = {
+    [key: string]: string;
+};
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     Correlation:
+ *       description: A Correlation.
+ *       type: object
+ *       required:
+ *         - correlationId
+ *       properties:
+ *         correlationId:
+ *           description: The id of the correlation.
+ *           type: string
+ *         metadata:
+ *           description: Metadata for the correlation.
+ *           $ref: '#/components/schemas/CorrelationMetadata'
+ *         processInstances:
+ *           description: The process instances that run in the context of this correlation.
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/ProcessInstance'
+ */
+/**
+ * Describes a Correlation.
+ * Correlations are used to group ProcessInstances into context.
+ */
+export declare type Correlation = {
+    correlationId: string;
+    /**
+     * Optional: A dictionary of all the metadata attached to this Correlation.
+     */
+    metadata?: CorrelationMetadata;
+    /**
+     * Optional: Contains a collection of ProcessInstances that run in the context of this Correlation.
+     */
+    processInstances?: Array<ProcessInstance>;
+};
+export declare enum CorrelationSortableColumns {
+    correlationId = "correlationId",
+    createdAt = "createdAt"
+}
+export declare type CorrelationSortSettings = {
+    sortBy: CorrelationSortableColumns;
+    sortDir?: 'ASC' | 'DESC';
+};

package/dist/DataModels/Cronjob/Cronjob.d.ts

@@ -0,0 +1,180 @@
+import { SearchQuery } from '../ProcessInstance/ProcessInstanceQuery';
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     ActiveCronjob:
+ *       description: Describes an active cronjob.
+ *       type: object
+ *       required:
+ *         - processDefinitionId
+ *         - processModelId
+ *         - startEventId
+ *         - crontab
+ *         - nextExecution
+ *       properties:
+ *         processDefinitionId:
+ *           type: string
+ *           description: The processDefinitionId that contains the ProcessModel with the cronjob.
+ *         processModelId:
+ *           type: string
+ *           description: The ID of the ProcessModel that contains the cronjob.
+ *         startEventId:
+ *           type: string
+ *           description: The ID of the StartEvent that contains the cronjob.
+ *         crontab:
+ *           type: string
+ *           description: The crontab that describs the cronjob.
+ *         nextExecution:
+ *           type: string
+ *           description: The next time the cronjob will be triggered.
+ */
+export declare type ActiveCronjob = {
+    /**
+     * The processDefinitionId that contains the ProcessModel with the cronjob.
+     */
+    processDefinitionId: string;
+    /**
+     * The ID of the ProcessModel that contains the cronjob.
+     */
+    processModelId: string;
+    /**
+     * The ID of the StartEvent that contains the cronjob.
+     */
+    startEventId: string;
+    /**
+     * The crontab that describs the cronjob.
+     */
+    crontab: string;
+    /**
+     * The next time the cronjob will be triggered.
+     */
+    nextExecution: Date;
+};
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     CronjobList:
+ *       description: A list of active cronjobs.
+ *       type: object
+ *       required:
+ *         - cronjobs
+ *         - totalCount
+ *       properties:
+ *         cronjobs:
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/ActiveCronjob'
+ *           description: The active cronjobs
+ *         totalCount:
+ *           type: number
+ *           description: The total number of active cronjobs
+ */
+export declare type CronjobList = {
+    cronjobs: Array<ActiveCronjob>;
+    totalCount: number;
+};
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     Cronjob:
+ *       description: Describes a cronjob.
+ *       type: object
+ *       required:
+ *         - processDefinitionId
+ *         - processModelId
+ *         - startEventId
+ *         - enabled
+ *         - crontab
+ *       properties:
+ *         processDefinitionId:
+ *           type: string
+ *           description: The ID of the ProcessDefinition that contains the cronjob.
+ *         processModelId:
+ *           type: string
+ *           description: The ID of the ProcessModel that contains the cronjob.
+ *         startEventId:
+ *           type: string
+ *           description: The ID of the StartEvent that contains the cronjob.
+ *         enabled:
+ *           type: boolean
+ *           description: Flag indicating whether or not the cronjob is enabled.
+ *         crontab:
+ *           type: string
+ *           description: The crontab that describs the cronjob.
+ *         startedProcessInstances:
+ *           type: number
+ *           description: The number of ProcessInstances that have been started by this cronjob.
+ *         lastStartedProcessInstance:
+ *           type: string
+ *           description: The ID of the last ProcessInstance that has been started by this cronjob.
+ *         lastTriggerDate:
+ *           type: string
+ *           description: The date of the last time the cronjob was triggered.
+ *         nextTriggerDate:
+ *           type: string
+ *           description: The date of the next time the cronjob will be triggered.
+ */
+export type Cronjob = {
+    processDefinitionId: string;
+    processModelId: string;
+    startEventId: string;
+    enabled: boolean;
+    crontab: string;
+    startedProcessInstances?: number;
+    lastStartedProcessInstance?: string;
+    lastTriggerDate?: Date;
+    nextTriggerDate?: Date;
+};
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     DeployedCronjobList:
+ *       description: A list of all deployed cronjobs.
+ *       type: object
+ *       required:
+ *         - cronjobs
+ *         - totalCount
+ *       properties:
+ *         cronjobs:
+ *           description: The deployed cronjobs
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/Cronjob'
+ *         totalCount:
+ *           description: The total number of deployed cronjobs
+ *           type: number
+ */
+export type DeployedCronjobList = {
+    cronjobs: Array<Cronjob>;
+    totalCount: number;
+};
+export declare type CronjobQuery = {
+    processDefinitionId?: Array<string> | string | SearchQuery;
+    processModelId?: Array<string> | string | SearchQuery;
+    startEventId?: Array<string> | string | SearchQuery;
+    crontab?: Array<string> | string | SearchQuery;
+    enabled?: boolean;
+    lastTriggerDate?: Array<Date> | Date;
+    lastTriggerDateBefore?: Date;
+    lastTriggerDateAfter?: Date;
+    nextTriggerDate?: Array<Date> | Date;
+    nextTriggerDateBefore?: Date;
+    nextTriggerDateAfter?: Date;
+};
+export declare type CronjobSortSettings = {
+    sortBy: CronjobSortableColumns;
+    sortDir?: 'ASC' | 'DESC';
+};
+export declare enum CronjobSortableColumns {
+    processDefinitionId = "processDefinitionId",
+    processModelId = "processModelId",
+    startEventId = "startEventId",
+    crontab = "crontab",
+    enabled = "enabled",
+    lastTriggerDate = "lastTriggerDate",
+    nextTriggerDate = "nextTriggerDate"
+}

package/dist/DataModels/Cronjob/CronjobHistory.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     CronjobHistoryEntry:
+ *       description: Describes a single entry in the list of cronjob histories.
+ *       type: object
+ *       required:
+ *         - processDefinitionId
+ *         - processModelId
+ *         - startEventId
+ *         - crontab
+ *         - executedAt
+ *       properties:
+ *         processDefinitionId:
+ *           description: The ID of the process definition
+ *           type: string
+ *         processModelId:
+ *           description: The ID of the process model
+ *           type: string
+ *         startEventId:
+ *           description: The ID of the start event
+ *           type: string
+ *         crontab:
+ *           description: The crontab that describs the cronjob.
+ *           type: string
+ *         executedAt:
+ *           description: The time the cronjob was executed.
+ *           type: string
+ *         processInstanceId:
+ *           description: The ID of the process instance that was started by the cronjob.
+ *           type: string
+ */
+export declare type CronjobHistoryEntry = {
+    processDefinitionId: string;
+    processModelId: string;
+    startEventId: string;
+    crontab: string;
+    executedAt: Date;
+    processInstanceId?: string;
+};
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     CronjobHistoryList:
+ *       description: A list of cronjob histories.
+ *       type: object
+ *       required:
+ *         - cronjobHistories
+ *         - totalCount
+ *       properties:
+ *         cronjobHistories:
+ *           description: The cronjob histories
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/CronjobHistoryEntry'
+ *         totalCount:
+ *           description: The total number of cronjob histories
+ *           type: number
+ */
+export declare type CronjobHistoryList = {
+    cronjobHistories: Array<CronjobHistoryEntry>;
+    totalCount: number;
+};
+export declare type CronjobHistoryQuery = {
+    processDefinitionId?: Array<string> | string;
+    processModelId?: Array<string> | string;
+    startEventId?: Array<string> | string;
+    crontab?: Array<string> | string;
+    executedAt?: Array<Date> | Date;
+    createdAt?: Array<Date> | Date;
+    updatedAt?: Array<Date> | Date;
+};
+export declare type CronjobHistorySortSettings = {
+    sortBy: CronjobHistorySortableColumns;
+    sortDir?: 'ASC' | 'DESC';
+};
+export declare enum CronjobHistorySortableColumns {
+    processDefinitionId = "processDefinitionId",
+    processModelId = "processModelId",
+    startEventId = "startEventId",
+    crontab = "crontab",
+    createdAt = "createdAt",
+    executedAt = "executedAt"
+}

package/dist/DataModels/Cronjob/index.d.ts

@@ -0,0 +1,2 @@
+export * from './CronjobHistory';
+export * from './Cronjob';