Anleitung
Formular Management System: www.formdesk.de
 
 
 

Webservice API - Formdesk aus einer Anwendung heraus steuern
 
Neben der „manuellen Bedienung“ von Formdesk über die Website bietet Formdesk eine weitere Möglichkeit: den Webservice.

In diesem Handbuch wird beschrieben, was ein Webdienst ist und was Sie mit diesem Dienst machen können. Wie man den Webservice steuert und welche Funktionen unterstützt werden, erfahren Sie im technischen Handbuch für Entwickler.

Der Formdesk Webservice, auch API (Application Programming Interface) genannt, ermöglicht es einem Computerprogramm, mit Formdesk über ein Standardprotokoll zu kommunizieren. Formdesk unterstützt dabei zwei: SOAP und REST.

Mit dem Webservice können Sie häufig wiederkehrende Vorgänge umfassend automatisieren oder Formdesk in Ihre (automatisierten) Geschäftsprozesse integrieren. So kann zum Beispiel Ihre Buchhaltung, Ihr Auftragsabwicklungssystem oder Ihr Dokumentenverarbeitungssystem mit Formdesk kommunizieren. In Kombination mit dem Formdesk Webhook kann der Webservice leistungsstarke integrale Verbindungsmöglichkeiten bieten. Für die Kommunikationen zwischen Ihrem System und Formdesk brauchen Sie in vielen Fällen eine einfache Applikation (Connector). Dieses Programm, der Connector, kann Teil Ihres Systems oder eine eigenständige Anwendung sein.

Um den Webservice verwenden zu können, benötigen Sie API-Credits. Nähere Informationen sowie die Kosten für API-Credits finden Sie auf der Website.

Allgemeine Informationen über API - automatisiert koppeln
 

Diese Anleitung beinhaltet folgende Themen:
 
Möglichkeiten
Kosten und Testen
Sicherheit
Vorausgefüllte Formular-Felder
Automatisch einloggen
Formulareinträge austauschen
Formulareinträge bearbeiten
Formular-Besucher bearbeiten
 

Möglichkeiten
Der Formdesk-Webservice besteht aus mehreren Funktionen (oft auch Methods genannt). Zum Beispiel liefert die Funktion FormsGet eine Liste aller Formulare in Ihrem Konto. Der Programmierer, der Ihren Connector entwickelt, kann eine spezifische Anwendung erstellen, indem er eine Kombination von Funktionen verwendet.

Dieses Dokument gibt Ihnen einen Überblick über die Möglichkeiten bei der Verwendung des Webservice. Es handelt sich jedoch nicht um eine vollständige Liste. Wenn Sie eine bestimmte Anwendung benötigen und wissen möchten, ob der Webservice eine mögliche Lösung darstellt, nehmen Sie bitte Kontakt mit einem unserer Spezialisten auf.
 
 

Kosten und Testen
Um den Webservice verwenden zu können, brauchen Sie API-Credits. Für fast alle Funktionen wird je ein Credit benötigt. Einige Funktionen funktionieren ohne Credits und andere Funktionen sind abhängig von der Menge der Daten, die übermittelt werden. Im technischen Handbuch ist für jede Funktion die Anzahl der benötigten Credits angegeben.

Jede Funktion zeigt die verbleibenden API-Credits an. Der Connector überprüft, ob das Guthaben ausreicht. Genau wie beim Erreichen des Kontingents für Ihr Konto werden Sie per E-Mail benachrichtigt, wenn Sie fast keine API-Guthaben mehr haben.

Bei einem Standard-Abonnement, ist es nicht mehr möglich den Webservice zu nutzen, wenn das API-Guthaben aufgebraucht ist. Für Business-Abonnements funktioniert der Webservice weiterhin.

Sie erhalten 100 API-Gutschriften, um den Webservice zu testen.

API-Credits kosten 50 Euro pro 5.000 Credits. Wir empfehlen, dass Sie Ihren Connector effizient programmieren, um unnötige API-Aufrufe zu vermeiden.
 

Sicherheit
Die Datenübertragung wird über eine sichere Verbindung (SSL) ausgeführt. Der Connector muss sich bei Formdesk anmelden, genau wie Sie es tun würden. Allerdings nicht mit Ihrem Benutzernamen und Passwort, sondern mit einem speziellen Schlüssel, dem API-Schlüssel. Diesen Schlüssel finden Sie in Ihrem Formdesk-Supervisor-Konto auf der Seite Kontodetails und bei einem Benutzer im Abschnitt Benutzerverwaltung. Der API-Schlüssel berücksichtigt die entsprechenden Benutzerrechte. Wenn Sie also den Zugriff auf die API einschränken möchten, können Sie einen Benutzer mit den entsprechenden Rechten anlegen und dessen API-Schlüssel verwenden.
 

Vorausgefüllte Formular-Felder
Mit der Funktion „Park“ können Einträge, die beim Öffnen eines Formulars automatisch ausgefüllt werden sollen, vorübergehend „geparkt“ werden. Formdesk generiert eine einmalige Ticketnummer. Wird das Formular aufgerufen, dann füllt Formdesk automatisch mit dieser Ticketnummer als Parameter, die dazu gehörenden Daten im Formular aus.

Beispiel

Eine Organisation verwendet mehrere Formdesk-Formulare für interne Zwecke, z. B. ein Urlaubsantrag, Reisekostenabrechnung, Antragsformulare für einen neuen PC, Telefon, einen Zugangsausweis usw. Die URLs zu diesen Formularen sind im Intranet zu finden. Die persönlichen Daten aller Angestellten werden in Microsoft Active Directory registriert. Sobald ein Formular geöffnet wird, werden die Angaben in das Formular automatisch einhelesen.

Nach erfolgter Anmeldung im Intranet ist dem System bekannt, wer das Formular geöffnet hat. Die Organisation hat zu diesem Zweck einen Connector entwickelt. Die URL im Intranet verweist nicht direkt auf das Formular, sondern auf den Connector. Dieser holt sich die für das jeweilige Formular erforderlichen persönlichen Daten aus dem Active Directory und parkt sie bei Formdesk. Der Connector erhält eine Ticketnummer von Formdesk und startet das Formular mit dieser Nummer. Formdesk trägt die entsprechenden Daten im Formular bereits ein.
 
 

Automatisch einloggen
Mit der Funktion SignOn werden Nutzer, die bereits in Ihrem System (Netzwerk, Intranet, etc.) registriert sind, automatisch in Formdesk eingeloggt. Es wird ein sogenanntes 'Single SignOn' erstellt. Dies gilt sowohl für Formdesk-Benutzer als auch für Besucher eines Formdesk-Formulars (Achtung: Die Option „Benutzer muss eigene Einträge pflegen können“ muss aktiv sein). Der Benutzer muss in Ihrem Formdesk-Konto registriert sein. Allerdings muss Ihr System das Formdesk-Login nicht unbedingt kennen. Ein eindeutiges Element wie der Name oder die E-Mail-Adresse ist ausreichend.

Beispiel

Eine Organisation verwendet mehrere Formdesk-Formulare für interne Zwecke, z. B. ein Urlaubsantrag, Reisekostenabrechnung, Antragsformulare für einen neuen PC, Telefon, einen Zugangsausweis usw. Die URLs zu diesen Formularen sind im Intranet zu finden. Die Mitarbeitenden sollen eine Liste früherer Anträge erhalten, sich aber nicht jedes Mal neu anmelden müssen.

Nach erfolgreicher Anmeldung im Intranet, wird beim Öffnen des Formulars der Mitarbeitende durch "das System" erkannt. Die Organisation hat zu diesem Zweck einen Connector eingerichtet. Die URL im Intranet verweist nicht direkt auf das Formular, sondern auf den Connector. Wird der Link angeklickt, meldet sich der Connector mit der E-Mail-Adresse der jeweiligen Person an und öffnet dann das Formular.

Tipp: Die API enthält mehrere Funktionen zur Verwaltung von Formularbesuchern, und kann z.B. neuen Besuchern Zugriff zu Formularen geben. Ihr System kann somit sämtliche Benutzer von Formdesk verwalten.

Tipp: Auch das automatische Ausfüllen eines Formulars mit Daten, die in Ihrem eigenen System gespeichert sind, ist möglich (Vorbelegung). Verwenden Sie dazu die Funktion Parken.
 

Formulareinträge austauschen
Neben dem manuellen Herunterladen von Formulareinträgen aus Ihrem Formdesk-Konto können Sie den Webservice auch für den Datenaustausch nutzen. Zum Beispiel, um ausgefüllte Formulare automatisch in die Buchhaltung, Auftragserfassungssystem etc. einfließen zu lassen. Der dafür entwickelte Connector kann in festgelegten Abständen neu ausgefüllte oder bearbeitete Formulare herunterladen und verarbeiten. Die Vorteile für den Nutzer des Webservice sind:
  • vollständig automatisierte Verarbeitung der Daten;
  • Formdesk prüft, welcher Formulareintrag bereits abgerufen wurde und welcher nicht. Sobald ein Eintrag geändert wird, steht dieser erneut zum Abruf bereit;
  • Filter können verwendet werden;
  • es können Dateien, die zusammen mit dem Formular übermittelt wurden, heruntergeladen werden;
  • ausgefüllte Formulare können als PDF heruntergeladen werden;
  • Nach dem Datenaustausch können die Einträge auf Wunsch wieder entfernt werden.
 

Formulareinträge bearbeiten
Der Webservice enthält unter anderem Funktionen zum Hinzufügen, Bearbeiten und Entfernen von Formulareinträgen. Beim Hinzufügen oder Bearbeiten haben Sie die Möglichkeit, den Post-Formular-Übermittlungsprozess zu aktivieren, z. B. indem Sie E-Mail-Nachrichten versenden.
 

Formular-Besucher bearbeiten
Verwenden Sie für ein Formular die Option Formulareinträge verwalten, müssen sich die Benutzer registrieren, bevor sie das Formular ausfüllen können. Der Webservice enthält Funktionen zum automatischen Hinzufügen, Bearbeiten oder Entfernen von Registrierungen. In Kombination mit der Funktion 'SignOn' kann zum Beispiel ein Single SignOn erstellt werden.