Zum Hauptinhalt springen

Managing Forms

A form groups related controls into a single semantic unit the assistant can fill in one action. Use a form whenever your application has a multi-field workflow you want the assistant to complete autonomously or guide the user through.

Forms compose Controls and are referenced from Knowledge entries via the {{form:semantic_id}} token. The assistant chooses which form to fill based on the user's intent; the runtime materializes the Action Plan deterministically from the form descriptor, so authors never repeat field order or transitions across multiple workflows.

When to use a form vs. a control vs. a knowledge entry vs. a tool​

Each primitive has a clear job:

  • Control: a single UI element (button, field, link). Authored once, referenced everywhere. See Managing Controls.
  • Form: an ordered group of controls that fill together, possibly across tabs. Example: an "Online service" creation form.
  • Knowledge entry: prose that describes a workflow, referencing forms and controls by ID. The assistant reads it to plan multi-step procedures. See Knowledge management.
  • Tool: backend capabilities (HTTP endpoints, WebMCP integrations). Not used for click-by-click choreography. That is what forms plus knowledge replace.

Anatomy of a form​

Fields​

A form is an ordered list of controls that the assistant will fill in turn. The order matches what a user would do top-to-bottom on screen.

[screenshot: Forms editor, Fields tab with TSA's online-service-form selected]

Each field carries:

  • Its controlling Control (the link is bidirectional: the Control's Form and Form order fields point back here).
  • A Required flag: required fields appear in the Action Plan even when the user did not provide a value (the assistant prompts or falls back to a field default).
  • A Field default: used when the user asks the assistant to "fill the form with test data".

View paths​

A form lives on one or more views. For multi-tab forms, list every tab path in fill order. The assistant emits transitions between tabs automatically.

Example for TSA's online-service form:

zf/online-services/form/allgemein
zf/online-services/form/konfigurationsparameter

The order matters: section 1 of the Action Plan covers Allgemein, section 2 covers Konfigurationsparameter, and the runtime emits a click on the appropriate form-tab-* control between them.

Entry control​

Some forms are hidden behind a button (a "+ Add" that reveals a sub-form). If your form is gated this way, set Entry control to the button. The assistant invokes it before starting to fill, but only when the user is not already on one of the form's view paths.

Prerequisites​

Sometimes a form is not reachable until the user does something first, beyond the single entry-control click: open a drawer, expand a section, switch a panel. List those steps under Prerequisites. The assistant adds them to the start of the action plan automatically, before it opens or fills the form, so "complete this form" is presented as one clean step with its setup already handled.

Use prerequisites when the gating step belongs to the form as a whole. When the gating belongs to one specific control (a menu item that only appears inside a popover, a hover-only sidebar item), set the prerequisite on that control instead, so the assistant still handles it whenever it points to that control on its own. The two work together: form prerequisites run first, then the control's own prerequisites, then the form opens.

Submit control​

The control that commits the form. Set it to enable autocomplete-style workflows where the assistant saves the form after filling. Leave it empty when an enclosing surface commits the form.

Visibility rules​

Use visibility rules for conditional fields. Example: TSA's payment form shows extra fields only when field-payment-status equals Auswahl.

[
  {
    "when": { "control": "field-payment-status", "op": "equals", "value": "Auswahl" },
    "show": ["field-online-payment-process"]
  }
]

Operators: equals, not_equals, truthy, falsy. value is required for the first two, ignored for the rest. The runtime drops non-visible fields from the Action Plan automatically.

Field defaults​

When a user asks the assistant to "fill the form with test data", how should each field be generated? Choose one per field:

  • none (default): the assistant must ask the user for a value.
  • lorem: random lorem ipsum text.
  • sample_url: a plausible URL like https://test.example.com/....
  • sample_email: a plausible email.
  • literal: <value>: a fixed string. Templating tokens like {{timestamp}} and {{date}} are interpolated at runtime.

Authoring a form​

Step 1: Make sure the controls exist​

A form is composed of controls. If your controls are not authored yet, go to Managing Controls first.

Step 2: Open the Forms tab​

Navigate to Apps → [Your App] → [Domain] → Forms.

[screenshot: Backoffice domain sidebar with Forms highlighted]

Step 3: Click "Create form"​

Step 4: Basic tab​

Fill in:

  • Semantic ID: a stable identifier like online-service-form. Lowercase letters, digits, hyphens or underscores, starting with a letter; the editor suggests it from the Label and checks the format as you type. This is what knowledge entries use to reference the form.
  • Label: human-readable name.
  • Description: what this form does. The assistant uses this to decide when to fill the form.
  • View paths: every view where this form is rendered, in fill order.

[screenshot: Forms editor, Basic tab]

Step 5: Fields tab​

Add controls from the left ("Available controls") to the right ("In this form"). Reorder by using the up/down arrows. Check "Required" for each required field. Pick a field default if you want "fill with test data" to work for that field.

[screenshot: Forms editor, Fields tab with drag-reorder]

Step 6: Behaviour tab​

If the form is behind a button, set the Entry control. If the form needs setup steps before it is even reachable (open a drawer, expand a section), list them under Prerequisites. If you want the assistant to save the form when done, set the Submit control. If fields appear conditionally, write a visibility rule.

[screenshot: Forms editor, Behaviour tab]

Step 7: Save​

The form is now available to the assistant. Any knowledge entry that references it via {{form:semantic_id}} will materialize an Action Plan that fills it.

Referencing a form from a knowledge entry​

In a knowledge entry's description, write:

To create a new online service, fill {{form:online-service-form}} with
the required fields and save via {{control:action-save}}.

The assistant turns the tokens into Narrative Steps, and the runtime assembles them into the standard Action Plan view. The full token syntax (including {{control:...}} and {{tool:...}}) lives in Knowledge management § Token reference.

Common patterns​

Multi-tab form​

TSA's online service form spans two tabs: Allgemein and Konfigurationsparameter. List both view_paths in fill order; the runtime emits the tab transition between them automatically.

Sub-form behind a button​

TSA's parameter sub-form has an entry control (action-add-parameter). The runtime invokes it before filling, but only when the user is not already on the sub-form's view.

Conditional fields​

TSA's payment form shows extra fields when the user selects Auswahl via a visibility rule. The hidden fields disappear from the Action Plan; the agent does not narrate them.

Multiple instances of the same form​

Workflows like TSA's "add 4 required parameters" reference the parameter form multiple times in a single knowledge entry:

1. Fügen Sie über {{form:online-service-parameter}} den Schlüssel "datenschutz" hinzu.
2. Fügen Sie über {{form:online-service-parameter}} den Schlüssel "impressum" hinzu.
3. Fügen Sie über {{form:online-service-parameter}} den Schlüssel "oe_id" hinzu.
4. Fügen Sie über {{form:online-service-parameter}} den Schlüssel "leistung_id" hinzu.

Each occurrence becomes its own section in the Action Plan, in document order. The runtime invokes the entry control between sections so the parameter sub-form re-opens for each row.

Backoffice UX​

Page-level states the Backoffice surfaces:

  • Empty state: when the domain has no forms yet, the page shows a CTA to create the first form and a pointer to this guide. [screenshot: Empty state]
  • Loading state: the table renders with skeletons while forms are fetched. [screenshot: Loading state]
  • Error state: API failures show an inline error banner with a retry button, never a blank page. [screenshot: Error banner]
  • Validation errors: surface under the offending field in the modal, not as a top-of-page banner (unless the error is cross-field).

Every input in the editor carries an InfoTooltip describing what it does. Hover the ⓘ icon to read it.

Troubleshooting​

SymptomLikely causeFix
Field does not appear in the Action PlanControl has no form_id, or form_order is missingIn Controls, set the Form and Form order on the control.
Plan visits tabs in the wrong orderview_paths is in the wrong orderReorder via the Basic tab.
Visibility rule is not honoredOperator or value mismatchCheck the JSON, especially exact string match. Visibility operators do not coerce types.
Cannot delete: "knowledge entries reference this form"A KB entry uses {{form:semantic_id}}Remove the reference in the knowledge entry, then retry.
Sub-form opens but fields stay emptyEntry control fires but the sub-form's controls are not linked to this FormConfirm each sub-form field has form_id set to this form.
Action Plan re-opens the parent form even though the user is already on itEntry control fires unconditionallyConfirm the form's view_paths[] includes the user's current view. The runtime skips the entry only when currentViewPath ∈ view_paths.