Skip to content

Commit

Permalink
feature(inbound-template): refactor the inbound template
Browse files Browse the repository at this point in the history
  • Loading branch information
@mathias-vandaele
mathias-vandaele committed Dec 27, 2024
1 parent 764b51a commit f48b13c
Show file tree
Hide file tree
Showing 12 changed files with 1,127 additions and 394 deletions.
138 changes: 108 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,31 @@
> A template for new C8 inbound Connectors.
> A Connector template for new C8 inbound connector
>
> To use this template update the following resources to match the name of your connector:
>
> * [README](./README.md) (title, description)
> * [Element Template](./element-templates/inbound-template-connector.json)
> * [Element Template](./element-templates/template-connector-message-start-event.json)
> * [POM](./pom.xml) (artifact name, id, description)
> * [Connector Executable](./src/main/java/io/camunda/connector/inbound/MyConnectorExecutable.java) (rename, implement, update `InboundConnector` annotation)
> * [Service Provider Interface (SPI)](./src/main/resources/META-INF/services/io.camunda.connector.api.inbound.InboundConnectorExecutable) (rename)
> * [Connector Executable](src/main/java/io/camunda/connector/inbound/MyConnectorExecutable.java) (rename, implement,
update
`InboundConnector` annotation)
> * [Service Provider Interface (SPI)](./src/main/resources/META-INF/services/io.camunda.connector.api.inbound.InboundConnectorExecutable) (
rename)
>
> ...and delete this hint.
>
> Read more about [creating Connectors](https://docs.camunda.io/docs/components/connectors/custom-built-connectors/connector-sdk/#creating-a-custom-connector)
>
>
> Read more
>
about [creating Connectors](https://docs.camunda.io/docs/components/connectors/custom-built-connectors/connector-sdk/#creating-a-custom-connector)
>
> Check out the [Connectors SDK](https://github.com/camunda/connector-sdk)

# Inbound Connector Template
# Connector Template

Camunda Inbound Connector Template

Emulates a simple inbound connector function that start process X times per minutes(to be specified in the element
template)

## Build

You can package the Connector by running the following command:
Expand All @@ -30,39 +37,39 @@ mvn clean package
This will create the following artifacts:

- A thin JAR without dependencies.
- An uber JAR containing all dependencies, potentially shaded to avoid classpath conflicts. This will not include the SDK artifacts since those are in scope `provided` and will be brought along by the respective Connector Runtime executing the Connector.
- A fat JAR containing all dependencies, potentially shaded to avoid classpath conflicts. This will not include the SDK
artifacts since those are in scope `provided` and will be brought along by the respective Connector Runtime executing
the Connector.
- All element templates

### Shading dependencies

You can use the `maven-shade-plugin` defined in the [Maven configuration](./pom.xml) to relocate common dependencies
that are used in other Connectors and the [Connector Runtime](https://github.com/camunda-community-hub/spring-zeebe/tree/master/connector-runtime#building-connector-runtime-bundles).
This helps to avoid classpath conflicts when the Connector is executed.
that are used in other Connectors and
the [Connector Runtime](https://github.com/camunda-community-hub/spring-zeebe/tree/master/connector-runtime#building-connector-runtime-bundles).
This helps to avoid classpath conflicts when the Connector is executed.

Use the `relocations` configuration in the Maven Shade plugin to define the dependencies that should be shaded.
The [Maven Shade documentation](https://maven.apache.org/plugins/maven-shade-plugin/examples/class-relocation.html)
The [Maven Shade documentation](https://maven.apache.org/plugins/maven-shade-plugin/examples/class-relocation.html)
provides more details on relocations.

## API

### Connector Properties

This Connector can be configured with the following properties:
### Input

| Name | Description | Example | Can be a secret |
|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|-----------------|
| sender | Value of the `sender` field of the messages generated by [`MockSubscription`](https://github.com/camunda/connector-template-inbound/blob/main/src/main/java/io/camunda/connector/inbound/subscription/MockSubscription.java) | `Alice` | Yes |
| messagesPerMinute | How many messages per minute should MockSubscription produce (1-10) | `3` | No |
| Name | Description | Example |
|--------------------|--------------------------------------|---------|
| Sender | Message sender | `alice` |
| Message per minute | Number of message created per minute | 6 |

### Output

This Connector produces the following output:

```json
{
"event": {
"sender": ".....",
"message": ".....",
"code": 999
"event":{
"sender":"test",
"code":4,
"message":"56b020ef-e51a-4a4b-b9a4-8df521a2e78f"
}
}
```
Expand All @@ -77,11 +84,82 @@ mvn clean verify

### Test with local runtime

Use the [Camunda Connector Runtime](https://github.com/camunda-community-hub/spring-zeebe/tree/master/connector-runtime#building-connector-runtime-bundles) to run your function as a local Java application.
To ensure the seamless functionality of your custom Camunda connector, please follow the steps below:

#### Prerequisites:

1. Camunda Modeler, which is available in two variants:
- [Desktop Modeler](https://camunda.com/download/modeler/) for a local installation.
- [Web Modeler](https://camunda.com/download/modeler/) for an online experience.

2. [Docker](https://www.docker.com/products/docker-desktop), which is required to run the Camunda platform.

#### Setting Up the Environment:

1. Clone the Camunda Platform repository from GitHub:

```shell
git clone https://github.com/camunda/camunda-platform.git
```

Navigate to the cloned directory and open docker-compose-core.yaml with your preferred text editor.

Locate the connector image section and comment it out using the # symbol, as you will be executing your connector
locally.

Initiate the Camunda suite with the following Docker command:

In your IDE you can also simply navigate to the `LocalContainerRuntime` class in test scope and run it via your IDE.
If necessary, you can adjust `application.properties` in test scope.
```shell
docker compose -f docker-compose-core.yaml up
```

### Configuring Camunda Modeler

1. Install the Camunda Modeler if not already done.
2. Add the `element-templates/template-connector-message-start-event.json` to your Modeler configuration as per
the [Element Templates documentation](https://docs.camunda.io/docs/components/modeler/desktop-modeler/element-templates/configuring-templates/).

### Launching Your Connector

1. Run `io.camunda.example.LocalConnectorRuntime` to start your connector.
2. Create and initiate a process that utilizes your newly created connector within the Camunda
Modeler. ![Connector in Camunda Modeler](img/img.png)
3. Verify that the process is running smoothly by accessing Camunda Operate at [localhost:8081](http://localhost:8081).

Follow these instructions to test and use your custom Camunda connector effectively.

### Test with SaaS

#### Prerequisites:

None required.

#### Setting Up the Environment:

1. Navigate to Camunda [SaaS](https://console.camunda.io).
2. Create a cluster using the latest version available.
3. Select your cluster, then go to the `API` section and click `Create new Client`.
4. Ensure the `zeebe` checkbox is selected, then click `Create`.
5. Copy the configuration details displayed under the `Spring Boot` tab.
6. Paste the copied configuration into your `application.properties` file within your project.

### Launching Your Connector

1. Start your connector by executing `io.camunda.connector.inbound.LocalConnectorRuntime` in your development environment.
2. Access the Web Modeler and create a new project.
3. Click on `Create new`, then select `Upload files`. Upload the connector template from the repository you have.
4. In the same folder, create a new BPMN diagram.
5. Design and start a process that incorporates your new connector.

By adhering to these steps, you can validate the integration of your custom Camunda connector with the SaaS environment.

## Element Template

The element templates can be found in the [element-templates/inbound-template-connector.json](element-templates/inbound-template-connector.json) file.
The element template for this sample connector is generated automatically based on the connector
input class using
the [Element Template Generator](https://github.com/camunda/connectors/tree/main/element-template-generator/core).

The generation is embedded in the Maven build and can be triggered by running `mvn clean package`.

The generated element template can be found
in [element-templates/template-connector.json](./element-templates/template-connector-message-start-event.json).
191 changes: 191 additions & 0 deletions dependency-reduced-pom.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>io.camunda.connector</groupId>
<artifactId>connector-template-inbound</artifactId>
<name>connector-template-inbound</name>
<version>0.1.0-SNAPSHOT</version>
<description>Camunda Inbound Connector Template</description>
<build>
<plugins>
<plugin>
<artifactId>maven-shade-plugin</artifactId>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>io.camunda.connector</groupId>
<artifactId>element-template-generator-maven-plugin</artifactId>
<version>${version.connectors}</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>generate-templates</goal>
</goals>
</execution>
</executions>
<configuration>
<connectors>
<connector>
<connectorClass>io.camunda.connector.inbound.MyConnectorExecutable</connectorClass>
<files>
<file>
<templateId>io.camunda.connectors.inbound.EmailMessageStartEvent.v1</templateId>
<templateFileName>email-inbound-connector-start-event.json</templateFileName>
</file>
<file>
<templateId>io.camunda.connectors.inbound.EmailIntermediate.v1</templateId>
<templateFileName>email-inbound-connector-intermediate.json</templateFileName>
</file>
<file>
<templateId>io.camunda.connectors.inbound.EmailBoundary.v1</templateId>
<templateFileName>email-inbound-connector-boundary.json</templateFileName>
</file>
</files>
</connector>
</connectors>
</configuration>
</plugin>
</plugins>
</build>
<repositories>
<repository>
<releases />
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>connectors</id>
<name>Connectors Repository</name>
<url>https://artifacts.camunda.com/artifactory/connectors/</url>
</repository>
<repository>
<releases>
<enabled>false</enabled>
</releases>
<snapshots />
<id>connectors-snapshots</id>
<name>Connectors Snapshot Repository</name>
<url>https://artifacts.camunda.com/artifactory/connectors-snapshots/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>io.camunda.connector</groupId>
<artifactId>connector-core</artifactId>
<version>8.7.0-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>io.camunda.connector</groupId>
<artifactId>connector-test</artifactId>
<version>8.7.0-SNAPSHOT</version>
<scope>test</scope>
<exclusions>
<exclusion>
<artifactId>connector-runtime-core</artifactId>
<groupId>io.camunda.connector</groupId>
</exclusion>
<exclusion>
<artifactId>connector-validation</artifactId>
<groupId>io.camunda.connector</groupId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>5.10.2</version>
<scope>test</scope>
<exclusions>
<exclusion>
<artifactId>junit-jupiter-api</artifactId>
<groupId>org.junit.jupiter</groupId>
</exclusion>
<exclusion>
<artifactId>junit-jupiter-params</artifactId>
<groupId>org.junit.jupiter</groupId>
</exclusion>
<exclusion>
<artifactId>junit-jupiter-engine</artifactId>
<groupId>org.junit.jupiter</groupId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.mockito</groupId>
<artifactId>mockito-junit-jupiter</artifactId>
<version>5.11.0</version>
<scope>test</scope>
<exclusions>
<exclusion>
<artifactId>mockito-core</artifactId>
<groupId>org.mockito</groupId>
</exclusion>
<exclusion>
<artifactId>junit-jupiter-api</artifactId>
<groupId>org.junit.jupiter</groupId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.assertj</groupId>
<artifactId>assertj-core</artifactId>
<version>3.25.3</version>
<scope>test</scope>
<exclusions>
<exclusion>
<artifactId>byte-buddy</artifactId>
<groupId>net.bytebuddy</groupId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.camunda.connector</groupId>
<artifactId>spring-boot-starter-camunda-connectors</artifactId>
<version>8.7.0-SNAPSHOT</version>
<scope>test</scope>
<exclusions>
<exclusion>
<artifactId>connector-runtime-spring</artifactId>
<groupId>io.camunda.connector</groupId>
</exclusion>
<exclusion>
<artifactId>spring-boot-starter-camunda-sdk</artifactId>
<groupId>io.camunda</groupId>
</exclusion>
<exclusion>
<artifactId>spring-core</artifactId>
<groupId>org.springframework</groupId>
</exclusion>
<exclusion>
<artifactId>spring-boot-starter-web</artifactId>
<groupId>org.springframework.boot</groupId>
</exclusion>
<exclusion>
<artifactId>spring-boot-starter-actuator</artifactId>
<groupId>org.springframework.boot</groupId>
</exclusion>
<exclusion>
<artifactId>connector-validation</artifactId>
<groupId>io.camunda.connector</groupId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
<properties>
<maven.compiler.release>21</maven.compiler.release>
<version.assertj>3.25.3</version.assertj>
<version.mockito>5.11.0</version.mockito>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<version.junit-jupiter>5.10.2</version.junit-jupiter>
<version.connectors>8.7.0-SNAPSHOT</version.connectors>
</properties>
</project>
Loading

0 comments on commit f48b13c

Please sign in to comment.