Integrate a built-in connector

Integrate a built-in connector to reduce the time it takes to automate and orchestrate business processes across systems.

About

With built-in connectors, you can automate complex business processes by inserting them into BPMN diagrams within your Camunda Hub projects and configuring them with the properties panel.

You can also orchestrate APIs, for example by working with a REST connector. Learn more about types of connectors.

Connectors technically consist of two parts:

• The business logic is implemented as a job worker
• The user interface during modeling is provided using an element template.

In this tutorial, you'll walk step-by-step through the implementation of a sample connector.

Prerequisites

Before you begin, ensure you have:

• A Camunda 8 account.
• A SendGrid account. You'll use SendGrid in the example connector. Once you've created your account, you will immediately be prompted to create a sender.
• A Camunda Hub workspace. This is typically provisioned by a center of excellence team.

Create a cluster

To deploy and run your process, create a cluster in Camunda 8.

1. In Camunda Hub, under Console > Clusters, click Create cluster.
2. Name your cluster.
3. Select a region and backup location.
4. Select a cluster type and tag.
5. Select a channel and generation. For the purpose of this guide, Camunda recommends using the Stable channel and the latest generation.
6. Click Create cluster.

It will take a few moments to create your cluster. Check the status on the Clusters page or by clicking into the cluster itself and looking at the Components section.

tip

If Create cluster is disabled, consider these explanations:

• Your organization is on a trial plan, and you have already created a cluster. In this case, you cannot create another cluster, because only one cluster is included in the trial plan.
• Your billing reservations do not allow any more clusters. You must increase the reservations to create more clusters. If you do not have the necessary rights, contact an admin or the owner of the organization.

If the cluster shows a status of at least Creating, you can start modeling. However, Zeebe must show a status of Healthy to properly deploy your model.

Import a diagram

1. Download the following files:
   • submit-expense.bpmn: A process for submitting expenses for approval.
   • upload-receipt.form: A form for uploading receipts.
   • approve-receipt.form: A form for approving receipts.
2. Log in to your Camunda 8 account.
3. In your Camunda Hub workspace, click New project, and name your project Expense process.
4. In your project, delete the default diagram, and click Create new > Upload files.
5. Upload submit-expense.bpmn, upload-receipt.form, and approve-receipt.form.

Open submit-expense to see the process you'll be working with throughout this tutorial:

note

To learn more about building your own BPMN diagram from scratch, visit our guide on automating a process using BPMN.

Add a connector

At the beginning of the process, a receipt is ready and uploaded for review. The next task is to notify the manager of the uploaded receipt.

To accomplish this, you'll use SendGrid to send an email:

1. With the submit-expense diagram open, make sure you're in Implement mode.
2. Click the Notify manager of receipt task.
3. Click Change element.
4. Search for SendGrid Outbound Connector. If you're using Self-Managed, you may need to download it from the connector marketplace.
5. Open the Details panel on the right side of the modeling interface.
6. Under Properties, configure the following sections:
   • Authentication: Full Access API Key
   • Sender: Name and email address. Make sure this email is verified by SendGrid.
   • Receiver: Name and email address
   • Compose email: Email contents

The connector is ready to use.

note

Camunda offers a variety of available connectors. For example, utilize cloud connectors to communicate with cloud-native applications and conform to REST, GraphQL, or SOAP protocols. Or, employ service connectors to integrate with technology enablers like RPA, AI or IOT services. Learn more about our available connectors to find out which may best suit your business needs.

Execute your process diagram

If you change a diagram and it is auto-saved, this has no effect on your cluster(s). When you deploy the diagram, it becomes available on the selected cluster, and new instances can start.

To execute your completed process with the diagram open:

1. Make sure you're in Implement mode.
2. Click Deploy and run.

You can now monitor your instances in Operate.

note

Variables are part of a process instance and represent the data of the instance. To learn more about these values, variable scope, and input/output mappings, visit our documentation on variables.

Observe your running process

After the user task Upload receipt is completed in Tasklist, an email is automatically sent to the address you specified in the SendGrid connector's properties panel.

In Operate, you will now see the process move forward to Review receipt.

Additional resources and next steps

• Use connectors in your BPMN process
• Available connectors
• Connectors & Integration Framework
• Camunda BPMN Tutorial
• Camunda Academy: How To Configure the SendGrid Connector