8 Custom Actions

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

What a custom action does when invoked by the add-in is determined by the service. The add-in simply sends a POST on the collection or item path that includes the action name, such as /contextRoot/v1/myBusObj/{itemId}/action/doMyAction for a business object item.

This post can include payload field values, known as "parameters", to the service. The service then takes the passed parameters and performs the custom action. This action may act on a single row when defined at the row level. When the action is defined at the business object level, 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.

Let's look at a couple of examples of custom actions at the business object (BO) level and BO item level. For example, a REST service may have a custom action defined at the BO level such as the one described here in REST API for Oracle Fusion Cloud Project Management. When triggered, this custom action reprocesses all the project budget versions which are showing as failed and brings these back into a working state.

Examples of custom actions at the BO item level might be a couple of custom actions, "Approve" and "Reject", that operate on the items of a expense report business object. A business user can download one or more expense reports, approve or reject each one, and then update them all in a single upload.

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.

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.

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.

Edit Custom Actions

Custom actions exposed by the service that your workbook uses can be viewed and edited in the Custom Actions tab of the Business Object Editor.

Oracle Visual Builder Add-in for Excel populates this editor with the custom action properties as described in the service's OpenAPI service metadata.

Description of excel-custaction.png follows
Description of the illustration excel-custaction.png

In this example, the add-in shows the properties for a "Reject" custom action on an ExpenseReports business object (BO) item path (/ExpenseReports/{ExpenseReports_Id}/action/reject). The Applies to a single row check box indicates that the custom action operates at the business object (BO) item level. If this check box is unselected, the custom action operates at the BO level.

Custom Action Properties

The Title, Help Text, and Description properties can be edited as needed in the Custom Action Editor. The other properties, ID, Path, and Request Media Type, reflect the service configuration and should be left as is.

  • Title: The name of this custom action. Provide a short value that is meaningful to your business users. This value appears wherever business users can invoke the action. This value can be localized.
  • Help Text: Provide a brief explanation of what the custom action does. This value appears near the title when possible. This value can be localized.
  • Description: This is an internal technical description. This value only appears in the designer. It is not localizable.

Note:

When the Help Text value is displayed to your business users, the label next to that value is "Description".

For information on the Supports Multi-Row Requests check box, refer to Multi-Row Mode for Custom Actions.

Payload Field Properties

Payload fields can be edited on the Payload Fields tab of the Custom Action Editor. Properties such as the Title, Data Type, and Required can be changed. For example, you can change the data type of a payload field from String to Integer, as long as the change is compatible with the service. You can also update the Required property to mark the payload field as required or not:



As with the custom action, the Title, Help Text, and Description properties can be edited as needed in the Custom Action Field Editor. The other properties, ID and Data Type reflect the service configuration and should be left as is.

  • Title: The name of this custom action field. Provide a short value that is meaningful to your business users. This value can be localized.
  • Help Text: Provide a brief description of the custom action field. This value can be localized.
  • Description: This is an internal technical description. This value only appears in the designer. It is not localizable.

For single row custom actions, this help text appears in a popup when the business user selects the column header for a payload field in a Table layout, as shown on the left in this image:



For BO-level custom actions, the help text appears in a popup when you hover over the help icon (Help) next to a payload field in the Perform Action wizard, as shown on the right.

You can also configure a payload field with a custom field validation rule as well as a list of values. See About Custom Field Validation Rules and Configure a List of Values with a Business Object.

Add Custom Action Fields to a Table Layout

If the service your workbook uses includes custom actions on individual items of a business object, you can add defined custom action payload fields to your Table layout or the table part of your Form-over-Table layout.

Let's take as an example a "reject" custom action that's exposed by an expense report business object to reject expenses.

This task assumes you have a Table layout for an expense report business object that includes a "reject" custom action. You can also add custom actions to the table of a Form-over-Table layout.

To add custom action table columns to a layout:

  1. Select the layout, then click Designer from the Oracle Visual Builder tab to open the Layout Designer.
  2. Click the Columns tab in the Layout Designer.
  3. Click Manage Columns (Manage Columns) to open the Table Column Manager.
  4. From the Table Column Manager, click Custom Actions in the Available Fields pane.
  5. In the Selected Fields pane, select the location where you want the payload field columns to be added. The columns will be inserted before the selected field.
  6. In the Available Fields pane, select the payload fields you want to add.
    In this example, we'll select Reason and Notes to add these columns to the layout.
  7. Click Done.

Once you add custom action fields to a layout in your integrated workbook, your business users can mark rows for the custom action by entering values in the payload field columns or by using the ribbon command. See Perform Custom Actions in Table and Form-over-Table Layouts in Managing Data Using Oracle Visual Builder Add-in for Excel.

When they click Upload Changes, Oracle Visual Builder Add-in for Excel sends their changes to the REST endpoint and invokes the custom action on the marked rows.

Service Metadata for Custom Actions

If a given REST API supports custom actions, they are described in the OpenAPI service metadata generated by the Oracle ADF REST Resource service. For example, a reject item-level custom action would appear in the paths collection:

// Note: some JSON content has been omitted for brevity/clarity

"/ExpenseReports/{ExpenseReports_Id}/action/reject": {
    "parameters": [
      {
        "$ref": "#/components/parameters/ExpenseReports_Id"
      }
    ],
    "post": {
      "summary": "reject",
      "description": "reject",
      "operationId": "do_reject_ExpenseReports",
      "responses": {
        "default": {
          "description": "The following table describes the default response for this task.",
          "content": {
            "application/vnd.oracle.adf.actionresult+json": {
              "schema": {
                "type": "object",
                "properties": {
                  "result": {
                    "type": "string"
                  }
                },
                "required": [
                  "result"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      },
      "requestBody": {
        "description": "The following table describes the body parameters in the request for this task.",
        "content": {
          "application/vnd.oracle.adf.action+json": {
            "schema": {
              "type": "object",
              "properties": {
                "rejectionReasonCode": {
                  "type": "string",
                  "nullable": true
                },
                "notes": {
                  "type": "string",
                  "nullable": true
                }
              },
              "additionalProperties": false
            }
          }
        }
      }
    }
  }
Note the following:
  • For a item-level custom action, the path entry contains a path parameter for the row/item ID, for example, /ExpenseReports/{ExpenseReports_Id}/action/reject"

    In the case of a business object-level custom action, the path (such as /ExpenseReports/action/sendToAuditor) doesn't include a path parameter for the row/item.

  • The end of the path entry (reject) matches the name of the custom method defined in the service (see Publishing Custom Service Methods to UI Clients)
  • The presence of a POST operation for the action path entry is required
  • In the requestBody schema, there are properties that match the parameters defined in the custom method signature from the service. In this document, these properties are referred to as custom action payload fields.

Multi-Row Mode for Custom Actions

If a custom action supports multi-row mode, Oracle Visual Builder Add-in for Excel can process custom actions and other types of changes in batches.

Multi-row mode is only relevant for custom actions defined on the item path since custom actions on individual items are sent as separate requests. A custom action on an entire business object may update multiple items in the business object but is accomplished using a single request.

To enable the add-in to process changes in batches, select the Supports Multi-Row Requests check box in the Custom Action Editor. If the check box is not selected, the add-in invokes the custom action one row at a time.

If you attempt to use multi-row processing on a custom action that does not support it, you may get an error from the service. If the custom action doesn't work properly in batches, deselect the check box to disable multi-row processing.

For more information, see Upload Changes Using Multi-Row Requests.

Note:

The "batchEnabled" : false property in the service metadata only determines the default value of the Supports Multi-Row Requests check box in the Custom Action Editor. If the property is not configured, the check box is selected by default.

After the catalog is created, the check box setting controls how the add-in behaves.

Notes on Custom Actions

Here are some things to keep in mind when using custom actions:

  • Custom actions are not supported for pending Create rows or form in Create mode.
  • Custom actions defined in the OpenAPI service metadata document that have request payload schema members that match business object fields are unlikely to function properly.
  • Oracle ADF REST Resource service OpenAPI service metadata documents do not indicate which custom action request payload fields are required. You can use the Business Object Editor to adjust the Required property on payload fields. See Edit Custom Actions.
  • Oracle ADF REST Resource services do not return the updated row. As a result, you need to download before making further changes.
  • Custom action payload fields must be simple scalar types. Complex objects or maps are not supported.
  • The add-in handles custom action results automatically. It processes the "result" member of the REST response this way:
    • Simple scalar values are displayed verbatim
    • The first level of JSON objects and arrays are unpacked
    • Deeper levels of JSON are displayed verbatim
    • If there is a null value in an object or array, a "null" string is shown in the results. If the value of the result member is null, then the action result is suppressed.
  • To use custom actions with the VBBO REST framework, you will need to define an Object Function for each custom action in the business object. In those Object functions, be sure to enable Callable by External System. See Object Functions for Business Objects.