Web-Services¶

In einer vernetzten Welt muss ein Ticket-System in der Lage sein, auf Anfragen von anderen Systemen zu reagieren und auch Anfragen oder Informationen an andere Systeme zu senden:

CRM-Systeme
Projektmanagement-Systeme
Dokumentenmanagement-Systeme
und viele mehr

Das Ticket-System muss für andere Dienste ohne manuelle Eingriffe eines Agenten erreichbar sein.

OTOBO supports this requirement by the Generic Interface. It empowers the administrator to create a web service for a specific task without scripting language knowledge. OTOBO reacts on incoming REST or SOAP requests and creates objects or provides object data to other systems transparently.

Ein Web-Service ist eine Kommunikationsmethode zwischen zwei Systemen, in unserem Fall OTOBO und einem entfernten System. In seiner Konfiguration bestimmt die Operation oder der invoker die Richtung der Kommunikation, und das Mapping und der Transport kümmern sich um den Empfang und die Interpretation der Daten.

By configuration, you can define what actions the web service can perform internally (operation), what actions the OTOBO request can perform on a remote system (invokers), how data is converted from one system to the other (mapping), and which protocol is used for communication (transport).

The generic interface is the framework which makes it possible to create web services for OTOBO in a predefined way, using ready-made building blocks that are independent from each other and interchangeable.

Verwenden Sie diese Ansicht, um Web-Services im System zu verwalten. Eine neue OTOBO-Installation beinhaltet standardmäßig keine Web-Services. Die Ansicht zur Verwaltung von Web-Services ist im Modul Web-Services in der Gruppe Prozesse & Automation verfügbar.

Web-Service-Verwaltung

Web-Services verwalten¶

So erstellen Sie einen Web-Service:

Klicken Sie in der linken Seitenleiste auf die Schaltfläche Web-Service hinzufügen.
Fill-in the required fields.
Klicken Sie auf die Schaltfläche Speichern.

Neuen Web-Service erstellen

So bearbeiten Sie einen Web-Service:

Klicken Sie auf einen Web-Service in der Liste mit den Web-Services.
Ändern Sie die Felder.
Klicken Sie auf die Schaltfläche Speichern oder Speichern und abschließen.

Web-Service bearbeiten

So löschen Sie einen Web-Service:

Klicken Sie auf einen Web-Service in der Liste mit den Web-Services.
Klicken Sie in der linken Seitenleiste auf die Schaltfläche Web-Service löschen.
Klicken Sie im Dialog auf die Löschen-Schaltfläche.

Web-Service löschen

So klonen Sie einen Web-Service:

Klicken Sie auf einen Web-Service in der Liste mit den Web-Services.
Klicken Sie in der linken Seitenleiste auf die Schaltfläche Web-Service klonen.
Geben Sie einen Namen für den Web-Service ein.

Web-Service klonen

So exportieren Sie einen Web-Service:

Klicken Sie auf einen Web-Service in der Liste mit den Web-Services.
Klicken Sie in der linken Seitenleiste auf die Schaltfläche Web-Service exportieren.
Choose a location in your computer to save the Export_ACL.yml file to.

Warnung

Alle in der Konfiguration des Web-Service gespeicherten Passwörter werden im Klartext exportiert.

So schauen Sie sich eine Konfigurationshistorie eines Web-Service an:

Klicken Sie auf einen Web-Service in der Liste mit den Web-Services.
Klicken Sie in der linken Seitenleiste auf die Schaltfläche Konfigurationshistorie.

Web Service Configuration History Screen

Web-Service - Konfigurationshistorie

So benutzen Sie einen Debugger für einen Web-Service:

Klicken Sie auf einen Web-Service in der Liste mit den Web-Services.
Klicken Sie in der linken Seitenleiste auf die Schaltfläche Debugger.

Web-Service - Debugger

So importieren Sie einen Web-Service:

Klicken Sie in der linken Seitenleiste auf die Schaltfläche Web-Service hinzufügen.
Klicken Sie in der linken Seitenleiste auf die Schaltfläche Web-Service importieren.
Klicken Sie im Dialog auf die Schaltfläche Durchsuchen….
Wählen Sie eine zuvor exportierte .yml Datei.
Tragen Sie einen Namen für den Web-Service ein (optional). Bleibt dieses Feld leer, wird der Dateiname der Konfigurationsdatei als Name verwendet.
Klicken Sie auf die Schaltfläche Importieren.

Web-Service - Einstellungen¶

Die folgenden Einstellungen sind verfügbar, wenn Sie diese Ressource hinzufügen oder bearbeiten. Die mit einem Sternchen gekennzeichneten Felder sind Pflichtfelder.

Allgemeine Einstellungen für Web-Services¶

Web-Service - Allgemeine Einstellungen

Name *

Der Name der Ressource. In dieses Feld können beliebige Zeichen eingegeben werden, einschließlich Großbuchstaben und Leerzeichen. Der Name wird in der Übersichtstabelle angezeigt.

Beschreibung

Wie Kommentar, aber hier kann längerer Text hinzugefügt werden.

Remote-System

Debug-Level

The default value is Debug. When configured in this manner, all communication logs are registered in the database. Each subsequent debug threshold value is more restrictive and discards communication logs of lower order than the one set in the system.

Debug-Level (von niedriger zu hoch):

Debug
Info
Notiz
Error

Gültigkeit

Set the validity of this resource. Resources can only be used in OTOBO if this field is set to valid. Setting this field to invalid or invalid-temporarily will disable the use of the resource.

Provider Web-Service - Einstellungen¶

Bemerkung

To access the otobo webservice, please use the following URL: https://SERVERADDRESS/otobo/nph-genericinterface.pl/Webservice/WEBSERVICENAME/OPERATION

Web Service Settings - OTOBO as Provider

Web-Service - Einstellungen - OTOBO als Provider

Netzwerktransport: Select which network transport you would like to use with the web service. Possible values are HTTP::REST and HTTP::SOAP.

Bemerkung

After selecting the transport method, you have to save the configuration by clicking on the Save button. A Configuration button will be displayed next to this field.
Konfiguration: The Configuration button is visible only after a network transport was selected and saved. See the configuration for OTOBO as Provider - HTTP::REST and OTOBO as Provider - HTTP::SOAP below.
Operation hinzufügen: This option is visible only after a network transport was selected and saved. Selecting an operation will open a new screen for configuration.

Web-Service-Einstellungen - OTOBO als Provider - Operationen

OTOBO als Provider - HTTP::REST¶

To use the OTOBO REST interface, choose the network transport method „HTTP::REST“. Save and reload the screen to load the ticket operations.

$Web Service Settings - OTOBO as Provider - HTTP\:\:REST$

Web-Service-Einstellungen - OTOBO als Provider - HTTP::REST

You should now be able to select an operation.

Operations¶

There are different Ticket Operations which all serve a specific job:

Ticket::TicketCreate
Ticket::TicketGet
Ticket::TicketSearch
Ticket::TicketUpdate
Ticket::TicketHistoryGet

In this example, we are going to use the Ticket::TicketCreate operation. Click on „Add Operation“ and choose the „Ticket::TicketCreate“ operation. Choose a descriptive name, save the operation and go back to the webservice overview.

You now should see a new entry „Route mapping for Operation ‚TicketCreate‘“. Enter for example „/TicketCreate“

This will define the route, which will translate to: https://YOURSERVER/otobo/nph-genericinterface.pl/Webservice/<WEBSERVICE_NAME>/TicketCreate

Click „Save and finish“.

Now you can send a request to the endpoint.

Here is an example using curl:

curl -X POST --header "Content-Type: application/json"
--data '{
        "UserLogin": "AgentUser",
        "Password": "Password",
        "Ticket": {
                "Title": "created by Webservice request",
                "QueueID":5,
                "CustomerUser": "CustomerUser",
                "State": "new",
                "PriorityID": 1
        },
        "Article": {
                "CommunicationChannel": "Email",
                "From": "test@test.de",
                "Subject": "Webservice Create Example",
                "Body": "This was created by a Webservice request!",
                "ContentType": "text/html charset=utf-8"
        }
}'
https://YOURSERVER/otobo/nph-genericinterface.pl/Webservice/<WEBSERVICE_NAME>/TicketCreate

This request is using the least amount of attributes needed to create a new Ticket.

A full list of all attributes needed for operations can be found here:

XLST-Mapping for OTOBO as Provider - HTTP::REST¶

The XLST standard can be used to transform XML, JSON and CSV data.

In this example, we are going to use the XLST mapping to transform the response from the webservice into Dynamic Fields.

Create a Dynamic Field of Type Ticket->Text and name it for example „RemoteTicketID“.

Given the incoming data:: { „incidentID“ : „12345“, „incidentTitle“ : „Test Ticket“ }
We can save the data in the Dynamic Field as follows:: <example code here>

OTOBO als Provider - HTTP::SOAP¶

$Web Service Settings - OTOBO as Provider - HTTP\:\:SOAP$

Web-Service-Einstellungen - OTOBO als Provider - HTTP::SOAP

Requester Web-Service - Einstellungen¶

Web Service Settings - OTOBO as Requester

Webs Service-Einstellungen - OTOBO als Requester

Netzwerktransport: Wählen Sie aus, welchen Netzwerktransport Sie mit dem Web-Service verwenden möchten. Mögliche Werte sind HTTP::REST und HTTP::SOAP.

Bemerkung

After selecting the transport method, you have to save the configuration by clicking the Save button. A Configuration button will be displayed next to this field.
Konfiguration: The Configuration button is visible only after a network transport was selected and saved. See the configuration for OTOBO as Requester - HTTP::REST and OTOBO as Requester - HTTP::SOAP below.
Fehlerbehandlungs-Modul hinzufügen: This option is visible only after a network transport was selected and saved. Selecting an operation will open a new screen for its configuration.

Web Service Settings - OTOBO als Provider - Fehlerbehandlungs-Modul

OTOBO als Requester - HTTP::REST¶

$Web Service Settings - OTOBO as Requester - HTTP\:\:REST$

Web-Service-Einstellungen - OTOBO als Requester - HTTP::REST

OTOBO als Requester - HTTP::SOAP¶

$Web Service Settings - OTOBO as Requester - HTTP\:\:SOAP$

Web-Service-Einstellungen - OTOBO als Requester - HTTP::SOAP