Oracle SCM Integration Design Patterns with OIC

OIC is a perfect fit for building integrations when Oracle Apps(ERP, SCM, HCM, CX, DB, DBaaS, ADB, etc.) are in the landscape. It is even greater if there is a requirement to create business workflows and custom web apps. All of these work very well together.

In this blog we will look at the various integration patterns available with OIC to integrate with Oracle Supply Chain management cloud.  

Inbound (Send to SCM)

• Realtime Sync – rest API/soap web services
• FBDI

Outbound (Fetch from SCM)

• Realtime Sync - business events
• BI Publisher
• BICC

Inbound Pattern - Realtime Sync

Key Takeaways

• Use for real-time integrations
• Two flavors SOAP and REST.
• Preference is REST over SOAP.
• Use SOAP only if functionality is not available in the REST
• REST APIs are growing in numbers
• REST API "Batch Action" can be used to process multiple records in one shot
• SOAP services have Async web services with callbacks. These services are useful for implementing Async patterns
• Plan for Rest API limits
• Paginate to overcome limits on records/call
• Use batch action to combine multiple operations into a single HTTP request (batch actions) to improve performance.
• Transform & Enrich payload in OIC using information from other applications

Can use Oracle REST APIs to view and manage data stored in Oracle Supply Chain Management Cloud. You can view a list of all REST endpoints

Inbound Pattern - Bulk Import (FBDI)

Key Takeaways

• Inbound Batch Pattern
• Use capabilities of ERP Adapter to simplify FBDI import and callback
• FBDI Imports have asynchronous callbacks(business event) to monitor the status of import
• Widely used pattern in ERP and SCM world
• Import bulk data operation does end-to-end process – upload file to ucm, submit load, and import job.
• Need not create an explicit Interface WSDL to implement on job completion operation
• Event is natively supported by Oracle ERP Cloud Adapter which protects from any changes in the ERP Cloud interface changes just in case.
• Needless to mention we can avoid all the additional steps to capture JSON and parse the same. Event payload is parsed and readily available in the trigger message to fetch the report from UCM
• When an Event-based integration is activated OIC creates a subscription entry in Oracle ERP Cloud. For some reason, if the Event-based Integration Flow is not reachable ERP Cloud will re-try the events multiple times with an exponential time gap. In the URL-based callback, re-try cannot happen as it is a fire and forget from ERP Cloud

Outbound Pattern - Realtime Sync (Event Driven)

Key Takeaways

• Events can only be used with OIC. Cannot be used with any other third-party listener
• Events make use of the Event Handling Framework
• Not all business events are supported through the Events Framework
• If there are no events for a specific Business Object or if the use case in question is Batch Processing, then use BIP/BICC

Outbound Pattern - Bulk Export (BI Publisher)

Key Takeaways

• Use BIP only when REST and SOAP Services are not available
• Do not use runReport() service in high volume transaction
• Use BIP Reports in an asynchronous pattern using scheduled-based integrations
• Export bulk data operation does – submit ess job(bip) and transfer output and log files to ucm.
• Need not create an explicit Interface WSDL to implement onJobCompletion operation
• Event is natively supported by Oracle ERP Cloud Adapter which protects from any changes in ERP Cloud interface changes just in case.
• Needless to mention we can avoid all the additional steps to capture JSON and parse the same. Event payload is parsed and readily available in the trigger message to fetch the report from UCM
• When an Event-based integration is activated OIC creates a subscription entry in Oracle ERP Cloud. For some reason, if the Event-based Integration Flow is not reachable ERP Cloud will re-try the events multiple times with an exponential time gap. In the URL-based callback re-try cannot happen as it is a fire and forget from ERP Cloud

Outbound Pattern - BICC (BI Cloud Connector)

BICC is a cloud connector to extract business intelligence and other data in bulk. BICC can be configured to write the extracted data files to UCM or Cloud Object Store. BICC is available as part of the Oracle Applications Cloud subscription.

Oracle’s simplified solution of Oracle Integration Cloud (OIC) enables customers to easily exchange data with SCM Cloud.

Capture request originating IP address in OIC

Recently, we encountered a business use case where requests passed through proxies or load balancers and reaches to HCM. At one layer, requests were being blocked, preventing users from logging into HCM. For debugging, the customer requested information on the originating IP address, along with intermediary IP addresses, to diagnose the issue. The ‘X-Forwarded-For’ header is one of the properties that can be utilized for debugging purposes.

The X-Forwarded-For (XFF) is an HTTP header field that is used to identify the originating IP address of a client, especially when a request passes through one or more intermediary proxies or load balancers.

Here’s how it typically works:

1. Client Sends Request: A client (e.g., a web browser) sends an HTTP request to a web server.
2. Request Passes Through Proxies or Load Balancers: If the request passes through one or more proxies or load balancers, each intermediary server may append the client’s IP address to the X-Forwarded-For header.
3. X-Forwarded-For Header: The X-Forwarded-For header then contains a comma-separated list of IP addresses, where the first IP address is the original client's IP, and subsequent addresses are the IP addresses of the intermediaries.
4. Web Server Accesses X-Forwarded-For Header: The web server, upon receiving the request, can check the X-Forwarded-For header to determine the original client's IP address.

The primary use cases for X-Forwarded-For include:

• Logging and Analysis: Web servers can log the client’s original IP address for analysis and logging purposes. This is especially important in scenarios where traffic passes through proxies or load balancers.
• Security: Some applications use the X-Forwarded-For header to implement security measures. For example, it might be used to allow or deny access based on the client's IP address.

It’s important to note that the X-Forwarded-For header can be easily manipulated. Additionally, when using this header, be aware of privacy considerations and potential security risks.

OIC Implementation

Create an App-Driven integration , drag an REST Connection (trigger)

Select custom Request headers

Request Headers, add Custom Header Name X-Forwarded-For

Print the X-Forwarded-For using logger

Logger will print X-Forwarded-For: Client IP, Proxy1, Proxy2

You can also check other Custom Header like 

X-Forwarded-Port : Gives the port the client connected to on the proxy (e.g. 80 or 443)

X-Forwarded-Proto : Gives the protocol the client used to connect to the proxy (http or https)

X-Forwarded-Host : Gives the content of the Host header the client sent to the proxy

OIC3 Connectivity Agent for Hybrid Integrations

In one my previous blog I discussed about Private Endpoint that allows to connect to private resources that resides in Virtual Cloud Network(VCN).

But currently Private Endpoint has some limitations such as - 

• Not all adapters support Private Endpoint
• The VCN with private resources must be in same region as Oracle Integration Instance
• There can be only one Private endpoint per integration Instance connecting to only one subnet.

In such scenarios Oracle Integration Connectivity agent is a solution for hybrid integrations. It works as a bridge between Oracle Integration and on-premises application. Using the connectivity agent, you can create hybrid integrations and exchange messages between applications in private or on-premises networks and Oracle Integration. 

Agent can either be installed on OCI or behind the firewall on the same network as the on-premises applications.

Agent in OCI

Connect to applications running on On-Premises Data Center through Oracle Integration Cloud, without requiring traffic routing through the public internet.

This scenario uses as OIC connectivity agent to communicate with the On-Premises Data Center application. The OIC Connectivity agent is installed on an Oracle Cloud Infrastructure Compute instance on a private subnet of a VCN. The agent communicates with OIC integration through a service gateway on one side and with the application running on On-Premises Data Center on the other side through a dynamic routing gateway (DRG) and FastConnect Private Peering or VPN.

The following diagram illustrates this architecture

Agent in customer DC

Connect to applications running on On-Premises Data Center through Oracle Integration Cloud, traffic routing through the public internet.

This scenario uses as OIC connectivity agent to communicate with the On-Premises Data Center application. The OIC Connectivity agent is installed on On-Premises Data Center on a DMZ Network. The agent communicates with OIC integration through public internet and with the application running on On-Premises Data Center on the other side by allowing internal network traffic.

The following diagram illustrates this architecture

In this blog we will see how to install a OIC agent on a compute VM on OCI to enable onprem connectivity but the steps remain same even if you have install the agent on customer DC.

Configure Compute Instance

Navigate to Compute and click on Instances.

Compartment in which you want to create an instance and click Create Instance

In the Create Instance dialog, Enter the Name and choose the availability domain

Choose Image and shape

 Choose VCN and Subnet

 Add SSH keys : You can either choose to Generate a key pair or upload a public key that you already have. If your are generating a key pair,  Download the keys so that you can connect to the instance using SSH. Please note it will not be shown again. The public key is used while creating the instance and the private key is used while connecting to the instance.

Leave everything else default and click on Create

 After a few minutes, we can see the instance have created

We can access this Instance created using PuTTY (https://www.putty.org/) or WinSCP (https://winscp.net/). 

Download PuTTY  and WinSCP software from the location given above and Install on your machine. Once you Install the PuTTY on your machine, you can easily run PuTTYgen to convert the private key we saved while creating the instance. 

Open PuttyGen

Load the existing private key file (.key downloaded while creating the compute)

Save the Private key file (.ppk format RSA key)

Install OIC Agent

Login to Oracle Integration Console then navigate to Home >> Design >> Agents and click on Create to create an Agent group. Please note before we start with downloading Agent, we need to create an OIC Agent Group in OIC Console. 

In the Create agent group dialog, Enter the Name and click Create

This action automatically creates an OAuth client application in Oracle Identity Cloud Service. The application name takes the following form: agent_group_name-instance_IDCS_name

Click on Download to download the Connectivity agent (which will be a zip file to be configured On-Prem/Cloud)

Hover over the agent group. Click Actions(...) icon, then select Download config. This step downloads a preconfigured InstallerProfile.cfg file to use during installation.  

Replace the InstallerProfile.cfg file in the agent zip(oic_conn_agent_installer.zip) with this preconfigured InstallerProfile.cfg file.

JDK 17 is the minimum version required for Oracle Integration 3. Download JDK 17 from link (Linux x64 Compressed Archive for Linux)

Next step is to copy the Agent and JDK file to the compute instance. 

We can access the Compute Instance created above using WinSCP and transfer the files.

Copy the public IP Address of Instance created

Open WinSCP and paste the IP address as shown below and add a private SSH key.

 

Once Loggedin, move the Agent and JDK files to the compute instance.

Next step is to execute the Agent. Open PuTTY and paste the IP address as shown below and add a private SSH key.

Now we are successfully connected to the instance

Make a Directory under opc directory and move the jdk file to that folder.

mkdir jdk

mv jdk-17.0.9_linux-x64_bin.tar.gz jdk

cd jdk

Extract the .tar file in the jdk Directory

tar -xvf jdk-17.0.9_linux-x64_bin.tar.gz

Similarly make another Directory under opc directory and move the agent file to that folder.

mkdir agent 

mv oic_conn_agent_installer.zip agent

cd agent 

Extract the .zip file in the agent Directory

unzip oic_conn_agent_installer.zip

Open the InstallerProfile.cfg file and verify that it have details like OIC URL,Agent Group Identifier, IDCS URL, Client ID, Client Secret & Scope populated.

cat InstallerProfile.cfg

Set the JAVA_HOME property to the location of the JDK installation. Also set the PATH property and verify using echo command. 

export JAVA_HOME=home/opc/jdk/jdk-17.0.9

export PATH=$JAVA_HOME/bin:$PATH

echo $JAVA_HOME

echo $PATH

Run the connectivity agent installer as a background process

nohup java -jar connectivityagent.jar &

Wait for a successful installation message to appear, then you can check the status of the Agent from OIC console.