Web Services API Developer's Guide - David Pier

861 Pages·2011·9.14 MB·English

Version 21.0: Spring '11
Web Services API Developer's Guide
Last updated:April 18, 2011
© Copyright 2000-2011 salesforce.com, inc. All rights reserved. Salesforce.com is a registered trademark of salesforce.com, inc., as are other
names and marks. Other marks appearing herein may be trademarks of their respective owners.

Table of Contents
Table of Contents
Getting Started.........................................................................................................................11
Chapter 1:Introducing the API.........................................................................................11
When to Use the Web Services API................................................................................................................12
Customize, Integrate, and Extend Your Salesforce Solutions..........................................................................13
Supported Salesforce Editions.........................................................................................................................13
Standards Compliance.....................................................................................................................................14
Development Platforms...................................................................................................................................14
API Support Policy..........................................................................................................................................14
Choosing a WSDL..........................................................................................................................................15
Related Resources ...........................................................................................................................................15
What’s New in Version 21.0............................................................................................................................16
Quick Start......................................................................................................................................................20
Chapter 2:Standard and Custom Object Basics .................................................................32
Primitive Data Types.......................................................................................................................................33
Field Types.......................................................................................................................................................35
API Data Types and Salesforce Field Types....................................................................................................39
Core Data Types Used in API Calls................................................................................................................40
System Fields...................................................................................................................................................57
Required Fields................................................................................................................................................59
Frequently-Occurring Fields............................................................................................................................59
API Field Properties........................................................................................................................................60
Relationships Among Objects.........................................................................................................................61
Relabeling Fields and Tabs and the API..........................................................................................................62
Force.com AppExchange Object Prefixes and the API...................................................................................62
Custom Objects...............................................................................................................................................62
Chapter 3:API Call Basics................................................................................................65
Characteristics of API Calls............................................................................................................................66
Factors that Affect Data Access.......................................................................................................................66
Package Version Settings.................................................................................................................................68
Chapter 4:Error Handling................................................................................................70
Error Handling for Session Expiration ...........................................................................................................71
More About Error Handling...........................................................................................................................71
Chapter 5:Security and the API........................................................................................72
User Authentication.........................................................................................................................................73
User Profile Configuration...............................................................................................................................73
Security Token.................................................................................................................................................73
Sharing............................................................................................................................................................74
i
Table of Contents
Implicit Restrictions for Objects and Fields....................................................................................................75
API Access in Force.com AppExchange Packages..........................................................................................75
Outbound Port Restrictions.............................................................................................................................77
Chapter 6:Using the Partner WSDL.................................................................................78
Obtaining the Partner WSDL File..................................................................................................................79
Calls and the Partner WSDL .........................................................................................................................79
Objects, Fields, and Field Data and the Partner WSDL.................................................................................80
Queries and the Partner WSDL......................................................................................................................80
Namespaces in the Partner WSDL..................................................................................................................81
Package Versions and the Partner WSDL.......................................................................................................81
User Interface Themes.....................................................................................................................................82
Examples..........................................................................................................................................................82
Reference..................................................................................................................................90
Chapter 7:Data Model.....................................................................................................90
Sales Objects....................................................................................................................................................91
Task and Event Objects...................................................................................................................................92
Support Objects...............................................................................................................................................93
Document, Note, and Attachment Objects.....................................................................................................94
User and Profile Objects..................................................................................................................................94
Record Type Objects........................................................................................................................................95
Product and Schedule Objects.........................................................................................................................96
Sharing and Team Selling Objects...................................................................................................................97
Customizable Forecasting Objects...................................................................................................................98
Territory Management.....................................................................................................................................99
Process Objects..............................................................................................................................................100
Content Objects............................................................................................................................................101
Salesforce Chatter Objects.............................................................................................................................102
Chapter 8: Standard Objects...........................................................................................104
Account..........................................................................................................................................................114
AccountContactRole.....................................................................................................................................124
AccountFeed..................................................................................................................................................126
AccountHistory.............................................................................................................................................128
AccountOwnerSharingRule..........................................................................................................................129
AccountPartner..............................................................................................................................................131
AccountShare.................................................................................................................................................133
AccountTag....................................................................................................................................................135
AccountTeamMember...................................................................................................................................136
AccountTerritoryAssignmentRule.................................................................................................................137
AccountTerritoryAssignmentRuleItem.........................................................................................................138
AccountTerritorySharingRule.......................................................................................................................140
ActivityHistory..............................................................................................................................................141
AdditionalNumber.........................................................................................................................................146
ii
Table of Contents
ApexClass......................................................................................................................................................147
ApexComponent............................................................................................................................................148
ApexLog........................................................................................................................................................150
ApexPage.......................................................................................................................................................151
ApexTrigger...................................................................................................................................................153
Approval........................................................................................................................................................156
Article Type__DataCategorySelection..........................................................................................................158
Article Type__Feed........................................................................................................................................159
Asset..............................................................................................................................................................162
AssetFeed.......................................................................................................................................................164
AssetTag........................................................................................................................................................167
AssignmentRule.............................................................................................................................................168
AsyncApexJob................................................................................................................................................169
Attachment....................................................................................................................................................170
Bookmark......................................................................................................................................................173
BrandTemplate..............................................................................................................................................174
BusinessHours...............................................................................................................................................175
BusinessProcess..............................................................................................................................................178
CallCenter.....................................................................................................................................................180
Campaign......................................................................................................................................................181
CampaignFeed...............................................................................................................................................187
CampaignMember.........................................................................................................................................190
CampaignMemberStatus...............................................................................................................................192
CampaignOwnerSharingRule.......................................................................................................................193
CampaignShare.............................................................................................................................................194
CampaignTag................................................................................................................................................195
Case...............................................................................................................................................................196
CaseComment...............................................................................................................................................202
CaseContactRole ..........................................................................................................................................204
CaseFeed........................................................................................................................................................205
CaseHistory...................................................................................................................................................207
CaseMilestone...............................................................................................................................................208
CaseOwnerSharingRule................................................................................................................................210
CaseShare......................................................................................................................................................211
CaseSolution..................................................................................................................................................212
CaseStatus.....................................................................................................................................................213
CaseTag.........................................................................................................................................................214
CaseTeamMember.........................................................................................................................................215
CaseTeamRole...............................................................................................................................................216
CaseTeamTemplate.......................................................................................................................................217
CaseTeamTemplateMember..........................................................................................................................217
CaseTeamTemplateRecord............................................................................................................................218
CategoryData.................................................................................................................................................218
CategoryNode................................................................................................................................................219
CategoryNodeLocalization............................................................................................................................221
iii
Table of Contents
CollaborationGroup.......................................................................................................................................223
CollaborationGroupFeed...............................................................................................................................225
CollaborationGroupMember.........................................................................................................................228
CollaborationGroupMemberRequest............................................................................................................229
CollaborationInvitation.................................................................................................................................230
Community....................................................................................................................................................232
Contact..........................................................................................................................................................232
ContactFeed...................................................................................................................................................239
ContactHistory..............................................................................................................................................242
ContactOwnerSharingRule...........................................................................................................................243
ContactShare.................................................................................................................................................244
ContactTag....................................................................................................................................................245
ContentDocument.........................................................................................................................................246
ContentDocumentFeed.................................................................................................................................248
ContentDocumentHistory.............................................................................................................................251
ContentDocumentLink.................................................................................................................................252
ContentVersion..............................................................................................................................................253
ContentVersionHistory..................................................................................................................................259
ContentWorkspace........................................................................................................................................260
ContentWorkspaceDoc..................................................................................................................................261
Contract.........................................................................................................................................................263
ContractContactRole ....................................................................................................................................268
ContractFeed.................................................................................................................................................269
ContractHistory.............................................................................................................................................272
ContractLineItem..........................................................................................................................................273
ContractLineItemHistory..............................................................................................................................275
ContractStatus...............................................................................................................................................277
ContractTag...................................................................................................................................................278
CronTrigger...................................................................................................................................................278
CurrencyType................................................................................................................................................280
Custom Object__Feed...................................................................................................................................281
Dashboard......................................................................................................................................................284
DashboardComponent..................................................................................................................................286
DashboardComponentFeed...........................................................................................................................287
DashboardFeed..............................................................................................................................................289
DashboardTag................................................................................................................................................292
DatedConversionRate....................................................................................................................................292
Division.........................................................................................................................................................293
DivisionLocalization......................................................................................................................................295
Document......................................................................................................................................................296
DocumentAttachmentMap...........................................................................................................................300
DocumentTag................................................................................................................................................300
EmailMessage................................................................................................................................................301
EmailServicesAddress....................................................................................................................................303
EmailServicesFunction..................................................................................................................................305
iv
Table of Contents
EmailStatus....................................................................................................................................................309
EmailTemplate..............................................................................................................................................310
Entitlement....................................................................................................................................................313
EntitlementContact.......................................................................................................................................315
EntitlementHistory.......................................................................................................................................316
EntitlementTemplate.....................................................................................................................................317
EntityHistory.................................................................................................................................................318
EntitySubscription.........................................................................................................................................319
Event..............................................................................................................................................................321
EventAttendee...............................................................................................................................................330
EventFeed......................................................................................................................................................332
EventTag.......................................................................................................................................................334
FeedComment...............................................................................................................................................335
FeedItem........................................................................................................................................................337
FeedLike........................................................................................................................................................340
FeedPost.........................................................................................................................................................342
FeedTrackedChange......................................................................................................................................344
FiscalYearSettings..........................................................................................................................................347
Folder.............................................................................................................................................................350
ForecastShare.................................................................................................................................................352
GoogleDoc....................................................................................................................................................353
Group............................................................................................................................................................354
GroupMember...............................................................................................................................................356
Holiday..........................................................................................................................................................357
Idea................................................................................................................................................................360
IdeaComment................................................................................................................................................363
KnowledgeArticle..........................................................................................................................................364
KnowledgeArticleVersion..............................................................................................................................365
KnowledgeArticleViewStat...........................................................................................................................369
KnowledgeArticleVoteStat............................................................................................................................370
Lead...............................................................................................................................................................371
LeadFeed.......................................................................................................................................................383
LeadHistory...................................................................................................................................................386
LeadOwnerSharingRule................................................................................................................................387
LeadShare......................................................................................................................................................388
LeadStatus.....................................................................................................................................................389
LeadTag.........................................................................................................................................................390
LineitemOverride..........................................................................................................................................391
LoginHistory.................................................................................................................................................393
MailmergeTemplate.......................................................................................................................................395
MilestoneType...............................................................................................................................................397
Name.............................................................................................................................................................398
NewsFeed......................................................................................................................................................400
Note...............................................................................................................................................................403
NoteAndAttachment.....................................................................................................................................404
v
Table of Contents
NoteTag.........................................................................................................................................................405
OpenActivity.................................................................................................................................................406
Opportunity...................................................................................................................................................410
OpportunityCompetitor................................................................................................................................416
OpportunityContactRole...............................................................................................................................418
OpportunityFeed...........................................................................................................................................419
OpportunityFieldHistory..............................................................................................................................421
OpportunityHistory.......................................................................................................................................422
OpportunityLineItem....................................................................................................................................424
OpportunityLineItemSchedule......................................................................................................................428
OpportunityOverride.....................................................................................................................................431
OpportunityOwnerSharingRule....................................................................................................................434
OpportunityPartner.......................................................................................................................................435
OpportunityShare..........................................................................................................................................436
OpportunitySplit...........................................................................................................................................437
OpportunityStage..........................................................................................................................................439
OpportunityTag.............................................................................................................................................440
OpportunityTeamMember............................................................................................................................441
OrgWideEmailAddress.................................................................................................................................442
Organization..................................................................................................................................................443
Partner...........................................................................................................................................................452
PartnerNetworkConnection...........................................................................................................................454
PartnerNetworkRecordConnection...............................................................................................................455
PartnerRole ...................................................................................................................................................458
Period.............................................................................................................................................................459
Pricebook2.....................................................................................................................................................461
PricebookEntry .............................................................................................................................................464
ProcessInstance..............................................................................................................................................465
ProcessInstanceHistory..................................................................................................................................467
ProcessInstanceStep.......................................................................................................................................468
ProcessInstanceWorkitem..............................................................................................................................469
Product2 ........................................................................................................................................................470
Product2Feed.................................................................................................................................................475
ProductEntitlementTemplate........................................................................................................................478
Profile............................................................................................................................................................479
QuantityForecast............................................................................................................................................481
QuantityForecastHistory...............................................................................................................................486
Question........................................................................................................................................................488
QuestionDataCategorySelection...................................................................................................................489
QueueSobject.................................................................................................................................................490
Quote.............................................................................................................................................................491
QuoteDocument............................................................................................................................................497
QuoteLineItem..............................................................................................................................................498
RecordType....................................................................................................................................................501
RecordTypeLocalization................................................................................................................................503
vi
Table of Contents
Reply..............................................................................................................................................................504
Report............................................................................................................................................................505
ReportFeed....................................................................................................................................................507
ReportTag......................................................................................................................................................509
RevenueForecast............................................................................................................................................510
RevenueForecastHistory................................................................................................................................515
Scontrol..........................................................................................................................................................516
ScontrolLocalization......................................................................................................................................519
SelfServiceUser..............................................................................................................................................522
ServiceContract.............................................................................................................................................524
ServiceContractHistory.................................................................................................................................528
ServiceContractOwnerSharingRule..............................................................................................................529
ServiceContractShare....................................................................................................................................530
Site.................................................................................................................................................................531
SiteDomain....................................................................................................................................................534
SiteHistory.....................................................................................................................................................535
SlaProcess......................................................................................................................................................536
Solution.........................................................................................................................................................537
SolutionFeed..................................................................................................................................................539
SolutionHistory.............................................................................................................................................542
SolutionStatus................................................................................................................................................542
SolutionTag...................................................................................................................................................543
StaticResource................................................................................................................................................544
TagDefinition................................................................................................................................................546
Task................................................................................................................................................................548
TaskFeed........................................................................................................................................................554
TaskPriority...................................................................................................................................................556
TaskStatus......................................................................................................................................................557
TaskTag.........................................................................................................................................................558
Territory.........................................................................................................................................................559
User................................................................................................................................................................561
UserAccountTeamMember............................................................................................................................575
UserFeed........................................................................................................................................................577
UserLicense....................................................................................................................................................580
UserPreference...............................................................................................................................................582
UserProfileFeed..............................................................................................................................................583
UserRole........................................................................................................................................................586
UserTeamMember.........................................................................................................................................588
UserTerritory.................................................................................................................................................589
Vote................................................................................................................................................................590
WebLink........................................................................................................................................................592
WebLinkLocalization....................................................................................................................................597
Chapter 9:Core Calls......................................................................................................601
convertLead().................................................................................................................................................602
vii
Table of Contents
create()...........................................................................................................................................................607
delete()...........................................................................................................................................................612
emptyRecycleBin().........................................................................................................................................615
getDeleted()...................................................................................................................................................618
getUpdated()..................................................................................................................................................621
invalidateSessions()........................................................................................................................................624
login()............................................................................................................................................................626
logout()..........................................................................................................................................................629
merge()...........................................................................................................................................................630
process().........................................................................................................................................................633
query()............................................................................................................................................................636
queryAll().......................................................................................................................................................689
queryMore()...................................................................................................................................................691
retrieve().........................................................................................................................................................695
search()...........................................................................................................................................................696
undelete().......................................................................................................................................................718
update()..........................................................................................................................................................720
upsert()...........................................................................................................................................................725
Chapter 10:Describe Calls..............................................................................................730
describeDataCategoryGroups().....................................................................................................................730
describeDataCategoryGroupStructures().......................................................................................................733
describeGlobal().............................................................................................................................................737
describeLayout()............................................................................................................................................740
describeSObject()...........................................................................................................................................748
describeSObjects().........................................................................................................................................750
describeSoftphoneLayout()............................................................................................................................761
describeTabs()................................................................................................................................................765
Chapter 11:Utility Calls..................................................................................................768
getServerTimestamp()...................................................................................................................................768
getUserInfo().................................................................................................................................................769
resetPassword()..............................................................................................................................................772
sendEmail()....................................................................................................................................................773
setPassword().................................................................................................................................................781
Chapter 12:SOAP Headers.............................................................................................783
AllOrNoneHeader.........................................................................................................................................784
AllowFieldTruncationHeader........................................................................................................................785
AssignmentRuleHeader.................................................................................................................................786
CallOptions...................................................................................................................................................787
DisableFeedTrackingHeader.........................................................................................................................789
EmailHeader..................................................................................................................................................790
LocaleOptions...............................................................................................................................................791
LoginScopeHeader........................................................................................................................................792
MruHeader....................................................................................................................................................793
viii