camunda-community-hub · jonathanlukas · Feb 5, 2024
diff --git a/spring-connector/README.md b/spring-connector/README.md
@@ -0,0 +1,37 @@
+# Spring Connector
+
+This example shows how a connector can be implemented as Spring Bean and be picked up from the Spring bean context instead of the SPI.
+
+## Details
+
+The connector implementation itself uses an injected bean (which is not possible from SPI).
+
+To make the connector available via Spring bean context, it is configured in an `@AutoConfiguration` which is registered as `spring.factories`.
+
+From here, it will be picked up during auto-configuration and be processed by connectors-spring.
+
+## Runtimes
+
+There are 2 possible runtimes presented.
+
+### Injection to existing connector bundle
+
+After building the project with maven, run
+
+```shell
+docker-compose up -d
+```
+
+from the `./docker` directory.
+
+This will start the normal connectors-bundle and mount the connector jar to a location inside the container from where it will be added to the classpath.
+
+### Build your own runtime
+
+Inside `./example-connector-runtime`, you will find a simple Spring Boot project that allows to run the connector as simple dependency.
+
+Just run
+
+```shell
+mvn spring-boot:run
+```
diff --git a/spring-connector/bpmn/example-process.bpmn b/spring-connector/bpmn/example-process.bpmn
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:modeler="http://camunda.org/schema/modeler/1.0" id="Definitions_0d0gd4i" targetNamespace="http://bpmn.io/schema/bpmn" exporter="Camunda Modeler" exporterVersion="5.16.0" modeler:executionPlatform="Camunda Cloud" modeler:executionPlatformVersion="8.3.0">
+  <bpmn:process id="ExampleConnectorDemoProcess" name="Example Connector Demo" isExecutable="true">
+    <bpmn:sequenceFlow id="Flow_0znzi23" sourceRef="ExampleConnectorCallRequiredStartEvent" targetRef="CallExampleConnectorTask" />
+    <bpmn:endEvent id="ExampleConnectorCallDoneEndEvent" name="Example connector call done">
+      <bpmn:incoming>Flow_1ups00p</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="Flow_1ups00p" sourceRef="CallExampleConnectorTask" targetRef="ExampleConnectorCallDoneEndEvent" />
+    <bpmn:startEvent id="ExampleConnectorCallRequiredStartEvent" name="Example connector call required">
+      <bpmn:outgoing>Flow_0znzi23</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:serviceTask id="CallExampleConnectorTask" name="Call example connector">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="com.camunda.consulting:example" />
+      </bpmn:extensionElements>
+      <bpmn:incoming>Flow_0znzi23</bpmn:incoming>
+      <bpmn:outgoing>Flow_1ups00p</bpmn:outgoing>
+    </bpmn:serviceTask>
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_1">
+    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="ExampleConnectorDemoProcess">
+      <bpmndi:BPMNShape id="_BPMNShape_StartEvent_2" bpmnElement="ExampleConnectorCallRequiredStartEvent">
+        <dc:Bounds x="179" y="99" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="163" y="142" width="68" height="40" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Event_057bnq1_di" bpmnElement="ExampleConnectorCallDoneEndEvent">
+        <dc:Bounds x="432" y="99" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="416" y="142" width="68" height="40" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Activity_060pymq_di" bpmnElement="CallExampleConnectorTask">
+        <dc:Bounds x="270" y="77" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="Flow_0znzi23_di" bpmnElement="Flow_0znzi23">
+        <di:waypoint x="215" y="117" />
+        <di:waypoint x="270" y="117" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="Flow_1ups00p_di" bpmnElement="Flow_1ups00p">
+        <di:waypoint x="370" y="117" />
+        <di:waypoint x="432" y="117" />
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>
diff --git a/spring-connector/docker/docker-compose.yaml b/spring-connector/docker/docker-compose.yaml
@@ -0,0 +1,33 @@
+version: "2"
+
+networks:
+  zeebe_network:
+    driver: bridge
+
+services:
+  zeebe:
+    container_name: zeebe
+    image: camunda/zeebe:8.3.0
+    environment:
+    - ZEEBE_LOG_LEVEL=debug
+    ports:
+    - "26500:26500"
+    - "9600:9600"
+    networks:
+    - zeebe_network
+  connector-runtime:
+    container_name: connector-runtime
+    image: camunda/connectors-bundle:8.3.0
+    environment:
+    - ZEEBE_CLIENT_BROKER_GATEWAY-ADDRESS=zeebe:26500
+    - ZEEBE_CLIENT_SECURITY_PLAINTEXT=true
+    - CAMUNDA_CONNECTOR_POLLING_ENABLED=false
+    - CAMUNDA_CONNECTOR_WEBHOOK_ENABLED=false
+    - SPRING_MAIN_WEB-APPLICATION-TYPE=none
+    - OPERATE_CLIENT_ENABLED=false
+    depends_on:
+    - zeebe
+    networks:
+    - zeebe_network
+    volumes:
+    - ./../example-connector/target/example-connector-1.0-SNAPSHOT.jar:/opt/custom/spring-connector.jar
diff --git a/spring-connector/example-connector-runtime/pom.xml b/spring-connector/example-connector-runtime/pom.xml
@@ -0,0 +1,51 @@
+<?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/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>com.camunda.consulting</groupId>
+    <artifactId>spring-connector</artifactId>
+    <version>1.0-SNAPSHOT</version>
+  </parent>
+
+  <groupId>org.example</groupId>
+  <artifactId>example-connector-runtime</artifactId>
+
+  <properties>
+    <maven.compiler.source>17</maven.compiler.source>
+    <maven.compiler.target>17</maven.compiler.target>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+  <dependencies>
+    <dependency>
+      <groupId>io.camunda.connector</groupId>
+      <artifactId>spring-boot-starter-camunda-connectors</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.camunda.consulting</groupId>
+      <artifactId>example-connector</artifactId>
+      <version>1.0-SNAPSHOT</version>
+    </dependency>
+  </dependencies>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-maven-plugin</artifactId>
+        <configuration>
+          <layout>ZIP</layout>
+          <mainClass>com.camunda.consulting.connector.App</mainClass>
+        </configuration>
+        <executions>
+          <execution>
+            <goals>
+              <goal>repackage</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+
+</project>
diff --git a/...nnector/example-connector-runtime/src/main/java/com/camunda/consulting/connector/App.java b/...nnector/example-connector-runtime/src/main/java/com/camunda/consulting/connector/App.java
@@ -0,0 +1,11 @@
+package com.camunda.consulting.connector;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class App {
+  public static void main(String[] args) {
+    SpringApplication.run(App.class, args);
+  }
+}
diff --git a/spring-connector/example-connector-runtime/src/main/resources/application.yaml b/spring-connector/example-connector-runtime/src/main/resources/application.yaml
@@ -0,0 +1,15 @@
+zeebe:
+  client:
+    security:
+      plaintext: true
+    broker:
+      gateway-address: localhost:26500
+spring:
+  main:
+    web-application-type: none
+camunda:
+  connector:
+    webhook:
+      enabled: false
+    polling:
+      enabled: false
diff --git a/spring-connector/example-connector/pom.xml b/spring-connector/example-connector/pom.xml
@@ -0,0 +1,80 @@
+<?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/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>com.camunda.consulting</groupId>
+    <artifactId>spring-connector</artifactId>
+    <version>1.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>example-connector</artifactId>
+
+  <dependencies>
+    <dependency>
+      <groupId>io.camunda.connector</groupId>
+      <artifactId>connector-core</artifactId>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework</groupId>
+      <artifactId>spring-context</artifactId>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-autoconfigure</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>io.camunda.connector</groupId>
+      <artifactId>spring-boot-starter-camunda-connectors</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <!-- https://mvnrepository.com/artifact/io.github.alexswilliams/logstash-log4j2-encoder -->
+    <dependency>
+      <groupId>io.github.alexswilliams</groupId>
+      <artifactId>logstash-log4j2-encoder</artifactId>
+      <version>1.0.4</version>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jar-plugin</artifactId>
+        <configuration>
+          <archive>
+            <manifest>
+              <mainClass>org.springframework.boot.loader.PropertiesLauncher</mainClass>
+            </manifest>
+          </archive>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-dependency-plugin</artifactId>
+        <configuration>
+          <outputDirectory>${project.build.directory}/lib</outputDirectory>
+          <includeScope>compile</includeScope>
+          <excludeTransitive>false</excludeTransitive>
+        </configuration>
+        <executions>
+          <execution>
+            <id>copy-dependencies</id>
+            <goals>
+              <goal>copy-dependencies</goal>
+            </goals>
+            <phase>package</phase>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+
+</project>
diff --git a/...or/example-connector/src/main/java/com/camunda/consulting/connector/ExampleConnector.java b/...or/example-connector/src/main/java/com/camunda/consulting/connector/ExampleConnector.java
@@ -0,0 +1,24 @@
+package com.camunda.consulting.connector;
+
+import io.camunda.connector.api.annotation.OutboundConnector;
+import io.camunda.connector.api.outbound.OutboundConnectorContext;
+import io.camunda.connector.api.outbound.OutboundConnectorFunction;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+@OutboundConnector(name = "example-connector", type = "com.camunda.consulting:example", inputVariables = {})
+public class ExampleConnector implements OutboundConnectorFunction {
+  private static final Logger LOG = LoggerFactory.getLogger(ExampleConnector.class);
+private final MyBean myBean;
+
+
+  public ExampleConnector(MyBean myBean) {
+    this.myBean = myBean;
+  }
+
+  @Override
+  public Object execute(OutboundConnectorContext context) throws Exception {
+    LOG.info("Example connector has been invoked");
+    return null;
+  }
+}
diff --git a/...nnector/src/main/java/com/camunda/consulting/connector/ExampleConnectorConfiguration.java b/...nnector/src/main/java/com/camunda/consulting/connector/ExampleConnectorConfiguration.java
@@ -0,0 +1,17 @@
+package com.camunda.consulting.connector;
+
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.context.annotation.Bean;
+
+@AutoConfiguration
+public class ExampleConnectorConfiguration {
+  @Bean
+  public ExampleConnector exampleFunction(MyBean myBean) {
+    return new ExampleConnector(myBean);
+  }
+
+  @Bean
+  public MyBean myBean() {
+    return new MyBean();
+  }
+}
diff --git a/...ng-connector/example-connector/src/main/java/com/camunda/consulting/connector/MyBean.java b/...ng-connector/example-connector/src/main/java/com/camunda/consulting/connector/MyBean.java
@@ -0,0 +1,3 @@
+package com.camunda.consulting.connector;
+
+public class MyBean {}
diff --git a/spring-connector/example-connector/src/main/resources/META-INF/spring.factories b/spring-connector/example-connector/src/main/resources/META-INF/spring.factories
@@ -0,0 +1 @@
+org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.camunda.consulting.connector.ExampleConnectorConfiguration
diff --git a/...esources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports b/...esources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
@@ -0,0 +1 @@
+com.camunda.consulting.connector.ExampleConnectorConfiguration
diff --git a/spring-connector/pom.xml b/spring-connector/pom.xml
@@ -0,0 +1,55 @@
+<?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/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>com.camunda.consulting</groupId>
+  <artifactId>spring-connector</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <packaging>pom</packaging>
+  <modules>
+    <module>example-connector</module>
+    <module>example-connector-runtime</module>
+  </modules>
+
+  <properties>
+    <version.java>17</version.java>
+    <maven.compiler.source>17</maven.compiler.source>
+    <maven.compiler.target>17</maven.compiler.target>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
+  <dependencyManagement>
+    <dependencies>
+      <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-dependencies</artifactId>
+        <version>3.1.5</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+      <dependency>
+        <groupId>io.camunda.connector</groupId>
+        <artifactId>connector-core</artifactId>
+        <version>8.3.0</version>
+      </dependency>
+      <dependency>
+        <groupId>io.camunda.connector</groupId>
+        <artifactId>spring-boot-starter-camunda-connectors</artifactId>
+        <version>8.3.0</version>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+  <build>
+    <pluginManagement>
+      <plugins>
+        <plugin>
+          <groupId>org.springframework.boot</groupId>
+          <artifactId>spring-boot-maven-plugin</artifactId>
+          <version>3.1.5</version>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+  </build>
+</project>