Skip to main content

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​

RequirementButton type
Update records, call an external service, or execute server business logicCustom task button
Submit configured approval or automation workflowsTask button; workflow submission is separate from final workflow completion
Open a Studio page for user interactionInteraction button
Change the current page UI or prefill another formCustom task scripts whose outputs are returned to the foreground browser; or browser-consumed UI callbacks

Configuration​

  1. Add a custom button in Button Design and select Task Button.
  2. Select the Studio script and its entry file for the main click action.
  3. Optionally configure before-click and after-click scripts.
  4. 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:

PhaseBehavior
beforeClickValidates input and can stop execution
actionRuns the main Studio server script
Workflow submissionSubmits configured button workflows after the action succeeds
afterClickRuns 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 };
}
PropertyMeaning
schemasoln.runtime-context/v1
source.typeform_button
source.phasebeforeClick, action, or afterClick
source.buttonIdButton identifier
source.buttonTypepreset or custom; distinct from the design setting task/interaction
formCurrent form identity, including id and apiName
recordA single selected record, or null without a single record context
draft.dataValues supplied for this execution; use these for current input
selection.recordsSelected persisted records for batch execution
inputAdditional explicit caller input
resultMain action result available to afterClick
runtimeExecution 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 propertyServer task behavior
ok: false / preventDefault: trueStops the phase as an execution failure
Nonempty fieldErrors objectStops 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 resultWhen returned by the foreground request, the user-facing message is displayed with the task failure; errorCode remains available for diagnostics.
patch.draft / patch.recordMerges 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 valuesThe action output is available to afterClick through payload.result.output
effects, notification, modalConsumed 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.