Formulare vorausfüllen

Mit der Bauform Formular vorausfüllen trägt der Assistent Angaben aus dem Gespräch in ein Formular auf Ihrer Website ein. Er erfragt die Werte, zeigt dem Besucher im Chatfenster einen Vorschlag und schreibt erst nach dessen Bestätigung in die zugeordneten Felder. Diese Seite beschreibt die Einstellungen, die Meldungen und die Rückmeldung, die Sie danach in der App sehen.

So läuft ein Aufruf ab

1. 1

   Schritt 1

   Werkzeug einrichten

   Sie legen fest, welches Formular gemeint ist und welche Felder der Assistent erfragen darf. Beim Speichern prüft der Dienst Selektor, Seite und Zuordnung.

2. 2

   Schritt 2

   Der Assistent fragt nach

   Passt die Beschreibung unter Wann soll der Assistent es benutzen? zum Gespräch, erfragt der Assistent die Angaben. Fehlt eine Pflichtangabe, wird kein Vorschlag daraus und er fragt erneut.

3. 3

   Schritt 3

   Vorschlag im Chatfenster

   Der Besucher sieht jeden Wert, der eingetragen werden soll, und ob danach abgeschickt wird. Er wählt Bestätigen oder Ablehnen.

4. 4

   Schritt 4

   Eintragen auf Ihrer Seite

   Nach der Bestätigung trägt der Lader die Werte in das Formular ein. Steht das Formular auf einer anderen Seite desselben Ursprungs, also mit gleichem Protokoll, Host und Port, öffnet er diese Seite zuerst.

5. 5

   Schritt 5

   Rückmeldung

   Der Lader meldet, welche Felder eingetragen wurden, welche nicht und ob abgeschickt wurde. Der Besucher liest einen Satz dazu, Sie sehen die Einzelheiten in der App.

Wo Sie das Werkzeug einrichten

Öffnen Sie Auslöser › Werkzeuge (app.xicbot.de/werkzeuge) und wählen Sie oben unter Assistent den Assistenten, dessen Chatfenster das Formular füllen soll. Die Karte Werkzeuge des Assistenten listet seine Werkzeuge nach Schlüssel. Im Bereich Werkzeug hinzufügen stellen Sie Bauform von der Voreinstellung Anfrage aufnehmen auf Formular vorausfüllen in der Gruppe Eingebaut. Erst dann erscheinen der Bereich Formular auf Ihrer Website und die Feldzuordnung.

Jede Zeile der Liste zeigt Bezeichnung, Schlüssel und Beschreibung, darunter „Formular vorausfüllen · schreibend · mit Bestätigung“ und die Mindestrolle. Ist das Werkzeug nicht aktiv, folgt „· inaktiv“. Mit Bearbeiten öffnen Sie es im Formular; wer nur lesen darf, sieht dort Ansehen. Löschen fragt zuerst „Dieses Werkzeug löschen? Bereits ausgelöste Vorgänge bleiben bestehen.“ und meldet danach „Das Werkzeug ist gelöscht.“

Einstellungen

Allgemeine Felder

Die Mindestrolle legt fest, wer das Werkzeug auslösen darf. Das Chatfenster auf Ihrer Website zählt als Besucher, auch wenn im selben Browser jemand in der App angemeldet ist. Ein Formularwerkzeug für das Chatfenster braucht darum Besucher (öffentlicher Chat). Zur Wahl stehen die Stufen bis zur eigenen Rolle, dazu der Wert, den ein bestehendes Werkzeug schon trägt. Unter der gesperrten Auswahl Freigabe steht bei dieser Bauform der Satz „Werkzeuge dieser Bauform verändern etwas und laufen darum immer mit Bestätigung.“

Formular auf Ihrer Website

Der Bereich beginnt mit dem Hinweis „Der Assistent trägt die Angaben erst ein, nachdem der Besucher den Vorschlag bestätigt hat. Kennwort-, versteckte und Dateifelder bleiben leer.“

Eine Adresse unter Seite des Formulars (optional) muss mit ihrem Host genau auf einer der erlaubten Domains des Assistenten liegen; Groß- und Kleinschreibung spielt keine Rolle, eine Unterdomain zählt nicht. Sind keine Domains eingetragen, ist nur ein Pfad möglich. Geprüft wird beim Speichern gegen die Domains, die dann eingetragen sind. Wo Sie die Domains pflegen, steht unter Erlaubte Domains. Leer lassen Sie das Feld, wenn das Formular auf der Seite mit dem Chatfenster steht.

Felder der Eingabe

„Jede Zeile verbindet ein Feld Ihres Formulars (Attribut name) mit einer Angabe, die der Assistent im Gespräch erfragt. Andere Felder füllt er nicht aus.“ Solange keine Zeile besteht, steht dort „Noch keine Zuordnung.“ Mit Feld hinzufügen kommt eine Zeile mit der Feldart Text und ohne Pflicht dazu; nach der 20. Zeile ist die Schaltfläche gesperrt, und darunter steht „Höchstens 20 Zuordnungen.“ Feld entfernen nimmt eine Zeile heraus. Ein Werkzeug braucht mindestens eine Zeile.

Der Bereich Pflichtangaben anderer Bauformen fehlt hier, weil die Spalte Pflicht diese Rolle übernimmt; die Liste nennt die Pflicht-Angaben trotzdem hinter „Pflichtangaben:“. Leerzeichen am Anfang und Ende von Selektor, Seite, Feldnamen, Angaben und Beschriftungen entfernt der Dienst beim Speichern. Ist Abschicken erlauben gesetzt, erhält der Assistent zusätzlich die Ja-oder-Nein-Angabe absenden mit der Beschreibung „Nur true, wenn der Besucher ausdrücklich möchte, dass das Formular nach dem Eintragen abgeschickt wird. Ohne diese Angabe schickt der Besucher selbst ab.“

Feldarten

Der Assistent sieht je Angabe die ersten 200 Zeichen der Beschriftung, bei Zahl, Auswahl und Datum ergänzt um den deutschen Zusatz aus der Tabelle. Die Feldart steuert, wie der Assistent den Wert liefert. Ob ein Feld auf Ihrer Seite beschreibbar ist, entscheidet dagegen die Art des Felds im Formular selbst, siehe Abschnitt „Was eingetragen wird“.

Meldungen beim Speichern

Passt eine Formulareinstellung nicht, speichert der Dienst nichts und antwortet mit Status 422 und einem Code unter error. Die App zeigt dazu diese Meldungen:

Vorschlag und Bestätigung

Der Dienst bietet dem Assistenten nur aktive Werkzeuge an, deren Mindestrolle der Gesprächspartner erreicht. Ruft der Assistent das Werkzeug auf, nimmt der Dienst nur die Angaben aus der Zuordnung an und kürzt Texte auf 2000 Zeichen. Daraus entsteht eine Vorschau nach diesem Muster:

Formular „Kontakt“ vorausfüllen, ohne es abzuschicken. Eingetragen wird: Name: Erika Muster; E-Mail: erika@example.com; Rückruf gewünscht: ja

Ob abgeschickt wird, steht vor dem ersten Wert: bei erlaubtem und gewünschtem Abschicken heißt es „vorausfüllen und danach abschicken“. Jeder Wert erscheint mit seiner Beschriftung, ein Ankreuzfeld als „ja“ oder „nein“; ohne Werte endet der Satz mit „nichts“. Die Vorschau steht in der Sprache der Antwort darüber: auf Englisch beginnt sie mit „Prefill form“, nennt „without submitting it“ oder „and submit it“ und danach „Entered:“; ein Ankreuzfeld erscheint dort als „yes“ oder „no“, ohne Werte steht „nothing“. Die Antwort folgt der Sprache der jeweiligen Nachricht des Besuchers; wechselt er mitten im Gespräch die Sprache, wechselt die Vorschau mit. Erkennt der Dienst die Sprache einer Nachricht nicht, gilt die Sprache des Gesprächs, die der erste Satz des Besuchers festlegt, dessen Sprache der Dienst erkennt; danach bleibt sie stehen. Steht auch sie noch nicht fest, gilt die Sprache des Assistenten. Ist die Sprache der Antwort weder Deutsch noch Englisch, steht die Vorschau in der Sprache des Gesprächs und, ist auch diese weder Deutsch noch Englisch oder steht sie noch nicht fest, in der Sprache des Assistenten. Bezeichnung und Beschriftungen erscheinen so, wie Sie sie eingetragen haben. Die Kopfzeilen der Karte in der folgenden Tabelle folgen derselben Sprache; auf Englisch lauten sie „Unknown tool …“, „Not approved: …“, „Incomplete details for …“ und „Details too long for …“. Werte, die leer sind, trägt der Lader nicht ein; ein vorhandener Inhalt im Formular bleibt dann stehen. Ein Wert wird am Anfang und Ende von Leerzeichen befreit und auf 1000 Zeichen gekürzt.

Im Chatfenster erscheint statt des Fehlertexts nur „Der Schritt konnte nicht ausgeführt werden.“, im englischen Chatfenster „The step could not be carried out.“; den genauen Text sehen Sie in der App hinter Fehler.

Zustände

Im Chatfenster trägt die Karte die Vorschau als Kopfzeile, darunter das Zustandswort und bei einem Fehler den festen Satz „Der Schritt konnte nicht ausgeführt werden.“ Solange der Vorschlag offen ist, stehen darunter Bestätigen und Ablehnen. Nach dem Klick sind beide gesperrt. Scheitert die Anfrage oder antwortet der Dienst mit einem Fehler, werden sie wieder frei, und unter dem Gesprächsverlauf erscheint „Der Schritt ging nicht durch.“ Weist der Dienst eine Bestätigung ab, weil die Einwilligung inzwischen widerrufen wurde, bleiben die Schaltflächen gesperrt, das Chatfenster nimmt keine Nachricht mehr an, und unter dem Gesprächsverlauf erscheint „Die Einwilligung wurde widerrufen. Dieser Schritt wird nicht mehr ausgeführt.“

Beim Bestätigen prüft der Dienst erneut: Ist das Werkzeug inzwischen gelöscht, scheitert der Aufruf mit „Das Werkzeug wurde inzwischen entfernt.“, ist es inzwischen ausgeschaltet, mit „Das Werkzeug ist inzwischen ausgeschaltet.“ Rolle und Pflichtangaben werden gegen den aktuellen Stand geprüft. Selektor, Seite und Feldnamen liest der Dienst erst jetzt aus den gespeicherten Einstellungen; aus dem Vorschlag stammen nur die Werte. Sind die Einstellungen nicht mehr gültig, scheitert der Aufruf mit „Die Formulareinstellungen dieses Werkzeugs sind unvollständig.“

Was auf Ihrer Seite geschieht

Beim Laden des Chatfensters erhält der Lader auf Ihrer Seite die Einstellungen der Formularwerkzeuge: Werkzeug, Selektor, Seite, Feldnamen mit Feldart und ob Abschicken erlaubt ist, aber keine Beschriftungen und keine Werte. Er erhält höchstens zehn aktive Formularwerkzeuge, die ein Besucher aufrufen darf und deren Einstellungen gültig sind, in der Reihenfolge ihrer Schlüssel. Werkzeuge mit einer höheren Mindestrolle als Besucher oder mit ungültigen Einstellungen erhält er nicht, und sie belegen keinen der zehn Plätze. Änderungen an einem Werkzeug erreichen eine offene Seite erst nach dem nächsten Laden. Kennt der Lader zu einer Anweisung keine Einstellungen mit demselben Selektor, trägt er nichts ein und meldet das Formular als nicht gefunden.

Auf welcher Seite eingetragen wird

• Ist Seite des Formulars (optional) leer, sucht der Lader das Formular auf der Seite, auf der das Chatfenster offen ist.
• Zeigt die Einstellung auf die aktuelle Seite, trägt er dort ein. Verglichen werden Ursprung und Pfad ohne abschließenden Schrägstrich, dazu die Abfrage, wenn die Einstellung eine enthält.
• Zeigt sie auf eine andere Seite desselben Ursprungs, legt der Lader die Anweisung für zwei Minuten im sessionStorage ab und öffnet diese Seite. Dort trägt er nach dem Laden des Chatfensters ein.
• Liegt die Seite auf einem anderen Ursprung, etwa einer anderen Unterdomain, wird nichts eingetragen und die Rückmeldung lautet „Formular nicht gefunden“. Dasselbe gilt, wenn der Browser keinen sessionStorage zulässt.

Die Werte des Besuchers stehen dabei nicht in der Adresse. Auf der Zielseite muss der Einbaucode des Chatfensters stehen, sonst liest niemand die Übergabe. Der Lader liest sie einmal und entfernt sie; ist sie älter als zwei Minuten, verfällt sie. Einzelheiten zum Eintrag stehen unter Formularübergabe.

Was eingetragen wird

Der Selektor muss auf ein Element form zeigen. Darin sucht der Lader jedes zugeordnete Feld über sein Attribut name, und zwar nur für Werte, die nicht leer sind. Jedes Feld landet in genau einer von drei Gruppen:

Bei einer Auswahlliste sucht der Lader zuerst eine Option mit genau diesem Wert, danach eine, deren sichtbarer Text ohne Rücksicht auf Groß- und Kleinschreibung übereinstimmt; deaktivierte Optionen zählen nicht. Ein Ankreuzfeld wird bei „ja“ angekreuzt und sonst abgewählt, und zwar per Klick wie beim Besucher. Ein einzeiliges Feld erhält Zeilenumbrüche als Leerzeichen, ein mehrzeiliges behält sie. Nach dem Setzen löst der Lader die Ereignisse input und change aus, damit Prüfungen und Zähler Ihrer Seite mitlaufen.

Abschicken

Der Lader schickt das Formular nur ab, wenn alle diese Bedingungen erfüllt sind:

• Abschicken erlauben ist im Werkzeug gesetzt.
• Der Assistent hat die Angabe absenden mitgeschickt, und die bestätigte Vorschau nennt „vorausfüllen und danach abschicken“, auf Englisch „and submit it“.
• Mindestens ein Feld ist eingetragen und kein Wert ist in der Gruppe „Nicht eintragbar“ oder „Gesperrt“.
• Der Browser kennt requestSubmit().

requestSubmit() durchläuft die Pflichtfeldprüfung des Browsers und die Absende-Skripte Ihrer Seite. Als abgeschickt meldet der Lader das Formular nur, wenn das Ereignis submit tatsächlich ausgelöst wurde. Andernfalls prüft und schickt der Besucher selbst ab.

Rückmeldung an Chatfenster und App

Nach dem Eintragen gibt der Lader das Ergebnis an das Chatfenster weiter. Das Chatfenster schreibt einen Satz unter die Karte des Vorschlags und schickt die Rückmeldung an den Dienst, auch wenn die Seite gerade durch das Abschicken verlassen wird. Übermittelt werden nur Feldnamen, höchstens 20 je Gruppe, dazu ob das Formular gefunden und ob es abgeschickt wurde; Werte gehen dabei nicht mit.

Die Zahl umfasst Werte aus beiden Gruppen. Lädt der Besucher die Seite neu, stellt das Chatfenster den Satz aus der gespeicherten Rückmeldung wieder her, mit derselben Zahl.

In der App steht die Rückmeldung am Werkzeugaufruf im Gesprächsverlauf, zum Beispiel „Rückmeldung der Website: 3 Feld(er) eingetragen · nicht abgeschickt“ oder „Rückmeldung der Website: Formular nicht gefunden“. Darunter folgen die Feldnamen unter Eingetragen, Nicht eintragbar und Gesperrt; die Werte des Aufrufs stehen unter Eingabe.

Kennt der Lader keine Einstellungen mit demselben Selektor, etwa weil das Werkzeug beim Laden der Seite ausgeschaltet war, sein Selektor danach geändert wurde oder es nicht zu den zehn Formularwerkzeugen gehört, die der Lader erhält, trägt er nichts ein und meldet das Formular als nicht gefunden; unter der Karte steht dann „Das Formular wurde auf dieser Seite nicht gefunden. Bitte füllen Sie es selbst aus.“ Keine Rückmeldung entsteht, wenn der Besucher die Seite vorher verlässt. Die Karte zeigt dann nur „Erledigt“.

Über die Schnittstelle

Über die Schnittstelle trägt das Werkzeug den Typ form_fill. Die Formulareinstellungen stehen unter settings; ein mitgeschicktes schema ersetzt der Dienst durch das aus der Zuordnung erzeugte, approval setzt er auf confirm. Die Regeln der Felder sind dieselben wie in der App.

{
  "type": "form_fill",
  "key": "kontaktformular",
  "title": "Kontaktformular ausfüllen",
  "description": "Wenn der Besucher eine Anfrage stellen möchte und Name, E-Mail und Anliegen genannt hat.",
  "min_role": "public",
  "is_active": true,
  "settings": {
    "selector": "#kontakt",
    "page": "/kontakt",
    "submit_allowed": false,
    "fields": [
      { "name": "name", "key": "name", "label": "Name", "type": "text", "required": true },
      { "name": "email", "key": "email", "label": "E-Mail-Adresse", "type": "email", "required": true },
      { "name": "nachricht", "key": "nachricht", "label": "Anliegen", "type": "textarea", "required": false }
    ]
  }
}

Rollen

Mit der Rolle Lesen steht über dem Formular „Mit der Rolle Lesen lässt sich hier nur ansehen. Ändern kann, wer mindestens die Rolle Bearbeiten hat.“ Die Felder sind dann gesperrt. Ohne Verwaltung ist die Auswahl Mindestrolle beim Bearbeiten gesperrt und darunter steht „Die Mindestrolle eines bestehenden Werkzeugs ändert, wer die Rolle Verwaltung oder Inhaber hat.“ Wer eine Stufe über der eigenen Rolle wählt, erhält „Diese Mindestrolle liegt über der eigenen Rolle. Zur Wahl stehen die Stufen bis zur eigenen Rolle.“

Ändern und löschen

• Bauform und Schlüssel stehen nach dem Anlegen fest. Für einen anderen Schlüssel legen Sie ein neues Werkzeug an.
• Jedes Speichern prüft alle Einstellungen erneut, auch die Seite gegen die dann erlaubten Domains. Steht dort eine Adresse auf einer Domain, die nicht mehr erlaubt ist, speichern Sie erst nach Anpassen der Seite.
• Anlegen, Ändern und Löschen stehen im Protokoll. Kommt der Eintrag nicht zustande, wird nichts gespeichert und die App meldet „Nicht gespeichert: Der Eintrag ins Protokoll kam nicht zustande. Bitte versuchen Sie es erneut.“
• Nach erfolgreichem Speichern leert die App das Formular für das nächste Werkzeug und meldet neben dem Knopf „Gespeichert: …“ mit der Bezeichnung.
• Löschen entfernt das Werkzeug; bereits ausgelöste Vorgänge bleiben bestehen. Ein offener Vorschlag scheitert beim Bestätigen mit „Das Werkzeug wurde inzwischen entfernt.“
• Ein Ändern über die Schnittstelle ohne is_active lässt den Schalter, wie er ist; ein ausgeschaltetes Werkzeug bleibt ausgeschaltet.

Hinweise für die Praxis

• Stellen Sie die Mindestrolle auf Besucher (öffentlicher Chat). Mit einer höheren Stufe erhält der Lader die Einstellungen nicht, und im Chatfenster bietet der Dienst das Werkzeug gar nicht an.
• Der Lader erhält je Assistent höchstens zehn Formularwerkzeuge, nach Schlüssel geordnet. Werkzeuge mit höherer Mindestrolle oder ungültigen Einstellungen zählen dabei nicht mit. Gibt es mehr als zehn passende Werkzeuge, erhält der Lader die mit den hinteren Schlüsseln nicht.
• Binden Sie das Chatfenster auch auf der Seite mit dem Formular ein und tragen Sie deren Domain als erlaubte Domain ein, siehe Widget einbauen.
• Prüfen Sie den Selektor in der Konsole des Browsers auf der Formularseite mit document.querySelector('#kontakt'): das Ergebnis muss das Element form sein, nicht ein umgebendes Element.
• Ordnen Sie nur Felder zu, die der Lader beschreiben kann, und wählen Sie für Auswahllisten die Feldart Auswahl, damit der Assistent den Eintrag so nennt, wie er in der Liste steht.
• Beschreiben Sie unter Wann soll der Assistent es benutzen? knapp, wann das Formular gemeint ist, und probieren Sie den Ablauf im Chatfenster auf Ihrer eigenen Seite aus: nur dort wird eingetragen.

Häufige Fragen