Invoke a Child 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.
-
You select an active integration from runtime (a child) to build a new integration. Note the following guidelines:
-
Active synchronous-synchronous, asynchronous with no callback, and schedule integrations are available for selection.
-
Asynchronous with callback integrations do not appear.
-
De-activated and draft integrations do not appear.
-
Schedule 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 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 the receiver is required 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 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
- You cannot send or receive file references between parent and child integrations, in either direction, whether using local integrations or otherwise. The stage file is scoped in the context of its own flow instance and is not shared between parent and child integrations. This is by design. Instead, you can send or receive the stage file as an attachment instead of a direct reference.
- 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 processed 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 processing. In those cases, calls do not benefit from parallelism across nodes and instead are competing for resources on a single node.
Invoke a Child Integration with a Parent Integration
The following steps provide an overview of creating an application integration in which a parent integration invokes a child 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 child integration is invoked from a parent integration.
- Integrations with a REST Adapter using a Swagger-based connection.
- Create and design an application integration.
- Add an integration action to an integration in either of the
following ways:
- On the side of the canvas, click
Actions
and drag the Integration action to the appropriate location.
- Click
at the location where you want to add the integration action, then select Integration.
The Integration Adapter Wizard is displayed.
- On the side of the canvas, click
Actions
- 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.
- Specify the following details, and click Next.
Element Description Select Integration Context Note: This field is only displayed if the parent integration is in a project.
Select the location of the child integration to invoke.- Project:
Select this option, then choose the specific
project. Your current project is highlighted and
selected by default at the top of the list.
Two types of child integrations are shown for selection:
- If you select the project you are already in, all integrations are shown, regardless of whether they are set as public.
- If you select a different project, all integrations that are set as public in that project are shown. See Set a Project Integration as Public.
- Not in Project: Select to invoke a child integration in the global context (that is, not available in a project).
Note: You can invoke an integration not set as public from a runtime tool such as
Postman
.Integration
Select the child integration to invoke. Only active integrations are displayed.
Identifier
Displays the identifier of the selected integration. This value cannot be changed.
Description
Displays the description of the selected integration.
- Project:
Select this option, then choose the specific
project. Your current project is highlighted and
selected by default at the top of the list.
- Select the operation for the child 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 processes a submit now configuration.
- Review your selections, and click Done.
- Complete design of the parent integration.
- Specify appropriate business identifiers for tracking the integration at runtime.
- Activate and invoke the integration.
- In the navigation
pane, click Observability, then
Instances.
If successful, the 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 did not properly process 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. Header 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.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.
|
Based on the selection of Yes or No, headers are visible or invisible in the mapping. |
Dynamically Invoke a Child Integration
You can dynamically invoke a (co-located) child 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.- Create and activate an initial child integration with a REST Adapter trigger connection.
- Create and activate a second child integration with a REST Adapter trigger
connection.
- Create a second integration (for this example, named
childtwo
). - Add a second REST Adapter trigger connection.
- Configure the second REST Adapter with the same values as the first REST Adapter.
- Perform mappings in the mapper.
- Activate the integration.
- Create a second integration (for this example, named
- Create and activate a parent integration.