Webservice Setup

Configure a Znuny GenericInterface REST webservice before using the Python SDK — required for all API calls.

Webservice setup — Znuny

The Python SDK cannot talk to Znuny until a GenericInterface REST webservice exists.
pip install znuny only installs the client library. Every ZnunyClient call goes through URLs like:

https://your-znuny-server/Webservice/{webservice_name}/{operation_path}

If no webservice is configured, you will see HTTP 404 errors, authentication failures, or GenericInterface error responses — not Python import errors.

What you need before writing Python code

The SDK ships a setup wizard that creates all of this for you. Manual configuration in the Znuny admin UI is also possible.

Recommended: znuny-cli setup-system

Run this on the Znuny application server (or a machine with shell access to it and the Znuny console).

1. Install the package

pip install znuny

2. Start the wizard

znuny-cli setup-system

The CLI auto-detects Znuny at common paths (/opt/znuny/bin/otrs.Console.pl) or in Docker containers named znuny-web-1 / znuny_web_1.

If detection fails, run the command directly on the Znuny host where the console binary exists.

3. Create an API user (recommended)

The wizard asks whether to create a dedicated user. Choose yes unless you already have an agent account reserved for integrations.

Store the password securely (environment variable or secret manager). Never commit it to git.

4. Configure the webservice

The wizard generates a GenericInterface YAML file and imports it via:

otrs.Console.pl Admin::WebService::Add --name <name> --source-path <file.yml>

5. Default operation paths

When you use the CLI wizard with default settings, map operations in Python like this:

These path names must match exactly what is configured in the webservice. If you chose different names during setup, use those names instead.

6. Connect the SDK

from znuny import ZnunyClient, BasicAuth, ClientConfig, TicketOperation

client = ZnunyClient(
    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.login(BasicAuth(user_login="python-client-user", password="YOUR_PASSWORD"))

Replace base_url with your public Znuny URL (no trailing slash). Use the webservice name and paths from your setup.

Manual setup in the Znuny admin UI

Use this when you cannot run the CLI on the server, or when you need to attach the SDK to an existing webservice.

Step 1 — Open web services

1. Log in to Znuny as an administrator.
2. Go to Admin → Web Services.
3. Click Add web service.

Step 2 — Provider configuration

1. Set Name to the value you will use in ClientConfig.webservice_name (for example PythonClientWebService).
2. Set Type to Provider (incoming REST requests from your Python app).
3. Under Transport, choose HTTP::REST.

Step 3 — Add provider operations

Add one operation per SDK method. Use these backend operation types and route paths:

Enable Include ticket data for each operation (the SDK expects full ticket payloads).

Map the route for each operation in the transport RouteOperationMapping section so the URL path matches the operation name.

Step 4 — Agent permissions

Ensure the agent account you pass to BasicAuth:

• Can log in to Znuny.
• Has read/write access to the queues you create tickets in.
• Is allowed to use the webservice (if you configured user restriction on the webservice).

Step 5 — Save and test

Save the webservice. Test with curl before switching to Python:

curl -X GET "https://your-znuny-server/Webservice/PythonClientWebService/ticket-get?UserLogin=python-client-user&Password=YOUR_PASSWORD&TicketID=1"

Adjust query parameters to match your webservice mapping. A valid response (or a structured GenericInterface error) confirms the endpoint is reachable.

Manual import via console (YAML)

If you have a webservice YAML file (for example exported from another system or generated by the CLI), import it on the Znuny server:

/opt/znuny/bin/otrs.Console.pl Admin::WebService::Add \
  --name PythonClientWebService \
  --source-path /path/to/webservice.yml

Place the YAML under /opt/znuny/var/webservices/ if your installation expects files there.

Troubleshooting

Next steps

Once the webservice responds, continue with Getting started and Working with tickets.