You are on page 1of 52

Bridging the Gap between Internal Systems and Salesforce.

com using Oracle SOA Suite 11g


Overcoming Salesforce.com Integration Challenges August 2010 Author: Brian Sipsey of M&S Consulting http://www.mandsconsulting.com

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

INTEGRATING INTERNAL SYSTEMS AND CLOUD BASED APPLICATIONS

As the world of Business / IT Alignment evolves, and Process Centric IT becomes a focus for gaining visibility and driving transformation, organizations must assess if each application can be seamlessly integrated into the enterprise. The business model where a third party company manages applications and infrastructure inside of a cloud, aka Software as a Service (SaaS), has left organizations wondering what boundaries a cloud really has. How well can clouds integrate into an enterprise? Does our organization have control of our Software as a Service (SaaS) and managed environments?
Software as a Service (SaaS) is also known as Cloud computing because a third party has full ownership of all hardware and software. Use of the application is licensed out to customers as a service.

Advantages of the SaaS business model are a low startup cost, reduced risk for customers without strong internal IT, and increased scalability as users can be added and removed as needed

Oracle SOA Suite 11g, a member of the Fusion Middleware family, is a powerful suite of products for integration applications and SaaS environments. At a high level, integrating with a SaaS application might appear just like any other integration project. However, SaaS solutions have additional complexity around security, scalability, and endless customization options that require proper tooling to effectively achieve the integration. This white paper will demonstrate how one can bridge the gap between internal systems and SaaS applications. It will use Oracle SOA Suite 11g and Salesforce.com, both leading products in their space, to illustrate the concepts.
INTEGRATING SALESFORCE.COM INTO THE ENTERPRISE

Disadvantages are that there is no direct control of the environments, and licensing fees over time will typically result in a higher total cost of ownership.

There are many cases where it is valuable to automate business processes which originate or pass through Salesforce.com. A sale that originates in Salesforce.com could be then be automatically available in downstream CRM and Ordering systems once the sale is closed. Customers data may need to be synchronized and potentially updated in Salesforce.com to help instruct Sales Associates of cross selling opportunities. This whitepaper will describe how to overcome integration challenges and mold Salesforce.com to conform to the business needs of the enterprise.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 2

SaaS Interface Challenges


Software as a Service(SaaS) vendors have integration layers similar to most mature applications. Workflow can typically be configured to generate outbound events, and Web Service APIs provide fine grained access to the business objects.

If we look at the nature of SaaS, a few notable design challenges present themselves that should be addressed at the beginning of an integration project. A direct look at the nuances of Salesforce.com web services gives insight into common challenges of most SaaS providers. Overcoming Salesforce.com Integration Challenges SaaS Challenge Fine Grained, Weakly typed Services Oracle Fusion Middleware Solution Salesforce.com business services, like most application business services, attempt to be flexible, powerful and generic so users may accomplish any function. This leaves customers with the task of orchestrating the services to extend the functionality to make it readily consumable by the organization. Salesforce.com doesnt provide a strongly typed CRUD service for each object which is common in object oriented models. Instead, Salesforce.com provides single Create, Retrieve, Update, and Delete methods that work with generic arrays of objects of ANY type, and SQL queries that can be run directly against the Salesforce.com database. Processes within Oracle Fusion Middleware can identify the contents of the generic object arrays, and cast them into strongly typed arrays of objects so that data can be easily accessed within the middleware. Security SaaS Web Services are publicly available on the internet, meaning user logins, sessions, and security certificates must be well managed. SOA Suite can easily authenticate with Salesforce.com login methods and enforce additional encryption using centralized security policies. Large volumes of customers access Salesforce.com web services through a single login access point, and are redirected to a site specific end point after login. Real time assignment of web service binding information helps Salesforce.com handle the volume, but presents an additional challenge to integration developers. SOA Suite makes it easy to dynamically update endpoint bindings on a service definition after login. Salesforce.com allows users to add custom fields to any business object, but propagates this field into the service definition causing changes in the Middleware layer. Oracle Fusion Middleware provides an Enterprise Service Repository and a Meta Data Service (MDS) that can be

Scalability

Customizations

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 3

used to centrally administer updates and manage versions. Inbound and outbound service definitions can generate the same objects with different definitions that cause schema validation errors if both schemas are imported into the same project. A loosely coupled design of inbound and outbound services should be used to avoid this problem. Schema validation can be turned off as a compiler option, but this is not recommended. Public Outbound Event Interfaces Salesforce.com workflow can be easily configured to trigger events to a publicly available endpoint. Oracle Fusion Middleware makes it easy to expose and secure services conforming to a specified service definition.

PROBLEM STATEMENT

The use case covered for this white paper is a value add scenario where any high priority Account will be automatically followed up by a Business Owner who can reach out to the client to discuss additional opportunities. The Sales person will be using Salesforce.com to identify high priority accounts, and the Business Owner will be using an external Enterprise Application to contribute opportunities. Business Process for High Priority Accounts
integrating Salesforce.com with other applications in the enterprise can generate enormous value and transparency into Sales operations. The ability for SOA Suite to monitor and provide real time reports on the success of any standardized business
Business Owner (Enterprise App) Sales Representative (Salesforce)

Differentiating a sales process by

Set Salesforce Account to High Priority

Pursue Sales Opportunity

process can also inform about the success of enterprise wide sales strategies.

Follow Up on Account to Discover Sales Opportunities

Enter Sales Opportunities

Account Follow Up - Salesforce.com Outbound Integration When a Sales Representative using Salesforce.com indicates an Account is high priority, the account automatically transfers to an external Enterprise Application so the a Business Owner can further assess the clients needs. Opportunity Creation - Salesforce.com Inbound Integration A Business Owner will place a follow up call to a customer, and enter strategy information on the account in an Enterprise Application. A corresponding Opportunity will be automatically created under the account in Salesforce.com for a Sales Representative to pursue.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 4

This Business Process will explore many integration features of Salesforce.com such as Workflow, Outbound Messages, and the create and query methods of the web service API. This design will also demonstrate features of Oracle SOA Suite 11g including Mediators, and the creation of a loosely coupled architecture using SOA Composites. The diagram below shows how everything fits together. Component Layout of the Solution
Notable new features in Oracle Fusion Middleware 11g are Mediator Service Engine and SCA Composites. The Mediator Service Engine makes it faster to develop services focused on transformation and routing. The SCA Composite allows BPEL Processes, Mediators, and other engines (Rules, Human Workflow, etc) to work together in the same project.

Salesforce
Web Service Layer Save and Query Opportunities * * Workflow Rule Trigger Account Followup

Enterprise Application

Database

Outbound Message * * * * *

Oracle Fusion Middleware - SOA Suite


Salesforce Outbound * * Salesforce Inbound

**

Account * Follow Up * Enterprise * Business * Service

Enterprise Application * Inbound * Enterprise Application Outbound

Overview of Solution

To follow the steps outlined in this white paper, the following items are required. 1. 2. Salesforce.com User Account (a trial account can be obtained for 30 days) Install JDeveloper 11g, available on the Oracle Technical Network (OTN) http://www.oracle.com/technetwork/middleware/soasuite/downloads/i ndex.html.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 5

This technical white paper is broken down into several distinct sections that make it easy to jump to a particular section of interest, or follow the paper step by step as a primer on Salesforce.com integration with Oracle Fusion Middleware.

3.

Install the Oracle Database, WebLogic Server and SOA Suite 11g (all available on OTN http://www.oracle.com/technetwork/middleware/soasuite/downloads/i ndex.html)

1. Salesforce.com Outbound Integration

Scenario: When an account is updated in Salesforce.com with a status of High, the corresponding Opportunity will be sent to SOA Suite for processing in the enterprise. 1.1 1.2 1.3 1.4 1.5
2.

Create an Enterprise Business Service Create a Salesforce.com Outbound Event Create a Salesforce.com Workflow Rule Consume the Outbound Event with Oracle SOA Suite Configure the Salesforce.com Outbound Event
Salesforce.com Inbound Integration

Scenario: Creating a business service that exposed by SOA Suite to the enterprise that creates Opportunities within Salesforce.com. 2.1 2.2 2.3 2.4 Configure a Project for the Salesforce.com Inbound Integration Salesforce.com Authentication Create a New Salesforce.com Opportunity Query the Opportunity based on the Account Id

3. Enterprise Application Integration with DB Adapters

Scenario: SOA Suite will be used to create an inbound business service to add Accounts and an outbound event that notifies when strategy information is added to an account. 3.1 3.2 3.3 3.4 Setup the Enterprise Application Databse Insert a Record into the Enterprise Application Database Trigger Events from the Enterprise Application Database Configure Enterprise Business Service Routing Rules

4. Testing and Auditing the Integration

Scenario: Walk through an end to end test, and audit the process within SOA Suite. 4.1 4.2 4.3 4.4 Account Follow Up Test (Salesforce.com -> Enterprise Application) Audit the Account Follow Up Integration within Oracle SOA Opportunity Creation Test (Entperise Application to Salesforce.com) Audit the Opportunity Creation Integration within Oracle SOA

5. Conclusion

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 6

SECTION 1 - SALESFORCE OUTBOUND INTEGRATION

Business processes often originate from user actions within. A Workflow Rule will be created to trigger an event when an account is set to high priority. The Workflow Rule will then be linked to an Outbound Message Within SOA Suite, a service will be created to consume the outbound event. To ensure the design is application independent, an Enterprise Business Service will also be created to decouple the Salesforce.com integration from external applications. The Salesforce.com API documentation should be explored to see more options: http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_om_out boundmessaging_setting_up.htm.
Section 1.1 - Create an Enterprise Business Service
An Enterprise Business Service is a concept used in Oracle AIA (Application Integration Architecture) to loosely couple Application Business Connector Services, and also to enforce an Application Independent Business Domain. In this white paper, the inbound and outbound services are similar in concept to the Application Business Connector (ABCS) providers and requestor services.

To ensure the integration is loosely coupled and application independent, the first part of the project is to create a Business Service and Account definition that does not conform to either application specific representation of an account.
Step 1 - Open Oracle JDeveloper 11g

It is assumed that JDeveloper 11g and SOA Suite 11g have been installed. Both can be downloaded from oracle.com.
Step 2 - Create a new Application and an empty SOA Project

In JDeveloper, navigate to File | New | Application. Create a Generic Application named SalesforceIntegration. Right click on the application, and select New Project. Choose to create a SOA Project and name it AccountFollowUpEBS.
Step 3 - Create a Enterprise Account Business Object

Right click on the xsd directory within the SOA Project, and select New | XML | XML Document | Name the Document EnterpriseAccount.xsd. This enterprise account will serve as the canonical definition used in the middleware layer as an interchange format for accounts that is application independent. Copy the following schema definition into the xsd file.
<?xml version= '1.0' encoding= 'UTF-8' ?> <schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://xmlns.oracle.com/EnterpriseAccount" xmlns:ea="http://xmlns.oracle.com/EnterpriseAccount" xmlns="http://www.w3.org/2001/XMLSchema"> <element name="EnterpriseAccount" type="ea:EnterpriseAccountType"/> <complexType name="EnterpriseAccountType"> <sequence> <element name="accountId" type="string"/> <element name="accountNumber" type="string"/> <element name="accountName" type="string"/> <element name="description" type="string"/> <element name="annualRevenue" type="string"/> <element name="numberOfEmployees" type="string"/> <element name="phone" type="string"/> <element name="promotionStrategy" type="string"/>

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 7

<element name="strategyNotes" type="string"/> </sequence> </complexType> </schema>

Step 4 Create a new Mediator for Routing between applications


Mediators make it easy to quickly define a service definition based on an existing schema (xsd) by clicking on the generate WSDL gear icon.

Drag the Mediator Service Component from the Component Pallete into the SOA Composite, and Name the mediator AccountFollowUpMediator. Under Template, choose Interface Definition from WSDL. There is no WSDL yet, but clicking on the gear next to WSDL URL will generate one.

Step 5 Create a Service Definition accepting the Enterprise Account

On the Request tab, click on the flashlight, and select Project Schema Files | EnterpriseAccount.xsd | Enterprise Account. Then set the operation name to updateAccount and the port type name to updateAccount_ptt. Accepting these settings will create the business service that will be used to route between applications.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 8

Step 6 - Deploy the AccountFollowUpEBS Project

Deploy the process that was just created so the endpoint is available for the inbound and outbound Application Business Connectors. The routing on this service will be updated again at the end of the paper once the inbound integrations have been created.
Section 1.2 - Create a Salesforce.com Outbound Event
A Salesforce.com workflow can be used to detect complex data conditions and trigger an outbound message to notify external applications.

Define the structure and obtain the service definition for the outbound message.
Step 1 - Login to Salesforce.com

An assumption for this document is that you have a valid salesforce.com account. A test sandbox account should be used to avoid impacting production environments. A trial account can be obtained for 30 days.
Step 2 - Create a New Outbound Message

A workflow can be setup so that it executes when a certain data condition is met, and send an outbound message containing a specific Salesforce.com object. To create a workflow, navigate to the following location: Setup | Create | Workflow and Approvals | Outbound Messages | New Outbound Message. Salesforce.com will ask you to fill out three steps to complete the workflow.
Step 3 - New Outbound Message: Select Object

Select Opportunity as the object to send in the outbound message as shown below.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 9

Step 4 - New Outbound Message: Configure Outbound Message


To consume outbound messages from Salesforce.com, a service must be visible to salesforce. This white paper uses a publicly accessible endpoint. Additional Security configurations are available through Salesforce.com.

Fill out the name, description, and outbound URL. Since the endpoint has not been created yet, fill out a generic endpoint and the correct endpoint will be added once the publicly accessible service is available. Add the Opportunity fields that will be sent with this outbound message.

Step 5 Verify Outbound Message Press next to accept the default settings on step 3, and verify the Outbound message was correctly setup as shown below.

Step 6: Obtain Service Definition for Outbound Event

Select the Click for WSDL link, and save the wsdl that pops up as workflowOutboundMessage.wsdl. The WSDL file is a service definition defining the format that a web service will adhere to in order to consume the outbound message.
Section 1.3 - Create a Salesforce.com Workflow Rule

Now that an outbound event is created, a rule needs to be setup to trigger the outbound event.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 10

Step 1 - Create a New Workflow Rule

To create a Workflow Rule, navigate to the following location: Setup | Create | Workflow and Approvals | Workflow Rules | New Rule. Salesforce.com will ask you to fill out three steps to complete the workflow.

Step 2 - New Workflow Rule: Select Object


Workflow rules can be triggered on any Salesforce.com object based on the objects state, such as when it is newly created, and also based on a list of conditional statements around each field making it easy to generate business relevent events.

Specify that the Account object is going to be monitored by this workflow.

Step 3 - Configure Workflow Rule

Configure the Rule by filling out the following fields:

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 11

Rule Name: Customer Notification Description: Send a message to Oracle SOA Suite when a customer is updated Evaluation Rule: When a record is created, or edited and did not previously meet the rule criteria Run This Rule if the following criteria are met: Customer Priority equals High
Step 4 - Specify Workflow Actions

Link the outbound message created earlier named AccountChange to the Workflow to trigger the message.

Step 5 - Select Outbound Message and Save the Action


Salesforce.com Workflows Actions can be associated with Tasks, Email Alerts, Field Updates, and Outbound Messages .

Step 6 - Pressing Done to Finalize the Workflow Rule

At this point there are still two remaining salesforce.com configuration tasks. 1) The endpoint on the outbound message should be updated once the web service is made publicly available. 2) The Workflow Rule needs to be activated, which can be done by selecting the Activate Button after the Outbound Message is configured with the correct endpoint.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 12

Section 1.4 - Consume the Outbound Event with Oracle SOA Suite
Consuming the Oubound Event can be done by creating an end point that conforms to the service definition published by Salesforce.com. With Oracle SOA Suite 11g, a Mediator can be used to transform and route the message with just a few simple steps.

This section describes how to use Oracle JDeveloper 11g to implement a web service conforming to the service definition for the outbound event generated by Salesforce.com in the previous section. Once the message is received, a mediator will transform the message and route it to the Enterprise Business Service.
Step 1 - Create a new SOA Composite project within JDeveloper

Navigate to File | New | Application | SOA Application and fill in the required fields to create a New SOA Composite project. Name the Project SalesforceOutboundIntegration.
Step 2 - Copy the Salesforce.com Outbound Message Service Definition into the project

Copy the Salesforce.com service definition (workflowOutboundMessage.wsdl) downloaded in the previous section into the project directory that was created. To find the project directory, navigate to the workspace directory configured for JDeveloper, find the application directory, and then the project directory. The refresh button on the tree view will need to be pressed in JDeveloper to verify the service definition is available within the project.

Step 3 - Create a Mediator to Consume the Outbound Salesforce.com Message

Drag a Mediator from the Component Palette into the new SOA Composite. Name the Mediator OutboundSalesforceEventFollowUp and choose Interface Definition from WSDL. Click the Find Existing WDSL (+) Logo next to the WSDL URL, and select the workflowOutboundMessage.wsdl.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 13

Step 4 Create a Web Service Reference to the Enterprise Business Service


For this demo, Web Service references are obtained from the server rather than the file system to ensure correct service bindings are setup. Deployment plans in Oracle SOA Suite 11g allow users to create configurations that work with multiple environments.

Drag the Web Service from the Components Palette into the External References section of the SOA Composite. Name the reference UpdateAccountEBS, and click on the Find Existing WSDLs icon next to the WSDL URL field. In the SOA Resource Browser, change the drop down to Resource Palette, Expand the application server and project where the Enterprise Business Service is located, and select the AccountFollowUp service endpoint. Choose Okay to accept the configured service.

Step 5 Connect the Mediator to the UpdateAccountEBS Service Reference

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 14

Step 6 Open the Mediator and Select the Transform Icon

Step 7 Create a new Transform File and update the mappings


Mediators are based on the former Oracle Enterprise Service Bus and in SOA Suite 11g, can be added to SOA Composites to work side by side with other SOA Components such as BPEL Processes.

Step 8 Obtain an Endpoint for the Salesforce.com Outbound Integration

Deploy the process to SOA Suite. Open the Enterprise Manager, expand the SOA -> soa-infra, and verify the process was deployed successfully. Obtain an endpoint by clicking into the service and pressing the Test Web Service button.

Section 1.5 - Configure the Salesforce.com Outbound Message

This section shows how to update the end point on the outbound message and activate it.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 15

Ensure the Business Service exposed to consume Salesforce.com Outbound messages is visible to Salesforce.com. When SOA Suite is running within an organization, network administrators may be required to allow Salesforce.com access to the endpoint, the ip may need to be changed to a host name, and the port may need to be opened so it is accessible outside a firewall.

Step 1 - Update Endpoint Location for the Salesforce.com Outbound Event

Login to Salesforce.com and navigate to Setup | Create | Outbound Messages| Edit Account Change. Update and save the Endpoint URL to the publicly exposed endpoint. 1.4.2 Activate the Salesforce.com Outbound Event On the Outbound Message Detail screen, select the Activate button for the Customer Notification workflow rule that appears under the Workflow Rules Using this Outbound Message section. The salesforce inbound integration has now been completed. This can be unit tested by creating a high priority account within salesforce and seeing if the cooresponding SalesforceOutboundIntegration composite is kicked off within SOA Suite.

SECTION 2 SALESFORCE INBOUND INTEGRATION

Salesforce.com exposes standard web services for performing Create, Update, Retrieve, and Delete (CRUD) operations on underlying business objects. Oracle Fusion Middleware is ideal for orchestrating the Salesforce.com business services to drive functionality and expose a powerful layer of web services that are more relevant to the business. This section describes how to create a SOA Composite containing a BPEL Process that will orchestrate Salesforce.com services. The process will accept an Account containing additional strategy information, Login to Salesforce.com, Create an Opportunity, and then Query that Opportunity based on its account id.
Section 2.1 Configure a Project for the Salesforce.com Inbound Integration

This section will describe how to download the Salesforce.com Web Service API, configure elements, variables, and partner links, and plan the flow using the scope activity.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 16

Step 1 - Create a new SOA Composite Project with a BPEL Process

In JDeveloper Studio 11g, navigate to File | New | Create SOA Project. On Step 1, enter the Project Name SalesforceInboundIntegration, choose composite template Composite with BPEL, and press Finish. A Create BPEL Process will now pop up. Enter the name SalesforceInboundIntegration and specify the template as a One Way BPEL Process. This can also be made synchronous or asynchronous depending on what functionality the business service will contain.
Every time a custom field is added to an Object within Salesforce.com, the change will propagate into the generated service definition.

Step 2 - Generating the Salesforce.com Web Service Definition

An Enterprise WSDL is published by salesforce.com to represent the custom salesforce.com domain for each customer. After setting up customizations to business objects within Salesforce.com, a developer must log in to salesforce.com and navigate to setup | Develop | API Enterprise WSDL. Save the file as to the local file system as SalesforceEnterpriseServices.wsdl.

Step 3 - Add a Partner link for the Salesforce.com Services

Add the SalesforceEnterpriseServices.wsdl file to the project. Click the flashlight to find the SalesforceEnterpriseService.wsdl. A Ref file will be created to add additional partner link types.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 17

Step 4 - Modify the BPEL Process input variable to accept an Enterprise Account
The Enterprise Account is a simple canonical data model used to establish an enterprise domain that is independent of any other application.

Since this process is expected to lookup an account, the input parameter needs to be updated to accept an Enterprise Account. Add the EnterpriseAccount.xsd to this project. Open the schema definition for the BPEL Process. Add the following as shown in the illustration. 1) The namespace definition:
xmlns:eca=http://xmlns.oracle.com/EnterpriseAccount

This example could have been designed as a single BPEL Process that worked with both Salesforce.com and the Enterprise Application database. A loosely coupled design is just as easy to create and will quickly add value when changes come along down the road.

2) The import statement:


<import schemaLocation="EnterpriseAccount.xsd" namespace="http://xmlns.oracle.com/EnterpriseAccount" />

3) Update the process element to:


<element name="CustomerAccount" type="eca:EnterpriseAccountType"/>

The following image shows the new schema for the BPEL Process.

Step 5- Expose the Opportunity complexType as an Element

The complex types within the Salesforce.com service definition need to be exposed as elements before they can be manipulated as variables within BPEL. To do this, open the SalesforceEnterpriseServices.wsdl, find the Opportunity complex type, and add the line: <element name="OpportunityElement" type="ens:Opportunity"/>

Step 6 - Create a SalesforceOpportunity variable

Create a new variable to setup the Opportunity that will be created in Salesforce.com. Open the new variable dialog by clicking on the (x) on the outer scope of the process flow. Enter the name SalesforceOpportunity. Chose element,

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 18

and look through the available element in the enterprise.wsdl file to locate the OpportunityElement that was just added.

Step 7 - Create a Variable to store Session Header Information


Salesforce.com objects are generated as Complex Types in the service definition. Elements need to be created based on these complex types to manipulate them as variables.

Create a new variable to set the session id information that can be attached to soap requests when invoking the Salesforce.com API. Select the Message Type Flashlight | expand SalesforceEnterpriseServices.wsdl |Select the Header message type.

Step 8 - Create a Variable to update the Endpoint

This section will create a Endpoint Reference that can be used to update the server url on the partnerlink for all requests after a login to salesforce. Open the Create New Variable Dialog, and enter the variable name endpointReference. Select Type Element, select the flashlight, and then choose the option Import Schema File. Type the URL http://schemas.xmlsoap.org/ws/2003/03/addressing as the url, and enter ok. The addressing schema will now appear as an imported schema in the type explorer. Select the EndpointReference as the type and create the variable.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 19

Step 9 - Add Scopes to Outline the Process Flow


When using BPEL, scopes are handy for laying the functional aspects of a process flow prior to adding each activity.

Section 2.2 Salesforce.com Authentication

Access to the Salesforce.com API requires authentication with the salesforce login service, creating a session header to submit to subsequent requests, and updating the endpoint on the partner link for subsequent requests. For this project, the login endpoint binding used for login is: http://login.salesforce.com/services/Soap/c/19.0.
Step 1 Add Login Activities

Add an Assign activity named AssignCredentials, and an Invoke activity named LoginToSalesforce within the LoginToSalesforce scope.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 20

Step 2 Configure the Login to Salesforce.com Invoke Activity


Logging into Salesforce.com will return a session id and a server URL to be used for authentication and site specific binding on subsequent service calls.

Select the SalesforceEnterpriseService Partner Link, login operation and create default input and output variables.

Step 3 Configure the Assign Credentials Invoke Activity

Setup the user name and password for the Salesforce.com Account.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 21

Step 4 - Add Assigns to Set the Endpoint and Session Header


The session id needs to be passed into the SOAP header on method calls to validate identity.

Step 5 - Initialize an Endpoint Reference Element

Use the following XML Fragment to initialize the end point.

<EndpointReference xmlns="http://schemas.xmlsoap.org/ws/2003/03/addressing"> <Address/> </EndpointReference>

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 22

Step 6 - Copy the Server URL into the Endpoint Reference


All customers log into the same login service and are dynamically routed to a customer specific endpoint for accessing other Salesforce.com services.

Step 7 - Update the Endpoint Reference to Salesforce.com

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 23

Step 8 - Copy the Session ID into the Session Header Variable

Section 2.3 - Create a New Salesforce.com Opportunity


The create operation in Salesforce.com accepts an array of objects, so multiple objects of different types can be submitted in a single service call.

In this section, a Salesforce.com Opportunity will be created, required fields will be populated, and then the opportunity will be sent to the create operation on the Salesforce.com business service.
Step 1 Fill in the Write Opportunity Scope

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 24

Step 2 - Configure the Write Opportunity Invoke

Choose the SalesforceEnterpriseService as the partner link, create as the operation, and generate the default input and output variables.

Step 3 - Set the Session Header on the Invoke


In JDeveloper 10G, a tab on the invoke was used to set the session header. This tab has been removed in 11g, but the underlying BPEL can be updated directly in the source view to pass in the session id.

JDeveloper 11g does not provide a graphical way to set the header variable, but this can be remedied by updating the BPEL Source directly. Switch to the source view and add the following attribute to the invoke:
bpelx:inputHeaderVariable="headerRequest"

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 25

Step 4 - Intialize the Opportunity Element

In the Set Opportunity assign, we must fill in a series of copy operations to populate the Opportunity with required fields to write it to Salesforce.com.

The xml used in the XML Fragment is:

<sfdc:OpportunityElement xsi:type="sfdc:Opportunity" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:sfdc="urn:sobject.enterprise.soap.sforce.com"> <sfdc:AccountId xmlns:sfdc="urn:sobject.enterprise.soap.sforce.com"/> <sfdc:Amount xmlns:sfdc="urn:sobject.enterprise.soap.sforce.com"/> <sfdc:CloseDate xmlns:sfdc="urn:sobject.enterprise.soap.sforce.com"/> <sfdc:Description xmlns:sfdc="urn:sobject.enterprise.soap.sforce.com"/> <sfdc:Name xmlns:sfdc="urn:sobject.enterprise.soap.sforce.com"/> <sfdc:StageName xmlns:sfdc="urn:sobject.enterprise.soap.sforce.com"/> </sfdc:OpportunityElement>

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 26

Step 5 - Write the Account ID


Setting the account id on an opportunity will automatically link it to the desired Account.

Set the high level account id in the Salesforce.com Opportunity to link it to the correct account.

Step 6 - Set the Opportunity Name

For this example, the name will be the text Auto Generated plus the value entered into the Promotion Strategy field.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 27

Step 7 - Set the Amount of the Opportunity

A generic value of $5,500 will be set to the value of the opportunity.

Automatically creating an Opportunity within Salesforce.com will allow a Sales Representative to identify customer needs without constant communication with the Business Owner.

Step 8 - Set the Sales Stage for the Opportunity to Prospecting

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 28

Step 9 - Set the Opportunity Description to the Strategy Notes


Salesforce.com returns errors as strongly typed messages in the response. Fault handlers will be useful for catching binding faults, but the response variable also needs to be checked to determine if any specific business faults occurred,

Step 10 - Set the Close Date

Step 11 - Assign the Opportunity as the Create Input Object


The diagram in Step 11 shows that the create variable is weakly typed as an array of ANY type elements. All of the CRUD services work in the same way requiring the objects to be cast into strongly typed elements before the data can be easily accessed.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 29

Section 2.4 - Query the Opportunity based on the Account Id

This section will validate the opportunity was created and associated to the correct Account. This adds no functionality to the process, but demonstrates how to perform a query.
Step 1 Add Activities needed to perform a Query

Step 2 Fill out the Query Account Invoke Activity


Salesforce.com has created a proprietary Query language called SOQL (Salesforce Object Query Language) that is very similar to SQL and can be used to join objects and specify conditional clauses.

Set the Partner Link to SalesforceEnterpriseService, the operation to query, and add default input and output variables.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 30

Step 3 Set the Session Header on the Invoke

Switch to the source view and add the following attribute to the invoke:
bpelx:inputHeaderVariable="headerRequest"

Step 4 Assign the Query String


A SOQL Builder is available at salesforce.com to help build and test SOQL Queries.

Salesforce.com uses a query language similar to SQL called SOQL which can be set on the query. This query will return all opportunities on the account that has been passed in, which can be seen during audit to validate the opportunity was created.

The SOQL Query used here is: concat("SELECT Id, Name, AccountId ,CloseDate, Amount FROM Opportunity WHERE AccountId='", bpws:getVariableData('inputVariable','payload','/client:process/client:CustomerAc count/ns6:accountId'),"'")

SECTION 3 - ENTERPRISE APPLICATION INTEGRATION WITH DB ADAPTERS

This section will create a fictitious application named Enterprise Application to demonstrate how to use the DB Adapter in SOA Suite to build inbound and outbound integrations with a database. The routing rules on the Enterprise Business Service created at the beginning of this white paper will then be updated to create a loosely coupled integration between Salesforce.com and the Enterprise Application.
Section 3.1 - Set up the Enterprise Application Database

To keep things simple, this white paper will assume the Enterprise Application will be a simple database schema with a single table to store Account information. Two

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 31

account fields will be unique to the application named Promotion Strategy and Strategy Notes. Once filled in, this additional data will be used to auto generate a Salesforce.com Opportunity for the account. To set up the Enterprise Application, create a new database user named EnterpriseApp, and execute the following SQL to generate the Customer Account Table.
CREATE TABLE "ENTERPRISEAPP"."CUSTOMER_ACCOUNTS" ( "ACCOUNT_ID" VARCHAR2(20 BYTE) NOT NULL ENABLE, "ACCOUNT_NUMBER" VARCHAR2(20 BYTE), "ACCOUNT_NAME" VARCHAR2(20 BYTE), "DESCRIPTION" VARCHAR2(20 BYTE), "ANNUAL_REVENUE" VARCHAR2(20 BYTE), "NUMBER_OF_EMPLOYEES" NUMBER, "PHONE" VARCHAR2(20 BYTE), "PROMOTION_STRATEGY" VARCHAR2(20 BYTE), "STRATEGY_NOTES" VARCHAR2(20 BYTE), "CREATE_DATE" DATE, "UPDATE_DATE" DATE, CONSTRAINT "CUSTOMER_ACCOUNTS_PK" PRIMARY KEY ("ACCOUNT_ID") )

Section 3.2 - Insert a Record into the Enterprise Application Database

This section will demonstrate how to create a web service that accepts accounts and inserts them into the Enterprise Application.
Step 1 - Create a New Project

Create a SOA Project named EAInboundIntegration containing a BPEL Process named EAInboundAdapter.
Step 2 - Configure the Input Element to Accept an Enterprise Account
The Database Adapter automatically exposes complex database functionality such a Merge, Insert, Update, Delete, Select, and database polling as web services containing auto-generated request and response messages.

As was done earlier in this paper, import the CustomerAccount.xsd into the project. Then add the corresponding namespace, import statement, and Request element as shown below.

Step 3 - Create a Database Adapter to Insert Accounts

Open the EAInboundAdapter bpel process. Drag and drop the Database Adapter from the components panel into the partnerlink area of the BPEL Process. The Adapter Configuration Wizard will appear. Step 1: Click Next.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 32

Step 2: Add Service Name EnterpriseApplicationDB and Click Next Step 3: Select or Create a Connection to the database and click Next Step 4: Select Perform an Operation on a Table, check Insert Only, and press Next

Multiple tables can be chosen to create logic requiring table joins.

Step 5: Select the Table by clicking Import Table. Query for the Customer_Accounts table, move it into the Selected column, Press Next, and then Press Next again.

Step 6 : Press Next to skip Reachable Relationships

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 33

Step 7 : Setup the attributes that will be written

Step 8: Click Next Step 9: Click Finish.


Step 4 - Layout the Process

Create scope in the BPEL Process named InsertAccount filled with an Transform activity named SetupAccount and an Invoke activity named InsertAccount. A final returnSuccess assign activity has also been added to update the output value to Success.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 34

Step 5 - Configure the Insert Account Invoke

Configure the Invoke Operation to use operation insert and create the default parameters.

Step 6 - Transform the Enterprise Account


XSLT makes it quick to create and standardize transformations between business domains that can be reused throughout the application.

To convert the Enterprise Account into a readable format, open the transform. Select the source as the inputVariable payload, set the target to the insert input variable for the DB Adapter, and then Create a new mapper file named xsl/XFormCreateAccount.xsl. Update the mappings as shown.

Step 7 - Deploy the EAInbound project

Section 3.3 - Trigger Events from the Enterprise Application Database

Now that accounts are written to the EA database, this project will set up a polling mechanism to trigger a BPEL flow when the Strategy Notes are added to the Customer Account.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 35

Step 1 - Create an EA Outbound Integration Project

The auto generated services and port types are not needed in this bpel process since a DB Polling Adapter will instantiate the process, and an external service will then be invoked.

Create a new SOA Project named EAOutboundIntegration that contains a BPEL Process named UpdateAccount. In the composite, we will delete the Exposed Service that was created since the process will be initiated from a polling adapter. The default WSDL definition can also be removed.

Step 2 - Create a new DB Adapter to Poll the EA Database

Open the BPEL Process and drag the Database Adapter from the Component Palette onto the process. Name the Adapter DatabaseEventListener and press next.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 36

Step 3 - Choose the Database Connection and press Next.

Database Polling works by executing a query against the database at intervals and generating a message containing all new or changed records. All records will be sent as an array in the same process flow, so records may need to be looped through and individually processed or correlated with long running processes.

Step 4 - Choose to Poll for New or Changed Records in a Table

Step 5 - Choose the table CUSTOMER_ACCOUNTS

The Query button will display a list of available tables will appear. Select CUSTOMER_ACCOUNT and click the arrow to move it into the selected tables. Click OK and next through to step 8.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 37

Step 6 - Choose to Delete the Row that was Read

Step 7 - Accept Default Polling

Step 8 - Edit the SQL to Read Accounts with a Promotion Strategy


Database Polling requires a data condition to be satisfied within the database to identify when a record has changed. This trigger can be an update or create date, restricting the query based on a data value, or as simple as removing the record once it polled.

Add a where clause to the sql by pressing the edit button and building a new Expression. Set the Query Key to Promotion_Strategy, the Operator to Not Equal, and the Second Argument to an empty Literal that will be translated to null. Then press Ok, Next, Next, Finish to create the adapter.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 38

When consuming outbound events from a database, the initial Receive activity must have the Create Instance box checked so the process can be created.

Step 9 Update the Initial Receive Activity for the BPEL Process Double click on the default receive activity that instantiates the process. Change the name to ReceiveAccountUpdate, Change the Partner Link to the DatabaseEventListener, set the operation to receive, and create the default variable. Ensure that the Create Instance button is checked.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 39

Step 10 Create a Partner Link to the Enterprise Business Service


By having all outbound business connectors call the Enterprise Business Service, it is easy to centrally configure the routing of all messages.

Drag a Web Service onto the BPEL Process. Name it SaveAccountEBS, make it of type reference, and pull up the search for the WSDL URL. In the SOA Resource Browser, navigate to the Resource Palette| Application Server | EBS Project Name | and select the WSDL.

Step 11 Update the clientCallback Invoke to call the EnterpriseBusinessService

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 40

Step 12 Add a Transform Operation


This process is triggered by a database adapter, so it is important to check the Receive activity connected to the Database Event Listener and ensure the Create Instance option is checked.

Map the input variable from the DB Polling Adapter to the outbound variable being sent to the Enterprise Business Service, and create a new XSL Mapper file.

Step 13 Map the EA Account to the Enterprise Account

Step 14 - Deploy the SalesforceOutboundIntegration project

Section 3.4 - Configure Enterprise Business Service Routing Rules


This whitepaper describes a very simple integration where routing can directly occur between application specific business connectors. For more complex processes, the Enterprise Business Service may route to a long running Enterprise Business Flow that could centrally manage the flow in an application independent way.

Now that Inbound and Outbound Integrations have been setup for Salesforce.com and the example Enterprise Application, the routing logic within the Enterprise Business Service can be updated.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 41

Step 1 Add Web Service References to the Salesforce.com Inbound Integration

In the AccountFollowUpEBS composite.xml, drag a Web Service onto the SOA Composite. Create a Service named Salesforce.com of type reference, and open the SOA Resource Browser to find the Salesforce.com Inbound WSDL location on the application server in the Resource Palette.

Step 2 Add Web Service References to the EA Inbound Integration

Drag another Web Service onto the SOA Composite. Create a Service named EAInbound of type reference, and open the SOA Resource Browser to find the EA Inbound WSDL location on the application server in the Resource Palette.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 42

Once a Mediator is connected two services, content-based routing rules need to be configured or messages will be propagated to both services.

Step 3 Connect the Mediator to the newly created Service Reference

Step 4 Add Routing Rules in the Mediator

Double Click on the Mediator to view the routing. Static Routing references have been created, but the routing rules need to be updated so the mediator correctly route based on the content of the EnterpriseAccount. For each Static Routing Rule, click on the funnel to edit the Routing Expression. For the Salesforce.com Mapping add:
string($in.request/inp1:EnterpriseAccount/inp1:strategyNotes) != ""

For the EA Inbound Mapping, add the inverse:


string($in.request/inp1:EnterpriseAccount/inp1:strategyNotes) = ""

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 43

Step 5 - Deploy the Enterprise Business Service

SECTION 4 - TESTING AND AUDITING THE INTEGRATION

This section outlines how to run the end to end test, and then audits the BPEL Process to show the results.
Section 4.1 - Account Follow Up Test (Salesforce.com Enterprise Application)
New Accounts can be created quickly in Salesforce.com by navigating to the Accounts tab and selecting New.

Step 1 - Navigate within Salesforce.com to Create New Account

After logging into Salesforce.com, select Create New Account which can also be accessed under the Account tab by clicking the New button.

Step 2 - Enter the Account Information

Ensure the Customer Priority is set to High to trigger the workflow, and fill out the Phone, Annul Revenue, Employees, and Description fields which will be viewed by the business user in the external Enterprise Application Press Save.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 44

Step 3 - View the Account in the Enterprise Application


SQL Developer is being used as the User Interface to update fields in this demo Enterprise Application.

Section 4.2 - Audit the Account Follow Up Integration within Oracle SOA Suite
Step 1 - Navigate to the process instances

Open the Enterprise Manager, click on SOA | soa-infra | Instances tab | Press Search. The flow can now be seen through the SalesforceOutboundIntegration process into the EAInboundIntegration Process.

Step 2 - View the Flow Trace

Click on the Instance ID for the EAInboundIntegration that was just run.
The flow trace highlights the loosely coupled process flow from the OutboundSalesforce.com integration, through the Enterprise Business Service, and into the Inbound EA integration.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 45

Step 3 - Validate the Data Insert

Click on the EAOutboundAdapter BPEL Component to validate everything ran successfully. Expand the UpdateAccountInvoke to validate the data being inserted into the Enterprise Application.

Section 4.3 - Opportunity Creation Test (Enterprise Application to Salesforce.com)


Step 1 - Update the Test Account with a Promotion Strategy and Strategy Note
Once this change is committed, the data will be propagated back to Salesforce.com as an opportunity within 5 seconds since the default database polling configuration is used.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 46

Step 2 - Verify the Account was created in Salesforce.com

Open Salesforce.com, refresh the Account created earlier, and validate that the Opportunity has been created under Opportunities.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 47

Step 3 - Validate the Opportunity

Click on the Opportunity Name and verify the opportunity was created.

Enterprise Manager has allowed all types of SOA Composites to be viewed in the same SOA admin console.

Section 4.4 - Audit the Opportunity Creation integration within Oracle SOA Suite
Step 1 - View the SOA Composite Instances

Navigate to Enterprise Manager | SOA | soa-infra | Instances | Search listing to see that the EA Outbound and Salesforce.com Inbound SOA Composites have executed.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 48

Step 2 - View the Flow Trace

Drill into the instance id for Inbound Salesforce.com composite. Validate that all parts of the process ran successfully.

Step 3 - Verify the Login to Salesforce.com Activity


This diagram shows the session id and server URL that were generated from a successful login.

Drill into the UpdateSalesforceAccount BPEL Component. Click on Flow View | Click on the Login to Salesforce activity and verify that the session id and Server URL were returned.

Step 4 - Verify the Endpoint Reference


The partner link has been dynamically updated to route all service calls to a dynamic endpoint location during process execution.

Click on the Set Server URL activity to verify the Endpoint Reference was updated to use the Salesforce server url.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 49

Step 5 - Verify the Session Header

Select the Set Session Id activity to verify that the Salesforce session id has been passed into the session header which will be used on subsequent invokes.

Step 6 - Verify the Write Opportunity

Click on the Write Opportunity activity and validate the Opportunity has the correct information and that the result says it was created successfully.

Step 7 Verify the Query and Opportunity Returned

Click on the Query Account activity and validate the SOQL (Salesforce Object Query Language) was properly formed and returned the expected Opportunity.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 50

Only the fields requested in the query will be returned. The return value will still conform to a Salesforce.com complex type so it is easy to work with.

The Returned Opportunity:

SECTION 5 - CONCLUSION

This whitepaper has demonstrated that integrating with Salesforce.com or another SaaS solution using Oracle SOA Suite 11g is not inherently more difficult than integrating with internal applications. The business scenario chosen provides a primer on how to build inbound and outbound integrations around Salesforce.com that can be adapted to just about any project. The new features in Oracle SOA Suite 11g also facilitate the creation of a loosely coupled, application independent design.

Bridging the Gap between Internal Systems and Salesforce.com using Oracle SOA Suite 11g

Page 51

Bridging the Gap between Internal Systems and Salesforce.com with Oracle SOA Suite 11g September 2010 Author: Brian Sipsey of M&S Consulting http://www.mandsconsulting.com Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A. Worldwide Inquiries: Phone: +1.650.506.7000 Fax: +1.650.506.7200 oracle.com Copyright 2010, Oracle and/or its affiliates. All rights reserved. This document is provided for information purposes only and the contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. We specifically disclaim any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without our prior written permission. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.