CLAIA Zammad Extension

A CLAIA extension providing tool modules for Zammad helpdesk integration, including ticket management and AI-assisted processing workflows.

• Website: https://claia.dev
• License: Apache-2.0
• Python: 3.12+

Overview

This extension adds two tool modules to CLAIA for interacting with Zammad:

• zammad - Basic commands for listing, viewing, and managing tickets
• zammad_processes - AI-assisted workflows for tagging and account processing

Installation

From Source

# Clone the repository
git clone https://gitlab.com/exofox/claia/claia-zammad.git
cd claia-zammad

# Create virtual environment
python -m venv .venv
. .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -U pip
pip install -e .

From PyPI

pip install claia-zammad

Configuration

This extension requires the following configuration in your CLAIA settings:

• zammad_api_token - Your Zammad API token
• zammad_base_url - Your Zammad instance URL (e.g., https://example.zammad.com)
• files_directory - Directory for file operations

Usage

After installation, the Zammad tool modules will be automatically registered in CLAIA.

Basic Commands (zammad module)

# List open tickets
:zammad list

# List tickets with a specific query
:zammad list query=my-tickets

# Get ticket details
:zammad details ticket_id=123

# Add a tag to a ticket
:zammad tag_add ticket_id=123 tag=urgent

# Remove a tag from a ticket
:zammad tag_remove ticket_id=123 tag=resolved

# Find tickets by subject
:zammad find_subject subject="password reset"

# Delete tickets by subject (requires confirmation)
:zammad delete_subject subject="test ticket" confirm=true

Process Commands (zammad_processes module)

# Process a single ticket with AI tagging
:zammad_processes process_single ticket_id=123

# Remove AI tags from a ticket
:zammad_processes untag_single ticket_id=123

# Batch process untagged tickets
:zammad_processes process_tag limit=10

# Remove AI tags from all tagged tickets
:zammad_processes process_untag limit=10

# Process account management tickets
:zammad_processes process_account output_file=accounts.txt limit=5

# Process a single account ticket
:zammad_processes process_account_single ticket_id=456

Project Structure

claia-zammad/
├── src/
│   └── zammad/
│       ├── __init__.py
│       ├── api.py              # Zammad API client
│       ├── constants.py        # Queries and prompt templates
│       ├── plugin_basic.py     # Basic commands module
│       ├── plugin_processes.py # Process workflows module
│       ├── utils.py            # Formatting and AI utilities
│       └── README.md           # Module documentation
├── pyproject.toml              # Project config & entry points
├── deploy.sh                   # Deployment script
├── LICENSE
├── NOTICE
└── README.md

Module Details

API Client (api.py)

The ZammadAPI class provides HTTP-based access to Zammad:

• Ticket CRUD operations
• Article retrieval
• Tag management
• Search functionality

Utilities (utils.py)

The ZammadUtils class handles:

• Ticket formatting for display
• AI-assisted tagging workflows
• Account processing pipelines

Constants (constants.py)

Defines:

• Predefined ticket queries (open, closed, tagged, etc.)
• AI prompt templates for tagging and account processing

Building and Distribution

Build Wheel

pip install build
python -m build

# Or use the deploy script
./deploy.sh --build-whl

Build Debian Package

./deploy.sh --build-deb

Related Projects

• CLAIA Website
• CLAIA - The main CLAIA framework
• CLAIA Extension Template - Template for creating extensions

Support

• Documentation: https://claia.dev
• Issues: https://gitlab.com/exofox/claia/claia-zammad/-/issues
• Main Project: https://gitlab.com/exofox/claia/claia

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.