Row Status Custom Actions
Row status custom actions are BO item level custom actions that report row status information without changing the row state or field values.
Row status custom actions may flag an error or issue a warning when a business user enters an invalid value—say a duplicate invoice number or an expense amount that exceeds a certain threshold.
They can be performed manually as well as triggered automatically, for example, when a business user first selects a cell. You can configure a row status custom action to trigger automatically from the Layout Designer. Only row status custom actions without payload fields can be configured for automatic use. See Automate a Row Status Custom Action.
Configure a Row Status Custom Action
Set a custom action as a row status custom action from the Custom Action Editor.
A row status custom action must:
- Be a row-level custom action.
This check box is unavailable if Applies to a single row is not selected.
- Report the current state of the row without changing the row state, field values, and so on.
- Return row status information following the expected row status custom action schema. See Row Status Custom Action Response Schema.
Caution:
Selecting this check box for a custom action that is not a row status one will result in unexpected behavior by the add-in. You could also experience data corruption if the custom action makes changes to the row.To designate a custom action as a Row Status Custom Action, open the Custom Action Editor for the custom action, then select Returns row status from the General tab.
Automate a Row Status Custom Action
A row status custom action operates on a single row and reports the current state without changing the row state or field values. It may be used to flag an error or issue a warning such as when it detects a duplicate invoice number or an expense amount over a set threshold.
If you decide not to configure a row status custom action for automatic invocation, it can still be performed manually by the business user, like other row-level custom actions.
Note:
Automatic invocation is not supported for Form-over-Table layouts.To configure a row status custom action for automatic use:
- Expand the Row Status section, then click the Edit icon (
) to open the Choose a Row Status Custom Action window.Note:
If the custom action you are looking for doesn't appear in the list, it is either not set as a row status custom action in the Custom Action Editor or it includes payload fields.
Once configured, the row status custom action is triggered automatically when a business user first selects a cell. As with other custom actions, results are displayed in the Status column and Status Viewer. See Perform Custom Actions in Table and Form-over-Table Layouts in Managing Data Using Oracle Visual Builder Add-in for Excel.
Since the row state and field values are not changed, the business user can continue to edit the row following a row status custom action without having to upload or download data. Oracle Visual Builder Add-in for Excel does not consider the row "stale".
The result of the row status custom action is cached, and the custom action will not be performed on selection again until:
- The layout is cleared
- Data is downloaded
- Row updates are successfully uploaded
Caution:
Technical limitations in Microsoft Excel require the spreadsheet to be disabled while the custom action request is executed. If the response time is slower than 100 ms, the data entry experience may be negatively affected.Row Status Custom Action Response Schema
Review this topic for the response schema for a row status custom action as well as response messages for the custom action.
This sample JSON file shows the response schema for a row status custom action:
{
"$schema": "http://json-schema.org/draft-07/schema",
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "A valid field ID of a field defined on the business object that is bound to the layout. If a value is omitted, the message is considered relevant to the entire row instead of a specific field."
},
"summary": {
"type": "string",
"description": "A localized summary message, no markup allowed."
},
"detail": {
"type": "string",
"description": "A localized detail message, no markup allowed."
},
"type": {
"type": "string",
"enum": [
"info",
"warning",
"error"
],
"default": "info"
}
},
"required": ["summary"]
}
}
}
}Custom actions return a JSON object with a "result" property. This property for a row status custom action must contain an array of Row Status Item objects.
The Row Status Item objects contain these properties:
| Property Name | Required? | Default Value | Allowed Values |
|---|---|---|---|
path |
No | – |
A valid field ID of a field defined on the business object that is bound to the layout. If a value is omitted, the message is considered relevant for the entire row instead of for a specific field. |
summary |
Yes | – | A localized string; no markup allowed |
detail |
No | – | A localized string; no markup allowed |
type |
No | info | info | error | warning |
Sample Response - Rejection Messages:
{
"result": [
{
"path": "invoiceNumber",
"summary": "Duplicate Invoice Number",
"detail": "Invoice numbers must be unique.",
"type": "error"
},
{
"path": "amount",
"summary": "Invalid Amount",
"type": "error"
}
]
}Sample Response - Info/Suggestion:
{
"result": [
{
"summary": "A similar item is available from Acme Corp at a lower price",
"type": "info"
}
]
}Sample Response - Warning:
{
"result": [
{
"path": "amount",
"summary": "The expense report exceeds the standard limit and requires special approval",
"type": "warning"
}
]
}