Control Events

Control events let you define how fields respond to user interactions when a record is created or edited on the detail page. When a control event is triggered and the field values on the form meet the specified conditions, HAP performs the configured actions, such as showing a message or calling an integrated API.

The detail page refers to either the page used to create a record or the record detail page opened for an existing record. Control events are not available when records are edited directly in a view or through bulk editing. They are also not triggered when records are imported or created through a workflow.

Common use cases:

• Data validation alerts: Play an alert sound when an exception occurs while scanning items into inventory in an app, prompting the user to review the issue.
• Update field values: When creating a customer record, automatically set the discount based on the selected membership level. For example, set the discount to 95% for VIP1, 85% for VIP2, and 100% when no membership level is selected.

Example

In this example, the Discount field is automatically updated based on the customer's membership level:

• If VIP1 is selected, set the discount to 95%.
• If VIP2 is selected, set the discount to 85%.
• If the customer is not a member or the membership level is cleared, apply no discount.

Configure a Control Event

In the form designer, select the target field and click Event in the right panel. Then click + Event to configure a control event.

1. Select an Event Type

Select When the value changes. Both selecting a membership level and clearing the selection are considered changes to the field value.

2. Configure a Condition and Action

Configure the first condition and its corresponding action. In this example, when the Membership Level field is set to VIP1, the Discount field is set to 95%.

Condition:

Action:

3. Add Conditions and Actions for Other Scenarios

Click Add conditions next to the event type to add another condition and action group.

Result:

Supported Event Types

HAP supports the following control events: When displayed, When hidden, When the value changes, When focused, When focus is lost, and When the value changes and focus is lost.

The available events vary by field type, as shown below.

Field Type	When displayed	When hidden	When focused	When focus is lost	When the value changes	When the value changes and focus is lost
Input	✅	✅	✅	✅	🚫	✅
Action	✅	✅	🚫	🚫	✅	🚫
Read-only	✅	✅	🚫	🚫	🚫	🚫
Selection	✅	✅	🚫	🚫	✅	🚫
Relationship	✅	✅	🚫	🚫	✅	🚫

Input fields: Text, Number (direct input), Amount, Email, Telephone, Rich Text, ID Number

Action fields: Number (Progress, Stepper), Date, Time, File, Check Items, Level, Positioning, Signature

Read-only fields: Formula, Auto Number, OCR, API Query (Button), Barcode, Uppercase, Embed, Query Records, Foreign Field, Rollup, Free Link, Section, Tab, Remarks

Selection fields: Region/City, Single Select, Multiple Select, Members, Department, Organization Role, API Query (Dropdown)

Relationship fields: Relationship, Subform, Cascading

warning

1. If a field is read-only and has no value, its When displayed event is not triggered.

2. The When the value changes event is triggered only when the field value is changed manually. Changes made by a default value or another control event do not trigger this event.

Supported Actions

When a control event is triggered, the following actions are available:

Action	Description
Show/Hide	Shows or hides specified fields when the event is triggered. Unlike business rules, this action takes effect only when the event is triggered.
Set Read-only / Editable	Sets specified fields to read-only or editable when the event is triggered. Unlike business rules, this action takes effect only when the event is triggered.
Set Field Value	Sets or clears the value of a specified field when the event is triggered.
Refresh Field Value	Refreshes the values of calculated fields, such as Formula, rollup field, and concat field, when the event is triggered.
Call PBP	Calls an available PBP in the organization when the event is triggered. Returned values can be mapped back to fields in the current record.
Call integrated API	Calls a specified integrated API when the event is triggered. Returned values can be mapped back to fields in the current record.
Show Message	Displays a custom global message when the event is triggered.
Play Audio	Plays a specified sound effect or audio file when the event is triggered.
Show Tab	Displays a specified tab when the form contains multiple tabs.

Event Conditions

You can configure conditions that must also be met before an action is performed when a control event is triggered.

Multiple condition groups can be configured for the same event. If a condition group is not met, HAP continues evaluating the remaining groups in order. Once a matching condition group is found, HAP performs the actions configured for that group.

The following condition types are supported:

Condition Type	Description
By field value	Performs the configured actions if the field values on the current form meet the specified conditions when the event is triggered.
By worksheet query	Performs the configured actions if querying the specified worksheet with the configured conditions returns the expected result.
By custom function	Performs the configured actions if the custom JavaScript code returns true. Fields on the current form can be referenced in the code.

Execution Order and Priority

1. Actions within a control event are performed from top to bottom in the order in which they are configured.

2. When a form is loaded, the When displayed events for all visible fields are triggered after the form finishes loading. The events are triggered in the order in which the fields appear in the form layout, and the actions within each event are performed from top to bottom.

3. If a business rule contains a Show or Hide action and applying the rule changes a field's visibility, the field's When displayed or When hidden event is triggered accordingly.

4. Field properties configured directly in the field settings, such as Hidden or Read-only, can be changed by control events to make the field visible or editable.

5. If control events and business rules both apply Show, Hide, Read-only, or Editable actions to the same field, the control event actions are performed first in their configured order. The results are then combined with the business rules according to the following priorities:

   • Visibility: Hide > Show
   • When the field is visible: Read-only > Required > Editable