1. Using Integrations in Oracle Integration Generation 2
  2. Integrate with Processes and Services
  3. Invoke a Co-located Integration from a Parent Integration

Invoke a Co-located Integration from a Parent Integration

You can invoke a co-located (child), active integration from the parent integration that you are designing through use of the local integration adapter. Co-located means the integration is running on the same host instance or in the same domain. Upon activation and invocation of the parent integration, it invokes and consumes the co-located integration.

Capabilities

The local integration adapter is a system adapter that is not exposed on the Connections page when you create a connection. Instead, the local integration adapter is invoked by a preseeded connection. It is created when creating an integration, if the local integration connection does not exist. This adapter has no connection properties and no security policies.

The local integration adapter works as follows:

  • You select an active integration from runtime (that is, co-located) to build a new integration. Note the following guidelines:

    • Active synchronous-synchronous, asynchronous with no callback, and scheduled integrations are available for selection.

    • Asynchronous with callback integrations do not appear.

    • De-activated and draft integrations do not appear.

    • Scheduled integrations are permitted as an invoke connection and automatically called by the Submit Now option.

  • You can add multiple child integrations. You can also add an integration containing a child integration (embedding multiple levels).

  • You can map return values downstream. This mapping functionality is the same as for any other invoke mappings in the integration.

  • You can add header support to the payload of the SOAP Adapter or REST Adapter used in the co-located (child) integration. See Create a Co-located Integration with Header Support.

  • You can create a parent integration using a REST Adapter invoke connection configured with the OpenAPI URL connection type to pass a binary payload to a child integration.

    Use binary data with payloads that are unstructured and inline (for example, application/octet-stream). The file contents are preserved, but require the receiver to determine the file type (for example, from the file name extension). The internet media type for an arbitrary byte stream is application/octet-stream.

  • You can dynamically invoke child integrations from a parent integration at runtime. This feature is useful for scenarios in which you must:
    • Invoke a REST endpoint dynamically or when the endpoint is not known at design time.
    • Invoke multiple REST child integration endpoints, all of which accept the same input payload and return the same response payload. This feature eliminates the need to design all child integrations in a switch action.

    See Dynamically Invoke a Co-located Integration.

The local integration adapter and the existing SOAP Adapter and REST Adapter differ as follows:

  • You do not need to create multiple connections (SOAP/REST) to invoke the local integration service.

  • Runtime communication always uses HTTP (that is, non-SSL).

This adapter is invoked internally in Oracle Integration to perform the local service invocation.

Restrictions

Note the following local integration restrictions:
  • You cannot pass stage file references from parent to child flows. The stage file is scoped in the context of its own flow instance and is not shared between parent and child flows. This is by design. Instead, pass the stage file from parent to child as an attachment.
  • OAuth with client credentials is not recommended.
  • You cannot create a child integration with a WSDL having a nested anonymous schema. As a workaround, manually edit the WSDL and make the schema non-anonymous.
  • SOAP-based child integrations:
    • A parent integration cannot send an attachment to a configured child integration.
  • REST-based child integrations:
    • A parent integration cannot send an attachment to a configured child integration.
    • A parent integration cannot process an XML payload that is expected by the child integration. The child flow must be configured to receive a JSON payload only, and cannot be invoked locally using an XML payload.

Best Practices for Designing Local Invoke Calls

  • Calls to schedule tasks or asynchronous integrations are always fine with a local invoke because they are not executed in the context of the current node.
  • Calls from nonparallel code sections are also always fine because the calling integration block is waiting for a response. There is currently no parallel capability in synchronous integrations. Therefore, a local invoke is always fine in a synchronous flow.
  • Calls from parallel code sections (parallel for-each and parallel file processing) are problematic when using a local invoke because they may use the same node for execution. In those cases, calls do not benefit from parallelism across nodes and instead are competing for resources on a single node.

Invoke a Co-located Integration with a Parent Integration

The following steps provide an overview of creating an orchestrated integration in which a parent integration invokes a co-located integration.

Note:

  • If you need to move a parent integration to another instance, it is best to include that integration and all its child integrations in a package.
  • If the following integrations are imported from one environment to another (having different host names), then editing the local (child) integration or editing the REST Adapter in the Adapter Endpoint Configuration Wizard leads to major changes in the mapper that may require remapping.
    • Integrations in which a co-located (child) integration is invoked from a parent integration.
    • Integrations with a REST adapter using a Swagger-based connection.
  1. Create and design an orchestrated integration.
  2. Add an integration action to an integration in either of the following ways:
    • On the right side of the canvas, click Actions icon and drag the Integration action to the appropriate location.
    • Click Plus icon at the location where you want to add the integration action, then select Integration.

    The Configure Local Integration Selection Wizard is displayed.

  3. Specify the following details, and click Next.
    Element Description

    What do you want to call your local integration invocation?

    Specify a name.

    What does this local integration invocation do?

    Specify a description.
  4. Specify the following details, and click Next.
    Element Description

    Integration

    Select the co-located integration to invoke. Only active integrations are displayed.

    Identifier

    Displays the identifier of the selected integration.

    Description

    Displays the description of the selected integration.
  5. Select the operation for the co-located integration to perform, and click Next. The operation depends on the child integration. Note the following:
    • If the child integration trigger connection is a REST Adapter, it can have Get, Post, Put, and Delete operations.
    • If the child integration trigger connection is a SOAP Adapter, it can have the WSDL operation name.
    • If the child integration trigger connection is a schedule, it executes a submit now configuration.
  6. Review your selections, and click Done.
  7. Complete design of the parent integration.
  8. Specify appropriate business identifiers for tracking the integration at runtime.
  9. Activate and invoke the integration.
  10. Go to the Track Instances page to track integration status.

    If successful, the Track Instances page has two instances (one for the parent and one for the child). If unsuccessful, and the parent is unable to call the child, there is one entry (for the parent). If the parent can call the child, there are two entries. If the child fails or the child was successful, but the parent the did not process properly the response, the parent may fail.

Create a Co-located Integration with Header Support

Headers are optional elements that pass extra information about your application requirements. For example, you can use the header element to specify a digital signature for password-protected services. You can configure and select the headers to send with the payload. Headers selection is automatic based on the WSDL URL definition you provide on the Connections page.

Along with request and response SOAP and REST headers, you can configure standard HTTP headers with the SOAP Adapter and REST Adapter, custom HTTP headers with the SOAP Adapter and REST Adapter, and custom SOAP headers. You can view and edit these headers in the request and response mapper under the header elements for either the SOAP Adapter or REST Adapter.

The following use case provides a high level overview of creating a co-located integration with header support.
  1. Create a SOAP Adapter connection (for this example) with a WSDL URL that includes the header definitions.
    WSDL with header specified in the WSDL URL field of the Connection Properties section of the Connections page

  2. Complete the remaining fields on the Connections page.
  3. Test and save the connection.
  4. Create an orchestrated integration to act as the co-located (child) integration.
  5. Add the SOAP Adapter as a trigger connection in the integration.
  6. Complete the pages of the Adapter Endpoint Configuration Wizard. In particular:
    1. On the Headers page, specify request and response header details.
      Description of local_int_soap_adapter_hdr.png follows
      Description of the illustration local_int_soap_adapter_hdr.png

    2. On the Request-Headers page, specify request header names.
      Description of local_int_soap_adapter_req.png follows
      Description of the illustration local_int_soap_adapter_req.png

      .
    3. On the Response-Headers page, specify response header names.
      Description of local_int_soap_adapter_resp.png follows
      Description of the illustration local_int_soap_adapter_resp.png

      .
  7. In the mapper, map the request and response headers. While this example maps headers between two SOAP Adapters, you can also map request and response headers between two REST Adapters.
    Description of mapper1.png follows
    Description of the illustration mapper1.png

  8. Save and activate the integration.
  9. Create another orchestrated integration to act as the parent integration.
  10. Add the REST Adapter as a trigger connection in the integration.
  11. Configure the pages in the Adapter Endpoint Configuration Wizard.
  12. On the Summary page, review your selections, then click Done.
    Description of rest_adapter_summary.png follows
    Description of the illustration rest_adapter_summary.png

  13. Add an Integration action to the integration.
    This invokes the Configure Local Integration Selection Wizard.
  14. Complete the pages of the wizard. In particular, select the child integration created in Step 4 on the Selection Integration page.
  15. Click the map icon between the REST Adapter trigger connection and SOAP invoke (the Integration action you configured) to configure the map.
  16. Map the source id element to the target SOAP, HTTP, and custom header elements.
    Description of mapper2.png follows
    Description of the illustration mapper2.png

  17. Save and activate the parent integration. The parent integration is now designed with a child integration as a SOAP invoke.

Backward Compatibility for Header Support

Note the following details when using header support in existing integrations created prior to the release of support for headers in co-located integrations.

Question Answer
What happens if an existing integration created with a header is imported into an environment in which header support in co-located integrations is supported. You can activate the integration without any issues. However, if you want to use header functionality, you must edit the adapter by clicking through the pages of the Adapter Endpoint Configuration Wizard, then clicking Done on the Summary page. In this scenario, mapping is not deleted; you must to correct it.
What happens if you perform the following steps.
  1. Create a child flow with headers in a trigger connection.
  2. Use this child endpoint as a SOAP connection.
  3. Use the above SOAP connection as a trigger and create an integration in which you set Do you want to configure headers for this endpoint? to No on the Headers page of the Adapter Endpoint Configuration Wizard.
  4. Activate the integration.
  5. Invoke this child integration in a parent integration that uses the Integration action.
  6. Check if the integration generates a wrapper in the local invoke.
 Based on the selection of Yes or No, headers are visible or invisible in the mapping.

Dynamically Invoke a Co-located Integration

You can dynamically invoke a co-located integration at runtime. In this example, a parent integration can call either of two child integrations at runtime based on the data. The parent integration is designed to invoke child integration one. However, it can also invoke child integration two. The code and version values are passed to the appropriate child integration.

Note:

Dynamic invocations are only supported with the REST Adapter.
  1. Create and activate an initial child integration with a REST Adapter trigger connection.
    1. Create an app-driven orchestration integration (for this example, named childone).
    2. Add a REST Adapter trigger connection.
      This invokes the Adapter Endpoint Configuration Wizard.
    3. Provide the necessary details on the pages of the wizard.
    4. Review your configurations on the Summary page, then click Done. For this example, the following values are configured:
      • The relative resource URI is /emp.
      • The verb (method) is GET.
      • The response media is JSON.

      The Summary page shows the REST endpoint summary, the description, and the endpoint summary. The endpoint summary values are described above this image.

    5. Perform mappings in the mapper.
    6. Activate the integration.
  2. Create and activate a second child integration with a REST Adapter trigger connection.
    1. Create a second app-driven orchestration integration (for this example, named childtwo).
    2. Add a second REST Adapter trigger connection.
    3. Configure the second REST Adapter with the same values as the first REST Adapter.
    4. Perform mappings in the mapper.
    5. Activate the integration.
  3. Create and activate a parent integration.
    1. Create an app-driven orchestration integration.
    2. Add a REST Adapter trigger connection.
    3. Provide the necessary details on the pages of the wizard, including creating the code and version query parameters on the Request Parameters page.
    4. Review your configurations on the Summary page, then click Done. For this example, the following values are configured:
      • The relative resource URI is /employeeinfo.
      • The verb (method) is GET.
      • The query parameters are code and version.
      • The response media is JSON.
      The Summary page shows the REST endpoint summary, the description, and the endpoint summary. The endpoint summary values are described above this image.
    5. Add an Integration action to the integration.
      This invokes the Integration Adapter Wizard.
    6. Select the child integration to invoke. For this example, childone is selected.

      The Select Integration page shows the Integration list. The childone integration is selected.

    7. Select the operation.

      The Select Operation page shows the Operation field, with getEmployee selected.

    8. Complete the wizard, and click Done.
    9. Map the code and version source query parameters to the code and version target local integration elements.

      The mapper shows the source code and version elements mapped to target code and version elements that appear below the LocalIntegration element.

    10. Complete design of any remaining actions in the integration.
    11. Activate the integration.
      Even though the parent integration was designed to invoke only child integration one, you can now invoke either child integration by replacing the code and version of that child integration in the endpoint below.
      http://host_name:port/ic/api/integration/v1/flows/rest/DYNAMIC_INVOKE/1.0/employeeinfo?
code=[code-value]&version=[version-value]

      The parent integration box is shown connected with a solid arrow to a box labeled Child 1 and with a dotted arrow to a box labeled Child 2. Child 1 and Child 2 connect to a runtime box.