Camunda FailJob

Camunda FailJob
Certified
Report a Camunda job as failed

Tells Camunda the job could not be done, so the process instance stops waiting on this worker. Use it in a flow's errors block alongside the Trigger, which does not report failure by itself.

Leaving a job neither completed nor failed is not equivalent. Camunda re-offers a job whose lock expired without decrementing its retries, so the trigger activates it again, the flow fails again, and that repeats for as long as the process instance lives. Retries never reach zero, so no incident is ever raised and nothing surfaces in Operate.

retries defaults to 0, which raises an incident immediately and makes the failure visible. Pass {{ trigger.retries - 1 }} instead to spend the retries modelled on the BPMN task before the incident.

yaml
type: io.kestra.plugin.camunda.FailJob

Examples

Complete a Camunda job on success and report it as failed on error.

yaml
id: handle_camunda_job_with_errors
namespace: company.team

triggers:
  - id: on_camunda_job
    type: io.kestra.plugin.camunda.Trigger
    restAddress: "{{ secret('CAMUNDA_REST_ADDRESS') }}"
    clientId: "{{ secret('CAMUNDA_CLIENT_ID') }}"
    clientSecret: "{{ secret('CAMUNDA_CLIENT_SECRET') }}"
    authorizationServerUrl: "{{ secret('CAMUNDA_AUTH_SERVER_URL') }}"
    audience: "{{ secret('CAMUNDA_AUDIENCE') }}"
    audience: "{{ secret('CAMUNDA_AUDIENCE') }}"
    jobType: charge-payment
    timeout: PT5M

tasks:
  - id: charge
    type: io.kestra.plugin.core.http.Request
    uri: https://payments.example.com/charge

  - id: complete_job
    type: io.kestra.plugin.camunda.CompleteJob
    restAddress: "{{ secret('CAMUNDA_REST_ADDRESS') }}"
    clientId: "{{ secret('CAMUNDA_CLIENT_ID') }}"
    clientSecret: "{{ secret('CAMUNDA_CLIENT_SECRET') }}"
    authorizationServerUrl: "{{ secret('CAMUNDA_AUTH_SERVER_URL') }}"
    audience: "{{ secret('CAMUNDA_AUDIENCE') }}"
    audience: "{{ secret('CAMUNDA_AUDIENCE') }}"
    jobKey: "{{ trigger.jobKey }}"

errors:
  - id: fail_job
    type: io.kestra.plugin.camunda.FailJob
    restAddress: "{{ secret('CAMUNDA_REST_ADDRESS') }}"
    clientId: "{{ secret('CAMUNDA_CLIENT_ID') }}"
    clientSecret: "{{ secret('CAMUNDA_CLIENT_SECRET') }}"
    authorizationServerUrl: "{{ secret('CAMUNDA_AUTH_SERVER_URL') }}"
    audience: "{{ secret('CAMUNDA_AUDIENCE') }}"
    audience: "{{ secret('CAMUNDA_AUDIENCE') }}"
    jobKey: "{{ trigger.jobKey }}"
    errorMessage: "Kestra execution {{ execution.id }} failed"

Spend the retries modelled on the BPMN task before raising an incident, backing off between attempts.

yaml
id: retry_camunda_job
namespace: company.team

triggers:
  - id: on_camunda_job
    type: io.kestra.plugin.camunda.Trigger
    restAddress: http://localhost:8080
    jobType: charge-payment
    timeout: PT5M

tasks:
  - id: charge
    type: io.kestra.plugin.core.http.Request
    uri: https://payments.example.com/charge

  - id: complete_job
    type: io.kestra.plugin.camunda.CompleteJob
    restAddress: http://localhost:8080
    jobKey: "{{ trigger.jobKey }}"

errors:
  - id: fail_job
    type: io.kestra.plugin.camunda.FailJob
    restAddress: http://localhost:8080
    jobKey: "{{ trigger.jobKey }}"
    retries: "{{ trigger.retries - 1 }}"
    retryBackoff: PT30S
    errorMessage: "Charge failed, {{ trigger.retries - 1 }} attempts left"

Properties

jobKey *integerstring

Key of the job to fail

Available as {{ trigger.jobKey }} when the execution was started by the Camunda trigger.

audience string

OAuth2 audience

Required for OAuth2 against a self-managed cluster. The audience claim the identity provider must issue the token for, commonly zeebe-api. Derived from the cluster for Camunda SaaS, so leave it unset there.

authorizationServerUrl string

OAuth2 token endpoint

Required for OAuth2 against a self-managed cluster, for example http://localhost: 18080/auth/realms/camunda-platform/protocol/openid-connect/token.

clientId string

OAuth2 client ID

Set together with clientSecret and either authorizationServerUrl (self-managed) or clusterId (SaaS).

clientSecret string

OAuth2 client secret

Set together with clientId.

clusterId string

Camunda SaaS cluster ID

Switches the client to SaaS mode, where restAddress and grpcAddress are derived from the cluster ID and region.

errorMessage string

Message attached to the failure

Shown on the incident in Operate, so include whatever identifies the failed run.

grpcAddress string

gRPC gateway address of the Camunda cluster

For a self-managed cluster, for example http://localhost: 26500. Setting it without restAddress sends this task's commands over gRPC instead of REST.

password string

Password for Basic authentication

Must be set together with username.

region string

Camunda SaaS region

For example bru-2. Only used with clusterId.

restAddress string

REST API base URL of the Camunda cluster

For a self-managed cluster, the orchestration cluster address, for example http://localhost: 8080. Commands use the REST API unless only grpcAddress is set.

retries integerstring

Default0

Retries left after this failure

0, the default, raises an incident in Camunda straight away. Any higher value makes the job activatable again, so pass {{ trigger.retries - 1 }} to spend the retries modelled on the BPMN task first. Camunda raises the incident once this reaches zero.

retryBackoff string

How long Camunda waits before making the job activatable again

ISO-8601 duration. Only has an effect when retries is above zero.

tenantId string

Camunda tenant ID

Camunda's own multi-tenancy identifier, unrelated to the Kestra tenant the flow runs in. Applied to every command this task sends. Defaults to <default>, which is the only tenant on a cluster that does not have multi-tenancy enabled.

transport string

Possible Values

RESTGRPC

Which API to send commands over

Defaults to gRPC on Camunda SaaS, and on a self-managed cluster to the API implied by whichever address is set, falling back to REST when both or neither are. SaaS defaults to gRPC because a default free-tier cluster answers 404 Not Found on the REST base the client derives, while gRPC succeeds with the same credentials. Set REST to opt back in if your cluster serves it.

username string

Username for Basic authentication

Must be set together with password. Mutually exclusive with the OAuth2 properties.

variables object

Variables to merge into the process instance