One of the big challenges with adopting Cloud Services Architecture is how to integrate the on-premise applications when the applications are behind the firewall. A very common scenario that falls within this pattern is cloud integration with Oracle E-Business Suite (EBS). To address this cloud-to-ground pattern without complex firewall configurations, DMZs, etc., Oracle offers a feature with the Integration Cloud Service (ICS) called Connectivity Agent (additional details about the Agent can be found under New Agent Simplifies Cloud to On-premises Integration). Couple this feature with the EBS Cloud Adapter in ICS and now we have a viable option for doing ICS on-premise integration with EBS. The purpose of this A-Team blog is to detail the prerequisites for using the EBS Cloud Adapter and walk through a working ICS integration to EBS via the Connectivity Agent where ICS is calling EBS (EBS is the target application). The blog is also meant to be an additional resource for the Oracle documentation for Using Oracle E-Business Suite Adapter.
The technologies at work for this integration include ICS (Inbound REST Adapter, Outbound EBS Cloud Adapter), Oracle Messaging Cloud Service (OMCS), ICS Connectivity Agent (on-premise), and Oracle EBS R12. The integration is a synchronous (request/response) to EBS where a new employee will be created via the EBS HR_EMPLOYEE_API. The flow consists of a REST call to ICS with a JSON payload containing the employee details. These details are then transformed in ICS from JSON to XML for the EBS Cloud Adapter. The EBS adapter then sends the request to the on-premise connectivity agent via OMCS. The agent then makes the call to EBS where the results will then be passed back to ICS via OMCS. The EBS response is transformed to JSON and returned to the invoking client. The following is a high-level view of the integration:
![ICSEBSCloudAdapter-Overview-001]()
Prerequisites
* For EBS 11 integrations, see another A-Team Blog E-Business Suite Integration with Integration Cloud Service and DB Adapter.
Create Connections
| 1. |
Inbound Endpoint Configuration. |
|
a. |
Start the connection configuration by clicking on Create New Connection in the ICS console: |
|
b. |
For this blog, we will be using the REST connection for the inbound endpoint. Locate and Select the REST Adapter in the Create Connection – Select Adapter dialog: |
|
c. |
Provide a Connection Name in the New Connection – Information dialog: |
|
d. |
The shell of the REST Connection has now been created. The first set of properties that needs to be configured is the Connection Properties. Click on the Configure Connectivity button and select REST API Base URL for the Connection Type. For the Connection URL, provide the ICS POD host since this is an incoming connection for the POD. A simple way to get the URL is to copy it from the browser location of the ICS console being used to configure the connection: |
|
e. |
The last set of properties that need to be configured are the Credentials. Click on the Configure Credentials button and select Basic Authentication for the Security Policy. The Username and Password for the basic authentication will be a user configured on the ICS POD: |
|
f. |
Now that we have all the properties configured, we can test the connection. This is done by clicking on the Test icon at the top of the window. If everything is configured correctly, a message of The connection test was successful!: |
| 2. |
EBS Endpoint Connection |
|
a. |
Create another connection, but this time select Oracle E-Business Suite from the Create Connection – Select Adapter dialog: |
|
b. |
Provide a Connection Name in the New Connection – Information dialog: |
|
c. |
Click on the Configure Connectivity button and for the EBS Cloud Adapter there is only one property, the Connection URL. This URL will be the hostname and port where the EBS metadata has been deployed for EBS. This metadata is provided by Oracle’s E-Business Suite Integrated SOA Gateway (ISG) and the setup/configuration of ISG can be found under the Prerequisites for this blog (item #2). The best way to see if the metadata provider has been deployed is to access the WADL using a URL like the following: http://ebs.example.com:8000/webservices/rest/provider?WADL where ebs.example.com is the hostname of your EBS metatdata provider machine. The URL should provide something like the following: |
<?xml version = '1.0' encoding = 'UTF-8'?>
<application name="EbsMetadataProvider" targetNamespace="http://xmlns.oracle.com/apps/fnd/soaprovider/pojo/ebsmetadataprovider/" xmlns:tns="http://xmlns.oracle.com/apps/fnd/soaprovider/pojo/ebsmetadataprovider/" xmlns="http://wadl.dev.java.net/2009/02" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns1="http://xmlns.oracle.com/apps/fnd/rest/provider/getinterfaces/" xmlns:tns2="http://xmlns.oracle.com/apps/fnd/rest/provider/getmethods/" xmlns:tns3="http://xmlns.oracle.com/apps/fnd/rest/provider/getproductfamilies/" xmlns:tns4="http://xmlns.oracle.com/apps/fnd/rest/provider/isactive/">
<grammars>
<include href="http://ebs.example.com:8000/webservices/rest/provider/?XSD=getinterfaces_post.xsd" xmlns="http://www.w3.org/2001/XMLSchema"/>
<include href="http://ebs.example.com:8000/webservices/rest/provider/?XSD=getmethods_post.xsd" xmlns="http://www.w3.org/2001/XMLSchema"/>
<include href="http://ebs.example.com:8000/webservices/rest/provider/?XSD=getproductfamilies_post.xsd" xmlns="http://www.w3.org/2001/XMLSchema"/>
<include href="http://ebs.example.com:8000/webservices/rest/provider/?XSD=isactive_post.xsd" xmlns="http://www.w3.org/2001/XMLSchema"/>
<include href="http://ebs.example.com:8000/webservices/rest/provider/?XSD=getinterfaces_get.xsd" xmlns="http://www.w3.org/2001/XMLSchema"/>
<include href="http://ebs.example.com:8000/webservices/rest/provider/?XSD=getmethods_get.xsd" xmlns="http://www.w3.org/2001/XMLSchema"/>
<include href="http://ebs.example.com:8000/webservices/rest/provider/?XSD=getproductfamilies_get.xsd" xmlns="http://www.w3.org/2001/XMLSchema"/>
<include href="http://ebs.example.com:8000/webservices/rest/provider/?XSD=isactive_get.xsd" xmlns="http://www.w3.org/2001/XMLSchema"/>
</grammars>
<resources base="http://ebs.example.com:8000/webservices/rest/provider/">
<resource path="getInterfaces/{product}/">
<param name="product" style="template" required="true" type="xsd:string"/>
<method id="getInterfaces" name="GET">
<request>
<param name="ctx_responsibility" type="xsd:string" style="query" required="false"/>
<param name="ctx_respapplication" type="xsd:string" style="query" required="false"/>
<param name="ctx_securitygroup" type="xsd:string" style="query" required="false"/>
<param name="ctx_nlslanguage" type="xsd:string" style="query" required="false"/>
<param name="ctx_language" type="xsd:string" style="query" required="false"/>
<param name="ctx_orgid" type="xsd:int" style="query" required="false"/>
<param name="scopeFilter" type="xsd:string" style="query" required="true"/>
<param name="classFilter" type="xsd:string" style="query" required="true"/>
</request>
<response>
<representation mediaType="application/xml" type="tns1:getInterfaces_Output"/>
<representation mediaType="application/json" type="tns1:getInterfaces_Output"/>
</response>
</method>
</resource>
<resource path="getInterfaces/">
<method id="getInterfaces" name="POST">
<request>
<representation mediaType="application/xml" type="tns1:getInterfaces_Input"/>
<representation mediaType="application/json" type="tns1:getInterfaces_Input"/>
</request>
<response>
<representation mediaType="application/xml" type="tns1:getInterfaces_Output"/>
<representation mediaType="application/json" type="tns1:getInterfaces_Output"/>
</response>
</method>
</resource>
<resource path="getMethods/{api}/">
<param name="api" style="template" required="true" type="xsd:string"/>
<method id="getMethods" name="GET">
<request>
<param name="ctx_responsibility" type="xsd:string" style="query" required="false"/>
<param name="ctx_respapplication" type="xsd:string" style="query" required="false"/>
<param name="ctx_securitygroup" type="xsd:string" style="query" required="false"/>
<param name="ctx_nlslanguage" type="xsd:string" style="query" required="false"/>
<param name="ctx_language" type="xsd:string" style="query" required="false"/>
<param name="ctx_orgid" type="xsd:int" style="query" required="false"/>
<param name="scopeFilter" type="xsd:string" style="query" required="true"/>
<param name="classFilter" type="xsd:string" style="query" required="true"/>
</request>
<response>
<representation mediaType="application/xml" type="tns2:getMethods_Output"/>
<representation mediaType="application/json" type="tns2:getMethods_Output"/>
</response>
</method>
</resource>
<resource path="getMethods/">
<method id="getMethods" name="POST">
<request>
<representation mediaType="application/xml" type="tns2:getMethods_Input"/>
<representation mediaType="application/json" type="tns2:getMethods_Input"/>
</request>
<response>
<representation mediaType="application/xml" type="tns2:getMethods_Output"/>
<representation mediaType="application/json" type="tns2:getMethods_Output"/>
</response>
</method>
</resource>
<resource path="getProductFamilies/">
<method id="getProductFamilies" name="GET">
<request>
<param name="ctx_responsibility" type="xsd:string" style="query" required="false"/>
<param name="ctx_respapplication" type="xsd:string" style="query" required="false"/>
<param name="ctx_securitygroup" type="xsd:string" style="query" required="false"/>
<param name="ctx_nlslanguage" type="xsd:string" style="query" required="false"/>
<param name="ctx_language" type="xsd:string" style="query" required="false"/>
<param name="ctx_orgid" type="xsd:int" style="query" required="false"/>
<param name="scopeFilter" type="xsd:string" style="query" required="true"/>
<param name="classFilter" type="xsd:string" style="query" required="true"/>
</request>
<response>
<representation mediaType="application/xml" type="tns3:getProductFamilies_Output"/>
<representation mediaType="application/json" type="tns3:getProductFamilies_Output"/>
</response>
</method>
</resource>
<resource path="getProductFamilies/">
<method id="getProductFamilies" name="POST">
<request>
<representation mediaType="application/xml" type="tns3:getProductFamilies_Input"/>
<representation mediaType="application/json" type="tns3:getProductFamilies_Input"/>
</request>
<response>
<representation mediaType="application/xml" type="tns3:getProductFamilies_Output"/>
<representation mediaType="application/json" type="tns3:getProductFamilies_Output"/>
</response>
</method>
</resource>
<resource path="isActive/">
<method id="isActive" name="GET">
<request>
<param name="ctx_responsibility" type="xsd:string" style="query" required="false"/>
<param name="ctx_respapplication" type="xsd:string" style="query" required="false"/>
<param name="ctx_securitygroup" type="xsd:string" style="query" required="false"/>
<param name="ctx_nlslanguage" type="xsd:string" style="query" required="false"/>
<param name="ctx_language" type="xsd:string" style="query" required="false"/>
<param name="ctx_orgid" type="xsd:int" style="query" required="false"/>
</request>
<response>
<representation mediaType="application/xml" type="tns4:isActive_Output"/>
<representation mediaType="application/json" type="tns4:isActive_Output"/>
</response>
</method>
</resource>
<resource path="isActive/">
<method id="isActive" name="POST">
<request>
<representation mediaType="application/xml" type="tns4:isActive_Input"/>
<representation mediaType="application/json" type="tns4:isActive_Input"/>
</request>
<response>
<representation mediaType="application/xml" type="tns4:isActive_Output"/>
<representation mediaType="application/json" type="tns4:isActive_Output"/>
</response>
</method>
</resource>
</resources>
</application>
|
|
If you don’t get something like the above XML, here are some general troubleshooting steps:
Login to EBS console
–> Integrated SOA Gateway
—-> Integration Repository
——> Click on “Search” button on the right
——–> Enter “oracle.apps.fnd.rep.ws.service.EbsMetadataProvider” in the field “Internal Name”
———-> Click “Go” (If this doesn’t list anything, you are missing a patch on the EBS instance. Please follow the Note. 1311068.1)
————> Click on “Metadata Provider”
————–> Click on “REST Web Service” tab
—————-> Enter “provider” as is in the “Service Alias” field and click the button “Deploy”
——————> Navigate to “Grants” tab and give grants on all methods. |
|
|
If the WADL shows that the metadata provider is deployed and ready, the Connection URL is simply the host name and port where the metatdata provider is deployed. For example, http://ebs.example.com:8000 |
![ICSEBSCloudAdapter-Connections_2-003]()
|
d. |
The next set of properties that need to be configured are the Credentials. Click on the Configure Credentials button and select Basic Authentication for the Security Policy. The Username and Password for the basic authentication will be a user configured on the on-premise EBS environment granted privileges to access the EBS REST services: |
|
|
NOTE: The Property Value for Username in the screen shot above shows the EBS sysadmin user. This will most likely “not” be the user that has grants on the EBS REST service. If you use the sysadmin user here and your integration (created later) “fails at runtime” with a “Responsibility is not assigned to user” error from EBS, either the grants on the EBS REST service are not created or a different EBS user needs to be specified for this connection. Here is an example error you might get: |
<ISGServiceFault>
<Code>ISG_USER_RESP_MISMATCH</Code>
<Message>Responsibility is not assigned to user</Message>
<Resolution>Please assign the responsibility to the user.</Resolution>
<ServiceDetails>
<ServiceName>HREmployeeAPISrvc</ServiceName>
<OperationName>CREATE_EMPLOYEE</OperationName>
<InstanceId>0</InstanceId>
</ServiceDetails>
</ISGServiceFault>
|
e. |
Finally, we need to associate this connection with the on-premise Connectivity Agent that was configured as a Prerequisite. To do this, click on the Configure Agents button and select the agent group that contains the running on-premise Connectivity Agent: |
|
f. |
Now that we have all the properties configured, we can test the connection. This is done by clicking on the Test icon at the top of the window. If everything is configured correctly, a message of The connection test was successful!: |
|
|
|
| 3. |
We are now ready to construct our cloud-to-ground integration using ICS and the connections that were just created. |
Create Integration
| 1. |
Create New Integration. |
|
a. |
Navigate to the Integrations page of the Designer section. Then click on Create New Integration: |
|
b. |
In the Create Integration – Select a Pattern dialog, locate the Map My Data and select it: |
|
c. |
Give the new integration a name and click on Create: |
| 2. |
Configure Inbound Endpoint. |
|
a. |
The first thing we will do is to create our inbound endpoint (entry point to the ICS integration). In the Integration page that opened from the previous step, locate the Connections section and find the REST connection configured earlier. Drag-and-Drop that connection onto the inbound (left-hand side) of the integration labeled “Drage and Drop a Trigger”: |
|
b. |
Since the focus of this blog is on the EBS Adapter, we will not go into the details of setting up this endpoint. The important details for this integration is that the REST service will define both the request and the response in JSON format: |
Example Request:
{
"CREATE_EMPLOYEE_Input": {
"RESTHeader": {
"Responsibility": "US_SHRMS_MANAGER",
"RespApplication": "PER",
"SecurityGroup": "STANDARD",
"NLSLanguage": "AMERICAN",
"Org_Id": "204"
},
"InputParameters": {
"HireDate": "2016-01-01T09:00:00",
"BusinessGroupID": "202",
"LastName": "Sled",
"Sex": "M",
"Comments": "Create From ICS Integration",
"DateOfBirth": "1991-07-03T09:00:00",
"EMailAddress": "bob.sled@example.com",
"FirstName": "Robert",
"Nickname": "Bob",
"MaritalStatus": "S",
"MiddleName": "Rocket",
"Nationality": "AM",
"SocialSSN": "555-44-3333",
"RegisteredDisabled": "N",
"CountryOfBirth": "US",
"RegionOfBirth": "Montana",
"TownOfBirth": "Missoula"
}
}
}
Example Response:
{
"CreateEmployeeResponse": {
"EmployeeNumber": 2402,
"PersonID": 32871,
"AssignmentID": 34095,
"ObjectVersionNumber": 2,
"AsgObjectVersionNumber": 1,
"EffectiveStartDate": "2016-01-01T00:00:00.000-05:00",
"EffectiveEndDate": "4712-12-31T00:00:00.000-05:00",
"FullName": "Sled, Robert Rocket (Bob)",
"CommentID": 1304,
"AssignmentSequence": null,
"AssignmentNumber": 2402,
"NameCombinationWarning": 0,
"AssignPayrollWarning": 0,
"OrigHireWarning": 0
}
}
| 3. |
Configure Outbound Endpoint. |
|
a. |
Now we will configure the endpoint to EBS. In the Integration page, locate the Connections section and find the E-Business Suite adapter connection configured earlier. Drag-and-Drop that connection onto the outbound (right-hand side) of the integration labeled “Drage and Drop an Invoke”: |
|
b. |
The Configure Oracle E-Business Suite Adapter Endpoint configuration window should now be open. Provide a meaningful name for the endpoint and press Next >. If the windows hangs or errors out, check to make sure the connectivity agent is running and ready. This endpoint is dependent on the communication between ICS and EBS via the connectivity agent. |
|
c. |
At this point, the adapter has populated the Web Services section of the wizard with Product Family and Product metatdata from EBS. For this example, the Product Family will be Human Resources Suite and the Product will be Human Resources. Once those are selected, the window will be populated with API details. |
|
d. |
Next to API label is a text entry field where the list of APIs can be searched by typing values in that field. This demo uses the HR_EMPLOYEE_API, which can be found by typing Employee in the text field and selecting Employee from the list: |
|
e. |
The next section of the configuration wizard is the Operations. This will contain a list of “all” operations for the API including operations that have not yet been deployed in the EBS Integration Repository. If you select an operation and see a warning message indicating that the operation has not been deployed, you must go to the EBS console and deploy that operation in the Integration Repository and provide the appropriate grants. |
|
f. |
This demo will use the CREATE_EMPLOYEE method of the HR_EMPLOYEE_API. Notice that there is no warning when this method is selected: |
|
g. |
The Summary section of the configuration wizard shows all the details from the previous steps. Click on Done to complete the endpoint configuration. |
|
h. |
Check point – the ICS integration should look something like the following: |
| 4. |
Request/Response Mappings. |
|
a. |
The mappings for this example are very straightforward in that the JSON was derived from the EBS input/output parameters, so the relationships are fairly intuitive. Also, the number of data elements have been minimized to simplify the mapping process. It is also a good idea to provide a Fault mapping: |
Request Mapping:
Response Mapping:
Fault Mapping:
| 5. |
Set Tracking. |
|
a. |
The final step to getting the ICS Integration to 100% is to Add Tracking. This is done by clikcing on the Tracking icon at the top right-hand side of the Integration window. |
|
b. |
In the Business Identifiers For Tracking window, drag-and-drop fields that will be used for tracking purposes. These fields show up in the ICS console in the Monitoring section for the integration. |
|
c. |
There can be up to 3 fields used for the tracking, but only one is considered the Primary. |
| 6. |
Save (100%). |
|
a. |
Once the Tracking is configured, the integration should now be at 100% and ready for activation. This is a good time to Save all the work that has been done thus far. |
Test Integration
| 1. |
Make sure the integration is activated and you open the endpoint URL that located by clicking on the “I”nformation icon. |
| 2. |
Review the details of this page since it contains everything needed for the REST client that will be used for testing the integration. |
| 3. |
Open a REST test client and provide all the necessary details from the endpoint URL. The important details from
the page include: |
|
|
|
|
Base URL: |
https://[ICS POD Host Name]/integration/flowapi/rest/HR_CREATE_EMPLOYEE/v01 |
|
REST Suffix: |
/hr/employee/create |
|
URL For Test Client: |
https://[ICS POD Host Name]/integration/flowapi/rest/HR_CREATE_EMPLOYEE/v01/hr/employee/create |
|
REST Method: |
POST |
|
Content-Type |
application/json |
|
JSON Payload: |
|
{
"CREATE_EMPLOYEE_Input": {
"RESTHeader": {
"Responsibility": "US_SHRMS_MANAGER",
"RespApplication": "PER",
"SecurityGroup": "STANDARD",
"NLSLanguage": "AMERICAN",
"Org_Id": "204"
},
"InputParameters": {
"HireDate": "2016-01-01T09:00:00",
"BusinessGroupID": "202",
"LastName": "Demo",
"Sex": "M",
"Comments": "Create From ICS Integration",
"DateOfBirth": "1991-07-03T09:00:00",
"EMailAddress": "joe.demo@example.com",
"FirstName": "Joseph",
"Nickname": "Demo",
"MaritalStatus": "S",
"MiddleName": "EBS",
"Nationality": "AM",
"SocialSSN": "444-33-2222",
"RegisteredDisabled": "N",
"CountryOfBirth": "US",
"RegionOfBirth": "Montana",
"TownOfBirth": "Missoula"
}
}
}
|
The last piece that is needed for the REST test client is authentication information. Add Basic Authentication to the header with a user name and password for an authorized “ICS” user. The user that will be part of the on-premise EBS operation is specified in the EBS connection that was configured in ICS earlier. The following shows what all this information looks like using the Firefox RESTClient add-on: |
| 4. |
Before we test the integration, we can login to the EBS console as the HRMS user. Then navigating to Maintaining Employees, we can search for our user Joseph Demo by his last name. Notice, nothing comes up for the search: |
| 5. |
Now we send the POST from the RESTClient and review the response: |
| 6. |
We can compare what was returned from EBS to ICS in the EBS application. Here is the search results for the employee Joseph Demo: |
| 7. |
Here are the details for Joseph Demo: |
| 8. |
Now we return to the ICS console and navigate to the Tracking page of the Monitoring section. The integration instance shows up with the primary tracking field of Last Name: Demo |
| 9. |
Finally, by clicking on the tracking field for the instance, we can view the details: |
Hopefully this walkthrough of how to do an ICS integration to an on-premise EBS environment has been useful. I am looking forward to any comments and/or feedback you may have. Also, keep an eye out for the “Part 2” A-Team Blog that will detail EBS business events surfacing in ICS to complete the ICS/EBS on-premise round trip integration scenarios.
All content listed on this page is the property of Oracle Corp. Redistribution not allowed without written permission
