Dynamically Update REST Adapter Invoke Connections at Runtime

You can dynamically update the REST Adapter invoke connection to use at runtime. This feature lets you use a single integration to send requests to multiple end systems or instances of the same application and eliminates the need to create a separate integration for each endpoint or multiple invoke connections configured in a switch action in a single integration.

Dynamic Connection Capabilities

Dynamic connections provide the following capabilities.

  • Connections can be local to a project, shared between projects, or standalone (that is, available globally and not under the context of a project).
  • Each connection can be defined with different properties and security policies. Some examples include the following:
    • An invoke connection configured with the API Key Based Authentication security policy at design-time can be overridden at runtime by an invoke connection configured with the OAuth Custom Three Legged Flow security policy.
    • Two invoke connections may use the same security policy, but each connection is registered with a different user account for accessing the endpoint application (for example, different Google Gmail accounts). One invoke connection with its unique user account can be overridden at runtime by an invoke connection configured with a different user account.
  • A connection can be overridden with the connectivity agent. For example, an invoke connection configured without the connectivity agent at design-time can be overridden at runtime by an invoke connection configured with the connectivity agent.
  • The runtime connection to use is defined by a property in the payload of the incoming message or through the result of a lookup table function.
  • For any invoke connection, you can specify an XPath expression or optionally a lookup table function result on the source payload. Once evaluated against the actual data, the value of the connection ID to use at runtime is provided for that particular invoke connection.

    Note:

    Lookup table-based expressions are supported only in the design-time lookup wizard and not in the mapper at runtime.
  • The invoke connection used dynamically can be tracked and monitored in the activity stream at runtime.

Configure and Use a Dynamic Connection

Let's look at a high-level overview of how to create and use a dynamic connection.

  1. Create an application integration.
  2. Create and configure a REST Adapter trigger connection.
  3. Create and configure multiple REST Adapter invoke connections. For this example, two connections are configured with the following security policies:
    • Name: test-rest-1
      • Security Policy: API Key Based Authentication
    • Name: test-rest-2
      • Security Policy: OAuth Custom Three Legged Flow
  4. Drag the test-rest-1 REST Adapter invoke connection into the integration canvas.
  5. On the Basic Info page, specify details, including the name, description, endpoint relative resource URI from which to obtain the endpoint response, action to perform on the endpoint (for example, GET), whether to receive a request or response, and any headers.
  6. On the Dynamic Connections page, select Enable Dynamic Connection to map the ID from the request body of the trigger connection.

    The Dynamic Connection ID field is displayed.

  7. Click Switch to Developer View Switch view icon.
  8. Specify a dynamic connection ID in either of two ways.
    • Input sources: Click to pass the connection ID as an XPath expression with the dynamic-connection-id query parameter. The XPath expression evaluates to the connection ID of the dynamic invoke connection used at runtime.
    • Functions: Click to use a lookup table function to pass different connection IDs representing the different regions.

      For this example, the dynamic-connection-id XPath expression is dragged from the Input sources tree to the field.


      The integration canvas shows a trigger connection, map action, and invoke action. On the right is the View Dynamic Connections page. The Enable Dynamic Connection checkbox is selected. Below this is the Dynamic Connection ID field.

  9. Complete the remaining pages of the Adapter Endpoint Configuration Wizard.
  10. Complete integration design, then activate. For this example, the integration looks as follows.


    The integration shows a trigger connection, map action, invoke action, log action, and map action.

    It's time to run the integration.

  11. Hover over the integration to run.
  12. From the Actions Actions icon menu, select Run.
  13. In the Body tab, specify a different invoke connection to use at runtime (for this example, test-rest-2). This invoke connection is configured with a different security policy (OAuth Custom Three Legged Flow) and overrides the test-rest-1 invoke connection configured with the API Key Based Authentication security policy that you added at design-time.
    "dynamic-connection-id": "test_rest_2"

    Note:

    If you specify only quotes, the design-time connection is used by default.
    "dynamic-connection-id": ""
  14. Click Run.
  15. Expand the connection in the activity stream.

    A connection message indicates the dynamic invoke connection of test-rest-2 was used instead of the test-rest-1 design-time connection.