Task Buttons
Task buttons execute business operations, submit configured workflows, or run custom server scripts. Set buttonType: 'task'; a custom button uses action.type: 'script'. Preset buttons retain their built-in product actions.
To open a Studio page in a modal or drawer, use an Interaction Button.
Choose a Button Type
| Requirement | Button type |
|---|---|
| Update records, call an external service, or execute server business logic | Custom task button |
| Submit configured approval or automation workflows | Task button; workflow submission is separate from final workflow completion |
| Open a Studio page for user interaction | Interaction button |
| Change the current page UI or prefill another form | Custom task scripts whose outputs are returned to the foreground browser; or browser-consumed UI callbacks |
Configuration
- Add a custom button in Button Design and select Task Button.
- Select the Studio script and its entry file for the main click action.
- Optionally configure before-click and after-click scripts.
- Configure approval/automation workflows when the button should trigger them.
For a workflow-only custom task, the main script can simply return { ok: true }; configure the workflow in Button Design. Do not call the approval submission SDK again unless a separate submission is explicitly intended.
Lifecycle
Custom main-form script task buttons are submitted to the server execution job path:
| Phase | Behavior |
|---|---|
beforeClick | Validates input and can stop execution |
action | Runs the main Studio server script |
| Workflow submission | Submits configured button workflows after the action succeeds |
afterClick | Runs after the action and workflow submission, receiving the action result |
An after-click failure does not roll back completed business writes. Scripts that perform several writes must design their own domain operation boundaries; the button lifecycle is not a transaction around all external calls.
Preset buttons, such as save and submit, keep their built-in execution paths. Their browser-side before/after callbacks can consume UI effects; do not assume every preset button runs as a background custom task.
Script Input
export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
return { ok: true };
}
| Property | Meaning |
|---|---|
schema | soln.runtime-context/v1 |
source.type | form_button |
source.phase | beforeClick, action, or afterClick |
source.buttonId | Button identifier |
source.buttonType | preset or custom; distinct from the design setting task/interaction |
form | Current form identity, including id and apiName |
record | A single selected record, or null without a single record context |
draft.data | Values supplied for this execution; use these for current input |
selection.records | Selected persisted records for batch execution |
input | Additional explicit caller input |
result | Main action result available to afterClick |
runtime | Execution metadata, including locale and workspace timezone |
Create pages may have no persisted record. Server task payloads can include persisted record data, while browser callbacks may provide only identity. Use context.form.get({ recordId }) when persisted values are required. Do not invent a record ID or use draft state as proof that a record was saved.
For browser callbacks, child row context, and the complete shared payload shape, see Interaction Buttons. Child-table local actions and browser callbacks must not be assumed to use the main-form background job path.
Return Values and Persistence
| Return property | Server task behavior |
|---|---|
ok: false / preventDefault: true | Stops the phase as an execution failure |
Nonempty fieldErrors object | Stops the phase as a validation failure; use { fieldApiName: 'message' }. When returned by the foreground request, these errors are applied to the form. |
message with a failed result | When returned by the foreground request, the user-facing message is displayed with the task failure; errorCode remains available for diagnostics. |
patch.draft / patch.record | Merges values into the server execution context without persistence; a returned draft patch can also update the browser draft when the foreground response is consumed |
| Other action result values | The action output is available to afterClick through payload.result.output |
effects, notification, modal | Consumed from foreground scriptOutputs; later background completion alone does not replay UI effects |
Use Soln SDK methods such as context.form.update() to persist changes. For navigation and prefill, return a navigate effect. The foreground response carries ordered scriptOutputs; the browser stops applying subsequent outputs after successful navigation. If no outputs are available when the foreground request returns, later background completion does not navigate automatically. A server task cannot pause for a browser confirmation modal returned from its script; UI results arrive after server execution and cannot authorize or undo writes that already ran.
Examples
Check the Amount Before Running
Use as the before-click script. Stops the action if the amount is not greater than zero.
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,
message: 'Amount must be greater than zero.',
fieldErrors: { amount: 'Amount must be greater than zero.' },
};
}
return { ok: true };
}
Update the Current Record
Use as the click script on a view-page button to change the current record’s description to “Reviewed”.
export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
const recordId = payload.record?.id;
if (!recordId) return { ok: false };
const record = await context.form.get({ recordId });
if (!record) return { ok: false };
const updated = await context.form.update({
recordId,
data: { description: 'Reviewed' },
});
if (!updated) throw new Error('RECORD_UPDATE_FAILED');
return { ok: true, recordId: updated.id };
}
This saves the change. Replace description with your field API name.
Start an Approval or Automation
Bind a workflow to the button, then use this click script. Applies to existing-record view buttons and list row or batch buttons.
export default async function main() {
return { ok: true };
}
Successful submission means the workflow has started, not that approval is complete.
Update Selected Records
Use as the click script on a list batch button to update the selected records’ descriptions.
export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
const records = payload.selection.records;
if (records.length === 0 || records.length > 100) {
return { ok: false };
}
const result = await context.form.batchUpdate({
records: records.map((record) => ({
recordId: record.id,
data: { description: 'Reviewed' },
})),
});
return { ok: true, updatedCount: result.total };
}
Updates at most 100 records at once. If any update fails, the whole batch is rolled back.
Send Order Lines to a Third Party
Use as the click script on a view-page button. Reads the current order and product lines, then sends them to an external API.
export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
const recordId = payload.record?.id;
if (!recordId) return { ok: false };
const source = await context.form.get({ recordId });
if (!source) return { ok: false };
const lines = source.childTables.find(
(table) => table.childFormApiName === 'order_products',
)?.items || [];
const response = await context.http.requestJson({
url: 'https://example.com/api/order-review',
method: 'POST',
json: {
recordId: source.id,
customer: source.data.customer,
lines: lines.map((line) => ({
product: line.data.product,
quantity: line.data.quantity,
})),
},
timeoutMs: 10000,
retry: { maxAttempts: 1 },
idempotency: `order-review:${context.runtime.traceId}`,
throwOnHttpError: false,
});
if (!response.ok) {
throw new Error(`ORDER_REVIEW_HTTP_${response.status}`);
}
return { ok: true, recordId: source.id, httpStatus: response.status };
}
Replace the endpoint, table, and field names. This reads saved values without changing Soln data. For in-approval values, see the approval SDK.
Read the Click Script Result
Pair this with the batch update example as the same button’s after-click script to log the updated count.
export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
const result = payload.result as { output?: { updatedCount?: number } } | null;
const count = result?.output?.updatedCount;
if (typeof count !== 'number') return { ok: false };
context.logger.info('Updated records:', count);
return { ok: true };
}
The click script return value is in payload.result.output. An after-click failure does not undo saved changes.
Execution Feedback
The task response contains a jobId and waitStatus: accepted, completed, or failed. An error can include errorCode; workflow submission can include workflowExecution.
After an approval task has been created successfully, the button can report successful submission while downstream approval and human tasks continue. This is not a guarantee that every subsequent workflow node has completed. Background completion can also generate an inbox notification in the Reminder app.
Use the interaction button's browser callbacks or Studio page for confirmations, navigation, and explicit UI feedback.