Merge pull request #131 from jwulf/129-complete-forwarded

Fixes #129 - add complete.forwarded

Author: s3than

README.md

@@ -331,20 +331,26 @@ zbc.createWorker('test-worker', 'console-log', maybeFaultyHandler, {
 })
 ```
 
-### Completing tasks with success, failure, or error
+### Completing tasks with success, failure, error, or forwarded
 
 To complete a task, the task worker handler function receives a `complete` parameter. The complete object has `success`, `failure`, and `error` methods.
 
 Call `complete.success()` passing in a optional plain old JavaScript object (POJO) - a key:value map. These are variable:value pairs that will be used to update the workflow state in the broker. They will be merged with existing values. You can set an existing key to `null` or `undefined`, but there is no way to delete a key.
 
 Call `complete.failure()` to fail the task. You must pass in a string message describing the failure. The client library decrements the retry count, and the broker handles the retry logic. If the failure is a hard failure and should cause an incident to be raised in Operate, then pass in `0` for the optional second parameter, `retries`:
 
-Call `complete.error()` to trigger a BPMN error throw event. You must pass in a string error code for the error code, and you can pass an optional error message as the second parameter. If no BPMN error catch event exists for the error code, an incident will be raised.
-
 ```javascript
 complete.failure('This is a critical failure and will raise an incident', 0)
 ```
 
+Call `complete.error()` to trigger a BPMN error throw event. You must pass in a string error code for the error code, and you can pass an optional error message as the second parameter. If no BPMN error catch event exists for the error code, an incident will be raised.
+
+Call `complete.forwarded()` to release worker capacity to handle another job, without completing the job in any way with the Zeebe broker. This method supports the _decoupled job completion_ pattern. In this pattern, the worker forwards the job to another system - a lambda or a RabbitMQ queue. Some other process is ultimately responsible for completing the job.
+
+## Completing jobs in the decoupled job completion pattern
+
+You can use the ZBClient methods `completeJob()`, `failJob()`, and `throwError()` in the decoupled pattern to complete jobs that were activated by another process. In contrast to the worker `complete` methods, the ZBClient methods require a specific job key, so you must pass the job key with the job data when forwarding the job from the worker that activates it to a remote system.
+
 ### Long polling
 
 With Zeebe 0.21 onward, long polling is supported for clients, and is used by default. Rather than polling continuously for work and getting nothing back, a client can poll once and leave the request open until work appears. This reduces network traffic and CPU utilization in the server. Every JobActivation Request is appended to the event log, so continuous polling can significantly impact broker performance, especially when an exporter is loaded (see [here](https://github.com/creditsenseau/zeebe-client-node-js/issues/64#issuecomment-520233275)).

src/lib/interfaces.ts

@@ -27,6 +27,11 @@ export interface CompleteFn<WorkerOutputVariables> {
 	 * count is decremented. Pass in `0`for retries to raise an incident in Operate.
 	 */
 	failure: (errorMessage: string, retries?: number) => void
+	/**
+	 * Mark this job as forwarded to another system for completion. No action is taken by the broker.
+	 * This method releases worker capacity to handle another job.
+	 */
+	forwarded: () => void
 	/**
 	 *
 	 * Report a business error (i.e. non-technical) that occurs while processing a job.

src/zb/ZBClient.ts

@@ -241,7 +241,9 @@ export class ZBClient extends EventEmitter {
 	): Promise<void> {
 		const withStringifiedVariables = stringifyVariables(completeJobRequest)
 		this.logger.debug(withStringifiedVariables)
-		return this.gRPCClient.completeJobSync(withStringifiedVariables)
+		return this.executeOperation('completeJob', () =>
+			this.gRPCClient.completeJobSync(withStringifiedVariables)
+		)
 	}
 
 	// tslint:disable: no-object-literal-type-assertion

src/zb/ZBWorker.ts

@@ -310,7 +310,7 @@ export class ZBWorker<
 			 * complete.success(variables?: object) and complete.failure(errorMessage: string, retries?: number)
 			 *
 			 * To halt execution of the business process and raise an incident in Operate, call
-			 * complete(errorMessage, 0)
+			 * complete.failure(errorMessage, 0)
 			 */
 
 			const workerCallback = {
@@ -345,6 +345,7 @@ export class ZBWorker<
 						this.drainOne()
 					}
 				},
+				forwarded: () => this.drainOne(),
 				success: async (completedVariables = {}) => {
 					let res
 					try {