Merge pull request #6 from crobbins215/upgrade/camunda-8.9.1

Upgrade to Camunda 8.9.1 / PDFBox 3.0.7 (v1.4.0)

Author: crobbins215

CLAUDE.md

@@ -0,0 +1,50 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+Camunda 8 outbound connector that merges and splits PDF documents inside BPMN workflows. Built on the Camunda Connector SDK (8.9.1) and Apache PDFBox (3.0.7), targeting Java 21 (`.tool-versions` pins `temurin-21.0.8` + `maven 3.8.4`).
+
+> **Runtime note:** the `camunda/connectors:8.9.1` base image ships **Java 25 + Spring Boot 4.0.5 + Tomcat 11**. We compile to Java 21 bytecode and rely on JVM backward compatibility — don't be surprised when container logs report Java 25.
+
+## Common commands
+
+```bash
+mvn clean package          # Build thin + shaded fat JAR; also regenerates element-templates/pdf-connector.json
+mvn clean verify           # Run all tests + JaCoCo report (target/site/jacoco/)
+mvn -Pcoverage-enforced verify   # Same, but fails build under 80% instruction / 75% branch coverage
+mvn test -Dtest=PdfConnectorTest                   # Single test class
+mvn test -Dtest=PdfConnectorTest#shouldMergeTwoPdfs # Single test method
+```
+
+The full Camunda runtime integration test (`integration/PdfConnectorIntegrationTest`) is `@Disabled` by default — it pulls `camunda/camunda:8.9.1` via Docker. Enable manually when Docker is available.
+
+Run the connector locally inside a Spring Boot runtime by starting the **test-scope** main class `io.camunda.example.classic.LocalConnectorRuntime` (Camunda config lives in `src/main/resources/application.properties`, copied from the `.template` file — never commit the real one).
+
+Enable the secret-scan pre-commit hook once per clone: `git config core.hooksPath .githooks`. Bypass with `SKIP_SECRET_CHECK=1` only if absolutely necessary.
+
+## Architecture
+
+This connector uses the **Operations API** pattern (`OutboundConnectorProvider` + `@Operation`), which is newer than the classic `OutboundConnectorFunction` single-entry-point style. One class exposes multiple operations and the SDK routes by `operationId`:
+
+- [src/main/java/io/camunda/example/operations/PdfConnectorProvider.java](src/main/java/io/camunda/example/operations/PdfConnectorProvider.java) — the `@OutboundConnector` + `@ElementTemplate` entry point. Each `@Operation`-annotated method (mergePdfs, splitByPage, splitByRange, splitByBookmark, splitBySize) is a thin delegate to `PdfOperations`. The `@Variable` parameter is a discriminated request record nested under `PdfConnectorRequest`.
+- [src/main/java/io/camunda/example/operations/PdfOperations.java](src/main/java/io/camunda/example/operations/PdfOperations.java) — all PDFBox logic. Static methods load PDFs via `Loader.loadPDF(RandomAccessReadBuffer)`, manipulate them, and create new `Document` objects via `context.create(DocumentCreationRequest...)`. Errors must be thrown as `ConnectorException` with one of the documented codes (`PDF_MERGE_ERROR`, `PDF_SPLIT_ERROR`, `NO_BOOKMARKS`, `INVALID_PAGE_RANGE`).
+- [src/main/java/io/camunda/dto/PdfConnectorRequest.java](src/main/java/io/camunda/dto/PdfConnectorRequest.java) and [PdfConnectorResult.java](src/main/java/io/camunda/dto/PdfConnectorResult.java) — Java records with `@TemplateProperty` and Jakarta Bean Validation annotations. **The element template is generated from these records at `mvn package` time** by the `element-template-generator-maven-plugin`, so any field/label/group change must be made in the record (do not hand-edit `element-templates/pdf-connector.json`).
+- [src/main/resources/META-INF/services/io.camunda.connector.api.outbound.OutboundConnectorProvider](src/main/resources/META-INF/services/io.camunda.connector.api.outbound.OutboundConnectorProvider) — SPI registration; must list `PdfConnectorProvider` for the runtime to discover the connector.
+
+### Shading (important)
+
+`maven-shade-plugin` relocates `org.apache.pdfbox` → `io.camunda.connector.pdf.shaded.pdfbox` (and fontbox similarly) in the fat JAR. This avoids classpath clashes with other connectors in the same runtime. The connector SDK is `<scope>provided</scope>` and supplied by the runtime — do not bundle it.
+
+### Test layout quirk
+
+`LocalConnectorRuntime` (the dev entry point) lives under `src/test/java/io/camunda/example/classic/`, not `src/main/java`. It is a Spring Boot starter that pulls in `spring-boot-starter-camunda-connectors` (test scope). Don't move it to main without also moving its dependencies out of test scope.
+
+## Conventions
+
+- Versions in `pom.xml`, `Dockerfile` (`COPY target/pdf-merge-split-connector-<version>.jar`), and the README release notes must stay in sync. Bump all three on release.
+- The Dockerfile copies the connector JAR to `/opt/custom/`, not `/opt/app/`. The 8.9.x base image's `start.sh` sets `-Dloader.path=/opt/custom/`; `/opt/app/` is reserved for the runtime jar itself and putting the connector there will crash with a `NoClassDefFoundError` for `OutboundConnectorProvider`. (Earlier 8.8.x images accepted `/opt/app/`.)
+- `element-template-generator-core` is a build-time-only dependency and must remain `<scope>provided</scope>` — it transitively pulls in slf4j-api, Jackson, scala-library, etc., which collide with the runtime if shaded into the fat JAR.
+- README documents user-facing behavior; keep operation input/output JSON schemas there in sync with the DTOs.
+- Coverage is reported on every `verify` but only enforced under the `coverage-enforced` profile — CI runs the unenforced variant.

Dockerfile

@@ -1,6 +1,7 @@
-FROM camunda/connectors:8.8.3
+FROM camunda/connectors:8.9.1
 
-# Copy the connector JAR
-COPY target/pdf-merge-split-connector-1.3.1.jar /opt/app/
+# Connector JARs go in /opt/custom/ (loader.path for Spring Boot PropertiesLauncher).
+# In 8.8.x and earlier, /opt/app/ worked; the 8.9.x base image changed this.
+COPY target/pdf-merge-split-connector-1.4.0.jar /opt/custom/
 
 # The base image will automatically pick up the connector

README.md

@@ -23,8 +23,8 @@ In many IDP (Intelligent Document Processing) scenarios, users deal with scanned
 This connector uses the **Operations API** approach with `OutboundConnectorProvider`, allowing multiple PDF operations within a single connector without manual routing.
 
 **Key Technologies:**
-- Apache PDFBox 3.0.3 for PDF manipulation
-- Camunda Connector SDK 8.8.3
+- Apache PDFBox 3.0.7 for PDF manipulation
+- Camunda Connector SDK 8.9.1
 - Java 21
 
 **Operations Implementation:** [`io.camunda.example.operations.PdfConnectorProvider`](src/main/java/io/camunda/example/operations/PdfConnectorProvider.java)
@@ -429,6 +429,15 @@ The generated element template can be found in [element-templates/pdf-connector.
 
 ## Release Notes
 
+**Version 1.4.0**
+
+Changes:
+- ✅ **Camunda 8.9** - Upgraded Connector SDK and `camunda-process-test-spring` to `8.9.1` to match the latest stable cluster
+- ✅ **Docker** - Base image bumped to `camunda/connectors:8.9.1`
+- ✅ **PDFBox** - Upgraded to `3.0.7` (patch-level)
+- ✅ **Test stack** - JUnit Jupiter `5.14.4`, AssertJ `3.27.7`, Mockito `5.23.0`, Awaitility `4.3.0`
+- ✅ **Build plugins** - JaCoCo `0.8.14`, maven-shade-plugin `3.6.2`, maven-surefire-plugin `3.5.5`
+
 **Version 1.3.1**
 
 Changes:

pom.xml

@@ -8,20 +8,20 @@
   <groupId>io.camunda.connector</groupId>
   <artifactId>pdf-merge-split-connector</artifactId>
   <packaging>jar</packaging>
-  <version>1.3.1</version>
+  <version>1.4.0</version>
 
   <properties>
     <maven.compiler.release>21</maven.compiler.release>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
-    <version.connectors>8.8.3</version.connectors>
-    <version.camunda>8.8.3</version.camunda>
-    <version.pdfbox>3.0.3</version.pdfbox>
+    <version.connectors>8.9.1</version.connectors>
+    <version.camunda>8.9.1</version.camunda>
+    <version.pdfbox>3.0.7</version.pdfbox>
     <version.assertj>3.27.7</version.assertj>
-    <version.junit-jupiter>5.11.3</version.junit-jupiter>
-    <version.awaitility>4.2.0</version.awaitility>
-    <version.mockito>5.19.0</version.mockito>
-    <jacoco.version>0.8.12</jacoco.version>
+    <version.junit-jupiter>6.0.3</version.junit-jupiter>
+    <version.awaitility>4.3.0</version.awaitility>
+    <version.mockito>5.23.0</version.mockito>
+    <jacoco.version>0.8.14</jacoco.version>
   </properties>
 
   <dependencies>
@@ -39,11 +39,12 @@
       <version>${version.pdfbox}</version>
     </dependency>
 
-    <!-- Element template generator annotations (compile-time only) -->
+    <!-- Element template generator annotations (compile-time only; provided by runtime) -->
     <dependency>
       <groupId>io.camunda.connector</groupId>
       <artifactId>element-template-generator-core</artifactId>
       <version>${version.connectors}</version>
+      <scope>provided</scope>
     </dependency>
 
     <!-- test dependencies -->
@@ -118,7 +119,7 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-surefire-plugin</artifactId>
-        <version>3.2.5</version>
+        <version>3.5.5</version>
       </plugin>
       <!-- JaCoCo plugin for code coverage -->
       <plugin>
@@ -144,7 +145,7 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-shade-plugin</artifactId>
-        <version>3.5.1</version>
+        <version>3.6.2</version>
         <executions>
           <execution>
             <phase>package</phase>

src/main/java/io/camunda/dto/PdfConnectorRequest.java

@@ -1,7 +1,7 @@
 package io.camunda.dto;
 
 import io.camunda.connector.api.document.Document;
-import io.camunda.connector.generator.dsl.Property;
+import io.camunda.connector.generator.java.annotation.FeelMode;
 import io.camunda.connector.generator.java.annotation.TemplateProperty;
 import jakarta.validation.constraints.*;
 import java.util.List;
@@ -19,7 +19,7 @@ public record MergePdfs(
             group = "operation",
             label = "PDF Documents",
             description = "List of PDF documents to merge (in order)",
-            feel = Property.FeelMode.required,
+            feel = FeelMode.required,
             type = TemplateProperty.PropertyType.String
         )
         @NotNull @NotEmpty
@@ -43,7 +43,7 @@ public record SplitByPage(
             group = "operation",
             label = "PDF Document",
             description = "The PDF document to split",
-            feel = Property.FeelMode.required,
+            feel = FeelMode.required,
             type = TemplateProperty.PropertyType.String
         )
         @NotNull
@@ -76,7 +76,7 @@ public record SplitByRange(
             group = "operation",
             label = "PDF Document",
             description = "The PDF document to split",
-            feel = Property.FeelMode.required,
+            feel = FeelMode.required,
             type = TemplateProperty.PropertyType.String
         )
         @NotNull
@@ -87,7 +87,7 @@ public record SplitByRange(
             group = "operation",
             label = "Page Ranges",
             description = "Comma-separated page ranges (e.g., '1-3,5-7,10-15'). Pages are 1-indexed.",
-            feel = Property.FeelMode.optional
+            feel = FeelMode.optional
         )
         @NotBlank
         String pageRanges,
@@ -110,7 +110,7 @@ public record SplitByBookmark(
             group = "operation",
             label = "PDF Document",
             description = "The PDF document to split by bookmarks",
-            feel = Property.FeelMode.required,
+            feel = FeelMode.required,
             type = TemplateProperty.PropertyType.String
         )
         @NotNull
@@ -143,7 +143,7 @@ public record SplitBySize(
             group = "operation",
             label = "PDF Document",
             description = "The PDF document to split by size",
-            feel = Property.FeelMode.required,
+            feel = FeelMode.required,
             type = TemplateProperty.PropertyType.String
         )
         @NotNull

src/test/java/io/camunda/example/classic/integration/PdfConnectorIntegrationTest.java

@@ -14,7 +14,7 @@
  * Integration test for PDF Merge & Split Connector.
  * Tests the connector in a full Camunda runtime environment.
  * 
- * NOTE: This test requires Docker to be running and will pull camunda/camunda:8.8.3 image.
+ * NOTE: This test requires Docker to be running and will pull camunda/camunda:8.9.1 image.
  * Disabled by default for faster builds. Enable when Docker is available.
  */
 @Disabled("Requires Docker - enable manually when needed")

src/test/java/io/camunda/example/classic/integration/TestConnectorRuntimeApplication.java

@@ -7,12 +7,11 @@
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.ImportAutoConfiguration;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
-import org.springframework.boot.autoconfigure.elasticsearch.ElasticsearchRestClientAutoConfiguration;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Primary;
 import org.springframework.test.context.bean.override.mockito.MockitoBean;
 
-@SpringBootApplication(exclude = {ElasticsearchRestClientAutoConfiguration.class})
+@SpringBootApplication
 @ImportAutoConfiguration({
     io.camunda.connector.runtime.InboundConnectorsAutoConfiguration.class,
     io.camunda.connector.runtime.OutboundConnectorsAutoConfiguration.class,