Vorgangsimport
PTworkflow stellt einen SOAP basierten Webservice bereit, mit dessen Hilfe der Datenaustausch mit anderen Applikationen ermöglicht werden kann. Der Webservice arbeitet mit einer standardisierten WSDL-Definitionsdatei, die den Webservice sowie die erlaubten Methoden und Aufrufe für den SOAP-Client beschreibt.
Der Aufruf der WSDL-Datei erfolgt in aller Regel über: http://IhrePTworkflowServeradresse:optionalerHttpPort/public/api/wsdl/show
Methodenaufrufe und grundsätzliche Funktionsweise des Webservice
Der SOAP-Webservice stellt derzeit die folgenden Funktionen bzw. Methodenaufrufe bereit:
a)userLogin() → Loginprozedur zur Anmeldung am SOAP-Server
b)getInterfaceSections() → Abruf der verfügbaren Schnittstellen
c)getDataColumns() → Abruf der gültigen Datenspalten zum Import von Vorgängen
d)transmitData() → Methode zur Übermittlung von Vorgangsdaten
e)userLogout() → Logoutprozedur zur Abmeldung vom SOAP-Server
Der Aufruf der Authentifizierungsmethode „a) userLogin()“ ist grundsätzlich vor der Nutzung des Dienstes nötig um sich am System zu legitimieren. Zur Anmeldung sollte ein in PTworkflow angelegter gültiger Benutzer mit Abteilungszugehörigkeit „Verkauf“ verwendet werden, um alle Funktionen in vollem Umfang nutzen zu können.
Nach erfolgreicher Anmeldung gibt die Methode „a) userLogin()“ zwei Responseparameter zurück, die zur weiteren Verwendung der Webservicefunktionen notwendig sind:
a)„userid“ → Eine eindeutige ID des angemeldeten Benutzers
b)„session_hash“ → Ein Sitzungstoken in Form eines 32 Zeichen Hex-MD5-Hash
Die Methoden „b)“ bis „d)“ und natürlich „e)“ sind nach erfolgreichem Login nutzbar. Jede Methode erwartet mindestens die Mitgabe der Benutzer-ID „userid“ und des Sitzungstokens „session_hash“ als Parameter.
Am Schluss der Ausführung der gewünschten Operationen sollte sich der Client mit der Methode „e) userLogout()“ vom Server abmelden. Der Server wird nach einer idle-time (Zeit, in der der Service
ungenutzt war und keine Aufrufe stattfanden) von 3600 Sekunden die Sitzung automatisch beenden. Wird nach Ablauf der idle-time ein erneuter Aufruf des Services versucht, wird dieser mit einer Fehlermeldung abgebrochen.
Um den Service wieder nutzen zu können, muss sich der SOAP-Client erneut mit Hilfe der Methode „a) userLogin()“ anmelden und ein gültiges Sitzungstoken erzeugen. Die idle-time ist fest hinterlegt und nicht änderbar.
Details zu den einzelnen Methoden und deren Aufrufe sind der nachfolgenden Auflistung zu entnehmen.
| Methodenname | Beschreibung | ||
|---|---|---|---|
| userLogin | Authentifiziert einen Benutzer „Verkauf“ am Server | ||
| Parameter-Liste | Name | Beschreibung | Erforderlich |
| $username | Benutzername | Ja | |
| $password | Passwort | Ja | |
| Rückgabewerte | Array Eindeutige Benutzer-ID und Sitzungstoken zur Übergabe und Nutzung der Webservice Funktionen. Bei einem Fehler wird ein entsprechender SOAP-Fault-Response zurückgegeben. | ||
| Methodenname | Beschreibung | ||
|---|---|---|---|
| getInterfaceSections | Gibt die Namen der verfügbaren Schnittstellen zurück | ||
| Parameter-Liste | Name | Beschreibung | Erforderlich |
| $userid | Benutzer-ID | Ja | |
| $hash | Sitzungstoken | Ja | |
| Rückgabewerte | Array Namen aller gültigen Schnittstellen zum Import von Vorgangsdaten. Dieser Name ist zur Verwendung der Methoden „c) getDataColumns()“ und „d) transmitData()“ erforderlich. Es sollte immer nur ein Sektionsname der Schnittstelle pro Aufruf angesprochen werden. Sie können die für Ihre PT-Version konfigurierte Schnittstellenbezeichnung bei unserem Support erfragen und damit dann auf den expliziten Aufruf dieser Methode verzichten. | ||
| Methodenname | Beschreibung | ||
|---|---|---|---|
| getDataColumns | Gibt die Namen der für die jeweilige Schnittstelle verfügbaren Datenspalten zurück | ||
| Parameter-Liste | Name | Beschreibung | Erforderlich |
| $userid | Benutzer-ID | Ja | |
| $hash | Sitzungstoken | Ja | |
| $interfaceSection | Name der zu nutzenden Schnittstelle | Ja | |
| Rückgabewerte | Array Bezeichnung aller gültigen Datenspalten zum Import von Vorgangsdaten. Alle über die Methode „d) transmitData()“ übermittelten Datenspalten müssen denen der Rückgabe dieser Methode entsprechen und damit als gültig gekennzeichnet sein. Datenspalten die nicht innerhalb dieser Werte aufgeführt sind, werden vom Server als ungültig abgewiesen und der gesamte Aufruf wird abgebrochen. Die verfügbaren Datenspalten werden über eine Puffer-Tabelle definiert und werden auf die Datenfelder des PTtickets gemappt. Das exakte Mapping der erlaubten Datenspalten auf Ihre Ticketfelder können Sie bei unserem Support erfragen. | ||
| Methodenname | Beschreibung | ||
|---|---|---|---|
| transmitData | Überträgt Vorgangsdaten in den Schnittstellenpuffer | ||
| Parameter-Liste | Name | Beschreibung | Erforderlich |
| $userid | Benutzer-ID | Ja | |
| $hash | Sitzungstoken | Ja | |
| $interfaceSection | Name der zu nutzenden Schnittstelle | Ja | |
| $data | Array mit Schlüssel-Wertepaaren | Ja | |
| Rückgabewerte | Erfolgs- oder Fehlermeldung, je nachdem ob die Daten korrekt übergeben und in den Schnittstellenpuffer eingelesen werden konnten. Diese Methode erlaubt die Übermittlung von Daten jeweils einer Vorgangsposition. Wenn mehrere Positionen übertragen werden sollen, ist diese Methode in einer Schleife mehrfach aufzurufen. Zur eindeutigen Identifikation einer Vorgangsposition sind mindestens die in der Schnittstelle definierten Primärschlüsselspalten zu übergeben und mit entsprechenden Werten zu füllen. Werden bei einer Datenübergabe die Identifikationsspalten nicht angegeben, wird die Aktion vom Server abgewiesen und der komplette Aufruf abgebrochen. Der Name der Primärschlüsselspalten kann über die Methode „c) getDataColumns()“ abgefragt werden. Alternativ erhalten Sie die entsprechenden Konfigurationsinformationen über unseren Support. | ||
| Methodenname | Beschreibung | ||
|---|---|---|---|
| userLogout | Meldet einen eingeloggten Benutzer vom Server ab | ||
| Parameter-Liste | Name | Beschreibung | Erforderlich |
| $userid | ID des abzumeldenden Users | Ja | |
| $hash | Token des abzumeldenden Users | Ja | |
| Rückgabewerte | Erfolgs- oder Fehlermeldung, je nachdem ob der Benutzer korrekt abgemeldet werden konnte oder nicht. | ||
