CRM On Demand                 Oracle Web Services                   On Demand GuideVersion 6.0 (Oracle CRM On Demand Relea...
Copyright © 2005, 2010 Oracle. All rights reserved.The Programs (which include both the software and documentation) contai...
ContentsOracle Web Services On Demand Guide 1Chapter 1:                               What’s New in This ReleaseChapter 2:...
Contents ■Chapter 4:         Establishing and Managing the Web Services                   SessionAbout Establishing and Ma...
Contents ■Chapter 6:          Web Services On Demand API CallsWeb Services v1.0 API Calls    62   User Keys 62   The Echo ...
Contents ■    AccessProfileUpsert 122    ActionBarLayoutReadAll 123    ActionBarLayoutUpsert 124    CascadingPicklistRead ...
Contents ■   Oracle CRM On Demand Pick Maps    157   Filterable Fields 158Parent Objects (Web Services v1.0)    158   Acco...
Contents ■    Recipient 296    Related Account   296    Related Contact   296    Revenue 296    SampleDropped     297    S...
Contents ■   Special Pricing Request Line Item     374Life Sciences Edition Parent Objects (Web Services v2.0)    376   Al...
Contents ■     Dealer    456     Vehicle   458Child Objects (Web Services v2.0)           461     Account 462     Activity...
Contents ■Appendix B: Mapping of Display Names to Service API            Object NamesAppendix C: Web Services On Demand Li...
Contents ■12    Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand      Release 18)
1              What’s New in This ReleaseWhat’s New in Oracle Web Services On Demand Guide, Version 6.0(Oracle CRM On Dema...
What’s New in This Release ■Table 1.     What’s New in Oracle Web Services On Demand Guide, Version 6.0 (Oracle CRM On    ...
2              Overview of Web Services On               DemandThis chapter provides an overview of Oracle CRM On Demand’s...
Overview of Web Services On Demand ■ Oracle CRM On Demand Web Services andIntegration with Oracle CRM On DemandOracle CRM ...
Overview of Web Services On Demand ■ Oracle CRM On Demand Web Services and                                          Integr...
Overview of Web Services On Demand ■ Oracle CRM On Demand Web Services andIntegration with Oracle CRM On Demand■    A full...
Overview of Web Services On Demand ■ Web Services and the Oracle CRM On Demand                                            ...
Overview of Web Services On Demand ■ Web Services and the Oracle CRM On DemandObjectsTable 2 shows the methods available t...
Overview of Web Services On Demand ■ Web Services and the Oracle CRM On Demand                                            ...
Overview of Web Services On Demand ■ Web Services and the Oracle CRM On DemandObjectsTable 3.     Web Services v1.0 and We...
Overview of Web Services On Demand ■ Web Services and the Oracle CRM On Demand                                            ...
Overview of Web Services On Demand ■ Stateless Web Services and SessionManagementTo download a WSDL file that is specific ...
Overview of Web Services On Demand ■ Field Types Supported by Oracle CRM On                                               ...
Overview of Web Services On Demand ■ Field Types Supported by Oracle CRM OnDemandTable 4.      Data Type Mapping in the We...
Overview of Web Services On Demand ■ Field Types Supported by Oracle CRM On                                               ...
Overview of Web Services On Demand ■ Field Types Supported by Oracle CRM OnDemand     2009-10-10T12:00:00-05:00represents ...
Overview of Web Services On Demand ■ Web Services Utilization       ❏   Percent (%)       ❏   Ampersand (&)       ❏   Sing...
Overview of Web Services On Demand ■ Web Services Utilization30    Oracle Web Services On Demand Guide Version 6.0 (Oracle...
3              Getting Started with Web               ServicesThis chapter provides an overview of how to get started with...
Getting Started with Web Services ■ Downloading WSDL files and Schema FilesThese privileges replace the Web Services Enabl...
Getting Started with Web Services ■ Downloading WSDL files and Schema FilesYou can download WSDL files for both the Web Se...
Getting Started with Web Services ■ Incorporating WSDL Files into the DevelopmentEnvironment2    From the Select Service d...
4              Establishing and Managing the               Web Services SessionThis chapter describes the different ways i...
Establishing and Managing the Web Services Session ■ Server-Side SessionManagementClient-Side ManagementAll other login me...
Establishing and Managing the Web Services Session ■ Client-Side Session                                                  ...
Establishing and Managing the Web Services Session ■ Stateful Login MechanismsStateful Login MechanismsThe following topic...
Establishing and Managing the Web Services Session ■ Stateful Login MechanismsFor code samples for logging in, see: https:...
Establishing and Managing the Web Services Session ■ Logging Out of the WebServices Session2    Login using SSO Token. The...
Establishing and Managing the Web Services Session ■ Logging Out of the Web                                               ...
Establishing and Managing the Web Services Session ■ Logging Out of the WebServices Session42    Oracle Web Services On De...
5               Best Practices for Designing                Client ApplicationsThis chapter provides best practice recomme...
Best Practices for Designing Client Applications ■ Best Practices for Integration DesignSending of Web Services Requests t...
Best Practices for Designing Client Applications ■ Best Practices for Integration Design    <wsse:Username>user@ondemand.c...
Best Practices for Designing Client Applications ■ Best Practices for Integration DesignFor stateless requests, a session ...
Best Practices for Designing Client Applications ■ Best Practices for Integration DesignWorking with Opportunity Product R...
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Webservices
Upcoming SlideShare
Loading in...5
×

Webservices

3,696

Published on

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
3,696
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
101
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Transcript of "Webservices"

  1. 1. CRM On Demand Oracle Web Services On Demand GuideVersion 6.0 (Oracle CRM On Demand Release 18) August 2010
  2. 2. Copyright © 2005, 2010 Oracle. All rights reserved.The Programs (which include both the software and documentation) contain proprietary information;they are provided under a license agreement containing restrictions on use and disclosure and are alsoprotected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering,disassembly, or decompilation of the Programs, except to the extent required to obtain interoperabilitywith other independently created software or as specified by law, is prohibited.The information contained in this document is subject to change without notice. If you find any problemsin the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part ofthese Programs may be reproduced or transmitted in any form or by any means, electronic ormechanical, for any purpose.If the Programs are delivered to the United States Government or anyone licensing or using the Programson behalf of the United States Government, the following notice is applicable:U.S. GOVERNMENT RIGHTSPrograms, software, databases, and related documentation and technical data delivered to U.S.Government customers are "commercial computer software" or "commercial technical data" pursuant tothe applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such,use, duplication, disclosure, modification, and adaptation of the Programs, including documentation andtechnical data, shall be subject to the licensing restrictions set forth in the applicable Oracle licenseagreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, CommercialComputer Software--Restricted Rights (June 1987). Oracle America, Inc., 500 Oracle Parkway, RedwoodCity, CA 94065.The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherentlydangerous applications. It shall be the licensees responsibility to take all appropriate fail-safe, backup,redundancy and other measures to ensure the safe use of such applications if the Programs are used forsuch purposes, and we disclaim liability for any damages caused by such use of the Programs.The Programs may provide links to Web sites and access to content, products, and services from thirdparties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites.You bear all risks associated with the use of such content. If you choose to purchase any products orservices from a third party, the relationship is directly between you and the third party. Oracle is notresponsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms ofthe agreement with the third party, including delivery of products or services and warranty obligationsrelated to purchased products or services. Oracle is not responsible for any loss or damage of any sortthat you may incur from dealing with any third party.Oracle, JD Edwards, and PeopleSoft are registered trademarks of Oracle Corporation and/or its affiliates.Other names may be trademarks of their respective owners.
  3. 3. ContentsOracle Web Services On Demand Guide 1Chapter 1: What’s New in This ReleaseChapter 2: Overview of Web Services On DemandAbout Web Services 15 Web Services Core Technologies 15 Oracle CRM On Demand Web Services Toolkit 16Oracle CRM On Demand Web Services and Integration with Oracle CRM On Demand 16 Web Services Security 17 Web Services Reliability 19Web Services and the Oracle CRM On Demand Objects 19 Web Service APIs 19 About Parent-Child Relationships 23 Web Services On Demand and Custom Fields 23Stateless Web Services and Session Management 24Field Types Supported by Oracle CRM On Demand 24 Web Services v1.0 25 Web Services v2.0 25 Special Search Fields 26 Support for Multi-Select Picklists 27 Locale-Dependent Access to Oracle CRM On Demand 27 Validation of Email Fields 28Web Services Utilization 29Chapter 3: Getting Started with Web ServicesAccessing Data in Oracle CRM On Demand 31Requesting Web Services Integration 31 Enabling Stateless Web Services Support 32Downloading WSDL files and Schema Files 32 Downloading Schema Files 33Incorporating WSDL Files into the Development Environment 34 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 3 Release 18)
  4. 4. Contents ■Chapter 4: Establishing and Managing the Web Services SessionAbout Establishing and Managing the Web Services Session 35 Server-Side Management 35 Client-Side Management 36Server-Side Session Management 36Client-Side Session Management 37Stateful Login Mechanisms 38 Logging in Using HTTP GET 38 Logging in Using Single Sign-On 39 Integration Requests for the Web Services Session 40Logging Out of the Web Services Session 40 Logoff Input 41 Logoff Output 41 Alternative Logoff 41 41Chapter 5: Best Practices for Designing Client ApplicationsBest Practices for Integration Design 43 Sending of Web Services Requests to Oracle CRM On Demand 44 Flushing of Caches 44 Using Stateless Web Services 45 Setting and Querying Blank Values 46 Working with Opportunity Product Revenue Records 47 Error Handling and Logging 47 Handling Outages and Failures 47 Best Practices for Generating Web Services Proxy Classes in Java Environments 48 Avoiding Proxy Class Compilation Failure Due to the Java 64KB Limit 49 Entering Telephone Number Values through Web Services 52Best Practices for Integration Performance 54 Batch Processing 54 Session Management and Pooling 55 API Calls 56Best Practices for Integration Management 58 Moving Customers Between Pods 58 Handling Outages 58 Maintaining SSL Certificates 594 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  5. 5. Contents ■Chapter 6: Web Services On Demand API CallsWeb Services v1.0 API Calls 62 User Keys 62 The Echo Argument 63 Delete 63 DeleteChild 66 Insert 67 InsertChild 68 InsertOrUpdate 68 QueryPage 69 Update 78 UpdateChild 79Web Services v2.0 API Calls 79 The Echo Argument 80 The ViewMode Argument 81 The LOVLanguageMode Argument 81 Delete 82 Execute 83 Insert 84 QueryPage 85 Specifying the Sort Order and Sort Sequence 90 Update 93Service API Calls 94 DeletedItemQueryPage 95 DeleteEvents 99 GetEvents 100 GetMapping 103 GetPicklistValues 104 GetServerTime 105 LoginHistoryQueryPage 106 MergeRecords 107 MetadataChangeSummaryQueryPage 109 SalesProcessQueryPage 110 SetPasswordAPI 112 SetSessionTimeZone 113 UpdatePicklist 114 UpdateCascadingPicklists 115 UserUsageQueryPage 117Administrative Services API Calls 119 AccessProfileRead 121 AccessProfileReadAll 121Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 5 Release 18)
  6. 6. Contents ■ AccessProfileUpsert 122 ActionBarLayoutReadAll 123 ActionBarLayoutUpsert 124 CascadingPicklistRead 125 CascadingPicklistReadAll 126 CustomRecordTypeRead 127 CustomRecordTypeReadAll 127 CustomRecordTypeUpsert 128 CustomWebLinkRead 129 CustomWebLinkReadAll 130 CustomWebLinkUpsert 131 CustomWebTabDelete 132 CustomWebTabRead 133 CustomWebTabReadAll 133 CustomWebTabUpsert 134 FieldManagementCreate 135 FieldManagementRead 136 FieldManagementReadAll 136 FieldManagementUpsert 137 HomepageLayoutReadAll 138 PageLayoutFieldRead 140 PageLayoutFieldReadAll 140 PageLayoutFieldUpsert 141 PageLayoutRelatedInformationReadAll 142 PageLayoutRelatedInformationUpsert 143 PicklistRead 144 PicklistReadAll 144 PicklistUpsert 145 RoleReadAll 146 RoleUpsert 147Data Loader API Calls 149 BulkOpImportCreateRequest 149 BulkOpImportSendData 151 BulkOpImportGetRequestDetail 153Chapter 7: Oracle CRM On Demand Objects Exposed Through Web ServicesReference Information About the Parent Objects 155 Oracle CRM On Demand User Keys 156 Audit Fields 156 Oracle CRM On Demand Status Keys 1576 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  7. 7. Contents ■ Oracle CRM On Demand Pick Maps 157 Filterable Fields 158Parent Objects (Web Services v1.0) 158 Account 159 Activity 178 Asset 187 Book 189 Campaign 192 Contact 201 Current User 220 CustomObject1 - CustomObject3 222 Dealer 231 Household 235 Lead 239 MedEd 246 Note 249 Opportunity 251 Portfolio 263 Product 268 Product Category 270 Service Request 272 Solution 277 Territory 280 User 282 User Group 285 Vehicle 287Child Objects (Web Services v1.0) 290 Address 291 Attachment 292 Audit Trail 292 BookUser 292 Competitor 292 DelegatedUser 293 HouseholdTeam 293 Interests 294 Invitee 294 Login History 294 Multiple Contact Roles 294 OpportunityTeam 294 PortfolioTeam 295 ProductsDetailed 295 Quota 295Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 7 Release 18)
  8. 8. Contents ■ Recipient 296 Related Account 296 Related Contact 296 Revenue 296 SampleDropped 297 SubBook 297 Team 297Core Parent Objects (Web Services v2.0) 297 Account 298 Activity 301 Asset 305 Book 308 Campaign 309 Category 312 Contact 313 CustomObject 317 Group 320 Lead 322 Note 324 Opportunity 325 Product 328 Service Request 330 Solution 332 Territory 334 User 336Partner Relationship Management Edition Objects (Web Services v2.0) 338 Accreditation 339 Accreditation Request 341 Application 343 Certification 346 Certification Request 348 Course 350 Course Enrollment 352 Deal Registration 355 Exam 357 Exam Registration 359 Fund 362 MDF Request 364 Partner 366 Price List 368 Price List Line Item 370 Special Pricing Request 3728 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  9. 9. Contents ■ Special Pricing Request Line Item 374Life Sciences Edition Parent Objects (Web Services v2.0) 376 Allocation 377 Business Plan 379 Contact Best Time 382 Contact State License 384 Inventory Audit Report 386 Inventory Period 388 MedEd 390 Message Response 392 Messaging Plan 394 Messaging Plan Item 397 Messaging Plan Item Relation 399 Modification Tracking 401 Objective 403 Plan Account 405 Plan Contact 407 Plan Opportunity 409 Sample Disclaimer 411 Sample Inventory 413 Sample Lot 415 Sample Transaction 417 Signature 420 Transaction Item 421Financial Services Edition Parent Objects (Web Services v2.0) 424 Claim 424 Coverage 427 Damage 429 Financial Account 431 Financial Account Holder 433 Financial Account Holding 435 Financial Plan 437 Financial Product 439 Financial Transaction 441 Household 443 Insurance Property 446 Involved Party 448 Policy 450 Policy Holder 452 Portfolio 454Automotive Edition Parent Objects (Web Services v2.0) 456Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 9 Release 18)
  10. 10. Contents ■ Dealer 456 Vehicle 458Child Objects (Web Services v2.0) 461 Account 462 Activity 464 Address 466 Asset 467 Attachment 469 Book 470 471 Contact 471 Contact Team 473 Custom Object 4 and Higher 474 Delegated User 476 Interests 477 Invitee 478 Lead 480 Note 482 Opportunity 483 Products Detailed 485 Promotional Items Dropped 486 Recipient 487 Related Contact 488 Revenue 490 Sample Dropped 492 Service Request 493 User 495Appendix A: Using Attachments With Web Services On DemandAbout Attachments 497The Attachment Element 497Specifying File Attachment Content 499 Attaching Binary Data 499 Attaching a Text File 500 Attaching a File to Multiple Records 501Retrieving or Querying File Attachments 503Specifying URL Attachments 50510 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  11. 11. Contents ■Appendix B: Mapping of Display Names to Service API Object NamesAppendix C: Web Services On Demand Limiters Web Services Request Rate 512IndexOracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 11 Release 18)
  12. 12. Contents ■12 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  13. 13. 1 What’s New in This ReleaseWhat’s New in Oracle Web Services On Demand Guide, Version 6.0(Oracle CRM On Demand Release 18)Table 1 lists changes described in this version of the documentation to support Version 6.0 (OracleCRM On Demand Release 18) of the software.Table 1. What’s New in Oracle Web Services On Demand Guide, Version 6.0 (Oracle CRM On Demand Release 18) Topic Description “Web Services On Demand and Custom Standard custom field support has been added for the Fields” on page 23 Account Relationship and the Contact Relationship objects. “Entering Telephone Number Values Information about best practices for entering telephone through Web Services” on page 52 numbers through Web services has been added. “Using the QueryPage Method” on More information about the best practices for using the page 57 QueryPage method has been added. “DeleteEvents” on page 99 The DeleteEvents and GetEvents methods now support Custom Object 04 and higher and a number of Life “GetEvents” on page 100 Sciences related objects. “Preparing the Integration Event WSDL In previous releases, to generate a WSDL file for the File and Schema Files” on page 102 Integration Events Web service, users downloaded a .zip file containing both the WSDL and generic Schema files for all supported objects. In this release, only a WSDL file is generated when users click the Download Custom WSDL or Download Generic WSDL button on the Web Services Administration page. You must download Schema files separately for supported objects that you wish to track. Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 13 Release 18)
  14. 14. What’s New in This Release ■Table 1. What’s New in Oracle Web Services On Demand Guide, Version 6.0 (Oracle CRM On Demand Release 18) Topic Description “Administrative Services API Calls” on The Administrative API, used to automate the page 119 administration of company configurations, has been extended. The calls for the following services are described: ■ Action Bar Layout ■ Custom Web Link ■ Homepage Layout ■ Page Layout Field ■ Page Layout Related Information ■ Role Management “Accreditation” on page 339 For Web Services v2.0 only, a number of new objects available with the Oracle CRM On Demand Partner “Accreditation Request” on page 341 Relationship Management Edition have been exposed: “Certification” on page 346 ■ Accreditation “Certification Request” on page 348 ■ Accreditation Request “Course” on page 350 ■ Certification “Course Enrollment” on page 352 ■ Certification Request “Exam” on page 357 ■ Course “Exam Registration” on page 359 ■ Course Enrollment ■ Exam ■ Exam Registration “Partner” on page 366 The QueryPage method is now supported for the Partner object. “Invitee” on page 478 The Invitee child object of MedEd has been exposed. Appendix B, “Mapping of Display Names Details of new objects have been added to the table to Service API Object Names,” showing the mapping of display names to Service API object names.14 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  15. 15. 2 Overview of Web Services On DemandThis chapter provides an overview of Oracle CRM On Demand’s support for Web services. It containsthe following topics:■ “About Web Services”■ “Oracle CRM On Demand Web Services and Integration with Oracle CRM On Demand” on page 16■ “Web Services and the Oracle CRM On Demand Objects” on page 19■ “Stateless Web Services and Session Management” on page 24■ “Field Types Supported by Oracle CRM On Demand” on page 24■ “Web Services Utilization” on page 29About Web ServicesThe term Web services describes a standardized way of integrating Web-based applications over theWeb. Web services allow businesses to communicate with each other and with other clients, withoutintimate knowledge of each other’s IT systems. Web services share business logic, data, andprocesses through a Web services application programming interface (API). Application developerscan then add the Web services to a software application (such as a Web page or executable program)to offer specific functionality to users.Web Services Core TechnologiesThe Web services core technologies are a set of standards-based technologies that include:■ Extensible Markup Language (XML). The standard markup language that allows the definition of message structures and facilitates the passing of data between software applications.■ 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.■ 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.For more information on Web services technologies, see:http://www.w3.org/2002/ws. Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 15 Release 18)
  16. 16. Overview of Web Services On Demand ■ Oracle CRM On Demand Web Services andIntegration with Oracle CRM On DemandOracle CRM On Demand Web Services ToolkitThe Web Services Toolkit provides access to an application programming interface (API) thatcompanies can use to build programs to integrate with Oracle CRM On Demand. The Toolkit includesa set of WSDL files that describes the interface to the Oracle CRM On Demand objects. This providesa programmatic interface for accessing your companys Oracle CRM On Demand information. Acustomer application can use the WSDL files through standard Web services development tools, suchas those provided by the Oracle SOA Suite.The API for this release of Oracle CRM On Demand is backward-compatible with previous releases.Figure 1 shows how the Web Services Toolkit interacts with the Oracle CRM On Demand database.The customer uses the Web Services Toolkit (WSDL fields) to define the objects and methods thatare contained in the Oracle CRM On Demand Hosted Service. The customer applicationcommunicates with Oracle CRM On Demand over the Internet using the secure HTTPS protocol. Itinvokes the Web services implementation contained in the Oracle CRM On Demand Hosted Service.Figure 1. How Web Services Communicate with Oracle CRM On DemandOracle CRM On Demand is designed to be backward-compatible with previous releases. ThereforeWSDL files from previous releases will continue to work with newer releases of Oracle CRM OnDemand, and there is no need for customers to modify their code when upgrading to a new releaseof Oracle CRM On Demand.Oracle CRM On Demand Web Servicesand Integration with Oracle CRM OnDemandThe Web Services On Demand API allows companies to build programs to integrate with Oracle CRMOn Demand. Some common examples of client integrations include the following:16 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  17. 17. Overview of Web Services On Demand ■ Oracle CRM On Demand Web Services and Integration with Oracle CRM On Demand■ Integrations of CRM and back-office applications. You can retrieve real-time sales, marketing, and service information from Oracle CRM On Demand 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 information into an order entry system that has a Web services user interface. In addition, you can store information from back- office applications in Oracle CRM On Demand for instant access by users, visible in custom fields on any Oracle CRM On Demand page.■ 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 Oracle CRM On Demand through the Web services interface. For example, an Oracle CRM On Demand 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 Oracle CRM On Demand for these requests through the Web services interface. Another Web page can allow visitors to browse through solutions to common problems stored in Oracle CRM On Demand and retrieved in real time through the Web services interface.■ Custom add-on modules. Customers can also extend Oracle CRM On Demand 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 Oracle CRM On Demand directly through the Web services interface. Oracle CRM On Demand administrators and users can run these modules while concurrently accessing the Oracle CRM On Demand user interface.Web Services SecurityThe Oracle CRM On Demand Web Services Integration framework includes the following securityfeatures:■ The mustUnderstand attribute of Simple Object Access Protocol (SOAP) 1.1 is supported. This allows a client to specify that the target server must be capable of processing all parameters in the SOAP request header, otherwise the requests must be rejected. SOAP message validation is performed, for example, to check for badly formed SOAP requests or for SOAP header elements that are not namespace-qualified.■ Support is provided for the WS-I Basic Security Profile Version 1.0. For more information, see “Support for the WS-I Basic Security Profile Version 1.0” on page 18.■ All communications are encrypted with Secure Sockets Layer (SSL) for security (minimum 128- bit).■ Access is session-based, requiring authorization with a valid Oracle CRM On Demand user name and password.■ Inactive sessions are reused or closed automatically after a period of inactivity.■ The same data visibility and access capabilities that apply to users in the Oracle CRM On Demand hosted service are applied to users connected through the Web services interface. Data visibility and access are restricted by the role that your company assigns. Permissions are checked for every data access. Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 17 Release 18)
  18. 18. Overview of Web Services On Demand ■ Oracle CRM On Demand Web Services andIntegration with Oracle CRM On Demand■ A full audit trail of Web services activity is available through Oracle CRM On Demands Administration pages. These pages display both current and historical usage statistics.■ A number of other proprietary solutions protect Oracle CRM On Demand against malicious use of the Web services interface. These solutions are constantly reviewed and improved as new technologies and techniques become available.A session with a standard HTTPS request is created to establish a connection with Oracle CRM OnDemand through the Web services interface. A client can create a new session with the loginoperation and close it with the logoff operation. When a session is created, an encrypted sessionidentifier is provided to the client. which for stateful Web services requests, must be included in allsubsequent requests during that session. For more information, see “About Establishing and Managingthe Web Services Session” on page 35.Support for the WS-I Basic Security Profile Version 1.0Support is provided for the WS-I Basic Security Profile Version 1.0, which describes the set ofparameters used to authenticate a Web services transaction.Oracle CRM On Demand has implemented support for the Username and PasswordType parameters,which are part of the UserNameToken standards. This allows a username and password to be passedwith a SOAP request, which removes the necessity for a separate login operation. For moreinformation, see “Server-Side Session Management” on page 36.Passwords can be specified as type PasswordText only, which mean that the password is in clear textformat.WSSE Namespace SupportThe SOAP header of messages received by Oracle CRM On Demand are validated to ensure they arenamespace-qualified. Oracle CRM On Demand supports the following namespace values whenspecifying the WSSE namespace in a SOAP request:■ Draft Namespaces: ■ wsse="http://schemas.xmlsoap.org/ws/2002/04/secext" ■ wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"■ Version 1.0 Namespace: wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- wssecurity-secext-1.0.xsd" The WSSE Version 1.0 namespace must be specified to perform a stateless transaction. (In addition, the Web Services R16 Compatibility Mode check box must be cleared in the Company Profile page and the Username and PasswordText tokens must be provided in the request.)For more information about stateless transactions and the use of the WSSE namespace, seeChapter 4, “Establishing and Managing the Web Services Session.”18 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  19. 19. Overview of Web Services On Demand ■ Web Services and the Oracle CRM On Demand ObjectsWeb Services ReliabilityAll server components of Oracle CRM On Demand, including those responsible for the Web servicesinterface, incorporate load balancing and other high-availability mechanisms. These mechanismsprevent the service from being interrupted by server or network infrastructure failure.Web Services and the Oracle CRM OnDemand ObjectsThe Oracle CRM On Demand Web services allow applications to integrate with Oracle CRM OnDemand. They provide the ability to find and invoke the core Oracle On Demand Web Services acrossthe Web from any client application language. This ability makes the process of using Oracle CRM OnDemand Web Services easy for those who want to use them.The Oracle CRM On Demand services provide a basis for customers to perform integration with OracleCRM On Demand based on SOAP technology.All major Oracle CRM On Demand business objects are exposed in the Web services, with the namesof the Web services matching the default names of the business objects. Chapter 7, “Oracle CRM OnDemand Objects Exposed Through Web Services” details the Oracle CRM On Demand parent and childobjects that are exposed through Oracle CRM On Demand Web Services.Web Service APIsStarting with Web Services On Demand Version 4.0 (CRM On Demand Release 16) , objects areaccessible through two APIs:■ Web Services v1.0. Used to interact with Custom Objects 01-03, as well as out-of-the-box objects.■ Web Services v2.0. Used to interact with all Oracle CRM On Demand Custom Objects, as well as out-of-the-box objects.Before Web Services On Demand Version 4.0, only the Web Services v1.0 was available.For the Web Services v1.0 API, operations work on the parent objects and all child components aresynchronized with the parent. The Web Services v2.0 API, however, works on a node basis, whereparent and child components are treated as separate nodes.The Web Services v2.0 API provides an Execute method for performing multiple operations onseparate nodes, and the Web Services v2.0 QueryPage method offers additional options (through thesearchspec, sortorder, and sortsequence arguments) for issuing queries compared to the WebServices v1.0 QueryPage method. Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 19 Release 18)
  20. 20. Overview of Web Services On Demand ■ Web Services and the Oracle CRM On DemandObjectsTable 2 shows the methods available through the Web Services v1.0 and Web Services v2.0 APIs foraccess to objects.Table 2. Web Services v1.0 and Web Services v2.0 Methods Web Services Web Services v1.0 v2.0 Comments Delete Delete Finds records in the Oracle CRM On Demand database that match specified field values, and then deletes them (in other words, puts them into the Deleted Items area). DeleteChild Not applicable Deletes child records from the Oracle CRM On Demand database, or removes the association between the child and the parent object. Not applicable Execute Executes multiple update, insert, and delete operations on separate records in the Oracle CRM On Demand database within the same Web services request. Insert Insert Inserts new records into the Oracle CRM On Demand database. InsertChild Not applicable Inserts new child records into the Oracle CRM On Demand database. InsertOrUpdate Not applicable Updates existing records or inserts a new record if one did not exist. QueryPage QueryPage Executes a query against a specified list of records, and returns a subset of the records that match the search criteria set by the method arguments. Update Update Updates records with a new value. UpdateChild Not applicable Updates child records with a new value.Table 3 shows differences between Web Services v1.0 and Web Services v2.0.Table 3. Web Services v1.0 and Web Services v2.0 Differences Web Services v1.0 Web Services v2.0 Supports an upsert operation through Does not support an upsert operation InsertOrUpdate call Pagination parameters are supported only Pagination parameters are supported at both the at the parent level parent and child level20 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  21. 21. Overview of Web Services On Demand ■ Web Services and the Oracle CRM On Demand ObjectsTable 3. Web Services v1.0 and Web Services v2.0 Differences Web Services v1.0 Web Services v2.0 Outputs all the children even if the Outputs only the specific child whose condition was condition is true for one child. met. For example, the QueryPage call returns For example, QueryPage returns only the specific all partner children from an account even partner child from the account for which the condition if the condition is true for only one partner was true child UseChildAnd argument of QueryPage call The UseChildAnd argument is not available. is available for using OR/AND logic Instead, by default, all parent records matching the between parent and child parent criteria and only children matching the child criteria are returned. Operators cannot be used to construct The SearchSpec argument of QueryPage can be used complex queries across multiple fields to construct complex queries across multiple fields in a request. For example, the OR operator can be used to find all records that match the specified condition for [Field A] OR the specified condition for [Field B]. Sort order is not customizable Sortorder and sortsequence arguments are available to customize the sorting order of the records Update call removes child objects not An Execute call with “operation=update” at the specified in the request parent level removes the unspecified children in the request InsertChild call is used to insert the For Web Services v2.0: children for existing parent objects ■ Insert call can be used to insert both parent records and child records. ■ If a child node is specified in the request, the Insert call inserts the child and associates it with the existing parent record. ■ If a child node is missing, the Insert call inserts only the new parent record. UpdateChild call is used to update child For Web Services v2.0: records ■ Update call can be used to update parent records and child records ■ If a child node is specified in the request, the Update call updates the child in the existing parent record ■ If the child node is missing, the Insert call updates only the existing parent record Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 21 Release 18)
  22. 22. Overview of Web Services On Demand ■ Web Services and the Oracle CRM On DemandObjectsTable 3. Web Services v1.0 and Web Services v2.0 Differences Web Services v1.0 Web Services v2.0 DeleteChild call is used to delete the child For Web Services v2.0: records ■ Delete call can be used to delete both parent records and child records ■ If the child node specified in the request is available, the Delete call deletes the child in the existing parent record, and leaves the parent record undeleted. ■ If the child node is missing, the Delete call deletes the existing parent record. InsertChild, UpdateChild, and DeleteChild In an Execute request, a specific node within the methods are used to perform operations request can be skipped using the on child records “operation=skipnode” attribute. This can be used to simulate InsertChild, UpdateChild or DeleteChild by skipping the parent node and only performing the specified actions on the child records. LOVLanguageMode argument is not The LOVLanguageMode argument is an input available argument for all of the Web Services v2.0 calls. It determines whether the processing for picklist fields occurs using language independent codes (LIC) or language dependent codes (LDC). ViewMode argument is not available The ViewMode argument, which specifies the level of access to records specified in the method call, is available for all of the Web Services v2.0 callsThere are some differences between the format of the WSDL files for Web Services v1.0 and WebServices v2.0:■ In the Web Services v2.0 API, strong data typing is supported. Therefore, in the Web Services v2.0 WSDL files, fields are represented by a range of xsd: data types, while in Web Services v1.0 WSDL files, all fields have the xsd:string data type. For more information, see “Field Types Supported by Oracle CRM On Demand” on page 24.■ In Web Services v2.0, messages do not include the business service name, and have the format: [Objectname][Method]_[Input/Output] For example: AccountInsert_Input, ContactQueryPage_Output as opposed to the following for Web Services v1.0: AccountWS_AccountInsert_Input, ContactWS_ContactQueryPage_Output■ The target namespace of the WSDL for Web Services v2.0 is:22 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  23. 23. Overview of Web Services On Demand ■ Web Services and the Oracle CRM On Demand Objects urn:crmondemand/ws/ecbs/objectname/ compared to the following for Web Services v1.0: urn:crmondemand/ws/objectname/About Parent-Child RelationshipsMany of the Oracle CRM On Demand objects interact with each other through parent-childrelationships. A parent object refers to the main or base object of interest and the child object refersto objects that are related to the parent in some way—for example, if the child is contained in theparent, or if the child has records that refer to the parent.These parent-child relationships can be one-to-many or many-to-many. For example, a lead can beassociated with a particular account, but an account can have many leads associated with it. In thiscase, you can think of the relationship between the account and its leads as a one-to-many parent-child relationship.Other relationships can be many-to-many, meaning that many children are associated with manyparents. For example, a contact can be associated with several opportunities, or an opportunity canhave several contacts associated with it. In this case, you can think of the relationship betweencontacts and their opportunities as a many-to-many parent-child relationship. The parent-childrelationship between contacts and opportunities can be treated with either the opportunity as theparent with contacts as children, or with the contact as the parent and the opportunities as children.Web Services On Demand and Custom FieldsOracle CRM On Demand allows company administrators to create custom fields that captureinformation specific to the company’s needs. Web Services On Demand allows customers to interactwith the data stored in these custom fields. Each custom field has an associated integration tag thatis used by Web services and Web links to reference data in custom fields. This feature allowsadministrators to change the display name of a field without making modifications to the existingWeb services integration.Fields are labeled as iField_Name in the Custom WSDL files and Custom FieldType# in the GenericWSDL files.To view or modify integration tag information for a record type1 Navigate to the Field Setup Administration page for the required record type. For example: Admin, Application Customization, Account, Account Field Setup, Rename Fields.2 Click Advanced. The integration tag information is displayed for you to view or modify.You can download custom WSDL files in which the XML tags for the custom fields are based on theintegration tags. Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 23 Release 18)
  24. 24. Overview of Web Services On Demand ■ Stateless Web Services and SessionManagementTo download a WSDL file that is specific to your company’s customization1 Navigate to the Web Services Administration page.2 Select Web Services v1.0 or Web Services v2.0, and click Go.3 Select the required record type, and click Download Custom WSDL. A record type’s WSDL that is specific to your company’s customization is downloaded.For more information about downloading WSDL files, refer to the online help for Oracle CRM OnDemand.Stateless Web Services and SessionManagementFrom Release 17, Oracle CRM On Demand supports stateless Web services transactions, and server-side session management capabilities removing the need for customers to implement sessionmanagement within their client applications.Stateless Web services transactions are those in which the client application does not need tomaintain a session identifier (a JSESSIONID value) to perform multiple requests to Oracle CRM OnDemand using the same session. As all Oracle CRM On Demand Web Services methods (with theexception of QueryPage) are stateless, each request can be performed and authenticatedindependently.Stateless Web services are ideally suited for situations in which an interactive application is used tointegrate with Oracle CRM On Demand.In an interactive application that issues requests through Web services calls to update, insert, ordelete records in Oracle CRM On Demand, the client can be implemented so that the user’scredentials are supplied in the request. The Oracle CRM On Demand server checks to see if there isalready a session established for that user in the session pool. If a session is found, it is reused forthe request. If no session is found for that user, a new session is established. By limiting the numberof sessions on a per user basis, it is possible to ensure that no single user can use all of the availablesessions in an Oracle CRM On Demand environment.Sessions that are idle can be reused to process incoming requests, removing the necessity toexplicitly log off from a session, or to wait for a session to time out before a new session can beestablished.For more information about session management, see “About Establishing and Managing the WebServices Session” on page 35 and “Server-Side Session Management” on page 36.Field Types Supported by Oracle CRM OnDemandThe field types supported depend on whether the Web Services v1.0 or Web Services v2.0 API isused, as described in the following topics.24 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  25. 25. Overview of Web Services On Demand ■ Field Types Supported by Oracle CRM On DemandWeb Services v1.0For the Web Services v1.0 API, all fields in Web services On Demand are transmitted and receivedas strings. It is the client’s responsibility to cast these to and from the required data type in anyapplication. The proper type can usually be determined from the name, purpose, or application ofthe field. There is no dynamic method for determining field types. You can derive clues about a field’stype from its name as follows:■ A name ending in the suffix Id is usually a key field, such as a primary key, foreign key, or user key Id. It can usually be treated as a unique text string.■ Fields with names containing Date or Time, such as LastUpdated, DueDate, StartTime, or EndTime might be date fields.■ Telephone number fields can be treated as numeric phone numbers or as plain text. When performing queries on phone number type fields the following formats must be used in Query operations: ■ U.S. Format: +1 872 9269923 ■ France: +33 01 40359564 ■ Japan: +81 3 54579623■ Other numeric fields, such as currency, size, revenue, or probability can be treated as integer, floating point, or text fields depending on the application.■ Boolean fields have the value Y for true or N for false.■ Most other fields can be treated as ordinary text.NOTE: If you attempt to query a field of type Date with syntax like <CloseDate>&gt;01/01/200400:00:00</CloseDate> you get an error, because the time parameter 00:00:00 is only valid forfields of type Date/Time and not for fields of type Date.Web Services v2.0The Web Services v2.0 API supports strong data types for fields, so fields are represented byappropriate XSD data types. Table 4 shows the list of supported XSD data types.Table 4. Data Type Mapping in the Web Services v2.0 API Data Type Mapped XSD Data Type BOOL xsd:boolean CURRENCY xsd:decimal NUMBER xsd:decimal DATE xsd:date DATETIME xsd:dateTime UTCDATETIME xsd:dateTime Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 25 Release 18)
  26. 26. Overview of Web Services On Demand ■ Field Types Supported by Oracle CRM OnDemandTable 4. Data Type Mapping in the Web Services v2.0 API Data Type Mapped XSD Data Type ID xsd:string NOTE xsd:string PHONE xsd:string TEXT xsd:string INTEGER xsd:int TIME xsd:time Others xsd:stringIf an incorrect data type is provided in a Web services request, the field is updated to NULL or adefault value for that specific data type, as shown in Table 5.Table 5. Updating of Fields When Incorrect Data Types are Provided in the Web Services v2.0 API XSD Data Type Default Value/Null xsd:boolean N xsd:decimal NULL xsd:date NULL xsd:dateTime NULL xsd:string NULL xsd:int 0 xsd:time NULLFor example, Activity has a field named Cost, which takes integer values. If you provide a text valuefor the field in an update request, the previous value is replaced with a 0.You can find further details about the definition of XSD data types here:http://www.w3.org/TR/xmlschema-2/#built-in-datatypesSpecial Search FieldsSome field names are prefixed with CI_ to denote that they are special fields that provide bettersearch functionality. These fields do not exist for all objects but are easily identified in the WSDL filesas shown in the following excerpt from the Account WSDL file:<xsd:element name="CI_AccountName" maxOccurs="1" minOccurs="0" type="xsd:string"></xsd:element>26 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  27. 27. Overview of Web Services On Demand ■ Field Types Supported by Oracle CRM On Demand<xsd:element name="CI_Location" maxOccurs="1" minOccurs="0" type="xsd:string"></xsd:element>Support for Multi-Select PicklistsA multi-select picklist is a picklist from which the user can select multiple values. In Web ServicesOn Demand, multi-select picklists are only exposed for the following record types:■ Account■ Activity■ Contact■ Custom Object 01■ Custom Object 02■ Custom Object 03■ Lead■ Opportunity■ Service RequestFor these record types, all standard and custom multi-select picklist fields are exposed. You can add,remove, replace or query selections in parent-level multi-select picklist fields, however child-levelmulti-select picklist fields are not supported.Input and output values are language-independent code (LIC) delimited, but the multi-select picklistdelimiter is always a semicolon regardless of locale for input and output: <LIC1>;<LIC2>.Locale-Dependent Access to Oracle CRM On DemandOracle CRM On Demand Web Services does not provide any specialized localization interfaces. OracleCRM On Demand supports full localization, so that the data created through Web services is localizedfor users. The localized fields in the Web services interfaces follow the formats outlined in thefollowing topics.Date and Time FieldsDate and time fields for Web services v1.0 are in the following format: MM/DD/YYYY hh:mm:ssFor Web services v2.0, the data in SOAP requests conforms to XSD data formats.The XSD dateTime datatype has the format: yyyy - mm - dd T hh : mm : ss (. s+)? (zzzzzz)?For example: Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 27 Release 18)
  28. 28. Overview of Web Services On Demand ■ Field Types Supported by Oracle CRM OnDemand 2009-10-10T12:00:00-05:00represents noon on 10th October 2002, Central Daylight Savings Time, which is equivalent to EasternStandard Time in the US.As a further example: 2009-10-09T17:00:00Zrepresents noon on 9th October 2009, UCT, which is equivalent to the GMT time zone.For the QueryPage method of Web Services v2.0, either the XSD formats (recommended) or thelocale-specific formats can be used.Number and Currency FieldsNumber and currency fields in Oracle CRM On Demand are in raw number format. In other words,number and currency fields hold only digits with no currency symbols, decimal separators, or othernumeric separators (different locales use different symbols as the decimal point).Validation of Email FieldsWhen Oracle CRM On Demand validates fields containing email addresses, it identifies the followingas invalid:■ Empty string■ String too long■ No characters before the at sign (@) character, for example: @riqhtequip.com■ No at sign (@) character, for example:isampleriqhtequip.com■ No period (.) character, for example: isample@riqhtequipcom■ No domain, for example: isample@■ No domain suffix such as com, for example: isample@riqhtequip■ Multiple at signs (@), for example: isample@@riqhtequip.com■ Consecutive period (.) characters, for example: isample@riqhtequip..com■ Spaces in the string, for example: isa mple@riqhtequip■ Characters other than the following in the local part of an email address: ■ Uppercase and lowercase letters (case insensitive) ■ The digits 0 through 9 ■ The characters: ❏ Exclamation point (!) ❏ Hash symbol (#) ❏ Dollar sign ($)28 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  29. 29. Overview of Web Services On Demand ■ Web Services Utilization ❏ Percent (%) ❏ Ampersand (&) ❏ Single quotation sign () ❏ Asterisk (*) ❏ Plus sign (+) ❏ Minus sign (-) ❏ Slash (/) ❏ Equal sign (=) ❏ Question mark (?) ❏ Caret (^) ❏ Underscore (_) ❏ Back single quotation mark (`) ❏ Left curly brace ({) ❏ Vertical bar (|) ❏ Right curly brace (}) ❏ Tilde (~)■ Any special characters in the domain name of an email address. These special characters are the same as those allowed in the local part of the email address, and also the left and right parentheses ().Web Services UtilizationIn the Oracle CRM On Demand application, the Web Services Utilization page provides usefulinformation on Web services usage, both current and historical, for a company.In the Web Services utilization page, the source of Web services calls is logged to determine whetherthe calls originated, for example, from a PDA application, or from a generic custom application.You can also use the UserUsageQueryPage method to get information about Web services utilization.For more information about this method, see “UserUsageQueryPage” on page 117.See the Oracle CRM On Demand online help for more information on using the Web ServicesUtilization page. Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 29 Release 18)
  30. 30. Overview of Web Services On Demand ■ Web Services Utilization30 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  31. 31. 3 Getting Started with Web ServicesThis 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” on page 31■ “Requesting Web Services Integration” on page 31■ “Downloading WSDL files and Schema Files” on page 32■ “Incorporating WSDL Files into the Development Environment” on page 34Accessing Data in Oracle CRM OnDemandA customer who wants to access data in Oracle CRM On Demand from a Web services-enabled clientmust perform the following tasks:1 Request Web Services Integration.2 Download WSDL files, and Schema files if required.3 Incorporate WSDL files into the development environment.Requesting Web Services IntegrationOn request, an Oracle CRM On Demand Customer Care representative enables the Oracle CRM OnDemand Integration capability for your company by limiting access to Web services to particularroles.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.Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 31 Release 18)
  32. 32. Getting Started with Web Services ■ Downloading WSDL files and Schema FilesThese privileges replace the Web Services Enabled check box on the Company Profile page in theOracle CRM On Demand application, which was the means of enabling Web services access beforeRelease 17. To maintain backwards compatibility, all roles for companies existing before Release 17have the privilege to enable access to Web services.if your company existed before Release 17, and you have access to Web services, you do not needto take any action unless you wish to restrict access to Web services, in which case you must do thefollowing:1 Contact Customer Care and request that the Administrator (or equivalent custom role) be granted the Manage Access to Web Services Integration privilege.2 Configure roles. The Administrator grants or revoke access to Web services on a per role basis.Enabling Stateless Web Services SupportSupport for stateless Web services requests is enabled by Customer Care or the companyadministrator through the Web Services R16 Compatibility Mode setting on the Company Profile pagein Oracle CRM On Demand. This check box controls whether Web services requests are processed asstateless 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 disabledby default for companies who were customers before Release 17. It is recommended to clear thecheck box and thus enable stateless Web Services.If stateless Web services support is enabled, the namespace specified in requests is used todetermine 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” on page 18.If stateless Web services support is disabled, requests containing the username and password tokensare treated as stateful requests, regardless of the specified namespace value. Responses arereturned with a session ID that can be used in subsequent requests to reuse an existing session.Downloading WSDL files and SchemaFilesYour company’s designated Oracle CRM On Demand administrator accesses the Web ServicesAdministration page in Oracle CRM On Demand to download Web Service Description Language(WSDL) files that have been published for the desired Oracle CRM On Demand objects (record types).The administrator can also download WSDL files for the Service API; the API for managingadministrative tasks through Web services, and WSDL files for the Administrative Services.32 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  33. 33. Getting Started with Web Services ■ Downloading WSDL files and Schema FilesYou can download WSDL files for both the Web Services v1.0 and Web Services v2.0 API, and forboth of these services, you can download Custom or Generic WSDL files.For Web Services v1.0, and Web Services v2.0 objects for which Integration Events support isoffered, you can also download Schema files, as described in Downloading Schema Files.To download a WSDL file1 Navigate to the Web Services Administration page.2 From the Select Service drop-down list, select Web Services v1.0, Web Services v2.0, Service, or Administrative Services APIs as required.3 From the WSDL Object drop-down list, select the required record type, for example, Account, or the name of the service API. The objects displayed in the WSDL Object drop-down list depend on the record types that are set up for your company.4 Click one of the following buttons, to display a page containing the WSDL. Depending on whether you select Download Custom WSDL, or Download Generic WSDL, custom fields are displayed differently in the WSDL: ■ Download Custom WSDL. For Custom WSDL, the XML tags for the custom fields are based on the Integration tags from Field Setup. Custom WSDL allows you to generate WSDL specific to your company that uses your companys field naming conventions. ■ Download Generic WSDL. For Generic WSDL, the custom fields are based on generic XML tags: CustomNumber0, CustomCurrency0, and so on. Using these placeholders, together with the Mapping Service allows applications to map to the field names that your company uses.5 Save the WSDL file to your computer.Downloading Schema FilesThe Integration Events Web service (part of the Service API) imports Schema (XSD) files from itsWSDL, therefore you must download the required Schema files for the objects included in the WSDLfile. 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 objects for which Integration Events support is offered.If you create custom fields or rename fields for a record type, you cannot use the Generic XSD filesfor tracking these fields. Instead, you must download a Custom XSD file using the Download CustomSchema button in the Web Services Administration page.For more information about the Integration Events Web service, see “Preparing the Integration EventWSDL File and Schema Files” on page 102.To download a Schema file1 Navigate to the Web Services Administration page. Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 33 Release 18)
  34. 34. Getting Started with Web Services ■ Incorporating WSDL Files into the DevelopmentEnvironment2 From the Select Service drop-down list, select Web Services v1.0 or Web Services v2.0.3 From the WSDL Object drop-down list, select the required record type, for example, Account. The objects displayed in the WSDL Object drop-down list depend on the record types that are set up for your company.4 Click one of the following buttons: ■ Download Custom Schema. ■ Download Generic Schema. A page containing the Schema is displayed. Depending on whether you select Download Custom Schema, or Download Generic Schema, custom fields are displayed differently in the Schema. 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. NOTE: If you selected Web Services v2.0, and Schema file generation is not supported for the selected record type, an error message is displayed.5 Save the Schema file to your computer.Incorporating WSDL Files into theDevelopment EnvironmentTo use the downloaded WSDL files, the company incorporates the WSDL files into its Web servicesdevelopment 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 ClassCompilation Failure Due to the Java 64KB Limit” on page 49.34 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  35. 35. 4 Establishing and Managing the Web Services SessionThis chapter describes the different ways in which an Oracle CRM On Demand Web services sessioncan be established and maintained. It contains the following topics:■ “About Establishing and Managing the Web Services Session” on page 35■ “Server-Side Session Management” on page 36■ “Client-Side Session Management” on page 37■ “Stateful Login Mechanisms” on page 38■ “Logging Out of the Web Services Session” on page 40About Establishing and Managing theWeb Services SessionA Web services-enabled client (that is, a client written in any language that interacts with the Webservices framework), must establish a secure session with Oracle CRM On Demand. Afterauthentication, the client interacts with the published Oracle CRM On Demand Web Services toperform data retrieval, modification, creation, and deletion operations. Oracle CRM On Demand andthe client format requests and resulting data as standard XML/SOAP messages.There are multiple ways in which client applications can establish authenticated sessions with OracleCRM On Demand. These sessions can be managed by the client or by the Oracle CRM On Demandserver based on the login mechanism used to establish the session.Server-Side ManagementTo establish a session that is managed on the Oracle CRM On Demand server:■ A company must have stateless Web services support enabled, see “Enabling Stateless Web Services Support” on page 32.■ The WS-I login mechanism must be used with the correct namespace and formats as described by the WS-I basic security profile http://www.ws-i.org/Profiles/BasicSecurityProfile- 1.0.html#UsernameToken: ■ The users login credentials must be supplied in the request. ■ The WSSE security namespace (http://docs.oasis-open.org/wss/2004/01/oasis-200401- wss-wssecurity-secext-1.0.xsd) must be specified in the request.Requests that meet these criteria qualify as stateless requests. Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 35 Release 18)
  36. 36. Establishing and Managing the Web Services Session ■ Server-Side SessionManagementClient-Side ManagementAll other login methods establish sessions that must be managed by the client application. Theselogin methods include:■ HTTP GET Request■ Single Sign On■ Sending a request with login credentials.Server-Side Session ManagementInteractive applications can be developed such that a users credentials are supplied within a requestsent to Oracle CRM On Demand, eliminating the need for an explicit login request. If the requestqualifies as a stateless request (see “Server-Side Management” on page 35), the Oracle CRM OnDemand server checks to see whether a session has already been established for that user. If asession is found, it is re-used for the new request. If no existing session is found for the user, a newsession is established. Each user is limited in the number of concurrent sessions that they canestablish.When a request is received by the server, a server ID value is returned in the response. This valuedoes not identify a specific user session, but rather is used to identify the server in the Oracle CRMOn Demand environment on which the session has been created. Subsequent requests can be sentthat include the server ID value, thus ensuring that the request is routed to the same server as theoriginal request.NOTE: Providing a server ID in subsequent requests is optional, however it is recommended that thisvalue is included.The ability to supply a user’s credentials is due to support for the UserNameToken profile of the WS-I Basic Security Profile Version 1.0. In this case, the SOAP header contains the element<wsse:UsernameToken>, which has child elements containing a username and password: <soap:Header> <wsse:Security soap:mustUnderstand="1"> <wsse:UsernameToken> <wsse:Username>admin@test.com</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- username-token-profile-1.0#PasswordText">adminOnDemand</wsse:Password> </wsse:UsernameToken> </wsse:Security> </soap:Header>NOTE: URL encoding of login credentials is not supported when they are provided in the SOAPsecurity headers.36 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  37. 37. Establishing and Managing the Web Services Session ■ Client-Side Session ManagementYou cannot explicitly log off from a stateless session; it will eventually time out or be reused, or couldbe destroyed by server-side session management routines.Client-Side Session ManagementIn instances in which the application manages the creation and release of user sessions, the followingapply:■ Clients must make login and logoff calls in their code to manage the session.■ The login step returns an HTTP cookie that contains the session identifier that must be used for making additional requests.■ A session remains active until the user explicitly logs out or until the session times out.Web services session management is HTTP-based and uses a session ID (also known as aJSESSIONID), which is contained in HTTP Session cookies, to uniquely identify a session establishedwith Oracle CRM On Demand.Oracle CRM On Demand Web Services enable session management by first creating a session usingthe login call, which is then referenced in any subsequent SOAP operations.In an Oracle SOAP session, after a session ID has been created in a login request, it can bereferenced in one of these ways:■ The session ID can be attached as a parameter to the URL request line. When a session ID is present in the URL line, it is identified by the string “jsessionid” in lowercase, followed by the exact session ID, which is coded using URL syntax.■ The session ID can be part of the cookie header line. When a session ID is referenced as a cookie, a cookie header line must appear in the SOAP request with the name JSESSIONID=. In this case, the session ID appears in uppercase, and the value of the cookie is exactly the same as the session ID received from the login request. NOTE: This is the recommended approach to referencing the session ID, for several reasons. The Java servlet specification advises the use of cookies and not the URL wherever possible. Most development environments and programming languages are efficient in using cookies rather than adding arguments to the URL. Furthermore, it is much simpler to implement cookies because the cookie container from the Oracle CRM On Demand login response can be copied onto further requests being sent to Oracle CRM On Demand.Unless the SOAP operation qualifies as stateless, a valid Oracle session ID must be provided for therequest to be processed.When a login request is made, the session ID is returned as a cookie in the response to the request.The client is responsible for extracting this session ID and using it throughout the session. If thesession times out for any reason, the error returned reports that the session is not valid and theclient must then request a new session. In this case, no explicit logoff operation is required.To issue a logoff request to terminate a session, the request must identify the session using theJSESSIONID value.All requests must use Secure Sockets Layer (SSL) over HTTP (HTTPS). Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 37 Release 18)
  38. 38. Establishing and Managing the Web Services Session ■ Stateful Login MechanismsStateful Login MechanismsThe following topics describe the various mechanisms for logging in and making integration requestswhen making stateful Web services requests.Logging in Using HTTP GETAn HTTPS request can be used to instantiate an Oracle CRM On Demand Web services session andobtain a valid session ID. A client invokes login by sending an HTTP GET request to a URL like thefollowing: https://secure-ausomx[ENV].crmondemand.com/Services/Integration?command=loginwhere [ENV] is the three-letter identifier for your company’s environment. If you do not know whatthis value is for your company, refer to the URL you use to access the Oracle CRM On Demand UI.NOTE: The login parameter value is case sensitive.Login InputThere are different mechanisms for login depending on whether the login header contains URLencoding with the UTF-8 encoding system. This is necessary when login credentials contain multi-byte characters.The input to login is provided in the URL parameters and the HTTP headers, as follows:■ Two URL parameters: ■ command, which has the value login ■ isEncoded, which is used if the HTTP headers are URL encoded using UTF-8. This parameter must have the value Y or y if encoding is required. The default value is N or n.■ Two HTTP headers, UserName and Password, must be set with the appropriate values for your system. For example: ■ UserName: johndoe@email.com ■ Password: mypass The HTPP headers can be in clear text, or can be URL encoded.Login OutputThe login command returns the following items:■ A session cookie, JSESSIONID. The client must use this cookie when submitting subsequent requests, including logoff requests.■ A status code of 200, if the session does not encounter any errors. This indicates that the request succeeded.38 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  39. 39. Establishing and Managing the Web Services Session ■ Stateful Login MechanismsFor code samples for logging in, see: https://codesamples.samplecode.oracle.com/servlets/Scarab/action/ExecuteQuery?query=crm_on_demandIt is also possible to log in at the same time as making an integration request; for more information,see “Integration Requests for the Web Services Session” on page 40.Logging in Using Single Sign-OnThe Single Sign-On (SSO) feature of CRM On Demand allows companies to integrate the hostedOracle CRM On Demand service with other systems that have the ability to manage user credentialsand authentication.If your company has been set up to use SSO for Oracle CRM On Demand, the following steps areused to log in and retrieve the session ID.1 The Web service client makes a request with the following command specifying the SSO Company Identifier. https://server/Services/Integration?command=ssoitsurl&ssoid=company-sso-id2 The server returns the SSO ITS URL in the "X-SsoItsUrl" HTTP header of the response3 The Web service makes a request with the ITS URL and retrieves a session ID.For detailed information about Single Sign-On, refer to the White Paper available from CustomerCare.For code samples for single sign-on see: https://codesamples.samplecode.oracle.com/servlets/Scarab/action/ExecuteQuery?query=crm_on_demandThe outbound SSO feature allows users who have signed into Oracle CRM On Demand using SSO topass the SSO credentials from Oracle CRM On Demand to third-party sites such as corporate Webpages or intranets. This allows users to embed or access third-party sites from within Oracle CRM OnDemand.Outbound SSO in Oracle CRM On Demand uses a proprietary method to generate a hashed messageauthentication code (HMAC) token that is passed to the third-party site. This third-party site makesa request back to Oracle CRM On Demand with the token. Oracle CRM On Demand then validates thetoken and provides a username back to the third-party site, or authenticates the token and providesa session ID to the user.Outbound SSO MethodsTwo methods are available as part of outbound SSO:1 SSO Token Validation. The following steps are used to validate an SSO token: a The third-party application makes a request with the following command specifying the SSO token: b https://server/Services/SSOTokenValidate?odSsoToken = "ssotoken value" c The server returns the username in the response. Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 39 Release 18)
  40. 40. Establishing and Managing the Web Services Session ■ Logging Out of the WebServices Session2 Login using SSO Token. The following steps are used to obtain a session ID using the SSO token: a The third party application makes a request with the following command specifying the SSO token: b https://server/Services/Integration?command=ssologin&odSsoToken="ssotoken value" c The server returns the session ID in the response, which is used for access to data within Oracle CRM On Demand.For detailed information about outbound SSO, refer to the Customer Care Portal - Web servicesresource library.Integration Requests for the Web Services SessionAn integration request is an HTTPS request to invoke a Web service to perform data creation,retrieval, update, and deletion operations. An integration request is made by an HTTP POSTcommand to a URL like the following: https://secure-ausomx[ENV].crmondemand.com/Services/Integration/objectwhere object is the name of the relevant Oracle CRM On Demand object (record type). This OracleCRM On Demand object is determined from the contents of the SOAP request.Integration request input. The JSESSIONID returned to the client during login must be includedwith the request. The request must contain the JSESSIONID either as a cookie or as a URL parameter,as follows: https://secure-ausomx[ENV].crmondemand.com/Services/Integration/object; jsessionid=xyZ12489w3482413The Web service input is provided as a SOAP command in the body of the HTTP POST request.Integration request output. The properties returned by the HTTP server populate the responseheaders and the response body. Table 6 shows the top-level properties that specify key properties ofthe HTTP response.Table 6. Properties of the HTTP Response Property Comments HttpStatus Status code returned in the response. If no value is provided, the response is given the value 200 (indicating success). Content-Type Content type returned in the response. If no value is provided, the response is given the value text/xml.Logging Out of the Web Services SessionA client logs out by sending an HTTP POST or HTTP GET request to a URL. For example:40 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  41. 41. Establishing and Managing the Web Services Session ■ Logging Out of the Web Services Session https://secure-ausomx[ENV].crmondemand.com/Services/Integration?command=logoff;NOTE: The parameter value logoff is case sensitive.Logoff InputThe preferred method is where the JSESSIONID returned to the client during login must be includedwith the request as a cookie with the same name. There are no other URL parameters or HTTPheaders, and there is no HTTP body.Logoff OutputA status code of 200 is returned if the request is received by the Oracle CRM On Demand server. Thisdoes not guarantee that the logoff request has been processed, and there may be a delay until thesession resources are released for use by a new Web services session.Alternative LogoffThe JSESSIONID can be included in the URL instead of a cookie if the user wants. The following URLis what the user would use, where XXXX is the JSESSIONID. https://secure-ausomx[ENV].crmondemand.com/Services/ Integration;jsessionid=XXXX?command=logoff Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 41 Release 18)
  42. 42. Establishing and Managing the Web Services Session ■ Logging Out of the WebServices Session42 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  43. 43. 5 Best Practices for Designing Client ApplicationsThis chapter provides best practice recommendations that allow you to design client applications thatinterface optimally with Oracle CRM On Demand using Web Services On Demand. It contains thefollowing topics:■ “Best Practices for Integration Design” on page 43 ■ “Sending of Web Services Requests to Oracle CRM On Demand” on page 44 ■ “Flushing of Caches” on page 44 ■ “Using Stateless Web Services” on page 45 ■ “Setting and Querying Blank Values” on page 46 ■ “Working with Opportunity Product Revenue Records” on page 47 ■ “Error Handling and Logging” on page 47 ■ “Handling Outages and Failures” on page 47 ■ “Best Practices for Generating Web Services Proxy Classes in Java Environments” on page 48 ■ “Avoiding Proxy Class Compilation Failure Due to the Java 64KB Limit” on page 49 ■ “Entering Telephone Number Values through Web Services” on page 52■ “Best Practices for Integration Performance” on page 54 ■ “Batch Processing” on page 54 ■ “Session Management and Pooling” on page 55 ■ “API Calls” on page 56■ “Best Practices for Integration Management” on page 58 ■ “Moving Customers Between Pods” on page 58 ■ “Handling Outages” on page 58 ■ “Maintaining SSL Certificates” on page 59Best Practices for Integration DesignThis topic describes best practices for optimizing the design of client applications. Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 43 Release 18)
  44. 44. Best Practices for Designing Client Applications ■ Best Practices for Integration DesignSending of Web Services Requests to Oracle CRM OnDemandOracle CRM On Demand processes Web services requests in a synchronous manner, therefore clientapplications using a single session must send requests in a synchronous manner. If the clientapplication needs to send messages asynchronously, multiple sessions must be used.Flushing of CachesIn Oracle CRM On Demand, there are internal caches that store metadata information such as fieldcustomization data, access or privilege settings, book information and so on.For stateless Web services only, users can flush the caches to reload any metadata information thathas changed recently. You use the MetadataChangeSummaryQueryPage method to determinewhether there have been any metadata changes; see “MetadataChangeSummaryQueryPage” onpage 109.In the case of session-based Web services (stateful Web Services), the same flushing of caches wouldonly occur on logging in again.Best PracticesThe best practices for flushing of the caches are as follows:■ You are advised not to flush caches unless really necessary, because it affects throughput.■ If you detect stale metadata, you use a flush cache flag to reload the caches.You can use the MetadataChangeSummaryQueryPage method to check whether the metadata haschanged.UsageTo flush the caches, you include the SOAP header element <FlushCache> in requests. The elementcan contain the values true or 1 to indicate that caches are to be flushed. Any other value isconsidered as false.The following shows a SOAP message containing the <FlushCache> element:<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"><soap:Header><wsse:Security><wsse:UsernameToken>44 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  45. 45. Best Practices for Designing Client Applications ■ Best Practices for Integration Design <wsse:Username>user@ondemand.com</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password></wsse:UsernameToken></wsse:Security><FlushCache xmlns=”urn:crmondemand/ws”>true</FlushCache></soap:Header><soap:Body>... Input request or payload here ......</soap:Body></soap:Envelope>Using Stateless Web ServicesIt is recommended that you use stateless Web services as opposed to stateful Web services wheneverpossible. Stateless Web services use server resources more efficiently and reduce the cost ofimplementation as customers do not need to implement session pooling and so on in clientapplications.The best practices for stateless Web services are described in the following sections.NOTE: The best practices for stateful Web services operations must also be applied to the use ofstateless Web services; see “Session Management and Pooling” on page 55.Using Sessions IDsIt is recommended that stateful and stateless Web services calls are not mixed. For example, thefollowing is not recommended:1 Login is performed and the JSESSIONID captured.2 A stateless Web services call is issued along with the JSESSIONID.This sequence results in the stateless Web service call using the session associated with theJSESSIONID and will therefore not be a stateless request. The JSESSIONID will not be invalidatedafter processing the request and the user must perform a log off because the session was createdthrough an implicit login.Hence, ideally users must not mix the two mechanisms.You should only use a session ID value when it is necessary to maintain a session across multiplerequests, for example, when paging across multiple pages of records in a QueryPage request whena snapshot of the data is required, or when an SSO Token is used to establish a session with OracleCRM On Demand. Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 45 Release 18)
  46. 46. Best Practices for Designing Client Applications ■ Best Practices for Integration DesignFor stateless requests, a session ID is returned to the client application. To maintain server affinity,the session ID returned by the initial request must be returned in subsequent requests. (This is thedefault behavior of most development platforms, in that the cookie is returned with the nextrequest). This session ID does not identify a specific session as it does for stateful requests, howeverit does identify the specific server on which the session resides. Including this session ID forsubsequent requests ensures that the request is routed to the correct server (not doing so may resultin the subsequent request being routed to another server and the establishment of a new session onthat server).Avoid Multiple Concurrent RequestsAvoid issuing multiple concurrent requests for the same application unless absolutely required. If youdo send multiple concurrent requests, and if you receive a RIP_WAIT error, or server unavailableerror, the server might be busy due to the number of concurrent requests it is handling. If thishappens, do one of the following:■ If possible, try the request again later, as the load on the server may decrease. Most load conditions should be rare and temporary. You may never see one during development.■ Retry with an exponential backoff. The client can be implemented such that retries are issued automatically using an exponential retry rate (that is, retries occur after 100ms, 200ms, 400ms, 1600ms and so on).■ Contact Oracle CRM On Demand Customer Care to increase the resources.Use Sort Criteria when Using QueryPageIf the QueryPage method is used as a stateless transaction, each request for an additional page ofdata returns any records that have been added or updated since the initial query. Any records thathave been deleted since the first request will no longer appear in the result set.Therefore, always use sort criteria to avoid returning the same record when paging through resultsusing the QueryPage method: ■ Use sort criteria on the Id field, which helps in most simple cases. ■ Use a stateful QueryPage Web service request, if it is required to paginate through a snapshot of data.Setting and Querying Blank ValuesWhen updating or querying for blank values the best practice is to specify isNull instead of leavingthe value blank.As an example, the AccountName and Location fields form a user key for updating or queryingAccount records. Location is not a required field, therefore a null or blank value can be set for thisfield. The best practice is therefore to specify isNull for Location instead of blank.46 Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand Release 18)
  47. 47. Best Practices for Designing Client Applications ■ Best Practices for Integration DesignWorking with Opportunity Product Revenue RecordsWhen implementing a client application that inserts or both inserts and updates Product Revenuerecords associated with an Opportunity, it is important to ensure that the Revenue record isassociated not only with the Opportunity but also with a Product record. This is because OpportunityRevenue records that do not have an associated Product will not appear within the Oracle CRM OnDemand UI. These records will appear in Forecast and Opportunity revenue roll-up but are noteditable using the UI or Web services.Error Handling and LoggingError handling and logging are essential when developing a client application. The client applicationmust provide for:■ Logging of detailed information about the error observed.■ Logging of the body and header information of all SOAP requests and responses. For the resolution of some errors, the actual SOAP request can be extremely useful in identifying the root cause of a problem.■ A call stack, which can be extremely important when analyzing problems and can provide useful hints that may reveal contributing factors to the problem.■ Entry points wrapped in log messages. The ability to identify entry and exit of Web service calls is important when analyzing issues.■ 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.■ End points that are not hard-coded.■ Dynamic server name and protocol configurationHandling Outages and FailuresThe client application must contain a mechanism to recognize when the Oracle CRM On Demandapplication is not available, and be able to persist in a dormant state. This mechanism can either beachieved manually or programmatically; for example:■ A process can become dormant if it receives a HTTP 404 error message and retry after several minutes.■ A process can alert an administrator and shut down after x failed attempts.A situation may arise where it is unknown if an operation has succeeded or not. In this situation, ifthe client application can detect duplicate errors, you can retry an insert operation with Oracle CRMOn Demand user keys allowing you to uniquely identify records. You can identify lost updates byexamining modification dates on records. Oracle Web Services On Demand Guide Version 6.0 (Oracle CRM On Demand 47 Release 18)

×