Skip to main content

Commands Reference

Commands are instructions sent from the AL backend to the Aptean Mesh client as part of an API action response. Unlike actions (which are defined in the page JSON and triggered by user interaction), commands are returned dynamically by server-side logic to control client behavior after an RPC call completes.

All command types implement the ICommand sealed interface. The type field is the JSON discriminator (set via @SerialName in the Kotlin source).

AlertCommand​

Type discriminator: "alert"

Displays an informational dialog to the user. The dialog has a single dismiss button. Use this to show success messages, warnings, or error details after an operation completes.

Properties​

PropertyTypeDefaultDescription
typestringrequiredMust be "alert".
titlestringrequiredThe dialog title text.
messagestringrequiredThe dialog body message.

When the server sends this​

The AL codeunit returns an AlertCommand when it needs to inform the user of a result that requires acknowledgment -- for example, after a successful operation or when a validation error needs to be communicated.

Example​

{
  "type": "alert",
  "title": "Pick Complete",
  "message": "All lines have been picked successfully."
}

Type discriminator: "navigate"

Instructs the client to navigate to a different page. Optionally includes data to pass to the destination page and an alert to display before or after navigation.

Properties​

PropertyTypeDefaultDescription
typestringrequiredMust be "navigate".
destinationstringrequiredThe pageId of the target page.
dataobject?nullKey-value pairs passed to the destination page as initial context.
alertTitlestring?nullOptional alert dialog title shown alongside navigation.
alertMessagestring?nullOptional alert dialog message shown alongside navigation.

When the server sends this​

The AL codeunit returns a NavigateCommand when server-side logic determines the user should move to a different page -- for example, after successfully selecting a document, the server navigates the user to the document detail page.

Example​

{
  "type": "navigate",
  "destination": "ORDER-DETAIL",
  "data": {
    "OrderNo": "WH-001",
    "OrderType": "Pick"
  }
}

Example with alert​

{
  "type": "navigate",
  "destination": "HOME",
  "alertTitle": "Order Released",
  "alertMessage": "Order WH-001 has been released and assigned."
}

Type discriminator: "navigateBack"

Instructs the client to navigate back to the previous page in the navigation stack. Optionally shows an alert dialog.

Properties​

PropertyTypeDefaultDescription
typestringrequiredMust be "navigateBack".
alertTitlestring?nullOptional alert dialog title shown when navigating back.
alertMessagestring?nullOptional alert dialog message shown when navigating back.

When the server sends this​

The AL codeunit returns a NavigateBackCommand when an operation completes and the user should return to the previous screen -- for example, after finishing all lines on a pick page.

Example​

{
  "type": "navigateBack"
}

Example with alert​

{
  "type": "navigateBack",
  "alertTitle": "Saved",
  "alertMessage": "Changes have been saved successfully."
}

Type discriminator: "navigateBackTo"

Instructs the client to pop the navigation stack back to a specific page. All pages between the current page and the target are removed from the stack. Optionally shows an alert dialog.

Properties​

PropertyTypeDefaultDescription
typestringrequiredMust be "navigateBackTo".
destinationstringrequiredThe pageId to navigate back to. Must exist in the current navigation stack.
alertTitlestring?nullOptional alert dialog title shown when navigating back.
alertMessagestring?nullOptional alert dialog message shown when navigating back.

When the server sends this​

The AL codeunit returns a NavigateBackToCommand when the user should skip back multiple levels -- for example, after completing a multi-step workflow, returning directly to the home page instead of stepping back through each intermediate page.

Example​

{
  "type": "navigateBackTo",
  "destination": "HOME",
  "alertTitle": "Workflow Complete",
  "alertMessage": "The put-away has been completed and posted."
}

ConfirmCommand​

Type discriminator: "confirm"

Displays a confirmation dialog and, if the user confirms, triggers a follow-up action by its id. This lets the server dynamically request confirmation for operations that depend on runtime conditions.

Properties​

PropertyTypeDefaultDescription
typestringrequiredMust be "confirm".
titlestringrequiredThe dialog title text.
messagestringrequiredThe dialog body message.
confirmLabelstring"Confirm"Label for the confirm button.
actionIdstringrequiredThe id of an action defined in the page's contract to execute if the user confirms.

When the server sends this​

The AL codeunit returns a ConfirmCommand when it needs to ask for user confirmation based on a runtime condition -- for example, if a scanned item already exists on a line and the server wants to ask whether to overwrite it.

Example​

{
  "type": "confirm",
  "title": "Overwrite Line?",
  "message": "Item 1001 is already on line 3. Replace it?",
  "confirmLabel": "Replace",
  "actionId": "overwriteLine"
}

RefreshCommand​

Type discriminator: "refresh"

Instructs the client to re-execute the page's initialAction, refreshing all data on the current page. This is a data object with no additional properties.

Properties​

PropertyTypeDefaultDescription
typestringrequiredMust be "refresh".

When the server sends this​

The AL codeunit returns a RefreshCommand when an operation modifies data that the current page displays and the page should reload to reflect the changes. This is equivalent to the user performing a pull-to-refresh gesture.

Example​

{
  "type": "refresh"
}

VibrateCommand​

Type discriminator: "vibrate"

Triggers a haptic feedback vibration on the device. Used to provide tactile confirmation of scan results or operation outcomes.

Properties​

PropertyTypeDefaultDescription
typestringrequiredMust be "vibrate".
vibrateTypestringrequiredThe vibration pattern. Must be "SUCCESS" or "ERROR".

VibrateType values​

ValueDescription
SUCCESSA short, gentle vibration indicating a successful operation.
ERRORA longer, more intense vibration pattern indicating a failure.

When the server sends this​

The AL codeunit returns a VibrateCommand to give the user immediate haptic feedback -- typically after a barcode scan to indicate whether the scan was accepted or rejected.

Example​

{
  "type": "vibrate",
  "vibrateType": "SUCCESS"
}

Multiple commands in a single response​

The AL backend can return multiple commands in a single RPC response. The client processes them in order. A common pattern is to combine a VibrateCommand with a NavigateCommand or RefreshCommand:

[
  { "type": "vibrate", "vibrateType": "SUCCESS" },
  { "type": "alert", "title": "Scan Accepted", "message": "Item 1001 added to the pick." },
  { "type": "refresh" }
]

This sequence gives the user haptic feedback, shows a confirmation message, and then refreshes the page data to reflect the newly added item.