Einbindung alternativer Messaging-Provider

Der von INTREXX vorkonfigurierte Phone Provider "seven.io“ kann durch einen beliebigen Messaging-Provider ersetzt werden. Auch eigene Hardware (Telefonanlagen, GSM-Karten) oder Software können gegebenenfalls angebunden werden.

Folgende Schritte müssen durchgeführt werden:

Datei "00-phone-service-context" kopieren und im entsprechenden Verzeichnis im Portal ablegen
Erforderliche Informationen des Providers anfordern
Prozess erstellen, der SMS oder Sprachanruf umsetzt
Einbinden des Providers in der jeweiligen Methode

Datei "00-phone-service-context" kopieren und im Portal ablegen

Damit ein alternativer Messaging-Provider von Intrexx genutzt wird, müssen Sie die Datei 00-phone-service-context kopieren und im entsprechenden Verzeichnis im Portal ablegen.

Die Datei 00-phone-service-context finden Sie in folgendem Verzeichnis:

<intrexx-installationsverzeichnis>\samples\custom-phone-service\internal\cfg\spring\custom

Kopieren Sie die Datei und fügen Sie sie in folgendes Verzeichnis ein:

<portalverzeichnis>\internal\cfg\spring\custom

Führen Sie einen Neustart des Portalserver-Dienstes durch.

Die erforderlichen Informationen des Providers

Folgende Informationen werden von einem Provider für die Versendung eines Sprachanrufs / einer SMS benötigt:

API-Key: Sie benötigen für den Connect einen API-Key, der über den Provider bereitgestellt wird. Informationen erhalten Sie direkt bei Ihrem Provider.
Request-Methoden für die REST-Call Aktion: Schema, Port, Hostname, Pfad
Hinterlegen des API-Keys im Anmeldeinformationsspeicher

Übersicht über den Aufbau des Prozesses

Hier behandeln wir den Prozess, der Informationen aus Intrexx ermittelt und an den Provider übergibt.

Übersicht der Aufgaben im Prozess:

Generischer Ereignisbehandler:

Er reagiert auf das Event "Multi-Faktor-Authentifizierung", sofern die SMS- bzw. Sprachanruf-Methode gewählt wurde.
Groovy-Aktion:

Die Daten der Nachricht (Absender, Nachricht) werden per Groovy ermittelt und in den Verarbeitungskontext geschrieben.
Rest-Call-Aktion

Die Rest-Call führt den Request aus und sendet die SMS bzw. den Sprachanruf an den im Anmeldeinformationsspeicher hinterlegten Messaging-Provider.

SMS

Zum Versenden einer SMS durch einen alternativen Provider bei der Multi-Faktor-Authentifizierung öffnen Sie den Portal Manager und wechseln in das Modul "Prozesse". Erstellen Sie einen neuen Prozess.

Klicken Sie in der Symbolleiste auf das Symbol des Prozessmanagers.

Im Prozessmanager klicken Sie auf den ersten Eintrag "Neuer Prozess".

Brechen Sie den Dialog "Neuer Prozess" über die "Abbrechen"-Schaltfläche ab.

Generischer Ereignisbehandler

Fügen Sie die "Generische Ereignisquelle" per Drag & Drop im Prozess ein.

Vergeben Sie den Titel "SMS". Der Prozess reagiert auf externe und interne Ereignisse.

Klicken Sie auf "Weiter".

Konfiguration

Wählen Sie aus der Liste die Klasse

"de.uplanet.lucy.server.phoneservice.workflow.eventhandler.PhoneServiceSendWorkflowEventHandler"

aus.

Fügen Sie über das Plus-Symbol einen neuen Eintrag hinzu.

SMS aktivieren

Der SMS-Versand soll berücksichtigt werden:

Wählen Sie die Klasse "handleSendSmsEvent" aus und hinterlegen Sie den Wert "true".

Sprachanruf deaktivieren

Fügen Sie über das Plus-Symbol einen neuen Eintrag hinzu, damit Sprachanrufe ignoriert werden.

Wählen Sie die Klasse "handleMakeVoiceCallEvent" und hinterlegen Sie den Wert "false".

Schließen Sie alle geöffneten Dialoge mit "OK".

Groovy-Aktion

Fügen Sie dem Generischen Ereignisbehandler eine Groovy-Aktion hinzu.

Wechseln Sie mit einem Doppelklick in den Eigenschaftendialog.

Klicken Sie auf "Weiter" und öffnen Sie den Intrexx-Editor über den gleichnamigen Link.

Der Skript-Editor von Intrexx öffnet sich.

Hinterlegen Sie das folgende Skript, in dem Absender, Empfänger und Text ermittelt und in den Verarbeitungskontext in Intrexx geschrieben werden:

// Required parameters
def msgTo   = g_event.recipients.join(',')
def msgText = g_event.text
				
// Optional parameters must contain a value for REST call
def msgFrom = "Intrexx"
if (g_event.optionalParameters.from)
	{
		msgFrom = g_event.optionalParameters.from
	}
g_sharedState.msgFrom = msgFrom
g_sharedState.msgTo   = msgTo
g_sharedState.msgText = msgText

Übernehmen Sie alle geöffneten Dialoge mit "OK".

REST-Call-Aktion

Fügen Sie der Groovy-Aktion jetzt eine REST-Call-Aktion hinzu.

Allgemein

Hinterlegen Sie den Alias "sendSMS" und einen Titel mit "Send SMS". Aktivieren Sie bei den Verbindungseinstellungen die Kontrollkästchen "Request und Response loggen" und "Hostnamen verifizieren".

Klicken Sie auf "Weiter".

Authentifizierung und Header

Die Authentifizierung werden wir über den API-Key des externen Providers konfigurieren.

Wählen Sie den Typ "API-Key" aus der Liste und dann die Option "X-API-Key".

Resource-Mapping

Wir werden nun das Resource-Mapping mit unseren Werten des Anmeldeinformationsspeichers sowie des Verarbeitungskontextes füllen:

API-Key des Providers
msgFrom
msgTo
msgText

Diese Informationen werden wir in diesem und in den nächsten Dialogen im Request verarbeiten.

Klicken Sie neben dem Feld "Token" auf das Symbol "Resource-Mapping".

apiKeyProvider

Im Resource-Mapping fügen Sie über das Plus-Symbol eine neue Ressource hinzu:

Key: apiKeyProvider
Ressource: Anmeldeinformationsspeichers
Passwort: Wählen Sie den Eintrag der hinterlegten API-Key Ihres Providers

Übernehmen Sie den Dialog mit "OK".

msgForm

Klicken Sie im Resource-Mapping erneut auf das Plus-Symbol, um die Ressource "msgForm" aus dem Verarbeitungskontext hinzuzufügen.

Key: msgForm
Ressource: Verarbeitungskontext
Wert: msgForm

Übernehmen Sie den Dialog mit "OK".

msgTo

Erzeugen Sie über das Plus-Symbol eine neue Ressource:

Key: msgTo
Ressource: Verarbeitungskontext
Wert: msgTo

Übernehmen Sie den Dialog mit "OK".

msgText

Erzeugen Sie über das Plus-Symbol eine neue Ressource:

Key: msgText
Ressource: Verarbeitungskontext
Wert: msgText

Übernehmen Sie den Dialog mit "OK".

Es sind nun alle Ressourcen definiert.

Markieren Sie bitte die Ressource "apiKeyProvider" und übernehmen Sie den Dialog mit "OK".

Die gewählte Ressource wurde in den "Token" sowie als Wert in den "Header" übernommen.

Headers

Erstellen Sie im Header zwei neue Einträge:

Accept
Content-Type

Klicken Sie auf das Plus-Symbol, um die folgenden Einträge zu definieren:

Accept

Key: Accept

Wert: application/json

Übernehmen Sie den Dialog mit "OK".

Content-Type

Key: Content-Type

Wert: application/xwww-form-urlencoded

Übernehmen Sie den Dialog mit "OK".

Der Dialog "Authentifizierung und Header" ist abgeschlossen.

Klicken Sie auf "Weiter".

Request

Im Request werden wir jetzt dafür sorgen, dass die Nachrichten verwendet werden. Hinterlegen Sie dazu die Methode "POST".

Füllen Sie die folgenden Eingabefelder mit den Informationen, die Ihnen von Ihrem Provider vorliegen:

Schema
Hostname
Pfad

Klicken Sie auf "Weiter".

Body

Im Body wird jetzt die SMS-Nachricht definiert.

Über das Symbol auf der rechten Seite können Sie auf das Resource-Mapping zugreifen, in dem Sie alle erforderlichen Einträge aus dem Verarbeitungskontext hinterlegt haben.

Hinterlegen Sie darüber Absender, Empfänger und Text der Nachricht wie folgt:

from=${msgFrom}&to=${msgTo}&text=${msgText}

Übernehmen Sie den Dialog mit "OK".

Wechseln Sie in die Eigenschaften des Prozesses, indem Sie einen Doppelklick auf den Prozess-Reiter ausführen. Vergeben Sie den Titel " Authentifizierung - alternativer Provider". Übernehmen Sie den Dialog mit "OK" und speichern Sie den Prozess.

Jetzt ist der Prozess aktiv: Wenn nun eine Multi-Faktor-Authentifizierung über die Methode "SMS" gewählt wird, tritt der Prozess in Kraft und versendet die erforderlichen Informationen an den Benutzer.

Sprachanruf

Zum Versenden eines Sprachanrufs durch einen alternativen Provider bei der Multi-Faktor-Authentifizierung öffnen Sie den Portal Manager und wechseln in das Modul "Prozesse". Öffnen Sie den eben erstellten Prozess " Authentifizierung - alternativer Provider".

Generischer Ereignisbehandler

Ziehen Sie die "Generischer Ereignisbehandler" per Drag & Drop in den Prozess.

Vergeben Sie den Titel "Sprachanruf". Der Prozess reagiert auf externe und interne Ereignisse.

Klicken Sie auf "Weiter".

Konfiguration

Wählen Sie aus der Liste die Klasse

"de.uplanet.lucy.server.phoneservice.workflow.eventhandler.PhoneServiceSendWorkflowEventHandler" aus.

Sprachanruf aktivieren

Fügen Sie über das Plus-Symbol einen neuen Eintrag hinzu.

Der Sprachanruf soll berücksichtigt werden:

Wählen Sie die Klasse "handleMakeVoiceCallEvent" und hinterlegen Sie den Wert "true".

SMS deaktivieren

Fügen Sie über das Plus-Symbol einen neuen Eintrag hinzu, damit Sprachanrufe ignoriert werden:

Wählen Sie die Klasse "handleSendSmsEvent" aus und hinterlegen Sie den Wert "false".

Schließen Sie alle geöffneten Dialoge mit "OK".

Groovy-Aktion

Fügen Sie dem Generischen Ereignisbehandler eine Groovy-Aktion hinzu.

Wechseln Sie mit einem Doppelklick in den Eigenschaftendialog. Klicken Sie auf "Weiter" und öffnen Sie den Intrexx-Editor über den gleichnamigen Link.

Hinterlegen Sie das folgende Skript, in dem Empfänger und Text ermittelt und in den Verarbeitungskontext in Intrexx geschrieben werden:

// Required parameters
def msgTo   = g_event.recipients.join(',')
def msgText = g_event.text
println(msgTo)
println(msgText)
g_sharedState.msgTo   = msgTo
g_sharedState.msgText = msgText

Übernehmen Sie alle geöffneten Dialoge mit "OK".

REST-Call-Aktion

Fügen Sie der Groovy-Aktion jetzt eine REST-Call-Aktion hinzu.

Wechseln Sie mit einem Doppelklick in den Eigenschaftendialog.

Allgemein

Hinterlegen Sie den Alias "sendVoiceCall" und einen Titel mit „Send VoiceCall“. Aktivieren Sie bei den Verbindungseinstellungen die Kontrollkästchen „Request und Response loggen" und "Hostnamen verifizieren".

Klicken Sie auf "Weiter".

Authentifizierung und Header

Die Authentifizierung werden wir über den API-Key des externen Providers konfigurieren. Wählen Sie den Typ "API-Key" aus der Liste und wählen die Option "X-API-Key".

Resource-Mapping

Wir werden nun das Resource-Mapping mit den Werten des Anmeldeinformationsspeichers und des Verarbeitungskontextes füllen:

API-Key des Providers
msgFrom
msgTo
msgText

Diese Informationen werden wir in diesem und den nächsten Dialogen im Request verarbeiten.

Klicken Sie neben dem Feld "Token" auf das Symbol "Resource-Mapping".

apiKeyProvider

Im Resource-Mapping fügen Sie über das Plus-Symbol eine neue Ressource hinzu:

Key: apiKeyProvider
Ressource: Anmeldeinformationsspeichers
Passwort: Wählen Sie den Eintrag der hinterlegten API-Key Ihres Providers

Übernehmen Sie den Dialog mit "OK".

msgForm

Klicken Sie im Resource-Mapping erneut auf das Plus-Symbol, um die Ressource "msgForm" aus dem Verarbeitungskontext hinzuzufügen.

Key: msgForm
Ressource: Verarbeitungskontext
Wert: msgForm

Übernehmen Sie den Dialog mit "OK".

msgTo

Erzeugen Sie über das Plus-Symbol eine neue Ressource:

Key: msgForm
Ressource: Verarbeitungskontext
Wert: msgForm

msgText

Erzeugen Sie über das Plus-Symbol eine neue Ressource:

Key: msgText
Ressource: Verarbeitungskontext
Wert: msgText

Übernehmen Sie den Dialog mit "OK".

Es sind nun alle Ressourcen definiert.

Markieren Sie bitte die Ressource "apiKeyProvider" und übernehmen Sie den Dialog mit "OK".

Die gewählte Ressource wurde in den "Token" sowie als Wert in den "Header" übernommen.

Header

Erstellen Sie im Header zwei neue Einträge:

Accept
Content-Type

Klicken Sie auf das Plus-Symbol, um die Einträge zu definieren:

Accept

Key: Accept
Wert: application/json

Übernehmen Sie den Dialog mit "OK".

Content-Type

Key: Content-Type
Wert: application/xwww-form-urlencoded

Übernehmen Sie den Dialog mit "OK".

Der Dialog "Authentifizierung und Header" ist damit abgeschlossen.

Klicken Sie auf "Weiter".

Request

Im Request werden wir jetzt dafür sorgen, dass die Nachrichten verwendet werden. Hinterlegen Sie dazu die Methode "POST".

Füllen Sie nun die folgenden Eingabefelder mit den Informationen, die Ihnen von Ihrem Provider vorliegen:

Schema
Hostname
Pfad

Klicken Sie auf "Weiter".

Body

Im Body wird jetzt die SMS-Nachricht definiert.

Über das Symbol auf der rechten Seite können Sie auf das Resource-Mapping zugreifen, in dem Sie alle erforderlichen Einträge aus dem Verarbeitungskontext hinterlegt haben.

Hinterlegen Sie darüber Absender, Empfänger und Text der Nachricht wie folgt:

from=${msgFrom}&to=${msgTo}&text=${msgText}

Übernehmen Sie den Dialog mit "OK". Der Prozess ist fertiggestellt. Wenn eine Multi-Faktor-Authentifizierung über die Methode "Sprachanruf" gewählt wird, tritt der Prozess in Kraft und versendet die erforderlichen Informationen.