Skip to content
Znuny Logo Znuny Community Docs

Znuny Web Services - REST API

Introduction to external interface integration

Section titled “Introduction to external interface integration”

In a globally connected digital environment, ticket systems must be able to react automatically to requests from other systems while simultaneously sending data or requests to external services. Znuny, the powerful open-source ticket system, addresses this requirement with its Generic Interface. It allows administrators to configure web services for a wide variety of tasks, even without extensive programming knowledge. Znuny supports communication via REST and SOAP protocols and enables seamless integration with:

  • CRM systems
  • Project management tools
  • Document management systems
  • and many other applications A web service acts as a bridge between Znuny and external systems. In this process, Operations and Invokers define the direction of communication, while Mapping and Transport determine how data is transmitted and interpreted. With Znuny, you can configure web services to execute internal actions, initiate requests on remote systems, manage data conversions between systems, and define the communication protocol. Access to the Web Services is located in the Web Services module within the Processes & Automation group. A fresh installation of Znuny does not contain any pre-configured web services by default. The following documentation illustrates how web services can be created, edited, deleted, cloned, exported, and imported, as well as the use of the debugger tool.

Implementation of interfaces

Section titled “Implementation of interfaces”

The implementation of web services in Znuny enables a flexible and dynamic integration of your business processes with numerous external tools and systems. By creating and using these services, efficiency is increased by reducing manual intervention and shortening response times to customer inquiries. Furthermore, the versatility of the Generic Interface ensures that Znuny is almost infinitely extensible and thus fits perfectly into existing IT landscapes.

Security and configuration

Section titled “Security and configuration”

When configuring and securing web services, it should be noted that all saved passwords are exported in plain text during an export. The storage and handling of passwords should therefore be treated with special care. For detailed information on system-internal configuration, such as the configuration options for Cache and Frontend modules, we recommend consulting the official Znuny system configuration documentation.

Documentation of connections

Section titled “Documentation of connections”

In an increasingly digitized operating environment, web services offer the possibility to link Znuny with other systems and services. Ensuring efficient and secure communication therefore means configuring web service settings precisely in advance. In the following, the basics of the settings for web services in Znuny are explained in more detail to provide you with a comprehensive guide.

General interface settings

Section titled “General interface settings”
  • Name*
    • The name uniquely identifies the web service within Znuny. It is important to choose a clear and descriptive name that reflects the function or the partner being interacted with.
  • Description
    • An extended comment that details the purpose and functionality of the web service. This improves clarity and maintainability.
  • Remote system
    • Allows you to specify the name of the external system with which Znuny interacts.
  • Debug threshold
    • Choose how detailed the logging of the communication should be. The settings range from Debug (most detailed logging) to Error (only error messages).
  • Validity
    • Determines whether the web service is activated (valid) or deactivated (invalid, temporarily invalid). Only valid web services are executed by Znuny.

Network transport - SOAP or REST

Section titled “Network transport - SOAP or REST”

Different protocols are available for implementing integration with other systems. The choice of network transport is fundamental here:

  • Network transport
    • Choose between HTTP::REST and HTTP::SOAP. These protocols define how data transmission occurs between the Znuny ticket system and the connected system.
  • Add operation
    • Allows you to define specific actions, so-called operations, for the web service. You can choose from a variety of predefined operations, such as Ticket::TicketCreate for creating tickets.

Creating a ticket via REST

Section titled “Creating a ticket via REST”

A practical example illustrates the value of web services in Znuny. The Ticket::TicketCreate operation can be set up via the HTTP::REST protocol. The defined routes allow external systems to create tickets in Znuny using HTTP-POST requests. This realizes new dimensions of automation and integration, which can significantly increase process efficiency and customer satisfaction.

Security note

Section titled “Security note”

Please note that passwords can be exported in plain text when exporting web service settings. It is therefore essential to handle sensitive information in a protected manner and to observe security regulations. The effective use of web services in Znuny allows companies to make their workflows more intelligent and agile. Through the precise configuration of web service settings, a solid foundation is created that allows Znuny to be seamlessly integrated into a company’s digital ecosystem.

Web service settings and operations in Znuny

Section titled “Web service settings and operations in Znuny”

The integration of external systems with Znuny via web services is an essential component for ensuring efficient ticket management. This integration is made possible by defining various operations that can execute specific actions within the ticket lifecycle. A key part of this integration is understanding the necessary attributes for each operation as well as using standards for data transmission.

Required attributes for interface operations

Section titled “Required attributes for interface operations”

Specific attributes are required for the basic ticket operations in Znuny. The most important operations include:

  • TicketCreate: Creates a new ticket with an associated article
  • TicketGet: Retrieves detailed information about one or more tickets
  • TicketUpdate: Updates existing ticket data
  • TicketSearch: Searches for tickets based on defined criteria
  • TicketHistoryGet: Retrieves the history of a ticket These operations allow developers to perform adjustments precisely and ensure that all requests contain the necessary information to be processed successfully.

Using XSLT for data transmission

Section titled “Using XSLT for data transmission”

XSLT transformation is a powerful technique for converting incoming data from web service requests into a form that Znuny can process. By, for example, creating a dynamic field “RemoteTicketID” for tickets, you can efficiently save and further process incoming data: Operations This example shows how you can transform the value of the incoming attribute incidentID into a ticket dynamic field named RemoteTicketID.

Web service settings: Requester

Section titled “Web service settings: Requester”

For the implementation of web service procedures as a requester, Znuny offers the choice between the protocols HTTP::REST and HTTP::SOAP. The selection of the network transport is elementary here to ensure a proper connection with the external system. After selecting the transport, the configuration must be saved and adjusted according to specific requirements. Setting up an error handling module is also an important step to guarantee robust communication. Znuny allows specific modules to be implemented and configured for this purpose.

Summary and next steps

Section titled “Summary and next steps”

By providing a versatile and configurable API for web services, Znuny opens up a world of possibilities for the integration and automation of ticket management processes. By providing precise specifications and using standards like XSLT for data manipulation, Znuny offers its users a flexible basis for expanding their ticketing systems in line with their specific business requirements. Whether as a provider or requester, the precise handling of web service settings ensures seamless and efficient communication with external systems and services.

Section titled “By providing a versatile and configurable API for web services, Znuny opens up a world of possibilities for the integration and automation of ticket management processes. By providing precise specifications and using standards like XSLT for data manipulation, Znuny offers its users a flexible basis for expanding their ticketing systems in line with their specific business requirements. Whether as a provider or requester, the precise handling of web service settings ensures seamless and efficient communication with external systems and services.”

Best Practices

Section titled “Best Practices”
  • Secure authentication: Always use HTTPS and API keys for production environments
  • Implement error handling: Set up dedicated error handlers for critical operations
  • Enable logging: Use debug logging during development and disable it in production
  • Versioning: Document changes to web service configurations for better traceability
  • Testing: Thoroughly test all operations in a test environment before deploying them to production With careful configuration of Znuny Web Services, you create the foundation for successful integration into your IT landscape and benefit from automated, efficient business processes.

Znuny automation & custom integrations

Integrate Znuny seamlessly with your IT landscape: We implement web services, business process workflows, and REST integrations.

Discuss automation

Frequently asked questions

Where can I find and manage Web Services in Znuny, and what's the initial setup?

You can access and manage Web Services in Znuny through the Web Services module, which is located within the Processes & Automation group in the administration interface. Upon a fresh installation, Znuny does not come with any pre-configured web services; you will need to create them yourself. The module provides functionalities to create, edit, delete, clone, export, and import web services, along with a debugger tool to assist in configuration and troubleshooting. This centralized management ensures that all your integrations are easily accessible and maintainable within the system.

What are the core components of a Znuny Web Service, and how do Operations differ from Invokers?

A Znuny Web Service acts as a crucial bridge between Znuny and various external systems, facilitating automated communication and data transfer. Its core components include Operations, Invokers, Mapping, and Transport. Operations are responsible for handling inbound calls, meaning Znuny acts as the provider of a service, responding to requests from external systems. Conversely, Invokers are used to send outbound requests, where Znuny acts as the requester, initiating communication with remote systems. Mapping defines how data is converted between Znuny's internal format and the external system's format, while Transport specifies the communication protocol, such as HTTP::REST or HTTP::SOAP.

What are the key configuration settings for a Znuny Web Service?

When configuring a Znuny Web Service, several general interface settings are essential for its proper functioning and identification. These include:

  • Name: A unique and descriptive identifier for the web service within Znuny.
  • Description: An extended comment detailing the service's purpose and functionality for better clarity.
  • Remote system: Specifies the name of the external system with which Znuny interacts.
  • Debug threshold: Determines the level of logging detail, ranging from Debug (most detailed) to Error (only error messages).
  • Validity: Controls whether the web service is valid (activated) or invalid (deactivated). Only valid services are executed. Additionally, you must choose the Network transport protocol, either HTTP::REST or HTTP::SOAP, which defines how data is transmitted.
  • Znuny Web Services - REST API
  • Web Services — Znuny documentation
What security considerations should I be aware of when configuring Znuny Web Services?

Security is a critical aspect when configuring Znuny Web Services, especially concerning sensitive information. It is crucial to be aware that any saved passwords within the web service configuration are exported in plain text during an export operation. This means that the storage and handling of passwords require special care and adherence to robust security practices. To mitigate risks, ensure that access to web service configurations is strictly controlled and that exported files containing sensitive data are handled in a protected manner. Always observe your organization's security regulations and best practices for managing credentials in integrated systems.

How can I use Znuny Web Services to create or manage tickets, and what protocols are supported?

Znuny Web Services enable seamless integration with external systems for ticket management, supporting both REST and SOAP protocols for communication. You can define specific Operations to perform various actions on tickets. For instance, the Ticket::TicketCreate operation, often configured via the HTTP::REST protocol, allows external systems to create new tickets in Znuny using HTTP-POST requests. Other essential operations include:

How does Znuny handle data transformation for incoming web service requests?

Znuny employs XSLT transformation as a powerful technique to convert incoming data from web service requests into a format that the system can effectively process. This is crucial because external systems may send data in a structure different from what Znuny expects. By using XSLT, you can define rules to map incoming attributes to Znuny's internal data fields, including dynamic fields. For example, an incoming attribute like incidentID from an external system can be transformed and saved into a Znuny dynamic field named RemoteTicketID. This ensures data consistency and allows for flexible integration without requiring changes to the external system's data structure, making Znuny highly adaptable to diverse IT landscapes.