Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pipeshub.com/llms.txt

Use this file to discover all available pages before exploring further.

Zammad Logo

​
Zammad

Open-source helpdesk and ticketing system

✅ Ready📖 Documentation Available

​
Overview

Zammad is an open-source, web-based helpdesk and customer support ticketing system. It provides a unified interface for managing customer communications across multiple channels including email, chat, telephone, and social media, making it ideal for support teams of all sizes.

​
Zammad Data Structure

The connector understands Zammad’s hierarchical data model:
  • Users (customers and agents with role assignments)
  • Groups (support teams/departments)
    • Tickets (with articles and attachments)
  • Roles (permission sets assigned to users)
  • Knowledge Base
    • Categories (hierarchical structure)
    • Answers (articles with translations and attachments)

​
What Gets Synced

The connector indexes the following content for AI-powered search:
Content TypeDetails
TicketsTitle, state, priority, group, owner, customer, articles (messages/replies), attachments
Knowledge BaseCategories, answers/articles with translations, and associated attachments
UsersCustomer and agent profiles with emails and roles
GroupsSupport team/department information
RolesUser roles and permission assignments
PermissionsGroup-based access controls for tickets, role-based access controls for knowledge base

​
Configuration Guide

The Zammad connector uses API Access Token authentication (HTTP Token Authentication) — the recommended method by Zammad for external integrations.
API operations performed with the token inherit the same permissions as the user who generated it. For full access to all tickets and data, generate the token from an admin user account.

​
Step 1: Access User Profile in Zammad

  1. Log in to your Zammad instance with an account that has administrator privileges.
  2. Click on your user avatar in the bottom left corner of the Zammad interface.
  3. Select Profile from the dropdown menu.
Zammad Profile Settings Access
The API token will have the same permissions as the user who creates it. For full access to all tickets and API endpoints, generate the token from an admin user account.

​
Step 2: Navigate to Token Access

  1. In the profile settings page, locate the Token Access tab.
  2. Click on it to open the Personal Access Tokens section.
  3. You’ll see a list of any existing tokens (if previously created).
Zammad Token Access Tab

​
Step 3: Create a new API token

  1. Click the Create button to generate a new token.
  2. Fill in the token configuration:
    FieldDescriptionRecommendation
    NameA descriptive identifier for the tokenUse something like PipesHub-Integration
    Expiry DateExpiration date for securityset based on your security policy
  3. Enable the following Permissions for the token:
    PermissionDescription
    ticket.agentAccess tickets as agent based on group access
    ticket.customerAccess tickets as customer
    knowledge_base.editorAccess the knowledge base editor features
    knowledge_base.readerAccess the knowledge base reader features
  4. Click Create (or Save) to generate the token.
Create New API Token
Create New API Token

​
Step 4: Copy the API token

CRITICAL: The API token is displayed immediately and only once. You must copy it now — it cannot be retrieved later. If you lose the token, you’ll need to create a new one.
  1. After clicking Create, the token is displayed in a dialog or on screen.
  2. Immediately copy the token to a secure location.
  3. Store it temporarily until you complete the PipesHub configuration.
Copy API Token

​
Step 5: Authenticate Instance tab — enter credentials

The connector drawer in PipesHub has three tabs: Authenticate Instance, Authorize, and Configure Records. Start on the Authenticate Instance tab.
  1. In PipesHub, go to Workspace Settings → Connectors, find Zammad, and click + Setup for a new instance.
  2. The connector panel opens as a right-side drawer. On the Authenticate Instance tab, enter:
    • Zammad URL — your Zammad instance base URL (e.g., https://support.yourcompany.com; no trailing slash)
    • API Token — the token you copied in Step 4
  3. Click Next. PipesHub validates the credentials and advances directly to the Configure Records tab (the Authorize tab is skipped because API Token authenticates on its own).
Authenticate Instance tab — enter Zammad URL and API Token
Generate the API token from a Zammad account that uses the same email address as your PipesHub account. Using a different email will cause permission issues on the PipesHub platform.
The Zammad URL must not include a trailing slash. Use https://support.yourcompany.com, not https://support.yourcompany.com/.

​
Step 6: Configure Records tab — sync settings, filters, and indexing

On the Configure Records tab, control how the connector syncs and what gets synced. Sync settings — configure your synchronization preferences first:
  1. Sync Strategy — Scheduled or Manual.
  2. Sync Interval — how often to sync (default: 60 minutes).
Configure Sync Settings
Scheduled sync runs automatically at the specified intervals. Manual sync requires you to trigger synchronization on-demand.
Sync filters — determine which content is downloaded from Zammad. Data excluded by sync filters is never downloaded.
Zammad Sync Filters
Available sync filters:
  1. Enable Manual Indexing — control indexing trigger method.
    • Enabled: records are indexed only when you manually trigger it.
    • Disabled (default): records are indexed automatically after sync.
  2. Groups — filter tickets by support group/department.
    • Operator: In (include only) or Not In (exclude)
    • Selection: searchable dropdown of your Zammad groups
    • Leave empty to sync all groups.
  3. Modified Date — filter by last modification date. Operators: Is After, Is Before, Is Between.
  4. Created Date — filter by creation date. Same operators.
Indexing filters — control what synced data gets processed for AI search.
  • Index Tickets (default: enabled) — include ticket content in search
  • Index Attachments (default: enabled) — include file attachments in search
  • Index Knowledge Base (default: enabled) — include knowledge base articles in search
Click Save to save your configuration. PipesHub confirms the instance is ready with a final dialog — “Instance is configured and ready to sync” — offering two choices: I’ll do it later or Start syncing now.
Instance is configured and ready to sync — I'll do it later or Start syncing now
Choose Start syncing now to kick off the initial sync immediately, or I’ll do it later to enable the connector without an immediate sync. Monitor the Indexing Progress to track sync completion.

​
Supported Features

The Zammad connector provides:
  • Full content sync — Tickets, knowledge base, attachments, users, and groups
  • Incremental sync — only fetches changes since last sync using updated_at timestamps
  • Batch processing — fetches data in optimized batches for performance
  • Permission preservation — respects group-based access controls
  • Attachment handling — syncs file attachments from ticket articles
  • Knowledge Base sync — syncs categories and answers with translations

​
Permission Model

Zammad uses different permission models for different content types:
  • Tickets: Group-based access controls. Users can only access tickets in their assigned groups.
  • Knowledge Base: Role-based access controls. Access to knowledge base content is determined by user roles.
The connector preserves these permissions:
  • Group assignments determine which agents can view synced tickets in PipesHub.
  • Internal articles respect the internal/public visibility flag.

​
Troubleshooting

​
Common Issues

Invalid API token error:
  • Verify the API token was copied correctly without extra spaces
  • Check that the token has not expired (if expiry date was set)
  • Ensure the token was not revoked in Zammad
  • Generate a new token if the current one is compromised or lost
Connection refused or timeout:
  • Verify the Zammad URL is correct and accessible
  • Check that your Zammad instance is running and reachable from PipesHub
  • Ensure there are no firewall rules blocking the connection
  • Verify SSL/TLS certificates are valid (for HTTPS connections)
Insufficient permissions error:
  • The API token inherits the creating user’s permissions
  • Use an admin user’s token for full API access
  • Check that the user account is active and not locked
  • Verify the user has access to the required groups
No data syncing:
  • Verify the connector status shows “Active”
  • Check that tickets exist in Zammad within your filter criteria
  • Ensure the API token user has access to the groups being synced
  • Review sync logs for specific error messages
Missing tickets:
  • Verify group filters aren’t excluding the desired content
  • Check that the API token user has access to those groups
  • Ensure ticket state filters aren’t excluding tickets
  • Verify date filters aren’t too restrictive
If you regenerate or revoke the API token in Zammad, you must update the configuration in PipesHub with the new token value.

​
Connector Workflow

The Zammad connector follows a structured synchronization process to ensure all data is accurately synced and permissions are properly maintained.

​
Sync Order

The connector syncs data in the following order:
  1. Users → Sync all Zammad users with their profiles and emails
  2. Groups → Sync support groups/departments (creates both RecordGroups and UserGroups for permissions)
  3. Roles → Sync user roles for knowledge base access controls
  4. Tickets → Sync tickets per group with articles and attachments
  5. Knowledge Base → Sync categories and answers with translations

​
Full Sync vs Incremental Sync

Full Sync occurs when:
  • First-time synchronization
  • Manual full sync is triggered
Incremental Sync occurs when:
  • Previous sync completed successfully
  • Only fetches content modified since last sync
  • Uses updated_at timestamps for change detection

​
What Gets Processed

Tickets: Number, title, state, priority, group assignment, owner, customer, all articles (messages, replies, notes), attachmentsKnowledge Base: Categories hierarchy, answers/articles with full content and translations, associated attachmentsAttachments: Files attached to ticket articles and knowledge base answers

​
FAQ

The initial sync duration depends on several factors:
  • Instance size: Number of tickets and knowledge base articles
  • Network latency: Connection speed to your Zammad instance
  • Content complexity: Tickets with many attachments take longer
Tips to speed up initial sync:
  • Use group filters to sync only the groups you need
  • Use date filters to exclude old tickets
The following permissions must be enabled when creating the API token:
  • ticket.agent - Access the tickets as agent based on group access
  • ticket.customer - Access tickets as customer
  • knowledge_base.editor - Access the knowledge base editor features
  • knowledge_base.reader - Access the knowledge base reader features
Yes. Use the Groups filter to specify which groups to include or exclude:
  • Include specific groups: Set Operator to In and select the groups
  • Exclude specific groups: Set Operator to Not In and select the groups to exclude
There are three common causes:
  1. Email mismatch - The email used during connector authentication doesn’t match your PipesHub account email. This causes permission issues preventing you from accessing synced data.
    • Fix: Reconfigure the connector and authenticate using the same email as your PipesHub account.
  2. Records show in “All Records” but not in search - Documents display in the All Records section but don’t appear in search query results.
    • Fix: Verify sync filters in the connector settings and ensure indexing has completed. Check that the data matches your search query criteria.
  3. Data not yet indexed - The connector is still syncing or hasn’t completed the initial indexing process.
    • Fix: Go to Workspace Settings → Connectors, check the sync status, and wait for indexing to complete.

​
Ready to Get Started?

Connect your Zammad helpdesk to PipesHub in just a few minutes. Follow the step-by-step guide above to enable organization-wide support ticket search across all your Zammad content.