dapr
/
docs
mirror of https://github.com/dapr/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add documentation for the Zeebe bindings

This commit is contained in:
Christian.Kaps 2021-04-22 18:03:59 +02:00
parent 744244aeea
commit dffa1b3106
3 changed files with 691 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
daprdocs/content/en/reference/components-reference/supported-bindings/_index.md
View File

@ -43,7 +43,6 @@ Table captions:
| [Twitter]({{< ref twitter.md >}}) | ✅ | ✅ | Alpha | v1 | 1.0 |
| [SendGrid]({{< ref sendgrid.md >}}) | | ✅ | Alpha | v1 | 1.0 |
### Alibaba Cloud
| Name | Input<br>Binding | Output<br>Binding | Status |
@ -78,3 +77,10 @@ Table captions:
| [Azure Service Bus Queues]({{< ref servicebusqueues.md >}}) | ✅ | ✅ | Alpha | v1 | 1.0 |
| [Azure SignalR]({{< ref signalr.md >}}) | | ✅ | Alpha | v1 | 1.0 |
| [Azure Storage Queues]({{< ref storagequeues.md >}}) | ✅ | ✅ | GA | v1 | 1.0 |
### Zeebe (Camunda)
| Name | Input<br>Binding | Output<br>Binding | Status | Component version | Since |
|------|:----------------:|:-----------------:|--------| --------- | ---------- |
| [Zeebe Command]({{< ref zeebe-command.md >}}) | | ✅ | Alpha | v1 | 1.2 |
| [Zeebe Job Worker]({{< ref zeebe-jobworker.md >}}) | ✅ | | Alpha | v1 | 1.2 |

583
daprdocs/content/en/reference/components-reference/supported-bindings/zeebe-command.md Normal file
View File

@ -0,0 +1,583 @@
---
type: docs
title: "Zeebe command binding spec"
linkTitle: "Zeebe command"
description: "Detailed documentation on the Zeebe command binding component"
aliases:
- "/operations/components/setup-bindings/supported-bindings/zeebe-commands/"
---
## Component format
To setup Zeebe command binding create a component of type `bindings.zeebe.command`. See [this guide]({{< ref "howto-bindings.md#1-create-a-binding" >}}) on how to create and apply a binding configuration.
See [this](https://docs.camunda.io/docs/product-manuals/zeebe/zeebe-overview/) for Zeebe documentation.
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <NAME>
namespace: <NAMESPACE>
spec:
type: bindings.zeebe.command
version: v1
metadata:
- name: gatewayAddr
value: <host>:<port>
- name: gatewayKeepAlive
value: 45s
- name: usePlainTextConnection
value: true
- name: caCertificatePath
value: /path/to/ca-cert
```
## Spec metadata fields
| Field | Required | Binding support | Details | Example |
|-------------------------|:--------:|------------|-----|---------|
| gatewayAddr | Y | Output | Zeebe gateway address | `localhost:26500` |
| gatewayKeepAlive | N | Output | Sets how often keep alive messages should be sent to the gateway. Defaults to 45 seconds | `45s` |
| usePlainTextConnection | N | Output | Whether to use a plain text connection or not | `true,false` |
| caCertificatePath | N | Output | The path to the CA cert | `/path/to/ca-cert` |
## Binding support
This component supports **output binding** with the following operations:
- `topology`
- `deploy-workflow`
- `create-instance`
- `cancel-instance`
- `set-variables`
- `resolve-incident`
- `publish-message`
- `activate-jobs`
- `complete-job`
- `fail-job`
- `update-job-retries`
- `throw-error`
### Output binding
Zeebe uses gRPC under the hood for the Zeebe client we use in this binding. Please consult the gRPC API reference for more information:
https://stage.docs.zeebe.io/reference/grpc.html
#### topology
The `topology` operation obtains the current topology of the cluster the gateway is part of.
To perform a `topology` operation, invoke the Zeebe command binding with a `POST` method and the following JSON body:
```json
{
"data": {},
"operation": "topology"
}
```
##### Response
The binding returns a JSON with the following response:
```json
{
"brokers": [
{
"nodeId": null,
"host": "172.18.0.5",
"port": 26501,
"partitions": [
{
"partitionId": 1,
"role": null,
"health": null
}
],
"version": "0.26.0"
}
],
"clusterSize": 1,
"partitionsCount": 1,
"replicationFactor": 1,
"gatewayVersion": "0.26.0"
}
```
The response values are:
- `brokers` - list of brokers part of this cluster
- `nodeId` - unique (within a cluster) node ID for the broker
- `host` - hostname of the broker
- `port` - port for the broker
- `port` - port for the broker
- `partitions` - list of partitions managed or replicated on this broker
- `partitionId` - the unique ID of this partition
- `role` - the role of the broker for this partition
- `health` - the health of this partition
- `version` - broker version
- `clusterSize` - how many nodes are in the cluster
- `partitionsCount` - how many partitions are spread across the cluster
- `replicationFactor` - configured replication factor for this cluster
- `gatewayVersion` - gateway version
#### deploy-workflow
The `deploy-workflow` operation deploys a single workflow to Zeebe.
To perform a `deploy-workflow` operation, invoke the Zeebe command binding with a `POST` method and the following JSON body:
```json
{
"data": "YOUR_FILE_CONTENT",
"metadata": {
"fileName": "products-process.bpmn",
"fileType": "bpmn"
},
"operation": "deploy-workflow"
}
```
The metadata parameters are:
- `fileName` - the name of the workflow file
- `fileType` - (optional) the type of the file 'bpmn' or 'file'. If no type was given, the default will be recognized based on the file extension
'bpmn' for file extension .bpmn, for all other files it will be set to 'file'
##### Response
The binding returns a JSON with the following response:
```json
{
"key": 2251799813687320,
"workflows": [
{
"bpmnProcessId": "products-process",
"version": 3,
"workflowKey": 2251799813685895,
"resourceName": "products-process.bpmn"
}
]
}
```
The response values are:
- `key` - the unique key identifying the deployment
- `workflows` - a list of deployed workflows
- `bpmnProcessId` - the bpmn process ID, as parsed during deployment; together with the version forms a unique identifier for a specific
workflow definition
- `version` - the assigned process version
- `workflowKey` - the assigned key, which acts as a unique identifier for this workflow
- `resourceName` - the resource name from which this workflow was parsed
#### create-instance
The `create-instance` operation creates and starts an instance of the specified workflow. The workflow definition to use to create the instance can be
specified either using its unique key (as returned by the `deploy-workflow` operation), or using the BPMN process ID and a version.
Note that only workflows with none start events can be started through this command.
##### By BPMN process ID
To perform a `create-instance` operation, invoke the Zeebe command binding with a `POST` method and the following JSON body:
```json
{
"data": {
"bpmnProcessId": "products-process",
"variables": {
"productId": "some-product-id",
"productName": "some-product-name",
"productKey": "some-product-key"
}
},
"operation": "create-instance"
}
```
The data parameters are:
- `bpmnProcessId` - the BPMN process ID of the workflow definition to instantiate
- `version` - (optional, default: latest version) the version of the process to instantiate
- `variables` - (optional) JSON document that will instantiate the variables for the root variable scope of the
workflow instance; it must be a JSON object, as variables will be mapped in a
key-value fashion. e.g. { "a": 1, "b": 2 } will create two variables, named "a" and
"b" respectively, with their associated values. [{ "a": 1, "b": 2 }] would not be a
valid argument, as the root of the JSON document is an array and not an object
##### By workflow key
To perform a `create-instance` operation, invoke the Zeebe command binding with a `POST` method and the following JSON body:
```json
{
"data": {
"workflowKey": 2251799813685895,
"variables": {
"productId": "some-product-id",
"productName": "some-product-name",
"productKey": "some-product-key"
}
},
"operation": "create-instance"
}
```
The data parameters are:
- `workflowKey` - the unique key identifying the workflow definition to instantiate
- `variables` - (optional) JSON document that will instantiate the variables for the root variable scope of the
workflow instance; it must be a JSON object, as variables will be mapped in a
key-value fashion. e.g. { "a": 1, "b": 2 } will create two variables, named "a" and
"b" respectively, with their associated values. [{ "a": 1, "b": 2 }] would not be a
valid argument, as the root of the JSON document is an array and not an object
##### Response
The binding returns a JSON with the following response:
```json
{
"workflowKey": 2251799813685895,
"bpmnProcessId": "products-process",
"version": 3,
"workflowInstanceKey": 2251799813687851
}
```
The response values are:
- `workflowKey` - the key of the workflow definition which was used to create the workflow instance
- `bpmnProcessId` - the BPMN process ID of the workflow definition which was used to create the workflow instance
- `version` - the version of the workflow definition which was used to create the workflow instance
- `workflowInstanceKey` - the unique identifier of the created workflow instance
#### cancel-instance
The `cancel-instance` operation cancels a running workflow instance.
To perform a `cancel-instance` operation, invoke the Zeebe command binding with a `POST` method and the following JSON body:
```json
{
"data": {
"workflowInstanceKey": 2251799813687851
},
"metadata": {},
"operation": "cancel-instance"
}
```
The data parameters are:
- `workflowInstanceKey` - the workflow instance key
##### Response
The binding does not return a response body.
#### set-variables
The `set-variables` operation creates or updates variables for an element instance (e.g. workflow instance, flow element instance).
To perform a `set-variables` operation, invoke the Zeebe command binding with a `POST` method and the following JSON body:
```json
{
"data": {
"elementInstanceKey": 2251799813687880,
"variables": {
"productId": "some-product-id",
"productName": "some-product-name",
"productKey": "some-product-key"
}
},
"metadata": {},
"operation": "set-variables"
}
```
The data parameters are:
- `elementInstanceKey` - the unique identifier of a particular element; can be the workflow instance key (as
obtained during instance creation), or a given element, such as a service task (see elementInstanceKey on the job message)
- `local` - (optional, default: `false`) if true, the variables will be merged strictly into the local scope (as indicated by
elementInstanceKey); this means the variables is not propagated to upper scopes.
for example, let's say we have two scopes, '1' and '2', with each having effective variables as:
1 => `{ "foo" : 2 }`, and 2 => `{ "bar" : 1 }`. if we send an update request with
elementInstanceKey = 2, variables `{ "foo" : 5 }`, and local is true, then scope 1 will
be unchanged, and scope 2 will now be `{ "bar" : 1, "foo" 5 }`. if local was false, however,
then scope 1 would be `{ "foo": 5 }`, and scope 2 would be `{ "bar" : 1 }`
- `variables` - a JSON serialized document describing variables as key value pairs; the root of the document must be an object
##### Response
The binding returns a JSON with the following response:
```json
{
"key": 2251799813687896
}
```
The response values are:
- `key` - the unique key of the set variables command
#### resolve-incident
The `resolve-incident` operation resolves an incident.
To perform a `resolve-incident` operation, invoke the Zeebe command binding with a `POST` method and the following JSON body:
```json
{
"data": {
"incidentKey": 2251799813686123
},
"metadata": {},
"operation": "resolve-incident"
}
```
The data parameters are:
- `incidentKey` - the unique ID of the incident to resolve
##### Response
The binding does not return a response body.
#### publish-message
The `publish-message` operation publishes a single message. Messages are published to specific partitions computed from their correlation keys.
To perform a `publish-message` operation, invoke the Zeebe command binding with a `POST` method and the following JSON body:
```json
{
"messageName": "",
"correlationKey": "2",
"timeToLive": "1m",
"variables": {
"productId": "some-product-id",
"productName": "some-product-name",
"productKey": "some-product-key"
}
}
```
The data parameters are:
- `messageName` - the name of the message
- `correlationKey` - (optional) the correlation key of the message
- `timeToLive` - (optional) how long the message should be buffered on the broker
- `messageId` - (optional) the unique ID of the message; can be omitted. only useful to ensure only one message with the given ID will ever
be published (during its lifetime)
- `variables` - (optional) the message variables as a JSON document; to be valid, the root of the document must be an object, e.g. { "a": "foo" }.
[ "foo" ] would not be valid
##### Response
The binding returns a JSON with the following response:
```json
{
"key": 2251799813688225
}
```
The response values are:
- `key` - the unique ID of the message that was published
#### activate-jobs
The `activate-jobs` operation iterates through all known partitions round-robin and activates up to the requested maximum and streams them back to
the client as they are activated.
To perform a `activate-jobs` operation, invoke the Zeebe command binding with a `POST` method and the following JSON body:
```json
{
"data": {
"jobType": "fetch-products",
"maxJobsToActivate": 5,
"timeout": "5m",
"workerName": "products-worker",
"fetchVariables": [
"productId",
"productName",
"productKey"
]
},
"metadata": {},
"operation": "activate-jobs"
}
```
The data parameters are:
- `jobType` - the job type, as defined in the BPMN process (e.g. `<zeebe:taskDefinition type="fetch-products" />`)
- `maxJobsToActivate` - the maximum jobs to activate by this request
- `timeout` - (optional, default: 5 minutes) a job returned after this call will not be activated by another call until the timeout has been reached
- `workerName` - (optional, default: `default`) the name of the worker activating the jobs, mostly used for logging purposes
- `fetchVariables` - (optional) a list of variables to fetch as the job variables; if empty, all visible variables at the time of activation for the
scope of the job will be returned
##### Response
The binding returns a JSON with the following response:
```json
[
{
}
]
```
The response values are:
- `key` - the key, a unique identifier for the job
- `type` - the type of the job (should match what was requested)
- `workflowInstanceKey` - the job's workflow instance key
- `bpmnProcessId` - the bpmn process ID of the job workflow definition
- `workflowDefinitionVersion` - the version of the job workflow definition
- `workflowKey` - the key of the job workflow definition
- `elementId` - the associated task element ID
- `elementInstanceKey` - the unique key identifying the associated task, unique within the scope of the workflow instance
- `customHeaders` - a set of custom headers defined during modelling; returned as a serialized JSON document
- `worker` - the name of the worker which activated this job
- `retries` - the amount of retries left to this job (should always be positive)
- `deadline` - when the job can be activated again, sent as a UNIX epoch timestamp
- `variables` - JSON document, computed at activation time, consisting of all visible variables to the task scope
#### complete-job
The `complete-job` operation completes a job with the given payload, which allows completing the associated service task.
To perform a `complete-job` operation, invoke the Zeebe command binding with a `POST` method and the following JSON body:
```json
{
"data": {
"jobKey": 2251799813686172,
"variables": {
"productId": "some-product-id",
"productName": "some-product-name",
"productKey": "some-product-key"
}
},
"metadata": {},
"operation": "complete-job"
}
```
The data parameters are:
- `jobKey` - the unique job identifier, as obtained from the activate jobs response
- `variables` - (optional) a JSON document representing the variables in the current task scope
##### Response
The binding does not return a response body.
#### fail-job
The `fail-job` operation marks the job as failed; if the retries argument is positive, then the job will be immediately activatable again, and a
worker could try again to process it. If it is zero or negative however, an incident will be raised, tagged with the given errorMessage, and the
job will not be activatable until the incident is resolved.
To perform a `fail-job` operation, invoke the Zeebe command binding with a `POST` method and the following JSON body:
```json
{
"data": {
"jobKey": 2251799813685739,
"retries": 5,
"errorMessage": "some error occured"
},
"metadata": {},
"operation": "fail-job"
}
```
The data parameters are:
- `jobKey` - the unique job identifier, as obtained when activating the job
- `retries` - the amount of retries the job should have left
- `errorMessage ` - (optional) an message describing why the job failed this is particularly useful if a job runs out of retries and an
incident is raised, as it this message can help explain why an incident was raised
##### Response
The binding does not return a response body.
#### update-job-retries
The `update-job-retries` operation updates the number of retries a job has left. This is mostly useful for jobs that have run out of retries, should the
underlying problem be solved.
To perform a `update-job-retries` operation, invoke the Zeebe command binding with a `POST` method and the following JSON body:
```json
{
"data": {
"jobKey": 2251799813686172,
"retries": 10
},
"metadata": {},
"operation": "update-job-retries"
}
```
The data parameters are:
- `jobKey` - the unique job identifier, as obtained through the activate-jobs operation
- `retries` - the new amount of retries for the job; must be positive
##### Response
The binding does not return a response body.
#### throw-error
The `throw-error` operation throw an error to indicate that a business error is occurred while processing the job. The error is identified
by an error code and is handled by an error catch event in the workflow with the same error code.
To perform a `throw-error` operation, invoke the Zeebe command binding with a `POST` method and the following JSON body:
```json
{
"data": {
"jobKey": 2251799813686172,
"errorCode": "product-fetch-error",
"errorMessage": "The product could not be fetched"
},
"metadata": {},
"operation": "throw-error"
}
```
The data parameters are:
- `jobKey` - the unique job identifier, as obtained when activating the job
- `errorCode` - the error code that will be matched with an error catch event
- `errorMessage` - (optional) an error message that provides additional context
##### Response
The binding does not return a response body.
## Related links
- [Basic schema for a Dapr component]({{< ref component-schema >}})
- [Bindings building block]({{< ref bindings >}})
- [How-To: Trigger application with input binding]({{< ref howto-triggers.md >}})
- [How-To: Use bindings to interface with external resources]({{< ref howto-bindings.md >}})
- [Bindings API reference]({{< ref bindings_api.md >}})

101
daprdocs/content/en/reference/components-reference/supported-bindings/zeebe-jobworker.md Normal file
View File

@ -0,0 +1,101 @@
---
type: docs
title: "Zeebe JobWorker binding spec"
linkTitle: "Zeebe JobWorker"
description: "Detailed documentation on the Zeebe JobWorker binding component"
aliases:
- "/operations/components/setup-bindings/supported-bindings/zeebe-jobworker/"
---
## Component format
To setup Zeebe JobWorker binding create a component of type `bindings.zeebe.jobworker`. See [this guide]({{< ref "howto-bindings.md#1-create-a-binding" >}}) on how to create and apply a binding configuration.
See [this](https://docs.camunda.io/docs/product-manuals/concepts/job-workers) for Zeebe JobWorker documentation.
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <NAME>
namespace: <NAMESPACE>
spec:
type: bindings.zeebe.jobworker
version: v1
metadata:
- name: gatewayAddr
value: <host>:<port>
- name: gatewayKeepAlive
value: 45s
- name: usePlainTextConnection
value: true
- name: caCertificatePath
value: /path/to/ca-cert
- name: workerName
value: products-worker
- name: workerTimeout
value: 5m
- name: requestTimeout
value: 15s
- name: jobType
value: fetch-products
- name: maxJobsActive
value: 32
- name: concurrency
value: 4
- name: pollInterval
value: 100ms
- name: pollThreshold
value: 0.3
- name: fetchVariables
value: productId, productName, productKey
```
## Spec metadata fields
| Field | Required | Binding support | Details | Example |
|-------------------------|:--------:|------------|-----|---------|
| gatewayAddr | Y | Input | Zeebe gateway address | `localhost:26500` |
| gatewayKeepAlive | N | Input | Sets how often keep alive messages should be sent to the gateway. Defaults to 45 seconds | `45s` |
| usePlainTextConnection | N | Input | Whether to use a plain text connection or not | `true,false` |
| caCertificatePath | N | Input | The path to the CA cert | `/path/to/ca-cert` |
| workerName | N | Input | The name of the worker activating the jobs, mostly used for logging purposes | `products-worker` |
| workerTimeout | N | Input | A job returned after this call will not be activated by another call until the timeout has been reached; defaults to 5 minutes | `5m` |
| requestTimeout | N | Input | The request will be completed when at least one job is activated or after the requestTimeout. If the requestTimeout = 0, a default timeout is used. If the requestTimeout < 0, long polling is disabled and the request is completed immediately, even when no job is activated. Defaults to 10 seconds | `30s` |
| jobType | Y | Input | the job type, as defined in the BPMN process (e.g. `<zeebe:taskDefinition type="fetch-products" />`) | `fetch-products` |
| maxJobsActive | N | Input | Set the maximum number of jobs which will be activated for this worker at the same time. Defaults to 32 | `32` |
| concurrency | N | Input | The maximum number of concurrent spawned goroutines to complete jobs. Defaults to 4 | `4` |
| pollInterval | N | Input | Set the maximal interval between polling for new jobs. Defaults to 100 milliseconds | `100ms` |
| pollThreshold | N | Input | Set the threshold of buffered activated jobs before polling for new jobs, i.e. threshold * maxJobsActive. Defaults to 0.3 | `0.3` |
| fetchVariables | N | Input | A list of variables to fetch as the job variables; if empty, all visible variables at the time of activation for the scope of the job will be returned | `productId, productName, productKey` |
## Binding support
This component supports **input** binding interfaces.
### Input binding
The Zeebe workflow engine handles the workflow state as also workflow variables which can be passed
on workflow instantiation or which can be updated or created during workflow execution. These variables
can be passed to a registered job worker by defining the variable names as comma-separated list in
the `fetchVariables` metadata field. The workflow engine will then pass these variables with its current
values to the job worker implementation.
If the binding will register three variables `productId`, `productName` and `productKey` then the service will
be called with the following JSON:
```json
{
"productId": "some-product-id",
"productName": "some-product-name",
"productKey": "some-product-key"
}
```
## Related links
- [Basic schema for a Dapr component]({{< ref component-schema >}})
- [Bindings building block]({{< ref bindings >}})
- [How-To: Trigger application with input binding]({{< ref howto-triggers.md >}})
- [How-To: Use bindings to interface with external resources]({{< ref howto-bindings.md >}})
- [Bindings API reference]({{< ref bindings_api.md >}})