From 9b9a6816e1090c1a07d1c095568d3ffa717458f4 Mon Sep 17 00:00:00 2001 From: Bastian Koerber <119578341+bastiankoerber@users.noreply.github.com> Date: Thu, 2 Apr 2026 10:54:44 +0200 Subject: [PATCH 1/2] fix: add Slack connector input targets and element template guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add exact Slack connector input targets (chat.postMessage, conversations.create, conversations.invite) to camunda-dev-guide.md - Document that data.messageType is required for chat.postMessage - Document correct field names (data.newChannelName not data.name, data.visibility not is_private) - Add element template warning: do NOT set zeebe:modelerTemplate attributes or elementTemplateId headers in generated BPMN XML — these cause "Template Not found" errors in Web Modeler - Update /new-process skill to reference element template JSON from the connectors repo for accurate input target discovery --- .claude/skills/new-process/SKILL.md | 11 +++++++- docs/camunda-dev-guide.md | 39 +++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+), 1 deletion(-) diff --git a/.claude/skills/new-process/SKILL.md b/.claude/skills/new-process/SKILL.md index 21d30ab..4c5abd6 100644 --- a/.claude/skills/new-process/SKILL.md +++ b/.claude/skills/new-process/SKILL.md @@ -6,7 +6,16 @@ argument-hint: "[process description]" Generate a deployable Camunda 8 BPMN file. Find and read `camunda-dev-guide.md` for Zeebe-specific patterns. For agentic processes with AI agents and ad-hoc sub-processes, use `/new-agent` instead. -If the process uses non-REST connectors (Slack, Kafka, SendGrid, etc.), look up their task type and input targets via the Camunda Docs MCP tool or at https://docs.camunda.io/docs/components/connectors/out-of-the-box-connectors/ +If the process uses non-REST connectors (Slack, Kafka, SendGrid, etc.), look up their **element template JSON** from `https://github.com/camunda/connectors/tree/main/connectors/` to get the exact input target names, required fields, and conditional properties. Fall back to Camunda Docs MCP or https://docs.camunda.io/docs/components/connectors/out-of-the-box-connectors/ + +## Element Templates — IMPORTANT + +Do NOT manually add `zeebe:modelerTemplate` attributes or `elementTemplateId`/`elementTemplateVersion` task headers in generated BPMN XML. These cause "Template Not found" errors in Web Modeler. + +Instead: +- Generate BPMN with correct `zeebe:taskDefinition`, `zeebe:ioMapping`, and `zeebe:taskHeaders` matching the template's property bindings +- Use the official element template JSON to determine correct input target names (they differ per connector — some use flat names, others use `data.*` or `authentication.*` prefixes) +- After uploading to Web Modeler, the user applies the connector template from the Modeler UI $ARGUMENTS diff --git a/docs/camunda-dev-guide.md b/docs/camunda-dev-guide.md index 8191893..567c05d 100644 --- a/docs/camunda-dev-guide.md +++ b/docs/camunda-dev-guide.md @@ -161,6 +161,45 @@ Secrets (API keys, tokens) are referenced as `{{secrets.MY_SECRET}}` in input va ### REST connector input targets (must be exact): `method`, `url`, `body`, `headers`, `queryParameters`, `authentication.type`, `authentication.token`, `authentication.username`, `authentication.password`, `connectionTimeoutInSeconds`, `readTimeoutInSeconds` +### Slack connector (`io.camunda:slack:1`): + +Input targets vary by method. Root-level: `token`, `method`. Method-specific fields use `data.*` prefix. + +**chat.postMessage:** +```xml + + + + + +``` +`data.messageType` is required (`plainText` or `messageBlock`). Channel accepts channel name, user ID (for DMs), or email. + +**conversations.create:** +```xml + + + +``` +Note: field is `data.newChannelName` (not `data.name`), `data.visibility` is `PUBLIC`/`PRIVATE` (not boolean). + +**conversations.invite:** +```xml + + + +``` + +Other methods: `reactions.add`, `pins.add`, `pins.remove`. Look up the element template JSON for full bindings. + +### Element Templates — do NOT set manually + +Do NOT add `zeebe:modelerTemplate` attributes or `elementTemplateId`/`elementTemplateVersion` task headers in generated BPMN. These cause "Template Not found" errors in Web Modeler. + +Instead: generate correct `zeebe:taskDefinition`, `zeebe:ioMapping`, and `zeebe:taskHeaders` matching the template's property bindings. The user applies the connector template from the Web Modeler UI after upload. + +To find correct input targets for any connector, fetch its element template JSON from: `https://github.com/camunda/connectors/tree/main/connectors//element-templates/` + --- ## Agentic BPMN (AI Agents) From 2f7e51a7e787fd49a21a8140d38208643b08b0b5 Mon Sep 17 00:00:00 2001 From: Bastian Koerber <119578341+bastiankoerber@users.noreply.github.com> Date: Thu, 2 Apr 2026 11:07:39 +0200 Subject: [PATCH 2/2] docs: generalize element template and connector input target guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Expand "To configure any specific connector" section with step-by-step instructions for reading element template JSON (binding types, conditional properties, required fields) - Add comprehensive "Element Templates — do NOT set manually in BPMN XML" section explaining why zeebe:modelerTemplate attributes cause errors and how to correctly generate BPMN for Web Modeler compatibility - Add note that input target naming is connector-specific (REST uses flat names, Slack uses data.* prefix) — always check the element template - Update /new-agent skill with same element template guidance Validated against two connectors: - REST (io.camunda:http-json:1): flat targets, deployed and ran successfully - Slack (io.camunda:slack:1): data.* prefixed targets, learned correct field names through deployment error iteration --- .claude/skills/new-agent/SKILL.md | 2 +- docs/camunda-dev-guide.md | 36 ++++++++++++++++++++++++------- 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/.claude/skills/new-agent/SKILL.md b/.claude/skills/new-agent/SKILL.md index 9bb1d6b..07ac07d 100644 --- a/.claude/skills/new-agent/SKILL.md +++ b/.claude/skills/new-agent/SKILL.md @@ -24,6 +24,6 @@ Tools can also be **sub-processes** for multi-step async patterns: - Use this for send+wait, request+callback, or any tool needing async interaction - See the "Sub-flow Tool Pattern" section in camunda-dev-guide.md -For non-REST connectors as tools, look up their task type and input targets via the Camunda Docs MCP tool. +For non-REST connectors as tools, look up their **element template JSON** from `https://github.com/camunda/connectors/tree/main/connectors/` for exact input target names. Do NOT add `zeebe:modelerTemplate` attributes or `elementTemplateId` headers — these cause errors in Web Modeler. The user applies templates from the Modeler UI after upload. Save to resources/. Deploy with c8ctl. diff --git a/docs/camunda-dev-guide.md b/docs/camunda-dev-guide.md index 567c05d..68e9766 100644 --- a/docs/camunda-dev-guide.md +++ b/docs/camunda-dev-guide.md @@ -128,10 +128,13 @@ All outbound connectors (REST, Slack, Kafka, SendGrid, OpenAI, AWS, etc.) use th ``` ### To configure any specific connector: -1. Look up the connector in Camunda docs (use the Docs MCP tool or https://docs.camunda.io/docs/components/connectors/out-of-the-box-connectors/) -2. Find the **task type** (e.g., `io.camunda:http-json:1`, `io.camunda:slack:1`, `io.camunda:kafka:1`) -3. Find the **required input target names** and expected values -4. Apply them to the pattern above +1. **Fetch the element template JSON** from `https://github.com/camunda/connectors/tree/main/connectors//element-templates/` — this is the authoritative source for input target names +2. Find the **task type** in the template (property with `"binding": {"property": "type", "type": "zeebe:taskDefinition"}`) +3. Find all **input bindings** (properties with `"binding": {"name": "...", "type": "zeebe:input"}`) — the `name` field is the exact `target` value for `` +4. Note **conditional properties** — some inputs are only required when another property has a specific value (e.g., `data.text` only when `method` = `chat.postMessage`) +5. Apply them to the universal pattern above + +Fall back to Camunda Docs MCP or https://docs.camunda.io/docs/components/connectors/out-of-the-box-connectors/ if the template JSON is unavailable. Secrets (API keys, tokens) are referenced as `{{secrets.MY_SECRET}}` in input values. @@ -140,6 +143,7 @@ Secrets (API keys, tokens) are referenced as `{{secrets.MY_SECRET}}` in input va - Outputs (result extraction) go in `` as `` — NOT in ioMapping - Response shape for REST: `response.status`, `response.headers`, `response.body` - `retryBackoff` is a reserved header key handled by the connector runtime +- **Input target naming is connector-specific**: REST uses flat names (`method`, `url`, `body`) + `authentication.*`; Slack uses `data.*` prefix for method-specific fields. Always check the element template — do NOT guess target names. ### REST connector example (most common, `io.camunda:http-json:1`): ```xml @@ -192,13 +196,29 @@ Note: field is `data.newChannelName` (not `data.name`), `data.visibility` is `PU Other methods: `reactions.add`, `pins.add`, `pins.remove`. Look up the element template JSON for full bindings. -### Element Templates — do NOT set manually +### Element Templates — do NOT set manually in BPMN XML + +Element templates are JSON files that define the connector's properties, UI groups, and validation rules for Web Modeler. Each connector has one in the `camunda/connectors` repo. + +**When generating BPMN programmatically or with AI:** + +Do NOT add `zeebe:modelerTemplate` / `zeebe:modelerTemplateVersion` attributes on service tasks, and do NOT add `elementTemplateId` / `elementTemplateVersion` task headers. These cause "Template Not found" errors in Web Modeler because the template must be resolved from the Modeler's internal catalog — raw XML references don't link to it. + +Instead: +1. Generate BPMN with correct `zeebe:taskDefinition`, `zeebe:ioMapping`, and `zeebe:taskHeaders` that match the template's property bindings +2. The user applies the connector template from the Web Modeler UI after upload (right-click task → "Apply template" or use the properties panel) +3. Web Modeler will recognize the existing inputs and map them to the template fields -Do NOT add `zeebe:modelerTemplate` attributes or `elementTemplateId`/`elementTemplateVersion` task headers in generated BPMN. These cause "Template Not found" errors in Web Modeler. +**Reading element template JSON — how to extract input targets:** -Instead: generate correct `zeebe:taskDefinition`, `zeebe:ioMapping`, and `zeebe:taskHeaders` matching the template's property bindings. The user applies the connector template from the Web Modeler UI after upload. +Each template property has a `binding` object: +- `"type": "zeebe:input"` with `"name": "..."` → the `name` is the exact `target` for `` +- `"type": "zeebe:taskDefinition"` with `"property": "type"` → the task type +- `"type": "zeebe:taskHeader"` with `"key": "..."` → the `key` for `` +- Properties with `"condition"` are only required when the condition matches (e.g., `body` only for POST/PUT/PATCH) +- Properties with `"value"` have defaults — include them if they're required (`constraints.notEmpty`) -To find correct input targets for any connector, fetch its element template JSON from: `https://github.com/camunda/connectors/tree/main/connectors//element-templates/` +Template JSON location: `https://github.com/camunda/connectors/tree/main/connectors//element-templates/` ---