Znuny Web Services – REST API

Znuny Web Services – REST API

In this detailed guide, you will learn how to activate, configure, and integrate the Znuny REST API (part of the Generic Interface) into your own applications.

1. Architecture & Basic Principles

Znuny provides its Generic Interface via REST and SOAP web services. The REST API communicates via HTTP(S) using the JSON data format and enables:

• Ticket Management: Create, retrieve, update, delete
• Article Management: Add articles, manage attachments
• History & Search: View ticket history and perform complex search queries

Important Note: A standard installation does not contain pre-configured web services – these must be created manually in the Admin area under “Processes & Automation → Web Services”.

2. Configuration

2.1 Activate Generic Interface

1. In the Admin area, navigate to SysConfig → GenericInterface.Transport and select REST (HTTP).
2. Under AdminGenericInterfaceTransportHTTPREST, configure timeouts, host headers, and debug levels.
3. In GenericInterface.Operation, define the desired operations (e.g., TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete, TicketHistoryGet) and activate them.

2.2 Base URL & Authentication

• Base URL TicketCreate
• Authentication
  • Znuny session cookies
  • API keys / tokens (configurable via SysConfig)
  • Always use HTTPS for secure transmissions!

3. Endpoints & HTTP Methods (Detailed Overview)

For each endpoint, you will find a detailed presentation of parameters, possible responses, and practical examples here.

3.1 TicketCreate (POST)

URL: /Webservice/<ServiceName>/TicketCreate Method: POST Description: Creates a new ticket and simultaneously creates an initial article.

Parameter	Type	Required	Description
SessionID	Integer	Yes¹	Session ID or UserLogin+Password
UserLogin	String	Yes²	Agent login (in combination with Password)
Password	String	Yes²	Password (in combination with UserLogin)
Ticket.Title	String	Yes	Subject of the ticket
Ticket.Queue	String	Yes	Queue name or Ticket.QueueID
Ticket.State	String	Yes	Initial state (e.g., new)
Ticket.Priority	String	Yes	Priority (e.g., 3 normal)
Ticket.CustomerUser	String	Yes	Customer email or login
Article.Subject	String	Yes	Subject of the first article
Article.Body	String	Yes	Content of the first article
Article.MimeType	String	Yes	text/plain or text/html

¹ Either SessionID OR UserLogin+Password required. ² If no SessionID token is present.

Example Request: TicketSearch

Example Response: TicketGet

3.2 TicketSearch (GET)

URL: /Webservice/<ServiceName>/TicketSearch Method: GET Description: Searches for tickets based on various filter criteria.

Parameter	Type	Required	Description
UserLogin, Password	String,String	Yes¹	Agent credentials or SessionID²
SessionID	Integer	Yes²	Token for authenticated sessions
Title	String/String[]	No	Wildcard search in title (%Order%)
TicketNumber	String/String[]	No	Ticket number(s)
QueueIDs	Integer[]	No	Queue IDs
States	String[]	No	States (new, open, …)
StateType	String/String[]	No	Open/Closed category
DynamicField_Name.Op	Mixed	No	Dynamic fields with operator (Equals, Like, GreaterThan …)

¹ Either UserLogin+Password OR SessionID. ² If no login pair is provided.

Example Request: TicketUpdate

Example Response: TicketDelete

3.3 TicketGet (GET)

URL: /Webservice/<ServiceName>/TicketGet Method: GET Description: Retrieves detailed ticket data including articles, attachments, and dynamic fields.

Parameter	Type	Required	Description
UserLogin, Password	String,String	Yes¹	Agent credentials or SessionID²
SessionID	Integer	Yes²	Token for authenticated sessions
TicketID	String/String[]	Yes	One or more ticket IDs (comma-separated or array)
DynamicFields	Boolean (0/1)	No	1 = Dynamic fields in result, default = 0
Extended	Boolean	No	1 = Extended metadata (e.g., FirstResponse)
AllArticles	Boolean	No	1 = Return all articles
ArticleLimit	Integer	No	Max. number of returned articles
Attachments	Boolean	No	1 = Embed attachments in Base64
GetAttachmentContents	Boolean	No	1 = Also load attachment contents
HTMLBodyAsAttachment	Boolean	No	1 = Attach HTML version of article as attachment

¹ Either UserLogin+Password OR SessionID. ² If no login pair is provided.

Example Request: TicketHistoryGet

Example Response (abbreviated): /Webservice/<ServiceName>/TicketCreate

3.4 TicketUpdate (PUT)

URL: /Webservice/<ServiceName>/TicketUpdate Method: PUT Description: Updates fields of an existing ticket and can optionally create a new article.

Parameter	Type	Required	Description
SessionID	Integer	Yes¹	Token or UserLogin+Password²
TicketID	Integer	Yes	ID of the ticket to be updated
Ticket.Title	String	No	New title
Ticket.State	String	No	New state
Ticket.Owner	String/ID	No	New owner
Ticket.PendingTime	Hash / Diff	No	New pending time
Article.Subject	String	No	Creates a new article
Article.Body	String	No	Content of the new article
DynamicField…	Array	No	Update dynamic fields
Attachment…	Array	No	Add new attachments

¹ Either SessionID OR UserLogin+Password. ² If no SessionID token is present.

Example Request: POST

Example Response: new

3.5 TicketDelete (DELETE)

URL: /Webservice/<ServiceName>/TicketDelete Method: DELETE Description: Permanently deletes one or more tickets.

Parameter	Type	Required	Description
SessionID	Integer	Yes¹	Token or UserLogin+Password²
TicketID	String/Array	Yes	One or more ticket IDs

Example Request: 3 normal

Example Response: text/plain

3.6 TicketHistoryGet (GET)

URL: /Webservice/<ServiceName>/TicketHistoryGet Method: GET Description: Retrieves the history of one or more tickets.

Parameter	Type	Required	Description
SessionID	Integer	Yes¹	Token or UserLogin+Password²
TicketID	String/Array	Yes	One or more ticket IDs

Example Request: text/html

4. Extension & Customization

4.1 WADL Definition

Define new resources in the WADL file: /Webservice/<ServiceName>/TicketSearch

4.2 YAML Import

Alternatively, you can define operations via YAML: GET

---

5. Error Handling & Logging

• Success indicator: Success: 0|1
• Error message: ErrorMessage in JSON
• Debugging: Set Debug-Level to Debug in the transport dialog → log entries become visible in the database

---

6. Use Cases

Scenario	Description
Cross-system automation	Create tickets from monitoring tools (Nagios, Zabbix)
Data synchronization	Batch updates of ticket fields from external CRM
Self-service portals	Customers create their own tickets via REST
Mobile apps	Native iOS/Android apps communicate via REST

---

Conclusion

The Znuny REST API is flexible, performant, and highly extensible thanks to the Generic Interface. Whether it’s simple ticket creation or complex workflow automation – with just a few steps in the Admin area and standard JSON requests, you can realize seamless integrations into any IT landscape.

---

7. Python Client: pyznuny

For Python developers, the official package pyznuny is available, which encapsulates the entire Znuny REST API in a simple, typed library. You do not need to formulate HTTP requests by hand – pyznuny handles authentication, session management, and the serialization of all parameters.

7.1 Installation

pip install pyznuny

7.2 Quick Start

from pyznuny import ZnunyClient

client = ZnunyClient(
    url="https://znuny.example.com",
    username="admin",
    password="secret"
)

# Create ticket
ticket_id = client.ticket_create(
    title="Server unreachable",
    queue="Support",
    state="new",
    priority="3 normal",
    customer_user="customer@example.com",
    article_subject="Initial report",
    article_body="The server has not been responding since 08:00 AM.",
    mime_type="text/plain"
)
print(f"New ticket created: #{ticket_id}")

# Retrieve ticket
ticket = client.ticket_get(ticket_id=ticket_id, all_articles=True)
print(ticket)

# Update ticket
client.ticket_update(ticket_id=ticket_id, state="open", owner="max.muster")

7.3 Supported Operations

Method	Description
ticket_create()	Create new ticket with first article
ticket_get()	Retrieve ticket details incl. articles & attachments
ticket_search()	Search tickets by filters
ticket_update()	Update fields, state, owner, and articles
ticket_delete()	Permanently delete ticket
ticket_history_get()	Load full history of a ticket

Note: pyznuny is available on PyPI and is actively maintained by Softoft.

---

8. OpenTicketAI Runtime & Znuny Connector

For those who want to not only use the Znuny REST API but intelligently automate it, the OpenTicketAI Runtime is the solution – an on-premise AI platform that classifies, prioritizes, and routes incoming tickets fully automatically.

8.1 System Architecture

                            ┌─────────────────────────┐
  Incoming Emails     ────► │   Znuny (Generic Interface / REST API)  │
                            └────────────┬────────────┘
                                         │  Webhook / Polling
                                         ▼
                            ┌─────────────────────────┐
                            │  OpenTicketAI Runtime   │
                            │  (Docker, On-Premise)   │
                            │  ┌───────────────────┐  │
                            │  │  AI Model (NLP)   │  │
                            │  └───────────────────┘  │
                            └────────────┬────────────┘
                                         │  otai-znuny-znuny Connector
                                         ▼
                            ┌─────────────────────────┐
                            │  Znuny REST API          │
                            │  TicketUpdate / Routing  │
                            └─────────────────────────┘

The runtime runs entirely locally in your data center – no ticket data leaves your infrastructure.

8.2 Installation of the Znuny Connector

Install the OpenTicketAI core library together with the Znuny-specific connector package otai-znuny-znuny:

pip install open-ticket-ai otai-hf-local otai-znuny-znuny

Package	Function
open-ticket-ai	OpenTicketAI core: orchestration, pipelines, config
otai-hf-local	Local AI models via Hugging Face (On-Premise)
otai-znuny-znuny	Connector: reads & writes tickets via Znuny REST

8.3 Configuration

Create a config.yaml and connect the runtime to your Znuny instance:

connector:
  type: znuny
  url: https://znuny.example.com
  username: otai-bot
  password: "${ZNUNY_PASSWORD}"

model:
  provider: hf-local
  model_name: softoft/ticket-classifier-de

routing:
  default_queue: "Unclassified"
  rules:
    - category: "Network"
      queue: "IT-Infrastructure"
      priority: "4 high"
    - category: "Billing"
      queue: "Accounting"
      priority: "3 normal"

8.4 Workflow of Automatic Ticket Processing

1. Ticket arrives in Znuny (via email or REST TicketCreate)
2. Connector polls for new tickets at the configured interval via TicketSearch
3. AI model analyzes subject and article text with Natural Language Processing
4. Classification result (category, priority, suggested queue) is determined
5. TicketUpdate via REST sets queue, priority, and optional internal article
6. Ticket lands fully automatically with the correct team – without manual triage

8.5 Advantages over Manual REST Integration

Feature	Manual REST Integration	OpenTicketAI + Connector
Classification	❌ Manual	✅ Fully automatic (AI)
Data protection	✅ Local	✅ 100% On-Premise
Rule-based routing	✅ Possible	✅ Included
Learning capability	❌ Rigid rules	✅ Model trainable
Setup effort	High	Low (YAML config)

Learn more: Visit openticketai.com or contact Softoft for an individual demo.