In the previous chapters, we looked at basic integration patterns. In Chapter 2, Integrating Our First Two Applications, we created a point-to-point integration, integrating a SOAP inbound service and a REST outbound service, and in Chapter 3, Distribute Messages Using the Pub-Sub Model, we converted a simple integration into a publish and subscribe pair of integrations and extended it with multiple subscribers.
So far we have demonstrated the use of our own service definitions for the trigger services and online tooling to document and mock our back-end services. In this chapter we're going to demonstrate the integration between existing SaaS (Software as a Service) applications. Integrating with SaaS applications is getting more and more important now that companies are moving away from on-premises application to Cloud hosted solutions. Where we have the need to share data between on-premises applications, for example integrating our CRM with our ERP application, this requirement will still exist when using Cloud hosted versions of these solutions. As we do not have direct access to where these applications are hosted, we need some kind of integration platform like Oracle Integration Cloud Service to connect these applications with each other.
As SaaS solutions are created to provide economies of scale, are exposed to the unrestricted internet and need to support many variations in capability this can lead to complex APIs. To address this, we will often see adapters being provided to ease these challenges as we will see in this chapter.
We are going to bring the idea alive by introducing you to our aircraft maintenance department. This department uses Salesforce for CRM purposes and other SaaS applications for collaboration and messaging. The maintenance department has the requirement to interact these applications with each other, but they did not have an integration component and decided to use ICS. The first thing the department want to create is an integration that represents a scheduled aircraft maintenance that gets escalated which triggers sending a notification to the mobile phone of the case owner by SMS (Short Message Service).
Both service providers are SaaS applications. For the case management we are going to use Service Cloud from Salesforce (http://salesforce.com), and for sending SMS messages we will use Twilio (https://twilio.com). This chapter not only shows the steps to create the integration in ICS using simplified adapters, but also the configuration in both SaaS applications. The integration we are building in this chapter is shown here:
In this chapter, we will cover the following topics:
- How to set up the SaaS application
- Defining the necessary SaaS connections
- Differences in creating the integration with cloud adapters
- Simplifying the mapping of complex message structures
- How to test and troubleshoot the SaaS integration
Before we can build our integration, let's get acquainted with the SaaS applications we are going to integrate with. As shown in the previous diagram our inbound call is a notification send by Salesforce, this is in itself an asynchronous call. The notification is triggered when a Case in Service Cloud is escalated. Oracle ICS supports an out-of-the-box (OOTB) adapter that supports inbound interactions from Salesforce to ICS. Without a lot of extra configuration in Salesforce the adapter in ICS is capable of receiving notifications.
Our outbound call is also using an OOTB Cloud adapter, but Twilio. Twilio provides a Cloud service to send messages using SMS, MMS and voice messaging to mobile phones. The response of the message will create a new comment for the case that is escalated, mentioning the case owner received a SMS.
For this integration, we are going to use Service Cloud. Service Cloud is a customer service application. One major component is for creating cases around issues that are reported by customers. To complete our setup of Salesforce to send escalated cases to Integration Cloud, we need to execute the following steps:
- Get access to a Salesforce (Service Cloud) Enterprise or Developer instance.
- Generate the enterprise service definition (WSDL).
- Obtain or reset your security token.
- Create a workflow rule that triggers on escalated cases.
- Create an outbound message format and generate message WSDL.
If your organization already uses Salesforce (Service Cloud) request a user account with system administration rights or check if your existing account has these rights. If your organization doesn't have access to a Salesforce instance, like we encountered, or you want an environment for testing solutions, obtain a Salesforce Developer Edition instance. Go to https://developer.salesforce.com/signupand follow the instructions.
To integrate Salesforce with ICS we need the Enterprise Web Service definition. This is a WSDL file we need to generate in order to get access to the API. You can generate it yourself or obtain it from your organization's Salesforce administrator.
In our case, since we are using a developer instance we can generate the WSDL file ourselves. Log in to your Salesforce account. You must log in as a user who had the Modify All Data permission. After logging in, navigate to the Setup page. On the top right corner of each page you will find a set of icons as shown here:
Click on the setup icon, which is the third icon from the right in the menu in the top-right corner of the screen, and select the Setup Home item.
On the Setup page, we find a Quick Find box; enter API and select API under Custom Code to navigate to the download page. ICS uses the Force.com Enterprise WSDL in its communication. Scroll down to the WSDL and Client Certificates section and generate the Enterprise WSDL and save it as SForce-Enterprise.wsdl.
Because we access Salesforce from an IP address that isn't likely to be trusted for our instance, and because we use the API from ICS, we need a security token to log in. The security token is a case-sensitive alphanumeric code that we need to append to our password. Whenever your password is reset, your security token is also reset.
If you have already obtained the security token or can obtain it from your administrator, then the next step can be skipped, but in our case, we don't know it yet.
Click on the view profile icon, which is the last icon on the right, of the menu in the top-right corner of the screen and select the Settings. Enter Reset in the Quick Find box and select Reset My Security Token under My Personal Information.
On this page, click the Reset Security Token button, which will send out an e-mail with your new token. Be warned that after a reset, you can't use your old token anymore, and clients that use it will stop working:
Now that we have retrieved the WSDL and security token that we can use in ICS to create our connection, we need to define the actual workflow rule. Workflow rules are triggered when its conditions are met. In our scenario, we want the case owner to be notified when one of their cases is escalated, which happens when the Case Status is changed to Escalated.
Again, we need to navigate to the Setup Home page. In the Quick Find box, enter Workflow and select Workflow Rules under Process Automation to navigate to the rules page.
This page lists all workflow rules that are created for your organization. When starting with a clean environment, this list will be empty. On this page, we will find some quick tips and links to sample workflow rules and video tutorials.
Click the New Rule button to open the wizard for creating a new workflow rule:
In our case, we want to trigger the case object. In the first step, select Case in the Object drop-down list and click the Next button to proceed:
In the second step, we configure the workflow rule. In this step, we enter the name, description and criteria to trigger our workflow rule. Complete the configuration with the following details:
|
Criteria |
Property |
Action |
|
Edit Rule |
Rule Name |
Call it |
|
Description |
Add the description: | |
|
Evaluation Criteria |
Evaluate then rule when a record is? |
Choose the (default) option, created, and any time it's edited to subsequently meet criteria |
|
Rule Criteria |
Run this rule if the following? |
Choose criteria are met |
|
Field |
Select the Case: Status field | |
|
Operator |
Select the equals: operator | |
|
Value |
Click the lookup icon and check the Escalated option |
Click the Save and Next buttons to proceed. In the third step we can specify workflow actions that are executed when the criteria are met. You have the option to create a new task, send an email alert, automatically update a field, send an outbound message or select an existing action you created earlier. In our case let's choose to create a new outbound message. If this workflow action is triggered it sends a message to an external endpoint. Which is exactly what we want. The New Task and Field Update actions are internal actions whereas the New Email Alert sends an e-mail to given recipients.
The Outbound Messages page is where we can configure our new outbound message. Complete the configuration with the following details:
|
Property |
Value |
|
Name |
|
|
Unique Name |
This will be proposed based on the rule name and there is no need to change unless you'd like an alternate name. |
|
Description |
|
|
Endpoint URL |
Because we don't know endpoint from ICS yet, since we still need to create our integration, enter: |
|
User to send as |
Choose the account that is the owner of the sent message, for example, your own account. |
|
Protected Component |
Keep unchecked. |
|
Send Session ID |
Keep unchecked. |
|
Case fields to send |
Select the following available fields:
|
Click the Save button to accept the configuration. This will bring us back to the last step of creating the workflow rule. Click Done to complete the process.
Before we can activate our workflow rule, we need to complete our integration in ICS first. To complete the integration we need to generate the WSDL that we use to let ICS know what the message format is that it will receive from Salesforce.
On the Workflow Rule Detail page, click on the outbound message Case_OM:
We are navigated to the Workflow Outbound Message Detail page. To generate and download the WSDL, click the link after the field Endpoint URL. Save the WSDL file as SForce-CaseEscalated.wsdl:
At this point we have configured Salesforce as much as we can right now. We will return to Salesforce when the integration is done to edit the Endpoint URL and to activate our workflow rule.
For this integration we are going to invoke Twilio. Twilio allows software developers to send and receive SMS, MMS, and voice messages using web service APIs. In our integration, we are using Twilio to send out an SMS message to the mobile phone of the case owner. To complete our setup of Twilio to send escalated cases to the mobile phone, we need to execute the following steps:
- Get access to a Twilio account.
- Create or port a phone number for sending messages.
- Add verified caller IDs.
- Obtain live and/or test API credentials.
If your organization already uses Twilio, you can skip right to the Step 3 - add verified callers IDs section. If your organization doesn't have access to a Twilio account, as we found, or you want an account for testing solutions, obtain a free Twilio account. Go to https://www.twilio.com/try-twilio and follow the instructions. For the question WHICH PRODUCT DO YOU PLAN TO USE FIRST?, select the option SMS. For WHAT ARE YOU BUILDING?, select the option Other types of SMS Alerts and for CHOOSE YOUR LANGUAGE, select Java (because ICS adapters are built with Java).
This step is not necessary if you want to create a test solution. Each Twilio account comes with a live and test credentials when using the API. In our case, we can use the test credentials, but if you want to create (buy) or port a phone number, there are a few steps to complete.
To create or port a phone number navigate to the Phone Numbers service. Click the all products and services icon, which is always the bottom icon, in the menu on the left.
Click on the Phone Numbers service to manage the phone numbers of your account. In our case, we do not yet have a phone number for sending out SMS messages. In the submenu, click the item Manage Numbers and get a new number:
Use the Get a number now button to navigate to the Get Started page and subsequently click Get your first Twilio phone number. This will show a dialog box where you can pick your first phone number. Pick a phone number that can send SMS messages. An available number is assigned to you, but it isn't the default that will support SMS, just like in our case:
Search for a different number supports SMS. Your first number is part of the trial:
You can always go back to the chosen number on the Manage Number page where we started to create our first phone number:
To send messages to mobile phones, we first need to verify them so Twilio knows we are not spamming the number without their knowledge. In the Phone Number service, click on Verified Caller IDs and add the numbers you want to send messages to.
Like we mentioned in the previous step, we don't necessary need a phone number to send messages to a real device. We can use the test credentials, which uses a default phone number, +15005550006, to virtually send messages from.
To obtain the API credentials navigate to your account settings. Click the console home icon, which is always the top icon in the menu on the left. In the submenu, click the item Account and view the API Credentials. We will start building our integration with the TEST Credentials, but will use the LIVE Credentials during the final step. To see the Auth token, click on the lock icon. We need both values to create our connection in ICS shown as follows:
