Verbindung mit Formstack einrichten und Formulare verwalten
Mit einer Integration des Tools "Formstack Forms" können Sie vor oder nach jedem Einsatz über ein Formular Informationen von Mitarbeitenden abfragen.
Um diese Funktionalität zu nutzen, benötigen Sie das Add-On "Reporting" und zusätzlich ist ein Account für "Formstack Forms" notwendig. Weitere Informationen zu Formstack Forms und den Kosten finden Sie hier: https://www.formstack.com/pricing
In diesem Artikel erfahre ich:
- wie man die Verbindung zwischen Staffcloud und Formstack einrichtet - welche Konfigurationen in Formularen zwingend notwendig sind, um die Funktionen des Add-Ons "Reporting" voll ausschöpfen zu können.
Springe zu Anleitung für
- Formstack Forms mit Staffcloud verbinden in 5 Schritten
- Erstellen eines Formulars in Formstack
- Webhook URL von Staffcloud in Formstack bei jedem neu erstellen Formular eintragen
Sobald Sie sich für einen Formstack-Account entschieden und diesen erstellt haben, können Sie Ihren Formstack-Account mit Staffcloud verbinden.
Formstack Forms mit Staffcloud verbinden in 5 Schritten
1. Staffcloud API Key bei Staffcloud Support anfragen.
Nehmen Sie Kontakt mit dem Staffcloud Support auf (support@staff.cloud oder Ticket erstellen auf https://support.staff.cloud), um einen Staffcloud API Key zu erhalten. Bitte beachten Sie, dass für einen API Key einmalige Kosten anfallen.
2. Planer-Berechtigungen zuweisen
Damit die Formulare hinzugefügt werden können, braucht es die entsprechende Berechtigung für Ihre Staffcloud-Planer-Zugänge. Unser Support-Team ist hier gerne behilflich.
3. Erstellen eines Formstack API Keys.
Loggen Sie sich bei Formstack ein und gehen Sie in ihrem Account zum Bereich "API". Klicken Sie dort auf 'New Application'.
4. Application erstellen
Application Name: Bennen Sie Ihre Application
Redirect URl: tragen Sie den Link ein, wo der Mitarbeiter nach dem Ausfüllen hingeleitet werden soll → wir empfehlen dafür Ihre Instanz anzugeben: https://[tenant].staff.cloud
Description: Beschreibung (Name kann auch einfach ein zweites Mal eingetragen werden)
Nach erfolgreicher Erstellung, findet sich in der Übersichts-Tabelle neben dem Titel der eben erstellen Application der begleitende 'Access Token'. Dieser Access Token wird in Schritt 5 benötigt.
5. Token in Staffcloud eintragen.
Öffnen Sie Staffcloud und gehen im Menü links auf "Konfiguration" > "Add Ons" > "Reporting". Wählen Sie Formstack aus und tragen Sie den eben kreierten Formstack Access Token (aus Punkt 4) ein. Nun sind ihre Staffcloud-Instanz und ihr Formstack-Account beidseitig verbunden und können miteinander kommunizieren.
Erstellen eines Formulars in Formstack
Hilfreiche Tutorials dazu finden Sie direkt auf Formstack: https://www.formstack.com/admin/learn/dashboard
Beim Erstellen eines neuen Formular beachten, dass ein 'verstecktes Feld' mit der Bezeichnung 'AssignmentId' im Hauptteil des Formulars hinzugefügt wird. Dies ist für die Verarbeitung der Webhook-Benachrichtigungen erforderlich (Erkennung, für welche Zuordnung das Formular gesendet wird).
Hier sehen Sie ein Beispiel dafür (wir haben das Basic field 'short answer' dafür verwendet):
Zusätzlich zum obligatorischen Feld 'AssignmentId' können weitere Felder eingefügt werden, welche dann automatisch ausgefüllt werden:
| ProjectName | Der Projektname aus Staffcloud wird hier eingefügt. |
| ProjectId | Die (interne) ID des Projekts wird eingefügt. |
| EventName | Der Eventname wird eingefügt. Dies funktioniert auch für automatisch generierte Namen, z.B. aus dem Einsatzort. |
| EventId | Die (interne) ID des Events wird eingefügt. |
| FunctionName | Die Bezeichnung der Funktion wird eingefügt. |
| FunctionId | Die (interne) ID der Funktion wird eingefügt. |
| AssignmentStatus | Der Status (Eingeteilt, Betätigt, etc.) wird eingefügt. Vor allem interessant für Formulare, die vor dem Event auszufüllen sind. |
| EmployeeId | Die (interne) ID des Mitarbeiters wird eingefügt. |
Bitte beachten Sie, dass die Groß- und Kleinschreibung exakt wie hier angegeben, übernommen werden muss! Andernfalls werden die Daten nicht korrekt übernommen.
Alle Felder werden am Besten analog zur 'AssignmentId' als short answer eingefügt und versteckt, also als 'hidden' markiert.
Webhook URL von Staffcloud in Formstack bei jedem neu erstellen Formular eintragen
Damit Staffcloud weiß, ob ein entsprechendes Formular ausgefüllt wurde, muss jedem Formular ein Webhook angefügt werden.
Kopieren Sie in Staffcloud unter Konfiguration > Integrationen > Reporting (siehe Bild oben) die URL des Webhooks heraus und gehen Sie zurück in Ihren Formstack-Account.
Gehen Sie in Formstack auf Forms und klicken auf 'Settings' beim entsprechenden Formular.
Danach wählen Sie links im Menu 'Email & Actions' aus und öffnen zu unterst die 'Advanced Settings'.
Nun können Sie einen Webhook hinzufügen:
Webhook URL: fügen Sie den kopierten Link (aus den Einstellungen in Staffcloud) ein und ergänzen den Link https://[tenant].staff.cloud/api/v1/reporting-webhooks/submissions?authorization_bearer=Bearer%20[StaffCloud API Key] entsprechen mit:
- tenant: Ihr Instanzname (finden Sie im Browser → http://[tenant]staff.cloud
- Staffcloud API Key: diesen haben Sie ganz zu Beginn vom Support erhalten (siehe Punkt 1.)
(lassen Sie die Klammerzeichen [ und ] weg)
Wählen Sie zwingend JSON als content type.
Wenn Sie einmal einen Webhook erstellt haben, können Sie die URL für weitere Formulare jeweils aus bestehenden Formularen kopieren und müssen so die Webhook URL nicht mehr aus Staffcloud kopieren und mit Name und API Key ergänzen.
