Ticket System Integration
Connect OTAI Runtime to OTOBO, Znuny, or Zammad via environment variables and the TicketSystemService adapter contract.
Ticket System Integration
OTAI Runtime v3 connects to one ticket system at a time. Select the connector with OTAI_TICKET_SYSTEM_TYPE and set the matching credentials as environment variables.
Environment variables
| Variable | Default | Description |
|---|---|---|
OTAI_TICKET_SYSTEM_TYPE | otobo | otobo, znuny, or zammad |
OTAI_OTOBO_BASE_URL | local GI URL | OTOBO Generic Interface base URL |
OTAI_OTOBO_USERNAME | open_ticket_ai | OTOBO API user |
OTAI_OTOBO_PASSWORD | — | OTOBO API password (required when type=otobo) |
OTAI_ZNUNY_BASE_URL | local GI URL | Znuny Generic Interface base URL |
OTAI_ZNUNY_USERNAME | open_ticket_ai | Znuny API user |
OTAI_ZNUNY_PASSWORD | — | Znuny API password (required when type=znuny) |
OTAI_ZAMMAD_BASE_URL | — | Zammad instance URL (required when type=zammad) |
OTAI_ZAMMAD_ACCESS_TOKEN | — | Zammad personal access token (required when type=zammad) |
OTOBO / Znuny
Use the Generic Interface REST webservice. Create user open_ticket_ai, import the restricted webservice YAML, and grant queue/priority/note permissions. See the OTOBO / Znuny setup guide for step-by-step instructions.
Zammad
Create a personal access token for a dedicated agent account with the permissions your workflows need (read tickets, change queue/priority, update custom fields). Set OTAI_ZAMMAD_BASE_URL to your instance root (for example https://helpdesk.example.com/).
TicketSystemService contract
All connectors implement TicketSystemService and return UnifiedTicket data:
find_tickets— search by criteriafind_first_ticket— return the first matchget_ticket— fetch one ticket by IDcreate_ticket— create a ticketupdate_ticket— update queue, priority, fieldsadd_note— add an internal or public note
Implementations live in the runtime package:
otobo/znuny— Generic Interface adapterzammad— Zammad REST API adapter
Workflow polling
The runtime polls the configured ticket system every OTAI_RUNNER_INTERVAL seconds (default 30) and runs active workflows (queue_classification, priority_classification, ticket_summary). Activate workflows via OTAI Studio or the REST API at http://localhost:8080/api/workflows/{name}.