Benutzerhandbuch für den Click2Call-Rückrufservice

Transkript

1 Benutzerhandbuch für den Click2Call-Rückrufservice

2 Inhaltsverzeichnis 1 Anwendungsbeschreibung und Funktionsliste 3 2 Installation Systemvoraussetzungen Das Extension Repository Aktualisierungen Backend Provider verwalten Dateiverwaltung System-Log Frontend Frontend-Modul Click2Call Rückrufservice Formular Entwicklung Dateistruktur Programmierung Updates... 16

3 1 Anwendungsbeschreibung und Funktionsliste Click2Call ermöglicht es, eine Contao-Installation um einen Rückrufservice zu erweitern. Es wird ein Zugang zu einem VoIP-Konto benötigt. Nach der Installation steht im Backend ein zusätzliches Frontend-Modul und ein zusätzlicher Menüpunkt zur Verfügung, unter dem Zugänge zu VoIP-Providern konfiguriert werden. Zusätzlich dazu kann die Verfügbarkeit des Services über die Eingabe von Geschäftszeiten zeitlich begrenzt werden. Der Click2Call Rückrufservice der Firma gispack ist in Verbindung mit einer Aterisk-Telefonlage der Version 1.8 implementiert. Folgende Auflistung gibt Aufschluss über die Funktionen des Click2Call Rückrufservices. Mit Asterisk 1.8 getestet. Geschäftszeiten können eingerichtet werden. Stellt ein zusätzliches Backend- Modul zur Verfügung. Firmenlogo kann dem Frontend- Modul hinzugefügt werden. Nur deutsche Telefonnummern werden akzeptiert. Die ID des Empfängers wird im Display angezeigt. Formular durch Captcha gesichert. 3

4 2 Installation Um Click2Call installieren zu können, müssen bestimmte Voraussetzungen erfüllt sein. Die Installation und Aktualisierungen werden über das Extension Repository eingespielt. 2.1 Systemvoraussetzungen Lauffähiges Contao in der Version 2.11 SOAP-Erweiterung für PHP Aktueller Webbrowser möglichst mit aktivierten JavaScript und erlaubten Cookies Zugang zu VoIP-Konto (Hostname/IP-Adresse, Benutzername, Passwort) 2.2 Das Extension Repository Die Anwendung ist im Extension Repository hinterlegt und kann mit wenigen Klicks installiert werden. Die Installation der Anwendung erfolgt im über den Menüpunkt Erweiterungskatalog im Contao Backend. Über verschiedene Filter oder die Volltextsuche kann nach Click2call gesucht werden. Mit der Installation werden automatisch Verzeichnisse, Dateien und Datenbanktabellen angelegt und das Programm ist sofort einsatzbereit. 2.3 Aktualisierungen Aktuelle Programmversionen werden vom Etwickler im Extension Repository in Form von Releases veröffentlicht. Daraufhin ist die neue Version über den Menüpunkt Erweiterungsverwaltung verfügbar. Mit einigen Klicks werden gegebenenfalls die Datenbankstruktur aktualisiert und Programmdateien ausgetauscht. 4

5 3 Backend Im Backend von Contao wird der Rückrufservice konfiguriert. Zudem besteht die Möglichkeit über die Dateiverwaltung ein individuelles Logo für den Service hochzuladen. Außerdem bietet das System-Log nützliche Informationen zur Fehleranalyse und Nutzung des Services. 3.1 Provider verwalten Über den Menüpunkt Einstellungen der Kategorie Click2Call Rückrufservice werden Providerdaten hinzugefügt, bearbeitet oder gelöscht. In der folgenden Übersicht werden die Felder der Provider-Konfiguration und die vom System erwarteten Eingabewerte aufgelistet. Feldname Beschreibung Eingabeprüfung Provider* Namen des Providers erweitert alphanumerisch, maximal 128 Zeichen Registrar* Host-Namen oder die IP-Adresse. erweitert alphanumerisch, maximal 128 Zeichen Benutzername* Passwort* Bitte geben Sie den Benutzernamen an, mit dem Sie sich beim Provider anmelden möchten. Bitte geben Sie ein Passwort für den Benutzer ein. alphanumerisch, maximal 64 Zeichen beliebig, maximal 32 Zeichen Kanal / Nebenstelle* Bitte geben Sie den Kanal / die Nebenstelle an, auf dem / der Sie die Rückrufanfrage entgegennehmen möchten z.b. SIP/XXX, IAX2/XXXX, ZAP/XXXX, local/1nxxnxxxxxx@from-internal usw. erweitert alphanumerisch, maximal 128 Zeichen 5

6 Kontext* Port Wartezeit Kontext für das Rauswählen, standardmäßig from-internal für Asterisk Port für den Verbindungsaufbau, standardmäßig 5038 für den Asterisk Manager Dauer des Rückrufanfrage, nur numerische Zeichen erweitert alphanumerisch, maximal 32 Zeichen numerisch, maximal 5 Zeichen numerisch, maximal 2 Zeichen Priorität Priorität des Anrufs an, 1-4 für Asterisk numerisch, maximal 2 Zeichen Versuche Verfügbarkeit beschränken Maximale Anzahl an Rückrufversuchen an Die Checkbox aktiviert Felder für alle Wochentage, in denen minutengenau Uhrezeiten für Start und Stopp des Services eingetragen werden können. numerisch, maximal 2 Zeichen Format hh:mm 3.2 Dateiverwaltung Die Dateiverwaltung ist unter der Kategorie System des Backend-Menüs zu finden. Dort lässt sich unter anderem das Logo für den Rückrufservice hochladen, welches dadurch im entsprechenden Modul auswählbar ist. Um ein Bild hochzuladen, wird die Schaltfläche Datei-Upload betätigt und über die Pfeil-Symbole der Ordner ausgewählt, in dem das Bild abgelegt werden soll. Nun kann das Bild über die Schaltfläche Durchsuchen bestimmt und anschließend hochgeladen werden. Es ist auch möglich, mehrere Bilder gleichzeitig hochzuladen. Beim Upload sollte darauf geachtet werden, dass das Bild nicht die in den Contao-Einstellungen angegebenen Maße oder die maximale Dateigröße überschreitet. Nach erfolgreichem Ablauf wird eine entsprechenden Erfolgsmeldung ausgegeben und das Bild steht zur weiteren Verwendung im angegebenen Ordner bereit. 6

7 3.3 System-Log Das System-Log von Contao befindet sich unter der Kategorie System und bietet eine Übersicht über alle im System gespeicherten Programmmeldungen. An dieser Stelle werden auch Meldungen der Click2Call-Erweiterung gespeichert. Demnach werden Erfolgs- und Fehlermeldungen in folgender Form aufgezeichnet: Connection established between <Host> and <Name><<Rufnummer>>. Connection refused by <Registrar> (#111). 7

8 4 Frontend Unter der Kategorie Themes liegt der Menüpunkt Frontend-Module. Dort lassen sich die Module des jeweiligen Themes erstellen, bearbeiten und löschen. Das Modul erstellt ein Frontend-Formular für den Rückrufservice und es lässt sich eine zuvor erstellte Provider-Konfiguration zuweisen. 4.1 Frontend-Modul Click2Call Rückrufservice In der Bearbeitungsansicht des Moduls wird als Modultyp Click2Call Rückrufservice gewählt, um die Einstellungen für das Frontend-Formular vornehmen zu können. Die folgende Übersicht listet alle hinzugekommenen Felder des Moduls und die erwarteten Eingabewerte auf. Feldname Beschreibung Eingabeprüfung Konfiguration* Weist dem Formular eine Provider- Konfiguration zu <Provider-Name> [<Benutzername>] (<ID>) Teaser Text vor dem Formular erweitert alphanumerisch, kein HTML Ein Bild hinzufügen Die Checkbox aktiviert weitere Felder für die Logobild-Einstellungen Das fertig konfigurierte Modul kann dann entweder im Seitenlayout unter dem Menüpunkt Themes an gewünschter Position oder in einem Artikel als Inhaltselement mit dem Elementtyp Modul eingebunden werden. 8

9 4.2 Formular In der folgenden Übersicht werden die Felder des Frontend-Formulars für den Rückrufservice und die vom System erwarteten Eingabewerte aufgelistet. Feldname Beschreibung Eingabeprüfung Ihr Name* Name des Nutzers alphabetisch Ihre Nummer* Zielrufnummer des Anrufs deutsche Telefonnummer mit Vorwahl Sicherheitsabfrage* Captcha mit Rechenaufgabe numerisch, Lösung der Rechenaufgabe Nach dem Absenden des Formular wird im Erfolgsfall folgende Meldung ausgegeben: Wir verarbeiten Ihre Rückruf-Anfrage, bitte warten Sie einen Moment Sind alle Angaben korrekt, klingelt die in der Konfiguration angegebene Nebenstelle und nach Abnehmen des Hörers wird eine Verbindung zwischen dieser Nebenstelle und dem im Formular eingetragenen Anschluss hergestellt. Andernfalls wird eine Fehlermeldung generiert, die Aufschluss über die Ursache des Fehlers gibt. Die folgende Tabelle zeigt mögliche Fehlermeldung, deren wahrscheinliche Ursache und den dazugehörigen Lösungsansatz. Fehlermeldung Ursache Lösung Bitte füllen Sie das Feld <Feldname> aus! Bitte geben Sie nur Buchstaben ein! Ihre Nummer * muss eine gültige deutsche Telefonnummer mit Pflichtfeld leer gelassen Pflichtfeld Name enthält nicht alphabetische Zeichen Pflichtfeld für Telefonnummer enthält ungültige Telefonnummer Pflichtfeld ausfüllen unzulässige Zeichen entfernen deutsche Telefonnummer mit Vorwahl eintragen 9

10 Vorwahl sein, die nur Ziffern enthält z.b Bitte beantworten Sie die Sicherheitsfrage! Derzeit ist unser Büro leider nicht besetzt. Ein Verbindungsfehler ist aufgetreten. <Fehlerbeschreibung> <Fehlernummer>. Pflichtfeld für Sicherheitsfrage leer oder Ergebnis der Rechnung falsch Anfrage liegt außerhalb der angegebenen Bürozeiten Internetverbindung gestört / Zugang zum Provider falsch konfiguriert / Provider nicht erreichbar oder blockiert Anfrage richtige Antwort der Rechenaufgabe ins Feld eintragen Bürozeiten in Erfahrung bringen und erneut versuchen Internetverbindung prüfen, Providerkonfiguration prüfen, Provider benachrichtigen, eventuell zum späteren Zeitpunkt erneut versuchen 10

11 5 Entwicklung Das folgende Kapitel ist der Weiterentwicklung der Click2Call-Anwendung gewidmet. Dazu wird als Erstes die Ordner- und Dateistruktur bekanntgegeben. Als Nächstes werden grundlegende Prinzipien der Programmierung erläutert und schließlich Aktualisierungen für Contao und Click2Call behandelt. 5.1 Dateistruktur Die Ordner- und Dateistruktur folgt dem von Contao vorgegebenen Muster. Auf der obersten Ebene befinden sich die Ordner config, dca, languages und templates sowie die Moduldatei ModuleClick2Call.php und der Hook HookGermanNumbers.php. Die Moduldatei enthält die Modulklasse ModuleClick2Call, während der Hook die Validierung auf deutsche Telefonnummern für das Frontend-Formular beinhaltet. Alle Ordner beinhalten eine.htaccess -Datei, die vor unerlaubtem Zugriff schützt. Der Ordner config beinhaltet die Konfiguration der Erweiterung: config.php : Registrierung von Front- sowie Backend-Modul und Hook database.sql : SQL-Tabellenstruktur Im Ordner dca sind die Data Container Arrays für das Frontend (tl_click2call.php) und Backend (tl_module.php) gespeichert. Ordner- und Dateistruktur von Click2Call 11

12 Im Ordner languages liegen die Übersetzungen der Erweiterung. Jede Übersetzung bekommt ihren eigenen Ordner mit dem entsprechenden Länderkürzel und enthält folgende Dateien: default.php : Sonstiges modules.php : Übersetzung der Modultitel und -beschreibungen tl_click2call.php : Übersetzung des Frontend-Moduls tl_module.php : Übersetzung des Backend-Moduls Schließlich sind im Ordner templates das html5-template mod_click2call_form.html5 und das xhtml-template mod_click2call_form.xhtml für die Darstellung des Formulars im Frontend zu finden. 12

13 5.2 Programmierung Die folgende Abbildung zeigt die Datenbankstruktur der Erweiterung. Abbildung 1: Struktur der Datenbank in phpmyadmin 13

14 Jede Datei enthält im Kopfbereich Informationen zu Lizenz, Autor, Paketzugehörigkeit und Copyright. Datei-Header der Klasse ModuleClick2Call 14

15 Die Klasse ModuleClick2Call befindet sich in der gleichnamigen PHP-Datei und beinhaltet Variablen, Funktionen sowie die Programmlogik. Außerdem gibt sie Aufschluss über die Benennung von Variablen und die übersichtliche Formatierung von Programmcode. Auszüge der Klasse ModuleClick2Call 15

16 5.3 Updates Etwaige Erweiterungen, Anpassungen, Korrekturen oder Verbesserungen des Programmcodes werden im Extension Repository als Releases veröffentlicht und stehen somit als Update zur Verfügung. Hinter Version stable von click2call steckt also das erste Major-Release, welches stabil läuft und noch keine Minor- und Maintenance- Version zählt. Das Freigabedatum gibt Auskunft über den Zeitpunkt der letzten Aktualisierung. Über die Erweiterungsverwaltung der Contao-Installation wird automatisch darauf hingewiesen, ob eine neue Version von Click2Call verfügbar ist. Zudem sind hier Support- Informationen abrufbar und die Erweiterung kann aktualisiert oder deinstalliert werden. Erweiterungsverwaltung Fragen, Anregungen und Kritik helfen Click2Call zu verbessern und können an folgende -Adresse gesendet werden: 16