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

This is part 2 of the blog series that covers SOAP and REST integration with Sales Cloud

In part 1, I covered the topic of invoking Sales Cloud SOAP web services from external applications. In this part, I will cover the topic of invoking external SOAP services from Sales Cloud.

2. Invoking external SOAP Web Services from Sales Cloud

Sales Cloud Application Composer allows you to invoke external web services from within Sales Cloud.

In your Sales Cloud instance, use the Navigator to navigate to Tools > Customization >Application Composer.
Invoking an external SOAP web service using Application Composer is three step process

• Register the external Web service definition in Oracle Sales Cloud
• Create groovy triggers in Sales Cloud object to Compose a payload in groovy and trigger the registered web service passing the payload
• Test and Debug web service invocations

2a. Register the external Web service definition in Oracle Sales Cloud

Log in to Sales Cloud using a user that has Sales Administrator access. Create a sandbox (this is required before performing any customization on Sales Cloud). Next, launch Application Composer using the Navigation menu(hamburger menu). Once in Application Composer, click on Web Services in the left navigation bar

For this exercise, let us assume that we are synchronizing an opportunity created in Sales Cloud immediately in an on-premise system. To register a new web service end point, click the 'Create' icon, give the reference a name, say' OpptySync', provide the WSDL for this external service, and click Read WSDL. Let us assume that this external service uses Username/ password for authentication. Select the ‘Invoke with separate user credentials over SSL’ policy and create a credential key. Save and Close

Note: If your external service is also protected using Oracle Webservice Manager (OWSM) then the security options in the figure above translates to invoking web services protected with one of the following OWSM security policies

• wss_username_token_over_ssl_service_policy
• wss_username_token_with_message_protection_service_policy
• wss11_saml_token_with_message_protection_client_policy
• wss_saml_token_bearer_over_ssl_client_policy
• wss11_saml _token_ identity_switch_with_message_protection_service_policy

If the external service is not protected using OWSM then refer the interoperability scenarios at http://docs.oracle.com/cd/E57014_01/owsm/interoperability/owsm-interop-intro.htm

2b. Create groovy triggers in Sales Cloud object to Compose a payload in groovy and trigger the registered web service passing the payload

The next task is to configure Sales Cloud such that this web service is invoked whenever a new Oppty is created. This is achieved using a trigger written in groovy language. Launch Application Composer if not launched already. Select the Sales Application from the dropdown on the left. The application chosen will vary based on the object that you are choosing. For example, Opportunity is specific to Sales and hence under Sales Application. An account or contact is generic and hence is available under Common

Select the Opportunity Object. Drill down to select ‘Action and Scripts’. Navigate to the triggers tab and click on new.

Create a New trigger on “After Update in Database”. This fires for both create and update. The trigger code is written in groovy as shown below.

Note a few things here. Expand the Show Pallete. This provides you with a list of functions, Fields, keywords and web services that you can easily insert. Remember that this code is getting executed in the context of the current object. So if you want to refer to a particular field of the current opportunity in context, all you have to do is just refer it directly. For example if you want to refer to Country field you can simply search for it in the pallete and insert it (as shown in the screen shot). If you were to do println of the country field, you will see in the logs (how to access - discussed later) the value of the country field in the UI that the end user is viewing.

The same thing applies to web services as well. The web service created will show up in the palette for inserting into the groovy code and passing all necessary values from the UI (see image below)

No XML manipulation or SOAP Payload construction is done at the groovy level. The translation from Groovy Maps to SOAP payloads is taken care of by Sales Cloud infrastructure using the web service definition that you created in the previous step.

try {
 def userEmailAddress = adf.context.getSecurityContext().getUserProfile().getBusinessEmail().toLowerCase() println('Entering Update Oppty') println('Building Oppty payload') def OpptyWebSvcPayload = [
  [CreatedBy: nvl(userEmailAddress, ''), CurrencyCode: nvl(CurrencyCode, ''), LastUpdatedBy: nvl(userEmailAddress, ''), Name: nvl(Name, ''), WinProb: nvl(WinProb, ''), Revenue: nvl(Revenue, ''), PrSrcNumber: nvl(PrSrcNumber, ''), OpportunityLead: [
   [LeadNumber: nvl(LeadNumber, ''), ]
  ], ]
 ] println('Invoking Oppty Update in External System with payload: ' + OpptyWebSvcPayload) def resp = adf.webServices.CreateOppty.process(OpptyWebSvcPayload) if (resp == null) {
  throw new Exception('Null response from web service')
 } println('Oppty Update response received') println('Response: ' + resp.toString())
} catch (e) {
 println('Failed to Sync Oppty due to: ' + e.getMessage()) e.printStackTrace()
}

A highly simplified version of this groovy code is presented below. The simplicity is for easy understanding. The complete Oracle Sales Cloud groovy scripting reference guide is available here. Additionally some best practices for writing groovy code in Sales Cloud App composer can be found here

2c. Test and Debug web service invocations

Since the above trigger was written to fire on create/update of an opportunity, no additional custom UI element is required in Sales Cloud to initiate the integration. Instead of a trigger, a custom UI widget such as a button can be created and configured to execute the same groovy code. I'll proceed with the assumption that we are using a trigger and hence to test the web service invocation, I have to merely create a new opportunity on Sales Cloud and click Save.

To debug, you can use print statements in groovy code to print values during the trigger execution. These print statements can be viewed through the Application Composer itself. Navigate to Runtime messages as shown in the screen below. Ensure that you are in the ‘Sales’ application and ensure that the logging flag is checked. As you create or edit opportunities, you should see the log messages.

Note: In addition to invoking SOAP services during record edit or create, Sales Cloud can also raise events that integration systems can consume. This is covered in another blog which is not part of this series - http://www.ateam-oracle.com/osc-ics-using-events/

This concludes the topic of making outbound SOAP invocations from Sales Cloud.