Skip to main content

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​

  1. Add a custom button in Button Design and select Interaction Button.
  2. Choose a published Studio page and configure its modal/drawer, title, and dimensions.
  3. Optionally attach before-click and after-click Studio scripts.
PhaseBehaviorCan stop subsequent actions
beforeClickRuns the script; the browser consumes returned UI effectsYes
actionOpens the configured Studio pageThe page action does not execute a Studio script
afterClickRuns after opening the page container and submitting configured workflowsDoes 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​

FieldTypeDescription
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.idstringForm schema ID when a form is available
form.apiNamestringForm API name when a form is available
source.buttonIdstringButton identifier
source.buttonType'preset' | 'custom'Whether the button is built in or custom
source.placementstringRuntime placement such as FORM_HEADER, LIST_ROW, or LIST_BATCH
source.operationstringOperation name such as submit, save, saveDraft, or custom
draft.dataRecord<string, unknown>Current draft values keyed by field API name
recordRuntimeRecord | nullExisting record identity. Usually null on create pages; record.data is not preloaded for button bindings
resultunknown | nullCompleted action result. Mainly useful in afterClick
runtime.localestringBrowser locale such as en-US or zh-CN
runtime.timezonestringBrowser 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​

FieldTypeDescription
child.formobjectChild-form identity when a button is clicked from a child table
child.relationFieldApiNamestring | nullRelation field that connects the child form
child.rowobject | nullCurrent child row for row buttons
selection.childRowsArray<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.

PlacementExtra payload
FORM_LIST_HEADERchild.form
FORM_LIST_BATCHchild.form and selection.childRows
FORM_LIST_ROWchild.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;
};
FieldTypeDescription
okbooleanWhether the phase can continue. Missing values are treated as true
preventDefaultbooleanExplicitly stops the current button action when true
messagestringShows a simple runtime message
fieldErrorsRecord<string, string>Sets field validation errors by field API name
patch.draftRecord<string, unknown>Merges values into the current draft state
patch.recordRecord<string, unknown>Merges values into the current record state
effectsFormRuntimeEffect[]Ordered runtime effects
notificationobject | stringShortcut for one top-level notification effect
modalobject | stringShortcut 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.

EffectPurpose
fieldStateOverrides parent field hidden, required, readonly, or disabled state
fieldOptionFilterFilters a parent choice field's configured options by stable option values
fieldValueSets a parent field value
fieldErrorDisplays a parent field validation error
fieldErrorClearClears a parent field validation error
childFieldStateOverrides child-table field hidden, required, readonly, or disabled state
childRowStateOverrides child-table row state
childFieldValueSets a child-table field value
childFieldErrorDisplays a child-table field validation error
childFieldErrorClearClears child-table field validation errors
childRowAddAppends one or more draft rows to a child table
childRowRemoveRemoves one or more draft rows from a child table
messageShows a simple message
notificationShows a richer toast
modalShows a modal dialog
refreshRequests a runtime refresh
navigateOpens a workspace page; a new form can receive parent fields and child rows

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 }] },
}],
};
PropertyTypeDescription
type'navigate'Navigation effect
pathstringRegistered workspace path starting with /, opened in the current tab. External URLs, query strings, and fragments are not accepted
dataRecord<string, unknown>Optional parent values keyed by target field API name; allowed only on /forms/runtime/{formApiName}/new
childTablesRecord<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 fieldValue to pass
Text, textarea, autocomplete, email, linkString
NumberFinite number, e.g. 2, not "2"
Switchtrue or false; strings, numbers, and null are rejected
Select/radioA configured option value, not its label
Multi-select/checkbox groupArray of configured option values
Relation, foreign key, department, organizationRecord ID string; multi-value variants use ID arrays
MemberMember ID string or { principalType: 'MEMBER', principalId: '...' }; multi-member uses an array
File, image, video, audioArray of file ID strings, not URLs or file objects
LocationObject containing string address parts, numeric latitude (-90–90) and longitude (-180–180), and optional provider (tianditu, mapbox, google)
Date, week, month, quarter, yearA valid YYYY-MM-DD date; valid ISO timestamps from draft values are also accepted
DatetimeValid ISO datetime with offset/Z, or workspace-local YYYY-MM-DD HH:mm:ss
TimeHH:mm or HH:mm:ss, in the 00:00–23:59 range
Date/datetime/time rangeExactly two entries [start, end]; an empty endpoint may be null, subject to submit validation
Multiple datesArray 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.',
}
FieldTypeApplies toDescription
typestringallfieldState, fieldOptionFilter, fieldValue, fieldError, or fieldErrorClear
fieldstringallParent field API name
allowedValuesstring[]fieldOptionFilterStable option values that remain selectable
clearInvalidValuebooleanfieldOptionFilterClears values that are no longer allowed
resetbooleanfieldOptionFilterRestores the original configured options
hiddenbooleanfieldStateHides or shows the field
requiredbooleanfieldStateChanges whether the field is required
readonlybooleanfieldStateChanges whether the field is read-only
disabledbooleanfieldStateChanges whether the field is disabled
valueunknownfieldValueNew field value
messagestringfieldErrorError 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 },
],
},
}
FieldTypeApplies toDescription
typestringallchildFieldState, childFieldValue, childFieldError, or childFieldErrorClear
tablestringallChild form API name
fieldstringallChild field API name
whereApprovalFlowConditionGroupallRow filter evaluated against each child row
hiddenbooleanchildFieldStateHides or shows the child field. Hidden child fields clear their draft value
requiredbooleanchildFieldStateChanges whether the child field is required
readonlybooleanchildFieldStateChanges whether the child field is read-only
disabledbooleanchildFieldStateChanges whether the child field is disabled
valueunknownchildFieldValueNew child field value
messagestringchildFieldErrorChild 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' },
],
},
}
FieldTypeApplies toDescription
typestringallchildRowState, childRowAdd, or childRowRemove
tablestringallChild form API name
selectedbooleanchildRowStateMarks matching rows as selected
backgroundColorstringchildRowStateRuntime background color for matching rows
hoverBackgroundColorstringchildRowStateRuntime hover background color for matching rows
dataRecord<string, unknown>childRowAddSingle row to append
rowsArray<Record<string, unknown>>childRowAddMultiple rows to append. When rows is present, data is ignored
whereApprovalFlowConditionGroupchildRowState, childRowRemoveMatching 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,
}
FieldTypeApplies toDescription
typestringallmessage, notification, or modal
levelstringallsuccess, info, warning, error; modal also supports confirm
textstringmessageSimple message text
titlestringnotification, modalTitle text
descriptionstringnotificationNotification body text
contentstringmodalModal body text
okTextstringmodalOK button text
cancelTextstringmodalCancel button text for confirm modals
awaitActionbooleanmodalWhen true on a confirm modal, waits for the user and cancels the action if they cancel
placementstringnotificationToast position
durationnumbernotificationDuration in seconds
closablebooleannotificationWhether a close control is shown
centeredbooleanmodalWhether the modal is vertically centered in the viewport
widthnumber | stringnotification, modalWidth
heightnumber | stringnotification, modalFixed body height
maxHeightnumber | stringnotification, modalMaximum body height

Top-level notification and modal shortcuts accept the same parameters except type.

Refresh​

{
type: 'refresh',
target: 'record',
}
FieldTypeDescription
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.buttonType is preset/custom, distinct from the design setting task/interaction.
  • Effects change runtime UI or draft state, not field design. Requiredness uses the current runtime state.
  • refresh is 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.