Custom Actions

Describe Custom Actions

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

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

"/Employees/{Employees_Id}/action/adjustSalary": {
"parameters": [
{
  "$ref": "#/components/parameters/Employees_Id"
}
],
"post": {
"tags": [
  "Employees"
],
"summary": "adjustSalary",
"description": "adjustSalary",
"operationId": "do_adjustSalary_Employees",
"parameters": [
  {
    "$ref": "#/components/parameters/REST-Framework-Version"
  }
],
"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": {
	  "proposedSalary": {
	    "type": "number",
	    "nullable": true
	  },
	  "ajdustmentReason": {
	    "type": "string",
	    "nullable": true
	  }
	},
	"additionalProperties": false
      }
    }
  }
}
}
}

Note the following:

The path entry is a templated-string that includes the row/item ID. For example /Employees/{Employees_Id}/action/adjustSalary.
The end of the path entry (adjustSalary) exactly matches the Java method name.
The presence of a POST operation for the action path entry is required.
The tags property under the post operation maps the custom action definitions to the corresponding business objects.
In the requestBody schema, there are properties that match the parameters defined in the Java method signature. In this document, these properties are referred to as custom action Payload Fields.

Use 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 and Description can edited as needed. The value of the Title property appears in the UI that the user of the workbook sees. 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

To pass argument values that the custom action needs, such as proposed salary, you create new columns in the Table Layout that map to the payload field of the custom action.

In the Layout Designer, click the Columns tab and click the Add a column for a custom action payload field button ().
In the Custom Actions dialog that appears, expand the custom action to select the payload field, and click OK.

The add-in adds a new column to the Table layout.

After downloading some existing rows, you perform the custom action as follows:

Select one or more rows in the Table Layout or in the table of a Form-over-Table layout.
Click the Row Changes drop-down list and click Mark for Action.

If more than one custom action is defined for the business object, a dialog appears that allows you to search for and select a custom action. After selecting the custom action, 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.

You click Upload Changes to perform the custom actions. For each row that you marked for action, the add-in performs the following steps:

Creates the payload by collecting the cell values for each custom action field column and adding the value to a simple JSON object (member name/value pairs) in the payload. The entire payload body follows this example format:
```
{
  "proposedSalary": 75123,
  "ajdustmentReason": "superior job rating"
}
```
- There is no other content in the POST request body (no action name, no array of argument values).
- Should any values from these columns be invalid (missing when required, incorrect data type, Excel formula error) the row will be omitted from the Upload operation and marked as failed
Prepare the request
- REST-Framework-Version header added (version 6)
- Content-Type header added (application/vnd.oracle.adf.action+json)
Make the request
- Send the POST (POST is the only HTTP method supported for invoking custom actions)
- See the note below about BATCH requests.
Process the response
- For 200 response status, the row is marked as succeeded
- For 400 response status, the row is marked as failed, and the response payload is parsed for Oracle RAMP REST service error content, any error details can be seen in the Status Viewer pane.
- A 412 response status indicates that the row was modified by some other agent or user after it was downloaded into the Excel table; such a status treated as a row-level error
- Note: cell values in action rows are not refreshed. If the custom Java method logic has altered any values in the row, such changes will not be reflected in table row until the next Download operation.

For any rows marked for Update or Create, custom action field columns' values are reset to empty as part of Upload.

Rows marked for action can be combined with Update, Create, and Delete rows in the same Upload operation. For rows marked for Update, Create, or Delete, the cell values for all custom action field columns are ignored:

They are not included in the request payload (eg. for Update (PATCH) or Create (POST))
Invalid values in such cells do not prevent the Upload operation on that row from proceeding

Until a row is marked for action, cell values in custom action field columns do not participate in data entry validation. Likewise, for a row with an empty Change column, any edits to cells in custom action field columns do not convert the row to a pending Update row. Edits to custom action field columns' cells are ignored in rows marked as pending Create.

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 supported for existing rows in the Table layout and the child table in a Form-over-Table layout. Performing actions on the parent form row in a Form-over-Table layout is not supported.

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.

Invocation of custom actions in Batch request mode is not currently supported by the Oracle RAMP REST service. As such, when an Upload operation contains one or more custom action invocations, then 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 RAMP REST 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.