Custom Actions

Use Custom Actions

When your REST API exposes a custom action, let’s see how you can invoke the custom action in your Excel workbook, for example, a custom action called "Close" that's exposed by a purchase order business object to close purchase orders.

Note:

Your REST API must expose custom actions on the item path for your resource, something like a POST to /contextRoot/v1/myBusObj/{itemId}/action/doMyAction. Actions defined on the collection path are not supported. For other limitations, see Limitations, Known Issues, and Other Notes.

Create a layout for the custom action, for example, a Table layout for the "Close" custom action.
1. In the Oracle Visual Builder tab, click Designer.
2. When prompted, provide the service description document.
3. Choose a business object, for example, purchaseOrders.
  
  Description of the illustration custom_action_purchaseorders.png
4. Select Table Layout and click OK.
  
  Description of the illustration custom_action_tablelayout.png
A table layout that includes column headers and a placeholder data row is created in the Excel workbook.
Create new columns in the layout to pass payload field values that the custom action needs. In this example, we'll add columns to show the Close Action and the Close Reason payload fields.
1. In the Layout Designer, click Columns, then click Manage Columns ().
  
  Description of the illustration custom_action_columns.png
2. Click Custom Actions in the Table Column Manager.
3. In the Selected Fields pane, select the location where you want the payload fields' columns to be added. The columns will be inserted before the selected field.
4. In the Available Fields pane, select the payload fields (Close Action and Close Reason).
  
  Description of the illustration custom_action_columns_available_fields_selected.png
5. Click Done.
6. Click Redraw Layout.
The newly added columns show in the worksheet table.
Mark rows for the custom action.
1. Click Download Data to download data to the table.
2. Update cells that correspond to the custom action’s payload fields, in our example, cells that correspond to the Close Action (Close) and the Close Reason (Close) columns.
  
  You can mark cells for action simply by entering values in cells that correspond to custom action columns. Alternatively, you can click the Table Row Changes menu and select Mark for Action.
  
  Description of the illustration custom_action_close_updateonecell.png
  
  Tip:
  To mark several rows for the custom action, enter values in the custom action column's cells (for example, Rejected in the Close Action (Close) column and Over budget in the Close Reason (Close) column), then copy and paste the values to other rows.
  
  Note:
  When marking cells for action, if you enter a value in a custom action column's cell before making other edits in that row, the row is automatically marked for that custom action. For example, in the following image, adding Rejected in cell D2 marks the row for the Close custom action. Note how fields that don't correspond to a custom action in that row (PO Header Id and Order Number) can no longer be edited. Editing fields that don't involve custom actions in row 3 marks the row as an Update, but now, the custom action cells in that row (corresponding to the Close Action (Close) and Close Reason (Close) columns) cannot be updated.
  
  Description of the illustration auto_mark_rows_closeaction.png
3. If you used the Mark for Action option and only one custom action is defined for the business object, you're prompted to confirm. If more than one custom action is defined, you're prompted to select from a list of custom actions.
The selected table rows are updated in the Change column, and the Status Viewer indicates that the rows are pending the selected action. Up to this point, no REST requests have been made and the custom actions have not been performed. Data entry validation is performed at this point on custom action field columns for the current action.
Click Upload Changes to send your changes to the REST endpoint and invoke the custom action on the marked rows. See Upload Changes for Custom Actions.

Use Custom Actions in a Form Row of a Form-over-Table Layout

When the REST service in your workbook exposes custom actions, you can perform those actions on a Form row in a Form-over-Table layout.

In a Form-over-Table layout, click Download Data.
Click the Form Changes menu and select Perform Action. You can perform a custom action only on an existing row (not on a pending Create row).

Description of the illustration form_perform_custom_action.png

If multiple custom actions are found, you are prompted to select an action, as shown here. Otherwise, you are prompted to confirm the action.
If payload fields are required, provide a value for each payload field.
Click Perform Action.

The result of the custom action is returned. You can also view details in the Status Viewer.
To refresh data in the form row, click Download Data. Form row data is not automatically refreshed after a custom action is performed, even if the action was successful.

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.

Properties such as Title (which appears in the UI that the workbook user sees) and Description can be edited as needed. Other properties of the custom action should generally be left as is. Payload fields can be edited by clicking the Edit button or double-clicking an entry in the list.

Description of excel-custaction.png follows

Description of the illustration excel-custaction.png

Service Description for Custom Actions

If a given REST API supports custom actions, they are described in the OpenAPI v3 service description document generated by the Oracle business object REST API service. For example, a close custom action would appear in the paths collection:

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

"/purchaseOrders/{purchaseOrders_Id}/action/close": {
    "parameters": [
      {
        "$ref": "#/components/parameters/purchaseOrders_Id"
      }
    ],
    "post": {
      "summary": "close",
      "description": "close",
      "operationId": "do_close_purchaseOrders",
      "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": {
                "closeAction": {
                  "type": "string",
                  "nullable": true
                },
                "closeReason": {
                  "type": "string",
                  "nullable": true
                }
              },
              "additionalProperties": false
            }
          }
        }
      }
    }
  }

Note the following:

The path entry contains a path parameter for the row/item ID, for example, /purchaseOrders/{purchaseOrders_Id}/action/close"
The end of the path entry (close) 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.

Limitations, Known Issues, and Other Notes

Custom actions that correspond to view object methods (as opposed to view object row methods) are not currently supported.

Custom actions are not supported for pending Create rows or form in Create mode.

Custom actions defined in the OpenAPI 3 service description document that have request payload schema members that match business object fields are unlikely to function properly.

When an Upload operation contains one or more custom action invocations, the entire operation will be performed on a row-by-row basis (one PATCH/POST/DELETE request made for each of the participating rows). For best performance of bulk Updates, Creates, and Deletes, avoid mixing custom action invocations into those bulk operations.

Oracle business object REST API service OpenAPI 3 service descriptions 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.