Actions Reference

Actions define behaviors triggered by user interactions or page lifecycle events in Aptean Mesh. They are declared inside the contract.actions array and referenced by id from components, the contract's initialAction/scanAction, or other actions.

Every action type shares a common base interface (IAction in the Kotlin source):

Property	Type	Default	Description
`id`	`string`	required	Unique identifier used to reference this action from components or other actions.
`type`	`string`	required	Type discriminator. Determines which action subtype is used.
`confirm`	`ConfirmDialog?`	`null`	Optional confirmation dialog displayed before the action executes.
`input`	`InputPrompt?`	`null`	Optional input prompt dialog to collect user input before the action executes.

The type field is the JSON discriminator (set via @SerialName in Kotlin). The client deserializes the action to the matching subclass based on this value.

ApiAction

Type discriminator: "api"

Calls a backend AL codeunit method via JSON-RPC. This is the primary action type for data operations -- fetching records, submitting changes, processing scans, and triggering business logic.

Properties

Property	Type	Default	Description
`id`	`string`	required	Unique action identifier.
`type`	`string`	required	Must be `"api"`.
`method`	`string`	required	The RPC method name to invoke on the AL codeunit. Resolves to `State.Method()` in the service's State codeunit.
`params`	`string[]`	`[]`	Parameter keys to extract from page data (navigation data, input values, filter selections) and pass to the method.
`confirm`	`ConfirmDialog?`	`null`	Confirmation dialog shown before executing.
`input`	`InputPrompt?`	`null`	Input prompt shown before executing.

How it connects to AL

When the client dispatches an ApiAction, it:

Resolves each key in params from the current page data context (navigation parameters, input field values, filter selections).
Sends a JSON-RPC request to the service identified by the page's service field.
The AL codeunit reads parameters with State.GetInput('paramName') and returns data via State.SetValue(...) or State.SetArray(...).
The client merges the response data into the page's data store, triggering UI updates on any bound components.

Example

{
  "id": "loadOrders",
  "type": "api",
  "method": "GetOrders",
  "params": ["locationFilter", "statusFilter"]
}

Example with confirmation and input

{
  "id": "adjustQuantity",
  "type": "api",
  "method": "AdjustQuantity",
  "params": ["ItemNo", "newQty"],
  "confirm": {
    "title": "Adjust Quantity",
    "message": "Are you sure you want to change the quantity?",
    "confirmLabel": "Adjust",
    "cancelLabel": "Cancel"
  },
  "input": {
    "title": "New Quantity",
    "message": "Enter the adjusted quantity:",
    "inputKey": "newQty",
    "defaultValue": "",
    "confirmLabel": "OK",
    "keyboardType": "number"
  }
}

NavigateAction

Type discriminator: "navigate"

Navigates to another page within the App Bundle. Navigation is instant because all page definitions are cached locally after the initial GetPageFlow call.

Properties

Property	Type	Default	Description
`id`	`string`	required	Unique action identifier.
`type`	`string`	required	Must be `"navigate"`.
`destination`	`string`	required	The `pageId` of the target page to navigate to.
`data`	`object`	`{}`	Key-value pairs passed to the destination page as initial context. Values support `{FieldName}` interpolation from the current data context.
`confirm`	`ConfirmDialog?`	`null`	Confirmation dialog shown before navigating.
`input`	`InputPrompt?`	`null`	Input prompt shown before navigating.

Parameter interpolation

Use {FieldName} syntax in the data values to interpolate values from the current row or page data context. When a user taps a repeater row, the row's fields are available for interpolation:

{
  "id": "onOrderTap",
  "type": "navigate",
  "destination": "ORDER-DETAIL",
  "data": {
    "OrderNo": "{Document No}",
    "OrderType": "{Type}"
  }
}

If the tapped row has "Document No": "WH-001" and "Type": "Pick", the destination page receives {"OrderNo": "WH-001", "OrderType": "Pick"}. The destination page's API actions can then include "OrderNo" in their params list, and AL reads it with State.GetInput('OrderNo').

Example

{
  "id": "navigateToDetail",
  "type": "navigate",
  "destination": "ITEM-DETAIL",
  "data": {
    "ItemNo": "{No}",
    "LocationCode": "{Location Code}"
  }
}

FilterAction

Type discriminator: "filter"

Fetches filtered data from a backend endpoint. Used by filter controls (selector components, filter panel) to dynamically reload data when the user changes a filter selection.

Properties

Property	Type	Default	Description
`id`	`string`	required	Unique action identifier.
`type`	`string`	required	Must be `"filter"`.
`endpoint`	`string`	required	The API endpoint (method name) to call with the current filter values.
`params`	`string[]`	`[]`	Parameter keys whose current values are sent with the filter request. Typically these match the `id` values of filter definitions.
`confirm`	`ConfirmDialog?`	`null`	Confirmation dialog shown before fetching.
`input`	`InputPrompt?`	`null`	Input prompt shown before fetching.

How filter actions work

A selector component or filter panel triggers the filter action via onSelect or a similar event.
The client reads the current value of each key listed in params from the filter state.
A request is sent to the endpoint with those parameter values.
The response data replaces the page's data store, and bound components re-render.

Example

{
  "id": "onStatusFilterChanged",
  "type": "filter",
  "endpoint": "GetOrders",
  "params": ["StatusFilter", "LocationFilter"]
}

LookupAction

Type discriminator: "lookup"

Opens a lookup modal that lets the user search and select from a list of options. The lookup list is populated from a repeater component's data.

Properties

Property	Type	Default	Description
`id`	`string`	required	Unique action identifier.
`type`	`string`	required	Must be `"lookup"`.
`title`	`string?`	`null`	Title text displayed in the lookup modal header.
`componentId`	`string?`	`null`	The `id` of a repeater component whose data populates the lookup list.
`confirm`	`ConfirmDialog?`	`null`	Confirmation dialog shown before opening the lookup.
`input`	`InputPrompt?`	`null`	Input prompt shown before opening the lookup.

Example

{
  "id": "selectWarehouse",
  "type": "lookup",
  "title": "Select Warehouse",
  "componentId": "warehouseList"
}

ConfirmDialog

An optional confirmation dialog that can be attached to any action. When present, the client shows this dialog before executing the action. If the user cancels, the action is not executed.

Property	Type	Default	Description
`title`	`string`	required	The dialog title text.
`message`	`string`	required	The dialog body message explaining what the action will do.
`confirmLabel`	`string`	`""`	Label for the confirm button. Falls back to a platform default ("Confirm") when blank.
`cancelLabel`	`string`	`""`	Label for the cancel button. Falls back to a platform default ("Cancel") when blank.

Example

{
  "confirm": {
    "title": "Delete Record",
    "message": "This cannot be undone. Continue?",
    "confirmLabel": "Delete",
    "cancelLabel": "Keep"
  }
}

InputPrompt

An optional input prompt dialog that can be attached to any action. When present, the client shows a text input dialog before executing the action. The user's input is stored under the specified inputKey and made available to the action's parameters.

Property	Type	Default	Description
`title`	`string`	required	The dialog title text.
`message`	`string`	required	The dialog body message explaining what input is needed.
`inputKey`	`string`	required	The data key where the user's input value is stored for the action. Include this key in the action's `params` to pass it to AL.
`defaultValue`	`string`	`""`	Pre-filled value in the input field.
`confirmLabel`	`string`	`""`	Label for the confirm button. Falls back to a platform default when blank.
`keyboardType`	`string`	`"text"`	Keyboard type to display. Common values: `"text"`, `"number"`.

Example

{
  "id": "enterQuantity",
  "type": "api",
  "method": "SetQuantity",
  "params": ["ItemNo", "enteredQty"],
  "input": {
    "title": "Enter Quantity",
    "message": "How many units?",
    "inputKey": "enteredQty",
    "defaultValue": "1",
    "confirmLabel": "Submit",
    "keyboardType": "number"
  }
}

Complete contract example

This example shows a page contract with multiple action types working together:

{
  "contract": {
    "initialAction": "loadItems",
    "scanAction": "onScan",
    "actions": [
      {
        "id": "loadItems",
        "type": "api",
        "method": "GetItems",
        "params": ["locationFilter"]
      },
      {
        "id": "onScan",
        "type": "api",
        "method": "ProcessScan",
        "params": ["scanInput"]
      },
      {
        "id": "onFilterChanged",
        "type": "filter",
        "endpoint": "GetItems",
        "params": ["locationFilter"]
      },
      {
        "id": "onItemTap",
        "type": "navigate",
        "destination": "ITEM-DETAIL",
        "data": {
          "ItemNo": "{No}",
          "Description": "{Description}"
        }
      },
      {
        "id": "deleteItem",
        "type": "api",
        "method": "DeleteItem",
        "params": ["ItemNo"],
        "confirm": {
          "title": "Delete Item",
          "message": "Remove this item from the list?",
          "confirmLabel": "Delete",
          "cancelLabel": "Cancel"
        }
      },
      {
        "id": "selectLocation",
        "type": "lookup",
        "title": "Choose Location",
        "componentId": "locationRepeater"
      }
    ],
    "filters": [
      {
        "id": "locationFilter",
        "label": "Location",
        "mode": "DROPDOWN",
        "optionsKey": "locations",
        "labelKey": "name",
        "valueField": "code"
      }
    ]
  }
}

Flow:

Page loads -- the client executes loadItems, calling GetItems on the AL codeunit.
User scans a barcode -- the client executes onScan, calling ProcessScan with the scanned value.
User changes the location filter -- the client executes onFilterChanged, reloading items filtered by location.
User taps a row -- the client executes onItemTap, navigating to ITEM-DETAIL with interpolated data.
User long-presses a row and confirms deletion -- the client shows the confirm dialog, then executes deleteItem.
User opens the location lookup -- the client executes selectLocation, displaying a modal populated from the locationRepeater component.

ApiAction​

Properties​

How it connects to AL​

Example​

Example with confirmation and input​

NavigateAction​

Properties​

Parameter interpolation​

Example​

FilterAction​

Properties​

How filter actions work​

Example​

LookupAction​

Properties​

Example​

ConfirmDialog​

Example​

InputPrompt​

Example​

Complete contract example​

ApiAction

Properties

How it connects to AL

Example

Example with confirmation and input

NavigateAction

Properties

Parameter interpolation

Example

FilterAction

Properties

How filter actions work

Example

LookupAction

Properties

Example

ConfirmDialog

Example

InputPrompt

Example

Complete contract example