Generische Anbindung
Hinweis: Diese Feature sind Teil der Visforms Subscription und in der freien Visforms Version nicht enthalten.
Mit dieser generischen Anbindung können Sie die Formular-Daten mit frei konfigurierbaren POST-Abfragen und GET-Abfragen an Web-Schnittstellen oder REST-API-Endpunkte übergeben.
Sie können damit nach dem Absenden des Formulars die Formular-Daten an verbreitete Web-Schnittstellen wie Vtiger und Zapier sowie viele andere senden.
Sie können die Formular-Daten auch an spezielle und individuelle Web-Schnittstellen senden.
Hinweis: Die generischen Anbindung ist vielseitig. Ihre erfolgreiche Nutzung setzt allerdings gewisse Kenntnisse um technische Details der verwendeten Web-Schnittstellen voraus.
Hinweis: In zukünftigen Visforms Versionen wird es weitere, auf verbreite Web-Schnittstellen spezialisierte, eigene Anbindungen geben.
Formular-Konfiguration
Die Einrichtung der generischen Anbindung erfolgt in der Formular-Konfiguration auf dem Reiter Datenanbindungen Unter-Reiter Generische Anbindung.
Es sind folgende Optionen einzustellen:
- Aktivieren: Auf Ja setzen, damit die Web-Schnittstelle nach dem Absenden des Formulars genutzt wird.
- URL:
Tragen Sie hier die URL der Web-Schnittstelle oder den REST-API-Endpunkt ein.
Die Weitergabe von Formular-Daten erfolgt über die angegebene URL.
Beispiel: https://api.my-domain.com/api/add-new-user.php - Schnittstellen-Typ:
Der Schnittstellen-Typ legt die technische Art und Weise fest, mit dem die URL der Web-Schnittstelle oder das REST-APIs aufgerufen wird. \- URL-Parameter:
Die in der Feld-Konfiguration aktivierten Felder werden als sogenannte GET-Parameter oder URL-Parameter an den Parameter URL angehängt. - POST-Parameter:
Die in der Feld-Konfiguration aktivierten Felder werden als Name-Wert-Pärchen der Liste der übergebenen POST-Parameter gesetzt. - POST-Template:
In das frei editierbare Template (Text, XML, JSON, HTML) fügen Sie an die notwendigen Stellen Visforms-Platzhalter für die Feld-Werte ein. - POST-JSON:
Alle aktivierten Formular-Felder werden als Name-Wert-Pärchen zu einem JSON-String formatiert.
- URL-Parameter:
Schnittstellen-Typ
Bei einem Aufruf einer Web-Schnittstelle stehen grundsätzlich verschiedene Möglichkeiten der Daten-Übertragung zu Verfügung. Der gewählte Schnittstellen-Typ aus der Formular-Konfiguration muss im Bereich der unterstützten Anforderungen der gewünschten Web-Schnittstelle liegen. Viele Web-Schnittstellen unterstützen gleich mehrere Methoden der Parameter-Übergabe.
Visforms unterstützt alle gängigen Methoden der Parameter-Übergabe. Dadurch kann die Anbindung an die unterschiedlichsten Web-Schnittstellen erfolgen.
URL-Parameter (GET)
Die in der Feld-Konfiguration aktivierten Felder werden automatisch als sogenannte GET-Parameter oder URL-Parameter an die URL aus der Option URL angehängt.
Die Sonderzeichen ?? und & werden automatisch korrekt gesetzt.
Insbesondere wird berücksichtigt, falls die Option URL bereits eigene feste GET-Parameter enthält.
Beispiele:
- URL ohne GET-Parameter: https://api.my-domain.com/api/webforms.php
- URL mit GET-Parametern: https://api.my-domain.com/api/webforms.php?user=user-name&pwd=user-password&key=123456
Visforms-Platzhalter verwenden
In der Option URL können auch Visforms-Platzhalter verwendet werden.
Dadurch kann aufgrund einer Benutzer-Auswahl, etwa in einer geeigneten Listbox, zwischen verschiedenen Web-Interface-URLs oder REST-API-Endpunkten umgeschaltet werden.
Beispiel:
- https://api.my-domain.com/api/webforms-${type}.php
Das Formular-Feld mit dem Namen type könnte etwa eine Listbox zur Angabe eines bestimmten Benutzer-Typs oder Anfrage-Typs sein.
POST-Parameter
Die in der Feld-Konfiguration aktivierten Felder werden automatisch als Name-Wert-Pärchen der Liste der übergebenen POST-Parameter gesetzt. Der POST-Parameter-Name eines Feldes richtet sich nach den Einstellungen in der Feld-Konfiguration.
POST-Parameter Format
Die Option POST-Parameter Format legt fest, in welchem Format die POST-Parameter übertragen werden.
Die möglichen Einstellungen sind:
- URL-Encoded:
Die POST-Parameter werden im gleichen Format wie URL-Parameter übertragen.
Hierbei sind keine Datei-Uploads möglich. - Liste:
Die POST-Parameter werden in einer Listen-Form mit Name-Wert-Pärchen übertragen.
Hierbei sind Datei-Uploads an die Web-Schnittstelle mit den Dateien aus Datei-Upload-Feldern möglich.
POST-JSON
Alle aktivierten Formular-Felder werden als Name-Wert-Pärchen zu einem JSON-String formatiert.
POST-JSON Name
Vergeben Sie in der die Option POST-JSON Name den Namen, unter dem der JSON-String als alleiniges Name-Wert-Pärchen übertragen wird.
Bleibt die Option POST-JSON Name leer, so wird der JSON-String als alleiniger namenloser Wert übertragen.
POST-Template
In die Option POST-Template fügen Sie das frei editierbare Template (Text, XML, JSON, HTML) ein.
Fügen Sie im frei editierbaren Template an die notwendigen Stellen Visforms-Platzhalter für die Feld-Werte ein.
Hierbei ist es egal, ob das Feld dafür in der Feld-Konfiguration für die Schnittstelle explizit aktiviert wurde oder nicht. Es zählt allein die Existenz des Feld-Platzhalters im Template. Existiert der Feld-Platzhalter im Template, dann wird das Feld auch übertragen.
Im Folgenden ein Beispiel für ein kleines POST-Template im Format JSON:
- "name": Post-Parameter Name.
- "${name}“: Visforms-Platzhalter für das Feld mit dem Namen name.
- "123456789": Der feste Wert des Post-Parameters key.
{"name":"${name}","message":"${message}","email":"${email}","date":"${date}","key":"123456789"}
POST-Template Format
Das POST-Template Format muss mit dem im POST-Template verwendeten Format übereinstimmen. Das POST-Template Format gibt also an, in welcher Form die Daten im Feld POST-Template eingetragen und später auch übertragen werden. Letztendlich steuert es den korrekten Mime-Typ der POST-Anfrage.
Authentifizierung
Stellen Sie die Option Authentifizierung verwenden auf Ja, um alle zusätzlichen Informationen zur Authentifizierung hier anzugeben.
Hinweis: Für den Schnittstellen-Typ POST-Template werden diese zusätzlichen statischen Informationen nicht hier, sondern direkt mit in die Option POST-Template eingetragen. Das Format der Informationen zur Authentifizierung ist auf JSON festgelegt. Das POST-Template kann hingegen verschiedene Formate annehmen.
Hinweis: Für den Schnittstellen-Typ URL-Parameter werden diese zusätzlichen statischen Informationen nicht hier, sondern direkt mit in die Option URL als sogenannte GET-Parameter oder URL-Parameter eingetragen.
Die Informationen zur Authentifizierung werden in einem JSON-Format hinterlegt und später dem Schnittstellen-Aufruf als zusätzliche POST-Parameter hinzugefügt (Name-Wert-Pärchen). Bei dieser Art der Festlegung verbleiben die sensiblen Zugangs-Daten der Schnittstelle ausschließlich im Backend. Insbesondere sind die sensiblen Zugangs-Daten der Schnittstelle niemals im Frontend im Web-Browser vorhanden. Das erhöht die Daten-Sicherheit.
Grundsätzlich wären die sensiblen Zugangs-Daten der Schnittstelle rein technisch auch als versteckte Formular-Felder umsetzbar. In diesem Fall wären aber die Zugangs-Daten der Schnittstelle im Frontend im Web-Browser im Formular vorhanden und somit für Unbefugte abgreifbar. Das mindert die Daten-Sicherheit erheblich.
Im Folgenden ein kleines Beispiel zur Angabe der Zugangs-Daten im JSON-Format.
{"user":"Mein Benutzer-Name","pwd":"Mein Kennwort","id":"Meine ID","key":"Mein Key"}
Meldungen an den Benutzer
Keine Meldungen
Die Daten-Anbindung an eine Web-Schnittstelle soll oft nur im Hintergrund erfolgen, ohne jegliche zusätzlichen Meldungen an den Benutzer.
Belassen Sie für diesen Fall folgende Optionen auf ihrem Default-Wert:
- Erfolgsmeldung an Benutzer = Nein.
- Fehlermeldung an Benutzer = Nein.
Erfolgsmeldung
Für den Fall einer erfolgreichen Daten-Übertragung kann dem Benutzer eine Erfolgsmeldung angezeigt werden:
- Erfolgsmeldung an Benutzer = Ja.
Alternativ zum Visforms-Standard-Text kann die Erfolgsmeldung auch aus einem Benutzer-definierten Text bestehen. Sie können in der Erfolgsmeldung Visforms-Platzhaltern nutzen.
- Erfolgsmeldung an Benutzer = Benutzerdefiniert.
Im Folgenden ein kleines Beispiel zur Angabe einer Benutzer-definierten Erfolgsmeldung:
Ihr Antrag wurde für ${name} mit der Antrags-Nummer ${anr} in unser hauseigenes Vtiger-CMS übernommen.
Wir melden uns zeitnah bei Ihnen unter der von Ihnen angegebenen Telefon-Nummer ${tel}.
Fehlermeldung
Für den Fall einer erfolgreichen Daten-Übertragung kann dem Benutzer eine Fehlermeldung angezeigt werden:
- Fehlermeldung an Benutzer = Ja.
Alternativ zum Visforms-Standard-Text kann die Fehlermeldung auch aus einem Benutzer-definierten Text bestehen. Sie können in der Fehlermeldung Visforms-Platzhaltern nutzen.
- Fehlermeldung an Benutzer = Benutzerdefiniert.
Im Folgenden ein kleines Beispiel zur Angabe einer Benutzer-definierten Fehlermeldung:
Ihr Antrag für ${name} konnte leider nicht in unser hauseigenes Vtiger-CMS übernommen werden.
Bitte wiederholen Sie den Vorgang ein zweites Mal und/oder melden Sie sich zeitnah bei uns.
Schnittstellen-Aufrufe Loggen
Die Schnittstellen-Aufrufe können in einer Datei geloggt werden.
Die Log-Datei finden Sie unter administrator/logs/visforms_wffrm.php.
Die Log-Datei finden Sie auch direkt im Visforms-Inspektor auf dem Reiter Logging Daten-Anbindung.
Eine Unterscheidung zwischen Erfolgsfall und Fehlerfall ist möglich:
- Schnittstellen-Aufrufe loggen = Fehlerfall.
- Schnittstellen-Aufrufe loggen = Erfolgsfall.
- Schnittstellen-Aufrufe loggen = Fehlerfall und Erfolgsfall.
Feld-Konfiguration
Die Einstellungen erfolgen in der Feld-Konfiguration auf dem Reiter Generische Anbindung.
Dort sind folgende Optionen einzustellen:
- Aktivieren: Auf Ja setzen, damit das Feld in der Web-Schnittstelle nach dem Absenden des Formulars genutzt wird.
- Name: Abweichender Name des Feldes in der Web-Schnittstelle.
Aktivieren
Nur die in der Felder-Konfiguration auf dem Reiter Generische Anbindung aktivierten Formular-Felder, werden in den Aufruf der in der Formular-Konfiguration auf dem Reiter Generische Anbindung festgelegten Web-Schnittstelle mit aufgenommen.
Hinweis: Für den Schnittstellen-Typ POST-Template aktiviert bereits die Existenz des Feld-Platzhalters im Template. Existiert der Feld-Platzhalter im Template, dann wird das Feld auch übertragen. Die Einstellung Aktivieren in der Feld-.Konfiguration spielt in diesem Fall keine Rolle.
Name
Sie können Feld-Konfiguration einen abweichenden Namen des Feldes für die Nutzung in der Web-Schnittstelle festlegen.
Wird ein abweichender Schnittstellen-Name für das Feld nicht gesetzt, wird der Feld-Name verwendet.
Hinweis: Für den Schnittstellen-Typ POST-Template wird der Feld-Name in der Schnittstelle direkt im Template festgelegt.
Auch in diesem Feld können Visforms-Platzhalter verwendet werden. Dadurch kann aufgrund einer Benutzer-Auswahl, etwa in einer geeigneten Listbox, zwischen verschiedenen Web-Interface-Feldern oder REST-API-Feldern umgeschaltet werden. Die Benutzer-Auswahl in einem anderen Feld entscheidet also darüber, in welchem genauen Feld der Web-Schnittstelle der Wert dieses Feldes übertragen wird.
Ein Beispiel:
- Der Benutzer füllt ein Text-Feld.
- Der Benutzer wählt für das Text-Feld eine Radio-Button-Option mit dem Namen type für die Art der Verwendung des Textes.
Mit der Einstellung Name = user_${type}_text wir bewirkt, dass der Text des Feldes in der Web-Schnittstelle in ein Feld geschrieben wird, dessen Name der gewählten Art der Verwendung des Textes entspricht.