GenericTicketConnectorREST

GenericTicketConnectorREST#

This document explains how to install the Ready2Adopt GenericTicketConnectorREST web service and how to use it, including calling it as a customer user rather than an agent. The GenericTicketConnectorREST provides RESTful API endpoints to interact with tickets and sessions.

Installing The Web Service#

The web service definition ships with every Znuny installation, ready to import, at:

var/webservices/examples/GenericTicketConnectorREST.yml

To import it through the admin interface, follow Web Service Quick Start (Ready2Adopt) and pick GenericTicketConnectorREST from the template list. No further transport configuration is required afterwards; the file already wires every operation below to a REST route.

To import it from the command line instead, which is easier to repeat across environments:

bin/znuny.Console.pl Admin::WebService::Add \
  --name GenericTicketConnectorREST \
  --source-path var/webservices/examples/GenericTicketConnectorREST.yml

Run bin/znuny.Console.pl Admin::WebService::Add --help for all options, and see Command Line Interface for general console usage.

Default Operations:

SessionCreate: Create a Session
SessionDelete: Delete a Session
SessionGet: Retrieve Session Data
TicketCreate: Create a Ticket
TicketGet: Retrieve Ticket Data
TicketHistoryGet: Retrieve Ticket History
TicketSearch: Search for Tickets
TicketUpdate: Update a Ticket

Note

All examples assume that the web service is hosted at http://localhost/znuny/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/.

You may need to adjust the URL based on your Znuny installation and configuration.

Calling It As A Customer User#

Every operation below accepts one of two ways to authenticate: pass UserLogin/CustomerUserLogin and Password on each call, or create a session once with SessionCreate and reuse the returned SessionID. This works the same way for a customer as it does for an agent - the difference is only which login field you send, and it is the same account the customer already uses to sign in to the customer portal, nothing separate to provision.

Once authenticated as a customer, three things follow automatically, without any extra parameters:

TicketSearch only ever returns tickets that customer owns, even with no filters at all.
TicketGet returns TicketGet.AccessDenied if the ticket belongs to a different customer.
TicketCreate and TicketUpdate also accept a customer session; the ticket is written under the system’s configured CustomerPanelUserID, while permission checks still apply against the calling customer.

Not every operation is available to a customer. TicketHistoryGet rejects a customer session outright with TicketHistoryGet: User needs to an Agent! - use an agent login for that one.

Caution

SessionGet returns the full session record for whichever account is logged in. For a customer session this includes the hashed password (UserPassword) and the complete customer/company field mapping; for an agent session the password hash is filtered out. Treat access to that operation the same way you would treat access to the login credentials themselves, and do not expose it to end users beyond what an integration genuinely needs.

SessionCreate#

Create a Session for use with other operations. Provide either UserLogin (agent) or CustomerUserLogin (customer) together with Password.

Example Request (customer):

POST /znuny/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Session HTTP/1.1
Host: localhost
Content-Type: application/json
Accept: application/json

{
    "CustomerUserLogin": "customer_login",
    "Password": "customer_password"
}

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "SessionID": "your_session_id"
}

An agent session is created the same way, with UserLogin in place of CustomerUserLogin.

SessionDelete#

Delete a Session

Example Request:

DELETE /znuny/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Session/<your_session_id> HTTP/1.1
Host: localhost
Content-Type: application/json
Accept: application/json

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "Success": 1
}

SessionGet#

Retrieve Session Data. See the caution note above before exposing this operation to anything but a trusted backend.

Example Request:

GET /znuny/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Session/<your_session_id> HTTP/1.1
Host: localhost
Accept: application/json

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "SessionData": [
        {
            "Key": "UserLogin",
            "Value": "customer_login"
        },
        {
            "Key": "UserType",
            "Value": "Customer"
        }
        // Full session record: name/address fields, UserPassword (hashed),
        // company config, timestamps, and everything else Znuny attaches
        // to that session
    ]
}

TicketCreate#

Create a Ticket. A customer session may call this too; the ticket is then created under the system’s configured CustomerPanelUserID rather than the customer’s own agent-side user.

Example Request:

POST /znuny/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Ticket HTTP/1.1
Host: localhost
Content-Type: application/json
Accept: application/json

{
    "UserLogin": "admin",
    "Password": "admin_password",
    "Ticket":
        {
            "Queue": "Postmaster",
            "StateID": "1",
            "OwnerID": "1",
            "TypeID": "1",
            "PriorityID": "3",
            "Title": "Test",
            "CustomerUser": "user@example.com",
            "Lock": "unlock"
        },
    "Article": {
        "CommunicationChannel": "Internal",
        "SenderType": "agent",
        "Subject": "Initial Request",
        "Body": "Test Body",
        "From": "user@example.com",
        "To": "user@znuny.exapmle.com",
        "VisibleForCustomer": "0",
        "ContentType": "text/plain; charset=utf8"
    }
}

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "TicketID": "1",
    "TicketNumber": "2025000001",
    "ArticleID": "1"
}

TicketGet#

Retrieve Ticket Data

Example Request:

GET /znuny/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Ticket/<ticket_id>?SessionID=<your_session_id> HTTP/1.1
Host: localhost
Accept: application/json

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Ticket": [
    {
      "TicketID": 1,
      "TicketNumber": "2025000001",
      "Title": "Test",
      "State": "new",
      "StateType": "new",
      "Queue": "Postmaster",
      "Priority": "3 normal",
      "Owner": "admin",
      "CustomerID": "",
      "CustomerUserID": "user@example.com",
      "Created": "2025-09-11 05:52:20",
      "Changed": "2025-09-16 14:08:17",
      "Age": 1052507
      // ...remaining ticket fields
    }
  ]
}

Requesting a ticket that does not belong to the calling customer, when authenticated as a customer, returns an error instead of ticket data:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "Error": {
        "ErrorCode": "TicketGet.AccessDenied",
        "ErrorMessage": "TicketGet: User does not have access to the ticket!"
    }
}

TicketHistoryGet#

Retrieve Ticket History. Agent login required - a customer session is rejected with TicketHistoryGet: User needs to an Agent!, regardless of whether the customer owns the ticket.

Example Request:

GET /znuny/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Ticket/History/<ticket_id>?SessionID=<your_session_id> HTTP/1.1
Host: localhost
Accept: application/json

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "History": [
        {
            "HistoryType": "ArticleCreate",
            "CreateBy": 1,
            "Created": "2025-09-11 05:52:20",
            "Content": "Article (ID=456) created.",
            "UserID": 1,
            "UserLogin": "admin"
        },
        {
            "HistoryType": "StateUpdate",
            "CreateBy": 1,
            "Created": "2025-09-11 06:00:00",
            "Content": "State changed from 'new' to 'open'.",
            "UserID": 1,
            "UserLogin": "admin"
        }
    ]
}

TicketSearch#

Search for Tickets. Called with a customer session, results are always limited to that customer’s own tickets, whether or not any filters are given.

Example Request:

POST /znuny/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Ticket/Search  HTTP/1.1
Host: localhost
Accept: application/json

{
    "SessionID": "<your_session_id>"
}

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "TicketID": [
        "1",
        "4",
        "7"
    ]
}

Add any of the usual search fields (States, Queues, Priorities, TicketCreateTimeNewerDate, DynamicField_*, and so on) to narrow the result. They combine with the automatic customer scope; they never widen past it.

TicketUpdate#

Update a Ticket. A customer session may call this too, subject to the same ownership check as TicketGet.

Example Request:

PATCH /znuny/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Ticket/<ticket_id> HTTP/1.1
Host: localhost
Content-Type: application/json
Accept: application/json

{
    "SessionID": "<your_session_id>",
    "Ticket":
        {
            "StateID": "2",
            "PriorityID": "2",
            "OwnerID": "2",
            "Title": "Updated Test Title"
        }
}

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "TicketID": "1",
    "TicketNumber": "2025000001"
}

Common Errors#

Every operation returns its own <Operation>.AuthFail and, where an ownership check applies, <Operation>.AccessDenied - the prefix always names the call that failed, which is useful when logging integration errors.

Situation	ErrorCode	ErrorMessage
Wrong login or password	`SessionCreate.AuthFail`	Authorization failing!
Expired or invalid SessionID	`<Operation>.AuthFail` (`SessionGet.SessionInvalid` for SessionGet)	Authorization failing!
Ticket belongs to a different customer	`TicketGet.AccessDenied` / `TicketUpdate.AccessDenied`	User does not have access to the ticket!
Customer session calling an agent-only operation	`TicketHistoryGet.AuthFail`	User needs to an Agent!

Note

A SessionID follows the normal Znuny session timeout (SessionMaxTime / SessionMaxIdleTime), the same clock a browser login runs on. An integration that runs longer than that should call SessionCreate again rather than assume a SessionID is permanent.

Always call this web service over HTTPS in production - credentials and SessionID travel in plain request bodies and query strings.

GenericTicketConnectorREST

Contents

GenericTicketConnectorREST#

Installing The Web Service#

Calling It As A Customer User#

SessionCreate#

SessionDelete#

SessionGet#

TicketCreate#

TicketGet#

TicketHistoryGet#

TicketSearch#

TicketUpdate#

Common Errors#