Webseiten-Rückruffunktion - SOAP Schnittstelle
1 Einleitung
Dieses Dokument soll die SOAP-Schnittstelle für die Phonalisa Rückruffunktion erläutern. Es beschreibt den technischen Ablauf einer Rückrufspeicherung, einer Statusabfrage und eines Löschvorganges. Es wird nur auf die SOAP-Schnittstelle eingegangen. Die Funktionsweise der Rückruffunktion an sich, ist in einem extra Dokument enthalten.
2 Einführung in grundlegende Technologien
2.1 Phonalisa Rückruffunktion
Die Rückruffnktion dient in erster Linie dazu, einem Kunden die Möglichkeit zu geben, einen Rückruf zu vereinbaren, ohne selbst ein Telefonat aufbauen zu müssen. Das Rückrufsystem kann über eine SOAP-Schnittstelle bedient werden. So ist es möglich, einen Webserver einzusetzen, welcher dem Benutzer die Möglichkeit bietet, seine Telefonnummer und seine gewünschte Rückrufzeit einzugeben. Diese Anfrage wird nun vom Webserver per SOAP an den Phonalisa-Server (welcher auch einen HTTP(S)-Server bereitstellt), übergeben. Dieser gibt eine Antwort (z.B. "Ok" oder "Error"). Wenn der Rückruf erfolgreich gespeichert werden konnte, so wird dieser zu der angegebenen Uhrzeit ausgelöst.
2.2 SOAP
SOAP ist ein Netzwerkprotokoll, mit dem üblicherweise Daten zwischen Servern getauscht werden. Es basiert auf standardisierten Technologien wie z.B. XML. Eine SOAP-Übertragung findet im Normalfall über HTTP und TCP/IP statt. Die Funktionalität einer SOAP-Schnittstelle ist im Normalfall in einer WSDL-Datei beschrieben (siehe 2.3). Ein sogennanter SOAP-Request (SOAP-Anfrage) besteht immer aus dem Funktionsnamen der auszuführenden Funktion und diversen Paramtern, die die Funktion erwartet. Der Request kann auch beliebige Daten zurückgeben, so z.B. einen Fehlercode.
2.3 WSDL
WSDL steht für Web Services Description Language = Eine Beschreibungssprache für Web Schnittstellen/Services. Diese im XML-Format gehaltene Datei enhält Informationen über den Nachrichten-Fluss, deren Parameter und Datentypen. Der Phonalisa Rückrufservice benutzt eine solche WSDL-Datei zur Beschreibung des Webservices.
3 Die Verschiedenen SOAP-Funktionen für das Rückrufsystem
3.1 Rückruf erzeugen - createCallBack
Die createCallBack Funktion dient zum Speichern von neuen Rückrufen in dem Telefonsystem. Es müssen einige Paramter übergeben werden:
3.1.1 createCallBack - Parameter
Alle erwarteten Paramter haben den Typ xsd:string.
agent: Der Name des Agenten, dieser ist ein in Phonalisa generierter Agent und hat eine Rufnummer unter der dieser erreichbar ist.
time: Die Zeit, zu der der Rückruf ausgelöst werden soll. Mögliche Werte: now oder ein Datum im Format: 2010-09-26 15:56:00
target: Die Zielrufnummer, wie diese aus der Telefonanlage herraus gewählt werden würde also z.B (inkl. Amtsholung): 0036424760823
escalation_target: Die Rufnummer an die das Gespräch eskaliert werden soll, wenn der Agent nicht erreicht werden kann. Dies kann z.B. ein Call-Center sein. Hier ist die Nummer so anzugeben, wie diese aus der Telefonanlage herraus gewählt werden würde.
announcement: eine Ansage, die dem Agenten vorgelesen wird. Der Paramter ist eine ID für die konfigurierte Ansage, z.B.: 1
customerid: Die Kundennummer, diese kann dem Agenten zusätzlich vorgelesen werden. Ob und wann die Nummer vorgelesen wird hängt davon ab, wie die Ansage, die mit dem Paramter announcement festgelegt wird, programmiert ist.
3.1.2 createCallBack - Rückgabewerte
Die createCallBack-Funktion liefert immer eine Zeichenkette als Rückgabewert zurück. Falls ein Fehler auftritt, wird der Fehlertext im Klartext zurückgegeben.
3.1.2.1 ok:id=<id>
Wenn dieser Rückgabewert zurückgeliefert wird, wurde der Rückruf erfolgreich angelegt. Hier wird, eine Zeichenkette in der Form: ok:id=<id> zurückgegeben. Die ID ist eine fortlaufende Nummer, welche den einzelnen Rückruf idendifiziert. Zu einem späteren Zeitpunkt, kann der Status des Rückrufes mit dieser ID abgefragt werden. Zusätzlich benötigt man die ID auch, um den Rückruf wieder zu löschen.
3.1.2.2 Invalid characters in parameter "agent"
Es befinden sich nicht alphabetische (kleingeschriebene) Zeichen im Paramter agent.
3.1.2.3 Invalid strlen in parameter "agent"
Die Länge des Paramters agent ist länger als 25 Zeichen.
3.1.2.4 Invalid date in parameter "time"
Das Datumformat ist fehlerhaft, es wurde z.B. ein 32.03. angegeben.
3.1.2.5 Invalid time in parameter "time"
Die angegebene Zeit ist fehlerhaft, z.B.: 25:67.
3.1.2.6 Invalid date/time in parameter time, the given date/time is not in Future
Die angegebene Zeit ist nicht in der Zukunft.
3.1.2.7 Invalid characters in parameter "target"
Der Paramter target enthält andere nicht ausschließlich numerische Zeichen.
3.1.2.8 Invalid strlen in parameter "target"
Der Parameter target ist länger als die maximal erlaubten 25 Zeichen.
3.1.2.9 Invalid characters in parameter "escalation_target"
Der Paramter escalation_target enthält andere nicht ausschließlich numerische Zeichen.
3.1.2.10 Invalid strlen in parameter "escalation_target"
Der Parameter target ist länger als die maximal erlaubten 25 Zeichen.
3.1.2.11 Invalid characters in parameter "announcement"
Der Paramter announcement enthält andere nicht ausschließlich numerische Zeichen.
3.1.2.12 Invalid characters in parameter "customerid"
Der Paramter customerid enthält andere nicht ausschließlich numerische Zeichen.
3.1.2.13 Invalid strlen in parameter "customerid"
Der Parameter customerid ist länger als die maximal erlaubten 25 Zeichen.
3.1.2.14 no such agent
Der angegebene Agent konnte nicht gefunden werden.
3.1.2.15 internal server error
Dieser schwerwiegende Fehler tritt auf, wenn ein Fehler im Rückrufsystem selbst vorliegt. Dies kommt z.B. vor, wenn das Rückrufsystem nicht auf die interne Datenbank zugreifen kann. Sollte dieser Fall auftreten, hilft nur die Log-Datei auf dem Rückrufserver weiter.
3.2 Rückrufstatus auslesen - getCallBackStatusRequest
Mit getCallBackStatus kann man den Status eines angelegten Rückrufes auslesen. Dies geht bis zu dem Zeitpunkt an dem der Rückruf gelöscht wurde.
3.2.1 getCallBackStatus - Parameter
Alle erwarteten Paramter haben den Typ xsd:string.
id Die ID des Rückrufes, diese wurde beim Anlegen des Rückrufes zurückgegeben.
3.2.2 getCallBackStatus - Rückgabewerte
Die getCallBackStatus-Funktion liefert immer eine Zeichenkette als Rückgabewert zurück
- 3.2.2.1 ok:<id>:PENDING
Der Rückruf wurde gespeichert, aber noch nicht ausgeführt. Der Zeitpunkt zu dem der Rückruf ausgelöst werden soll, ist also noch nicht erreicht.
- 3.2.2.2 ok:<id>:INITIALISED
Der Rückruf wurde ausgelöst, wurde aber noch nicht vom Agenten beantwortet.
- 3.2.2.3 ok:<id>:MOVED
Der Rückruf wurde vom Agenten verschoben und wird zu einem späteren Zeitpunkt wieder ausgeführt.
- 3.2.2.4 ok:<id>:DELETEDBYAGENT
Der Rückruf wurde vom Agenten gelöscht und wird nicht wieder ausgeführt werden.
- 3.2.2.5 ok:<id>:AGENTREACHABLE
Der Agent hat den Anruf angenommen und wartet in diesem Moment darauf, dass der Kunde den Anruf entgegennimmt.
- 3.2.2.6 ok:<id>:CUSTOMERUNREACHABLE
Der Agent hat den Kunden nicht erreicht, der Kunde hat den Anruf also nach 30 Sekunden klingeln nicht entgegengenommen.
- 3.2.2.7 ok:<id>:ANSWEREDTIMETOSHORT
Der Agent hatte eine Verbindung mit dem Kunden, die aber sehr kurz war. In diesem Fall wurde der Agent vielleicht mit einem Fax oder einem Anrufbeantworter verbunden, oder der Kunde hatte einfach nicht genügend Zeit.
- 3.2.2.8 ok:<id>:AGENTBREAKEDOUT
Der Agent hat den Rückruf während er mit dem Kunden verbunden werden sollte, durch drücken der *-Taste am Telefon abgebrochen.
- 3.2.2.9 ok:<id>:SUCCESS
Der Rückruf wurde erfolgreich ausgeführt.
- 3.2.2.10 no such callback id in database
Der Rückruf konnte unter den angebeben ID nicht gefunden werden.
- 3.2.2.11 internal server error
Ein schwerwiegender Systemfehler ist aufgetreten. Hier hilft der System-Log weiter.
3.3 Rückruf löschen - deleteCallBack
Die deleteCallBack dient zum Löschen eines Rückrufes.
3.3.1 deleteCallBack - Parameter
Alle erwarteten Paramter haben den Typ xsd:string.
id Die ID des Rückrufes, diese wurde beim Anlegen des Rückrufes zurückgegeben.
3.3.2 deleteCallBack - Rückgabewerte
Die deleteCallBack-Funktion liefert immer eine Zeichenkette als Rückgabewert zurück.
- 3.3.2.1 ok
Der Rückruf wurde erfolgreich gelöscht.
- 3.3.2.2 no such callback id in database
Der Rückruf konnte unter den angebeben ID nicht gefunden werden.
- 3.3.2.3 internal server error
Ein schwerwiegender Systemfehler ist aufgetreten. Hier hilft der System-Log weiter.
4 PHP-Beispiel
Dieser Abschnitt soll ein praktisches Beispiel Anhand von PHP-Code erläutern.
4.1 Die PHP-SOAP Client Klasse
PHP5 bietet eine sehr komfortable Client-Klasse, welche die SOAP-Aufrufe kapselt. Der Constructer der Klasse wird schematisch wie folgt aufgerufen:
$SoapClient = new SoapClient($WSDL_Datei>, $Kong_array);
Der Paramter $WSDL-Datei kann einfach den Pfad einer lokal im Dateisystem liegenden WSDL-Datei beinhalten, aber auch eine Weburl wäre denkbar. Von dieser würde sich der Soap-Client die WSDL-Datei herunter laden. Die Ablage der WSDL-Datei im Dateisystem wäre aber aus Performance-Gründen anzuraten.
4.2 Aufruf einer SOAP-Funktion mithilfe der SOAP-Klasse
Im letzten Schritt wurde die SOAP-Klasse erzeugt, wurde das Element richtig initialisiert, kann man damit auch schon die ersten SOAP-Funktionen aufrufen.
Schematisch sieht das ungefähr so aus:
$SoapClient->deleteCallBack($parameter);
Wie man sieht, liefert die createCallBackfunktion
false oder null zurück, wenn der SOAP-Aufruf aus irgend einem Grund erfolglos war. In der Variable $ret würde dann der Rückgabewert der Funktion stehen.