Introduction
A Connector is a reusable building block that performs the integration with an external system and works out of the box.
It is represented as a task in a BPMN process, which can be configured with parameters specific for the external system. As such, it can remove the need to write custom programming code for integration.
A Connector consists of two parts:
- The programming code in Java to connect to the external system (for example, see the Connector function for outbound Connectors.)
- The user interface to be used during modeling, which is provided using Connector templates.
Connectors are operated as part of the Connector runtime, which is provided for SaaS and Self-Managed environments.
Camunda Platform 8 SaaS
When using Camunda Platform 8 SaaS, the Connector runtime is operated by Camunda and offered in the scope of the product. In this environment, you can use the out-of-the-box Connectors provided by Camunda.
Camunda Platform 8 Self-Managed
In a Self-Managed environment, you manage the execution environment for Connectors yourself. Using our Connector runtime environments, you can consume any set of Connectors, including the out-of-the-box Connectors and custom Connectors developed using the Connector SDK and Connector templates.
You can find a list of Connectors developed by Camunda, Partners, and the community in our Camunda Connectors Awesome List.
The Self-Managed installation guide details how to install the pre-packaged Connector runtime environment. The guide also describes how to integrate the out-of-the-box Connectors provided by Camunda, including their Connector templates for modeling.
Some out-of-the-box Connectors are licensed under the Camunda Platform Self-Managed Free Edition license.
Connector types
Outbound Connectors
Use outbound Connectors if something needs to happen in the third-party system if a process reaches a service task. For example, calling a REST endpoint or publishing some message to Slack.
Inbound Connectors
Use inbound Connectors if something needs to happen within the workflow engine because of an external event in the third-party system. For example, because a Slack message was published, or a REST endpoint is called.
There are three types of inbound Connectors:
- Webhook: An HTTP endpoint is made available to the outside, which when called, can start a process instance, for example.
- Subscription: A subscription is opened on the third-party system, like messaging or Apache Kafka, and new entries are then received and correlated to a waiting process instance in Camunda, for example.
- Polling: Some external API needs to be regularly queried for new entries, such as a drop folder on Google Drive or FTP.
Currently, only webhooks are supported. We are working to support the other types as well.
Out-of-the-box vs. custom-built Connectors
There are out-of-the-box Connectors provided by Camunda, which are available with SaaS and Self-Managed.
You can also develop custom Connectors using the Connector SDK.
Outbound Connector vs. job worker
Integrating with external systems can be done with a Connector or a job worker.
You define the domain-specific UI for modeling a Connector through a Connector template. This Connector template is, in fact, an element template. Therefore, you can also build a Connector-like system using element templates and job workers.
If they both share the same core functionality, how do they differ, and when should you choose what? Connectors and job workers serve different purposes when it comes to aspects like delivery, reusability, focus, and context.
Delivery
A Connector is reusable code, written as an OutboundConnectorFunction using the Connector SDK.
It is not a standalone application, you cannot start it and have it work on Camunda Platform 8 jobs.
Instead, a Connector is delivered as a library and can be used in combination with other Connectors in a Connector runtime environment.
In contrast, a job worker is usually part of a Zeebe Client application that can be directly executed to work on jobs.
Reusability
A job worker usually runs as or inside a standalone Zeebe Client. Without effort, you cannot simply run this in Camunda Platform 8 SaaS or any other environment. As a Self-Managed user, you can run it standalone, but often not directly reuse the logic in your existing Zeebe Client that you might already have. You can manually extract the job handler from the given job worker, but you also have to ensure that it is still working as expected afterward.
In contrast, a Connector itself is environment-agnostic. There is a runtime environment for Camunda Platform 8 SaaS that can wrap and call this Connector. As the Connector developer, you don't have to worry about this as the runtime takes care of it if you developed the Connector using the Connector SDK.
You can also run the exact same Connector (without any modification) in Camunda Platform 8 Self-Managed; either as a standalone job worker, as additional job handler in your existing Zeebe Client application, or together with other Connectors in one Zeebe Client application. This all comes with the Connector SDK, and there is no additional code necessary to get started. However, if you need a custom environment, the Connector SDK provides a guide and default helpers to do that.
Focus
A job worker is often a complete Zeebe Client application, dealing with environment tasks like handling variables in and out. The core logic of calling a defined URL is only part of the application. Plus, it handles Camunda Platform 8-specific APIs like the job worker API to handle variables, complete executions, and throw errors.
A Connector only consists of core business functionality. No environment tasks, no Camunda Platform 8 job worker-related code. You can run this from Camunda Platform 7 as well, if you have a runtime that takes care of this. The Connector only needs input variables and access to secrets so they can be used in defined input attributes.
Context
Every job worker implementation defines on its own how to handle input data, validating and transforming it. There is no unified way of using secrets in a job worker implementation either, e.g. to replace placeholders in attributes with sensitive information only at runtime. Plus, there is no unified modeling experience for job workers. There can be an element template for the worker, but that template might look completely different for every job worker.
In contrast, Connectors bring all the above out of the box. The environment brings along secret management baked-in, being flexible in how you provide those secrets. Element templates, called Connector templates, are a vital part of a Connector. There are standardized best practices for developing those. Having used one Connector template will make it easy for you to use the next one just the same.
Which one should you choose?
It depends on your use case.
- You need access to low-level API in Camunda Platform 8 to perform a very specific task? You are better off with job workers.
- You want to write your worker logic in something else than Java? Job workers are your way to move forward.
- You want to create worker logic that is easily reusable in any environment? Write a Connector.
- You want to focus on your worker's logic and have no need for using low-level Camunda Platform 8 API? Write a Connector.
- You want to provide a standardized modeling experience alongside your runtime behavior? Write a Connector.