Thursday, December 22, 2022

#944 OIC 3 Connectivity Agent install and REST API

This post covers a couple of points related to accessing OIC 3 via OAuth. To begin with, this is now the default authorization method for the connectivity agent. 
In this post I will detail how to invoke integration endpoints using OAuth. I will also cover invoking the OIC 3 "Factory" apis via Oauth. 

There have been a couple of minor changes in the OIC REST api compared to gen2. These are covered in the OIC 3 api docs are here.

Just as a refresher, the OAuth authorisation flow is as follows - 

For the purpose of this post, I create a vanilla OIC 3 instance and then begin with the Connectivity Agent install, which includes a quick overview of the OIC 3 app OAuth setup. 

But before we do, let's look some of the OIC3 URLs - 

The Service Console URL has the following format -

This takes me to the OIC home page, the gen3 version of the gen2 /ic/home

I create a simple REST based integration and check out the Endpoint Metadata for it - 

The format here is - 

In this post, the first URL will be referred to as the Home URL, the second, the Endpoint URL.
Now to the OAuth setup.

OAuth Setup

Newly created OIC 3 instances surface in IDCS under Oracle Cloud Services. Let's check out that entry - 

Click on the console link - then select Oracle Cloud Services - select your OIC instance


Check out the credentials - 

Copy and save Client id/Secret -

Also, check out the Client Configuration

As already mentioned, the connectivity Agent now runs on OAuth. Let's install it.

OIC 3 Connectivity Agent Install

I create an agent group - AA-Agent-Group in my new OIC instance and then download the Connectivity Agent - 

Essentially the same data will be needed when making the OIC api calls from Postman.

Let's populate the InstallerProfile.cfg - the oic_Scope value can be found here in the IDCS created for our OIC instance - 

The oic_URL value is set to the hostname of the Endpoint url shown earlier.

I install the agent - 

Looks good - now to the next step -
Here I create a new confidential app in IDCS - it will be configured in a similar way to the default entry we just looked at.

Redirect URL has the following format - https://hostname from EndpointURL/icsapis/agent/oauth/callback

Note, I also added the 2 scopes from my OIC instance resource.

I get the clientId/Secret once this new confidential app has been saved/activated.

Calling the OIC apis from Postman

Now to actually testing the REST API - 

First test is for the integration endpoint, my AA-REST-Test demo integration.
The Postman Authorization setup is as follows - 


Callback url - set as in the IDCS confidential app
Auth url - https://yourIDCSUrl/oauth2/v1/authorize
Access Token url - https://yourIDCSUrl/oauth2/v1/token
ClientId/Secret - from the new IDCS confidential app
Scope - same scopes as used in the new IDCS confidential app, separated by a space.


Looks good! Now to the OIC Factory APIs, let's list all integrations in the instance - I check out the OIC3 REST API docs here and see - 

Back in Postman, I now use the "Home" url -

OAuth setup is exactly the same as above - 


Monday, December 19, 2022

#943 - Integrating with OTM Cloud using the OIC Logistics Adapter



I strongly suggest you read the following guide, before starting your development of OTM focused integrations -

It is available here.

Then check out the OIC Logistics adapter guide here.

Pre-requisites in OTM Cloud

Firstly, a big thanks to my OTM colleague, Sudheer R. here.

I am a neophyte when it comes to OTM Cloud, but I do have access to an OTM Cloud instance -


I am going to use the same OTM user in my OIC Logistics connection definition, best practices would be to create a specific OTM integration user, I may try that later!

So let's check out my user - 


Note the Access Control List section - add INTEGRATION, if not already present.

In this post I will use OIC to create a Location in OTM Cloud. It's probably one of the easiest business objects to create, excellent for a sanity test.


Creating the OTM(Logistics) connection in OIC

First step is to create the connection to OTM in OIC - 

Configure as follows - 

Creating the OIC Integration with OTM

The REST Request payload will contain all the salient data I need to create a new Location in OTM Cloud.  

Let's check out the configuration of the Logistics invoke - 

I map the following fields - 

from the following request payload - 

The Response payload is as follows - 

Here is a screenshot of the Target mapping result from the tester -

The Transmission number is in the following OTM response field -


I map this to the integration response.

Now to testing the integration - I do so with the following payload - 

This transmissionNr refers to the actual load request sent to OTM Cloud. Inserting data in this way is a 2 phase process, akin to HDL in HCM. I can check out the "load" process in OTM using this number.

PROCESSED = Successfully Loaded.

I click on the ID link - 

Clicking on the Transaction XML button will show the actual payload received.

I can also check the OTM Location List -