Interaction Buttons
Interaction buttons open a Studio page so users can inspect context, enter information, or run actions within that page. Set buttonType: 'interaction'; the current main action is studioPage, opened in a modal or drawer.
For business execution, automation, and approval tasks, see Task Buttons.
Configuration and Lifecycle
- Add a custom button in Button Design and select Interaction Button.
- Choose a published Studio page and configure its modal/drawer, title, and dimensions.
- Optionally attach before-click and after-click Studio scripts.
| Phase | Behavior | Can stop subsequent actions |
|---|---|---|
beforeClick | Runs the script; the browser consumes returned UI effects | Yes |
action | Opens the configured Studio page | The page action does not execute a Studio script |
afterClick | Runs after opening the page container and submitting configured workflows | Does not undo an opened page or submitted workflow |
afterClick does not mean the user has saved, submitted, or closed the page. Interaction buttons do not append a task-style success message; pages and scripts can explicitly provide feedback. Execution errors still surface. Configured approval or automation workflows can still run for existing records; an interaction button does not prohibit business writes.
The following script protocol applies to before/after callbacks whose results are consumed by the browser, including callbacks around preset system actions. Custom task scripts also return UI results in foreground scriptOutputs; see Task Buttons for its completion boundary.
export default async function main(
payload: FormButtonRuntimePayload,
_context: StudioScriptContext,
) {
return { ok: true, effects: [] };
}
Payload
type FormButtonRuntimePayload = {
schema: 'soln.runtime-context/v1';
source: {
type: 'form_button';
buttonId: string;
buttonType: 'preset' | 'custom';
placement: string;
operation: string;
phase: 'beforeClick' | 'action' | 'afterClick';
};
form: {
id: string;
apiName: string;
name: string | null;
} | null;
record: RuntimeRecord | null;
draft: { data: Record<string, unknown> } | null;
selection: {
records: RuntimeRecord[];
childRows: Array<{ id: string | null; data: Record<string, unknown> }>;
};
child: {
form: { id: string; apiName: string; name: string | null };
relationFieldApiName: string | null;
row: {
id: string | null;
data: Record<string, unknown>;
} | null;
} | null;
input: Record<string, unknown>;
result: unknown | null;
runtime: {
locale: string;
timezone: string;
executionId: string | null;
traceId: string | null;
};
};
Base Context
| Field | Type | Description |
|---|---|---|
schema | 'soln.runtime-context/v1' | Shared runtime context version |
source.type | 'form_button' | Identifies the button execution source |
source.phase | 'beforeClick' | 'action' | 'afterClick' | Current execution phase |
form.id | string | Form schema ID when a form is available |
form.apiName | string | Form API name when a form is available |
source.buttonId | string | Button identifier |
source.buttonType | 'preset' | 'custom' | Whether the button is built in or custom |
source.placement | string | Runtime placement such as FORM_HEADER, LIST_ROW, or LIST_BATCH |
source.operation | string | Operation name such as submit, save, saveDraft, or custom |
draft.data | Record<string, unknown> | Current draft values keyed by field API name |
record | RuntimeRecord | null | Existing record identity. Usually null on create pages; record.data is not preloaded for button bindings |
result | unknown | null | Completed action result. Mainly useful in afterClick |
runtime.locale | string | Browser locale such as en-US or zh-CN |
runtime.timezone | string | Browser timezone such as Asia/Shanghai |
Read current form values from payload.draft.data. When a script specifically needs persisted values, first require payload.record?.id, then call context.form.get({ recordId: payload.record.id }).
Child Table Context
| Field | Type | Description |
|---|---|---|
child.form | object | Child-form identity when a button is clicked from a child table |
child.relationFieldApiName | string | null | Relation field that connects the child form |
child.row | object | null | Current child row for row buttons |
selection.childRows | Array<object> | Selected child rows for batch buttons |
Child-table drafts are also available in payload.draft.data.__childFormDrafts[childFormApiName] as an array of row objects.
| Placement | Extra payload |
|---|---|
FORM_LIST_HEADER | child.form |
FORM_LIST_BATCH | child.form and selection.childRows |
FORM_LIST_ROW | child.form and child.row |
Response
Unknown response properties are ignored.
type FormButtonRuntimeResponse = {
ok?: boolean;
preventDefault?: boolean;
message?: string;
fieldErrors?: Record<string, string>;
patch?: {
draft?: Record<string, unknown>;
record?: Record<string, unknown>;
};
effects?: FormRuntimeEffect[];
notification?: RuntimeNotificationShortcut;
modal?: RuntimeModalShortcut;
};
| Field | Type | Description |
|---|---|---|
ok | boolean | Whether the phase can continue. Missing values are treated as true |
preventDefault | boolean | Explicitly stops the current button action when true |
message | string | Shows a simple runtime message |
fieldErrors | Record<string, string> | Sets field validation errors by field API name |
patch.draft | Record<string, unknown> | Merges values into the current draft state |
patch.record | Record<string, unknown> | Merges values into the current record state |
effects | FormRuntimeEffect[] | Ordered runtime effects |
notification | object | string | Shortcut for one top-level notification effect |
modal | object | string | Shortcut for one top-level modal effect |
If ok is false, preventDefault is true, or a confirm modal with awaitAction: true is cancelled, the runtime stops the current button action.
Effects
Effects are runtime UI instructions. They do not change form design configuration.
This section describes the form_button script return protocol (return { effects: [...] }). It is separate from the Studio page client API applyEffects, which writes to a host new/edit form draft; see Soln Studio. The Studio page API supports fieldValue, childFieldValue, childRowAdd, and childRowRemove only and does not inherit the current child row as an implicit target.
| Effect | Purpose |
|---|---|
fieldState | Overrides parent field hidden, required, readonly, or disabled state |
fieldOptionFilter | Filters a parent choice field's configured options by stable option values |
fieldValue | Sets a parent field value |
fieldError | Displays a parent field validation error |
fieldErrorClear | Clears a parent field validation error |
childFieldState | Overrides child-table field hidden, required, readonly, or disabled state |
childRowState | Overrides child-table row state |
childFieldValue | Sets a child-table field value |
childFieldError | Displays a child-table field validation error |
childFieldErrorClear | Clears child-table field validation errors |
childRowAdd | Appends one or more draft rows to a child table |
childRowRemove | Removes one or more draft rows from a child table |
message | Shows a simple message |
notification | Shows a richer toast |
modal | Shows a modal dialog |
refresh | Requests a runtime refresh |
navigate | Opens a workspace page; a new form can receive parent fields and child rows |
Navigation and New Form Prefill
Use navigate to open a page, with data and childTables to prefill a new form.
Interaction buttons open Studio pages as their main action. For a script that opens a new form and prefills data, use a custom task button: when its foreground response contains script outputs, the browser applies the returned navigate effect. If the request returns before script outputs are available, later background completion does not navigate the browser automatically.
When an interaction button’s before-click callback navigates successfully, the browser stops the remaining button action and does not also open its configured Studio page.
TypeScript scripts can use the built-in StudioScriptNavigateEffect type for completion and payload checks.
return {
ok: true,
effects: [{
type: 'navigate',
path: '/forms/runtime/orders/new',
data: { description: 'Copied from the current record' },
childTables: { order_lines: [{ product: 'product-record-id', quantity: 2 }] },
}],
};
| Property | Type | Description |
|---|---|---|
type | 'navigate' | Navigation effect |
path | string | Registered workspace path starting with /, opened in the current tab. External URLs, query strings, and fragments are not accepted |
data | Record<string, unknown> | Optional parent values keyed by target field API name; allowed only on /forms/runtime/{formApiName}/new |
childTables | Record<string, Record<string, unknown>[]> | Optional arrays keyed by target child form API name; each row contains target child field values. Allowed only on the new form page |
To carry persisted main and child data from a view page, read it with context.form.get() and explicitly map it to the target form. Replace every example form/field API name with your actual configuration:
export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
if (!payload.record?.id) {
return { ok: false, message: 'Select a source record first.' };
}
const source = await context.form.get({ recordId: payload.record.id });
if (!source) return { ok: false, message: 'Source record is not accessible.' };
const lines = source.childTables.find(
(table) => table.childFormApiName === 'source_lines',
)?.items || [];
return {
ok: true,
effects: [{
type: 'navigate',
path: '/forms/runtime/orders/new',
data: {
source_record: source.id, // Source main record ID, same as payload.record.id
customer: source.data.customer,
description: source.data.description,
},
childTables: {
order_lines: lines.map((line) => ({
source_line: line.id, // Source child record ID
product: line.data.product,
quantity: line.data.quantity,
})),
},
}],
};
}
The source main record ID is payload.record.id or source.id; each source child record ID is line.id in the selected child table's items. Both IDs are at the record's top level, not in source.data.id or line.data.id. childFormApiName identifies the child form, not an individual child record.
In this example, source_record is a writable relation field on the target main form pointing to the source main form; source_line is a writable relation field on the target child form pointing to the source child form. Configure these fields and replace their API names with your actual ones, or remove the mappings if source links are not needed.
The new record is unsaved; the user must still save or submit it. Only configured, writable target fields are filled. Readonly, serial-number, and calculated fields are not copied. Do not use source IDs as the new records' own id values or copy the child rows' parent owner links; new records receive their own IDs and parent links when saved. To retain source links, pass source record IDs through relation fields as shown above.
On an unsaved create/edit page, use payload.draft.data for current parent values and payload.draft.data.__childFormDrafts[childFormApiName] for current child rows, then map the values to target API names in the same way.
Carried data does not appear in the URL and is cleared when leaving or refreshing. Unsaved source edits prompt a confirmation first. Put navigate last in effects. To navigate without prefilling:
return { effects: [{ type: 'navigate', path: '/forms/runtime/orders' }] };
Carry Multiple Child Tables
childTables accepts multiple tables at once, keyed by target child form API name, each with its own row array. For example, prefill both product lines and expense lines on the order create page:
return {
effects: [{
type: 'navigate',
path: '/forms/runtime/orders/new',
data: {
customer: 'customer-record-id',
},
childTables: {
order_products: [
{ product: 'product-record-id', quantity: 2 },
],
order_expenses: [
{ description: 'Shipping', amount: 20 },
],
},
}],
};
Put the row arrays in one childTables object, keyed by target child form API name.
An invalid field stops the entire prefill and identifies the table, row, and field. Omitted tables initialize normally; [] supplies no rows. Tables not configured on the target page are ignored.
Field value types
Parent and child values must match the target field types. An error stops the entire prefill and shows a path such as childTables.order_lines[2].quantity (row 2). Required fields and access permissions are still checked on submit.
| Target field | Value to pass |
|---|---|
| Text, textarea, autocomplete, email, link | String |
| Number | Finite number, e.g. 2, not "2" |
| Switch | true or false; strings, numbers, and null are rejected |
| Select/radio | A configured option value, not its label |
| Multi-select/checkbox group | Array of configured option values |
| Relation, foreign key, department, organization | Record ID string; multi-value variants use ID arrays |
| Member | Member ID string or { principalType: 'MEMBER', principalId: '...' }; multi-member uses an array |
| File, image, video, audio | Array of file ID strings, not URLs or file objects |
| Location | Object containing string address parts, numeric latitude (-90–90) and longitude (-180–180), and optional provider (tianditu, mapbox, google) |
| Date, week, month, quarter, year | A valid YYYY-MM-DD date; valid ISO timestamps from draft values are also accepted |
| Datetime | Valid ISO datetime with offset/Z, or workspace-local YYYY-MM-DD HH:mm:ss |
| Time | HH:mm or HH:mm:ss, in the 00:00–23:59 range |
| Date/datetime/time range | Exactly two entries [start, end]; an empty endpoint may be null, subject to submit validation |
| Multiple dates | Array of valid dates; invalid or null entries are rejected |
Omit a field to leave its normal initialization in place. Except for switches, null explicitly clears a field; use [] for an empty multi-value selection. Dates such as 2026-02-30, unknown option values, malformed arrays, and invalid location coordinates are rejected.
Opening an edit page
Edit pages can be opened, but do not accept prefill data. They load the existing record using normal permissions. Passing data or childTables to an edit/view/list path is rejected. Opening an edit page does not update the record:
return {
effects: [{
type: 'navigate',
path: '/forms/runtime/orders/edit/record-id',
}],
};
Parent Field Effects
{
type: 'fieldState',
field: 'closeReason',
hidden: false,
required: true,
readonly: false,
disabled: false,
}
{
type: 'fieldValue',
field: 'status',
value: 'submitted',
}
{
type: 'fieldError',
field: 'amount',
message: 'Amount must be greater than zero.',
}
| Field | Type | Applies to | Description |
|---|---|---|---|
type | string | all | fieldState, fieldOptionFilter, fieldValue, fieldError, or fieldErrorClear |
field | string | all | Parent field API name |
allowedValues | string[] | fieldOptionFilter | Stable option values that remain selectable |
clearInvalidValue | boolean | fieldOptionFilter | Clears values that are no longer allowed |
reset | boolean | fieldOptionFilter | Restores the original configured options |
hidden | boolean | fieldState | Hides or shows the field |
required | boolean | fieldState | Changes whether the field is required |
readonly | boolean | fieldState | Changes whether the field is read-only |
disabled | boolean | fieldState | Changes whether the field is disabled |
value | unknown | fieldValue | New field value |
message | string | fieldError | Error text shown on the field |
Child Field Effects
Use table for the child form API name. You can also use childTable, formApiName, or childFormApiName.
Use where to target rows by child-field values. If where is omitted, the effect applies to every current row in that child table.
{
type: 'childFieldState',
table: 'orderItems',
field: 'discount',
where: {
logic: 'and',
children: [
{ field: 'productType', operator: 'eq', value: 'service' },
],
},
readonly: true,
required: false,
}
{
type: 'childFieldValue',
table: 'orderItems',
field: 'currency',
where: {
logic: 'and',
children: [
{ field: 'region', operator: 'eq', value: 'US' },
],
},
value: 'USD',
}
{
type: 'childFieldError',
table: 'orderItems',
field: 'quantity',
where: {
logic: 'and',
children: [
{ field: 'quantity', operator: 'lte', value: 0 },
],
},
message: 'Quantity must be greater than zero.',
}
{
type: 'childFieldErrorClear',
table: 'orderItems',
field: 'quantity',
where: {
logic: 'and',
children: [
{ field: 'quantity', operator: 'gt', value: 0 },
],
},
}
| Field | Type | Applies to | Description |
|---|---|---|---|
type | string | all | childFieldState, childFieldValue, childFieldError, or childFieldErrorClear |
table | string | all | Child form API name |
field | string | all | Child field API name |
where | ApprovalFlowConditionGroup | all | Row filter evaluated against each child row |
hidden | boolean | childFieldState | Hides or shows the child field. Hidden child fields clear their draft value |
required | boolean | childFieldState | Changes whether the child field is required |
readonly | boolean | childFieldState | Changes whether the child field is read-only |
disabled | boolean | childFieldState | Changes whether the child field is disabled |
value | unknown | childFieldValue | New child field value |
message | string | childFieldError | Child field error text |
Child Row Effects
{
type: 'childRowAdd',
table: 'orderItems',
rows: [
{
productName: 'Standard service',
quantity: 1,
currency: 'USD',
},
{
productName: 'Implementation',
quantity: 1,
currency: 'USD',
},
],
}
{
type: 'childRowRemove',
table: 'orderItems',
where: {
logic: 'and',
children: [
{ field: 'status', operator: 'eq', value: 'cancelled' },
],
},
}
| Field | Type | Applies to | Description |
|---|---|---|---|
type | string | all | childRowState, childRowAdd, or childRowRemove |
table | string | all | Child form API name |
selected | boolean | childRowState | Marks matching rows as selected |
backgroundColor | string | childRowState | Runtime background color for matching rows |
hoverBackgroundColor | string | childRowState | Runtime hover background color for matching rows |
data | Record<string, unknown> | childRowAdd | Single row to append |
rows | Array<Record<string, unknown>> | childRowAdd | Multiple rows to append. When rows is present, data is ignored |
where | ApprovalFlowConditionGroup | childRowState, childRowRemove | Matching rows are updated or removed from the current draft |
Feedback Effects
{
type: 'message',
level: 'warning',
text: 'Please review the highlighted fields.',
}
{
type: 'notification',
level: 'info',
title: 'Validation completed',
description: 'The record passed the external validation.',
placement: 'topRight',
duration: 4,
closable: true,
width: 480,
maxHeight: 320,
}
{
type: 'modal',
level: 'confirm',
title: 'Continue submission?',
content: 'This amount is high. Continue submitting this record?',
okText: 'Continue',
cancelText: 'Cancel submit',
awaitAction: true,
}
| Field | Type | Applies to | Description |
|---|---|---|---|
type | string | all | message, notification, or modal |
level | string | all | success, info, warning, error; modal also supports confirm |
text | string | message | Simple message text |
title | string | notification, modal | Title text |
description | string | notification | Notification body text |
content | string | modal | Modal body text |
okText | string | modal | OK button text |
cancelText | string | modal | Cancel button text for confirm modals |
awaitAction | boolean | modal | When true on a confirm modal, waits for the user and cancels the action if they cancel |
placement | string | notification | Toast position |
duration | number | notification | Duration in seconds |
closable | boolean | notification | Whether a close control is shown |
centered | boolean | modal | Whether the modal is vertically centered in the viewport |
width | number | string | notification, modal | Width |
height | number | string | notification, modal | Fixed body height |
maxHeight | number | string | notification, modal | Maximum body height |
Top-level notification and modal shortcuts accept the same parameters except type.
Refresh
{
type: 'refresh',
target: 'record',
}
| Field | Type | Description |
|---|---|---|
type | 'refresh' | Refresh request |
target | 'record' | 'list' | 'children' | 'all' | Requested refresh target. Support depends on the current surface |
Examples
Show Current Data in a Modal
Publish this component as a Studio page. Select it for a view-page interaction button and choose Modal.
import { getRuntimeContext } from '@soln/studio';
export default function App() {
const payload = getRuntimeContext();
return (
<pre>{JSON.stringify({
recordId: payload?.record?.id,
data: payload?.draft?.data,
childRows: payload?.selection?.childRows,
child: payload?.child,
}, null, 2)}</pre>
);
}
Parent values are in draft.data; child values are in draft.data.__childFormDrafts. Create pages have no record ID. To read saved data, call context.form.get() in a page server script.
Confirm Before Opening
Use as the before-click script. Confirming opens the page; cancelling stops it.
export default async function main() {
return {
ok: true,
modal: {
level: 'confirm',
title: 'Continue?',
content: 'Open the interaction page?',
awaitAction: true,
},
};
}
Fill a Description and Make It Required
Use as the before-click script on a create/edit page to fill the description and make it required.
export default async function main() {
return {
ok: true,
patch: { draft: { description: 'Ready for review' } },
effects: [{ type: 'fieldState', field: 'description', required: true }],
};
}
This only changes the draft. Save the form to persist it.
Open Selected Records in a Drawer
Add an interaction button to the list batch toolbar, select a Studio page, and choose Drawer. This before-click script checks that records are selected.
export default async function main(payload: FormButtonRuntimePayload) {
if (payload.selection.records.length === 0) {
return { ok: false, message: 'Select at least one record.' };
}
return { ok: true };
}
Use this component in the Studio page:
import { getRuntimeContext } from '@soln/studio';
export default function App() {
const records = getRuntimeContext()?.selection?.records || [];
return (
<ul>
{records.map((record) => <li key={record.id}>{record.id}</li>)}
</ul>
);
}
Check the Entered Amount
Use as the before-click script on a create/edit page. Invalid amounts display a field error and stop the page from opening.
export default async function main(payload: FormButtonRuntimePayload) {
const amount = payload.draft?.data?.amount;
if (typeof amount !== 'number' || !Number.isFinite(amount) || amount <= 0) {
return {
ok: false,
fieldErrors: { amount: 'Amount must be greater than zero.' },
};
}
return {
ok: true,
effects: [{ type: 'fieldErrorClear', field: 'amount' }],
};
}
Set Currency on Parent and Child Rows
Use as the before-click script on a create/edit page to set CNY on the parent and existing rows in two child tables.
export default async function main() {
return {
ok: true,
effects: [
{ type: 'fieldValue', field: 'currency', value: 'CNY' },
{
type: 'childFieldValue',
table: 'order_products',
field: 'currency',
value: 'CNY',
},
{
type: 'childFieldValue',
table: 'order_expenses',
field: 'currency',
value: 'CNY',
},
],
};
}
Replace the table and field API names. This only changes the draft. Choice fields need configured option values, not labels.
Remove Empty Lines and Add an Expense
Use as the before-click script on a create/edit page to remove zero-quantity product lines and add a shipping expense.
export default async function main() {
return {
ok: true,
effects: [
{
type: 'childRowRemove',
table: 'order_products',
where: {
logic: 'and',
children: [{ field: 'quantity', operator: 'eq', value: 0 }],
},
},
{
type: 'childRowAdd',
table: 'order_expenses',
rows: [{ description: 'Shipping', amount: 20 }],
},
],
};
}
Changes are saved with the form. Each click adds an expense row; check for an existing row if needed.
Show a Message After Opening
Use as the after-click script to show a message.
export default async function main() {
return {
ok: true,
effects: [{
type: 'message',
level: 'info',
text: 'The interaction page is opening.',
}],
};
}
This means the page is opening, not that the user has saved data.
Open a New Form with Data
See Navigation and New Form Prefill, including multiple child tables.
Use a custom task button for a navigation script main action. The script outputs must arrive in the foreground response; background completion alone does not navigate the browser.
Runtime Limits
source.buttonTypeispreset/custom, distinct from the design settingtask/interaction.- Effects change runtime UI or draft state, not field design. Requiredness uses the current runtime state.
refreshis currently validated and normalized without a refresh handler; do not rely on it to reload data.- Navigation, new-page prefill, and database writes are separate operations. Prefill does not save a record.