Invoke an Endpoint Dynamically

You can dynamically invoke a REST endpoint/URL at runtime without configuring additional invoke connection or REST outbound details. As long as the Oracle HCM Cloud REST APIs return a response with HATEOS links, you can use this feature by mapping the HATEOS link to the invoke connection. This feature is useful in situations that require invoking a REST endpoint dynamically or when the endpoint is not known at design time. This feature is also useful in situations that require invoking multiple REST services, all of which accept the same input payload and return the same response payload as configured for the outbound endpoint. For these cases, this feature eliminates the need to create multiple connections to invoke each REST endpoint.

Note:

Note the following restrictions.

• The request and response schema must be the same as provided during endpoint configuration.

• Template parameters are not supported while mapping these properties.

• The HTTP verb cannot be changed for the endpoint URL. For example, if the endpoint is configured to use POST, the outgoing request uses POST even if the endpoint URI changes at runtime.

• Because the endpoint URL is determined at runtime, there is no facility to test whether the security credentials provided during connection configuration also work with the new endpoint URL. If you think the endpoint URL determined at runtime requires a different authorization header then the original URL, you may need to provide a mapping for the authorization standard header.

This use case provides a high level overview of one way to design an integration that uses dynamic endpoints. You retrieve child objects using the REST API (for example, Primary Address is a child object of the Account parent object). The integration is designed as follows.

• An initial invoke is configured to get the Account object by using the REST API. The response of this REST API does not provide the child objects. Instead, there are HATEOS links to the child objects (that is, the Primary Address object).

• A second invoke uses the HATEOS links from the earlier response to make another invoke connection to the REST endpoint to fetch the child Primary Address object using dynamic REST endpoint support.

To change the endpoint configuration at runtime, you map one or more of the various properties under the ConnectivityProperties target element.

1. Create an orchestrated integration.
2. Drag an adapter into the integration canvas as an trigger connection (it can be any adapter).
3. Configure the adapter in the Adapter Endpoint Configuration Wizard.
4. Drag an initial Oracle HCM Cloud Adapter into the integration canvas as an invoke connection.
5. Configure it to use the hcmRESTApp service application, the Account object (business resource), and the get operation.

   The response of the first invoke connection contains a collection of HATEOS links, each pointing to a child object such as Primary Address.

6. In the mapper between the trigger adapter connection and the Oracle HCM Cloud Adapter invoke connection, map source elements to target elements. For this example, a PartyNumber source element is passed to an id target element.
   
   
   Description of the illustration mapper1.png
   
7. Add a for-each action to iterate between the HATEOS links. The value in the Repeating Element field is from the response object.
   
   
   Description of the illustration for_each.png
   
8. Add a switch action to get the HATEOS link corresponding to the Primary Address object.
   
   Description of the illustration switch.png
9. Drag the Oracle HCM Cloud Adapter into the switch action as the second invoke connection.
10. Configure it to use the hcmRESTApp service application, the Primary Address object (business resource), and the getAll operation. This object uses dynamic REST endpoint support. The Primary Address is a collection of links. The getAll operation is selected for getting all the HATEOS links.
11. In the mapper immediately before the second Oracle HCM Cloud Adapter invoke connection, expand RestApi under ConnectivityProperties in the target section.
12. From the source section, map href to AbsoluteEndpointURI under ConnectivityProperties. The ConnectivityProperties schema element supports dynamic REST endpoints. The href element points to the Primary Address object link. The href element is invoked by the Oracle HCM Cloud Adapter.
    
    
    Description of the illustration dynamic_mapping.png
    
13. If necessary, map other nodes under ConnectivityProperties. The runtime values provided by these mappings dynamically configure the request.

    You can also hover the cursor over these properties for brief descriptions.

    Element	Description
    AbsoluteEndpointURI	Represents the absolute endpoint URL that the REST Adapter invokes. Empty values are ignored. To route the request to an endpoint URL determined at runtime, provide a mapping for this element. AbsoluteEndpointURI takes first precedence among other URL-related properties under ConnectivityProperties.
    BaseUri	The equivalent of the base URL provided during connection configuration. To substitute only the base URI and retain the rest of the URL, provide a mapping for this element. The mapping is ignored if AbsoluteEndpointURI has a nonempty runtime value.
    RelativeUri	Forms the part of the endpoint URI between BaseUri and ?. The mapping has no effect if BaseUri has an empty runtime value or AbsoluteEndpointURI has a nonempty runtime value. The runtime value must start with a /.
    Uri	Use the various elements under this node to substitute runtime values for the specific parts of an endpoint URL.
    Scheme	Provide a mapping to change only the scheme of the endpoint URL. Supported values are HTTP and HTTPS.
    Host	Provide a mapping to change only the Host portion of the endpoint URL
    Port	Provide a mapping to change only the port of the endpoint URL.
    Query	Provide a mapping to change only the query portion of the endpoint URL. A query portion follows the ?.
    Path	Provide a mapping to change only the path portion of the endpoint URL. A Path is the part of a URI between the hostname and ?.
    Plugin	The various properties under this node impact the way the REST Adapter invokes the endpoint URL.
    PostQueryString	When the runtime value is true and the HTTP verb is POST, the query string parameters are sent using POST as form parameters. The default is false.
    UseFormUrlEncoding	When the runtime value is false, the REST Adapter uses RFC 3986-compliant encoding to encode the query parameters. The default is true. This is the equivalent of setting the custom header x-ics-use-x-www-form-urlencoded to false. See section “RFC 3986 Support for Encoding Query Parameters” for more information on x-ics-use-x-www-form-urlencoded. x-ics-use-x-www-form-urlencoded takes precedence when both are set.

14. Drag an FTP Adapter to the switch action for writing the Primary Address object response to a file on an FTP server.
15. In the mapper between the Oracle HCM Cloud Adapter and the FTP Adapter, map the Primary Address object details.
    
    Description of the illustration mapper3.png
    
16. When complete, integration design looks as follows:
    Description of the illustration dynamic_integration.png
17. Activate and invoke the integration. The Oracle HCM Cloud Adapter invokes the endpoint URI determined at runtime.