Skip to content

Latest commit

 

History

History
159 lines (121 loc) · 10.5 KB

Client.md

File metadata and controls

159 lines (121 loc) · 10.5 KB
Raw

Client

const { Client } = require("camunda-external-task-handler-js");

const client = new Client({baseUrl: "http://localhost:8080/engine-rest"});

client.subscribe("foo", async function({task, taskService}) {
  // Put your business logic
});

Client is the core class of the external task client. It is mainly used to start/stop the external task client and subscribe to a certain topic.

new Client(options)

Options are mandatory when creating a Client instance.

Here"s a list of the available options:

Option Description Type Required Default
baseUrl Path to the engine api string ✓
workerId The id of the worker on which behalf tasks are fetched. The returned tasks are locked for that worker and can only be completed when providing the same worker id. string "some-random-id"
maxTasks The maximum number of tasks to fetch number 10
maxParallelExecutions The maximum number of tasks to be worked on simultaneously number
interval Interval of time to wait before making a new poll. number 300
lockDuration The default duration to lock the external tasks for in milliseconds. number 50000
autoPoll If true, then polling start automatically as soon as a Client instance is created. boolean true
asyncResponseTimeout The Long Polling timeout in milliseconds. number
usePriority If false, task will be fetched arbitrarily instead of based on its priority. boolean true
interceptors Function(s) that will be called before a request is sent. Interceptors receive the configuration of the request and return a new configuration. function or [function]
use Function(s) that have access to the client instance as soon as it is created and before any polling happens. Check out logger for a better understanding of the usage of middlewares. function or [function]
sorting Defines the sorting of the fetched tasks. It can be used together with usePriority, but the sorting will be based on priority first. Array of Sorting objects

Sorting object properties:

Option Description Type Required Default
sortBy Specifies the sorting by property. Possible values. string ✓
sortOrder Specifies the sorting direction. Possible values. string ✓

About interceptors

  • Interceptors receive the configuration of the request and return a new configuration.
  • In the case of multiple interceptors, they are piped in the order they are provided.
  • Check out BasicAuthInterceptor for a better understanding of the usage of interceptors.

client.start()

Triggers polling.

About Polling

  • Polling tasks from the engine works by performing a fetch & lock operation of tasks that have subscriptions. It then calls the handler registered to each task.
  • Polling is done periodically based on the interval configuration.
  • Long Polling is enabled by configuring the option asyncResponseTimeout.

client.subscribe(topic, options, handler)

Subscribes a handler to a specific topic and returns a topic subscription. Here"s a list of the available parameters:

Parameter Description Type Required
topic topic name for which external tasks should be fetched string ✓
options options about subscription object
handler function to handle fetched task. Checkout this for more information function ✓

The currently supported options are:

Option Description Type Required Default
lockDuration specifies the lock duration for this specific handler. number global lockDuration configured in the client instance
variables defines a subset of variables available in the handler. array global lockDuration configured in the client instance
businessKey A value which allows to filter tasks based on process instance business key string
processDefinitionId A value which allows to filter tasks based on process definition id string
processDefinitionIdIn A value which allows to filter tasks based on process definition ids string
processDefinitionKey A value which allows to filter tasks based on process definition key string
processDefinitionKeyIn A value which allows to filter tasks based on process definition keys string
processDefinitionVersionTag A value which allows to filter tasks based on process definition Version Tag string
processVariables A JSON object used for filtering tasks based on process instance variable values. A property name of the object represents a process variable name, while the property value represents the process variable value to filter tasks by. object
tenantIdIn A value which allows to filter tasks based on tenant ids string
withoutTenantId A value which allows to filter tasks without tenant id boolean
localVariables A value which allow to fetch only local variables boolean
includeExtensionProperties A value which allow to fetch extensionProperties boolean

About topic subscriptions

A topic subscription, which is returned by the subscribe() method, is a an object that provides the following:

  • handler: a function that is executed whenever a task is fetched & locked for the topic subscribed to.
  • unsubscribe(): a function to unsubscribe from a topic.
  • lockDuration: the configured lockDuration for this specific topic subscription.
  • variables: the selected subset of variables.
const {Client} = require("camunda-external-task-client-js");

const client = new Client({baseUrl: "http://localhost:8080/engine-rest"});

const topicSubscription = client.subscribe(
  "foo",
  {
    // Put your options here
    processDefinitionVersionTag: "v2"
  },
  async function({task, taskService}) {
    // Put your business logic
  }
);

// unsubscribe from a topic
topicSubscription.unsubscribe();

client.stop()

Stops polling.

Client Events

Check out logger for a better understanding of the usage of events. Here"s a list of available client events:

  • client.on("subscribe", function(topic, topicSubscription) {})
  • client.on("unsubscribe", function(topic, topicSubscription) {})
  • client.on("poll:start", function() {})
  • client.on("poll:stop", function() {})
  • client.on("poll:success", function(tasks) {})
  • client.on("poll:error", function(error) {})
  • client.on("complete:success", function(task) {})
  • client.on("complete:error", function(task, error) {})
  • client.on("handleFailure:success", function(task) {})
  • client.on("handleFailure:error", function(task, error) {})
  • client.on("handleBpmnError:success", function(task) {})
  • client.on("handleBpmnError:error", function(task, error) {})
  • client.on("extendLock:success", function(task) {})
  • client.on("extendLock:error", function(task, error) {})
  • client.on("unlock:success", function(task) {})
  • client.on("unlock:error", function(task, error) {})
  • client.on("lock:success", function(task) {})
  • client.on("lock:error", function(task, error) {})

Error

The error object exposes the response body of the REST API request and has the following properties:

Property Description Type
message A summary of the error, e.g., Response code 400 (Bad Request); Error: my engine error; Type: ProcessEngineException; Code: 33333 string
httpStatusCode The HTTP status code returned by the REST API, e.g., 400 number
engineMsg The engine error message, e.g., my engine error string
type The class name of the exception, e.g., ProcessEngineException string
code A numeric exception error code, e.g., 33333. number

You can find more information about the exception error code feature in the Camunda Platform 7 Documentation.