@5minds/processcube_engine_client

Engine Client.ts

A client for communicating with the Engine.

It is written in TypeScript and implemented in NodeJS.

Quick example

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

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

async function run() {
  const client = new EngineClient(engineUri);

  const processInstances = await client.processInstances.query({});

  console.log(processInstances);
}

run();

How to use the client

You only need to provide an url to the Engine you want to access. After that, the client is ready to use.

You can either create a single EngineClient, which exposes references to all other clients,

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

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

async function run() {
  const client = new EngineClient(engineUri);

  const processInstances = await client.processInstances.query({}, null, 0, 100);

  console.log(processInstances);
}

run();

or create multiple specific clients with the ClientFactory:

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

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

async function run() {
  const processInstanceClient = ClientFactory.createProcessInstanceClient(engineUri);

  const processInstances = await processInstanceClient.query({}, null, 0, 100);

  console.log(processInstances);
}

run();

Starting Process Instances

You can start new Process Instances through processDefinitionsClient.startProcessInstance(parameters) - Resolves right after the Process Instance was started

Where parameters is an object that collects all startup parameters.

The following parameters are required:

• processModelId: The ID of the Process Model to execute
• startEventId: The ID of the Start Event by which to start the Process Model. Optional, if the Process Model only has one Start Event.

In addition, the following optional parameters are available:

• correlationId: The ID of the correlation to which this Process Instance belongs. If not provided, it will be auto-generated
• initialToken: The initial process token with which to start the Process Instance
• parentProcessInstanceId: When the Process Instance is supposed to be the Subprocess of another Process Instance, this contains the ID of the parent Process Instance

or through

processDefinitionsClient.startProcessInstanceAndAwaitEndEvent(parameters) - Resolves when the Process Instance has finished with any End Event

or through

processDefinitionsClient.startProcessInstanceAndAwaitSpecificEndEvent(parameters, endEventId) - Resolves after the ProcessInstance has reached a specific End Event and has additionally the required endEventId parameter:

• endEventId: The ID of the End Event to wait for

Examples:

Start Process Instance and wait for it to start

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

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

async function run() {
  const client = new EngineClient(engineUri);

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

run();

Start Process Instance and wait for it to finish

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

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

async function run() {
  const client = new EngineClient(engineUri);

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

run();

Start Process Instance and wait for an End Event

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

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

async function run() {
  const client = new EngineClient(engineUri);

  await client.processDefinitions.startProcessInstanceAndAwaitSpecificEndEvent({processModelId: 'myProcessModelId'}, 'My_End_Event_1');
}

run();

Start Process Instance with custom payload and correlation ID

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

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

async function run() {
  const client = new EngineClient(engineUri);

  await client.processDefinitions.startProcessInstance({
    processModelId: 'myProcessModelId',
    correlationId: 'my_custom_correlation_id',
    initialToken: {
      hello: 'world',
    },
  });
}

run();

Start Process Instance as a sub process

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

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

async function run() {
  const client = new EngineClient(engineUri);

  await client.processDefinitions.startProcessInstance({
    processModelId: 'myProcessModelId',
    parentProcessInstanceId: 'Some-Other-Process-Instance-Id',
  });
}

run();

Code Samples

You can find executable code samples here and here.

Query UserTasks

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

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

async function run() {
  const client = new EngineClient(engineUri);

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

  console.log(userTasks);
}

run();

How to use External Task Workers

An External Task worker is designed to process External Tasks associated with a BPMN ServiceTask.

Basic

You need to provide three arguments to a worker:

• The url of the Engine where the worker should connect to
• The topic by which to poll External Tasks
• A handler function for processing the External Tasks

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

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

interface AddResult {
  sum: number;
}

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

async function run() {
  const client = new EngineClient(engineUri);

  const externalTaskWorker = await client.externalTasks.subscribeToExternalTaskTopic(topic, doAdd);

  externalTaskWorker.start();
}

async function doAdd(
  payload: AddPayload,
  externalTask: DataModels.ExternalTasks.ExternalTask<AddPayload>,
): Promise<AddResult> {

  const result: AddResult = {
    sum: payload.number1 + payload.number2,
  };

  console.log('Receive payload from process instance');
  console.log(JSON.stringify(payload));

  return Promise.resolve(result);
}

run();

Note that by subscribing to a single topic, you create a specific worker for this topic.

Starting and stopping

Start the worker with:

externalTaskWorker.start();

And stop it with:

externalTaskWorker.stop();

Code Samples

You can find executable code samples here and here.