1. Using the Rapid Adapter Builder with Oracle Integration 3
  2. Work with the Adapter Definition Document
  3. Update Action Definitions
  4. Work with Action Definitions
  5. Design of Configuration Fields

Design of Configuration Fields

This section describes how to design configuration fields to configure an endpoint.

The configuration of an action may require the user to select multiple configuration fields. The Rapid Adapter Builder platform provides the flexibility to configure actions so that users:

  • Can select configuration fields through selective options.
  • Are presented with a set of valid choices to make.
  • Do not make mistakes while configuring actions.
  • Are presented with a set of values that are retrieved based on the user's input.

Once the user makes the required choices, the set configuration fields drive the runtime execution of the action.

For example, the adapters in Oracle Integration allow integration designers to configure how APIs call external applications. The following screenshot shows how the Oracle ERP Adapter in Oracle Integration presents the user with three choices representing various areas of fusion applications.


Configuring actions in Oracle Integration

These configuration fields appear as user interface widgets in the Oracle Integration user interface. A configuration field has the following properties:

  • name
  • displayName
  • description
  • type
  • required
  • options
  • dependencies

For more information about the properties, see Actions Properties and Sample Code.

The type property defines the type of user interface component to use for user selection. It includes user interface components like list box, text box, button, and so on. To learn more about how to use each user interface component, see Design User Interface Components of an Adapter.

Types of Configuration Dependencies

The types of adapter configurations are:

  • No dependency

    A set of configuration fields that are independent of each other. Selecting a value from a configuration field doesn't impact or drive other configurations.

    Note:

    The adapter developer need not specify the dependencies property if a configuration field has no dependency.
  • Field dependency

    Selecting a value from a configuration field may impact and initiate other configurations.

    Example 1: In the Oracle ERP adapter, selecting the business objects displays a list of business objects in the list box.

    Example 2: A Google Sheet adapter provides an operation to insert a row into a spreadsheet. As the first configurable step, the user selects the spreadsheet. Since a spreadsheet can contain multiple worksheets, as the next configurable field, the adapter initiates the selection of a worksheet.

  • Value dependency

    A configuration field drives the visibility and field values of one or more subsequent fields. For example, in the Oracle ERP adapter, when the user selects Business (REST) Resources from the Browse By dropdown, the field initiates/displays an additional dropdown option for Service Application where the user can provide the values like crmRestApp and hcmRestApp. However, if the user selects Business Objects from the Browse By field, the adapter doesn't display the Service Application field. In the example, only the value of Business (REST) Resources determine the display of the Service Application field.

Designing a Dependency

Declaring the dependency clause in the child or dependent field provides an indication to the child field about the parent field that it depends on. A child field can have only one parent that drives its functionality. Specifying an empty array in the values key signifies that any value of the parent can drive the functionality of the child.

Consider a business use case of a user selecting a worksheet within a spreadsheet. Displaying worksheets is not driven by specific values of the spreadsheet. Any value selected drives the worksheet field's visibility and field values. To configure an action, a spreadsheet selection is not dependent on the selection of a worksheet.

Sample code:

"dependencies": {
  "parentOption": {
    "values": []
  }
}

No Dependency

User selection of options may result in the action to call specific APIs. Consider a business scenario where a user has to select two independent static query parameters so that the API responds correctly and retrieves detailed object information. In this scenario, since the two static query parameters are independent of each other, the fields don't depend on each other. When there are no dependencies, user selection of configuration fields can happen in any order, and hence all the user interface widgets appear.

The following sample code shows two configuration fields that don't have any dependencies.

  • browse_by
  • restServiceApplication

The browse_by configuration field declares a static set of options for user selections and is designed as an array of objects. Each object has a keyName and displayName. The keyName is the internal identifier for the option, and the displayName is the name that appears on the user interface.

The restServiceApplication configuration field references a flow. The COMBO_BOX configuration field that appears on the user interface is derived from the execution of the flow.

Sample code:

[
      {
        "name": "browse_by",
        "displayName": "Browse By",
        "description": "Select the style of objects to configure.",
        "type": "COMBO_BOX",
        "required": true,
        "options": [
          {
            "keyName": "businessObjects",
            "displayName": "Business Objects"
          },
          {
            "keyName": "businessServices",
            "displayName": "Business Services"
          },
          {
            "keyName": "restResources",
            "displayName": "Business (REST) Resources"
          }
        ]
      },
      {
        "name": "restServiceApplication",
        "displayName": "Service application",
        "description": "Please select the REST service application",
        "type": "COMBO_BOX",
        "required": true,
        "options": "flow:getListOfRESTServiceApplication"
      }
    ]

Field Dependency

Selecting a parent field that results in deriving the values of a dependent child field is known as field dependency.

Consider a business use case where a user needs to insert a row into a Google spreadsheet. As a first step, the user selects the required spreadsheet from a dropdown list. The Google Sheet API is invoked to get the list of spreadsheets and populate the dropdown list. As the next step, the user selects the required worksheet since a spreadsheet can contain multiple worksheets.

This business use case shows how the selection of a spreadsheet results in the next step of selecting the worksheet. Selecting the worksheet configuration field is dependent on the selection of the spreadsheet configuration field.

The adapter developer can define the configuration fields for an action in the adapter definition document and ensure that both the following objectives are achieved:

  • Define the configuration field properties to display user interface widgets to enable the user to select.
  • Retrieve the keys and their values from external applications.

Value Dependency

In value dependency, the dependency clause is declared in the child or dependent field. The dependency clause specifies details of the parent to the child. The "values" array in the dependency declaration contains a series of values. These values can be either statically defined or driven by a function. The child field of the parent is relevant to the configuration only when the selected parent matches any of the values listed in the dependency declaration. For example, in the Oracle ERP adapter, the Service Application option is relevant when the parent option selected is Business (REST) Resources. If the selected parent option is Business Services or Business Objects, then the Service Application option does not appear to the user for selection because it is not relevant.

Sample code: Static keys for values for demonstration

"dependencies": {
  "parentField": {
    "values": ["bar1", "bar2"]
  }
}

Business use case

The top level option is the "Browse By". If the "Browse By" field selection matches "restResources", then the "Service application" field appears to the user. Selecting the "Service application" field results in displaying the "Rest Resources" field. However, if the "Browse By" field selection matches "businessServices", then the "Service application" field does not apply. Instead the backend logic for the "Business Services" field is executed and the resulting dropdown with the appropriate values is displayed to the user. 

[
      {
        "name": "browse_by",
        "displayName": "Browse By",
        "description": "Select the style of objects to configure.",
        "type": "COMBO_BOX",
        "required": true,
        "options": [
          {
            "keyName": "businessObjects",
            "displayName": "Business Objects"
          },
          {
            "keyName": "businessServices",
            "displayName": "Business Services"
          },
          {
            "keyName": "restResources",
            "displayName": "Business (REST) Resources"
          }
        ]
      },
      {
        "name": "restServiceApplication",
        "displayName": "Service application",
        "description": "Please select the REST service application",
        "type": "COMBO_BOX",
        "required": true,
        "options": "flow:getListOfRESTServiceApplication",
        "dependencies": {
          "browser_by": {
            "values": ["restResources"]
          }
        }
      },
      {
        "name": "restResources",
        "displayName": "REST resource",
        "description": "Please select the REST resource",
        "type": "COMBO_BOX",
        "required": true,
        "options": "flow:getListOfRESTResources",
        "dependencies": {
          "restServiceApplication": {
            "values": []
          }
        }
      },
      {
        "name": "businessServices",
        "displayName": "Business Services",
        "description": "Please select the Business Services",
        "type": "COMBO_BOX",
        "required": true,
        "options": "flow:getListOfRESTResources",
        "dependencies": {
          "restServiceApplication": {
            "values": ["businessServices"]
          }
        }
      }
    ]