{"id":13590072,"url":"https://github.com/camunda/camunda-external-task-client-js","last_synced_at":"2025-10-24T10:52:24.560Z","repository":{"id":30294865,"uuid":"122339156","full_name":"camunda/camunda-external-task-client-js","owner":"camunda","description":"Implement your BPMN Service Task in NodeJS.","archived":false,"fork":false,"pushed_at":"2025-05-02T09:35:40.000Z","size":4554,"stargazers_count":225,"open_issues_count":14,"forks_count":94,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-05-02T10:35:55.934Z","etag":null,"topics":["camunda","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/camunda.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-02-21T13:21:23.000Z","updated_at":"2025-04-24T01:33:52.000Z","dependencies_parsed_at":"2024-01-05T10:28:54.876Z","dependency_job_id":"c78e5a56-c80b-47c1-817c-9203adb5dfa1","html_url":"https://github.com/camunda/camunda-external-task-client-js","commit_stats":{"total_commits":263,"total_committers":27,"mean_commits":9.74074074074074,"dds":0.55893536121673,"last_synced_commit":"67d14e3ab8772f08e5882801ef676759994570f1"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camunda%2Fcamunda-external-task-client-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camunda%2Fcamunda-external-task-client-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camunda%2Fcamunda-external-task-client-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camunda%2Fcamunda-external-task-client-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/camunda","download_url":"https://codeload.github.com/camunda/camunda-external-task-client-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253625853,"owners_count":21938209,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["camunda","nodejs"],"created_at":"2024-08-01T16:00:38.688Z","updated_at":"2025-10-24T10:52:19.503Z","avatar_url":"https://github.com/camunda.png","language":"JavaScript","funding_links":[],"categories":["Supported Code by Camunda"],"sub_categories":[],"readme":"# camunda-external-task-client\n\n[![npm version](https://badge.fury.io/js/camunda-external-task-client-js.svg)](https://badge.fury.io/js/camunda-external-task-client-js)\n![CI](https://github.com/camunda/camunda-external-task-client-js/actions/workflows/CI.yml/badge.svg)\n\nImplement your [BPMN Service Task](https://docs.camunda.org/manual/latest/user-guide/process-engine/external-tasks/) in\nNodeJS.\n\n\u003e This package is an [ECMAScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) (ESM) and provides no CommonJS exports.\n\n\u003e NodeJS \u003e= v18 is required\n\n## Installing\n\n```sh\nnpm install -s camunda-external-task-client-js\n```\n\nOr:\n\n```sh\nyarn add camunda-external-task-client-js\n```\n\n## Usage\n\n1.  Make sure to have [Camunda](https://camunda.com/download/) running.\n2.  Create a simple process model with an External Service Task and define the topic as 'topicName'.\n3.  Deploy the process to the Camunda Platform engine.\n4.  In your NodeJS script:\n\n```js\nimport { Client, logger } from \"camunda-external-task-client-js\";\n\n// configuration for the Client:\n//  - 'baseUrl': url to the Process Engine\n//  - 'logger': utility to automatically log important events\nconst config = { baseUrl: \"http://localhost:8080/engine-rest\", use: logger };\n\n// create a Client instance with custom configuration\nconst client = new Client(config);\n\n// susbscribe to the topic: 'creditScoreChecker'\nclient.subscribe(\"creditScoreChecker\", async function({ task, taskService }) {\n  // Put your business logic\n  // complete the task\n  await taskService.complete(task);\n});\n```\n\n\u003e **Note:** Although the examples used in this documentation use _async await_ for handling asynchronous calls, you\n\u003e can also use Promises to achieve the same results.\n\n## About External Tasks\n\nExternal Tasks are service tasks whose execution differs particularly from the execution of other service tasks (e.g. Human Tasks).\nThe execution works in a way that units of work are polled from the engine before being completed.\n\n**camunda-external-task-client.js** allows you to create easily such client in NodeJS.\n\n## Features\n\n### [Fetch and Lock](https://docs.camunda.org/manual/latest/reference/rest/external-task/fetch/)\n\nDone through [polling](/docs/Client.md#about-polling).\n\n### [Complete](https://docs.camunda.org/manual/latest/reference/rest/external-task/post-complete/)\n\n```js\n// Susbscribe to the topic: 'topicName'\nclient.subscribe(\"topicName\", async function({ task, taskService }) {\n  // Put your business logic\n  // Complete the task\n  await taskService.complete(task);\n});\n```\n\n### [Handle Failure](https://docs.camunda.org/manual/latest/reference/rest/external-task/post-failure/)\n\n```js\n// Susbscribe to the topic: 'topicName'\nclient.subscribe(\"topicName\", async function({ task, taskService }) {\n  // Put your business logic\n  // Handle a Failure\n  await taskService.handleFailure(task, {\n    errorMessage: \"some failure message\",\n    errorDetails: \"some details\",\n    retries: 1,\n    retryTimeout: 1000\n  });\n\n});\n```\n\n### [Handle BPMN Error](https://docs.camunda.org/manual/latest/reference/rest/external-task/post-bpmn-error/)\n\n```js\n// Susbscribe to the topic: 'topicName'\nclient.subscribe(\"topicName\", async function({ task, taskService }) {\n  // Put your business logic\n\n  // Create some variables\n  const variables = new Variables().set('date', new Date());\n\n  // Handle a BPMN Failure\n  await taskService.handleBpmnError(task, \"BPMNError_Code\", \"Error message\", variables);\n});\n```\n\n### [Extend Lock](https://docs.camunda.org/manual/latest/reference/rest/external-task/post-extend-lock/)\n\n```js\n// Susbscribe to the topic: 'topicName'\nclient.subscribe(\"topicName\", async function({ task, taskService }) {\n  // Put your business logic\n  // Extend the lock time\n  await taskService.extendLock(task, 5000);\n});\n```\n\n### [Unlock](https://docs.camunda.org/manual/latest/reference/rest/external-task/post-unlock/)\n\n```js\n// Susbscribe to the topic: 'topicName'\nclient.subscribe(\"topicName\", async function({ task, taskService }) {\n  // Put your business logic\n  // Unlock the task\n  await taskService.unlock(task);\n});\n```\n\n### [Lock](https://docs.camunda.org/manual/latest/reference/rest/external-task/post-lock/)\n```js\n// Susbscribe to the topic: 'topicName'\nclient.subscribe(\"topicName\", async function({ task, taskService }) {\n  // Task is locked by default\n  // Put your business logic, unlock the task or let the lock expire\n\n  // Lock a task again\n  await taskService.lock(task, 5000);\n});\n```\n\n### Exchange Process \u0026 Local Task Variables\n\n```js\nimport { Variables } from \"camunda-external-task-client-js\";\n\nclient.subscribe(\"topicName\", async function({ task, taskService }) {\n  // get the process variable 'score'\n  const score = task.variables.get(\"score\");\n\n  // set a process variable 'winning'\n  const processVariables = new Variables();\n  processVariables.set(\"winning\", score \u003e 5);\n\n  // set a local variable 'winningDate'\n  const localVariables = new Variables();\n  localVariables.set(\"winningDate\", new Date());\n\n  // complete the task\n  await taskService.complete(task, processVariables, localVariables);\n});\n```\n\n## API\n\n* [Client](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Client.md)\n  * [new Client(options)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Client.md#new-clientoptions)\n  * [client.start()](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Client.md#clientstart)\n  * [client.subscribe(topic, [options], handler)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Client.md#clientsubscribetopic-options-handler)\n  * [client.stop()](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Client.md#clientstop)\n  * [Client Events)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Client.md#client-events)\n  * [About the Handler Function](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/handler.md)\n* [Variables](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Variables.md)\n  * [new Variables(options)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Variables.md#new-variablesoptions\")\n  * [variables.get(variableName)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Variables.md#variablesgetvariablename)\n  * [variables.getTyped(variableName)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Variables.md#variablesgettypedvariablename)\n  * [variables.getAll()](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Variables.md#variablesgetall)\n  * [variables.getAllTyped()](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Variables.md#variablesgetalltyped)\n  * [variables.set(variableName)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Variables.md#variablessetvariablename-value)\n  * [variables.setTyped(variableName)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Variables.md#variablessettypedvariablename-typedvalue)\n  * [variables.setAll(values)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Variables.md#variablessetallvalues)\n  * [variables.setAllTyped(typedValues)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Variables.md#variablessetalltypedtypedvalues)\n  * [About JSON \u0026 Date Variables](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/Variables.md#about-json--date-variables)\n* [File](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/File.md)\n  * [new File(options)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/File.md#new-fileoptions)\n  * [file.load()](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/File.md#fileload)\n  * [File Properties](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/File.md#file-properties)\n* [BasicAuthInterceptor](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/BasicAuthInterceptor.md)\n  * [new BasicAuthInterceptor(options)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/BasicAuthInterceptor.md#new-basicauthinterceptoroptions)\n* [KeycloakAuthInterceptor](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/KeycloakAuthInterceptor.md)\n  * [new KeycloakAuthInterceptor(options)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/KeycloakAuthInterceptor.md#new-keycloakauthinterceptoroptions)\n* [logger](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/logger.md)\n  * [logger.success(text)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/logger.md#loggersuccesstext)\n  * [logger.error(text)](https://github.com/camunda/camunda-external-task-client-js/blob/master/docs/logger.md#loggererrortext)\n\n## Contributing\n\nHave a look at our [contribution guide](https://github.com/camunda/camunda-bpm-platform/blob/master/CONTRIBUTING.md) for how to contribute to this repository.\n\n## Help and support\n\n* [Documentation](https://docs.camunda.org/manual/latest/)\n* [Forum](https://forum.camunda.org)\n* [Stackoverflow](https://stackoverflow.com/questions/tagged/camunda)\n\n## License\n\nThe source files in this repository are made available under the [Apache License Version 2.0](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcamunda%2Fcamunda-external-task-client-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcamunda%2Fcamunda-external-task-client-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcamunda%2Fcamunda-external-task-client-js/lists"}