Ticket System Integration

Connect OTAI Runtime to OTOBO, Znuny, or Zammad using environment variables and the TicketSystemService contract.

Ticket System Integration

OTAI Runtime v3 connects to one ticket system at a time. Select the connector using OTAI_TICKET_SYSTEM_TYPE and set credentials via 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 (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 (type=znuny)
`OTAI_ZAMMAD_BASE_URL`	—	Zammad instance URL (type=zammad)
`OTAI_ZAMMAD_ACCESS_TOKEN`	—	Zammad access token (type=zammad)

OTOBO / Znuny

Use the Generic Interface REST webservice. Create user open_ticket_ai, import the webservice YAML, and assign permissions. See the OTOBO / Znuny setup guide.

Zammad

Create a personal access token for a dedicated agent account with required permissions (read tickets, change group/priority, update custom fields). Set OTAI_ZAMMAD_BASE_URL to your instance root (e.g. https://helpdesk.example.com/).

TicketSystemService contract

All connectors implement TicketSystemService and return UnifiedTicket data:

find_tickets — search by criteria
find_first_ticket — return first match
get_ticket — fetch ticket by ID
create_ticket — create a ticket
update_ticket — update queue/group, priority, fields
add_note — add internal or public note

Implementations:

otobo / znuny — Generic Interface adapter
zammad — Zammad REST API adapter

Workflow polling

The runtime polls the ticket system every OTAI_RUNNER_INTERVAL seconds (default 30) and runs active workflows (queue_classification, priority_classification, ticket_summary). Enable workflows via OTAI Studio or the REST API at http://localhost:8080/api/workflows/{name}.