Managing Controls

A control is a single UI element (a button, a field, a link, a tab) the assistant is allowed to reference when it builds an Action Plan. Controls are the foundation of every workflow Appilot guides users through: forms compose controls, knowledge entries reference them by name, and the runtime resolves each control to a real DOM element via its locator.

The agent never invents controls. It only uses what is in the registry.

Why controls exist as a separate entity

Two reasons:

1. Stable, semantic addressability. A control's semantic_id (e.g. field-url, action-save) is the stable handle authors use everywhere. The underlying DOM selector can change without rewriting knowledge entries or forms.
2. Prerequisites. Some buttons live behind hover menus, dropdowns, or modal triggers, so they are hidden until another action reveals them. A control can carry the ordered prior steps that reveal it. The assistant inlines those steps as earlier steps in the guided action plan, so the user is walked from what is visible on screen to the hidden target (whether the assistant clicks for them or guides them step by step).

Anatomy of a control

Field	Purpose
Semantic ID	Stable identifier (field-url, action-save, drawer-goto-online-services). Lowercase letters, digits, hyphens or underscores, starting with a letter. The editor suggests it from the Label and checks the format as you type. Referenced from forms (form_id) and from knowledge entries via the {{control:semantic_id}} token.
Locator	The CSS selector, XPath expression, or ARIA query that identifies the element in the live DOM.
Locator strategy	One of id, class_text, aria, xpath, semantic. Tells the runtime how to interpret the locator value.
Label	Human-readable name (e.g. "Save", "URL"). Mirrors what the user sees on screen. Used in narration ("Click Save").
Description	What this control does and any caveats. The assistant reads this to decide when to use it.
View path	The view this control lives on. Used by Step 0 to scope which controls are relevant on the user's current page.
Scope	view (default) or global. Global controls are app-wide (top navigation, drawer, header).
Form	Optional. Assign this control to a form to participate in form-fill Action Plans. See Managing Forms.
Form order	Position within the form's fill order. Required when Form is set.
Prerequisites	Optional. The ordered prior steps that reveal the control (a hover that opens a drawer, a click that opens a menu), each with the readiness signal the assistant waits for. Used for controls hidden behind menus or modals. Most controls need none.

Locator strategies

Strategy	When to use	Robustness
id	The app exposes stable id attributes.	Highest
aria	aria-label, role, or other ARIA attributes are stable.	High
class_text	Deterministic CSS classes combined with visible text or tooltip (typical for Vaadin 7 / older enterprise apps).	Medium-high
xpath	Complex hierarchical queries. Use sparingly.	Medium

Choose the most stable strategy your application offers. Authors moving to WebMCP in the future will retire the Locator and Locator strategy fields once the host app exposes tools natively.

Naming convention

Semantic IDs should follow [optional-scope-]<noun>-<qualifier>:

• new-quickstart-button
• field-interne-bezeichnung
• action-save
• drawer-goto-online-services
• param-field-type

Prefixes are not strictly required, but the Step 2 prompt buckets controls by prefix for clarity:

Prefix	Bucket	Example
drawer-, menu-, nav-	Navigation	drawer-goto-online-services
field-, param-, form-	Form-local fields and tabs	field-url
action-, row-, filter-, sort-	List or page-level interactive elements	action-save
*-wrapper	Prerequisite triggers (hover to reveal a flyout), never directly clickable	drawer-wrapper-online-services

Avoid framework-specific names (vaadin-...) so the registry survives a future migration to WebMCP.

Authoring a control

Step 1: Open the Controls tab

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

[screenshot: Backoffice domain sidebar with Controls highlighted]

Step 2: Click "Create control"

Step 3: Fill the basics

Field	Notes
Semantic ID	Lowercase letters, digits, hyphens or underscores. Unique per app. Cannot be renamed cheaply (every reference must be updated), so the editor guards renaming an existing ID.
Label	What the user sees on screen. Keep it identical to the live UI literal so the agent's narration matches.
Description	One or two sentences. Mention the side effect (does it open a dialog? navigate? save data?).
View path	Which view this control lives on. Pick Global if it appears on every page (e.g. top nav).
Locator strategy + Locator	The selector. Test it in the browser console (document.querySelector('...')) before saving.

Step 4: Link to a form (optional)

If this control is one of the fields of a multi-field form, set Form to the parent form and Form order to its position in the fill order. The constraint is symmetric: both must be set together, or both must be empty.

See Managing Forms for the form-side of this relationship.

Step 5: Configure prerequisites (optional)

If the control is hidden until another action reveals it (a hover menu, a dropdown, a modal trigger), declare the prior steps that reveal it. The Prerequisites editor is a guided step builder: click Add prerequisite step, then for each step pick the Control the user acts on first, the Operation (hover, click, or leave it on Auto), and the selector that should become visible afterwards. Reorder steps with the up/down arrows. The condition details (the readiness check, failure handling) sit under each step's Advanced disclosure with sensible defaults, so the common case (hover a wrapper, a flyout appears) needs only the control and the revealed selector.

A typical reveal step reads: Control drawer-wrapper-online-services, Operation hover, then the flyout selector is present. Power users can switch to Show raw JSON to edit the underlying array directly; the editor round-trips between the two.

The assistant inlines those steps as earlier steps in the plan (hover the wrapper, then click this control), so the user is walked from what is visible to the hidden target. For most controls, leave prerequisites empty.

In the Controls list you can narrow to controls that have them with the With prerequisites filter; a Lock icon on a row means that control has prerequisites.

Step 6: Save

The control is now in the registry and available to:

• The Step 2 prompt (the agent considers it when planning).
• Knowledge entries via {{control:semantic_id}}.
• Forms (when you assign it to a form's fields).

Common patterns

A button on the current page

Simple. Semantic ID, label, description, locator. No form, no prerequisites.

semantic_id:  action-save
label:        Save
description:  Commits the open form. Closes the dialog on success.
locator:      vaadin-button.shared-primary-button.save
strategy:     class_text
view_path:    zf/online-services/form

A field that belongs to a form

Same shape, plus form_id and form_order.

semantic_id:  field-url
label:        URL
description:  Onlinedienst endpoint (https://). Required field.
locator:      div.FieldRoot[aria-label="URL"] vaadin-text-field
strategy:     class_text
view_path:    zf/online-services/form/konfigurationsparameter
form:         online-service-form
form_order:   5

A control hidden behind a hover menu

The drawer item is hidden until the wrapper is hovered; the wrapper is the hover trigger. The drawer item lists the wrapper hover as its prerequisite.

semantic_id:   drawer-goto-online-services
locator:       vaadin-button.shared-drawer-item.online-services
strategy:      class_text
view_path:     (Global)
prerequisites: [ { control: 'drawer-wrapper-online-services', operation: 'hover', reveals: { kind: 'present', check: 'visible', selector: '...' } } ]

The wrapper itself is a separate control with no prerequisites of its own.

Empty state and onboarding

When the Controls tab is empty:

[screenshot: Empty state of DomainControlsPage]

A new domain typically gets its first controls via a recon script run against the live app, then refined in the Backoffice. For TSA the canonical seed is customers/tsa/seed/seed-controls-form-fields.ts (file paths are illustrative).

Troubleshooting

Symptom	Likely cause	Fix
The agent never references a control	Wrong view_path, or scope=view when the control is global	Adjust the view path, or set scope to global.
"Locator not found" at execute time	Selector drifted or app changed	Re-verify the selector in the browser console. Update locator.
Action plan double-clicks the wrapper instead of the hidden child	The child is missing its prerequisite step, or the prerequisite names the wrong control	Add or correct the prerequisites on the hidden control.
Cannot delete: "referenced by N controls"	Other controls list this one as a prerequisite	Remove or repoint the dependents first.
Cannot delete: "referenced by N forms"	A form lists this control as submit_control, entry_control, or a field	Update the form first.

Related

• Managing Forms: group controls into multi-field workflows.
• Knowledge management: reference controls from prose via {{control:semantic_id}}.
• Managing Views: define the surfaces where controls live.
• Domain configuration: register the domains where this whole registry takes effect.