Formstack technische Anleitung

Dank dem Modul Reporting können einem Projekt oder Event in Staffcloud ein oder mehrere Reporting-Formulare hinzugefügt werden. Diese Formulare werden von den Mitarbeitern ausgefüllt und direkt den jeweiligen Ereignissen zugeordnet, so dass diese Daten von den Planern für die Steuerung, Berichterstattung usw. verwendet werden können. Staffcloud greift dafür auf eine Drittanbieter-Lösung zurück und hat eine Schnittstelle zu Formstack gebaut.

Um das Modul Reporting nutzen zu können, brauchen Sie einen Formstack-Account. https://www.formstack.com/pricing/online-forms

Sobald Sie sich für einen Formstack-Account entschieden und diesen erstellt haben, sind Sie bereit. Sie finden nun hier die Anleitung, um einen Formstack-Account mit Staffcloud zu verbinden.

       1. Erstellen eines Staffcloud API Keys durch den Staffcloud Support.

Nehmen Sie Kontakt mit dem Staffcloud Support auf ([email protected] oder Ticket erstellen auf https://support.staff.cloud), um einen Staffcloud API Key zu erhalten.

2. Berechtigungen durch den Staffcloud Support geben lassen (betroffene Zugänge auflisten)

Damit die Formulare hinzugefügt werden können, braucht es die entsprechende Berechtigung für Ihre Staffcloud-User. Listen Sie dafür alle Zugänge auf, welche die Berechtigung erhalten sollten, Formulare zu integrieren.

3. Erstellen eines Formstack API Keys.

Loggen Sie sich bei Formstack ein und gehen Sie in ihrem Account auf API. Erstellen Sie eine 'Application', wodurch ein 'Access Token' kreiert wird. 

4. Application Felder

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)

5. Token in Staffcloud Office eintragen.

Öffnen Sie ihr Staffcloud Office und gehen im Menü links auf "Konfiguration". Unter 'Add Ons' finden Sie einen Reiter '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. 

6. Erstellen eines Formulars in Formstack.

Hilfreiche Tutorials dazu finden Sie direkt auf Formstack: https://www.formstack.com/admin/learn/dashboard

Hier als Beispiel ein POS Report.

!! 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:

Alle Felder werden am Besten analog zur 'AssignmentId' als short answer eingefügt und versteckt, also als 'hidden' markiert.

7. Webhook URL von Staffcloud in Formstack bei jedem neu erstellen Formular eintragen

Damit Staffcloud weiss, ob ein entsprechendes Formular ausgefüllt wurde, muss jedem Formular diese Information angefügt werden.

Kopieren Sie aus den Einstellungen (Reporting, siehe Bild oben) den Webhook 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 einfügen und müssen so den Link nicht mehr aus den Einstellungen holen und mit Name und API Key ergänzen.

8. Formular einem Projekt oder Event anhängen

Zurück im Staffcloud Office, könnten Sie unter Projektmanagement einem beliebigen Projekt oder Event das entsprechende Formular anhängen.

1 Wählen Sie in der Projektübersicht die gewünschten Events per Klick auf die Checkboxen aus.

2 Klicken Sie nun auf den grünen Button "Event(s) editieren" am unteren Bildschirmrand.

3 Nun öffnet sich die Oberfläche des Projektmanagements. Gehen Sie in den Bereich "Reporting".

4 Jetzt können Sie das passende Formular aus dem Drop down Menu anwählen und via 'Hinzufügen' dem Projekt und/oder den Events anhängen.

5 Klicken Sie 'Speichern' um das Formular mit den getroffenen Einstellungen im Projekt oder Event zu veröffentlichen.

Projekt-Formulare werden automatisch in jedem (neuen) Event dieses Projekts angezeigt.  
Event-Formulare werden nur in den ausgewählten Events angezeigt. 

9. Optionen konfigurieren

Nachdem das Form zum Projekt/Event hinzu gefügt wurde, können weitere Einstellungen vorgenommen werden:

• Mehrfaches Ausfüllen erlauben
  Ist diese Option aktiv, kann das Formular nicht nur einmal, sondern mehrmals pro Einsatz ausgefüllt werden.
• Zwingend nötig
  Mit der Aktivierung dieser Option wird das Form zum Pflichtfeld. Der Mitarbeiter ist gezwungen das Formular (mindestens einmal) auszufüllen.
• Auszufüllen
  Diese Option legt fest, wann das Form vom Mitarbeiter zu füllen ist.
• Erinnerung senden
  Falls das Form benötigt wird (2. Option) kann optional eine Erinnerung nach X Tagen an den Mitarbeiter verschickt werden.

10. Formular durch Mitarbeiter ausfüllen lassen

Der Mitarbeiter findet den Link zum Formular in seinem Einsatz. Das ausgefüllte und unterschriebene Formular wird dann direkt in Formstack erfasst und kann dort weiterverwendet werden.