Connection Properties and Sample Code

Properties in the connectionProperties Section

In connectionProperties, you define the behavior of a single connection property. Keep in mind the following points:

Each collection of properties in connectionProperties is related to a single connection property.

The connection property appears as a field in Oracle Integration when an integration developer configures a connection. For instance, the displayName property defines the property name that appears in the user interface, the shortDescription property provides brief hint text, and so on.

The collection of properties model the behavior of the connection property.
You can specify whether a connection property in Oracle Integration appears in an invoke connection, a trigger connection, or both.
Many properties below define metadata. However, pay particular attention to the functional properties: required, hidden, and scope.

connectionProperties includes the following properties.

Property	Description
`name`	Unique name for the connection property. The value must contain no spaces. The value does not appear in the Oracle Integration user interface. However, you use this value to reference the property from within the adapter definition document.
`displayName`	Name of the connection property. This value appears as the name of the property in the Oracle Integration user interface when an integration developer creates a connection using the adapter. See Update the Name or Description of a Connection Property.
`shortDescription`	Short hint text for the connection property. This text appears in the Oracle Integration user interface.
`description`	Description of the property. This description appears on the Oracle Integration user interface when you select a property to update or modify.
`type`	Data type of the property. The following data types are supported: `STRING` `NUMBER` `URL` `PASSWORD` `TEXT` `CHOICE` `BOOLEAN`
`required`	Either `true` or `false`, indicating whether the adapter requires a value for the property. When `true`, the property has an asterisk in the Oracle Integration user interface, and integration developers must provide a value. Sometimes, an adapter requires a value for a property, and the value is always the same. In such cases, consider setting `required` and `hidden` to `true` and specifying the value using the `default` property. See Hide a Connection Property.
`hidden`	Either `true` or `false`, indicating whether the property is hidden to integration developers. If you specify `true`, indicating that the property is hidden, you must provide a default value using the `default` property. For example, you might set the `releaseVersion` parameter to hidden and specify its default value to `1A`. See Hide a Connection Property.
`tokenized`	Either `true` or `false`, indicating the location in which the value of the property is stored: When `true`, the value is stored in a database, and a reference to the value is saved with the integration. If an integration developer exports the integration and imports it into another environment, the value is not included in the import. The developer must specify a new value for the property while configuring the connection in the target environment. When `false`, the value is saved as part of the integration. If an integration developer exports the integration and imports it into another environment, the integration continues to work with the fixed value that the developer specified.
`default`	Default value for the property. This value appears in the property field in the Oracle Integration user interface.
`scope`	Type of connection that the connection property applies to: `TRIGGER`: The connection property appears only when integration developers configure trigger connections, which securely expose integration flows to external applications. `ACTION`: The connection property appears only when integration developers configure invoke connections, which securely connect to and invoke external applications. For example, you might configure ten connection properties, five for trigger connections and five for invoke connections.
`options`	Provide a predefined list of values in a drop-down list. An integration developer can select from the values when creating a connection in Oracle Integration. Below the options property, add one or more sets of the following properties: `keyName`: Internal name of the value. `displayName`: User-facing name of the value. This value appears to integration developers in a drop-down list for the connection property. See Create a Connection Property with a Drop-Down List.

Properties in the securityPolicies Section

In securityPolicies, define one or more security policies for a connection definition. Security policies define how a connection accesses protected endpoints and Oracle Integration.

When you convert a Postman collection or an OpenAPI document into an adapter definition document, the Rapid Adapter Builder collects security policy information about the APIs and enters it into the securityPolicies section. If needed, you can update some security policy details.

The Rapid Adapter Builder supports a number of managed security policies, including several extensible policies. You can't add and modify properties of managed security policies. However, you can make a number of updates, including hiding security policy properties and providing a default value instead, and changing the display name and description of a managed security policy. See Understand Security Policies in Connection Definitions.

You can define one or more security policies in each connection definition. Each security policy can contain one or more security properties. For each entry in the securityProperties section, you must define the following set of properties. These properties describe the behavior of the field that the integration developer interacts with while configuring a connection.

securityPolicies includes the following properties.

Property	Description
`type`	Usage of the security policy: `managed`: The security policy is an authentication and authorization scheme that is natively implemented in the Rapid Adapter Builder. Additionally, the scheme is a managed security policy that governs one of the following types of connections: Trigger connections, which securely expose integration flows to external applications. Invoke connections, which securely connect to and invoke external applications. `composite`: The security policy is an extension of a managed security policy and wraps two policies in one. A composite policy governs inbound (trigger) connections that also must make outbound (invoke) calls. `selfManaged`: Reserved for future use.
`description`	Description of the security policy.
`displayName`	Name of the security policy. This value appears as the name of the security policy in the Oracle Integration user interface when an integration developer creates a connection using the adapter.
`scope`	Role for the security policy: `TRIGGER`: The security policy is used for a trigger operation. `ACTION`: The security policy is used for an invoke operation. Note: You specify a scope for both a connection property and a security policy. For example, you might define four connection properties for invoke connections and six connection properties for trigger connections. Similarly, you might define two security policies for invoke connections and one security policy for trigger connections.
`policy`	Name of the security policy that is used to access protected endpoints. You adapter can expose one or more of the following policies: Security policies for invoke connections: `BASIC_AUTH` `API_KEY_AUTHENTICATION` `OCI_SIGNATURE_VERSION1` `OAUTH_ONE_TOKEN_BASED` `OAUTH_RESOURCE_OWNER_PASSWORD_CREDENTIALS` `OAUTH_CLIENT_CREDENTIALS` `OAUTH_AUTHORIZATION_CODE_CREDENTIALS` `OAUTH_JWT_USER_ASSERTION` `OAUTH_JWT_CLIENT_ASSERTION` Security policies for trigger connections: `BASIC_AUTH` `OAUTH2.0_TOKEN_VALIDATION` `HMAC_SIGNATURE_VALIDATION` `RSA_SIGNATURE_VALIDATION` `JWT_VALIDATION`
`policyInbound`	`policyInbound` is required when the `type` property is `composite`. `policyInbound` is a complex object and requires the following properties: `type`: One of the following values: `managed`: The inbound security policy is a predefined managed security policy. `nonManaged`: Reserved for future use. `policy`: See the `policy` row. `securityProperties`: See the `securityProperties` row.
`policyOutbound`	`policyOutbound` is required when the `type` property is `composite`. `policyOutbound` is a complex object and requires the following properties: `type`: One of the following values: `managed`: The outbound security policy is a predefined managed security policy. `nonManaged`: Reserved for future use. `policy`: See the `policy` row. `securityProperties`: See the `securityProperties` row.
`securityProperties`	Properties for each security policy. Most security policies require several sets of these properties. Each property that you define appears on the page for configuring connection security. Integration developers must specify the appropriate values for each property. `name`: Name used to reference the security policy property. `displayName`: Name of the security policy property that appears on the connection page. See Change the Display Name or Description of a Security Property `shortDescription`: Short hint text for the security property. `description`: Description of the security property. See Change the Display Name or Description of a Security Property `type`: The data type of the property. The following data types are supported: `STRING` `NUMBER` `URL` `PASSWORD` `TEXT` `CHOICE` `BOOLEAN` `required`: Specifies whether it is a required property. If set to true, the property is marked as required on the connection page and the integration developer must provide a value. `hidden`: Hides the property. If set to true, the property does not appear on the connection page. You must specify a default value of you are hiding a property. See Hide a Security Property. To see the predefined values for each of these properties security policy, see the appropriate link: Outbound security policies: HTTP Basic Authentication API Key Based Authentication OCI Signature Version 1 OAuth 1.0 One-Legged Authentication OAuth Resource Owner Password Credentials OAuth Client Credentials OAuth Authorization Code Policy OAuth JWT User Assertion OAuth JWT Client Assertion Inbound security policies Basic Authentication OAuth 2.0 Access Tokens HMAC Signature Validation RSA Signature Validation JWT Validation
`authExtension`	The default implementation of these policies is RFC 6749 compatible. However, in practice, many implementations different from the RFC guidelines. Using the `authExtension` properties, you can extend the steps of the OAuth flow in the security policy. You can extend the following OAuth policies if needed: OAuth Resource Owner Password Credentials OAuth Client Credentials OAuth Authorization Code Policy

Sample Code: Define a Connection Definition

The following code sample defines a connection definition for the Square application using the OAuth Authorization Code Credentials authentication mechanism.

This sample includes one connectionProperties section, one securityPolicies section, and several securityProperties sections.

"connection": {
  "connectionProperties": [
    {
      "name": "baseURL",
      "type": "URL",
      "displayName": "Base URL",
      "description": "Base URL of the endpoints",
      "shortDescription": "Base URL of the endpoints",
      "default": "https://connect.squareupsandbox.com/v2",
      "required": true,
      "hidden": true,
      "scope": [
        "ACTION"
      ]
    }
  ],
  "securityPolicies": [
    {
      "type": "managed",
      "policy": "OAUTH_AUTHORIZATION_CODE_CREDENTIALS",
      "description": "Authorization Policy",
      "displayName": "Authorization Policy",
      "scope": "ACTION",
      "securityProperties": [
        {
          "name": "oauth.client.id",
          "displayName": "Square Application ID",
          "description": "Square Application ID",
          "shortDescription": "Square Application ID",
          "hidden": false,
          "required": true
        },
        {
          "name": "oauth.client.secret",
          "displayName": "Square Application Secret",
          "description": "Square Application Secret",
          "shortDescription": "Square Application Secret",
          "hidden": false,
          "required": true
        },
        {
          "name": "oauth.auth.code.uri",
          "default": "https://connect.squareupsandbox.com/oauth2/authorize",
          "hidden": true,
          "required": true
        },
        {
          "name": "oauth.access.token.uri",
          "default": "https://connect.squareupsandbox.com/oauth2/token",
          "hidden": true,
          "required": true
        },
        {
          "name": "oauth.scope",
          "default": "CUSTOMERS_WRITE ORDERS_WRITE INVOICES_WRITE CUSTOMERS_READ",
          "hidden": true,
          "required": true
        },
        {
          "name": "clientAuthentication",
          "default": "client_credentials_in_body",
          "hidden": true,
          "required": true
        }
      ],
      "authExtension": "flow:authExtension"
    }
  ],
  "test": "flow:testConnectionFlow"
}

Sample Code: Define a Connection Property

The following sample code shows how to define two connection properties. The first part of the sample demonstrates the definition of an editable property, and the second part demonstrates the definition of a hidden property.

"connectionProperties": [
  {
    "name": "accountid",
    "type": "string",
    "displayName": "Account ID",
    "shortDescription": "Enter the account id.",
    "required": false,
    "hidden": false,
      "scope": [
        "ACTION"
      ]
  },
   {
    "name": "baseURL",
    "type": "URL",
    "displayName": "Base URL",
    "shortDescription": "Ensure that this value corresponds to the type selected.",
    "required": false,
    "hidden": true,
    "default": "https://connect.abcxyz.com/v2",
    "scope": "ACTION"
  }
]

Sample Code: Define Security Policies within a Connection Definition

The following sample code shows how to define security policies. In this case, the connection supports two managed security policies, each of which has a combination of displayable and hidden security properties.

"connection": {
    "connectionProperties": [
    ],
    "securityPolicies": [
      {
        "type": "managed",
        "policy": "OAUTH_AUTHORIZATION_CODE_CREDENTIALS",
        "description": "ABC Company Authorization Code Policy",
        "displayName": "ABC Company Authorization Code Policy",
        "scope": "ACTION",
        "securityProperties": [
          {
            "name": "oauth.client.id",
            "displayName": "ABC Company Client ID",
            "description": "ABC Company Client ID",
            "shortDescription": "ABC Company Client ID",
            "hidden": false,
            "required": true
          },
          {
            "name": "oauth.client.secret",
            "displayName": "ABC Company Client Secret",
            "description": "ABC Company Client secret",
            "shortDescription": "ABC Company Client secret",
            "hidden": false,
            "required": true
          },
          {
            "name": "oauth.auth.code.uri",
            "default": "https://login.ABC Companyonline.com/common/oauth2/v2.0/authorize",
            "hidden": true,
            "required": true
          },
          {
            "name": "oauth.access.token.uri",
            "default": "https://login.ABC Companyonline.com/common/oauth2/v2.0/token",
            "hidden": true,
            "required": true
          },
          {
            "name": "oauth.scope",
            "default": "Tasks.ReadWrite offline_access",
            "hidden": true,
            "required": true
          },
          {
            "name": "clientAuthentication",
            "default": "client_credentials_as_header",
            "hidden": true,
            "required": true
          }
        ]
      },
      {
        "type": "managed",
        "policy": "OAUTH_RESOURCE_OWNER_PASSWORD_CREDENTIALS",
        "description": "ABC Company Resource Owner Password Credentials Policy",
        "displayName": "ABC Company Resource Owner Password Credentials Policy",
        "scope": "ACTION",
        "securityProperties": [
          {
            "name": "oauth.access.token.uri",
            "default": "https://login.ABC Companyonline.com/4a4a30f3-247a-47b6-acef-55ba707ea6df/oauth2/v2.0/token",
            "hidden": false,
            "required": true
          },
          {
            "name": "oauth.client.id",
            "displayName": "ABC Company Client ID",
            "description": "ABC Company Client ID",
            "shortDescription": "ABC Company Client ID",
            "hidden": false,
            "required": true
          },
          {
            "name": "oauth.client.secret",
            "displayName": "ABC Company Client Secret",
            "description": "ABC Company Client secret",
            "shortDescription": "ABC Company Client secret",
            "hidden": false,
            "required": true
          },
          {
            "name": "username",
            "displayName": "User Name",
            "description": "User Name",
            "shortDescription": "User Name",
            "hidden": false,
            "required": true
          },
          {
            "name": "password",
            "displayName": "Password",
            "description": "Password",
            "shortDescription": "Password",
            "hidden": false,
            "required": true
          },
          {
            "name": "oauth.scope",
            "default": "Tasks.ReadWrite offline_access",
            "hidden": true,
            "required": true
          },
          {
            "name": "oauth.request.content.type",
            "default": "application/x-www-form-urlencoded",
            "hidden": true,
            "required": true
          },
          {
            "name": "clientAuthentication",
            "default": "client_credentials_as_header",
            "hidden": true,
            "required": true
          }
        ]
      }
    ],
    "test": "flow:testConnectionFlow"
  },