3Getting Started with Web Services
Getting Started with Web Services
This chapter provides an overview of how to get started with Oracle CRM On Demand Web Services. It contains the following topics:
Accessing Data in Oracle CRM On Demand
A customer who wants to access data in Oracle CRM On Demand from a Web services-enabled client must perform the following tasks:
Request Web Services Integration.
Download WSDL files, and Schema files if required.
Incorporate WSDL files into the development environment.
Requesting Web Services Integration
On request, an Oracle CRM On Demand Customer Care representative enables the Oracle CRM On Demand integration capability for your company by limiting access to Web services to particular roles.
Web Services Privileges
Starting with Oracle CRM On Demand Release 17, Customer Care can grant two privileges:
Enable Web Services Access.
Users whose roles have been granted this privilege can log in to Oracle CRM On Demand through Web services, and issue requests using the Web services API.
By default, this privilege is enabled for the Administrator role for new companies.
Manage Access to Web Services.
Users (usually administrators) who have been granted this privilege can grant other roles the Enable Web Services Access privilege.
If your company existed before Release 17, and you have access to Web services, you do not need to take any action unless you wish to restrict access to Web services, in which case you must do the following:
Contact Customer Care and request that the Administrator (or equivalent custom role) be granted the Manage Access to Web Services Integration privilege.
Configure roles. The Administrator grants or revokes access to Web services on for each role.
Enabling Stateless Web Services Support
Support for stateless Web services requests is enabled by Customer Care or the company administrator through the Web Services R16 Compatibility Mode setting on the Company Profile page in Oracle CRM On Demand. This check box controls whether Web services requests are processed as stateless requests or as stateful requests as in Release 16 of Oracle CRM On Demand.
The Web Services R16 Compatibility Mode check box is cleared by default for all new companies, therefore support for stateless Web services is enabled by default for new customers, and disabled by default for companies who were customers before Release 17. It is recommended to clear the check box and thus enable stateless Web Services.
If stateless Web services support is enabled, the namespace specified in requests is used to determine whether or not a request is processed as a stateless request:
Specifying the WSSE Version 1.0 security namespace results in the request being treated as a stateless request. In this case, session pooling is used to manage user sessions (that is, no session ID is returned in the response). This conforms to WS-I specifications.
Specifying the WSSE draft namespace results in the request being treated as a stateful request, in which a session ID value is returned in the response (this was the behavior before Release 17).
For more information about these namespaces, see WSSE Namespace Support.
If stateless Web services support is disabled, requests containing the username and password tokens are treated as stateful requests, regardless of the specified namespace value. Responses are returned with a session ID that can be used in subsequent requests to reuse an existing session.
Downloading WSDL Files and Schema Files
Your company’s designated Oracle CRM On Demand administrator accesses the Web Services Administration page located under the Admin link in Oracle CRM On Demand to download Web Service Description Language (WSDL) files that can be used to create applications that interact with Oracle CRM On Demand through Web services. The WSDL files are divided into the following types, corresponding to APIs:
Web Services v1.0 and Web Services v2.0 APIs, which provide access to the data your company has stored within Oracle CRM On Demand
The Service APIs, which allow administrators to perform actions such as changing passwords or retrieving integration events
The Administrative Services APIs, which allow access to your company's configuration and can be used to retrieve or change the way you have configured Oracle CRM On Demand programmatically.
Downloading WSDL Files
You can download WSDL files for the Web Services v1.0 and Web Services v2.0 APIs in either a Custom or Generic version, as follows:
Downloading Custom WSDL. For Custom WSDL files, the XML tags for custom fields are based on the Integration tags configured in Field Setup. Custom WSDL files allow you to generate WSDL files that are specific to your company and which use your company's field naming conventions.
Downloading Generic WSDL. For Generic WSDL files, custom fields are based on generic XML tags: CustomNumber0, CustomCurrency0, and so on. Using these placeholders, together with the Mapping Service or Field Management API allows applications to map the generic XML tags to the field names that your company uses.
For Web Services v1.0, and Web Services v2.0 objects you can also download Custom or Generic Schema files, as described in Downloading Schema Files.
Downloading WSDL Files for Web Services v1.0 and Web Services v2.0
You can download a WSDL file for each record type and you can choose the child record types to include in the WSDL file for the parent record type.
To download a WSDL file for Web Services v1.0 and Web Services v2.0
Navigate to the Web Services Administration page.
From the Select Service drop-down list, select Web Services v1.0, or Web Services v2.0 as required.
From the Document list, select WSDL.
From the Type list, select Custom or Generic.
From the WSDL Object list, select the required record type, for example, Account.
The objects displayed in the WSDL Object list depend on the record types that are set up for your company. All of the child record types for the selected record type are displayed, in alphabetical order, in the Available Related Information list, regardless of whether you have access to the child record types. For Web Services v2.0, CustomWebApplet is also displayed.
Move the child record types that you wish to include in the WSDL from the Available Related Information list to the Selected Related Information list.
Click Download.
Save the WSDL file to your computer.
Downloading WSDL Files for Service APIs
You can download a WSDL file for each of the service APIs. If you download the WSDL for Integration Event, then you must additionally download the Schema files for each of the record types for which you wish to generate integration events, see Downloading Schema Files.
To download a WSDL file for Service APIs
Navigate to the Web Services Administration page.
From the Select Service drop-down list, select Service APIs.
Note: If you select the Merge Service API, you can select Custom or Generic from the Type list and download a Schema file for this Service API.From the Type list, select Custom or Generic.
From the WSDL Object list, select the required name of the Service API.
Click Download.
Save the WSDL file to your computer.
Downloading WSDL Files for Administrative Services
You can download a WSDL file for each Administrative service.
To download a WSDL file for Administrative Services
Navigate to the Web Services Administration page.
From the Select Service drop-down list, select Administrative Services.
From the WSDL Object list, select the required service.
Click Download.
Save the WSDL file to your computer.
Downloading Schema Files
The Integration Events Web service (part of the Service API) imports Schema (XSD) files from its WSDL, therefore you must download the required Schema files for the objects included in the WSDL file. You can download Custom or Generic Schema files for all objects for the Web Services v1.0 API, as well as Web Services v2.0 API.
If you create custom fields or rename fields for a record type, then you cannot use the Generic XSD files for tracking these fields. Instead, you must download a Custom XSD file using the Custom option on in the Web Services Administration page. For more information about the Integration Events Web service, see Preparing the Integration Event WSDL File and Schema Files.
To download a Schema file
Navigate to the Web Services Administration page.
From the Select Service drop-down list, select Web Services v1.0 or Web Services v2.0.
From the Document list, select Schema.
From the Type list, select Custom or Generic.
Depending on whether you select Custom or Generic, custom fields are displayed differently in the Schema file. For Custom Schema, the XML tags for the custom fields are based on the integration tags from Field Setup. For Generic Schema, the custom fields are based on generic XML tags.
From the WSDL Object list, select the required record type, for example, Account.
The objects displayed in the WSDL Object list depend on the record types that are set up for your company.
From the Select Related Information list, select the child record types that you wish to include in the Schema.
Click Download.
Save the Schema file to your computer.
Incorporating WSDL Files into the Development Environment
To use the downloaded WSDL files, the company incorporates the WSDL files into its Web services development environment—for example, by generating .NET, Java, or C# (C Sharp) proxy classes.
For some information about best practices when generating proxy classes, see Avoiding Proxy Class Compilation Failure Due to the Java 64KB Limit.