Introduction

This article describes how to integrate Oracle Sales Cloud (OCS) with Oracle Database as a Service (DBaaS) using PL/SQL.

The code snippet provided uses the REST API for Oracle Sales Cloud to create a new OSC contact from DbaaS. The PL/SQL uses UTL_HTTP commands to call the REST API for Oracle Sales Cloud.

A sample use case for this code snippet could be: Displaying a list of contacts in an Oracle or an external application. Then allowing the application consumer to select the relevant contacts to push to OSC as potential opportunities.

Alternative OCS integration patterns have been discussed in the previously published articles listed below:

Integrating Oracle Sales Cloud with Oracle Business Intelligence Cloud Service (BICS) – Part 1

Integrating Oracle Sales Cloud with Oracle Business Intelligence Cloud Service (BICS) – Part 2

The primary difference between the past and current articles is:

The prior two articles focused on using the APEX_WEB_SERVICE.

This current article uses UTL_HTTP and has no dependency on Apex.

That said, DBaaS does come with Apex and the previously published solutions above are 100% supported with DbaaS. However, some DbaaS developers may prefer to keep all functions and stored procedures in DbaaS – using native PL/SQL commands through Oracle SQL Developer or SQL*Plus. This article addresses that need.

Additionally, the article explains the necessary prerequisites steps required for calling the REST API for OCS from DbaaS. These steps include: configuring the Oracle Wallet and importing the OSC certificate into the wallet.

The techniques referenced in this blog can be easily altered to integrate with other components of the OSC API. Additionally, they may be useful for those wanting to integrate DbaaS with other Oracle and non-Oracle products using PL/SQL.

There are four steps to this solution:

1. Create Oracle Wallet

2. Import OSC Certificate into Wallet

3. Create Convert Blob to Clob Function

4. Run PL/SQL Sample Snippet

Main Article

1. Create Oracle Wallet

The Schema Service Database is pre-configured with the Oracle Wallet and 70+ common root CA SSL certificates. It is completely transparent to developers when building declarative web services in APEX or when using APEX_WEB_SERVICE API.

DbaaS, on the other hand, does not come pre-configured with the Oracle Wallet. Therefore, a wallet must be created and the OSC certificate imported into the Wallet.

Using PuTTY (or another SSH and Telnet client) log on to the DbaaS instance as oracle or opc.

If set, enter the passphrase.

If logged on as opc, run:

sudo su – oracle

Set any necessary environment variables:

. oraenv

Create the Wallet

orapki wallet create -wallet . -pwd Welcome1

2. Import OSC Certificate into Wallet

From a browser (these examples use Chrome) go to the crmCommonApi contacts URL. The screen will be blank.

https://abc1-cloud1234-crm.oracledemos.com/crmCommonApi/resources/11.1.10/contacts

In R10 you may need to use the latest/contacts URL:

https://abc1-cloud1234-crm.oracledemos.com/crmCommonApi/resources/latest/contacts

Click on the lock

Click Connection -> Certificate Information

Click “Certification Path”. Select “GeoTrust SSL CA – G3”.

Click Details -> Copy to File

Click Next

Select “Base-64 encoded X.509 (.CER)

Save locally as oracledemos.cer

Click Finish

Copy the oracledemos.cer file from the PC to the Cloud server. This can be done using SFTP.

Alternatively, follow the steps below to manually create the oracledemos.cer using vi editor and cut and paste between the environments.

Return to PuTTY.

Using the vi editor create the certificate file.

vi oracledemos.cer

Open the locally saved certificate file in NotePad (or other text editor). Select all and copy.

Return to the vi Editor and paste the contents of the certificate into the oracledemos.cer file.

Hit “i” to insert
“Right Click” to paste
Hit “Esc”
Type “wq” to save
Type “ls -l” to confirm oracledemos.cer file was successfully created

Run the following command to add the certificate to the wallet.

orapki wallet add -wallet . -trusted_cert -cert /home/oracle/oracledemos.cer -pwd Welcome1

 Confirm the certificate was successfully added to the wallet.

orapki wallet display -wallet . -pwd Welcome1

3. Create Convert Blob to Clob Function

I used this v_blobtoclob function created by Burleson Consulting to convert the blob to a clob.

There are many other online code samples using various methods to convert blobs to clobs that should work just fine as well.

This function isn’t actually required to create the OSC contact.

It is however necessary to read the response – since the response comes back as a blob.

4. Run PL/SQL Sample Snippet

Replace the highlighted items with those of your environment:

(a) Wallet Path

(b) Wallet Password

(c) OSC crmCommonAPI Contacts URL

(d) OCS User

(e) OSC Pwd

(f) Blob to Clob Function Name

Run the code snippet in SQL Developer or SQL*Plus.

DECLARE
l_http_request UTL_HTTP.req;
l_http_response UTL_HTTP.resp;
l_response_text VARCHAR2(32766);
l_response_raw RAW(32766);
l_inflated_resp blob;
l_body VARCHAR2(30000);
l_clob CLOB;
—
l_body := ‘{“FirstName”: “Jay”,”LastName”: “Pearson”,”Address”: [{“Address1”: “100 Oracle Parkway”,”City”: “Redwood Shores”,”Country”: “US”,”State”: “CA”}]}’;
UTL_HTTP.set_wallet(‘file:/home/oracle‘, ‘Welcome1‘);
l_http_request := UTL_HTTP.begin_request (‘https://abc1-cloud1234-crm.oracledemos.com:443/crmCommonApi/resources/11.1.10/contacts’,’POST’,’HTTP/1.1′);
UTL_HTTP.set_authentication(l_http_request,’User‘,’Pwd‘);
UTL_HTTP.set_header(l_http_request, ‘Content-Type’, ‘application/vnd.oracle.adf.resourceitem+json’);
UTL_HTTP.set_header (l_http_request, ‘Transfer-Encoding’, ‘chunked’ );
UTL_HTTP.set_header(l_http_request, ‘Cache-Control’, ‘no-cache’);
utl_http.write_text(l_http_request, l_body);
l_http_response := UTL_HTTP.get_response(l_http_request);
dbms_output.put_line (‘status code: ‘ || l_http_response.status_code);
dbms_output.put_line (‘reason phrase: ‘ || l_http_response.reason_phrase);
UTL_HTTP.read_raw(l_http_response, l_response_raw,32766);
DBMS_OUTPUT.put_line(‘>> Response (gzipped) length: ‘||utl_raw.length(l_response_raw));
l_inflated_resp := utl_compress.lz_uncompress(to_blob(l_response_raw));
DBMS_OUTPUT.put_line(‘>> Inflated Response: ‘||dbms_lob.getlength(l_inflated_resp));
l_clob := v_blobtoclob(l_inflated_resp);
dbms_output.put_line(dbms_lob.substr(l_clob,24000,1));
UTL_HTTP.end_response(l_http_response);
–;
/
sho err

Dbms Output should show status code: 201 – Reason Phrase: Created.

However, I have found that status 201 is not 100% reliable.

That is why it is suggested to return the response, so you can confirm that the contact was actually created and get the PartyNumber.

Once you have the PartyNumber, Postman can be used to confirm the contact was created and exists in OSC.

https://abc1-abc1234-crm.oracledemos.com:443/crmCommonApi/resources/11.1.10/contacts/345041

Further Reading

Click here for the REST API for Oracle Sales Cloud guide.

Click here for Oracle Database UTL_HTTP commands.

Click here for more A-Team BICS Blogs.

 
Summary

This article provided a code snippet of how to use UTL_HTTP PL/SQL commands in DbaaS to create an OSC contact using the REST API for Oracle Sales Cloud.

Additionally, the article provided the prerequisite steps to create an Oracle Wallet and import the OSC certificate. This is required for accessing the OSC API externally – in this case using PL/SQL ran in SQL Developer.

The techniques referenced in this blog can be easily altered to integrate with other components of the OSC API. Additionally, they may be useful for those wanting to integrate DbaaS with other Oracle and non-Oracle products using PL/SQL.

All content listed on this page is the property of Oracle Corp. Redistribution not allowed without written permission