Oracle Sales Cloud Web Services

November 2014

Oracle Sales Cloud Web
Services White Paper
Release 9

Copyright © 2005, 2014 Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing restrictions on use
and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license
agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit,
distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering,
disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you
find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf
of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs
installed on the hardware, and/or documentation, delivered to U.S. Government end users are “commercial
computer software” pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental
regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any
operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be
subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S.
Government.
This software or hardware is developed for general use in a variety of information management applications. It is not
developed or intended for use in any inherently dangerous applications, including applications that may create a
risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to
take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation
and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous
applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their
respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used
under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD
logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a
registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information on content, products, and
services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all
warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its
affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party
content, products, or services.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support
Oracle customers have access to electronic support through My Oracle Support. For information, visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Contents

1

Overview of Web Services ........................................................................................ 7
Sales Cloud Web Services and Integration with Sales Cloud ..................................... 7
Web Services Security ...................................................................................................... 8
Oracle/wss_username_token_over_ssl_client_policy ............................................ 8
Oracle/wss11_username_token_with_message_protection_client_policy ........ 9
Stateless Web Services and Session Management ...................................................... 9
Types of Web Services...................................................................................................... 9
Web Services Schema ................................................................................................... 10
Extract Schema and Metadata from Schema Files ............................................ 10
Web Services Operations .............................................................................................. 13

2

Getting started with Web Services......................................................................... 15
Oracle Enterprise Repository ......................................................................................... 15
Getting Started: Finding the Integration Assets You Need ................................. 16
Query Public/External Web Services in OER ......................................................... 18
Fusion Web Service Endpoint URLs ......................................................................... 19
Consuming Web Services and generation of proxy classes ..................................... 19
Authentication ................................................................................................................ 25
Web Services for Bulk Data Loads and Interactive Scenarios .................................. 27

3

Best Practices for designing client integrations .................................................... 29
Error Handling and Logging .......................................................................................... 29
Handling Outages and Failures .................................................................................... 29
Handling Multiple Concurrent Requests ...................................................................... 29
SOAP Messages need to follow WS Standards ........................................................... 30
Sort Criteria for Stateless Web Services Queries.......................................................... 30

4

Outbound Web Services ......................................................................................... 31
Defining the External Web Service ............................................................................... 32

Overview of Web Services

▪ Sales Cloud Web Services and Integration with Sales Cloud

External WSDL File Example ........................................................................................... 33
XSD File Example ............................................................................................................. 34
Outbound Web Service Authentication ...................................................................... 34
Synchronize data from On-Demand to an On-Premise System ............................... 35

5

Extensibility and Web Services ................................................................................ 37
Custom Object Web Service Endpoint URLs ............................................................... 37
Field Customizations and Dynamic WSDL generation ............................................... 38
Creating relationships between objects...................................................................... 44
Schema changes after association between objects .............................................. 45
Querying associated objects ........................................................................................ 49

Appendix 1: Extracting Oracle Public Certificate from Fusion WSDL ..................... 51
Appendix 2: Sample Payloads ..................................................................................... 53
Appendix 3: Custom Object Sample Payloads ......................................................... 55
Appendix 4: FAQs ........................................................................................................... 59
FAQs for Objects and Child Objects ............................................................................ 59
FAQs for Web Service Operations ................................................................................ 60

Glossary and References .............................................................................................. 63
Terms ................................................................................................................................. 63
Abbreviations .................................................................................................................. 64
Document References ................................................................................................... 65

Oracle Sales Cloud Web Services White Paper

5

1

Overview of Web Services

Sales Cloud Web Services and Integration with Sales Cloud
Sales Cloud web services provide access to an application programming interface (API)
that companies can use to build programs to integrate with Sales Cloud. It consists of a
set of WSDL files that describes the interface to the CRM objects. This provides a
programmatic interface for accessing your company's Sales Cloud information. A
customer application can use the WSDL files through standard web services
development tools, such as Oracle’s JDeveloper and those provided by the Oracle SOA
Suite.
The figure below shows how Fusion web services interact with the Oracle Sales Cloud
database. The customer uses web services (WSDL fields) to define the objects and
methods that are contained in Sales Cloud. The customer communicates with Sales
Cloud over the Internet. Sales Cloud web services are developed using the JAX-WS
Specification.

Figure 1: Web services communication with Sales Cloud

The web services API allows companies to build programs to integrate with Sales Cloud.
Some common examples of client integrations include the following:
• Integrations of CRM and back-office applications. You can retrieve real-time
sales and marketing information from Sales Cloud and use it in financial and
other back-office applications. For example, you can retrieve information about
recently closed opportunities through the web services interface and insert this

Overview of Web Services

•

•

▪ Web Services Security

information into an order entry system that has a web services user interface. In
addition, you can store information from back-office applications in Sales Cloud
for instant access by users, visible in custom fields.
Web-based portal applications. You can create customized web-based
applications using Active Server Pages (ASPs), Java Server Pages (JSPs), or similar
web technology that accesses Sales Cloud through the web services interface.
For example, a CRM customer can deploy a customized web form on its
corporate web site, allowing visitors to enter requests for more information. The
application creates new lead records in Sales Cloud for these requests through
the web services interface.
Custom add-on modules. Customers can also extend Sales Cloud functionality.
For example, a company can create a custom add-on module to streamline its
unique quote creation process, or a company can create additional utilities to
perform mass data cleanup operations. These modules access data in Sales
Cloud directly through the web services interface. Sales Cloud administrators
and users can run these modules while concurrently accessing the Sales Cloud
user interface.

Web Services Security
The Oracle Web Services Manager (OWSM) handles the security and management
policies for Oracle Fusion web services and is in compliance with WS Security 1.1
standards. Fusion environments support Message protection and Authentication
policies. SOAP requests from the client need to conform to one of the 2 listed policies
below.

Table 1: Web service policies
CLIENT POLICY

AUTH

AUTH

MESSAGE

MESSAGE

TRANSPORT

SOAP

PROTECTION

PROTECTION

TRANSPORT

SOAP

oracle/wss_username_token_over_ssl_client_policy

No

Yes

Yes

No

oracle/wss11_username_token_with_message_protection_client_policy

No

Yes

No

Yes

Note: Table from Oracle® Fusion Middleware Security and Administrator's Guide for Web Services 11g
Release 1 (11.1.1)

Oracle/wss_username_token_over_ssl_client_policy
This policy includes credentials in the WS-Security UsernameToken header in the SOAP
request messages. The policy verifies that the transport protocol provides SSL message
protection. Both plain text and digest mechanisms are supported. This policy can be
attached to any SOAP-based client.

This policy contains the following policy assertion:
oracle/wss_username_token_over_ssl_client_template.

Oracle/wss11_username_token_with_message_protection_client_policy
This policy provides message protection (integrity and confidentiality) and
authentication for outbound SOAP requests in accordance with the WS-Security 1.1
standard. Both plain text and digest mechanisms are supported. This policy can be
attached to any SOAP-based client. The web service consumer inserts username and
password credentials, and signs and encrypts the outgoing SOAP message. The web
service provider decrypts and verifies the message and the signature.
In order to prevent replay attacks, the assertion provides the option to include time
stamps and verification by the web service provider. The message can be protected
with ciphers of different strengths. This policy uses the symmetric key technology for
signing and encryption, and the WS-Security's Basic 128 suite of asymmetric key
technology for endorsing signatures.
This policy contains the following policy assertion:
oracle/wss11_username_token_with_message_protection_client_template.
For further information regarding the web services security policies, please refer to the
Oracle® Fusion Middleware Security and Administrator's Guide for Web Services 11g
Release 1 (11.1.1).

Stateless Web Services and Session Management
Prior to accessing the Fusion web services, user credentials should be supplied along
with any required keys in compliance with one of the above-listed security policies.
Upon successful authentication, the user is “logged” in and can issue web service
requests to access and retrieve data. All Fusion web services are stateless such that
each web service call is an atomic transaction and is not associated to a persistent
session. Management of the stateless web service calls is handled by the Fusion
framework and is abstracted from the end user.

Types of Web Services
Sales Cloud has an extensive list of available web services. These web services can be
transactional data access services and migration services.
1. Transactional data access services are services that provide access to the ADF
Business objects and provide Create, Read, Update and Delete (CRUD) operations
to these objects (e.g. Opportunity web service).
2. Migration services are used primarily for moving data from various systems into Sales
Cloud. They can be either private services used only internally or may be exposed
publicly on a case-by- case basis (e.g. Bulk import web service).
Oracle Sales Cloud Web Services White Paper

9

Overview of Web Services

▪ Web Services Schema

Web Services Schema
Fusion web services are organized in a granular fashion with schema information
abstracted from the methods/operations of the web Service. Schema file locations are
defined in the service WSDL and in the schema files themselves. The WSDL operations
and messages are stored in the WSDL file and the associated schema is stored in
separate files.
Below figure shows how the Opportunity web Service is organized into a WSDL and
associated schema files.

Figure 2: Opportunity web service, WSDL and schema files

Extract Schema and Metadata from Schema Files
The schema (XSD) files provide information about the object schema. The object
schema files are organized into parent object and child object schema files. The highest
level parent object schema files are referenced in the service WSDL and their
downloadable location is provided. Child schema files are referenced in parent schema
files, and their downloadable location is provided.

Listed below is an example of the schema information which will be available in the XSD
files. The schema information is extracted from the Opportunity XSD file.
1. <xsd:element minOccurs="0" name="AssignmentLock" type="xsd:string" />
Field name = AssignmentLock
Data type = String
minOccurs = 0 (Indicates if the field is required or not required. minOccurs set
to 0 indicates that the field is not required and minOccurs set to 1 indicates
that the field is required)
2. <xsd:element minOccurs="0" name="BudgetAvailableDate" nillable="true"
type="ns0:date-Date" />
•
•
•

•
•
•

Field name = BudgetAvailableDate
Data type = Date
MinOccurs = 0 (Indicates that the field is not required)

•

Nillable = True (can hold a null value)

3. <xsd:element maxOccurs="unbounded" minOccurs="0" name="RevenueTerritory"
type="ns1:RevenueTerritory" />
•
•

Field name = RevenueTerritory
Data Type = RevenueTerritory (Child object)

•
•

minOccurs = 0 (Indicates that the field is not required)
maxOccurs = unbounded (Indicates max number of times this field can occur
in the soap request. For Example, more than 1 RevenueTerritory child can be
associated to Opportunity as a 1: M relationship). The RevenueTerritory child
object schema is available in the RevenueTerritory schema file.

In order to obtain the complete object schema, the parent and child schema files can
be manually or programmatically introspected. Listed below are steps to extract the
schema information.
1. The schema file with the same ending name as the web Service should be read first.
For Example: open file OpportunityService_XSD_Opportunity.xsd in order to read the
Opportunity object schema.
2. Navigate to xsd:element node in the schema file and extract the metadata name
values pairs from the xsd:element node. For Example: <xsd:element minOccurs="0"
name="AssignmentLock" type="xsd:string" />
3. Store the metadata information in a flat file or database table
4. Repeat until all xsd:elements nodes are navigated to and metadata information is
extracted.
5. If the xsd:element node contains a reference to a child object, open the schema file
for the child object and repeat the above process in order to read and extract all
the metadata for the child object. For Example: If type = sdo:DataObject, then
element refers to a child object. <xsd:element name="OpportunityContact"
type="OpportunityContact" minOccurs="0" maxOccurs="unbounded"

Oracle Sales Cloud Web Services White Paper

11

Overview of Web Services

▪ Web Services Schema

sdoXML:dataType="sdo:DataObject"/> Open child object schema file
OpportunityService_XSD_OpportunityContact.xsd
6. Repeat above process until all xsd:element nodes in the child object schema files
have been navigated to and metadata information is extracted.

Figure 3: List of Opportunity schema files generated during WS proxy creation

Note: The schema files are automatically downloaded during web service proxy generation. The
schema files can be manually or programmatically introspected only if object metadata information
needs to be determined.

Web Services Operations
Each object web Service has a set of key CRUD operations which enable querying,
data creation and retrieval. Listed below are the CRUD Operations supported by web
services.
Table 2: WS CRUD operations
OPERATIO
N Type

OPERATION name

Description

Create

Createobjectname

Creates a single record along with
associated child records

Get

Getobjectname

Retrieves single record information by
Primary key (for example, Opportunity
ID)

Find

Findobjectname

Finds and returns a list of rows based
on the selected query statement

Update

Updateobjectname

Updates a single row

Merge

Mergeobjectname

Updates a row if one exists; otherwise,
creates a new one

Delete

Deleteobjectname

Deletes a single row

Delete

Deletechildobjectnam
e

Deletes associated child objects

Process

processobjectname

Performs a Create, Update, Delete, or
Merge operation on a list of rows.
The specified operation is applied to
all rows in the given list.

Process
Change
Summary

processCSobjectname

Performs a Create, Update, or Delete
operation on a list of rows.
Different operations may be applied
to different rows

Oracle Sales Cloud Web Services White Paper

13

Overview of Web Services

▪ Web Services Operations

2

Getting started with Web Services

Oracle Enterprise Repository
The Oracle Enterprise Repository (OER) is a portal for all Fusion product assets including
Sales Cloud web services with metadata documentation.
OER can be accessed by navigating to http://fusionappsoer.oracle.com and users can
login using any Oracle.com account like OTN or Support. If users do not have an
Oracle.com account, new accounts can be created from the OER access page.
The following types of assets can be accessed in the repository:
1. ADF Business Components services
2. ADF Business Components service data objects
3. SOA composites
4. SOA composite services
The Sales Cloud web services are ADF Business Components services and can be
accessed using the Fusion Logical Business Object or Fusion Logical Business Area
category. The figure below depicts the OER homepage.

Figure 4: OER Homepage

Oracle Sales Cloud Web Services White Paper

15

Contents

Getting Started: Finding the Integration Assets You Need
Following are some tips to get started using the Oracle Enterprise Repository:
If you know what business object you are interested in, enter that value in the Enter
Search String field to display all of the assets related to that object. For example, if you
want to find all assets related to an Opportunity you would enter Opportunity in the Enter
Search String field.

If you want to see a specific type of integration asset, such as all of the ADF Services,
choose one of the Oracle Fusion Application types in the Type field.

If you want to see assets by different categories, use the Browse option. Some of the
most useful categories for Fusion Applications Assets are:
1. Logical business areas
2. Logical business objects
3. Oracle coexistence scenarios

In the search results, view the name, version, type, and status for each asset type.

16

Oracle Sales Cloud Web Services White Paper

▪

Getting started with Web Services Oracle Enterprise Repository

Figure 5: OER search using browse assets

Select the asset to view the service overview and other information such as details,
taxonomy and usage. In the example below, the asset selected is Opportunity Service.
Details of the various methods/operations, parameters, taxonomy, logical business area,
etc., of the service is documented and can be viewed. In the detail tab is a service
WSDL URL and an abstract WSDL URL. The service WSDL URL can be modified to obtain
the endpoint URL for the service by replacing the first part of the URL
rep://FUSIONAPPS_CRM/ with customer specific hostname. For example: https://fusionabc.us.oracle.com

Figure 6: OER search using Fusion Logical Business Object

Oracle Sales Cloud Web Services White Paper

17

Contents

Note: OER currently is used for documenting the Fusion web services. In order to access a specific web
service, it is recommended that the endpoint URL of the required web service points to a Sales Cloud
instance. For more information about OER please refer to the whitepaper on OER.

Query Public/External Web Services in OER
External web services are services which can be called from outside the company
intranet or firewall. All other services can be used for integration projects inside the
firewall or can be extended to attach an appropriate security policy such that they can
be called from outside the firewall. The list of public or external web services can be
viewed in OER. The following search criteria lists all public or external web services.
• Select More Search Options
•
•

Set Type as ADF Service
Select Filter By Additional Criteria

•
•

Set field to Keywords
Set Keywords to Equal “EXTERNAL” and click the add button

The query should return a list of all public or external web services

Figure 7: Query External/Public Web Services in OER

18

Oracle Sales Cloud Web Services White Paper

▪

Getting started with Web Services Consuming Web Services and generation of proxy
classes

Fusion Web Service Endpoint URLs
This chapter provides additional details regarding endpoint URLs for certain common
web services. The Fusion WSDLs are specific to the Fusion environment and can be
accessed by providing the customer’s Fusion environment and the specific web service
path.
1. Fusion WSDL URL: <Hostname><ContextRoot>/<ServiceName>
For Example: hostname : https://secure-aufsn4abc.oracle.com

Table 3: WS WSDL URL example
web
service

HOST NAME

Context Root

fusion wsdl URL

Lead
Service

https://secur
eaufsn4abc.or
acle.com

mklLeads

https://secureaufsn4abc.oracle.com
/mklLeads/LeadService?WS
DL

Opportun
ity
Service

https://secur
eaufsn4abc.or
acle.com

opptyMgmtOpportunities

https://secureaufsn4abc.oracle.com
/opptyMgmtOpportunities/
OpportunityService?WSDL

Campaig
n
Service

https://secur
eaufsn4abc.or
acle.com

mktDialogs

https://secureaufsn4abc.oracle.com
/mktDialogs/CampaignSer
vice?WSDL

Customer
AccountS
ervice

https://secur
eaufsn4abc.or
acle.com

foundationParties

https://secureaufsn4abc.oracle.com
/foundationParties/Custom
erAccountService?WSDL

Consuming Web Services and generation of proxy classes
Client integration applications can be developed after generating proxy classes from
the CRM web services. Any IDE which supports the SOAP standards and conforms to WS
Security 1.1 policies can be used as a development platform.

To generate proxy classes using Oracle’s JDeveloper 11g:

1. Create a generic application using Oracle JDeveloper 11g
Oracle Sales Cloud Web Services White Paper

19

Contents

2. In order to add a web service proxy to the project, select the project and click Add
Select web services under Business Tier and select web Service Proxy

Figure 8: WS Proxy - Start
3. A web service proxy generation wizard is launched. Click Next to step through the
wizard.
4. Specify a JAX-WS client style

20

Oracle Sales Cloud Web Services White Paper

▪

Getting started with Web Services Consuming Web Services and generation of proxy
classes

Figure 9: WS proxy -- JAX WS style
5. Specify the location of the WSDL file. For e.g. The WSDL Document URL in the screen
below points to the CampaignService.wsdl file

Oracle Sales Cloud Web Services White Paper

21

Contents

Figure 10: WS proxy -- WSDL location

If you want to generate JAX-WS web service proxy for Resource Service, then you must create custom
binding files.

To generate a custom binding file:

1. Create a custom binding file for JAX-WS as follows, and replace <local> and <port>
in schemaLocation with appropriate values.
<jxb:bindings version="1.0" xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<jxb:bindings
schemaLocation="http://<localhost>:<port>/foundationResources/ResourceServ
ice?XSD=/oracle/apps/cdm/foundation/resources/resourceService/ResourcePrim
aryOrganization.xsd">
<jxb:bindings node="//xsd:element[@name='resourcePrimaryOrganization']">
<jxb:class name="ResourcePrimaryOrg"/>
</jxb:bindings>
</jxb:bindings>
</jxb:bindings>

2. Click Binding Files to add the CustomBinding.xml file and click OK.
3. Click next and specify a name for the root package (examples include com, org,
application name)

22

Oracle Sales Cloud Web Services White Paper

▪

Getting started with Web Services Consuming Web Services and generation of proxy
classes

4. Follow the remaining steps in the wizard. Fusion WSDLs contain both synchronous and
asynchronous methods and generation of the asynchronous methods can be turned
off.
5. The wizard provides the ability to configure OWSM policies. Do not select any policies
at this time. The security policies can be added in the authentication code.

Figure 11: WS proxy -- OWSM policies
6. Click Finish to complete the wizard and the proxy classes are generated.

Oracle Sales Cloud Web Services White Paper

23

Contents

Figure 12: WS proxy -- finish generation
7. Once the proxy classes are successfully generated, the
<objectname>ServiceSOAPHttpPortClient class can be used to test the generated
proxy.

24

Oracle Sales Cloud Web Services White Paper

▪

Getting started with Web Services Authentication

Figure 13: WS proxy -- testing

Authentication
In order to authenticate to the Sales Cloud application, one of the 2 security policies
listed below have to be adhered to. The policies are managed by Oracle Web Services
Manager.
•

oracle/wss_username_token_over_ssl_client_policy

This policy includes credentials in the WS-Security UsernameToken header in the SOAP
request messages. The plain text mechanism is supported. The policy uses SSL for
achieving transport layer security.
The following is an example of an authentication mechanism to Sales Cloud. This is a
code snippet written in the Java programming language, demonstrating the
authentication code to login to a Fusion environment using the username token over SSL
policy. In order for this code snippet to run, the OWSM agent should be present and
running. In this approach the OWSM agent is embedded in webLogic 11g or
JDeveloper 11g.

Oracle Sales Cloud Web Services White Paper

25

Contents

Figure 14: Authentication - Username token over SSL
•

oracle/wss11_username_token_with_message_protection_client_policy

The username_token_message_protection policy requires that the public Oracle
certificate (Service Public key) is referenced by the client as rcpt-key alias.
•

rcpt-key-alias : Service Public key
Encrypting symmetric key which is used for SAML+Body signature/encryption

One approach is to leverage the OWSM agent. In such an approach, a keystore needs
to be generated by the client and stored on the client machine. A keystore holds the
user alias, the appropriate keys and its corresponding values which are required in order
to authenticate to the Fusion environment.
The public Oracle certificate file can be obtained from the Fusion WSDL and can be
imported to the keystore under the rcpt-key-alias. The Oracle certificate file can be
imported to the keystore using the keytool commands listed below.
1. Import Oracle certificate to a keystore file
keytool -importcert -alias nameoforaclekey -file
oraclecertificatefile.cer -keystore oracle-keystore.jks -storepass
keystorepassword

2. List the contents of a keystore
keytool -list -keystore ".oracle-keystore.jks"

The client should store the keystore file to their local machine and reference the keystore
file in their client application in order to authenticate to the Fusion environment.
The following is an example of an authentication mechanism to Sales Cloud. This is a
code snippet written in the Java programming language, demonstrating the
authentication code to login to a Fusion environment using the username token with
message protection policy. In order for this code snippet to run, the OWSM agent should
be present and running. In this approach the OWSM agent is embedded in webLogic
11g or JDeveloper 11g.

26

Oracle Sales Cloud Web Services White Paper

▪

Getting started with Web Services Web Services for Bulk Data Loads and Interactive
Scenarios

Figure 15: Authentication -- Username token and message protection
Note: The above examples represent a single approach to authenticate to Sales Cloud web services
using Java as the programming language and JDeveloper 11g as the IDE. Any development platform
which complies with WS Security policies 1.1 can be used to authenticate to Sales Cloud web services.

For further information regarding extracting Oracle public certificate from a Fusion
WSDL, please refer to Appendix 1: Extracting Oracle Public Certificate from Fusion WSDL

Web Services for Bulk Data Loads and Interactive Scenarios
Stateless web services are atomic transactions which do not require the client or partner
application to maintain a unique identifier across multiple requests. In Stateless web
services, session management is managed by the server and is abstracted from the
client. Listed below are a couple of sample use cases using stateless web services.
Example 1: Interactive Use case

1. The customer or partner requires multiple users to authenticate to Sales Cloud. After
authentication, users insert or update existing Leads and logoff.
2. The stateless approach is ideal in this scenario as the user's credentials are supplied
with each web Service request, eliminating the need for the login request to

Oracle Sales Cloud Web Services White Paper

27

Contents

establish an explicit session. The users are logged in concurrently, make changes,
and logoff. There is no need to manage sessions or implement session pooling on the
client side as all transactions are stateless.

Example 2: Bulk Data Load Use Case

1. The customer or partner loads over 50,000 opportunities to the Sales Cloud system.
The data load consists of inserts and updates and occurs nightly as a batch process.
2. Stateless web services can be used effectively in bulk data load scenarios. Each
transaction is atomic and the client application can invoke multiple web Service
transactions to load data in a batch process. However since each transaction is
stateless, bulk data load scenarios involving query of large data volumes prior to
data inserts or updates require special consideration.
Each query operation and the subsequent paging operations is a stateless transaction.
The result set returned is dynamic and recent inserts and updates can be returned in the
result set. Also, records which have been deleted will no longer appear in the result set.
Applications should be designed with this behavior in mind, ensuring that the query is
always sorted on an ID field and construct optimal queries with specific query criteria to
reduce the size of the result set.

28

Oracle Sales Cloud Web Services White Paper

3

Best Practices for designing
client integrations

Error Handling and Logging
Error handling and logging are essential when developing a client application and can
assist in troubleshooting authentication and data validation issues. The client application
must provide for:
1. Logging of detailed information about the error observed.
2. Logging of the body and header information of all SOAP requests and responses. The
actual SOAP request can be extremely useful in identifying the root cause of a
problem.
3. A call stack, which can be extremely important when analyzing problems and can
provide useful hints that may reveal contributing factors to the problem.
4. Entry points wrapped in log messages. The ability to identify entry and exit of web
service calls is important when analyzing issues.
5. If a web service request returns an error, the ability to analyze the result, stop
immediately, or continue depending on the severity of the issue reported.
6. End point URLs that are not hard-coded.

Handling Outages and Failures
When accessing a SaaS instance of Sales Cloud, the client application should have
adequate mechanisms and checks to determine when the Fusion environment is not
available and be able to either persist or shutdown depending on the usage scenario.
Listed below are a couple of recommendations
1. A process can become dormant if it receives a “Server is unavailable” error message
and retry after several minutes.
2. A process can alert an administrator and shut down after x failed attempts.

Handling Multiple Concurrent Requests
In a SaaS deployment, governors that would limit the number of requests per tenant
may be deployed in order to ensure optimal usage of resources. If you send multiple
concurrent requests, and if you receive a RIP_WAIT error, or server unavailable error, the
server might be busy due to the number of concurrent requests it is handling. If this
happens retry with an exponential back off. The client can be implemented such that

Oracle Sales Cloud Web Services White Paper

29

Contents

retries are issued automatically using an exponential retry rate (that is, retries occur
after 100ms, 200ms, 400ms, 1600ms and so on).

SOAP Messages need to follow WS Standards
All web service requests should comply with WS Security 1.1 standards in order to
successfully authenticate and execute the web Service transaction. There is no
recommended IDE or programming language to design and develop client
integrations, however Any IDE or programming language that supports WS-Security
standards can be used to design and develop client integrations. The development
platform should support and comply with the web services standards.

Sort Criteria for Stateless Web Services Queries
Sales Cloud web services supports Stateless transactions. Stateless web services use
server resources more efficiently and reduce the cost of implementation as customers
do not need to manage sessions or implement session pooling in the client applications.
If the QueryPage method is used as a stateless transaction, each request for an
additional page of data returns any records that have been added or updated since
the initial query. Any records that have been deleted since the first request will no longer
appear in the result set. Here are a few recommendations to accommodate this
behavior.
1. Try to avoid paging if possible
2. Construct queries with specific criteria to reduce the size of the result set
3. Use sort criteria on the Id field or created date, which helps in most simple cases

30

Oracle Sales Cloud Web Services White Paper

4

Outbound Web Services

This chapter provides information on Outbound web services. One of the ways
outbound web services can be invoked is from Fusion Object Workflows. For more
information about CRM Application Composer and Object Workflow please refer to the
CRM Extensibility Guide.
Fusion Object Workflows provide an easy configuration interface for CRM applications
to automate commonly used business processes to improve the efficiency of the
customer sales force.
Fusion Object Workflows support the following 2 trigger points:
•
•

When a record is created
When a record is updated

In response to the trigger points, the following trigger actions can be configured:
4. Send Email
5. Create a Task
6. Update fields on the associated object or its child objects
7. Call an external web service
8. Call an approval process flow built with BPM Process Composer
To call an external web service, create an object workflow and select outbound
message as the event action. Provide a name, description and the endpoint URL of the
external Web service.
At runtime, a service data object containing details of the object on which the object
workflow is defined is sent to the specified endpoint URL. For example, you can define
an object workflow that automatically sends, based on a trigger, an outbound message
containing an object like opportunity, lead, or account details from one system to
another.
To define an outbound message action, the following attributes need to be specified:
1. Name – standard attribute for each action
2. Description – standard attribute for each action
3. End Point URL – URL to access the external service

Oracle Sales Cloud Web Services White Paper

31

Contents

Once a message is defined, it can be associated to an Object Workflow. When Object
Workflow is triggered, the modified data object is applied to the message, and the
message is sent out to the specified service.

Figure 16: Outbound web service setup

Defining the External Web Service
You can configure an object workflow to send an outbound message to a third-party
web service at a specified endpoint URL. An endpoint URL is an external web service
that shares data with Oracle Sales Cloud. The third-party web service is required to
conform to the OutboundMessageService WSDL defined by Sales Cloud.
To configure a web service, you must replace the parameters in the
OutboundMessageService.xsd file using the instructions provided below.
Navigate to Oracle Enterprise Repository (OER):

1. For a standard object, search for ADF Service in OER by object name. For custom
objects, search for the generic web service for all custom objects in the
corresponding application, for example, Sales Custom Business Object.
2. Extract the object schema (.xsd) files from the live environment URL using the
information provided under the object’s web service.
3. Replace the parameters in OutboundMessageService.xsd with the names for the
object of your interest.

32

Oracle Sales Cloud Web Services White Paper

▪

Outbound Web Services External WSDL File Example

The parameters are marked in the OutboundMessageService.xsd file as parameters,
$OBJECT_TARGET_NAMESPACE$ and $OBJECT_NAME$.

External WSDL File Example
The external web service should comply with the OutboundMessageService.wsdl. The
OutboundMessageService.wsdl references the OutboundMessageService.xsd schema
file.

Oracle Sales Cloud Web Services White Paper

33

Contents

Figure 17: Outbound message WSDL

XSD File Example
The parameters marked in the xsd file should be replaced by the specified object name
and namespace

Figure 18: Outbound message schema
For more details regarding the Outbound message WSDL and Outbound message
schema files please refer to the Sales Cloud implementation guide.

Outbound Web Service Authentication
The object workflow outbound messages can use either an authentication-only client
side security policy or a transport-level security policy that can protect the message
during transfer.
The default authentication-only policy used by object workflow outbound message is
oracle/wss10_saml_token_client_policy, which includes security assertion mark up
language (SAML) tokens in outbound simple object access protocol (SOAP) request
messages. This policy should only be used when the target external web service is
located within a secure network segment. The corresponding external service can use
any compatible service policy, such as oracle/wss10_saml_token_service_policy or
oracle/wss_saml_or_username_token_service.
If the target external services are outside customer firewalls, the transport level security
policy used by outbound web service is the
oracle/wss_username_token_over_ssl_client_policy with one-way SSL enabled security
policy. The corresponding external service must use the compatible
oracle/wss_saml_or_username_token_over_ssl_service_policy service policy.
34

Oracle Sales Cloud Web Services White Paper

▪

Outbound Web Services Synchronize data from On-Demand to an On-Premise System

In order to modify the security policy on the outbound web service, please contact
Sales Cloud support. For more information about Fusion Web service configuration and
security, see the Oracle Fusion Middleware Security and Administrator's Guide for Web
Services.

Synchronize data from On-Demand to an On-Premise System
A sample use case for outbound web services is synchronizing data between an OnDemand and On-Premise application. When records are created, updated, or deleted
in the On Demand system, customers may want to track the changes and update the
On Premise system accordingly. This allows the On Premise application users to
seamlessly manage records entered from On Demand. For example, On Demand
customers can make changes to Opportunities and the changes should be propagated
to the On Premise system.
In order to meet this use case, Object Workflows can be configured to send an
outbound message to the external endpoint when a Service Request record is created
or updated.
Using Object Workflow Triggers and Outbound messaging the On Demand and On
Premise systems can be in sync and data changes in On Demand system can be
updated to the On Premise system.

Oracle Sales Cloud Web Services White Paper

35

5

Extensibility and Web Services

This chapter provides information on accessing custom objects using Sales Cloud web
services
Custom objects can be accessed using a generic Custom Object web service. The web
service contains generic operations to which the custom object is passed as a
parameter. This ensures that the web Service does not change as custom objects are
added or modified.
Here is a summary of the operations available in the generic custom object web Service:

4. getEntity(ObjectName);
5. findEntity(FindCriteria, FindControl, ObjectName);
6. SDODataObject createEntity( Object, ObjectName );
7. SDODataObject updateEntity(Object, ObjectName );
8. SDODataObject mergeEntity(Object, ObjectName );
9. deleteEntity(Object, ObjectName);
For more details about custom objects and operations, please refer to the Oracle
Enterprise Repository and the CRM Extensibility guide.

NOTE: Schema of child custom objects is included in the parent custom object schema file. Web
Service access to the child custom objects can be only via the parent custom object.

Custom Object Web Service Endpoint URLs
Custom Object WSDLs can be accessed similar to the other standard object web
services. The Fusion Custom Object WSDLs are specific to the Fusion environment and
can be accessed by providing the customer’s Fusion environment root context and the
specific Custom Object web Service path.
Fusion Custom Object WSDL URL: <Hostname><ContextRoot>/<ServiceName>
For Example:
Hostname: https://secure-aufsn4abc.oracle.com
ContextRoot: opptyMgmtExtensibility
Sales Custom Object service name: SalesCustomObjectService
Sales Custom Object WSDL URL:
https://secureaufsn4abc.oracle.com/opptyMgmtExtensibility/SalesCustomObjectService

Oracle Sales Cloud Web Services White Paper

37

Contents

Table 4: Custom WSDL URL
web service

Host Name

Context Root

Custom wsdl URL

CRMCommo
nService

https://secur
eaufsn4abc.or
acle.com

foundationCustExtn

https://secureaufsn4abc.oracle.com/
foundationCustExtn /

SalesCustom
ObjectServic
e

https://secur
eaufsn4abc.or
acle.com

opptyMgmtExtensibi
lity

https://secureaufsn4abc.oracle.com/
opptyMgmtExtensibility/
SalesCustomObjectService

CustomerCe
nterCustom
ObjectServic
e

https://secur
eaufsn4abc.or
acle.com

crmCommonCustExt
n

https://secureaufsn4abc.oracle.com /
crmCommonCustExtn /
CustomerCenterCustomObject
Service

MarketingCu
stom

https://secur
eaufsn4abc.or
acle.com

mktExtensibility

https://secureaufsn4abc.oracle.com /
mktExtensibility/
MarketingCustomObjectServic
e

ObjectServic
e

CrmCommonReferenceServic
e

Field Customizations and Dynamic WSDL generation
Field customizations made to standard or custom objects are automatically updated in
the object schema files. An admin user makes changes to either a standard or custom
object in CRM Application Composer. The schema files for the relevant objects are
dynamically updated. In order to access the field changes, the user will need to regenerate the proxy classes corresponding to the schema files.
Example 1: A standard out of the box department object is modified in CRM Application
Composer. A custom field is added to the department object.

38

Oracle Sales Cloud Web Services White Paper

▪

Extensibility and Web Services Field Customizations and Dynamic WSDL generation

Figure 19: Department XSD before customizations

Figure 20: Department XSD after customizations

Oracle Sales Cloud Web Services White Paper

39

Contents

Figure 21: Soap request before customization

Figure 22: Soap response before customization

40

Oracle Sales Cloud Web Services White Paper

▪

Extensibility and Web Services Field Customizations and Dynamic WSDL generation

Figure 23: Soap request after customization

Figure 24: Soap response after customization

Example 2: A custom object is modified in CRM Application Composer. A custom field is
added to the custom object. The schema files for the custom object before and after
the changes are shown below.

Oracle Sales Cloud Web Services White Paper

41

Contents

Figure 25: Custom object XSD before customization

Figure 26: Custom object XSD after customization

Figure 27: Soap request before customization

42

Oracle Sales Cloud Web Services White Paper

▪

Extensibility and Web Services Field Customizations and Dynamic WSDL generation

Figure 28: Soap response before customization

Figure 29: Soap request after customization

Figure 30: Soap response after customization

Oracle Sales Cloud Web Services White Paper

43

Contents

Creating relationships between objects
Relationships can be created between standard and custom objects using CRM
Application Composer. Administrators can create two types of 1:M relationships across
objects.
•
•

1:M Parent child relationships
1:M Reference relationships

There are 2 differences between parent-child and a 1:M reference relationship.
•

•

In a parent-child relationship, when the parent is deleted, all associated child
objects are also deleted automatically. In the case in a 1:M reference relationship,
deleting the source object does not automatically delete the associated M target
objects.
In a parent-child relationship, the child schema is included in the parent object
schema. However in a 1:M relationship, the schema of the target object is not
included in the source object’s schema.

Table 5: Relationships Between Objects

44

Object

Object

Relations
hip
Type

Schema
included

Foreign key
on M/Child object

Standard
object
Departme
nt

Standard
object
Contact

Parent Child

Contact schema
included in
Department
schema

Department ID
available in Contact
schema

Standard
object
Departme
nt

Custom
Object

Parent –
Child

Employee schema
included in
Department
schema

Department ID
available in Employee
schema

Standard
object
Departme
nt

Standard
object
Contact

1:M
Referenc
e

Contact schema is
NOT included in
Department
schema

Department ID
available in Contact
schema

Standard
object

Custom
Object

1:M
Referenc

Employee schema is
NOT included in

Department ID
available in Employee

Employee

Oracle Sales Cloud Web Services White Paper

▪

Extensibility and Web Services Schema changes after association between objects

Object

Object

Relations
hip
Type

Schema
included

Foreign key
on M/Child object

Departme
nt

Employee

e

Department
schema

schema

Custom
object
Project

Standard
object
Contact

Parent Child

Contact schema
included in Project
schema

Project ID available in
Contact schema

Custom
object
Project

Custom
Object

Parent Child

Employee schema
included in Project
schema

Project ID available in
Employee schema

Custom
object
Project

Standard
object
Contact

1:M
Referenc
e

Contact schema is
NOT included in
Project schema

Project ID available in
Contact schema

Custom
object
Project

Custom
Object

1:M
Referenc
e

Employee schema is
NOT included in
Project schema

Project ID available in
Employee schema

Employee

Employee

NOTE: The above examples illustrate the impact on schema change when relationships are created.
These relationships are not available out of the box.

Schema changes after association between objects
Example 1: Here is an illustration of the changes seen when a 1:M parent child
relationship is created between two custom objects.
Parent Object: BenTopLvl110601_1. The schema file is modified to include references to
the child custom object BenTopLvl110601_1Child1.
Child Object: BenTopLvl110601_1Child1. Schema file of child custom object
BenTopLvl110601_1Child1 includes a foreign key reference to the parent object
BenTopLvl110601_1

Oracle Sales Cloud Web Services White Paper

45

Contents

Figure 31: Modified schema of BenTopLvl110601_1 object

46

Oracle Sales Cloud Web Services White Paper

▪

Extensibility and Web Services Schema changes after association between objects

Figure 32: Modified schema of child BenTopLvl110601_1Child1

Example 2: Here is an illustration of the changes seen when a 1:M reference relationship
is created between two custom objects.
Source Object: BenTopLvl110601_1. Schema of source object is unchanged and is not
modified to include the schema reference of the target object.
Target Object: BenTopLvl110601_2. Schema of target object is modified to include the
foreign key reference to the source

Oracle Sales Cloud Web Services White Paper

47

Contents

Figure 33: Schema of source object

Figure 34: Modified schema of target object

48

Oracle Sales Cloud Web Services White Paper

▪

Extensibility and Web Services Querying associated objects

Querying associated objects
Querying across a parent child relationship can be either via the parent or the child
object. Querying a parent will retrieve all associated child objects. Querying a child
object, will retrieve the associated parent Ids. Querying across a reference relationship
can be only via the target object. Querying a target object will retrieve the foreign key
reference to the source object, which is the associated source object Id.

Table 6: Querying Across Relationships
Relationshi
p

Query

Result

ParentChild

•

Query via
Parent

•

Querying a parent will retrieve all associated
child objects

•

Query via
Child

•

Querying a child object, will retrieve the
associated parent Ids.

Reference
(1:M)

Query via
target object

Querying a target object will retrieve the
associated source object Ids.

Oracle Sales Cloud Web Services White Paper

49

Appendix 1: Extracting Oracle Public
Certificate from Fusion WSDL

This is a sample certificate and the sections below illustrate how to extract the certificate
from a WSDL and add to a keystore. The actual Oracle public certificate should be
extracted from a Fusion WSDL.
In the Fusion WSDL, the encrypted certificate is stored in the following format:
<dsig:X509Certificate>MIICCzCCAXSgAwIBAgIETf8ZWjANBgkqhkiG9w0BAQUFADBKMRMw
EQYKCZImiZPyLGQBGRYDY29tMSEwHwYKCZImiZPyLGQBGRYRb3JhY2xlb3V0c291cmNpbmcxED
AOBgNVBAMTB3NlcnZpY2UwHhcNMTEwNjIwMDk1NjQyWhcNMTExMjE3MDk1NjQyWjBKMRMwEQYK
CZImiZPyLGQBGRYDY29tMSEwHwYKCZImiZPyLGQBGRYRb3JhY2xlb3V0c291cmNpbmcxEDAOBg
NVBAMTB3NlcnZpY2UwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJJsUQQHiE9qlTlv3n1j
P3JhepkAwsxXsy5+DMifv2ZbB2haoCcJ319Nx06tg67QyS5E79iAs3rLE5W/2rEKXmWjJ74whX
0gJho+a+33EMLDuejehtx1d726CoYIvTpGl+6C+QH1R3N1MIEFWk0JuLod5YFgEXgXhNQuEFXz
3UIbAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAGYQX4MKfFlwO1TuKpjtABEwveZKpyIvkfdCcqv
ZVpdIb7rNyCeVWOuSlpldgEQ4lUYo29IrFf50z/Rbuz4tu3JT8uB2cpRpX9GDUKq5MTx6efVUV
H9EGK0sZZ8NbX2aeAlOq02Wau2T0og5IxID7KPcCU1qiRV0WA3ebd15vODk=</dsig:X509Cer
tificate>

Copy the encrypted text to a text editor and remove the <dsig:X509Certificate> and
</dsig:X509Certificate> tags. Add the following lines before and after the encrypted
text.
-----BEGIN CERTIFICATE----MIICCzCCAXSgAwIBAgIETf8ZWjANBgkqhkiG9w0BAQUFADBKMRMwEQYKCZImiZPyLGQBGRYDY2
9tMSEwHwYKCZImiZPyLGQBGRYRb3JhY2xlb3V0c291cmNpbmcxEDAOBgNVBAMTB3NlcnZpY2Uw
HhcNMTEwNjIwMDk1NjQyWhcNMTExMjE3MDk1NjQyWjBKMRMwEQYKCZImiZPyLGQBGRYDY29tMS
EwHwYKCZImiZPyLGQBGRYRb3JhY2xlb3V0c291cmNpbmcxEDAOBgNVBAMTB3NlcnZpY2UwgZ8w
DQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJJsUQQHiE9qlTlv3n1jP3JhepkAwsxXsy5+DMifv2
ZbB2haoCcJ319Nx06tg67QyS5E79iAs3rLE5W/2rEKXmWjJ74whX0gJho+a+33EMLDuejehtx1
d726CoYIvTpGl+6C+QH1R3N1MIEFWk0JuLod5YFgEXgXhNQuEFXz3UIbAgMBAAEwDQYJKoZIhv
cNAQEFBQADgYEAGYQX4MKfFlwO1TuKpjtABEwveZKpyIvkfdCcqvZVpdIb7rNyCeVWOuSlpldg
EQ4lUYo29IrFf50z/Rbuz4tu3JT8uB2cpRpX9GDUKq5MTx6efVUVH9EGK0sZZ8NbX2aeAlOq02
Wau2T0og5IxID7KPcCU1qiRV0WA3ebd15vODk=
-----END CERTIFICATE----

Save the file as yourcert.crt. The certificate can now be imported to the keystore under
the rcpt-key-alias.
The Oracle certificate file can be imported to the keystore using the keytool commands
listed below.
•

Import Oracle certificate to a keystore file
keytool -importcert -alias nameoforaclekey -file
oraclecertificatefile.cer -keystore oracle-keystore.jks -storepass
keystorepassword

Oracle Sales Cloud Web Services White Paper

51

Contents

•

List the contents of a keystore
keytool -list -keystore "oracle-keystore.jks"

The client can save the keystore file to their local machine and reference the keystore
file in their client application to authenticate to the Fusion environment.

52

Oracle Sales Cloud Web Services White Paper

Appendix 2: Sample Payloads

Listed below are sample payloads for some of the commonly used web services
operations on standard objects and custom objects.

Figure 35: Get custom object with security header request

Figure 36: Get custom object response

Oracle Sales Cloud Web Services White Paper

53

Contents

Figure 37: Create opportunity request

Figure 38: Get opportunity request

54

Oracle Sales Cloud Web Services White Paper

Appendix 3: Custom Object
Sample Payloads

Listed below are sample payloads for some of the commonly used web services
operations on Custom Objects created using CRM Application Composer.

Figure 39: Get entity request

Figure 40: Get entity response

Figure 41: Find entity request

Oracle Sales Cloud Web Services White Paper

55

Contents

Figure 42: Find entity response

Figure 43: Create entity request

Figure 44: Create entity response

56

Oracle Sales Cloud Web Services White Paper

▪

Appendix 3: Custom Object Sample Payloads Querying associated objects

Figure 45: Update entity request

Figure 46: Update entity response

Figure 47: Merge Entity Request

Oracle Sales Cloud Web Services White Paper

57

Contents

Figure 48: Merge Entity Response

Figure 49: Delete entity request

Figure 50: Delete entity response

58

Oracle Sales Cloud Web Services White Paper

Appendix 4: FAQs

The following sections list the frequently asked questions regarding web services, order
by the area.

FAQs for Objects and Child Objects
How you would apply a filter by child data?

A filter needs to be defined on FindCriteria and/or ChildFindCriteria. A filter is a View
Criteria. This View Criteria can further reference a ViewCriteriaGroup and
ViewCriteriaItem. The ViewCriteriaItem contains conjunction, attributes and operators to
set values for filtering a query. ChildFindCriteria also has the ability to define a full filter
(using childFindCriteria.filter).
There are two kinds of filtering that can be applied related to child data:
•

•

Type 1: filtering the set of parent objects that are retrieved based on attributes of the
child. For example, show me all leads that have a MklLeadResources child object
with MklLeadResources.ResourceId = '12345'. Type 1 is accomplished using nested
criteria in the main findCriteria.
Type 2: filtering the set of child objects that are retrieved based on attributes of the
child. e.g. for the leads in the result set, only show MklLeadResources child objects
having MklLeadResources.ResourceID='12345'. Type 2 is accomplished using
ChildFindCriteria.
NOTE: You might want to do both, and can include both a nested FindCriteria and a
ChildFindCriteria.

As a quick example to clarify, imagine that you have three Lead records (Lead1, Lead2,
and Lead3), and each have two MklLeadResources.
Lead1: ResourceA, ResourceB
Lead2: ResourceA, ResourceC
Lead3: ResourceB, ResourceC
•

Type 1: nested find for leads having MklLeadResources.ResourceId="ResourceA"
would return Lead1 and Lead2. The response (assuming you don't have a
findAttribute defined) would include both child resource records (A and B for Lead1,
A and C for Lead2)

Oracle Sales Cloud Web Services White Paper

59

Contents

•

Type 2: ChildFindCriteria for leads having MklLeadResources.ResourceId="ResourceA"
would return all three leads. Lead1 and Lead2 would only include one child
resource (resourceA). Lead3 wouldn't include any child resources

What operators are supported?

Some of the operators supported are: =, !=, <, >, 'IN', 'STARTSWITH','CONTAINS' and ‘LIKE’.
How do I limit which fields and child objects/fields return in the results?

The FindAttribute element should be included for each attribute to be returned. For
example: In java the method getFindAttribute().add("attributename") can be used
to restricts fields which can be returned in a query.
What is the process for updating only one field in an object?

When sending an update, you only pass the attributes that are modified.
How do I blank out an existing value when updating a field?

It is possible to update an existing field value to a blank value by sending blank field attributes in the payload.

FAQs for Web Service Operations
How do I avoid the createEntity operation from displaying error?

Custom object XSD contains an attribute 'IsOwner'. IsOwner attribute is a
transient field, and when createEntity operation payload of Custom Object
Webservice is generated from the entity, it will contain the attribute as
below:
<q1:IsOwner xsi:nil="true"/>
When you call Custom Object Webservice, this attribute should be removed from
createEntity operation payload, otherwise you would get error like
'JBO-27008: Attribute IsOwner in view object cannot be set.'

What happens if I pass SalesAccountId and PartyId in the updateSalesAccount operation?

PartyId and SalesAccountId are attributes of the SalesAccount object. If you pass both
PartyId and SalesAccountId in the payload for the updateSalesAccount operation:
•
•

60

The PartyId is updated, if the PartyId value you pass is different from the current
PartyId of the record.
If you change the PartyId, the external references to the record are broken because
PartyId is an internal field. This breaks the relationships of external records with the

Oracle Sales Cloud Web Services White Paper

▪

Appendix 4: FAQs FAQs for Web Service Operations

current record. To avoid this, you should not pass PartyId attribute in the
updateSalesAccount payload.

How do I update assets information?

You can use the getSalesAccount operation of the SalesAccountService web service to
retrieve a party and its assets’ information. You can use the updateSalesAccount
operation of the SalesAccountService web service to update the asset information of a
party.
How do I avoid the party usage error while using the createPerson operation?
You must include the party usage assignments details when using the createPerson
operation. You must include the party usage assignment details such as
PartyUsageCode and CreatedByModule in the Usage section of the payload. If you do
not include this information, then the createPerson operation fails and displays the error
message JBO-HZ: This party is not valid because there is no party usage assigned.

Oracle Sales Cloud Web Services White Paper

61

Glossary and References

Terms
Item

Meaning

CRM
Application
Composer

Oracle CRM-centric tool that enables application
tailoring, extensibility.

Extensible
Markup
Language
(XML)

The standard markup language that allows the
definition of message structures and facilitates the
passing of data between software applications.

Oracle
Composer

Also known as Page Composer.

Oracle Data
Integrator (ODI)

Oracle non-CRM-centric tool that enables bulk data
import data to Sales Cloud schema.

Oracle capability that enables Sales Cloud Dashboard
tailoring.

Also see: File-based Import Tool
Page
Composer

Refer to Oracle Composer.

Security
Assertion
Markup
Language
(SAML)

A standard for exchanging authentication and
authorization data between security domains.

Simple Object
Access
Protocol (SOAP)

The XML-based protocol that is used to send web
services request and response messages. web services
messages are sent between the customer
implementation of web services and the SOAP handler
on the Oracle web Server.

Oracle Sales Cloud Web Services White Paper

63

Contents

Service Data
Object (SDO)

Fusion currently sends entire SDO to the external service.
If external service requires specific payload, an
intermediary (for example, BPEL) may need to transform
and parse the data.

Web services
Description
Language
(WSDL)

The XML-formatted language that is used to describe a
web service. A WSDL file defines the available
methods, message structures, and network addresses
required for using a specific web service.

WS-Policy

The WS-Policy framework provides a flexible and
extensible grammar for describing the
capabilities,
requirements, and general characteristics of web
services using policies.

Abbreviations

64

Item

Meaning

API

Application Program Interface

BPEL

Business Process Execution Language

CRM

Customer Relationship Management

IT

Information Technology

OER

Oracle Enterprise Repository

SAML

Security Assertion Markup Language

SOAP

Simple Object Access Protocol

SDO

Service Data Object

SQL

Structured Query Language

Oracle Sales Cloud Web Services White Paper

▪

Glossary and References Document References

Item

Meaning

SWE

Siebel Web Engine

UDDI

Universal Description, Discovery, and
Integration

UI

User interface

WS

Web service

WSDL

Web services Description Language

Document References
Below lists recommended readings to get additional information about related topics
and tools.
document title

Type of Reference

document location

CRM Extensibility
Guide

CRM-centric extensibility
guide

Help Portal - InfoDev

Oracle Fusion
Applications
Extensibility Guide

Cross-pillar extensibility guide

Help Portal - InfoDev

Integration
Cookbook

White paper discusses
Integration Patterns

Metalink, Files

Oracle Enterprise
Repository

Repository of services

SaaS – URL; On Premise –
specific to customer

Integrating with
Fusion Applications
– a SOA Whitepaper

Whitepaper

Metalink, Files

Oracle Sales Cloud Web Services White Paper

65

Contents

66

document title

Type of Reference

document location

Oracle® Fusion
Middleware Security
and Administrator's
Guide for Web
Services

Fusion Middleware guide

Help Portal - InfoDev

Making the most of
Oracle Enterprise
Repository for
Oracle Fusion
Applications

Whitepaper

OER portal

Oracle Sales Cloud Web Services White Paper

https://fusionappsoer.oracle.co
m/FusionApps_OER_WP.pdf