Integrating with Sales Cloud using SOAP web services and REST APIs (Part 3)

This is part 3 of the blog series that covers SOAP and REST integration with Sales Cloud. In part 1 and part 2, I covered SOAP services. In this part I’ll be covering Sales Cloud REST APIs

Please note that this blog was written in 2016 when R11 SaaS was available. Current version is R13. Although much of this blog still applies, REST APIs have largely been improved. Please visit https://docs.oracle.com/en/cloud/saas/engagement/19c/faaps/rest-endpoints.html for the latest as of Aug 2019

Sales Cloud provides REST APIs that allow external applications to view and edit Sales Cloud data. A complete catalog of these REST APIs is available at the Oracle Help Center

In this catalog you’ll notice several details as shown in the screenshot below

Sales Cloud REST APIs are automatically available in your Sales Cloud Instance. No additional configuration, or setup is required to enable REST APIs.

Sales Cloud REST APIs are also completely free of charge to use for any number of invocations you may want to make.

For each Sales Cloud object, GET, POST, PATCH and DELETE HTTP Methods are supported corresponding to CRUD operations on these Sales Objects. These appear in the API catalog, on the left navigation, under Accounts entry. The request and response payload structure along with sample payloads are all provided in this one stop shop.

The REST APIs also directly correlate to Sales Cloud UI. That is, if you have a field that is required or is of a specific data type, then the REST API automatically reflects those validations.

In addition to the Parent Object, REST APIs also supports using child objects. In the API catalog screenshot above the Accounts Objects and its corresponding child objects are shown.

The simplest way for you to get started is to use a tool like SOAPUI or Postman to execute a “Get all” action on the Account object. I’ll use Postman and use the /crmCommonApi/resources/latest/accounts. Since the latest version is 11.1.11, this is the same as /crmCommonApi/resources/11.1.11/accounts. The only other header I provided is the authentication using Basic Auth.

Note that URL references in the blog are of the format https://<instance>.crm.<datacenter>.oraclecloud.com. If the service was from HR, the URL had to be https://<instance>.hcm.<datacenter>.oraclecloud.com. This was true until R12. Starting R13, there's only one URL format for all services https://<instance>.fa.<datacenter>.oraclecloud.com

You can then query for a specific account now, as described in the “Get an Account” task of the catalog. The API will now be https://<instance>.crm.<datacenter>.oraclecloud.com/crmCommonApi/resources/11.1.11/accounts/3008

If you want to understand more about each field within the account object, then use https://<instance>.crm.<datacenter>.oraclecloud.com/crmCommonApi/resources/11.1.11/accounts/describe

It is possible to filter specific the results such that you see only the data that you need using the “fields” parameter

https://.crm..oraclecloud.com/crmCommonApi/resources/11.1.11/accounts/3008?fields=PartyUniqueName,PrimaryContactName

Even after specifying only two fields, you will notice that there are several other “links” return in the JSON response. These links are primarily used to navigate to child objects, self-references, and LOVs. In conformance to the HATEOAS constraints, Oracle Sales Cloud REST APIs provide these links to facilitate dynamic navigation from User interfaces. For example, it is easy to obtain the list of values associated with a given record, or access the child records, or during pagination it is easy to navigate back and forth to other sets of records. These links can be optionally be disabled using the onlyData=true parameter

Several parameters such as query, limit, total count, and order by are available when doing a GET. I won’t go into more details as these are very clearly described in the API catalog https://docs.oracle.com/cloud/latest/salescs_gs/FAAPS/Resource_Actions.html. It is very easy to play with these params. Try them out!

Custom Fields, Custom Objects, and REST APIs

All Custom objects will automatically have a REST API enabled. So, if you create a custom object called PromotionalMaterial, then you obtain an API /../PromotionalMaterial that exposes all fields of this object. No additional work is required. Any relationships that are modeled for between any combination of custom objects and standard objects are also exposed in the API immediately. Similarly, when custom fields are added to an existing standard object(for which a REST API is available), then these custom fields are also exposed immediately.

Important: Since you will typically be adding custom fields and custom objects when in an active Sandbox, these API changes will be visible only to those users that are using that sandbox. Once the changes are published to the mainline, all users will be able to access the new/modified APIs

Authentication

All Sales Cloud REST APIs are protected using an OWSM policy – oracle/multi_token_over_ssl_rest_service_policy. This policy currently the following client authentication methods

1. Basic Auth over SSL (which we used earlier in this post)

2. SAML 2.0 (provided a SAML trust is already established between the Sales Cloud and the calling service)

3. JWT Token (A bearer token instead of Basic Auth. If trust is set up between Sales Cloud and the calling service, the JWT token can be issued by the calling service)

Authorization

The data returned by the API is governed by the Sales Cloud Role and Data level security. For example, if John Doe does a GET on all Opportunities and authenticating using Basic Auth as John Doe, then Sales Cloud will check if John Doe is allowed to access Opportunities through the web service, and will also determine which Opportunities John Doe should be able to view based on standard data level security for Opportunities in Sales Cloud (more details here)

Additionally, clients can pre-verify the level of Role access for a given user by using /describe. For example, when John Doe executes /describe and it returns the content below, then it is clear that the GET and POST operation are allowed on this specific object. Additionally, Child objects can be protected separately and so it will have it’s own "actions" element with the allowed methods.

"actions":[  
   {  
      "name":"get",
      "method":"GET",
      "responseType":[  
         "application/json",
         "application/vnd.oracle.adf.resourcecollection+json"
      ]
   },
   {  
      "name":"create",
      "method":"POST",
      "requestType":[  
         "application/vnd.oracle.adf.resourceitem+json"
      ],
      "responseType":[  
         "application/json",
         "application/vnd.oracle.adf.resourceitem+json"
      ]
   }
]

Use Cases for SOAP vs REST APIs

Although Sales Cloud REST APIs can be used for both data integration use cases and UI extension use cases, it is likely that Sales Cloud REST APIs will be used more for the latter. Sales Cloud REST APIs use JSON by default making it a great choice for UI development (not the only reason). Sales Cloud SOAP services on the other hand use XML and since there are several mature integration tools that are based on XML technologies such as XSLT, and XQuery, it makes it easier for Integration developers to continue using SOAP Services. Additionally Sales Cloud Events and File integration choices are also available for data integration.

REST APIs are a huge boon for Custom UI development, which could take the form of building specific extensions Sales Cloud UIs, or for building fully standalone browser-based Javascript UIs, or Mobile UIs that are powered by Sales Cloud REST APIs. Since the REST API encapsulate all core Sales Cloud business logic and Security logic, custom UIs need not duplicate the same.

If you would like to get started on building your first UI based on Sales Cloud REST API, Angelo has written a very nice blog where he shows the usage of Oracle JET to build a custom UI that invokes Sales Cloud REST APIs.

Using Sales Cloud with Oracle Mobile Cloud Service when building Custom UIs

While Sales Cloud REST APIs are very powerful and intuitive to use, you may have requirements where it would make more sense to have a wrapper/proxy API which shapes these Sales Cloud APIs to make it more tailored for your custom UI. For example, your UI requirements may dictate the need for invoking multiple Sales Cloud APIs or even external applications, and shaping the data before it can be displayed meaningfully in your custom UI. When developing Single Page Applications (SPA) you may want to minimize the number of server calls made to render data and use getters and setters that simply bring the data that you are relevant to your current screen.

In such cases, as we discussed above, you will typically consider a wrapper/proxy layer. A good choice for implementing this shaping/orchestration/proxy would be any commercial product that serves as an API manager.

I'll talk next about using Oracle Mobile Cloud Service to implement this layer. Mobile Cloud Service is an Oracle offering which not only offers the power of creating and managing API endpoints, but also provides a Node.js engine to perform this orchestration, and connectors to connect to several end systems. In addition to serving as an API management layer, Mobile Cloud Service (as the name suggests) provide several Mobile centric features such as push notifications, offline support, caching support, and location support.

The focus of this blog is not to describe all Mobile Cloud Service (MCS) features, but to illustrate the usage of MCS with Sales Cloud using a simple example. We’ll also touch upon expanded security options when using this approach.
Note: If you would like to learn more about MCS, please refer to list of A-Team blogs on MCS

I'll next walk-through a simple use case of using MCS with Sales Cloud REST APIs.

Imagine a Sales Rep walking into a customer site for a meeting. This Rep would like to have a UI which provides details about this customer. Let's assume that the Sales Rep would like basic account details, open issues with existing products that this customer uses, and the current stock ticker of the company. As you may realize each of this information typically comes from a different system - account details come from Sales Cloud, Issue details (or Incidents) come from Service Cloud, and the stock ticker probably comes from Google Finance APIs . The developer of this custom UI however would like a single REST API called /Customers providing all this information.

Here are some high level steps to achieve this

Step 1: Create a new API in MCS and decide on a contract with the UI developer

Step 2: Create a REST connector in MCS to connect to Sales Cloud

Step 3: Create connectors to Service Cloud for incidents, and Google Finance for stock ticker

Step 4: Implement logic in MCS Node.js layer to orchestrate these calls

Step 5: Test service, add it to MCS Mobile back end, and expose MCS APIs securely

I’ll only discuss Step 2, Step 4 and Step 5. For step 1, refer to the Oracle MCS documentation. Step 3 is similar to Step 2.

For Step 2, refer to the image below. You will notice that when creating a connector you are providing only the endpoint of the top level Sales Cloud resource i.e. https://<instance>.crm.<datacenter>oraclecloud.com/crmCommonApi/resources/latest with no references to a specific Sales Cloud object. This connector will later be referenced in the Node.js implementation and specific resources will later be requested by the implementation code. For example Connector/Accounts. This decoupling is very useful when changing any connection details such as pointing the APIs to a different Sales Cloud instance or using different authentication credentials.

In the future, Oracle plans to release pre-build connectors to Sales Cloud which will also allow you to introspect the endpoints and browse different resources.

In terms of security, when creating the connector notice in the image below that I've chosen the SAML security policy. Since MCS and Sales Cloud are both Oracle Cloud products SSO and SAML trust is pre-established. By choosing SAML for the MCS to Sales Cloud communication, I ensure that the identity of the user invoking the /Customer MCS API will be automatically be propagated to Sales Cloud. Passing the user context is very important because, as you may recollect, the Sales Cloud API returns results specific to a user’s role and data level security access. To ensure that SAML works, MCS and Sales Cloud should be in the same oracle cloud identity domain which inherently sets up the SSO and SAML trust between these services.

Now step 4 requires me to invoke the Sales Cloud connector that I created using Node.js code and Oracle custom APIs. I'm not going into the details of how to attach a Node.js implementation to your MCS REST endpoint. This is explained very well in the Oracle MCS documentation. I'll just focus on the code that calls the Sales Cloud MCS connector that we created earlier. A sample code snippet for this looks like below

module.exports = function(service) {
    service.get('/mobile/custom/Customers/CustomerId', function(req, res) {
        var result = {};
        req.oracleMobile.connectors.ArvindSalesCloud.get('accounts', null, {
            qs: {
                fields: 'PartyUniqueName,StockSymbol',
                onlyData: 'true',
                limit: '10'
            }
        }).then( << Other code to gather Service Cloud and Stock price.Typically a series of Node.js calls are invoked using Futures or async.waterflow constructs >> function(result) {
                res.send(result.statusCode, result.result);
            },
            function(error) {
                res.send(500, error.error);
            });
    });
};

After implementation is complete, this API is attached to a Mobile Backend and published. The API is then protected for authentication using Basic Auth or OAuth. You can then call this API from the custom UI or using SOAPUI/Postman for the purpose of testing. Remember to pass the MCS Mobile Backend ID in your HTTP Header addition to providing the authentication headers. More details are available here in Oracle MCS documentation. Among other things, Mobile Backend acts an OAuth Client whose credentials are used by all Mobile apps that are using the MCS APIs. If the called MCS API includes calls to other MCS APIs (chaining) within the same backend, then the identity and credentials of the original caller are propagated through the chain of calls automatically.

As discussed before, when Sales Cloud and MCS are used together, they are typically provisioned in the same Oracle Cloud ID domain, inherently establishing a SAML trust. This is why MCS was able to invoke Sales Cloud using SAML when configuring the connector. In such environments, Sales Cloud is typically the IdP for Federation. In this setup, as soon as the end user using the mobile App logs in using the Sales Cloud credentials, he/she is able to request an OAuth token for the Mobile Backend which will be used for invocations in all subsequent contexts. This ensures end to end identity propagation.

As a closing remark, I'd like to point out that Sales Cloud REST APIs are very powerful, available out of the box, and free of charge to use. This post is to just introduce you to the APIs and point out some common implementation patterns. Expect to see more blogs from the A-Team on this topic.