8 Custom Actions

Oracle Visual Builder Add-in for Excel supports custom actions defined by ADF REST services. A custom action is a function defined by the REST service that is callable by external systems using REST POST requests.

If a given REST API supports custom actions, they are described in the service's OpenAPI service metadata. The add-in can analyze this service metadata, harvest custom action definitions, and include them in the workbook's corresponding business objects. No further configuration is required. However, you may want to change the title and add help text for a better user experience. See Custom Action Configuration.

Types of Custom Actions

The add-in supports two types of custom actions: business object (BO) level and BO item level custom actions.

A BO level custom action is defined at the BO level and can operate on one or more rows in a layout. Such a custom action could, for example, reprocess all the project budget versions which are showing as failed and bring them back into working state. For more information about this particular custom action, see Reprocess all failed project budgets in REST API for Oracle Fusion Cloud Project Management.

A BO item level custom action operates on only one row in the layout. Examples would be a couple of custom actions, "Approve" and "Reject", that operate on the items of a expense report business object. A business user can use these custom actions to approve or reject each expense report individually before updating them all in a single upload.

These custom actions may require input from the user. If so, the business user is prompted to provide values for any custom action parameters. For example, the "Reject" custom action may require the business user to provide a reason code when rejecting an expense report. Likewise, a "Send to Auditor" BO level custom action may require the business user to provide a severity code and auditor email.

If a BO item level custom action reports row status information, it is referred to as a row status custom action. These row status custom actions report the current state of the row without changing the row state or field values. For example, it 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.

If a BO item level custom action includes fields, called payload fields, for capturing input from the business user, make sure these are added to your Table layout or the table part of your Form-over-Table layout. See Add Custom Action Fields to a Table Layout.

Row status custom actions 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.

Performing Custom Actions

Business users perform custom actions using the buttons and menu commands from the Oracle Visual Builder ribbon tab. See Perform Custom Actions in Table and Form-over-Table Layouts in Managing Data Using Oracle Visual Builder Add-in for Excel.

When a custom action is performed, the add-in sends a POST on the collection or item path that includes the action name, such as /contextRoot/v1/myBusObj/{itemId}/action/doMyAction for a BO item level custom action.

This post can include payload field values, known as "parameters", to the service. The service takes the passed parameters and performs the custom action. This action may act on a single row when defined at the row level. Or it may act on one or more rows when defined at the business object level. In this case, the REST service determines which rows, if any are affected.

A custom action may accept zero or more parameters of simple types such as a String or Integer and returns a single value to the add-in, which is then displayed in the Status Viewer. This result returned by the service may be a simple scalar value like a string or a more complex non-scalar value like an array.

If a custom action supports multi-row mode, you can configure the add-in to process custom actions and other types of changes in batches. See Multi-Row Mode for Custom Actions.

BO item level custom actions can be performed on items in either the form or the table of a Form-over-Table layout, as well as on rows in a Table layout. BO level custom actions can be performed on BOs in a Table layout and the form in a Form-over-Table layout. They are not supported on the BO in the table of a Form-over Table layout. See Notes on Custom Actions for information on other custom action limitations.