Getting Started

Install the Znuny Python SDK and create your first ticket via the GenericInterface REST API.

Getting Started — Znuny Python SDK

Webservice required. pip install znuny alone is not enough. You must configure a GenericInterface REST webservice on your Znuny server before any API call works. Start with Webservice setup if you have not done this yet.

Install the distribution and import the Znuny-branded namespace:

pip install znuny

from znuny import ZnunyClient, BasicAuth, ClientConfig, TicketCreate, TicketOperation

Prerequisites

Znuny with GenericInterface enabled and a REST webservice configured.
An agent login with permission to use that webservice.
Python 3.11+.

If you do not have a webservice yet, follow Webservice setup first — run znuny-cli setup-system on your Znuny server.

Znuny admin concepts

Znuny term	Meaning for this SDK
Webservice	Named REST endpoint group; `ClientConfig.webservice_name` must match
Operation	One ticket action (create, get, search, update); mapped in `operation_url_map`
Agent login	User account passed to `BasicAuth` — needs webservice permission
Queue	Ticket inbox; use `IdName(name="Raw")` or your queue name in models
Dynamic field	Custom ticket attribute configured in Znuny; pass as `dict[str, str]` on models

You configure webservices under Admin → Web Services in the Znuny agent interface, or let znuny-cli setup-system create one for you. See Webservice setup for the full walkthrough.

Configuration

ClientConfig describes how the client reaches your Znuny webservice. Map each TicketOperation to the operation path segment defined in Znuny’s webservice configuration.

config = ClientConfig(
    base_url="https://your-znuny-server",
    webservice_name="PythonClientWebService",
    operation_url_map={
        TicketOperation.CREATE: "ticket-create",
        TicketOperation.GET: "ticket-get",
        TicketOperation.SEARCH: "ticket-search",
        TicketOperation.UPDATE: "ticket-update",
    },
)

client = ZnunyClient(config)
client.login(BasicAuth(user_login="agent1", password="secret"))

Request URLs follow the standard Znuny/OTRS GenericInterface pattern:

{base_url}/Webservice/{webservice_name}/{operation_path}

Create a ticket

import asyncio

from znuny import Article, IdName, TicketCreate


async def main() -> None:
    ticket = TicketCreate(
        title="New request",
        queue=IdName(name="Raw"),
        article=Article(subject="Hello", body="Ticket body"),
    )
    async with client:
        created = await client.create_ticket(ticket)
        print(created.id)


asyncio.run(main())

CLI setup

On your Znuny application server:

znuny-cli setup-system

The wizard uses Znuny’s otrs.Console.pl console by default.