Teaching how to integrate Sales Cloud with Integration Cloud Service

In this blog, I am going to show how simple it is to use ICS (Integration Cloud Service) to integrate to Oracle Sales Cloud easily and quickly. The steps that I am going to show are tailored for Sales Cloud, but in reality, they are almost the same steps to integrate virtually any Application whether it is on premise or in the cloud.

Using ICS Sales Cloud connector, allows you to fully introspect into all Business objects, custom objects and Services while building an Integration, so you can literally choose depending on your needs the object to interact with, either to Create, Read, Update or Remove; specific queries, services, etc. In this case I am mainly going to work with the “Contact” Business object that belongs to a particular “Account”.

This is the use case that I am going to develop:

  • REST API to create (POST) new a new “Contact” for an existing “Account” in Sales Cloud
  • REST API to retrieve (GET) all “Contacts” from an existing “Account” in Sales Cloud
  • REST API to retrieve (GET) a specific “Contact” from an existing “Account”, given a unique identifier in Sales Cloud

In Sales Cloud, I created a new Account called: S2V Exec Hospital and added a few contacts into it.

This is the list of contacts that I want to ultimately return from using my GET Contacts REST API.

Big thanks to Serene Tan for helping me understand Oracle Sales Cloud and making possible writing this blog!

For more information on how to use the Oracle ICS Sales Cloud Adapter, refer to the Oracle documentation.

For more information about the Sales Cloud Contact Business Object, refer to this Documentation – Note, I am using version 11d02

Pre-requisites

It is assumed that you already have access to a Sales Cloud, as well as access to Integration Cloud Service. Now days with Cloud, this is simple, you can get provisioned an account in minutes, simply go to: https://cloud.oracle.com/tryit and request a new trial.

Let’s configure the Sales Cloud Connector

The very first thing that we must do when using ICS is to create the connector(s) that are going to be used to integrate to the target applications. In this case, we need to create 2 connectors, the first one is the Sales Cloud connector that is going to allow us to easily interact with Sales Cloud. The second connector that we need to use is REST, this will allow us to easily expose whatever actions we are doing in the Sales Cloud, to be easily accessible via a simple to consume API.

To create the Sales Cloud Connector:

  • Login to ICS
  • Click on Connections

  • Click on New Connection and then select Oracle Sales Cloud.

  • Enter a sensible Name and Description. Also, select “Trigger and Invoke” for Connection Role. The idea behind this is that even though for this case we just want to “Invoke” Sales Cloud ad-hoc, if you also configure it to support “Trigger”, it means that you can also use this connector to “subscribe for events” in Sales Cloud, so that your ICS integration can get notified when “Whatever event” that you choose happens.

Note: “Trigger Sales Cloud integrations” is out of the scope of this blog, but should you need to use it, you need to:

1. Add some once-off Sales cloud configurations to enable listening for events.

Follow the next instructions: http://docs.oracle.com/cloud/latest/intcs_gs/ICSSC/GUID-DD9D2A04-2677-4E09-A6FA-E76F940A2731.htm#ICSSC-GUID-DD9D2A04-2677-4E09-A6FA-E76F940A2731

 Pay especial attention to the following section:

        To subscribe to events with Oracle Sales Cloud, you must perform a number of configuration steps. For information, see Enabling Event Subscriptions in Oracle Sales Cloud.

2. Notice that as part of these steps, you must configure a CSF Key… This one has to match the “ICS
Identity Domain name” – Most errors are because this step is missed.

That’s it, now you can create an ICS Sales Cloud connector of type “Trigger” or “Trigger and Invoke”

If you have any question or get into any trouble, feel free to contact any of the authors of solutionsanz.blog – We are here to help you!

  • Click on Configure Connectivity and set the following fields and when done click OK:
    • OSC Services Catalog WSDL URL: This field will give us the full introspection to “Invoke” Business Objects and Services in Sales Cloud.

      It follows the form (replace the X’s by your own env/account):

      https://ucfX-fapXXXX-fs.oracledemos.com/fndAppCoreServices/ServiceCatalogService?wsdl

    • OSC Events Catalog URL (option): This field is optional if you just need to “Invoke”, but since we configured our connector to also allow “Trigger” (events), we need to set this field as well.

      It follows the form (replace the X’s by your own env/account):

      https://ucfX-fapXXXX-crm.oracledemos.com/soa-infra

  • Click on Configure Security and enter your Sales Cloud username and password. Then click OK.

Note: Although this is out of the scope for this blog, if you want to use the Trigger capabilities,

make sure to use “the user” that you setup earlier as part of the Sales Cloud once-off event

configuration (optional steps earlier in this blog)

  • Click on Save and Test. Make sure you get a green 100% completion – That means that your connection configuration is correct and ready to use.

  • Now you can Save and Exit the connection.

Let’s create the REST Connector

  • Ok, now we are going to create a simple REST Connector that is going to be used during the Integration to expose GET and POST capabilities into Sales Cloud.
  • Click on New Connection and select REST this time.

  • Enter some sensible name and description

  • There is nothing else to do, simply test and save.

Great, your 2 connectors are ready. Now it is time to move on and build the integration.

Let’s build the Integration

Now that we have our connectors, we can create the Integration.

  • Login into ICS console if not already there.
  • Click on Integrations

  • Click on New Integration and select Basic Map Data.

  • Enter a sensible Name and description

  • Find and drag your new connector from the catalogue on the right into the right side of the integration pane. Enter a sensible endpoint name and description and click Next.

  • Wait while ICS downloads all the metadata. Basically this is the step where ICS will let you introspect across all Business Objects and Services to interact exactly with the target functionality in Sales Cloud.
  • Select Brose by Services
  • Select ContactService from the Service catalogue.
  • Select findContact as the operation to call. Then click Next.

  • Review and click Done.

  • Now find and drag your REST connector from the right catalogue into the left side of the integration pane. If you have multiple connectors, you can enter a keyword to filter the catalogue list. IN the example below I simply entered rest and hit the search icon. It will filter and give me exactly the connector that I need to drag and drop.

  • Fill in the configuration of the REST connector. In the next picture, take a look how I did it in my case.

    Notice how I used curly braces to denote the account from which I want to retrieve the list of contacts from.

    When done, click Next.

  • Make sure the account parameter that you specified as a template using curly braces is of type string. Then click Next.

  • For the time being, simply allow all origins by entering * – Then click Next.

  • Select JSON for the response type and click on the <<< inline>>> link

  • Type the JSON that matches the response that you wish to return from the list of contacts. In my case I entered something like this:

{“Contacts”: [{“id”:”id”, “name”:”name”, “title”:”title”, “phone”:”phone”, “email”:”email”},

{“id”:”id”, “name”:”name”, “title”:”title”, “phone”:”phone”, “email”:”email”}]}

        Notice that, since we are going to potentially return a list of multiple contacts, I am declaring an Array in JSON.

  • When done, click OK and then Next.
  • Confirm and click Done.
  • Click on the first mapping (request) and click on the “+” icon to create a new request mapping.

  • Oracle Sales Cloud, is part of the family of Oracle Fusion Applications, including HCM and ERP Cloud (Financials, ERP Procurement, Supply Chain Management). They all behave very similarly. In this example we need to build a query that basically specified the following:

For Account name “S2V Exec Hospital”, return all its Contact Ids, Names, Emails, Mobiles and Work Titles

One way we can make this possible in Sales Cloud (and other Oracle Fusion Applications) is by using operation findContact and configuring a simple filter.

That is:

  • Once the findContact request Mapper is open,
    • Expand: filter > group > item and enter the following values:
    • Click on attribute and set it to AccountName – You do not need quotes. Don’t forget to click Save before closing.
    • Click on operator and set it to CONTAINS – You do not need quotes. Don’t forget to click Save before closing.

Note: CONTAINS is one of the many available operators, among others such as:

  • AFTER, BEFORE, BETWEEN, CONTAINS, CONTAINSALL,
  • NOTBETWEEN, ONORAFTER, ONORBEFORE, STARTSWITH
  • CONTAINSDELIMITEDID, DOESNOTCONTAIN, ENDSWITH,
  • =, >=, >, ISBLANK, ISNOTBLANK, <=, <, <>

  • From the left menu, drag your account attribute into the right menu on value

 

  • So far, your mapping should look like this:

 

  • Now, it’s time to define which attributes out of Object Contact you want to return. You do this by setting the findAttribute attribute…
  • Given that we need multiple attributes (id, name, title, phone and email), right click on the “Mapping” column in front of findAttribute element and select Repeat Element.
  • Repeat these steps 5 times… It should look like this:

  • Now, click on each findAttribute element and enter the Business Objects that we need to return. If you want to see the full list of attributes, check the Sales Cloud Documentation for Contact object. In this case:
    • PartyId
    • ContactName
    • JobTitle
    • EmailAddress
    • MobileNumber

  • Make sure to Save and then Exit the Mapper.
  • Now click on the Response Mapper and click on the “+” icon to create a new one.

  • First, drag and drop the top left root result element to the top right root Contacts element. This will make sure to iterate across a simple for-each loop.
  • Then connect the required fields:
    • PartyId -> id
    • ContactName -> name
    • JobTitle -> title
    • MobileNumber -> phone
    • EmailAddress -> email

    Since the source list of elements is huge, you can use the filter element. Simply enter the name of the field and click on the search icon.

    For example for MobileNumber below:

  • Once complete, Save and then Exit
    the mapper.
  • We are almost done with the integration, add tracing by clicking on the top right Tracing link and drag and drop account from the left menu to the first Tracking field. Then click Done.

  • Save and make sure to get a green 100% icon on the top right. That means your integration is complete.

  • Exit the Integration.
  • Your new Integration will show up, in order to activate it, click on the Activation bar for this integration. A window will pop up, tick on Enable Tracing and click Activate.

  • Wait a minute and that’s it, your activation is complete. You can now test your integration.

  • Click on the “information” icon next to the green bar and then click on the link, it will take you to the Metadata of the external REST API

  • The REST metadata will show up

  • This is going to encode your username and password as an Authorization token.

  • When you are done, click Send. You should receive the list of Contacts who belong to S2V Exec Hospital Account. The response will come in the JSON format that you specified.

Congratulations!!! You just completed your first REST API to return all your Contacts from your Account in Sales Cloud!!!

Build the other Integrations

In the previous sections, we explained step by step how to GET all Contacts from a specific Account in Sales Force and expose this as a simple REST API.

Now we need to:

  • Create a new REST APIs that GETs a specific Contact based on his ID – For this we can reuse the previous GET all contacts API to get specific IDs to utilise as part of the Get Contact by Id operation.
  • Create a new REST API that POSTS a new Contact as part of a given Account. – We are going to use the same Account that we used previously (S2V Exec Hospital)
Let’s build a REST API that GETs Contact By Id

This REST API is very similar to the first one. The only considerations are the following:

  1. Instead of findContact, use getContact operation this time
  2. The API URI will be something like: /sc/contact/{id}

  1. Where {id} will map as a request to PartyId

  1. The response doesn’t need an JSON Array anymore, but simply a collection of: {“id”:”id”, “name”:”name”, “title”:”title”, “phone”:”phone”, “email”:”email”}

  1. When you test it, make sure to substitute in the actual REST API URI the {id} by the actual Id – You can use the first API to get all Contact details and simply copy one of the Ids.

    For example:

    https://xxx-xxx.integration.us2.oraclecloud.com/integration/flowapi/rest/S2VIIA_SC_GETACONT_INT/v01/sc/contact/300000130688678

That’s it, the rest is the very similar to the first Integration. You should be able to create it in a matter of minutes.

If you have any question, do not hesitate to contact any of the authors of solutionsanz.blog – We are here to help you!

Let’s build a REST API that POSTs a new Contact

This REST API is similar to the previous ones, but have some differences. The main considerations to note are the following:

  1. Instead of findContact or getContact, use mergeContact operation this time

    Think of mergeContact as an UPSERT function, i.e. it will create the contact if not already there or will update it if it already exists!

  2. The API URL URI is simpler this time, just: /sc/contact – But differently to the last 2 APIs, this one is of type POST
  3. As part of the API configuration, tick to setup a Request and Response.

  1. For the JSON request you can use something like this:

    {“accountId”:”accountId”, “firstName”:”firstName”,”lastName”:”lastName”, “title”:”title”, “phone”:”phone”, “email”:”email”}

  2. As for the response, you can simply get the new Contact Id: {“contactId”:”contactId”}
  3. During the Request Mapping, link the fields as you have been doing in the last 2 Integrations.

    The only ones that are new are:

  • firstName and lastName – These fields will ultimately compound the ContactName, but need to be entered separately.
  • accountId field on the left (source) which has to map to the AccountPartyId on the right (target)…

That means that the new contact to be created is going to be associated to that particular Account (in this case, S2V Exec Hospital)

Note: As part of the input request we need to enter the AccountId for S2V Exec Hospital, which we don’t have yet… All we have is the Account Name, i.e. S2V Exec Hospital. As you can imagine by now, we could easily retrieve this id in a similar way as we retrieved the Contact Ids, i.e. by using ICS to invoke findAccount and filter by OrganizationName
CONTAINS
“S2V” or something like that. Perhaps an orchestration would be more appropriate, so that the integration gets the id based on an enrichment via the Account Name.

However, since this is out of the scope of this blog, let’s get the AccountId using a sneaky way, that is going to be very helpful as part of your Fusion Apps integrations anyway… This is by using a SOAP client, such as SOAPUI to call Account Service ->
findAccount, similarly using a filter where attribute
OrganizationName
CONTAINS “S2V”.

This is how you do it:

  • First you need to retrieve the WSDL location of the right Sales Cloud Business Object Service, in this case Sales Cloud Account

  • Replace “(CRMDomain,CRM Common)” by your own Sales Cloud Domain, for example in my case it is: ucf3-fap2097-crm.oracledemos.com

So, the whole Account Service WSDL:

https://(CRMDomain,CRM Common)/crmCommonSalesParties/AccountService?WSDL

Becomes:

https://ucf3-fap2097-crm.oracledemos.com/crmCommonSalesParties/AccountService?WSDL

  • In SOAPUI, create a new SOAP Project using this WSDL. It will create requests for each operation in the WSDL.
  • In SOAPUI, go to findAccount operation request.
  • Configure the filter->group->item to include the required filter: OrganizationName
    CONTAINS S2V

  • Also, add the findAttribute that you want to return, in this case the Account
    PartyId

  • Since the request is secured, add a Basic Authentication by clicking down on the Auth tab and enter your username and password:

  • Then simply right click anywhere on your XML request and select Add WSS Username Token and then right click again anywhere in the XML request and click on Add WS-Timestamp – This will ensure to create the right headers.

  • Then simply hit the green submit icon and if your request is correct, you will get the response which will contain the Account PartyId.

This is the Account Id of “S2V Exec Hospital” – Take this Account PartyId (300000130688564) and use it as part of your test later.

  • Your Request Mapping will look like this:

  1. During the Response Mapping, simply set the PartyId to contactId, so that it returns the Id of the new Contact that was created.

  1. Similarly, as with the previous REST APIs, you can use Postman, which in this case makes it even more sense given it is not a GET request anymore.

    This time make sure to set your method as POST

  2. Add a header Content-Type set to application/json

  • Set the base URL and add your API URI as indicated in your REST API Metadata.

 

For example:

https://xxx-xxx.integration.us2.oraclecloud.com/integration/flowapi/rest/S2VIIA_SC_CREATECO_INT/v01/sc/contact

  • Based on your REST API Metadata (see below), add the body of the request that contains the structure defined in your REST API Request configuration. As we did with the first API, the API Metadata will also show you a sample that you can use.

Sample Body:

{“accountId”:”300000130688564“, “firstName”:”Alessia”,”lastName”:”Sacchi”, “title”:”Digital Guru”, “phone”:”61426926756″, “email”:” alessia.sacchi@oracle.com “}

Note: 300000130688564 is our “S2V Exec HospitalAccountId that we retrieved in the previous step.

  1. Don’t forget to add your Authentication.
  2. That’s it, when you test it, you should get a new Id, that corresponds to the new Contact that was created.

  1. One way to verify that the Contact was really created, use the first API (getContacts) and make sure that you get the new Contact as part of the list of Contacts. Another way is to check in Sales Cloud and make sure the Contact is there within S2V Exec Hospital Account.

Congratulations, I hope this blog helped demystify how to use ICS to integrate into Oracle Sales Cloud.

If you have any question, do not hesitate to contact any of the authors of solutionsanz.blog – We are here to help you!

Author: Carlos Rodriguez Iturria

I am extremely passionate about people, technology and the most effective ways to connect the two by sharing my knowledge and experience. Working collaboratively with customers and partners inspires and excites me, especially when the outcome is noticeable valuable to a business and results in true innovation. I enjoy learning and teaching, as I recognise that this is a critical aspect of remaining at the forefront of technology in the modern era. Over the past 10+ years, I have developed and defined solutions that are reliable, secure and scalable, working closely with a diverse range of stakeholders. I enjoy leading engagements and am very active in the technical communities – both internal and external. I have stood out as a noticeable mentor running technology events across major cities in Australia and New Zealand, including various technology areas such as, Enterprise Integrations, API Management, Cloud Integration, IaaS and PaaS adoption, DevOps, Continuous Integration, Continuous Automation among others. In recent years, I have shaped my role and directed my capabilities towards educating and architecting benefits for customers using Oracle and AWS Cloud technologies. I get especially excited when I am able to position both as a way to exceed my customers’ expectations. I hold a bachelor degree in Computer Science and certifications in Oracle and AWS Solutions Architecture.

One thought on “Teaching how to integrate Sales Cloud with Integration Cloud Service”

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s