Feature/#166 create element templates for workers

.github/workflows/development.yml

@@ -43,7 +43,7 @@ jobs:
 
       # Build
       - name: Build with Maven
-        run: ./mvnw clean verify -U -B -ntp -T4
+        run: ./mvnw clean install -U -B -ntp -T4
 
       # itest
       - name: Run itest

.github/workflows/master.yml

@@ -34,7 +34,7 @@ jobs:
 
       # Build
       - name: Build with Maven
-        run: ./mvnw clean verify -U -B -T4
+        run: ./mvnw clean install -U -B -T4
 
       # Get GPG private key into GPG
       - name: Import GPG Owner Trust

docs/process-engine-worker.md

@@ -75,8 +75,92 @@ If the annotation `@org.springframework.transaction.annotation.Transactional` wi
 is used, the library will execute the worker method and the completion of the external task via API in the same transaction. This will lead to 
 a transaction rollback, if the external task can't be completed (e.g. due to a network error).
 
+## Documentation
 
+You can automatically document your workers with the `process-engine-worker-documentation-api` and create on each build with the  `process-engine-worker-documentation-maven-plugin` maven plugin element templates for the workers.
 
+1. Add the `process-engine-worker-documentation-api`
 
+```xml
+    <dependency>
+      <groupId>dev.bpm-crafters.process-engine-worker</groupId>
+      <artifactId>process-engine-worker-documentation-api</artifactId>
+      <version>${process-engine-worker.version}</version>
+    </dependency>
+```
+
+2. Add the `@ProcessEngineWorkerDocumentation` annotation to your worker
+
+```kotlin
+  @ProcessEngineWorker("example-worker")
+  @ProcessEngineWorkerDocumentation(name = "Example Worker", description = "Example worker for documentation generation")
+  fun execute(@Variable(name = "exampleDto") exampleDto: ExampleDto): ExampleDto {
+    return exampleDto
+  }
+```
+
+3. Add the `@ProcessEngineWorkerPropertyDocumentation` annotation to your in and output variables
+
+```kotlin
+data class ExampleDto(
+  @field:ProcessEngineWorkerPropertyDocumentation(label = "Example Input")
+  val exampleInput: String
+) {
+}
+```
 
+```java
+public record ExampleDto(
+  @ProcessEngineWorkerPropertyDocumentation(label = "Example Input")
+  private String exampleInput
+){}
+```
+
+4. Add the maven plugin to your `pom.xml`s plugin section
+
+**C7 Maven Plugin**
+
+```xml
+  <plugin>
+    <groupId>dev.bpm-crafters.process-engine-worker</groupId>
+    <artifactId>process-engine-worker-documentation-c7-maven-plugin</artifactId>
+    <version>0.6.1-SNAPSHOT</version>
+    <configuration>
+      <clean>true</clean>
+      <outputDirectory>src/main/resources/bpmn/element-templates</outputDirectory>
+      <c7Config>
+        <asyncAfterDefaultValue>true</asyncAfterDefaultValue>
+      </c7Config>
+    </configuration>
+    <executions>
+      <execution>
+        <goals>
+          <goal>generate</goal>
+        </goals>
+        <phase>process-classes</phase>
+      </execution>
+    </executions>
+  </plugin>
+```
+
+**C8 Maven Plugin**
 
+```xml
+  <plugin>
+    <groupId>dev.bpm-crafters.process-engine-worker</groupId>
+    <artifactId>process-engine-worker-documentation-c8-maven-plugin</artifactId>
+    <version>0.6.1-SNAPSHOT</version>
+    <configuration>
+      <clean>true</clean>
+      <outputDirectory>src/main/resources/bpmn/element-templates</outputDirectory>
+    </configuration>
+    <executions>
+      <execution>
+        <goals>
+          <goal>generate</goal>
+        </goals>
+        <phase>process-classes</phase>
+      </execution>
+    </executions>
+  </plugin>
+```

documentation/documentation-api/pom.xml

@@ -0,0 +1,15 @@
+<?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>dev.bpm-crafters.process-engine-worker</groupId>
+    <artifactId>process-engine-worker-documentation</artifactId>
+    <version>0.6.1-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>process-engine-worker-documentation-api</artifactId>
+  <name>${project.artifactId}</name>
+
+</project>

documentation/documentation-api/src/main/kotlin/dev/bpmcrafters/processengine/worker/documentation/api/ProcessEngineWorkerDocumentation.kt

@@ -0,0 +1,7 @@
+package dev.bpmcrafters.processengine.worker.documentation.api
+
+annotation class ProcessEngineWorkerDocumentation(
+  val name: String,
+  val description: String = "",
+  val version: Int = -1
+)

documentation/documentation-api/src/main/kotlin/dev/bpmcrafters/processengine/worker/documentation/api/ProcessEngineWorkerPropertyDocumentation.kt

@@ -0,0 +1,8 @@
+package dev.bpmcrafters.processengine.worker.documentation.api
+
+annotation class ProcessEngineWorkerPropertyDocumentation(
+  val type: PropertyType = PropertyType.STRING,
+  val label: String,
+  val notEmpty: Boolean = false,
+  val editable: Boolean = true,
+)

documentation/documentation-api/src/main/kotlin/dev/bpmcrafters/processengine/worker/documentation/api/PropertyType.kt

@@ -0,0 +1,7 @@
+package dev.bpmcrafters.processengine.worker.documentation.api
+
+enum class PropertyType(val type: String) {
+  STRING("String"),
+  TEXT("Text"),
+  HIDDEN("Hidden")
+}

documentation/documentation-c7-maven-plugin/pom.xml

@@ -0,0 +1,96 @@
+<?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>dev.bpm-crafters.process-engine-worker</groupId>
+    <artifactId>process-engine-worker-documentation</artifactId>
+    <version>0.6.1-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>process-engine-worker-documentation-c7-maven-plugin</artifactId>
+  <name>${project.artifactId}</name>
+  <packaging>maven-plugin</packaging>
+  <description>Maven plugin to generate camunda 7 element templates</description>
+
+  <properties>
+    <org.apache.maven.version>3.9.11</org.apache.maven.version>
+    <org.apache.maven.plugin-tools.version>3.15.1</org.apache.maven.plugin-tools.version>
+    <org.reflections.version>0.10.2</org.reflections.version>
+    <org.apache.maven-plugins.version>3.15.1</org.apache.maven-plugins.version>
+  </properties>
+
+  <dependencies>
+    <!--Maven-->
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-plugin-api</artifactId>
+      <version>${org.apache.maven.version}</version>
+    </dependency>
+
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-core</artifactId>
+      <version>${org.apache.maven.version}</version>
+    </dependency>
+
+    <dependency>
+      <groupId>org.apache.maven.plugin-tools</groupId>
+      <artifactId>maven-plugin-annotations</artifactId>
+      <version>${org.apache.maven.plugin-tools.version}</version>
+      <scope>provided</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>dev.bpm-crafters.process-engine-worker</groupId>
+      <artifactId>process-engine-worker-documentation-core</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+  </dependencies>
+
+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-plugin-plugin</artifactId>
+        <version>${org.apache.maven-plugins.version}</version>
+      </plugin>
+    </plugins>
+  </reporting>
+
+  <build>
+    <pluginManagement>
+      <plugins>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-plugin-plugin</artifactId>
+          <version>${org.apache.maven-plugins.version}</version>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+
+    <plugins>
+      <plugin>
+        <groupId>org.jsonschema2pojo</groupId>
+        <artifactId>jsonschema2pojo-maven-plugin</artifactId>
+        <version>1.2.2</version>
+        <configuration>
+          <sourceDirectory>${basedir}/src/main/resources/schema</sourceDirectory>
+          <targetPackage>dev.bpmcrafters.processengine.worker.documentation.elementtemplates.gen</targetPackage>
+          <generateBuilders>true</generateBuilders>
+          <useJakartaValidation>true</useJakartaValidation>
+        </configuration>
+        <executions>
+          <execution>
+            <phase>generate-sources</phase>
+            <goals>
+              <goal>generate</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+
+</project>

documentation/documentation-c7-maven-plugin/src/main/kotlin/dev/bpmcrafters/processengine/worker/documentation/C7Config.kt

@@ -0,0 +1,6 @@
+package dev.bpmcrafters.processengine.worker.documentation
+
+data class C7Config(
+  val asyncBeforeDefaultValue: Boolean = false,
+  val asyncAfterDefaultValue: Boolean = false
+)

documentation/documentation-c7-maven-plugin/src/main/kotlin/dev/bpmcrafters/processengine/worker/documentation/WorkerDocumentationGeneratorMojo.kt

@@ -0,0 +1,80 @@
+package dev.bpmcrafters.processengine.worker.documentation
+
+import dev.bpmcrafters.processengine.worker.documentation.core.WorkerDocumentationGenerator
+import dev.bpmcrafters.processengine.worker.documentation.engine.Camunda7ElementTemplateGenerator
+import dev.bpmcrafters.processengine.worker.documentation.generator.api.DocumentationFailedException
+import dev.bpmcrafters.processengine.worker.documentation.generator.api.EngineDocumentationGeneratorApi
+import dev.bpmcrafters.processengine.worker.documentation.generator.api.InputValueNamingPolicy
+import org.apache.maven.plugin.AbstractMojo
+import org.apache.maven.plugin.MojoExecutionException
+import org.apache.maven.plugin.logging.Log
+import org.apache.maven.plugins.annotations.LifecyclePhase
+import org.apache.maven.plugins.annotations.Mojo
+import org.apache.maven.plugins.annotations.Parameter
+import org.apache.maven.plugins.annotations.ResolutionScope
+import org.apache.maven.project.MavenProject
+import java.io.File
+
+@Mojo(name = "generate", defaultPhase = LifecyclePhase.PROCESS_CLASSES, requiresDependencyResolution = ResolutionScope.RUNTIME)
+class WorkerDocumentationGeneratorMojo: AbstractMojo() {
+
+  private val log: Log = getLog()
+
+  @Parameter(defaultValue = "\${project}", required = true, readonly = true)
+  var project: MavenProject? = null
+
+  /**
+   * Directory to output the generated element templates to.
+   */
+  @Parameter(property = "elementtemplategen.outputDirectory", defaultValue = "\${project.build.directory/generated-sources/element-templates}")
+  var outputDirectory: File? = null
+
+  /**
+   * The naming policy for input values.
+   * EMPTY => ${}
+   * ATTRIBUTE_NAME => ${<attributeName>}
+  </attributeName> */
+  @Parameter(name = "inputValueNamingPolicy", property = "elementtemplategen.inputValueNamingPolicy", defaultValue = "EMPTY")
+  var inputValueNamingPolicy: InputValueNamingPolicy? = null
+
+  /**
+   * A flag indicating if the output directory should be cleaned before generation.
+   */
+  @Parameter(name = "clean", property = "elementtemplategen.clean", defaultValue = "false")
+  var clean: Boolean = false
+
+  /**
+   * Platform-specific configuration options
+   */
+  @Parameter
+  var c7Config: C7Config = C7Config()
+
+  // Minimal factory hook for testing/injection
+  var generatorFactory: (MavenProject, File, EngineDocumentationGeneratorApi) -> WorkerDocumentationGenerator =
+    { project, outputDir, generator -> WorkerDocumentationGenerator(project, outputDir, generator) }
+
+  override fun execute() {
+    log.info("Generating element templates for ${project?.artifactId}")
+
+    val workerDocumentationGenerator = generatorFactory(
+      requireNotNull(project),
+      requireNotNull(outputDirectory),
+      Camunda7ElementTemplateGenerator(c7Config = c7Config)
+    )
+
+    try {
+      if (clean) {
+        log.info("Cleaning output directory...")
+        workerDocumentationGenerator.clean()
+      }
+      log.info("Generate worker documentation")
+      workerDocumentationGenerator.generate()
+    } catch (e: DocumentationFailedException) {
+      log.error(e.message)
+      log.debug(e)
+      throw MojoExecutionException(e.message)
+    }
+
+  }
+
+}