Skip to content

Actions

Overview

Actions define what happens when a user interacts with a page — clicking a table row, pressing a button, or submitting a form. Each block can have one or more actions attached to it.

Actions are configured in the actions array of a block definition:

{
  "blockType": "table",
  "actions": [
    {
      "id": "action-1",
      "type": "navigate-to-page",
      "label": "View Details",
      "targetRef": "order-detail",
      "activation": "row-click"
    }
  ]
}

Action types

Action Type Description Common Use
navigate-to-page Redirects to another page, optionally passing data as query params List-to-detail navigation
invoke-trigger Invokes an on-demand function trigger Run business logic, call external APIs
create-record Creates a new record in a collection Form submission
update-record Updates an existing record Inline edit, status change
start-orchestration Starts an automation workflow Multi-step approval, provisioning
enqueue-job Enqueues a scheduled job Deferred processing

Deprecated types

execute-function and run-query are deprecated and should not be used in new page definitions. Use invoke-trigger instead of execute-function.

Allowed actions by block type

Not every action type is available on every block. The table below shows which action types are supported:

Block Type Allowed Actions
table (data-table) navigate-to-page, invoke-trigger
field-display invoke-trigger, navigate-to-page
related-list navigate-to-page, invoke-trigger
field-group (form) create-record, update-record, invoke-trigger
actions (action bar) invoke-trigger, navigate-to-page, start-orchestration, enqueue-job

Activation modes

The activation mode controls how the user triggers the action:

Mode Behavior Default For
row-click Triggered by clicking a table row table, related-list
button Triggered by clicking a button field-display, actions
form-submit Triggered by submitting a form field-group

Navigate to page

The navigate-to-page action redirects the user to another page in the same workspace. It is the primary mechanism for building multi-page navigation flows.

Basic navigation

{
  "id": "action-view",
  "type": "navigate-to-page",
  "label": "View",
  "targetRef": "order-detail",
  "activation": "row-click"
}

The targetRef is the slug of the destination page.

Passing data via query parameters

To pass data from the current row or record to the destination page, enable useQueryParams and configure paramConfig:

{
  "id": "action-view",
  "type": "navigate-to-page",
  "label": "View Order",
  "targetRef": "order-detail",
  "activation": "row-click",
  "config": {
    "useQueryParams": true
  },
  "paramConfig": {
    "source": "row",
    "mode": "selected",
    "selectedFields": ["id"]
  }
}

This produces a URL like: https://pages.centrali.io/my-workspace/order-detail?id=abc-123

Parameter configuration

The paramConfig object controls what data is passed:

Field Description
source Where the data comes from: row (table row), record (detail record), form (form fields), none
mode all (pass all fields) or selected (pass only specified fields)
selectedFields Array of field names to include (when mode is selected)

Use selected mode

Prefer mode: "selected" with explicit selectedFields over mode: "all". This keeps URLs clean and avoids passing unnecessary data.

Invoke trigger

The invoke-trigger action calls an on-demand function trigger, allowing you to run server-side logic from a page interaction.

{
  "id": "action-approve",
  "type": "invoke-trigger",
  "label": "Approve",
  "targetRef": "TRIGGER_ID",
  "activation": "button",
  "confirmationRequired": true,
  "paramConfig": {
    "source": "record",
    "mode": "selected",
    "selectedFields": ["id", "amount"]
  }
}

The targetRef is the trigger ID. The data specified by paramConfig is sent as the action payload.

Create and update record

Form blocks typically use create-record or update-record actions:

Create record

{
  "id": "action-submit",
  "type": "create-record",
  "label": "Submit Order",
  "targetRef": "COLLECTION_ID",
  "activation": "form-submit",
  "paramConfig": {
    "source": "form",
    "mode": "all"
  },
  "postSubmit": {
    "behavior": "message",
    "message": "Order created successfully!"
  }
}

Update record

{
  "id": "action-save",
  "type": "update-record",
  "label": "Save Changes",
  "targetRef": "COLLECTION_ID",
  "activation": "form-submit",
  "paramConfig": {
    "source": "form",
    "mode": "all"
  }
}

The targetRef for record actions is the collection ID.

Post-submit behavior

After a create-record or update-record action completes, you can control what happens next with postSubmit:

Behavior Description
message Show a success message to the user
navigate Redirect to another page

Show a message

{
  "postSubmit": {
    "behavior": "message",
    "message": "Record saved successfully!"
  }
}

{
  "postSubmit": {
    "behavior": "navigate",
    "targetPageSlug": "orders"
  }
}

Start orchestration and enqueue job

These actions integrate with Centrali's automation and scheduling systems:

Start orchestration

{
  "id": "action-provision",
  "type": "start-orchestration",
  "label": "Start Provisioning",
  "targetRef": "ORCHESTRATION_ID",
  "activation": "button",
  "confirmationRequired": true
}

Enqueue job

{
  "id": "action-export",
  "type": "enqueue-job",
  "label": "Export Report",
  "targetRef": "JOB_DEFINITION_ID",
  "activation": "button"
}

Execution modes

Actions that call server-side logic (invoke-trigger, start-orchestration, enqueue-job) support two execution modes:

Mode Behavior
fire-and-forget Action is dispatched and the UI immediately shows success
fire-and-poll Action is dispatched, the UI shows a loading state, and polls for completion 
{
  "id": "action-process",
  "type": "invoke-trigger",
  "label": "Process",
  "targetRef": "TRIGGER_ID",
  "executionMode": "fire-and-poll"
}

With fire-and-poll, the runtime tracks the action status in Redis. The UI polls the status endpoint until the action completes or fails:

  • Running: Action is in progress, UI shows a spinner
  • Completed: Action finished successfully, UI shows the result
  • Failed: Action encountered an error, UI shows the error message

When to use each mode

Use fire-and-forget for quick operations where the user does not need to wait for a result. Use fire-and-poll for longer-running operations where the user needs confirmation that the action completed.

Confirmation dialog

Set confirmationRequired: true on any action to show a confirmation dialog before executing:

{
  "id": "action-delete",
  "type": "invoke-trigger",
  "label": "Delete",
  "targetRef": "TRIGGER_ID",
  "confirmationRequired": true,
  "presentation": {
    "display": "button",
    "color": "destructive"
  }
}

Action presentation

The presentation object controls how the action button is displayed:

Field Options Description
display button, icon, icon-button Button style
icon Any icon name Icon to display
color primary, secondary, destructive, neutral Button color theme 
{
  "presentation": {
    "display": "icon-button",
    "icon": "trash",
    "color": "destructive"
  }
}

Form field defaults

Form blocks can define hidden fields with derived default values. These are resolved server-side at submit time and cannot be tampered with by the client:

{
  "blockType": "field-group",
  "fields": [
    {
      "key": "title",
      "label": "Title",
      "type": "text",
      "required": true
    },
    {
      "key": "createdBy",
      "label": "Created By",
      "type": "hidden",
      "defaultValue": { "source": "auth", "field": "userId" }
    },
    {
      "key": "submittedAt",
      "label": "Submitted At",
      "type": "hidden",
      "defaultValue": { "source": "system", "field": "now" }
    }
  ]
}

Available derived default sources:

Source Field Resolves to
auth userId Authenticated user's ID
auth email Authenticated user's email
auth name Authenticated user's display name
system now Current ISO 8601 timestamp
system uuid Randomly generated UUID

Auth defaults require authentication

If a form has hidden fields with auth defaults and the page is public, form submission will fail with an error. Set the page access policy to authenticated or role-gated when using auth-derived defaults.