OTOBO / Znuny Setup Guide

OTOBO / Znuny Setup Guide

Open Ticket AI connects to OTOBO/Znuny using a restricted WebService and a dedicated technical user. Follow these steps exactly to ensure the automation works reliably and securely.

1. Create the User open_ticket_ai

This user is used exclusively by the Open Ticket AI engine. It must not have admin permissions. It must have only exactly the permissions required for your automation.

Step 1: Go to Admin → Agents

Use the OTOBO Admin navigation:

Step 2: Click “Add Agent”

Fill in:

Generate a secure password

:::code-group

openssl rand -base64 32 | cut -c1-16

# PowerShell
-join ((33..126) | Get-Random -Count 16 | ForEach-Object {[char]$_})

:::

Step 3: Save the password as env var

Set the password as an environment variable for your ticket system type:

OTAI_OTOBO_PASSWORD=your_generated_password_here
# or for Znuny:
OTAI_ZNUNY_PASSWORD=your_generated_password_here

Never store this password inside Git. Use .env and server secret storage.

2. Assign Permissions (Agents ↔ Groups or Agents ↔ Roles)

Open Ticket AI can only perform actions that the user is allowed to do.

Depending on your active workflows, grant:

Option A — Assign via Groups (recommended)

Go to:

Admin → Agents ↔ Groups

Select the agent open_ticket_ai and give permissions like:

Add rw if you need to create tickets.

Option B — Assign via Roles (optional but scalable)

If your OTOBO uses Roles → Groups mapping, assign:

Admin → Agents ↔ Roles

Then ensure the Role has the required group permissions.

3. Ensure Queues, Priorities, and Fields Exist

Your workflows refer to specific queue and priority names configured in OTAI Studio, for example:

• Queues: “IT”, “Real Estate”, etc.
• Priorities: “3 Mittel”, “5 Kritisch”, etc.

You must manually confirm:

✅ Every queue name in your workflow config exists in OTOBO/Znuny ✅ Every priority your model predicts exists ✅ If you use note actions → agent has note permission ✅ Ticket types referenced in automation exist

If a name is wrong, the WebService update will fail.

4. Create the WebService “OpenTicketAI”

Go to:

Admin → Web Services

Step 1: Click “Add Web Service”

Then select Import Web Service.

Step 2: Import Webservice

Use the template shipped with Open Ticket AI:

Open Ticket AI yaml

Upload the file using the Import web service button.

This creates:

• /ticket-get
• /ticket-update
• /ticket-search
• /ticket-create

All restricted so only the user open_ticket_ai may use them.

5. Why the WebService Is Restricted

The YAML you import includes:

ValueMap:
  UserLogin:
    ValueMapRegEx:
      .*: open_ticket_ai

This forces every inbound request to authenticate as open_ticket_ai —even if an attacker sends arbitrary usernames.

This prevents:

• Password brute-force attacks
• API abuse
• Unauthorized ticket manipulation

With a 16-character random password, brute-force is impractical even under extreme load.

6. Verify WebService Is Active

After import, your list should show:

Look for:

✅ Name: OpenTicketAI ✅ Provider Transport: HTTP::REST ✅ Validity: valid ✅ Restricted to user open_ticket_ai

If not valid, edit → Save again.