Automation Task Design Canvas
The design canvas defines how a custom task starts and what it does: the trigger method, record scope, execution policy, and the processing nodes and branches between the start node and the end node.
Open Automation Tasks and choose Open design canvas on a task.
The canvas has four parts:
| Part | Location | Responsibility |
|---|---|---|
| Top actions | Canvas top bar | Back, copy, save, save and publish, and the current version or a historical snapshot |
| Node palette | Left | Click a node to add it to the canvas |
| Canvas | Center | Node arrangement and connections |
| Inspector | Right | Configures the selected node and shows an unsaved or saved state |
1. Top Actions
| Action | Description |
|---|---|
| Back | Returns to the task list; unsaved changes ask for confirmation first |
| Current version / historical snapshot | The top label shows the version being edited; viewing an older version shows "Historical snapshot vN" |
| Copy | Creates a new task from the current validated canvas, named "original name - copy" by default |
| Save | Saves the current canvas as a new draft version |
| Save and publish | Saves the canvas and publishes that version immediately |
Saving or publishing first opens the basic info dialog, where the name and description can be changed; the code is read-only.
2. Trigger And Record Scope
Trigger Methods
A task has exactly one trigger, and it must be complete before saving.
| Trigger | Settings | Description |
|---|---|---|
| Manual | Bind form, form, execution scope, data scope | Started from the task list with Run now after selecting a record |
| Schedule | Schedule mode, form and scope settings, execution policy | Runs on a Cron expression or a fixed interval |
| Data change | Form, data action, listened fields | Starts when a form record performs the selected action |
| Form button | Form, custom button, overlap policy | Starts from a record view, list page, or a child/related table on a view page |
Form Button
Use a button trigger when an automation should be an explicit action on form records, such as “Generate contract”, “Start sync”, or “Notify owner”.
- Create and enable a custom button in Button Design for the target form.
- Select View Page - Header, List Page - Row Action, List Page - Batch Action, View Page List - Row Action, or View Page List - Batch Action. The placement determines the applicable page: view-page placements use View Page, and list-page placements use List Page.
- Return to the automation design canvas and select Form button as the trigger.
- Select the form and custom button, then configure the overlap policy.
- Save and publish the task, and enable it from the Automation Tasks list.
- Select the button at its configured location. For a batch action, select records in the list, child table, or related table first.
A button trigger binds the selected form. Its location determines the execution scope, without a separate record filter:
| Button location | Execution target |
|---|---|
| View Page - Header | Current view-page record, one single-record execution |
| View Page List - Row Action | Record in that view-page list row, one single-record execution |
| View Page List - Batch Action | Only records selected in that view-page list, one batch execution with a child execution per selected record |
| List Page - Row Action | Record in that list-page row, one single-record execution |
| List Page - Batch Action | Only records selected on the list page, one batch execution with a child execution per record; unselected records are not included |
A View Page List can be a child-form list or a related-form list. Its button binds the form represented by that list. The current automation record is the row record or selected list record, not the main record displayed on the view page. Selecting the button still runs its configured click script and approval. Every enabled automation task published for that button starts separately, subject to its overlap policy.
The selector lists enabled custom buttons in these five placements when their applicable page matches, and shows the placement. If a button is deleted, disabled, or its placement/applicable page changes, the existing version fails resource validation. Select a valid button and publish again. Republish an older view-page version before changing it to a list-page placement.
Reopening the trigger settings reuses the loaded custom button list for the same form.
A form button trigger records the member who clicked it. Every child execution in a batch uses the same clicker. Later nodes can use Variable → Button clicker. Switching to another trigger type clears existing Button clicker selections on the canvas and keeps other people and field settings.
Approval and automation submissions for one button click are committed together on the server. If any selected record fails submission validation, the whole submission is rolled back and the error is returned. After a successful submission, background workers run the workflows even if you close the page. This does not roll back later workflow execution failures or the button’s click scripts, and automation does not wait for approval to finish.
Schedule Modes
| Mode | Description |
|---|---|
| Cron | Provide a Cron expression |
| Fixed interval | Provide an interval value and unit: seconds, minutes, hours, days, weeks, months, or years |
Data Change
- Select the form
- Select the data actions to listen for: create, update, or delete
- Select the listened fields: all fields, or only the selected ones
Data-change and form-button tasks take their form and execution target from the trigger itself, so they do not configure a separate record scope.
Record Scope
| Setting | Description |
|---|---|
| Bind form | Optional for manual and schedule triggers; data change and form button triggers bind the selected form automatically; data processing, human processing, branch, and recipient fields depend on the bound form |
| Execution scope | Manual triggers can use one record or a batch; schedule triggers always run as a batch; View Page - Header, List Page - Row Action, and View Page List - Row Action use one record; List Page - Batch Action and View Page List - Batch Action use only the selected records |
| Data scope (batch) | Records matching the filter requires a filter; All records shows the warning that the task runs for every record of the form |
| Overlap policy | Skip while running, queue all runs, or replace the current execution |
| Missed run policy | Skip the run, or run it once when a scheduled run was missed, for example during downtime |
3. Node Palette
| Node | Purpose | Main settings |
|---|---|---|
| Start | Automation entry point; a canvas keeps one start node | None |
| Data Processing | Create, update, or delete form data | Action, target form, approvals, field assignments |
| Human Processing | Continue after a user processes form data | Assignees, processing target, target form, relation field, fields to handle, default values |
| Agent Execution | Runs a selected agent with a task instruction and returns its result | Agent, execution timing, task instruction |
| Service Call | Calls a Studio script or an integration flow | Service type, script or integration flow |
| Message | Sends an app message or a group chat message | Channel, template, recipients, input mapping |
| Visualization | Returns a report link for subsequent nodes | Report or chart |
| Wait Callback | Waits for an inbound webhook callback before continuing | Inbound webhook flow, correlation key, wait timeout |
| Branch | Chooses the next path from the current record conditions | Conditions, Y/N outputs |
| End | Automation completed; a canvas keeps one end node | None |
4. Node Configuration
Data Processing Node
- Bind a form in the trigger first, then add the data processing node
- Choose the action: create, update, or delete data
- Creating data selects a target form; updating and deleting act on the current record
- Creating data can submit approvals after creation, and updating data can submit approvals after the update
- Configure the field assignments, then save the version
Field assignments support four value sources: a specified value, an empty value, the trigger record field, and a node output (select an upstream node and provide its output path, such as result.documentId).
For form button triggers, Button clicker is also available as a trigger source. It writes the clicking member's ID.
| Action | Required audit fields | Optional audit fields |
|---|---|---|
| Create | Created by | Updated by |
| Update | Updated by | None |
| Delete | None | None |
On regular forms the created-by and updated-by fields are the system fields __system_createdBy and __system_updatedBy; on the built-in organization, department, and member forms they are so_createdBy and so_updatedBy. Required fields are added automatically and cannot be removed.
Human Processing Node
- Open Configure people and select fixed members, data fields, or Button clicker under Variable for form button triggers
- Choose the processing target: edit current data, create new data, edit related form data, or select existing data and relate it
- Complete the target form, the required flag, and the relation field for the chosen target
- Configure the fields to handle by adding fields from the left panel, marking them as required during processing when needed
- Optionally provide default values for created data and choose whether the submission triggers form approvals
| Processing target | Required settings | Description |
|---|---|---|
| Edit current data | Fields to handle | Works on the current record |
| Create new data | Target form, required flag | The assignee creates a new record |
| Edit related form data | Target form, relation field, fields to handle | Locates the target data through a relation field of the current record |
| Select existing data and relate | Target form, relation field | The assignee selects an existing record and creates the relation |
Execution moves to the state "waiting for human action" at this node and continues after the assignee submits.
The Configure people dialog hides Data field when no member fields are available.
Agent Execution Node
- Select an active agent, enabling one in Luna first when none is available
- Choose the execution timing: on success, on failure, or always
- Enter the task instruction: describe only what this run must do and return, without repeating the agent responsibilities or general rules
| Timing | Description |
|---|---|
| On success | Runs after the automation completes normally |
| On failure | Runs only after the automation fails, with the failing node and error code passed to the agent |
| Always | Runs on both success and failure |
Service Call Node
A service call runs a Studio script or an integration flow, and both must be published before they can be selected.
- Prepare and publish the script or integration flow in Soln Studio or OpenLink
- Add the service call node and choose the service type (Studio script or integration flow)
- Select the script and its entry file, or select a published integration flow
- Use the payload preview to confirm the field API names the script reads
- Connect one input and one output, then save and publish
What The Call Target Receives
The node passes the soln.runtime-context/v1 context to the script or the integration flow, and the inspector can copy the current preview.
| Field | Purpose |
|---|---|
source.type | Always automation |
source.definitionId, source.executionId, source.nodeKey | The automation definition, this execution, and the current node |
source.trigger | Trigger snapshot (manual, schedule, data change, or form button and its settings) |
source.trigger.buttonClickerId | ID of the member who clicked the form button |
source.steps | Step output of the nodes that already ran |
form, record | Form information and the current record snapshot; field values live in record.data |
result | Result of the upstream node |
runtime.traceId | Trace ID of this node execution, usable as the idempotency key of an external request |
Later nodes can also read the source type, source definition or execution ID, source node key, upstream result, runtime language and time zone, form ID/API name/name, and the failure code and message through input mappings.
Message Node
| Setting | Description |
|---|---|
| Channel | App message or group chat |
| App channel | Required for app messages; uses the message channel of the selected app |
| Message template | Required; the template defines the message content and the available input variables |
| Recipients | Fixed recipients, member fields of a related form, or Variable → Button clicker for form button triggers; binding a form is required before using data-field recipients |
| Group send by recipient | Only for batch tasks with a bound form, and a recipient field must be selected |
| Group chat | Required for group chat messages: the sending agent and the target group chat; a chat cannot be selected when the agent is not in any chat |
| Input mapping | Maps context paths or fixed values to the input variables declared by the template |
The recipient Configure people dialog hides Data field when no member fields are available. Input mappings can also read source.trigger.buttonClickerId.
Visualization Node
- Select a saved report or chart
- Save and publish the version
- Connect its output to a subsequent Agent Execution or Message node
The node returns a report link containing kind: analysis_report_link, chartId, path, and Markdown text. Configure the message channel and recipients in a subsequent Message node.
For automatic analysis sent to a group, configure Visualization → Agent Execution → Message (group chat). Set analysis instructions in Agent Execution and enable system.analysis.chart.query for its agent. Queries read current data using the saved fields, filters, and aggregation; analysis must disclose truncated results. The Message node sends the analysis text and report link. Opening the link still requires report access.
Wait Callback Node
Use this node when the external system accepts the task first and returns the result later:
Service Call → Wait Callback → later nodes
- Connect Wait Callback directly after the service call node that starts the external task
- Select a published inbound webhook integration flow
- Configure the correlation key, which locates this wait, and the wait timeout as a value plus unit; when the unit is seconds it cannot be less than 60
- Connect one output, then save and publish
- Give the rendered correlation key to the external system and require it to send it back unchanged
When the external system calls the bound webhook, it sends the request structure shown in the inspector: callbackId provides idempotency, the automation uses correlationKey to locate the waiting node, and status, result, and error become that node output.
If no callback arrives before the wait timeout, the waiting node and the automation execution fail, and the execution history shows the error.
The complete payloads, callback protocol, and script examples for both kinds of workflow are in Workflow Integration.
Branch Node
- The trigger must already bind a form
- Add the branch node and configure one or more conditions
- Connect the Y (matched) and N (unmatched) outputs
A branch needs one input, and both outputs must be connected before later nodes can continue.
5. Validation, Saving, And Publishing
Canvas Validation
The canvas must pass validation before saving or publishing:
- The trigger is complete; a form button trigger selects a custom button with a matching placement and applicable page, and a manual or scheduled batch scope of records matching the filter has a filter
- The flow connects the start node to the end node without isolated nodes or cycles
- Every branch has one input and both the Y and N outputs connected
- Wait callback nodes are connected directly from a service call node, and their timeout is a valid value and unit of at least 60 seconds when the unit is seconds
- Service call and wait callback nodes each have one input and one output, and the input and output cannot use the same connection point
- Data processing: a bound form, a target form when creating data, and at least one complete, non-duplicated field assignment when creating or updating
- Human processing: assignees, processing target, the matching target form and relation field, and fields to handle when editing data
- Agent execution: an active agent and a task instruction
- Message: a channel and template; a group chat also needs the sending agent and target group chat; data-field recipients need a bound form; group send by recipient needs a recipient field
- Visualization: a report or chart, a channel, and at least one recipient
Save And Publish
| Action | Description |
|---|---|
| Save | Saves the current canvas as a new draft version |
| Save and publish | Saves the canvas and publishes that version immediately |
A task has a runnable version only after publishing, and its status is managed in the Automation Tasks list.
Copy The Current Canvas
Click Copy in the canvas top bar to create a new task from the current validated canvas. The dialog only asks for a new name and an optional description, defaulting to "original name - copy", and Soln generates the code. The result is an independent draft that does not copy the publish state, execution history, or previous versions.
6. Verify The Design
- Save a version after configuring the trigger
- Publish the version, or use Save and publish to publish the current canvas
- Verify manual, schedule, or data-change triggers through their matching entry point; for a form-button trigger, select the bound button at View Page - Header, List Page - Row Action, View Page List - Row Action, or the corresponding batch-action placement after selecting records
- Check the execution history to confirm which nodes ran and the result
7. Troubleshooting
| Symptom | What to check |
|---|---|
| Saving is rejected | The validation message points at the node or setting that is incomplete |
| A button is missing from the form-button selector | Make sure it is an enabled custom button at View Page - Header, List Page - Row Action, List Page - Batch Action, View Page List - Row Action, or View Page List - Batch Action, with the applicable page required by that placement |
| Selecting the button does not start the task | Check that the task is published and enabled and that its published version binds the same button, then inspect the button and automation execution records |
| A data processing node cannot be added | Bind a form in the trigger first; creating data also needs a target form and at least one complete field assignment |
| A wait callback node cannot be published | It must follow a service call node directly, bind a published inbound webhook flow, and have a valid wait timeout of at least 60 seconds when the unit is seconds |
| A message node cannot be published | It needs a channel, a template, and either fixed recipients or a recipient field; group send by recipient requires a bound form |