Connector Release 10 min read

Strict Public vs. Internal Isolation & Real Zammad 7.2 RAG: Announcing the Zammad Repository Connector

Support helpdesks hold some of an enterprise's richest operational knowledge—and some of its sharpest access-control hazards. Today we are releasing the native Zammad Helpdesk & Knowledge Base Repository Connector (oc-zammad-repository-connector, merged in PR #372), built on the official Zammad REST API v1, Java 25 Virtual Threads, strict public vs. internal article ACL separation, and end-to-end verified against a live Zammad 7.2.3 + Elasticsearch 9.5.5 stack.


1. Why Helpdesk RAG Breaks Without Article-Level Isolation

In an ITSM and helpdesk platform like Zammad, a single support ticket mixes two completely different trust zones: customer-facing replies (internal: false) and confidential internal agent triage notes, escalation runbooks, and diagnostic dumps (internal: true).

Flattening an entire ticket thread into one vector document—or indexing tickets without preserving Zammad's group, customer, and shared-organization boundaries—immediately leaks internal engineering notes to customers and exposes one customer's incidents to another organization. Even worse, Zammad Knowledge Base articles carry granular category role permissions and future-scheduled publication and archiving timestamps that naive scrapers routinely ignore.

Verified Against Real Zammad 7.2.3 + Elasticsearch 9.5.5: Every API call, incremental Elasticsearch delta query, Knowledge Base permission lookup, binary attachment stream, tombstone deletion, and 5-persona MCP Zero-Trust scenario is automatically verified in CI against official ghcr.io/zammad/zammad:7.2.3-0008 and elasticsearch:9.5.5 containers.

2. Architecture & Decoupled Ingestion Flow

ZammadRepositoryConnector connects to self-hosted or Zammad Cloud instances over REST API v1 (/api/v1/...) using personal HTTP access tokens (Authorization: Token token=…), OAuth2 Bearer tokens, or Basic authentication, with optional X-On-Behalf-Of user delegation. Tickets are processed concurrently on Java 25 Virtual Threads via StructuredTaskScope and bounded semaphores, streaming binary attachments through size-capped temporary files (TempFileInputStream) into OpenCrawling's Claim-Check Store and Kafka pipeline.

Zammad REST API v1 → Zero-Trust Decoupled RAG Pipeline
Zammad 7.x + ES 9.5
Tickets, Notes, Files & KB
ZammadRepositoryConnector
Virtual Threads & State
ZammadSecurityMapper
Public / Internal Split ACL
Kafka + Tika 4 + Embed
Claim-Check & Chunking
Vector Store + MCP
Zero-Trust Retrieval

3. Strict Public vs. Internal Ticket & Attachment Partitioning

Instead of merging public replies and private agent notes into a single document, the connector partitions every ticket according to article-granularity:

4. Fail-Closed Zero-Trust ACL Mapping

ZammadSecurityMapper translates Zammad's native authorization model into OIS SecurityConfig rules enforced authoritatively by the Secure MCP Server (DocumentAccessGate / McpAclEvaluator):

Mapping between Zammad entities and Open Ingestion Standard (OIS) security principals
Zammad Entity OIS Security Principals Guarantee
Public Ticket Thread & Public Attachments group:zammad-group-<group>, user:<customerEmail>, and group:zammad-org-<org> (only if organization.shared == true) Non-shared organizations (shared: false) never grant cross-colleague read access.
Internal Agent Notes & Internal Attachments group:zammad-group-<group> only Customer and organization principals—plus zammad.customer and zammad.organization metadata—are stripped.
Knowledge Base Answers group:zammad-role-<role> from Zammad's computed permissions_effective (or public only when published & allow-public-kb=true) Categories whose explicit granular permissions deny all roles (access: "none") fail closed instead of falling back to all agent groups.
Unresolvable / Orphan Group Empty SecurityConfig (permissions: []) Strict fail-closed behavior—never defaults to public.

5. Hardened Against Real Zammad 7.2 API Behavior

Running our connector against a live Zammad 7.2.3-0008 + Elasticsearch 9.5.5 deployment surfaced several real-world API details that we hardened directly into the v1 release:

6. Quick Configuration Reference

Sample application.yml configuration for oc-zammad-repository-connector
spring:
  opencrawling:
    connector:
      type: zammad
      zammad:
        base-url: "https://support.acme.com"
        auth-type: "token"                      # token | oauth2 | basic
        access-token: "${ZAMMAD_ACCESS_TOKEN}"
        group-names: "Tier-2-Identity-Security,Billing-Operations"
        article-granularity: "SPLIT_PUBLIC_AND_INTERNAL"
        include-internal-articles: true
        include-attachments: true
        include-knowledge-base: true
        include-tags: true
        crawl-mode: "search_delta"              # search_delta | full
        state-file: "/data/zammad-state"
        max-attachment-size-bytes: 52428800
        include-acls: true
        include-customer-in-public-acl: true
        include-shared-organization-in-public-acl: true
        allow-public-kb: false
        page-size: 50
        parallelism: 4

7. Dual-Tier Automated Verification (Mock & Real Zammad 7.2)

PR #372 ships two dedicated test suites wired directly into GitHub Actions (.github/workflows/integration-tests.yml):

Run the standalone and real Zammad 7.2 decoupled integration suites locally
# 1. Fast standalone REST contract, emulator, unit & runtime wiring suite
./scripts/test-zammad-connector.sh

# 2. Full 9-step decoupled E2E suite against real Zammad 7.2.3 + Elasticsearch 9.5.5
./scripts/test-zammad-decoupled.sh --local

Ready to Connect Zammad to Your Zero-Trust Enterprise AI Pipeline?

Read the full Zammad Wiki documentation, try Zammad in our interactive pipeline simulator, or run the real Zammad 7.2 Compose stack locally.