Service Metadata and Response Schemas for Custom Actions

If a given REST API supports custom actions, they are described in the OpenAPI service metadata generated by the ADF REST service. For example, a reject BO 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 BO 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 BO 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.

Row Status Custom Action Response Schema

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"
    }
  ]
}