Sunday, August 5, 2018

#642 OIC Integration 101 Part I --> Basics

Many folks have been asking me for introductory/basic OIC labs.
Here is the first of a series.
I begin with integration - OIC's integration component has a few basic concepts.

Connections: to the apps I want to integrate. We can connect to apps via app specific adapters, e.g. Fusion ERP adapter, SAP adapter, SFDC adapter. If OIC does not provide an app specific adapter then you can look at using one of the technical adapters e.g. SOAP, REST, FTP adapters etc.

Integrations: The leveraging of those connections to implement an integration flow.

A simple example - I need to keep the sales account object from Sales Cloud synced with the Organization object from Service Cloud. Both essentially refer to a customer albeit in pre-sales and post-sales mode. Ergo, I sell something to a customer via Sales Cloud, now I want to service that something via Service Cloud.

Now to some OIC speak -
An integration starts with a Trigger and usually end with an Invoke.
In the above example, the Trigger could be a SOAP or REST request that has a Sales Cloud Sales Account object as its payload. The Invoke would then leverage the Service Cloud Adapter to Create an Organization in Service Cloud.

The Integration component of OIC has the following menu structure - which succinctly illustrates what it actually does.

Designer -

In the Designer, I can create connections and integrations.
I can also create Lookups - these are essentially Domain Value Maps e.g. maps of essentially the same things between different apps e.g. Sales Cloud refers to the customer's state as CA, while Service Cloud uses California.  I can create a lookup that contains all of these name value pairs and leverage them automatically in an integration mapping, thus automating a tedious task.

Packages allow me to structure my integrations. For example, I could have a package that contains all my ERP integrations. Packages can be easily exported/imported and contain all other artifacts used by the Integration e.g. connections, lookups.

Agents are used top connect to on-prem apps, e.g. SAP, JDE, Oracle DB etc. An Agent is a small piece of software you install in your on-premise environment. It communicates with OIC in the cloud via REST calls over HTTPS. Essentially, it polls OIC for work e.g. I have an integration between SFDC and SAP on premise. The request to update SAP is pulled down by the agent and is executed against SAP.

Adapters are the plumbing of OIC. The product comes with over 60 adapters; you can add your own adapters via our Java based adapter SDK. These adapters cover Oracle and non-Oracle SaaS and on-prem apps; as well as technology adapters such as SOAP and REST.

Libraries are JavaScript based and can be added to OIC. We cover 2 use cases here.
1. using JavaScript to do complex data mapping.
2. using JavaScript for Service Callouts in an integration for data enrichment, data validation etc.

Creating Connections -

This is very simple - you select the required adapter and then enter the required connect information for that adapter. Let's use Service Cloud as an example -

Here we configure connectivity - in this case, we specify the enterprise wsdl, which defines the public services available for Service Cloud e.g. createOrganization, updateIncident etc.

We also Configure Security - specifying the RightNow username/password.

Creating Integrations

Let's look at the Integration styles offered by OIC -

Basic Routing - If you just need to do basic routing then this is the pattern for you.
An example would be - keeping related business objects in sync between 2 SaaS apps e.g.
synchronizing Sales Accounts from Sales Cloud with Organizations from Service Cloud. Both essentially refer to the same business entity - the customer.

App Driven Orchestration - here you can use events or business objects to trigger an integration flow. Orchestrations give you much more flexibility as Basic Routing. Available actions within an Orchestration include the following -

So, if you need to do File Based Data Integration (FDBI) e.g. importing data  into Fusion ERP or HCM, then the Orchestration pattern, with its Stage File Action is the way to go.

Also note the looping functionality for processing collections etc.

Function Call - allows me to call JavaScript from within the integration flow.

Assign - allows me to create variables with the integration flow.

Also note the Error Handling actions available.

Scheduled Orchestration - essentially a variation of the above. This time the integration flow executes according to a schedule e.g. kick off the batch update at 5pm every working day. This could, for example, trigger the read of a file from an ftp server and then the processing and loading of that file into an ERP system.

File Transfer - Move files from A to B across the network. Yes, many integrations are as simple as this.

Publish to OIC - Create an integration flow that publishes a message to OIC (to an internal Q).
Subscribe to OIC - Create an integration flow that subscribes to a published message.

Ok so far?

Now to a simple example of  Basic Routing -

Basic Routing Example 

Here my Trigger will be a REST Request that has the following payload -
{"orgName": "My Org"}

The Response will be in the following format -
{"orgID": "12345"}

I have already created a Service Cloud connection -

I will use the above in this integration.

I will also need a REST Connection for the Trigger -

I create that as follows -

When the integration is activated, I will be calling a REST API on OIC.
This will be auto-generated for me, so I do not need to specify anything here.

All I need to do is press the Test button and then Save.

Now to the integration itself -

Ok, the Trigger will be NC-REST-Trigger

I drag and drop this to the left and configure as follows -

Now I drop my Service Cloud Connection as the target -

All I need to attend to now is the request / response mappings -

Clicking the + will create a new mapping for me.

Clicking the above, allows me to import an existing xslt mapping.

In this case, I create a new mapping -

Now, while we're here - let's take a look at the mapper and all it offers -

I can immediately expand source and target -

Recommendations -

OIC allows us to crowd source mapping recommendations. This could provide us with the
first mapping draft when, for example, mapping complex objects such as Sales Account to Organization. It does not bring much value add for my simple example. But remember it, when you are using OIC in anger.

I simply map the orgName to Name - by dragging the field to the target -

Deleting mappings is easy - just right mouse click next to the mapped field -

Now to Code -

Here we see the xslt generated.

Very easy way of validating your mappings.

Now how do we do more funky mappings?
For example, we need to concatenate 2 source fields to 1 target field -

Click top right to toggle functions -

More about these in a later post!

The Request mapping is completed - now to the response mapping -

The integration is completed - but it signals I am only 87% complete -

I need to specify one or more "tracking" fields.
These will show up in the monitoring component of OIC.

Now we are finished!

Now you might be asking what about the + symbols and the funnel in the integration.

Let's look at the request trigger - the + allows us to invoke another service. For example, I need more data for the mapping, thus I call another service to enrich the payload, so to speak.
The funnel allows us to filter and branch based on a condition. For example, say I had two Service Cloud instances, one for DE and one for IE. Say my request payload also included a country field - I could branch on this and create the Organization in the appropriate Service Cloud instance.

We will add that functionality later.

So, we are finished for now - all we need to do is activate (essentially deploy) the integration.

So what are all the checkboxes etc. here?
Let's start from the top -
Recommendations Engine - this is how we crowd source the mappings offered to you in the OIC Mapper. You can, of course, opt out by de-selecting the checkbox.

Tracing - enabling tracing can be useful when you are still developing/testing the integration. You also have the option to include the payload in the audit. Naturally, this is not recommended, when you go into production.

Activate and Publish -  Activate the integration and publish to Oracle's API Platform Cloud Service.

Activate -  Activate the integration.

I choose Activate - once activated, I can  now test by picking up the URL -

I test via Postman -

Note: I need to add my OIC credentials -

As you can see, the new orgId from Service Cloud has been returned.

Now to add the country Filter to the integration - In this simple scenario,
customers are either German (DE) or Irish (IE).

I create a second Service Cloud Connection for the Irish customers.

In order to edit the integration, I first need to deactivate it -

We begin by adding a new field - country - to the REST Trigger -

I now add the filter -

Now I add the logic for the IE customers (2nd Routing Expression)-

I drag and drop in the new Service Cloud connection and configure as previously, to
create a new Organization.

I then complete the Mappings -

I add the routing expression - country = IE


No comments: