Metadata API Developer Guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 765

Download
Open PDF In Browser	View PDF

Metadata API Developer Guide
Version 39.0, Spring ’17

@salesforcedocs
Last updated: April 17, 2017

as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.

CONTENTS
GETTING STARTED

.................................................1

Chapter 1: Understanding Metadata API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Supported Salesforce Editions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Development Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Standards Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Metadata API Support Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Related Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 2: Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 1: Generate or Obtain the Web Service WSDLs for Your Organization
Step 2: Import the WSDL Files Into Your Development Platform . . . . . . . .
Step 3: Walk Through the Java Sample Code . . . . . . . . . . . . . . . . . . .

.
.
.
.

4
4
5
6

USING METADATA API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Chapter 3: Declarative (File-Based) Metadata API Calls . . . . . . . . . . . . . . . . . . . . . . . 15
Working with the Zip File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Sample package.xml Manifest Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Running Tests in a Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Running a Subset of Tests in a Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Run the Same Tests in Sandbox and Production Deployments . . . . . . . . . . . . . . . . . . . . . . . 25
Maintaining User References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Chapter 4: CRUD-Based Metadata API Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Chapter 5: Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Error Handling for Session Expiration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

REFERENCE

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Chapter 6: File-Based Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
deploy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Deleting Components from an Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
checkDeployStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
cancelDeploy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
deployRecentValidation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
retrieve() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
RetrieveRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Contents

checkRetrieveStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Chapter 7: CRUD-Based Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
createMetadata() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
readMetadata() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
updateMetadata() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
upsertMetadata() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
deleteMetadata() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
renameMetadata() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
update() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Chapter 8: Utility Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
checkStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
describeMetadata() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
describeValueType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
listMetadata() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
ListMetadataQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Chapter 9: Result Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
AsyncResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
CancelDeployResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
DeployResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
DescribeMetadataResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
DescribeValueTypeResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
ReadResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
RetrieveResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
SaveResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
DeleteResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
UpsertResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Chapter 10: Metadata Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Metadata Components and Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Unsupported Metadata Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Special Behavior in Metadata API Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
ActionLinkGroupTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
AnalyticSnapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
ArticleType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
ArticleType Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
ChannelLayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
ArticleType CustomField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
ApexClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
ApexComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Contents

ApexPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
ApexTestSuite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
ApexTrigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
AppMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
ApprovalProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
AssignmentRules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
AuraDefinitionBundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
AuthProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
AutoResponseRules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
CallCenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
CampaignInfluenceModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
CleanDataService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Community (Zone) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
CommunityTemplateDefinition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
CommunityThemeDefinition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
ConnectedApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
ContentAsset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
CorsWhitelistOrigin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
CspTrustedSite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
CustomApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
CustomApplicationComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
CustomFeedFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
CustomLabels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Custom Metadata Types (CustomObject) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
CustomMetadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
CustomObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
ActionOverride . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
BusinessProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
CompactLayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
CustomField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
FieldSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
HistoryRetentionPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
ListView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
NamedFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Picklist (Including Dependent Picklist) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
RecordType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
SearchLayouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
SharingReason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
SharingRecalculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
ValidationRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
WebLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Metadata Field Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
CustomObjectTranslation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Contents

CustomPageWebLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
CustomPermission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
CustomSite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
CustomTab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
CustomValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
DataCategoryGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
DelegateGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
DuplicateRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
EclairGeoData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
EmailTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
EntitlementProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
EntitlementTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
EscalationRules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
ExternalDataSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
FlexiPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
ExternalServiceRegistration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
FlowDefinition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
FolderShare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
GlobalPicklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
GlobalPicklistValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
GlobalValueSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
GlobalValueSetTranslation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
HomePageComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
HomePageLayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
InstalledPackage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
KeywordList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Letterhead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
LiveChatAgentConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
LiveChatButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
LiveChatDeployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
LiveChatSensitiveDataRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
ManagedTopics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
MatchingRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
MetadataWithContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
MilestoneType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
ModerationRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
NamedCredential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

Contents

Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
PathAssistant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
PermissionSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
PlatformCachePartition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
PostTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
ProfileActionOverride . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
QuickAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
RemoteSiteSetting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
ReportType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
Role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
RoleOrTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
SamlSsoConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
Scontrol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
AccountSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
ActivitiesSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
AddressSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563
BusinessHoursSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
CaseSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571
ChatterAnswersSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
CompanySettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
ContractSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
EntitlementSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
FileUploadAndDownloadSecuritySettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
ForecastingSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
IdeasSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598
KnowledgeSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
LeadConvertSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
LiveAgentSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
MobileSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
NameSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
OpportunitySettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611
OrderSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
OrgPreferenceSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
PathAssistantSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616
PersonalJourneySettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
ProductSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
QuoteSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618
SearchSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619

Contents

SecuritySettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
Territory2Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
SharedTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
SharingBaseRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
SharingRules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633
BaseSharingRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639
CriteriaBasedSharingRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
OwnerSharingRule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
SharingSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
SiteDotCom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
Skill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
StandardValueSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
StandardValueSetTranslation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659
StaticResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
SynonymDictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664
Territory2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665
Territory2Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
Territory2Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
Territory2Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
TransactionSecurityPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
Translations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
UserCriteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686
WaveApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
WaveDataflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
WaveDashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689
WaveDataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
WaveLens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
WaveTemplateBundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
Wavexmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698

Chapter 11: Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
AllOrNoneHeader .
CallOptions . . . . .
DebuggingHeader
SessionHeader . . .

APPENDICES

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720

Appendix A: CustomObjectTranslation Language Support: Fully Supported
Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720

Contents

Appendix B: CustomObjectTranslation Language Support: End-User
Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
Appendix C: StandardValueSet Names and Standard Picklist Fields . . . 733
GLOSSARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
INDEX

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750

GETTING STARTED

CHAPTER 1

Understanding Metadata API

Use Metadata API to retrieve, deploy, create, update or delete customization information, such as custom object definitions and page
layouts, for your organization. This API is intended for managing customizations and for building tools that can manage the metadata
model, not the data itself. To create, retrieve, update or delete records, such as accounts or leads, use data SOAP API or REST API.
The easiest way to access the functionality in Metadata API is to use the Force.com IDE or Force.com Migration Tool. Both tools are built
on top of Metadata API and use the standard Eclipse and Ant tools, respectively, to simplify working with Metadata API.
• Force.com IDE is built on the Eclipse platform, for programmers familiar with integrated development environments. Code, compile,
test, and deploy from within the IDE.
• The Force.com Migration Tool is ideal if you use a script or the command line for moving metadata between a local directory and a
Salesforce org.
For more information about the Force.com IDE or Force.com Migration Tool, see developer.salesforce.com.
The underlying calls of Metadata API have been exposed for you to use directly, if you prefer to build your own client applications. This
guide gives you more information about working directly with Metadata API.
You can use the Metadata API to manage setup and customization information (metadata) for your organizations. For example:
• Export the customizations in your organization as XML metadata files. See Working with the Zip File and retrieve().
• Migrate configuration changes between organizations. See deploy() and retrieve().
• Modify existing customizations in your organization using XML metadata files. See deploy() and retrieve().
• Manage customizations in your organization programmatically. See CRUD-Based Metadata Development.
You can modify metadata in test organizations on Developer Edition or sandbox, and then deploy tested changes to production
organizations on Enterprise, Unlimited, or Performance Editions. You can also create scripts to populate a new organization with your
custom objects, custom fields, and other components.
SEE ALSO:
Deploying and Retrieving Metadata
CRUD-Based Metadata Development
Metadata Components and Types

Supported Salesforce Editions
To use Metadata API, your organization must use Enterprise Edition, Unlimited Edition, Performance Edition, or Developer Edition.
If you are an existing Salesforce customer and want to upgrade to Enterprise, Unlimited, or Performance Edition, contact your account
representative.
It is strongly recommended that you use a sandbox, which is an exact replica of your production organization. Enterprise, Unlimited,
and Performance Editions come with free developer sandboxes. For more information, see
http://www.salesforce.com/platform/cloud-infrastructure/sandbox.jsp.

Understanding Metadata API

Development Platforms

Alternatively, you can use a Developer Edition org, which provides access to all of the features available with Enterprise Edition, but is
limited by the number of users and the amount of storage space. A Developer Edition org isn’t a copy of your production org, but it
provides an environment where you can build and test your solutions without affecting your organization’s data. Developer Edition
accounts are available for free at http://developer.salesforce.com/signup.
Note: A metadata component must be visible in the org for Metadata API to act on it. Also, a user must have the “API Enabled”
permission to have access to metadata components.

Metadata API Access for Professional Edition
ISV partners can request Metadata API access to Professional Edition orgs for apps that have passed the AppExchange Security Review.
Access is granted through an API token (client ID). This special key enables the app to make Metadata API calls to customers’ Professional
Edition orgs.
As an ISV partner, you can request Metadata API access by following these steps.
1. Submit your app for security review. See Steps in the Security Review in the ISVForce Guide.
2. After your app is approved, log a case in the Partner Community in AppExchange and Feature Requests > API Token Request,
and specify SOAP for the type of token.
To make calls to the Metadata API, append the API token to the CallOptions SOAP header in your calls.

Development Platforms
Metadata API supports both file-based and CRUD-based development.

File-Based Development
The declarative or file-based asynchronous Metadata API deploy() and retrieve() operations deploy or retrieve a .zip file
that holds components in a set of folders, and a manifest file named package.xml. For more information, see Deploying and Retrieving
Metadata on page 15. The easiest way to access the file-based functionality is to use the Force.com IDE or Force.com Migration Tool.

CRUD-Based Development
The CRUD Metadata API calls act upon the metadata components in a manner similar to the way synchronous API calls in the enterprise
WSDL act upon objects. For more information about the enterprise WSDL, see the SOAP API Developer's Guide.

Standards Compliance
Metadata API is implemented to comply with the following specifications:
Standard Name

Website

Simple Object Access Protocol (SOAP) 1.1

http://www.w3.org/TR/2000/NOTE-SOAP-20000508/

Web Service Description Language (WSDL) http://www.w3.org/TR/2001/NOTE-wsdl-20010315
1.1
WS-I Basic Profile 1.1

http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html

Understanding Metadata API

Metadata API Support Policy

Metadata API Support Policy
Salesforce supports previous versions of Metadata API. However, your new client applications should use the most recent version of the
Force.com Metadata API WSDL file to fully exploit the benefits of richer features and greater efficiency.

Backward Compatibility
Salesforce strives to make backward compatibility easy when using the Force.com platform.
Each new Salesforce release consists of two components:
• A new release of platform software that resides on Salesforce systems
• A new version of the API
For example, the Spring '07 release included API version 9.0 and the Summer '07 release included API version 10.0.
We maintain support for each API version across releases of the platform software. The API is backward compatible in that an application
created to work with a given API version will continue to work with that same API version in future platform software releases.
Salesforce does not guarantee that an application written against one API version will work with future API versions: Changes in method
signatures and data representations are often required as we continue to enhance the API. However, we strive to keep the API consistent
from version to version with minimal, if any, changes required to port applications to newer API versions.
For example, an application written using API version 9.0, which shipped with the Spring ’07 release, will continue to work with API
version 9.0 on the Summer ’07 release, and on future releases beyond that. However, that same application might not work with API
version 10.0 without modifications to the application.

API End-of-Life
Salesforce is committed to supporting each API version for a minimum of three years from the date of first release. In order to mature
and improve the quality and performance of the API, versions that are more than three years old might cease to be supported.
When an API version is to be deprecated, advance notice is given at least one year before support ends. Salesforce will directly notify
customers using API versions planned for deprecation.

Related Resources
The Salesforce developer website provides a full suite of developer toolkits, sample code, sample SOAP messages, community-based
support, and other resources to help you with your development projects. Be sure to visit
https://developer.salesforce.com/page/Getting_Started for more information, or visit
http://developer.salesforce.com/signup to sign up for a free Developer Edition account.
You can visit these websites to find out more about Salesforce applications:
• Salesforce Developers provides a wealth of information for developers.
• Salesforce for information about the Salesforce application.
• Force.com AppExchange for access to apps created for Salesforce.
• Salesforce.com Community for services to ensure Salesforce customer success.

CHAPTER 2

Quick Start

Use Metadata API to retrieve, deploy, create, update, or delete customizations for your org. The most common use is to migrate changes
from a sandbox or testing org to your production environment. Metadata API is intended for managing customizations and for building
tools that can manage the metadata model, not the data itself.
However, the underlying calls of Metadata API have been exposed for you to use directly, if you prefer to build your own client applications.
This quick start gives you all the information you need to start writing applications that directly use Metadata API to manage customizations
for your organization. It shows you how to get started with File-Based Development. For an example of CRUD-Based Development, see
Java Sample for CRUD-Based Development with Synchronous Calls.

Prerequisites
Make sure you complete these prerequisites before you start using Metadata API.
• Create a development environment.
It is strongly recommended that you use a sandbox, which is an exact replica of your production organization. Enterprise, Unlimited,
and Performance Editions come with free developer sandboxes. For more information, see
http://www.salesforce.com/platform/cloud-infrastructure/sandbox.jsp.
Alternatively, you can use a Developer Edition org, which provides access to all of the features available with Enterprise Edition, but
is limited by the number of users and the amount of storage space. A Developer Edition org isn’t a copy of your production org, but
it provides an environment where you can build and test your solutions without affecting your organization’s data. Developer Edition
accounts are available for free at http://developer.salesforce.com/signup.
• Identify a user that has the “API Enabled” and “Modify All Data” permissions. These permissions are required to access Metadata API
calls.
• Install a SOAP client. Metadata API works with current SOAP development environments, including, but not limited to, Visual Studio®
.NET and the Force.com Web Service Connector (WSC).
In this document, we provide Java examples based on WSC and JDK 6 (Java Platform Standard Edition Development Kit 6). To run
the samples, first download the latest force-wsc JAR file and its dependencies (dependencies are listed on the page when you select
a version) from mvnrepository.com/artifact/com.force.api/force-wsc/.
Note: Development platforms vary in their SOAP implementations. Implementation differences in certain development
platforms might prevent access to some or all of the features in Metadata API.

Step 1: Generate or Obtain the Web Service WSDLs for Your
Organization
To access Metadata API calls, you need a Web Service Description Language (WSDL) file. The WSDL file defines the Web service that is
available to you. Your development platform uses this WSDL to generate stub code to access the Web service it defines. You can either

Quick Start

Step 2: Import the WSDL Files Into Your Development Platform

obtain the WSDL file from your organization’s Salesforce administrator, or you can generate it yourself if you have access to the WSDL
download page in the Salesforce user interface. For more information about WSDL, see http://www.w3.org/TR/wsdl.
Before you can access Metadata API calls, you must authenticate to use the Web service using the login() call, which is defined in
the enterprise WSDL and the partner WSDL. Therefore, you must also obtain one of these WSDLs.
Any user with the “Modify All Data” permission can download the WSDL file to integrate and extend the Salesforce platform. (The System
Administrator profile has this permission.)
The sample code in Step 3: Walk Through the Java Sample Code on page 6 uses the enterprise WSDL, though the partner WSDL works
equally well.
To generate the metadata and enterprise WSDL files for your organization:
1. Log in to your Salesforce account. You must log in as an administrator or as a user who has the “Modify All Data” permission.
2. From Setup, enter API in the Quick Find box, then select API.
3. Click Generate Metadata WSDL and save the XML WSDL file to your file system.
4. Click Generate Enterprise WSDL and save the XML WSDL file to your file system.

Step 2: Import the WSDL Files Into Your Development Platform
Once you have the WSDL files, import them into your development platform so that your development environment can generate the
necessary objects for use in building client Web service applications. This section provides sample instructions for WSC. For instructions
about other development platforms, see your platform’s product documentation.
Note: The process for importing WSDL files is identical for the metadata and enterprise WSDL files.

Instructions for Java Environments (WSC)
Java environments access the API through Java objects that serve as proxies for their server-side counterparts. Before using the API, you
must first generate these objects from your organization’s WSDL file.
Each SOAP client has its own tool for this process. For WSC, use the wsdlc utility.
Note: Before you run wsdlc, you must have the WSC JAR file installed on your system and referenced in your classpath. You
can download the latest force-wsc JAR file and its dependencies (dependencies are listed on the page when you select a version)
from mvnrepository.com/artifact/com.force.api/force-wsc/.
The basic syntax for wsdlc is:
java -classpath pathToWsc;pathToWscDependencies com.sforce.ws.tools.wsdlc
pathToWsdl/WsdlFilename pathToOutputJar/OutputJarFilename

For example, on Windows:
java –classpath force-wsc-30.0.0.jar;ST4-4.0.7.jar;antlr-runtime-3.5.jar
com.sforce.ws.tools.wsdlc metadata.wsdl metadata.jar

On Mac OS X and Unix, use a colon instead of a semicolon in between items in the classpath:
java –classpath force-wsc-30.0.0.jar:ST4-4.0.7.jar:antlr-runtime-3.5.jar
com.sforce.ws.tools.wsdlc metadata.wsdl metadata.jar

wsdlc generates a JAR file and Java source code and bytecode files for use in creating client applications. Repeat this process for the

enterprise WSDL to create an enterprise.JAR file.

Quick Start

Step 3: Walk Through the Java Sample Code

Step 3: Walk Through the Java Sample Code
When you have imported the WSDL files, you can build client applications that use Metadata API. The sample is a good starting point
for writing your own code.
Before you run the sample, modify your project and the code to:
1. Include the WSC JAR, its dependencies, and the JAR files you generated from the WSDLs.
Note: Although WSC has other dependencies, the following sample only requires Rhino (js-1.7R2.jar), which you can
download from mvnrepository.com/artifact/rhino/js.
2. Update USERNAME and PASSWORD variables in the MetadataLoginUtil.login() method with your user name and
password. If your current IP address isn’t in your organization's trusted IP range, you'll need to append a security token to the password.
3. If you are using a sandbox, be sure to change the login URL.

Login Utility
Java users can use ConnectorConfig to connect to Enterprise, Partner, and Metadata SOAP API. MetadataLoginUtil creates
a ConnectorConfig object and logs in using the Enterprise WSDL login method. Then it retrieves sessionId and
metadataServerUrl to create a ConnectorConfig and connects to Metadata API endpoint. ConnectorConfig is
defined in WSC.
The MetadataLoginUtil class abstracts the login code from the other parts of the sample, allowing portions of this code to be
reused without change across different Salesforce APIs.
import
import
import
import
import

com.sforce.soap.enterprise.EnterpriseConnection;
com.sforce.soap.enterprise.LoginResult;
com.sforce.soap.metadata.MetadataConnection;
com.sforce.ws.ConnectionException;
com.sforce.ws.ConnectorConfig;

/**
* Login utility.
*/
public class MetadataLoginUtil {
public static MetadataConnection login() throws ConnectionException {
final String USERNAME = "user@company.com";
// This is only a sample. Hard coding passwords in source files is a bad practice.
final String PASSWORD = "password";
final String URL = "https://login.salesforce.com/services/Soap/c/39.0";
final LoginResult loginResult = loginToSalesforce(USERNAME, PASSWORD, URL);
return createMetadataConnection(loginResult);
}
private static MetadataConnection createMetadataConnection(
final LoginResult loginResult) throws ConnectionException {
final ConnectorConfig config = new ConnectorConfig();
config.setServiceEndpoint(loginResult.getMetadataServerUrl());
config.setSessionId(loginResult.getSessionId());
return new MetadataConnection(config);
}

Quick Start

Step 3: Walk Through the Java Sample Code

private static LoginResult loginToSalesforce(
final String username,
final String password,
final String loginUrl) throws ConnectionException {
final ConnectorConfig config = new ConnectorConfig();
config.setAuthEndpoint(loginUrl);
config.setServiceEndpoint(loginUrl);
config.setManualLogin(true);
return (new EnterpriseConnection(config)).login(username, password);
}
}

Note: This example uses user and password authentication to obtain a session ID, which is then used for making calls to Metadata
API. Alternatively, you can use OAuth authentication. After you athenticate with OAuth to Salesforce, pass the returned access
token instead of the session ID. For example, pass the access token to the setSessionId() call on ConnectorConfig.
To learn how to use OAuth authentication in Salesforce, see Authenticating Apps with OAuth in the Salesforce Help.

Java Sample Code for File-Based Development
The sample code logs in using the login utility. Then it displays a menu with retrieve, deploy, and exit.
The retrieve() and deploy() calls both operate on a .zip file named components.zip. The retrieve() call retrieves
components from your organization into components.zip, and the deploy() call deploys the components in
components.zip to your organization. If you save the sample to your computer and execute it, run the retrieve option first so that
you have a components.zip file that you can subsequently deploy. After a retrieve call, the sample calls
checkRetrieveStatus() in a loop until the operation is completed. Similarly, after a deploy call, the sample checks
checkDeployStatus() in a loop until the operation is completed.
The retrieve() call uses a manifest file to determine the components to retrieve from your organization. A sample package.xml
manifest file follows. For more details on the manifest file structure, see Working with the Zip File. For this sample, the manifest file
retrieves all custom objects, custom tabs, and page layouts.

*
CustomObject

*
CustomTab

*
Layout

39.0

Note the error handling code that follows each API call.

Quick Start

Step 3: Walk Through the Java Sample Code

Note: This sample requires API version 34.0 or later.
import
import
import
import
import
import

java.io.*;
java.nio.channels.Channels;
java.nio.channels.FileChannel;
java.nio.channels.ReadableByteChannel;
java.rmi.RemoteException;
java.util.*;

import javax.xml.parsers.*;
import org.w3c.dom.*;
import org.xml.sax.SAXException;
import com.sforce.soap.metadata.*;
/**
* Sample that logs in and shows a menu of retrieve and deploy metadata options.
*/
public class FileBasedDeployAndRetrieve {
private MetadataConnection metadataConnection;
private static final String ZIP_FILE = "components.zip";
// manifest file that controls which components get retrieved
private static final String MANIFEST_FILE = "package.xml";
private static final double API_VERSION = 29.0;
// one second in milliseconds
private static final long ONE_SECOND = 1000;
// maximum number of attempts to deploy the zip file
private static final int MAX_NUM_POLL_REQUESTS = 50;
private BufferedReader reader = new BufferedReader(new InputStreamReader(System.in));

public static void main(String[] args) throws Exception {
FileBasedDeployAndRetrieve sample = new FileBasedDeployAndRetrieve();
sample.run();
}
public FileBasedDeployAndRetrieve() {
}
private void run() throws Exception {
this.metadataConnection = MetadataLoginUtil.login();
// Show the options to retrieve or deploy until user exits
String choice = getUsersChoice();
while (choice != null && !choice.equals("99")) {
if (choice.equals("1")) {

Quick Start

Step 3: Walk Through the Java Sample Code

retrieveZip();
} else if (choice.equals("2")) {
deployZip();
} else {
break;
}
// show the options again
choice = getUsersChoice();
}
}
/*
* Utility method to present options to retrieve or deploy.
*/
private String getUsersChoice() throws IOException {
System.out.println(" 1: Retrieve");
System.out.println(" 2: Deploy");
System.out.println("99: Exit");
System.out.println();
System.out.print("Enter 1 to retrieve, 2 to deploy, or 99 to exit: ");
// wait for the user input.
String choice = reader.readLine();
return choice != null ? choice.trim() : "";
}
private void deployZip() throws Exception {
byte zipBytes[] = readZipFile();
DeployOptions deployOptions = new DeployOptions();
deployOptions.setPerformRetrieve(false);
deployOptions.setRollbackOnError(true);
AsyncResult asyncResult = metadataConnection.deploy(zipBytes, deployOptions);
DeployResult result = waitForDeployCompletion(asyncResult.getId());
if (!result.isSuccess()) {
printErrors(result, "Final list of failures:\n");
throw new Exception("The files were not successfully deployed");
}
System.out.println("The file " + ZIP_FILE + " was successfully deployed\n");
}
/*
* Read the zip file contents into a byte array.
*/
private byte[] readZipFile() throws Exception {
byte[] result = null;
// We assume here that you have a deploy.zip file.
// See the retrieve sample for how to retrieve a zip file.
File zipFile = new File(ZIP_FILE);
if (!zipFile.exists() || !zipFile.isFile()) {
throw new Exception("Cannot find the zip file for deploy() on path:"
+ zipFile.getAbsolutePath());
}
FileInputStream fileInputStream = new FileInputStream(zipFile);
try {

Quick Start

Step 3: Walk Through the Java Sample Code

ByteArrayOutputStream bos = new ByteArrayOutputStream();
byte[] buffer = new byte[4096];
int bytesRead = 0;
while (-1 != (bytesRead = fileInputStream.read(buffer))) {
bos.write(buffer, 0, bytesRead);
}
result = bos.toByteArray();
} finally {
fileInputStream.close();
}
return result;
}
/*
* Print out any errors, if any, related to the deploy.
* @param result - DeployResult
*/
private void printErrors(DeployResult result, String messageHeader) {
DeployDetails details = result.getDetails();
StringBuilder stringBuilder = new StringBuilder();
if (details != null) {
DeployMessage[] componentFailures = details.getComponentFailures();
for (DeployMessage failure : componentFailures) {
String loc = "(" + failure.getLineNumber() + ", " +
failure.getColumnNumber();
if (loc.length() == 0 &&
!failure.getFileName().equals(failure.getFullName()))
{
loc = "(" + failure.getFullName() + ")";
}
stringBuilder.append(failure.getFileName() + loc + ":"
+ failure.getProblem()).append('\n');
}
RunTestsResult rtr = details.getRunTestResult();
if (rtr.getFailures() != null) {
for (RunTestFailure failure : rtr.getFailures()) {
String n = (failure.getNamespace() == null ? "" :
(failure.getNamespace() + ".")) + failure.getName();
stringBuilder.append("Test failure, method: " + n + "." +
failure.getMethodName() + " -- " + failure.getMessage() +
" stack " + failure.getStackTrace() + "\n\n");
}
}
if (rtr.getCodeCoverageWarnings() != null) {
for (CodeCoverageWarning ccw : rtr.getCodeCoverageWarnings()) {
stringBuilder.append("Code coverage issue");
if (ccw.getName() != null) {
String n = (ccw.getNamespace() == null ? "" :
(ccw.getNamespace() + ".")) + ccw.getName();
stringBuilder.append(", class: " + n);
}
stringBuilder.append(" -- " + ccw.getMessage() + "\n");
}

Quick Start

Step 3: Walk Through the Java Sample Code

}
}
if (stringBuilder.length() > 0) {
stringBuilder.insert(0, messageHeader);
System.out.println(stringBuilder.toString());
}
}

private void retrieveZip() throws Exception {
RetrieveRequest retrieveRequest = new RetrieveRequest();
// The version in package.xml overrides the version in RetrieveRequest
retrieveRequest.setApiVersion(API_VERSION);
setUnpackaged(retrieveRequest);
AsyncResult asyncResult = metadataConnection.retrieve(retrieveRequest);
RetrieveResult result = waitForRetrieveCompletion(asyncResult);
if (result.getStatus() == RetrieveStatus.Failed) {
throw new Exception(result.getErrorStatusCode() + " msg: " +
result.getErrorMessage());
} else if (result.getStatus() == RetrieveStatus.Succeeded) {
// Print out any warning messages
StringBuilder stringBuilder = new StringBuilder();
if (result.getMessages() != null) {
for (RetrieveMessage rm : result.getMessages()) {
stringBuilder.append(rm.getFileName() + " - " + rm.getProblem() + "\n");
}
}
if (stringBuilder.length() > 0) {
System.out.println("Retrieve warnings:\n" + stringBuilder);
}
System.out.println("Writing results to zip file");
File resultsFile = new File(ZIP_FILE);
FileOutputStream os = new FileOutputStream(resultsFile);
try {
os.write(result.getZipFile());
} finally {
os.close();
}
}
}
private DeployResult waitForDeployCompletion(String asyncResultId) throws Exception {
int poll = 0;
long waitTimeMilliSecs = ONE_SECOND;
DeployResult deployResult;
boolean fetchDetails;
do {
Thread.sleep(waitTimeMilliSecs);

Quick Start

Step 3: Walk Through the Java Sample Code

// double the wait time for the next iteration
waitTimeMilliSecs *= 2;
if (poll++ > MAX_NUM_POLL_REQUESTS) {
throw new Exception(
"Request timed out. If this is a large set of metadata components, "
+
"ensure that MAX_NUM_POLL_REQUESTS is sufficient.");
}
// Fetch in-progress details once for every 3 polls
fetchDetails = (poll % 3 == 0);
deployResult = metadataConnection.checkDeployStatus(asyncResultId, fetchDetails);
System.out.println("Status is: " + deployResult.getStatus());
if (!deployResult.isDone() && fetchDetails) {
printErrors(deployResult, "Failures for deployment in progress:\n");
}
}
while (!deployResult.isDone());
if (!deployResult.isSuccess() && deployResult.getErrorStatusCode() != null) {
throw new Exception(deployResult.getErrorStatusCode() + " msg: " +
deployResult.getErrorMessage());
}
if (!fetchDetails) {
// Get the final result with details if we didn't do it in the last attempt.
deployResult = metadataConnection.checkDeployStatus(asyncResultId, true);
}
return deployResult;
}
private RetrieveResult waitForRetrieveCompletion(AsyncResult asyncResult) throws
Exception {
// Wait for the retrieve to complete
int poll = 0;
long waitTimeMilliSecs = ONE_SECOND;
String asyncResultId = asyncResult.getId();
RetrieveResult result = null;
do {
Thread.sleep(waitTimeMilliSecs);
// Double the wait time for the next iteration
waitTimeMilliSecs *= 2;
if (poll++ > MAX_NUM_POLL_REQUESTS) {
throw new Exception("Request timed out. If this is a large set " +
"of metadata components, check that the time allowed " +
"by MAX_NUM_POLL_REQUESTS is sufficient.");
}
result = metadataConnection.checkRetrieveStatus(
asyncResultId, true);
System.out.println("Retrieve Status: " + result.getStatus());
} while (!result.isDone());

Quick Start

Step 3: Walk Through the Java Sample Code

return result;
}
private void setUnpackaged(RetrieveRequest request) throws Exception {
// Edit the path, if necessary, if your package.xml file is located elsewhere
File unpackedManifest = new File(MANIFEST_FILE);
System.out.println("Manifest file: " + unpackedManifest.getAbsolutePath());
if (!unpackedManifest.exists() || !unpackedManifest.isFile()) {
throw new Exception("Should provide a valid retrieve manifest " +
"for unpackaged content. Looking for " +
unpackedManifest.getAbsolutePath());
}
// Note that we use the fully quualified class name because
// of a collision with the java.lang.Package class
com.sforce.soap.metadata.Package p = parsePackageManifest(unpackedManifest);
request.setUnpackaged(p);
}
private com.sforce.soap.metadata.Package parsePackageManifest(File file)
throws ParserConfigurationException, IOException, SAXException {
com.sforce.soap.metadata.Package packageManifest = null;
List listPackageTypes = new ArrayList();
DocumentBuilder db =
DocumentBuilderFactory.newInstance().newDocumentBuilder();
InputStream inputStream = new FileInputStream(file);
Element d = db.parse(inputStream).getDocumentElement();
for (Node c = d.getFirstChild(); c != null; c = c.getNextSibling()) {
if (c instanceof Element) {
Element ce = (Element) c;
NodeList nodeList = ce.getElementsByTagName("name");
if (nodeList.getLength() == 0) {
continue;
}
String name = nodeList.item(0).getTextContent();
NodeList m = ce.getElementsByTagName("members");
List members = new ArrayList();
for (int i = 0; i < m.getLength(); i++) {
Node mm = m.item(i);
members.add(mm.getTextContent());
}
PackageTypeMembers packageTypes = new PackageTypeMembers();
packageTypes.setName(name);
packageTypes.setMembers(members.toArray(new String[members.size()]));
listPackageTypes.add(packageTypes);
}
}
packageManifest = new com.sforce.soap.metadata.Package();
PackageTypeMembers[] packageTypesArray =
new PackageTypeMembers[listPackageTypes.size()];
packageManifest.setTypes(listPackageTypes.toArray(packageTypesArray));
packageManifest.setVersion(API_VERSION + "");

Quick Start

Step 3: Walk Through the Java Sample Code

return packageManifest;
}
}

USING METADATA API

CHAPTER 3

Deploying and Retrieving Metadata

Use the deploy() and retrieve() calls to move metadata (XML files) between a Salesforce organization and a local file system.
Once you retrieve your XML files into a file system, you can manage changes in a source-code control system, copy and paste code or
setup configurations, diff changes to components, and perform many other file-based development operations. At any time you can
deploy those changes to another Salesforce organization.
Note: The Force.com IDE and the Force.com Migration Tool use the deploy() and retrieve() calls to move metadata. If
you use these tools, interaction with Metadata API is seamless and invisible. Therefore, most developers will find it much easier to
use these tools than write code that calls deploy() and retrieve() directly.
Data in XML files is formatted using the English (United States) locale. This ensures that fields that depend on locale, such as date fields,
are interpreted consistently during data migrations between organizations using different languages. Organizations can support multiple
languages for presentation to their users.
The deploy() and retrieve() calls are used primarily for the following development scenarios:
• Development of a custom application (or customization) in a sandbox organization. After development and testing is completed,
the application or customization is then deployed into a production organization using Metadata API.
• Team development of an application in a Developer Edition organization. After development and testing is completed, you can then
distribute the application via Force.com AppExchange.
SEE ALSO:
Metadata Components and Types
Unsupported Metadata Types

Working with the Zip File
The deploy() and retrieve() calls are used to deploy and retrieve a .zip file. Within the .zip file is a project manifest
(package.xml) that lists what to retrieve or deploy, and one or more XML components that are organized into folders.
Note: A component is an instance of a metadata type. For example, CustomObject is a metadata type for custom objects,
and the MyCustomObject__c component is an instance of a custom object.
The files that are retrieved or deployed in a .zip file might be unpackaged components that reside in your organization (such as standard
objects) or packaged components that reside within named packages.
Note: You can deploy or retrieve up to 10,000 files at once and the maximum size of the deployed or retrieved .zip file is 39 MB.
Note the following:
• If using the Force.com Migration Tool to deploy an unzipped folder, all files in the folder are compressed first. The maximum
size of uncompressed components in an unzipped folder is 400 MB or less depending on the compression ratio. If the files
have a high compression ratio, you can migrate a total of approximately 400 MB because the compressed size would be under
39 MB. However, if the components can't be compressed much, like binary static resources, you can migrate less than 400 MB.

Deploying and Retrieving Metadata

Working with the Zip File

• Metadata API base-64 encodes components after they’re compressed. The resulting .zip file can't exceed 50 MB, which is the
limit for SOAP messages. Base-64 encoding increases the size of the payload, so your compressed payload can't exceed
approximately 39 MB before encoding.
Every .zip file contains a project manifest, a file that’s named package.xml, and a set of directories that contain the components.
The manifest file defines the components that you’re trying to retrieve or deploy in the .zip file and the API version that’s used for the
deployment or retrieval.
The following is a sample package.xml file. Note that you can retrieve an individual component for a metadata type by specifying
its fullName field value in a members element, or you can also retrieve all components of a metadata type by using
*.

MyCustomObject__c
CustomObject

*
CustomTab

Standard
Profile

39.0

The following elements can be defined in package.xml.
• contains the name of the server-side package. If no exists, this is a client-side unpackaged
package.
• contains the name of the metadata type (for example, CustomObject) and the named members (for example,
myCustomObject__c) to be retrieved or deployed. You can add multiple elements in a manifest file.
• contains the fullName of the component, for example MyCustomObject__c. The listMetadata()
call is useful for determining the fullName for components of a particular metadata type, if you want to retrieve an individual
component. For many metadata types, you can replace the value in members with the wildcard character * (asterisk) instead of
listing each member separately. For a list of metadata types that allow the wildcard character, see the “Allows Wildcard (*)?” column
in Metadata Types.
Note: You specify Security in the element and Settings in the name element when retrieving the SecuritySettings
component type.
• contains the metadata type, for example CustomObject or Profile. There is one name defined for each metadata
type in the directory. Any metadata type that extends Metadata is a valid value. The name that’s entered must match a metadata
type that’s defined in the Metadata API WSDL. See Metadata Types for a list.
• is the API version number that’s used when the .zip file is deployed or retrieved. Currently the valid value is 39.0.
For more sample package.xml manifest files that show you how to work with different subsets of metadata, see Sample
package.xml Manifest Files.

Deploying and Retrieving Metadata

Sample package.xml Manifest Files

To delete components, see Deleting Components from an Organization.
SEE ALSO:
Metadata Types

Sample package.xml Manifest Files
This section includes sample package.xml manifest files that show you how to work with different subsets of metadata. A manifest
file can include multiple elements so you could combine the individual samples into one package.xml manifest file if
you want to work with all the metadata in one batch. For more information about the structure of a manifest file, see Working with the
Zip File. The following samples are listed:
• Standard Objects
• All Custom Objects
• Standard Picklist Fields
• Custom and Standard Fields
• List Views for Standard Objects
• Packages
• Security Settings
• Assignment Rules, Auto-response Rules, Escalation Rules
• Sharing Rules
• Managed Component Access

Standard Objects
This sample package.xml manifest file illustrates how to work with the standard Account object. Retrieving or deploying a standard
object includes all custom and standard fields except for standard fields that aren’t customizable. All custom fields are supported. Only
standard fields that you can customize are supported, that is, standard fields to which you can add help text or enable history tracking
or Chatter feed tracking. Other standard fields aren't supported, including system fields (such as CreatedById or
LastModifiedDate) and autonumber fields.

Account
CustomObject

39.0

Note how you work with the standard Account object by specifying it as a member of a CustomObject type. However, you cannot use
an asterisk wildcard to work with all standard objects; each standard object must be specified by name.

Deploying and Retrieving Metadata

Sample package.xml Manifest Files

All Custom Objects
This sample package.xml manifest file illustrates how to work with all custom objects.

*
CustomObject

39.0

This manifest file can be used to retrieve or deploy all custom objects. This does not include all standard objects.

Standard Picklist Fields
In API version 38.0 and later, the StandardValueSet type represents standard picklists. Picklists are no longer represented by fields as in
earlier versions. This sample package.xml represents the Industry standard picklist as a StandardValueSet type.

Industry
StandardValueSet

39.0

Note: The name of a standard value set is case-sensitive.
The Industry standard value set corresponds to the Account.Industry or Lead.Industry field in API version 37.0 and
earlier. This example shows a package.xml sample for the Account.Industry picklist.

Account.Industry
CustomField

37.0

Note: The name of a picklist field is case-sensitive.
Note the objectName.picklistField syntax in the field where objectName is the name of the object, such
as Account, and picklistField is the name of the standard picklist field, such as Industry.
This next package.xml sample represents opportunity team roles in API version 38.0 and later. Specify opportunity team roles as a
SalesTeamRole standard value set. Opportunity team roles have the same picklist values as the account team roles.

SalesTeamRole

Deploying and Retrieving Metadata

Sample package.xml Manifest Files

StandardValueSet

39.0

The SalesTeamRole standard value set corresponds to one of these field names in API version 37.0 and earlier:
OpportunityTeamMember.TeamMemberRole, UserAccountTeamMember.TeamMemberRole,
UserTeamMember.TeamMemberRole, and AccountTeamMember.TeamMemberRole. Opportunity team roles are
represented in this sample package.xml as the OpportunityTeamMember.TeamMemberRole field.

OpportunityTeamMember.TeamMemberRole
CustomField

37.0

To learn about the names of standard value sets and how they map to picklist field names, see StandardValueSet Names and Standard
Picklist Fields.

Custom and Standard Fields
This sample package.xml manifest file illustrates how to work with custom fields in custom and standard objects and standard
fields in a standard object.

MyCustomObject__c.MyCustomField__c
CustomField

Account.SLA__c
Account.Phone
CustomField

39.0

Note the objectName.field syntax in the field where objectName is the name of the object, such as Account,
and field is the name of the custom or standard field, such as an SLA picklist field representing a service-level agreement option.
The MyCustomField custom field in the MyCustomObject custom object is uniquely identified by its full name,
MyCustomObject__c.MyCustomField__c. Similarly, the Phone standard field in the Account standard object is uniquely
identified by its full name, Account.Phone.
All custom fields are supported. Only standard fields that you can customize are supported, that is, standard fields to which you can add
help text or enable history tracking or Chatter feed tracking. Other standard fields aren't supported, including system fields (such as
CreatedById or LastModifiedDate) and autonumber fields.

Deploying and Retrieving Metadata

Sample package.xml Manifest Files

List Views for Standard Objects
The easiest way to retrieve list views for a standard object is to retrieve the object. The list views are included in the retrieved component.
See Standard Objects on page 17.
You can also work with individual list views if you do not want to retrieve all the details for the object. This sample package.xml
manifest file illustrates how to work with a list view for the standard Account object.

Account.AccountTeam
ListView

39.0

Note the objectName.listViewUniqueName syntax in the field where objectName is the name of the
object, such as Account, and listViewUniqueName is the View Unique Name for the list view. If you retrieve this list view,
the component is stored in objects/Account.object.

Packages
To retrieve a package, set the name of the package in the packageNames field in RetrieveRequest when you call retrieve().
The package.xml manifest file is automatically populated in the retrieved .zip file. The element in package.xml
contains the name of the retrieved package.
If you use an asterisk wildcard in a element to retrieve all the components of a particular metadata type, the retrieved
contents do not include components in managed packages. For more information about managed packages, see the ISVforce Guide.
The easiest way to retrieve a component in a managed package is to retrieve the complete package by setting the name of the package
in the packageNames field in RetrieveRequest, as described above. The following sample package.xml manifest file illustrates
an alternative to retrieve an individual component in a package.

myns__MyCustomObject__c
CustomObject

39.0

Note the namespacePrefix__objectName syntax in the field where namespacePrefix is the namespace
prefix of the package and objectName is the name of the object. A namespace prefix is a 1 to 15-character alphanumeric identifier
that distinguishes your package and its contents from other publishers’ packages. For more information, see “Register a Namespace
Prefix” in the Salesforce Help.

Deploying and Retrieving Metadata

Sample package.xml Manifest Files

Security Settings
This sample package.xml manifest file illustrates how to work with an organization’s security settings. You specify Security in the
element and Settings in the name element when retrieving the SecuritySettings component type.

Security
Settings

39.0

Assignment Rules, Auto-response Rules, Escalation Rules
Assignment rules, auto-response rules and escalation rules use different package.xml type names to access sets of rules or individual
rules for object types. For example, the following sample package.xml manifest file illustrates how to access an organization’s
assignment rules for just Cases and Leads.

Case
Lead
AssignmentRules

39.0

The following sample package.xml manifest file illustrates how to access just the “samplerule” Case assignment rule and the
“newrule” Lead assignment rule. Notice that the type name is AssignmentRule and not AssignmentRules.

Case.samplerule
Lead.newrule
AssignmentRule

39.0

Similarly, for accessing individual auto-response rules and escalation rules, use AutoResponseRule and EscalationRule
instead of AutoResponseRules and EscalationRules.

Sharing Rules
In API version 33.0 and later, you can retrieve and deploy sharing rules for all standard and custom objects. This sample package.xml
manifest file illustrates how to work with an organization’s sharing rules, which includes retrieving a specific criteria-based sharing rule

Deploying and Retrieving Metadata

Sample package.xml Manifest Files

for the lead object, retrieving all ownership-based sharing rules for all objects, and retrieving all territory-based sharing rules for the
account object.

Lead.testShareRule
SharingCriteriaRule

*
SharingOwnerRule

Account.*
SharingTerritoryRule

33.0

Managed Component Access
In API version 29.0 and later, you can retrieve and deploy access settings for the following managed components in profiles and permission
sets:
• Apex classes
• Apps
• Custom field permissions
• Custom object permissions
• Custom tab settings
• External data sources
• Record types
• Visualforce pages
When retrieving and deploying managed component permissions, specify the namespace followed by two underscores. Wildcards are
not supported.
For example, let’s say you install a managed package with the namespace MyNamespace and the custom object JobRequest__c.
To set object permissions for JobRequest__c in the package to the custom profile MyProfile, you would add the following to the
.profile file.
To deploy:

true
true
true
true
false
false

Deploying and Retrieving Metadata

Running Tests in a Deployment

To retrieve:

MyNamespace__JobRequest__c
CustomObject

MyProfile
Profile

When retrieving permission sets and profiles, make sure that you also retrieve any components that are related to the permissions and
settings. For example, when retrieving app visibilities, you must also retrieve the associated app, and when retrieving object or field
permissions, you must also retrieve the associated object.

Running Tests in a Deployment
Default Test Execution in Production
When no test level is specified in the deployment options, the default test execution behavior depends on the contents of your deployment
package. When deploying to production, all tests, except those that originate from managed packages, are executed if your deployment
package contains Apex classes or triggers. If your package doesn’t contain Apex components, no tests are run by default.
In API version 33.0 and earlier, tests were run for components that required tests, such as custom objects, and not only for Apex
components. For example, if your package contains a custom object, all tests are run in API version 33.0 and earlier. In contrast, starting
with API version 34.0, no tests are run for this package. The API version corresponds to the version of your API client or the version of the
tool you’re using (Force.com Migration Tool).
You can run tests for a deployment of non-Apex components. You can override the default test execution behavior by setting the test
level in your deployment options. Test levels are enforced regardless of the types of components present in your deployment package.
We recommend that you run all local tests in your development environment, such as sandbox, before deploying to production. Running
tests in your development environment reduces the number of tests needed to run in a production deployment.

Default Test Execution in Production for API Version 33.0 and Earlier
For deployment to a production organization, all local tests in your organization are run by default. Tests that originate from installed
managed packages aren’t run by default. If any test fails, the entire deployment is rolled back.
If the deployment includes components for the following metadata types, all local tests are run.
• ApexClass
• ApexComponent
• ApexPage
• ApexTrigger
• ArticleType
• BaseSharingRule
• CriteriaBasedSharingRule
• CustomDataType
• CustomField
• CustomObject

Deploying and Retrieving Metadata

Running a Subset of Tests in a Deployment

• DataCategoryGroup
• Flow
• InstalledPackage
• NamedFilter
• OwnerSharingRule
• PermissionSet
• Profile
• Queue
• RecordType
• RemoteSiteSetting
• Role
• SharingReason
• Territory
• Validation Rules
• Workflow
For example, no tests are run for the following deployments:
• 1 CustomApplication component
• 100 Report components and 40 Dashboard components
All tests are run for the following deployments:
• 1 CustomField component
• 1 ApexComponent component and 1 ApexClass component
• 5 CustomField components and 1 ApexPage component
• 100 Report components, 40 Dashboard components, and 1 CustomField component
SEE ALSO:
deploy()

Running a Subset of Tests in a Deployment
Test levels enable you to have more control over which tests are run in a deployment. To shorten deployment time to production, run
a subset of tests when deploying Apex components. The default test execution behavior in production has also changed. By default, if
no test level is specified, no tests are executed, unless your deployment package contains Apex classes or triggers.
If the code coverage of an Apex component in the deployment is less than 75%, the deployment fails. If one of the specified tests fails,
the deployment also fails. We recommend that you test your deployment in sandbox first to ensure that the specified tests cover each
component sufficiently. Even if your organization’s overall code coverage is 75% or more, the individual coverage of the Apex components
being deployed can be less. If the code coverage requirement isn’t met, write more tests and include them in the deployment.
To run a subset of tests, set the RunSpecifiedTests test level on the DeployOptions object. Next, specify each test class to
run in DeployOptions. Finally, pass DeployOptions as an argument to the deploy() call. The following example performs
those steps to run only the specified test classes.
// Create the DeployOptions object.
DeployOptions deployOptions = new DeployOptions();

Deploying and Retrieving Metadata

Run the Same Tests in Sandbox and Production Deployments

// Set the appropriate test level.
deployOptions.setTestLevel(TestLevel.RunSpecifiedTests);
// Specify the test classes to run.
// String array contains test class names.
String[] tests = {"TestClass1", "TestClass2", "TestClass3"};
// Add the test class names array to the deployment options.
deployOptions.setRunTests(tests);
// Call deploy() by passing the deployment options object as an argument.
AsyncResult asyncResult = metadatabinding.deploy(zipBytes,deployOptions);

Notes About Running Specific Tests
• You can specify only test classes. You can’t specify individual test methods.
• We recommend that you refactor test classes to include the minimum number of tests that meet code coverage requirements.
Refactoring your test classes can contribute to shorter test execution times, and as a result, shorter deployment times.
• You can deactivate a trigger in the target organization by deploying it with an inactive state. However, the trigger must have been
previously deployed with an active state.

Run the Same Tests in Sandbox and Production Deployments
Starting in API version 34.0, you can choose which tests to run in your development environment, such as only local tests, to match the
tests run in production. In earlier versions, if you enabled tests in your sandbox deployment, you couldn’t exclude managed package
tests.
By default, no tests are run in a deployment to a non-production organization, such as a sandbox or a Developer Edition organization.
To specify tests to run in your development environment, set a testLevel deployment option. For example, to run local tests in a
deployment and to exclude managed package tests, set testLevel on the DeployOptions object to
TestLevel.RunLocalTests. Next, pass this object as an argument to the deploy() call as follows.
// Create the DeployOptions object.
DeployOptions deployOptions = new DeployOptions();
// Set the appropriate test level.
deployOptions.setTestLevel(TestLevel.RunLocalTests);
// Call deploy() by passing the deployment options object as an argument.
AsyncResult asyncResult = metadatabinding.deploy(zipBytes,deployOptions);

Note: The RunLocalTests test level is enforced regardless of the contents of the deployment package. In contrast, tests are
executed by default in production only if your deployment package contains Apex classes or triggers. You can use
RunLocalTests for sandbox and production deployments.

Maintaining User References
User fields are preserved during a metadata deployment.

Deploying and Retrieving Metadata

Maintaining User References

When a component in your deployment refers to a specific user, such as a recipient of a workflow email notification or a dashboard
running user, then Salesforce attempts to locate a matching user in the destination organization by comparing usernames during the
deployment.
For example, when you copy data to a sandbox, the fields containing usernames from the production organization are altered to include
the sandbox name. In a sandbox named test, the username user@acme.com becomes user@acme.com.test. When you
deploy the metadata in the sandbox to another organization, the test in the username is ignored.
For user references in deployments, Salesforce performs the following sequence:
1. Salesforce compares usernames in the source environment to the destination environment and adapts the organization domain
name.
2. If two or more usernames match, Salesforce lists the matching names and requests one of the users in the source environment be
renamed.
3. If a username in the source environment doesn’t exist in the destination environment, Salesforce displays an error, and the deployment
stops until the usernames are removed or resolved to users in the destination environment.

CHAPTER 4

CRUD-Based Metadata Development

Use the CRUD-based metadata calls to create, update, or delete setup and configuration components for your organization or application.
These configuration components include custom objects, custom fields, and other configuration metadata. The metadata calls mimic
the behavior in the Salesforce user interface for creating, updating, or deleting components. Whatever rules apply there also apply to
these calls.
Metadata calls are different from the core, synchronous API calls in the following ways:
• Metadata API calls are available in a separate WSDL. To download the WSDL, log into Salesforce, from Setup, enter API in the
Quick Find box, then select API and click the Download Metadata WSDL link.
• After logging in, you must send Metadata API calls to the Metadata API endpoint, which has a different URL than the SOAP API.
Retrieve the metadataServerUrl from the LoginResult returned by your SOAP API login() call. For more information
about the SOAP API, see the SOAP API Developer's Guide.
• Metadata calls are either synchronous or asynchronous. CRUD calls are synchronous in API version 30.0 and later, and similar to the
API core calls the results are returned in a single call. In earlier API versions, create, update, and delete are only asynchronous, which
means that the results are not immediately returned in one call.
• There are synchronous metadata calls that map to the corresponding core SOAP API synchronous calls.
– createMetadata() maps to the create() SOAP API call.
– updateMetadata() maps to the update() SOAP API call.
– deleteMetadata() maps to the delete() SOAP API call.
Note: Metadata API also supports retrieve() and deploy() calls for retrieving and deploying metadata components.
For more information, see Deploying and Retrieving Metadata.

Java Sample for CRUD-Based Development with Synchronous Calls
This section guides you through a sample Java client application that uses CRUD-based calls. This sample application performs the
following main tasks.
1. Uses the MetadataLoginUtil.java class to create a Metadata connection. For more information, see Step 3: Walk Through
the Java Sample Code.
2. Calls createMetadata() to create a custom object. This call returns the result in one call.
3. Inspects the returned SaveResult object to check if the operation succeeded, and if it didn’t, writes the component name, error
message, and status code to the output.
import com.sforce.soap.metadata.*;
/**
* Sample that logs in and creates a custom object through the metadata API
*/
public class CRUDSampleCreate {

CRUD-Based Metadata Development

private MetadataConnection metadataConnection;
// one second in milliseconds
private static final long ONE_SECOND = 1000;
public CRUDSampleCreate() {
}
public static void main(String[] args) throws Exception {
CRUDSampleCreate crudSample = new CRUDSampleCreate();
crudSample.runCreate();
}
/**
* Create a custom object. This method demonstrates usage of the
* create() and checkStatus() calls.
*
* @param uniqueName Custom object name should be unique.
*/
private void createCustomObjectSync(final String uniqueName) throws Exception {
final String label = "My Custom Object";
CustomObject co = new CustomObject();
co.setFullName(uniqueName);
co.setDeploymentStatus(DeploymentStatus.Deployed);
co.setDescription("Created by the Metadata API Sample");
co.setEnableActivities(true);
co.setLabel(label);
co.setPluralLabel(label + "s");
co.setSharingModel(SharingModel.ReadWrite);
// The name field appears in page layouts, related lists, and elsewhere.
CustomField nf = new CustomField();
nf.setType(FieldType.Text);
nf.setDescription("The custom object identifier on page layouts, related lists
etc");
nf.setLabel(label);
nf.setFullName(uniqueName);
customObject.setNameField(nf);
SaveResult[] results = metadataConnection
.createMetadata(new Metadata[] { co });
for (SaveResult r : results) {
if (r.isSuccess()) {
System.out.println("Created component: " + r.getFullName());
} else {
System.out
.println("Errors were encountered while creating "
+ r.getFullName());
for (Error e : r.getErrors()) {
System.out.println("Error message: " + e.getMessage());
System.out.println("Status code: " + e.getStatusCode());
}
}

CRUD-Based Metadata Development

}
}
private void runCreate() throws Exception {
metadataConnection = MetadataLoginUtil.login();
// Custom objects and fields must have __c suffix in the full name.
final String uniqueObjectName = "MyCustomObject__c";
createCustomObjectSync(uniqueObjectName);
}
}

Java Sample for CRUD-Based Development with Asynchronous Calls
Important: The sample in this section depends on the asynchronous create() CRUD call. Asynchronous CRUD calls are no
longer available as of API version 31.0 and are available only in earlier API versions.
This section guides you through a sample Java client application that uses asynchronous CRUD-based calls. This sample application
performs the following main tasks:
1. Uses the MetadataLoginUtil.java class to create a Metadata connection. For more information, see Step 3: Walk Through
the Java Sample Code.
2. Calls create() to create a new custom object.
Salesforce returns an AsyncResult object for each component you tried to create. The AsyncResult object is updated with status
information as the operation moves from a queue to completed or error state.
3. Calls checkStatus() in a loop until the status value in AsyncResult indicates that the create operation is completed.
Note the error handling code that follows each API call.
import com.sforce.soap.metadata.*;
/**
* Sample that logs in and creates a custom object through the metadata api
*/
public class CRUDSample {
private MetadataConnection metadataConnection;
// one second in milliseconds
private static final long ONE_SECOND = 1000;
public CRUDSample() {
}
public static void main(String[] args) throws Exception {
CRUDSample crudSample = new CRUDSample();
crudSample.runCreate();
}
/**
* Create a custom object. This method demonstrates usage of the
* create() and checkStatus() calls.
*
* @param uniqueName Custom object name should be unique.

CRUD-Based Metadata Development

*/
private void createCustomObject(final String uniqueName) throws Exception {
final String label = "My Custom Object";
CustomObject customObject = new CustomObject();
customObject.setFullName(uniqueName);
customObject.setDeploymentStatus(DeploymentStatus.Deployed);
customObject.setDescription("Created by the Metadata API Sample");
customObject.setLabel(label);
customObject.setPluralLabel(label + "s");
customObject.setSharingModel(SharingModel.ReadWrite);
// The name field appears in page layouts, related lists, and elsewhere.
CustomField nf = new CustomField();
nf.setType(FieldType.Text);
nf.setDescription("The custom object identifier on page layouts, related lists
etc");
nf.setLabel(label);
nf.setFullName(uniqueName);
customObject.setNameField(nf);
AsyncResult[] asyncResults = metadataConnection.create(
new CustomObject[]{customObject});
if (asyncResults == null) {
System.out.println("The object was not created successfully");
return;
}
long waitTimeMilliSecs = ONE_SECOND;
// After the create() call completes, we must poll the results of the checkStatus()
// call until it indicates that the create operation has completed.
do {
printAsyncResultStatus(asyncResults);
waitTimeMilliSecs *= 2;
Thread.sleep(waitTimeMilliSecs);
asyncResults = metadataConnection.checkStatus(new
String[]{asyncResults[0].getId()});
} while (!asyncResults[0].isDone());
printAsyncResultStatus(asyncResults);
}
private void printAsyncResultStatus(AsyncResult[] asyncResults) throws Exception {
if (asyncResults == null || asyncResults.length == 0 || asyncResults[0] == null)
{
throw new Exception("The object status cannot be retrieved");
}
AsyncResult asyncResult = asyncResults[0]; //we are creating only 1 metadata object

if (asyncResult.getStatusCode() != null) {
System.out.println("Error status code: " +

CRUD-Based Metadata Development

asyncResult.getStatusCode());
System.out.println("Error message: " + asyncResult.getMessage());
}
System.out.println("Object with id:" + asyncResult.getId() + " is " +
asyncResult.getState());
}
private void runCreate() throws Exception {
metadataConnection = MetadataLoginUtil.login();
// Custom objects and fields must have __c suffix in the full name.
final String uniqueObjectName = "MyCustomObject__c";
createCustomObject(uniqueObjectName);
}
}

CHAPTER 5

Error Handling

Metadata API calls return error information that your client application can use to identify and resolve runtime errors. The Metadata API
provides the following types of error handling:
• Since the Metadata API uses the enterprise or partner WSDLs to authenticate, it uses SOAP fault messages defined in those WSDLs
for errors resulting from badly formed messages, failed authentication, or similar problems. Each SOAP fault has an associated
ExceptionCode. For more details, see “Error Handling” in the SOAP API Developer's Guide.
• For errors with the asynchronous create(), update(), and delete() calls, see the error status code in the statusCode
field in the AsyncResult object for the associated component.
• For errors with the synchronous CRUD calls, see the error status code in the statusCode field of the Error object corresponding
to each error in the array returned by the errors field of the appropriate result object. For example, the result object of
createMetadata() is SaveResult.
• For errors with deploy(), see the problem and success fields in the DeployMessage object for the associated component.
• For errors with retrieve(), see the problem field in the RetrieveMessage object for the associated component.
For sample code, see Step 3: Walk Through the Java Sample Code on page 6.

Error Handling for Session Expiration
When you sign on via the login() call, a new client session begins and a corresponding unique session ID is generated. Sessions
automatically expire after the amount of time specified in the Security Controls setup area of the Salesforce application (default two
hours). When your session expires, the exception code INVALID_SESSION_ID is returned. If this happens, you must invoke the login()
call again. For more information about login(), see the SOAP API Developer's Guide.

REFERENCE

CHAPTER 6

File-Based Calls

Use the following file-based calls to deploy or retrieve XML components.
• deploy()
• deployRecentValidation()
• retrieve()

deploy()
Uses file representations of components to create, update, or delete those components in a Salesforce org.

Syntax
AsyncResult = metadatabinding.deploy(base64 zipFile, DeployOptions deployOptions)

Usage
Use this call to take file representations of components and deploy them into an org by creating, updating, or deleting the components
they represent.
Note: You can deploy or retrieve up to 10,000 files at once and the maximum size of the deployed or retrieved .zip file is 39 MB.
Note the following:
• If using the Force.com Migration Tool to deploy an unzipped folder, all files in the folder are compressed first. The maximum
size of uncompressed components in an unzipped folder is 400 MB or less depending on the compression ratio. If the files
have a high compression ratio, you can migrate a total of approximately 400 MB because the compressed size would be under
39 MB. However, if the components can't be compressed much, like binary static resources, you can migrate less than 400 MB.
• Metadata API base-64 encodes components after they’re compressed. The resulting .zip file can't exceed 50 MB, which is the
limit for SOAP messages. Base-64 encoding increases the size of the payload, so your compressed payload can't exceed
approximately 39 MB before encoding.
In API version 29.0, Salesforce improved the deployment status properties and removed the requirement to use checkStatus()
after a deploy() call to get information about deployments. Salesforce continues to support the use of checkStatus() when
using deploy() with API version 28.0 or earlier.
For API version 29.0 or later, deploy (create or update) packaged or unpackaged components using the following steps.
1. Issue a deploy() call to start the asynchronous deployment. An AsyncResult object is returned. Note the value in the id field
and use it for the next step.
2. Issue a checkDeployStatus() call in a loop until the done field of the returned DeployResult contains true, which means
that the call is completed. The DeployResult object contains information about an in-progress or completed deployment started

File-Based Calls

deploy()

using the deploy() call. When calling checkDeployStatus(), pass in the id value from the AsyncResult object from the
first step.
For API version 28.0 or earlier, deploy (create or update) packaged or unpackaged components using the following steps.
1. Issue a deploy() call to start the asynchronous deployment. An AsyncResult object is returned. If the call is completed, the done
field contains true. Most often, the call is not completed quickly enough to be noted in the first result. If it is completed, note the
value in the id field returned and skip the next step.
2. If the call is not complete, issue a checkStatus() call in a loop using the value in the id field of the AsyncResult object returned
by the deploy() call in the previous step. Check the AsyncResult object which is returned until the done field contains true.
The time taken to complete a deploy() call depends on the size of the zip file being deployed, so a longer wait time between
iterations should be used as the size of the zip file increases.
3. Issue a checkDeployStatus() call to obtain the results of the deploy() call, using the id value returned in the first step.
To track the status of deployments that are in progress or completed in the last 30 days, from Setup, enter Deployment Status
in the Quick Find box, then select Deployment Status.
You can cancel a deployment while it’s in progress or in the queue by clicking Cancel next to the deployment. The deployment then
has the status Cancel Requested until the deployment is completely canceled. A canceled deployment is listed in the Failed
section.
The package.xml file is a project manifest that lists all the components that you want to retrieve or deploy. You can use
package.xml to add components. To delete components, add another manifest file. See Deleting Components from an Organization.

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Arguments
Name

Type

Description

zipFile

base64

Base 64-encoded binary data. Client applications must encode the binary data as base64.

deployOptions DeployOptions Encapsulates options for determining which packages or files are deployed.

DeployOptions
The following deployment options can be selected for this call:
Name

Type

Description

allowMissingFiles

boolean

If files that are specified in package.xml are not in the
.zip file, specifies whether a deployment can still succeed.
Do not set this argument for deployment to production orgs.

autoUpdatePackage

boolean

If a file is in the .zip file but not specified in package.xml,
specifies whether the file is automatically added to the package.
A retrieve() is issued with the updated package.xml
that includes the .zip file.

File-Based Calls

Name

deploy()

Type

Description
Do not set this argument for deployment to production orgs.

checkOnly

boolean

Defaults to false. Set to true to perform a test deployment
(validation) of components without saving the components
in the target org. A validation enables you to verify the results
of tests that would be generated in a deployment, but doesn’t
commit any changes. After a validation finishes with passing
tests, it might qualify for deployment without rerunning tests.
See deployRecentValidation().

ignoreWarnings

boolean

Indicates whether a warning should allow a deployment to
complete successfully (true) or not (false). Defaults to
false.
The DeployMessage object for a warning contains the following
values:
• problemType—Warning
• problem—The text of the warning.
If a warning occurs and ignoreWarnings is set to true,
the success field in DeployMessage is true. If
ignoreWarnings is set to false, success is set to
false and the warning is treated like an error.
This field is available in API version 18.0 and later. Prior to
version 18.0, there was no distinction between warnings and
errors. All problems were treated as errors and prevented a
successful deployment.

performRetrieve

boolean

Indicates whether a retrieve() call is performed
immediately after the deployment (true) or not (false).
Set to true in order to retrieve whatever was just deployed.

purgeOnDelete

boolean

If true, the deleted components in the
destructiveChanges.xml manifest file aren't stored
in the Recycle Bin. Instead, they become immediately eligible
for deletion.
This field is available in API version 22.0 and later.
This option only works in Developer Edition or sandbox orgs;
it doesn't work in production orgs.

rollbackOnError

boolean

Indicates whether any failure causes a complete rollback
(true) or not (false). If false, whatever actions can be
performed without errors are performed, and errors are
returned for the remaining actions. This parameter must be
set to true if you are deploying to a production org. The
default is false.

File-Based Calls

deploy()

Name

Type

Description

runAllTests

boolean

(Deprecated and only available in API version 33.0 and earlier.)
This field defaults to false. Set to true to run all Apex tests
after deployment, including tests that originate from installed
managed packages.
Note: Apex tests that run as part of a deployment
always run synchronously and serially.

runTests

string[]

A list of Apex tests to run during deployment. Specify the class
name, one name per instance. The class name can also specify
a namespace with a dot notation. For more information, see
Running a Subset of Tests in a Deployment.
To use this option, set testLevel to
RunSpecifiedTests.

singlePackage

boolean

Indicates whether the specified .zip file points to a directory
structure with a single package (true) or a set of packages
(false).

testLevel

TestLevel (enumeration of type
string)

Optional. Specifies which tests are run as part of a deployment.
The test level is enforced regardless of the types of components
that are present in the deployment package. Valid values are:
• NoTestRun—No tests are run. This test level applies
only to deployments to development environments, such
as sandbox, Developer Edition, or trial organizations. This
test level is the default for development environments.
• RunSpecifiedTests—Only the tests that you specify
in the runTests option are run. Code coverage
requirements differ from the default coverage requirements
when using this test level. Each class and trigger in the
deployment package must be covered by the executed
tests for a minimum of 75% code coverage. This coverage
is computed for each class and trigger individually and is
different than the overall coverage percentage.
• RunLocalTests—All tests in your org are run, except
the ones that originate from installed managed packages.
This test level is the default for production deployments
that include Apex classes or triggers.
• RunAllTestsInOrg—All tests are run. The tests
include all tests in your org, including tests of managed
packages.
If you don’t specify a test level, the default test execution
behavior is used. See Running Tests in a Deployment.
Note: Apex tests that run as part of a deployment
always run synchronously and serially.

File-Based Calls

deploy()

Name

Type

Description
This field is available in API version 34.0 and later.

Response
AsyncResult

Sample Code—Java
This sample shows how to deploy components in a zip file. See the retrieve() sample code for details on how to retrieve a zip file.
package com.doc.samples;
import java.io.*;
import java.rmi.RemoteException;
import
import
import
import
import
import
import
import
import
import
import
import
import

com.sforce.soap.metadata.AsyncResult;
com.sforce.soap.metadata.DeployDetails;
com.sforce.soap.metadata.MetadataConnection;
com.sforce.soap.metadata.DeployOptions;
com.sforce.soap.metadata.DeployResult;
com.sforce.soap.metadata.DeployMessage;
com.sforce.soap.metadata.RunTestsResult;
com.sforce.soap.metadata.RunTestFailure;
com.sforce.soap.metadata.CodeCoverageWarning;
com.sforce.soap.enterprise.LoginResult;
com.sforce.soap.enterprise.EnterpriseConnection;
com.sforce.ws.ConnectionException;
com.sforce.ws.ConnectorConfig;

/**
* Deploy a zip file of metadata components.
* Prerequisite: Have a deploy.zip file that includes a package.xml manifest file that
* details the contents of the zip file.
*/
public class DeploySample {
// binding for the metadata WSDL used for making metadata API calls
private MetadataConnection metadataConnection;
static BufferedReader rdr = new BufferedReader(new InputStreamReader(System.in));
private static final String ZIP_FILE = "deploy.zip";
// one second in milliseconds
private static final long ONE_SECOND = 1000;
// maximum number of attempts to deploy the zip file
private static final int MAX_NUM_POLL_REQUESTS = 50;
public static void main(String[] args) throws Exception {
final String USERNAME = "user@company.com";

File-Based Calls

deploy()

// This is only a sample. Hard coding passwords in source files is a bad practice.
final String PASSWORD = "password";
final String URL = "https://login.salesforce.com/services/Soap/c/29.0";
DeploySample sample = new DeploySample(USERNAME, PASSWORD, URL);
sample.deployZip();
}
public DeploySample(String username, String password, String loginUrl)
throws ConnectionException {
createMetadataConnection(username, password, loginUrl);
}
public void deployZip()
throws RemoteException, Exception
{
byte zipBytes[] = readZipFile();
DeployOptions deployOptions = new DeployOptions();
deployOptions.setPerformRetrieve(false);
deployOptions.setRollbackOnError(true);
AsyncResult asyncResult = metadataConnection.deploy(zipBytes, deployOptions);
String asyncResultId = asyncResult.getId();
// Wait for the deploy to complete
int poll = 0;
long waitTimeMilliSecs = ONE_SECOND;
DeployResult deployResult = null;
boolean fetchDetails;
do {
Thread.sleep(waitTimeMilliSecs);
// double the wait time for the next iteration
waitTimeMilliSecs *= 2;
if (poll++ > MAX_NUM_POLL_REQUESTS) {
throw new Exception("Request timed out. If this is a large set " +
"of metadata components, check that the time allowed by " +
"MAX_NUM_POLL_REQUESTS is sufficient.");
}
// Fetch in-progress details once for every 3 polls
fetchDetails = (poll % 3 == 0);
deployResult = metadataConnection.checkDeployStatus(asyncResultId, fetchDetails);
System.out.println("Status is: " + deployResult.getStatus());
if (!deployResult.isDone() && fetchDetails) {
printErrors(deployResult, "Failures for deployment in progress:\n");
}
}
while (!deployResult.isDone());
if (!deployResult.isSuccess() && deployResult.getErrorStatusCode() != null) {
throw new Exception(deployResult.getErrorStatusCode() + " msg: " +
deployResult.getErrorMessage());
}

File-Based Calls

deploy()

if (!fetchDetails) {
// Get the final result with details if we didn't do it in the last attempt.
deployResult = metadataConnection.checkDeployStatus(asyncResultId, true);
}
if (!deployResult.isSuccess()) {
printErrors(deployResult, "Final list of failures:\n");
throw new Exception("The files were not successfully deployed");
}
System.out.println("The file " + ZIP_FILE + " was successfully deployed");
}
/**
* Read the zip file contents into a byte array.
* @return byte[]
* @throws Exception - if cannot find the zip file to deploy
*/
private byte[] readZipFile()
throws Exception
{
// We assume here that you have a deploy.zip file.
// See the retrieve sample for how to retrieve a zip file.
File deployZip = new File(ZIP_FILE);
if (!deployZip.exists() || !deployZip.isFile())
throw new Exception("Cannot find the zip file to deploy. Looking for " +
deployZip.getAbsolutePath());
FileInputStream fos = new FileInputStream(deployZip);
ByteArrayOutputStream bos = new ByteArrayOutputStream();
int readbyte = -1;
while ((readbyte = fos.read()) != -1) {
bos.write(readbyte);
}
fos.close();
bos.close();
return bos.toByteArray();
}

/**
* Print out any errors, if any, related to the deploy.
* @param result - DeployResult
*/
private void printErrors(DeployResult result, String messageHeader)
{
DeployDetails deployDetails = result.getDetails();
StringBuilder errorMessageBuilder = new StringBuilder();
if (deployDetails != null) {
DeployMessage[] componentFailures = deployDetails.getComponentFailures();
for (DeployMessage message : componentFailures) {
String loc = (message.getLineNumber() == 0 ? "" :

File-Based Calls

deploy()

("(" + message.getLineNumber() + "," +
message.getColumnNumber() + ")"));
if (loc.length() == 0
&& !message.getFileName().equals(message.getFullName())) {
loc = "(" + message.getFullName() + ")";
}
errorMessageBuilder.append(message.getFileName() + loc + ":" +
message.getProblem()).append('\n');
}
RunTestsResult rtr = deployDetails.getRunTestResult();
if (rtr.getFailures() != null) {
for (RunTestFailure failure : rtr.getFailures()) {
String n = (failure.getNamespace() == null ? "" :
(failure.getNamespace() + ".")) + failure.getName();
errorMessageBuilder.append("Test failure, method: " + n + "." +
failure.getMethodName() + " -- " +
failure.getMessage() + " stack " +
failure.getStackTrace() + "\n\n");
}
}
if (rtr.getCodeCoverageWarnings() != null) {
for (CodeCoverageWarning ccw : rtr.getCodeCoverageWarnings()) {
errorMessageBuilder.append("Code coverage issue");
if (ccw.getName() != null) {
String n = (ccw.getNamespace() == null ? "" :
(ccw.getNamespace() + ".")) + ccw.getName();
errorMessageBuilder.append(", class: " + n);
}
errorMessageBuilder.append(" -- " + ccw.getMessage() + "\n");
}
}
}
if (errorMessageBuilder.length() > 0) {
errorMessageBuilder.insert(0, messageHeader);
System.out.println(errorMessageBuilder.toString());
}
}
private void createMetadataConnection(
final String username,
final String password,
final String loginUrl) throws ConnectionException {
final ConnectorConfig loginConfig = new ConnectorConfig();
loginConfig.setAuthEndpoint(loginUrl);
loginConfig.setServiceEndpoint(loginUrl);
loginConfig.setManualLogin(true);
LoginResult loginResult = (new EnterpriseConnection(loginConfig)).login(
username, password);
final ConnectorConfig metadataConfig = new ConnectorConfig();
metadataConfig.setServiceEndpoint(loginResult.getMetadataServerUrl());
metadataConfig.setSessionId(loginResult.getSessionId());

File-Based Calls

Deleting Components from an Organization

this.metadataConnection = new MetadataConnection(metadataConfig);
}
}

IN THIS SECTION:
1. Deleting Components from an Organization
To delete components, perform a deployment with the deploy() call by using a destructive changes manifest file that lists the
components to remove from your organization. You can perform a deployment that only deletes components, or a deployment
that deletes and adds components. In API version 33.0 and later, you can specify components to delete before and after other
components are added or updated. In earlier API versions, if deletions and additions are specified for the same deployment, the
deploy() call performs the deletions first.
2. checkDeployStatus()
3. cancelDeploy()
SEE ALSO:
Running Tests in a Deployment

Deleting Components from an Organization
To delete components, perform a deployment with the deploy() call by using a destructive changes manifest file that lists the
components to remove from your organization. You can perform a deployment that only deletes components, or a deployment that
deletes and adds components. In API version 33.0 and later, you can specify components to delete before and after other components
are added or updated. In earlier API versions, if deletions and additions are specified for the same deployment, the deploy() call
performs the deletions first.

Deleting Components in a Deployment
To delete components, use the same procedure as with deploying components, but also include a delete manifest file that’s named
destructiveChanges.xml and list the components to delete in this manifest. The format of this manifest is the same as
package.xml except that wildcards aren’t supported.
The following sample destructiveChanges.xml file names a single custom object to be deleted:

MyCustomObject__c
CustomObject

To deploy the destructive changes, you must also have a package.xml file that lists no components to deploy, includes the API
version, and is in the same directory as destructiveChanges.xml:

39.0

File-Based Calls

checkDeployStatus()

Note:
• To bypass the Recycle Bin, set the purgeOnDelete option to true.
• If you try to delete some components that don’t exist in the organization, the rest of the deletions are still attempted.

Adding and Deleting Components in a Single Deployment
You can perform a deployment that specifies components to delete in destructiveChanges.xml and components to add or
update in package.xml. The process is the same as with performing a delete-only deployment except that package.xml contains
the components to add or update.
By default, deletions are processed before component additions. In API version 33.0 and later, you can specify components to be deleted
before and after component additions. The process is the same as with performing a delete-only deployment except that the name of
the deletion manifest file is different.
• To delete components before adding or updating other components, create a manifest file that’s named
destructiveChangesPre.xml and include the components to delete.
• To delete components after adding or updating other components, create a manifest file that’s named
destructiveChangesPost.xml and include the components to delete.
The ability to specify when deletions are processed is useful when you’re deleting components with dependencies. For example, if a
custom object is referenced in an Apex class, you can’t delete it unless you modify the Apex class first to remove the dependency on
the custom object. In this example, you can perform a single deployment that updates the Apex class to clear the dependency and then
deletes the custom object by using destructiveChangesPost.xml. The following are samples of the package.xml and
destructiveChangesPost.xml manifests that would be used in this example.
Sample package.xml, which specifies the class to update:

SampleClass
ApexClass

39.0

Sample destructiveChangesPost.xml, which specifies the custom object to delete after the class update:

MyCustomObject__c
CustomObject

Note: The API version that the deployment uses is the API version that’s specified in package.xml.

checkDeployStatus()
Checks the status of declarative metadata call deploy().

File-Based Calls

cancelDeploy()

Syntax
DeployResult = metadatabinding.checkDeployStatus(ID id, includeDetails boolean);

Usage
checkDeployStatus is used as part of the process for deploying packaged or unpackaged components to an organization:

1. Issue a deploy() call to start the asynchronous deployment. An AsyncResult object is returned. Note the value in the id field
and use it for the next step.
2. Issue a checkDeployStatus() call in a loop until the done field of the returned DeployResult contains true, which means
that the call is completed. The DeployResult object contains information about an in-progress or completed deployment started
using the deploy() call. When calling checkDeployStatus(), pass in the id value from the AsyncResult object from the
first step.
In API version 29.0, Salesforce improved the deployment status properties and removed the requirement to use checkStatus()
after a deploy() call to get information about deployments. Salesforce continues to support the use of checkStatus() when
using deploy() with API version 28.0 or earlier.

Sample Code—Java
See the deploy() sample code for sample usage of this call.

Arguments
Name

Type

Description

ID obtained from an AsyncResult object returned by deploy() or a subsequent
checkDeployStatus() call.

includeDetails boolean

Sets the DeployResult object to include DeployDetails information ((true) or not (false).
The default is false. Available in API version 29.0 and later.

Response
DeployResult

cancelDeploy()
Cancels a deployment that hasn’t completed yet.

Syntax
CancelDeployResult = metadatabinding.cancelDeploy(string id)

File-Based Calls

cancelDeploy()

Usage
Use the cancelDeploy() operation to cancel a deployment in your organization started by the deploy() operation, which
includes deployments started by the Force.com Migration Tool and the Force.com IDE. The deployment can be in a queue waiting to
get started, or can be in progress. This operation takes the ID of the deployment you wish to cancel and returns a CancelDeployResult
object. When the deployment is in the queue and hasn’t started yet, calling cancelDeploy() cancels the deployment immediately.
When the deployment has started and is in progress, it might not get canceled immediately, so you should call
checkDeployStatus() to check the status of the cancellation.
Cancel a deployment using these steps.
1. Obtain the ID of the deployment you wish to cancel. For example, you can obtain the ID from the deploy() call in the
AsyncResult object id field. Alternatively, you can obtain the ID in the Salesforce user interface from Setup by entering
Deployment Status in the Quick Find box, selecting Deployment Status, and then noting the ID of a deployment
started by the API.
2. Issue a cancelDeploy() call to start the cancellation process. This call returns a CancelDeployResult object.
3. Check the value in the done field of the returned CancelDeployResult. If the done field value is true, the deployment
has been canceled and you’re done. If the done field value is false, the cancellation is in progress, and follow these steps to
check the cancellation status.
a. Call checkDeployStatus() using the deployment ID you obtained earlier.
b. In the returned DeployResult object, check the status field. If the status is Canceling, this means the cancellation is still
in progress, and repeat steps a and b. Otherwise, if the status is Canceled, this means the deployment has been canceled
and you’re done.
The deploy() operation throws these API faults.
INVALID_ID_FIELD with the message Invalid deploy ID
The specified ID argument doesn’t correspond to a valid deployment.
INVALID_ID_FIELD with the message Deployment already completed
The specified deployment has already completed.

Version
Available in API version 30.0 and later.

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Arguments
Name

Type

Description

string

The ID of the deployment to cancel.

Response
CancelDeployResult

File-Based Calls

deployRecentValidation()

Sample Code—Java
This sample shows how to cancel a deployment. The sample calls cancelDeploy() by passing it a given deployment ID. Next, it
checks whether the cancellation has completed, and if not, calls checkDeployStatus in a loop.
public void cancelDeploy(String asyncId) throws Exception {
// Issue the deployment cancellation request
CancelDeployResult result = metadataConnection.cancelDeploy(asyncId);
// If the deployment cancellation completed, write a message to the output.
if (result.isDone()) {
System.out.println("Your deployment was canceled successfully!");
}
else {
// The deployment cancellation is still in progress, so get a new status
DeployResult deployResult = metadataConnection.checkDeployStatus(asyncId, false);

// Check whether the deployment is done. If not done, this means
// that the cancellation is still in progress and the status is Canceling.
while (!deployResult.isDone()) {
// Assert that the deployment status is Canceling
assert deployResult.getStatus() == DeployStatus.Canceling;
// Wait 2 seconds
Thread.sleep(2000);
// Get the deployment status again
deployResult = metadataConnection.checkDeployStatus(asyncId, false);
}
// The deployment is done. Write the status to the output.
// (When the deployment is done, the cancellation should have completed
// and the status should be Canceled. However, in very rare cases,
// the deployment can complete before it is canceled.)
System.out.println("Final deploy status = >" + deployResult.getStatus());
}
}

deployRecentValidation()
Deploys a recently validated component set without running Apex tests.

Syntax
string = metadatabinding.deployRecentValidation(ID validationID)

Usage
Use deployRecentValidation() to deploy your components to production in less time by skipping the execution of Apex
tests. Ensure that the following requirements are met before deploying a recent validation.

File-Based Calls

deployRecentValidation()

• The components have been validated successfully for the target environment within the last 10 days.
• As part of the validation, Apex tests in the target org have passed.
• Code coverage requirements are met.
– If all tests in the org or all local tests are run, overall code coverage is at least 75%, and Apex triggers have some coverage.
– If specific tests are run with the RunSpecifiedTests test level, each class and trigger that was deployed is covered by at
least 75% individually.
This call is equivalent to performing a quick deployment of a recent validation on the Deployment Status page in the Salesforce user
interface.
Before you call deployRecentValidation(), your organization must have a validation that was recently run. You can run a
validation on a set of components by calling deploy() with the checkOnly property of the deployOptions parameter set to
true. Note the ID that you obtained from the deploy() call. You’ll use this ID for the deployRecentValidation() call in
the next step.
After you’ve run a validation successfully, use these steps to quick-deploy the validation to the same target environment.
1. To start an asynchronous quick deployment, call deployRecentValidation() and pass it the ID of a recent validation. This
ID is obtained from the previous deploy() call. The deployRecentValidation() call returns the ID of the quick deployment.
Note this value. You’ll use it in the next step.
2. Check for the completion of the call. This process is similar to that of deploy(). Issue a checkDeployStatus() call in a loop
until the done field of the returned DeployResult contains true, which means that the call is completed. The DeployResult object
contains information about an in-progress or completed deployment that was started by using the
deployRecentValidation() call. When calling checkDeployStatus(), pass in the ID value that you obtained in
the first step.

Version
Available in API version 33.0 and later.

Arguments
Name

Type

validationID string

Description
The ID of a recent validation.

Response
Type: string
The ID of the quick deployment.

Sample Code—Java
package com.salesforce.test.metadata;
import java.rmi.RemoteException;
import com.sforce.soap.metadata.CodeCoverageWarning;

File-Based Calls

import
import
import
import
import
import
import
import
import

deployRecentValidation()

com.sforce.soap.metadata.DeployDetails;
com.sforce.soap.metadata.DeployMessage;
com.sforce.soap.metadata.DeployResult;
com.sforce.soap.metadata.MetadataConnection;
com.sforce.soap.metadata.RunTestFailure;
com.sforce.soap.metadata.RunTestsResult;
com.sforce.soap.partner.Connector;
com.sforce.ws.ConnectionException;
com.sforce.ws.ConnectorConfig;

/**
* Quick-deploy a recent validation.
* Prerequisite: A successful validation (check-only deploy) has been done in the org
recently.
*/
public class DeployRecentValidationSample {
// binding for the metadata WSDL used for making metadata API calls
private MetadataConnection metadataConnection;
// one second in milliseconds
private static final long ONE_SECOND = 1000;
// maximum number of attempts to deploy the zip file
private static final int MAX_NUM_POLL_REQUESTS = 50;
public static void main(String[] args) throws Exception {
final String USERNAME = args[0];
final String PASSWORD = args[1];
final String URL = args[2];
final String recentValidationId = args[3];
DeployRecentValidationSample sample = new DeployRecentValidationSample(
USERNAME, PASSWORD, URL);
sample.deployRecentValidation(recentValidationId);
}
public DeployRecentValidationSample(String username, String password, String loginUrl)
throws ConnectionException {
createMetadataConnection(username, password, loginUrl);
}
public void deployRecentValidation(String recentValidationId)
throws RemoteException, Exception
{
String asyncResultId = metadataConnection.deployRecentValidation(recentValidationId);

// Wait for the deploy to complete
int poll = 0;
long waitTimeMilliSecs = ONE_SECOND;
DeployResult deployResult = null;
boolean fetchDetails;
do {

File-Based Calls

deployRecentValidation()

Thread.sleep(waitTimeMilliSecs);
// double the wait time for the next iteration
waitTimeMilliSecs *= 2;
if (poll++ > MAX_NUM_POLL_REQUESTS) {
throw new Exception("Request timed out. If this is a large set " +
"of metadata components, check that the time allowed by " +
"MAX_NUM_POLL_REQUESTS is sufficient.");
}
// Fetch in-progress details once for every 3 polls
fetchDetails = (poll % 3 == 0);
deployResult = metadataConnection.checkDeployStatus(asyncResultId, fetchDetails);
System.out.println("Status is: " + deployResult.getStatus());
if (!deployResult.isDone() && fetchDetails) {
printErrors(deployResult, "Failures for deployment in progress:\n");
}
}
while (!deployResult.isDone());
if (!deployResult.isSuccess() && deployResult.getErrorStatusCode() != null) {
throw new Exception(deployResult.getErrorStatusCode() + " msg: " +
deployResult.getErrorMessage());
}
if (!fetchDetails) {
// Get the final result with details if we didn't do it in the last attempt.
deployResult = metadataConnection.checkDeployStatus(asyncResultId, true);
}
if (!deployResult.isSuccess()) {
printErrors(deployResult, "Final list of failures:\n");
throw new Exception("The files were not successfully deployed");
}
System.out.println("The recent validation " + recentValidationId +
" was successfully deployed");
}
/**
* Print out any errors, if any, related to the deploy.
* @param result - DeployResult
*/
private void printErrors(DeployResult result, String messageHeader)
{
DeployDetails deployDetails = result.getDetails();
StringBuilder errorMessageBuilder = new StringBuilder();
if (deployDetails != null) {
DeployMessage[] componentFailures = deployDetails.getComponentFailures();
for (DeployMessage message : componentFailures) {
String loc = (message.getLineNumber() == 0 ? "" :
("(" + message.getLineNumber() + "," +
message.getColumnNumber() + ")"));

File-Based Calls

deployRecentValidation()

if (loc.length() == 0
&& !message.getFileName().equals(message.getFullName())) {
loc = "(" + message.getFullName() + ")";
}
errorMessageBuilder.append(message.getFileName() + loc + ":" +
message.getProblem()).append('\n');
}
RunTestsResult rtr = deployDetails.getRunTestResult();
if (rtr.getFailures() != null) {
for (RunTestFailure failure : rtr.getFailures()) {
String n = (failure.getNamespace() == null ? "" :
(failure.getNamespace() + ".")) + failure.getName();
errorMessageBuilder.append("Test failure, method: " + n + "." +
failure.getMethodName() + " -- " +
failure.getMessage() + " stack " +
failure.getStackTrace() + "\n\n");
}
}
if (rtr.getCodeCoverageWarnings() != null) {
for (CodeCoverageWarning ccw : rtr.getCodeCoverageWarnings()) {
errorMessageBuilder.append("Code coverage issue");
if (ccw.getName() != null) {
String n = (ccw.getNamespace() == null ? "" :
(ccw.getNamespace() + ".")) + ccw.getName();
errorMessageBuilder.append(", class: " + n);
}
errorMessageBuilder.append(" -- " + ccw.getMessage() + "\n");
}
}
}
if (errorMessageBuilder.length() > 0) {
errorMessageBuilder.insert(0, messageHeader);
System.out.println(errorMessageBuilder.toString());
}
}
private void createMetadataConnection(
final String username,
final String password,
final String loginUrl) throws ConnectionException {
final ConnectorConfig loginConfig = new ConnectorConfig();
loginConfig.setUsername(username);
loginConfig.setPassword(password);
loginConfig.setAuthEndpoint(loginUrl);
Connector.newConnection(loginConfig);

final ConnectorConfig metadataConfig = new ConnectorConfig();
metadataConfig.setServiceEndpoint(
loginConfig.getServiceEndpoint().replace("/u/", "/m/"));
metadataConfig.setSessionId(loginConfig.getSessionId());

File-Based Calls

retrieve()

this.metadataConnection = com.sforce.soap.metadata.Connector.
newConnection(metadataConfig);
}
}

retrieve()
This call retrieves XML file representations of components in an organization.

Syntax
AsyncResult = metadatabinding.retrieve(RetrieveRequest retrieveRequest)

Usage
Use this call to retrieve file representations of components in an organization.
Note: You can deploy or retrieve up to 10,000 files at once and the maximum size of the deployed or retrieved .zip file is 39 MB.
In API version 31.0 and later, the process of making a retrieve() call has been simplified. You no longer have to call
checkStatus() after a retrieve() call to obtain the status of the retrieve operation. Instead, make calls to
checkRetrieveStatus() only. If the retrieve operation is in progress, call checkRetrieveStatus() again until the
retrieve operation is completed. The checkStatus() call is still supported in versions API version 30.0 or earlier, but is not available
in API version 31.0 and later.
For API version 31.0 or later, retrieve packaged or unpackaged components by using the following steps.
1. Issue a retrieve() call to start the asynchronous retrieval. An AsyncResult object is returned. Note the value in the id field and
use it for the next step.
2. Issue a checkRetrieveStatus() call and pass in the id value from the AsyncResult object from the first step. Check the
value of the done field of the returned RetrieveResult. If it is true, this means that the call is completed and proceed to the next
step. Otherwise, repeat this step to call checkRetrieveStatus() again until the done field is true.
3. Retrieve the zip file (zipFile field) and other desired fields from RetrieveResult that was returned by the final call to
checkRetrieveStatus() in the previous step.
For API version 30.0 or earlier, retrieve packaged or unpackaged components by using the following steps.
1. Issue a retrieve() call to start the asynchronous retrieval. An AsyncResult object is returned. If the call is completed, the done
field contains true. Most often, the call is not completed quickly enough to be noted in the result. If it is completed, note the value
in the id field returned and skip the next step.
2. If the call is not complete, issue a checkStatus() call in a loop using the value in the id field of the AsyncResult object, returned
by the retrieve() call in the previous step. Check the AsyncResult object returned until the done field contains true. The
time taken to complete a retrieve() call depends on the size of the zip file being deployed, so use a longer wait time between
iterations as the size of the zip file increases.
3. Issue a checkRetrieveStatus() call to obtain the results of the retrieve() call, using the id value returned in the first
step.
For examples of manifest files, see Sample package.xml Manifest Files.

File-Based Calls

retrieve()

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Arguments
Name

Type

Description

retrieveRequest RetrieveRequest Encapsulates options for determining which packages or files are retrieved.

Response
AsyncResult

Sample Code—Java
This sample shows how to retrieve components into a zip file. See the deploy() sample code for details on how to deploy a zip file.
Note: This sample requires API version 34.0 or later.
package com.doc.samples;
import
import
import
import
import
import
import
import
import
import
import
import

java.io.*;
java.util.*;
java.nio.ByteBuffer;
java.nio.channels.*;
java.rmi.RemoteException;
javax.xml.parsers.DocumentBuilder;
javax.xml.parsers.DocumentBuilderFactory;
javax.xml.parsers.ParserConfigurationException;
org.w3c.dom.Element;
org.w3c.dom.Node;
org.w3c.dom.NodeList;
org.xml.sax.SAXException;

import
import
import
import
import
import
import
import
import
import
import

com.sforce.soap.metadata.AsyncResult;
com.sforce.soap.metadata.MetadataConnection;
com.sforce.soap.enterprise.EnterpriseConnection;
com.sforce.soap.metadata.RetrieveMessage;
com.sforce.soap.metadata.RetrieveRequest;
com.sforce.soap.metadata.RetrieveResult;
com.sforce.soap.metadata.RetrieveStatus;
com.sforce.soap.enterprise.LoginResult;
com.sforce.ws.ConnectionException;
com.sforce.ws.ConnectorConfig;
com.sforce.soap.metadata.PackageTypeMembers;

public class RetrieveSample {
// Binding for the metadata WSDL used for making metadata API calls
private MetadataConnection metadataConnection;

File-Based Calls

retrieve()

static BufferedReader rdr = new BufferedReader(new InputStreamReader(System.in));
// one second in milliseconds
private static final long ONE_SECOND = 1000;
// maximum number of attempts to retrieve the results
private static final int MAX_NUM_POLL_REQUESTS = 50;
// manifest file that controls which components get retrieved
private static final String MANIFEST_FILE = "package.xml";
private static final double API_VERSION = 31.0;
public static void main(String[] args) throws Exception {
final String USERNAME = "user@company.com";
// This is only a sample. Hard coding passwords in source files is a bad practice.
final String PASSWORD = "password";
final String URL = "https://login.salesforce.com/services/Soap/c/31.0";
RetrieveSample sample = new RetrieveSample(USERNAME, PASSWORD, URL);
sample.retrieveZip();
}
public RetrieveSample(String username, String password, String loginUrl)
throws ConnectionException {
createMetadataConnection(username, password, loginUrl);
}

private void retrieveZip() throws RemoteException, Exception
{
RetrieveRequest retrieveRequest = new RetrieveRequest();
// The version in package.xml overrides the version in RetrieveRequest
retrieveRequest.setApiVersion(API_VERSION);
setUnpackaged(retrieveRequest);
// Start the retrieve operation
AsyncResult asyncResult = metadataConnection.retrieve(retrieveRequest);
String asyncResultId = asyncResult.getId();
// Wait for the retrieve to complete
int poll = 0;
long waitTimeMilliSecs = ONE_SECOND;
RetrieveResult result = null;
do {
Thread.sleep(waitTimeMilliSecs);
// Double the wait time for the next iteration
waitTimeMilliSecs *= 2;
if (poll++ > MAX_NUM_POLL_REQUESTS) {
throw new Exception("Request timed out. If this is a large set " +
"of metadata components, check that the time allowed " +
"by MAX_NUM_POLL_REQUESTS is sufficient.");
}

File-Based Calls

retrieve()

result = metadataConnection.checkRetrieveStatus(
asyncResultId, true);
System.out.println("Retrieve Status: " + result.getStatus());
} while (!result.isDone());
if (result.getStatus() == RetrieveStatus.Failed) {
throw new Exception(result.getErrorStatusCode() + " msg: " +
result.getErrorMessage());
} else if (result.getStatus() == RetrieveStatus.Succeeded) {
// Print out any warning messages
StringBuilder buf = new StringBuilder();
if (result.getMessages() != null) {
for (RetrieveMessage rm : result.getMessages()) {
buf.append(rm.getFileName() + " - " + rm.getProblem());
}
}
if (buf.length() > 0) {
System.out.println("Retrieve warnings:\n" + buf);
}
// Write the zip to the file system
System.out.println("Writing results to zip file");
ByteArrayInputStream bais = new ByteArrayInputStream(result.getZipFile());
File resultsFile = new File("retrieveResults.zip");
FileOutputStream os = new FileOutputStream(resultsFile);
try {
ReadableByteChannel src = Channels.newChannel(bais);
FileChannel dest = os.getChannel();
copy(src, dest);
System.out.println("Results written to " + resultsFile.getAbsolutePath());
} finally {
os.close();
}
}
}
/**
* Helper method to copy from a readable channel to a writable channel,
* using an in-memory buffer.
*/
private void copy(ReadableByteChannel src, WritableByteChannel dest)
throws IOException
{
// Use an in-memory byte buffer
ByteBuffer buffer = ByteBuffer.allocate(8092);
while (src.read(buffer) != -1) {
buffer.flip();
while(buffer.hasRemaining()) {
dest.write(buffer);
}
buffer.clear();
}

File-Based Calls

retrieve()

}
private void setUnpackaged(RetrieveRequest request) throws Exception
{
// Edit the path, if necessary, if your package.xml file is located elsewhere
File unpackedManifest = new File(MANIFEST_FILE);
System.out.println("Manifest file: " + unpackedManifest.getAbsolutePath());
if (!unpackedManifest.exists() || !unpackedManifest.isFile())
throw new Exception("Should provide a valid retrieve manifest " +
"for unpackaged content. " +
"Looking for " + unpackedManifest.getAbsolutePath());
// Note that we populate the _package object by parsing a manifest file here.
// You could populate the _package based on any source for your
// particular application.
com.sforce.soap.metadata.Package p = parsePackage(unpackedManifest);
request.setUnpackaged(p);
}
private com.sforce.soap.metadata.Package parsePackage(File file) throws Exception {
try {
InputStream is = new FileInputStream(file);
List pd = new ArrayList();
DocumentBuilder db =
DocumentBuilderFactory.newInstance().newDocumentBuilder();
Element d = db.parse(is).getDocumentElement();
for (Node c = d.getFirstChild(); c != null; c = c.getNextSibling()) {
if (c instanceof Element) {
Element ce = (Element)c;
//
NodeList namee = ce.getElementsByTagName("name");
if (namee.getLength() == 0) {
// not
continue;
}
String name = namee.item(0).getTextContent();
NodeList m = ce.getElementsByTagName("members");
List members = new ArrayList();
for (int i = 0; i < m.getLength(); i++) {
Node mm = m.item(i);
members.add(mm.getTextContent());
}
PackageTypeMembers pdi = new PackageTypeMembers();
pdi.setName(name);
pdi.setMembers(members.toArray(new String[members.size()]));
pd.add(pdi);
}
}
com.sforce.soap.metadata.Package r = new com.sforce.soap.metadata.Package();
r.setTypes(pd.toArray(new PackageTypeMembers[pd.size()]));
r.setVersion(API_VERSION + "");
return r;
} catch (ParserConfigurationException pce) {

File-Based Calls

RetrieveRequest

throw new Exception("Cannot create XML parser", pce);
} catch (IOException ioe) {
throw new Exception(ioe);
} catch (SAXException se) {
throw new Exception(se);
}
}

private void createMetadataConnection(final String username,
final String password, final String loginUrl)
throws ConnectionException {
final ConnectorConfig loginConfig = new ConnectorConfig();
loginConfig.setAuthEndpoint(loginUrl);
loginConfig.setServiceEndpoint(loginUrl);
loginConfig.setManualLogin(true);
LoginResult loginResult = (new EnterpriseConnection(loginConfig)).login(
username, password);
final ConnectorConfig metadataConfig = new ConnectorConfig();
metadataConfig.setServiceEndpoint(loginResult.getMetadataServerUrl());
metadataConfig.setSessionId(loginResult.getSessionId());
this.metadataConnection = new MetadataConnection(metadataConfig);
}
//The sample client application retrieves the user's login credentials.
// Helper function for retrieving user input from the console
String getUserInput(String prompt) {
System.out.print(prompt);
try {
return rdr.readLine();
}
catch (IOException ex) {
return null;
}
}
}

RetrieveRequest
The RetrieveRequest object specified in a retrieve() call consists of the following properties:
Name

Type

Description

apiVersion

double

Required. The API version for the retrieve request. The API
version determines the fields retrieved for each metadata type.
For example, an icon field was added to the CustomTab
for API version 14.0. If you retrieve components for version 13.0
or earlier, the components will not include the icon field.

File-Based Calls

Name

checkRetrieveStatus()

Type

Description
Note: In API version 31.0 and later, the API version
that’s specified in package.xml is used for the
retrieve() call and overrides the version in the
apiVersion field. If the version is not specified in
package.xml, the version in this field is used.

packageNames

string[]

A list of package names to be retrieved. If you are retrieving
only unpackaged components, do not specify a name here.
You can retrieve packaged and unpackaged components in
the same retrieve.

singlePackage

boolean

Specifies whether only a single package is being retrieved
(true) or not (false). If false, then more than one
package is being retrieved.

specificFiles

string[]

A list of file names to be retrieved. If a value is specified for this
property, packageNames must be set to null and
singlePackage must be set to true.

unpackaged

Package

A list of components to retrieve that are not in a package.

checkRetrieveStatus()
Checks the status of the declarative metadata call retrieve() and returns the zip file contents.

Syntax
In API version 34.0 and later:
RetrieveResult = metadatabinding.checkRetrieveStatus(ID id, boolean includeZip);

In API version 33.0 and earlier:
RetrieveResult = metadatabinding.checkRetrieveStatus(ID id);

Usage
Use checkRetrieveStatus() to check the progress of the metadata retrieve() operation. The RetrieveResult object that
this method returns indicates when the asynchronous retrieve() call is completed. If the retrieval is completed, RetrieveResult
contains the zip file contents by default. Use the following process to retrieve metadata components with the retrieve() call.
1. Issue a retrieve() call to start the asynchronous retrieval. An AsyncResult object is returned. Note the value in the id field and
use it for the next step.
2. Issue a checkRetrieveStatus() call and pass in the id value from the AsyncResult object from the first step. Check the
value of the done field of the returned RetrieveResult. If it is true, this means that the call is completed and proceed to the next
step. Otherwise, repeat this step to call checkRetrieveStatus() again until the done field is true.
3. Retrieve the zip file (zipFile field) and other desired fields from RetrieveResult that was returned by the final call to
checkRetrieveStatus() in the previous step.

File-Based Calls

checkRetrieveStatus()

In API version 31.0 and later, the process of making a retrieve() call has been simplified. You no longer have to call
checkStatus() after a retrieve() call to obtain the status of the retrieve operation. Instead, make calls to
checkRetrieveStatus() only. If the retrieve operation is in progress, call checkRetrieveStatus() again until the
retrieve operation is completed. The checkStatus() call is still supported in versions API version 30.0 or earlier, but is not available
in API version 31.0 and later.

Retrieving the Zip File in a Second Process
By default, checkRetrieveStatus() returns the zip file on the last call to this operation when the retrieval is completed
(RetrieveResult.isDone() == true) and then deletes the zip file from the server. Subsequent calls to
checkRetrieveStatus() for the same retrieve operation can’t retrieve the zip file after it has been deleted. Starting with API
version 34.0, pass a boolean value for the includeZip argument of checkRetrieveStatus() to indicate whether to retrieve
the zip file. The includeZip argument gives you the option to retrieve the file in a separate process after the retrieval operation is
completed. For example, a service polls the retrieval status by calling checkRetrieveStatus(id, false) in a loop. This call
returns the status of the retrieval operation, but doesn’t retrieve the zip file. After the retrieval operation is completed, another process,
such as a background file transfer service, calls checkRetrieveStatus(id, true) to retrieve the zip file. This last call causes
the zip file to be deleted from the server.
// First process: Poll the retrieval but don’t retrieve the zip file.
AsyncResult asyncResult = metadataConnection.retrieve(retrieveRequest);
String asyncResultId = asyncResult.getId();
// Wait for the retrieve to complete
int poll = 0;
long waitTimeMilliSecs = ONE_SECOND;
RetrieveResult result = null;
do {
Thread.sleep(waitTimeMilliSecs);
// Check the status but don’t retrieve zip file.
result = metadataConnection.checkRetrieveStatus(asyncResultId, false);
} while (!result.isDone());
// Second process: Retrieve the zip file.
// For example, this process can be a background file transfer service.
// Retrieve the zip file.
result = metadataConnection.checkRetrieveStatus(asyncResultId, true);
// Get the zip file from the RetrieveResult (result) variable
if (result.getStatus() == RetrieveStatus.Succeeded) {
ByteArrayInputStream bais = new ByteArrayInputStream(result.getZipFile());
// ...
}

Sample Code—Java
See the retrieve() sample code for sample usage of this call.

Arguments
Name

Type

Description

ID obtained from an AsyncResult object returned by a retrieve() call or a subsequent
RetrieveResult object returned by a checkRetrieveStatus() call.

File-Based Calls

checkRetrieveStatus()

Name

Type

Description

includeZip

boolean

Set to true to retrieve the zip file. You can retrieve the zip file only after the retrieval operation
is completed. After the zip file is retrieved, it is deleted from the server. Set to false to check
the status of the retrieval without attempting to retrieve the zip file. If set to null, this argument
defaults to true, which means that the zip file is retrieved on the last call to
checkRetrieveStatus() when the retrieval has finished.
This argument is available in API version 34.0 and later.

Response
RetrieveResult

CHAPTER 7

CRUD-Based Calls

Use the following CRUD-based calls to work with metadata components in a manner similar to how synchronous API calls in the enterprise
WSDL act upon objects.
IN THIS SECTION:
createMetadata()
Adds one or more new metadata components to your organization synchronously.
readMetadata()
Returns one or more metadata components from your organization synchronously.
updateMetadata()
Updates one or more metadata components in your organization synchronously.
upsertMetadata()
Creates or updates one or more metadata components in your organization synchronously.
deleteMetadata()
Deletes one or more metadata components from your organization synchronously.
renameMetadata()
Renames a metadata component in your organization synchronously.
create()
Deprecated. Adds one or more new metadata components to your organization asynchronously. This call is removed as of API version
31.0 and is available in earlier versions only. Use createMetadata() instead.
delete()
Deprecated. Deletes one or more components from your organization asynchronously. This call is removed as of API version 31.0
and is available in earlier versions only. Use deleteMetadata() instead.
update()
Deprecated. Updates one or more components in your organization asynchronously. This call is removed as of API version 31.0 and
is available in earlier versions only. Use updateMetadata() or renameMetadata() instead.

createMetadata()
Adds one or more new metadata components to your organization synchronously.

Syntax
SaveResult[] = metadatabinding.createMetadata(Metadata[] metadata);

CRUD-Based Calls

createMetadata()

Usage
Use the createMetadata() call to create any component that extends Metadata. All components must be of the same type in
the same call. For more details, see Metadata Components and Types.
This call executes synchronously, which means that the call returns only when the operation completes.
Starting in API version 34.0, this call supports the AllOrNoneHeader header. By default, if AllOrNoneHeader isn’t used in API version
34.0 and later, this call can save a partial set of records for records with no errors (equivalent to AllOrNoneHeader=false). In API
version 33.0 and earlier, the default behavior is to only save all records when there are no failures in any record in the call (equivalent to
AllOrNoneHeader=true).

Version
Available in API version 30.0 and later.

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Required Fields
Required fields are determined by the metadata components being created. For more information about specific component types, see
Metadata Components and Types.

Valid Data Values
You must supply values that are valid for the field’s data type, such as integers for integer fields (not alphabetic characters). In your client
application, follow the data formatting rules specified for your programming language and development tool. (Your development tool
handles the appropriate mapping of data types in SOAP messages.)

String Values
When storing values in string fields, the API trims any leading and trailing whitespace. For example, if the value of a label field is
entered as "MyObject ", the value is stored in the database as "MyObject".

Basic Steps for Creating Metadata Components
Use the following process to create metadata components:
1. Design an array and populate it with the components that you want to create. All components must be of the same type.
2. Call createMetadata() with the component array passed in as an argument.
3. A SaveResult object is returned for each component you tried to create. It contains information about whether the operation
was successful, the name of the component created, and any errors returned if the operation wasn’t successful.

CRUD-Based Calls

createMetadata()

Sample Code—Java
public void createCustomObjectSync() {
try {
CustomObject co = new CustomObject();
String name = "MyCustomObject1";
co.setFullName(name + "__c");
co.setDeploymentStatus(DeploymentStatus.Deployed);
co.setDescription("Created by the Metadata API");
co.setEnableActivities(true);
co.setLabel(name + " Object");
co.setPluralLabel(co.getLabel() + "s");
co.setSharingModel(SharingModel.ReadWrite);
CustomField nf = new CustomField();
nf.setType(FieldType.Text);
nf.setLabel(co.getFullName() + " Name");
co.setNameField(nf);
SaveResult[] results = metadataConnection
.createMetadata(new Metadata[] { co });
for (SaveResult r : results) {
if (r.isSuccess()) {
System.out.println("Created component: " + r.getFullName());
} else {
System.out
.println("Errors were encountered while creating "
+ r.getFullName());
for (Error e : r.getErrors()) {
System.out.println("Error message: " + e.getMessage());
System.out.println("Status code: " + e.getStatusCode());
}
}
}
} catch (ConnectionException ce) {
ce.printStackTrace();
}
}

Arguments
Name

Type

Description

metadata

Metadata[]

Array of one or more metadata components.
Limit: 10. (For CustomMetadata and CustomApplication only, the limit is 200.)
You must submit arrays of only one type of component. For example, you can submit an array
of 10 custom objects or 10 profiles, but not a mix of both types.

CRUD-Based Calls

readMetadata()

Response
SaveResult[]

readMetadata()
Returns one or more metadata components from your organization synchronously.

Syntax
ReadResult = metadataConnection.readMetadata(string metadataType, string[] fullNames);

Usage
Use the readMetadata() call to retrieve any component that extends Metadata. All components must be of the same type in the
same call. For more details, see Metadata Components and Types.
This call executes synchronously, which means that the call returns only when the operation completes.

Version
Available in API version 30.0 and later.

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Basic Steps for Reading Metadata Components
Use the following process to read metadata components:
1. Determine the metadata type of the components you want to read, and the fullName of each component to read. See Metadata
for more details on the fullName field. You can read only components of the same type in a single call.
2. Invoke the readMetadata() call. For the first argument, pass in the name of the metadata type. The metadata type must match
one of the values returned by the describeMetadata() call. For the second argument, pass in an array of full names
corresponding to the components you wish to get. The full names must match one or more full names returned by the
listMetadata() call.
3. A ReadResult is returned that contains an array of Metadata components. Cast each returned Metadata object to the
metadata type you specified in the call to get the component’s properties.

Sample Code—Java
public void readCustomObjectSync() {
try {
ReadResult readResult = metadataConnection
.readMetadata("CustomObject", new String[] {
"MyCustomObject1__c", "MyCustomObject2__c" });

CRUD-Based Calls

updateMetadata()

Metadata[] mdInfo = readResult.getRecords();
System.out.println("Number of component info returned: "
+ mdInfo.length);
for (Metadata md : mdInfo) {
if (md != null) {
CustomObject obj = (CustomObject) md;
System.out.println("Custom object full name: "
+ obj.getFullName());
System.out.println("Label: " + obj.getLabel());
System.out.println("Number of custom fields: "
+ obj.getFields().length);
System.out.println("Sharing model: "
+ obj.getSharingModel());
} else {
System.out.println("Empty metadata.");
}
}
} catch (ConnectionException ce) {
ce.printStackTrace();
}
}

Arguments
Name

Type

metadataType string
fullNames

string[]

Description
The metadata type of the components to read.
Array of full names of the components to read.
Limit: 10. (For CustomMetadata and CustomApplication only, the limit is 200.)
You must submit arrays of only one type of component. For example, you can submit an array
of 10 custom objects or 10 profiles, but not a mix of both types.

Response
ReadResult

updateMetadata()
Updates one or more metadata components in your organization synchronously.

Syntax
SaveResult[] = metadataConnection.updateMetadata(Metadata[] metadata);

CRUD-Based Calls

updateMetadata()

Usage
Use the updateMetadata() call to update any component that extends Metadata. All components must be of the same type in
the same call. For more details, see Metadata Components and Types.
This call executes synchronously, which means that the call returns only when the operation completes.
Starting in API version 34.0, this call supports the AllOrNoneHeader header. By default, if AllOrNoneHeader isn’t used in API version
34.0 and later, this call can save a partial set of records for records with no errors (equivalent to AllOrNoneHeader=false). In API
version 33.0 and earlier, the default behavior is to only save all records when there are no failures in any record in the call (equivalent to
AllOrNoneHeader=true).

Version
Available in API version 30.0 and later.

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Required Fields
You must supply values for all the required fields in the component.

Valid Field Values
You must supply values that are valid for the field’s data type, such as integers for integer fields (not alphabetic characters). In your client
application, follow the data formatting rules specified for your programming language and development tool. (Your development tool
handles the appropriate mapping of data types in SOAP messages.)

String Values
When storing values in string fields, the API trims any leading and trailing white space. For example, if the value of a label field is
entered as "MyObject " the value is stored in the database as "MyObject".

Basic Steps for Updating Metadata Components
Use this process to update metadata components:
1. Create an array of the components you wish to update. All components must be of the same type.
2. Invoke the updateMetadata() call, passing in the array of metadata components to update.
A SaveResult object is returned for each component you tried to update. It contains information about whether the operation
was successful, the name of the component updated, and any errors returned if the operation wasn’t successful.

Sample Code—Java
public void updateCustomObjectSync() {
try {

CRUD-Based Calls

updateMetadata()

CustomObject co = new CustomObject();
String name = "MyCustomObject1";
co.setFullName(name + "__c");
co.setDeploymentStatus(DeploymentStatus.Deployed);
co.setDescription("Updated description");
co.setLabel(name + " Object Update");
co.setPluralLabel(co.getLabel() + "s");
co.setSharingModel(SharingModel.ReadWrite);
// Name field with a type and label is required
CustomField cf = new CustomField();
cf.setType(FieldType.Text);
cf.setLabel(co.getFullName() + " Name");
co.setNameField(cf);
SaveResult[] results = metadataConnection
.updateMetadata(new Metadata[] { co });
for (SaveResult r : results) {
if (r.isSuccess()) {
System.out.println("Updated component: " + r.getFullName());
} else {
System.out
.println("Errors were encountered while updating "
+ r.getFullName());
for (Error e : r.getErrors()) {
System.out.println("Error message: " + e.getMessage());
System.out.println("Status code: " + e.getStatusCode());
}
}
}
} catch (ConnectionException ce) {
ce.printStackTrace();
}
}

Arguments
Name

Type

Description

metadata

Metadata[]

Array of one or more metadata components you wish to update.
Limit: 10. (For CustomMetadata and CustomApplication only, the limit is
200.)
You must submit arrays of only one type of component. For example, you
can submit an array of 10 custom objects or 10 profiles, but not a mix of
both types.

Response
SaveResult[]

CRUD-Based Calls

upsertMetadata()

upsertMetadata()
Creates or updates one or more metadata components in your organization synchronously.

Syntax
UpsertResult[] = metadataConnection.upsertMetadata(Metadata[] metadata);

Usage
Use the upsertMetadata() call to create or update any component that extends Metadata. All components must be of the same
type in the same call. For more details, see Metadata Components and Types.
If the specified components already exist in your organization, the upsertMetadata() call updates them. Otherwise,
upsertMetadata() creates these components. Components are matched by the fullname field. This call executes synchronously,
which means that the call returns only after the operation is completed.
Starting in API version 34.0, this call supports the AllOrNoneHeader header. By default, if AllOrNoneHeader isn’t used in API version
34.0 and later, this call can save a partial set of records for records with no errors (equivalent to AllOrNoneHeader=false). In API
version 33.0 and earlier, the default behavior is to only save all records when there are no failures in any record in the call (equivalent to
AllOrNoneHeader=true).

Version
Available in API version 31.0 and later.

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Required Fields
You must supply values for all the required fields in the component.

Valid Field Values
You must supply values that are valid for the field’s data type, such as integers (not alphabetic characters) for integer fields. In your client
application, follow the data formatting rules that are specified for your programming language and development tool. (Your development
tool handles the appropriate mapping of data types in SOAP messages.)

String Values
The API trims any leading and trailing white space when storing values in string fields. For example, if the value of a label field is
entered as " MyObject ", the value is stored in the database as "MyObject".

CRUD-Based Calls

upsertMetadata()

Basic Steps for Upserting Metadata Components
Use this process to upsert metadata components.
1. Create an array of Metadata objects that correspond to the components that you want to create or update. All components must
be of the same type.
2. Invoke upsertMetadata(), passing in the array of metadata components that you created in the previous step.
The upsertMetadata() call returns an array of UpsertResult objects. Each returned UpsertResult corresponds
to a component that you upserted and contains information about the upsert operation—whether the operation was successful,
the name of the component that was upserted, a flag indicating whether the component was created, and any errors that were
returned if the operation wasn’t successful.

Sample Code—Java
public void upsertMetadataSample() {
try {
// Create custom object to upsert
CustomObject co = new CustomObject();
String name = "MyCustomObject";
co.setFullName(name + "__c");
co.setDeploymentStatus(DeploymentStatus.Deployed);
co.setDescription("Upserted by the Metadata API");
co.setEnableActivities(true);
co.setLabel(name + " Object");
co.setPluralLabel(co.getLabel() + "s");
co.setSharingModel(SharingModel.ReadWrite);
CustomField nf = new CustomField();
nf.setType(FieldType.Text);
nf.setLabel("CustomField1");
co.setNameField(nf);
// Upsert the custom object
UpsertResult[] results = metadataConnection
.upsertMetadata(new Metadata[] { co });
for (UpsertResult r : results) {
if (r.isSuccess()) {
System.out.println("Success!");
if (r.isCreated()) {
System.out.println("Created component: "
+ r.getFullName());
} else {
System.out.println("Updated component: "
+ r.getFullName());
}
} else {
System.out
.println("Errors were encountered while upserting "
+ r.getFullName());
for (Error e : r.getErrors()) {
System.out.println("Error message: " + e.getMessage());

CRUD-Based Calls

deleteMetadata()

System.out.println("Status code: " + e.getStatusCode());
}
}
}
} catch (ConnectionException ce) {
ce.printStackTrace();
}
}

Arguments
Name

Type

Description

metadata

Metadata[]

An array of one or more metadata components that you want to create
or update
Limit: 10.
You must submit arrays of only one type of component. For example, you
can submit an array of 10 custom objects or 10 profiles, but not a mix of
both types.

Response
UpsertResult[]

deleteMetadata()
Deletes one or more metadata components from your organization synchronously.

Syntax
DeleteResult[] = metadataConnection.delete(string metadataType, string[] fullNames);

Usage
Use the deleteMetadata() call to delete any component that extends Metadata. All components must be of the same type in
the same call. For more details, see Metadata Components and Types.
This call executes synchronously, which means that the call returns only when the operation completes.
Starting in API version 34.0, this call supports the AllOrNoneHeader header. By default, if the AllOrNoneHeader isn’t used in any
API version, this call can delete a partial set of records for records with no errors (equivalent to AllOrNoneHeader=false). If
AllOrNoneHeader is set to true, no records are deleted if one or more records cause a failure.

Version
Available in API version 30.0 and later.

CRUD-Based Calls

deleteMetadata()

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Rules and Guidelines
When deleting components, consider the following rules and guidelines:
• Your client application must be logged in with sufficient access rights to delete individual components within the specified component.
For more information, see “Factors that Affect Data Access” in the SOAP API Developer's Guide.
• In addition, you might also need permission to access this component’s parent component.
• To ensure referential integrity, this call supports cascading deletions. If you delete a parent component, you delete its children
automatically, as long as each child component can be deleted.

Basic Steps for Deleting Metadata Components
Use the following process to delete metadata components:
1. Determine the metadata type of the components you want to delete and the fullName of each component to delete. You can
delete only components of the same type in a single call. The full names must match one or more full names returned by the
listMetadata() call. See Metadata for more details on the fullName field.
2. Invoke the deleteMetadata() call. For the first argument, pass in the name of the metadata type. For the second argument,
pass in an array of full names corresponding to the components you wish to delete.
A DeleteResult object is returned for each component you try to delete. It contains information about whether the operation
was successful, the name of the deleted component, and any errors returned if the operation wasn’t successful.

Sample Code—Java
public void deleteCustomObjectSync() {
try {
DeleteResult[] results = metadataConnection.deleteMetadata(
"CustomObject", new String[] { "MyCustomObject1__c",
"MyCustomObject2__c" });
for (DeleteResult r : results) {
if (r.isSuccess()) {
System.out.println("Deleted component: " + r.getFullName());
} else {
System.out
.println("Errors were encountered while deleting "
+ r.getFullName());
for (Error e : r.getErrors()) {
System.out.println("Error message: " + e.getMessage());
System.out.println("Status code: " + e.getStatusCode());
}
}
}
} catch (ConnectionException ce) {
ce.printStackTrace();
}
}

CRUD-Based Calls

renameMetadata()

Arguments
Name

Type

metadataType string
fullNames

string[]

Description
The metadata type of the components to delete.
Array of full names of the components to delete.
Limit: 10. (For CustomMetadata and CustomApplication only, the limit is 200.)
You must submit arrays of only one type of component. For example, you can submit an array
of 10 custom objects or 10 profiles, but not a mix of both types.

Response
DeleteResult[]

renameMetadata()
Renames a metadata component in your organization synchronously.

Syntax
SaveResult = metadataConnection.renameMetadata(string metadataType, String oldFullname,
String newFullname);

Usage
Use the renameMetadata() call to rename one metadata component in your organization. This call executes synchronously,
meaning the call returns only when the operation completes.
You can use this call to rename any of the objects that extend Metadata. For more details, see Metadata Components and Types.

Version
Available in API version 30.0 and later.

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Basic Steps for Renaming Metadata Components
Use the following process to rename a metadata component:
1. Determine the metadata type of the component you want to rename, its current full name, and the new full name. See Metadata
for more details on the fullName field.

CRUD-Based Calls

create()

2. Invoke the renameMetadata() call. For the first argument, pass in the name of the metadata type. Pass in the old full name
as the second argument and the new full name as the last argument.
A SaveResult object is returned that contains information about whether the operation was successful, the name of the renamed
component (which is the new name if the renaming was successful), and any errors returned if the operation wasn’t successful.

Sample Code—Java
public void renameCustomObjectSync() {
try {
SaveResult[] results = metadataConnection.renameMetadata(
"CustomObject", "MyCustomObject1__c","MyCustomObject1New__c");
for (SaveResult r : results) {
if (r.isSuccess()) {
System.out.println("Renamed component: " + r.getName());
}
else {
System.out.println("Errors were encountered while renaming " + r.getName());
for(Error e : r.getErrors()) {
System.out.println("Error message: " + e.getMessage());
System.out.println("Status code: " + e.getStatusCode());
}
}
}
} catch (ConnectionException ce) {
ce.printStackTrace();
} catch (InterruptedException ie) {
ie.printStackTrace();
}
}

Arguments
Name

Type

metadataType string

Description
The metadata type of the components to rename.

oldFullName

string

The current component full name.

newFullName

string

The new component full name.

Response
SaveResult

create()
Deprecated. Adds one or more new metadata components to your organization asynchronously. This call is removed as of API version
31.0 and is available in earlier versions only. Use createMetadata() instead.

CRUD-Based Calls

create()

This call can be used to create any of the objects that extend Metadata. For more details, see Metadata Components and Types on page
117.

Syntax
AsyncResult[] = metadatabinding.create(Metadata[] metadata);

Usage
Use this call to add one or more metadata components to your organization.

Version
This call is available in API version 30.0 and earlier only. This call is not available in API version 31.0 and later. Use createMetadata()
instead.

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Required Fields
Required fields are determined by the metadata components being created. For more information about specific component types, see
Metadata Components and Types on page 117.

Valid Data Values
You must supply values that are valid for the field’s data type, such as integers for integer fields (not alphabetic characters). In your client
application, follow the data formatting rules specified for your programming language and development tool (your development tool
handles the appropriate mapping of data types in SOAP messages).

String Values
When storing values in string fields, the API trims any leading and trailing whitespace. For example, if the value of a label field is
entered as "MyObject " the value is stored in the database as "MyObject".

Basic Steps for Creating Metadata Components
Use the following process to create metadata components:
1. Design an array and populate it with the components you want to create. All components must be of the same type.
2. Call create() with the component array passed in as an argument.
3. An AsyncResult object is returned for each component you triy to create, and is updated with status information as the operation
moves from a queue to completed or error state. Call checkStatus() in a loop until the status values in AsyncResult indicate
that all create operations are completed. Start with a wait time of one second between iterations of checkStatus() calls, and
double the wait time each time you make a subsequent call.

CRUD-Based Calls

delete()

Sample Code—Java
See Step 3: Walk Through the Java Sample Code on page 6 for sample Java code using the create() call.

Arguments
Name

Type

Description

metadata

Metadata[]

Array of one or more metadata components.
Limit: 10.
You must submit arrays of only one type of component. For example, you could submit an
array of 10 custom objects or 10 profiles, but not a mix of both types.

Response
AsyncResult[]
SEE ALSO:
createMetadata()
update()
delete()
checkStatus()

delete()
Deprecated. Deletes one or more components from your organization asynchronously. This call is removed as of API version 31.0 and is
available in earlier versions only. Use deleteMetadata() instead.
You can use this call to delete any of the objects that extend Metadata. For more details, see Metadata Components and Types on page
117.

Syntax
AsyncResult[] = metadataConnection.delete(Metadata[] metadata);

Usage
Use this call to delete one or more components from your organization.

Version
This call is available in API version 30.0 and earlier only. This call is not available in API version 31.0 and later. Use deleteMetadata()
instead.

CRUD-Based Calls

delete()

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Basic Steps for Deleting Metadata Components
Use the following process to delete metadata components:
1. Determine the fullName of each component you want to delete. See Metadata for more details on the fullName field. You
can only delete components of the same type in a single call.
2. Invoke the delete() call, passing in the array of metadata components with fullName specified.
3. An AsyncResult object is returned for each component you try to delete, and is updated with status information as the operation
moves from a queue to completed or error state. Call checkStatus() in a loop until the status values in AsyncResult indicate
that all the delete operations are completed. Start with a wait time of one second between iterations of checkStatus() calls,
and double the wait time each time you make a subsequent call.

Sample Code—Java
public void deleteCustomObject() {
try {
CustomObject co = new CustomObject();
co.setFullName("MyCustomObject__c");
AsyncResult[] ars = metadataConnection.create(new Metadata[]
{co});
AsyncResult asyncResult = ars[0];
long waitTimeMilliSecs = 1000;
while (!asyncResult.isDone()) {
Thread.sleep(waitTimeMilliSecs);
// double the wait time for the next iteration
waitTimeMilliSecs *= 2;
asyncResult = mdConnection.checkStatus(
new String[] {asyncResult.getId()})[0];
System.out.println("Status is: " + asyncResult.getState());
}
} catch (ConnectionException ce) {
ce.printStackTrace();
} catch (InterruptedException ie) {
ie.printStackTrace();
}
}

CRUD-Based Calls

update()

Arguments
Name

Type

Description

metadata

Metadata[]

Array of one or more metadata components. You only need to set the fullName field in
the Metadata object.
Limit: 10.
You must submit arrays of only one type of component. For example, you could submit an
array of 10 custom objects or 10 profiles, but not a mix of both types.

Response
AsyncResult[]
SEE ALSO:
deleteMetadata()
create()
update()
checkStatus()

update()
Deprecated. Updates one or more components in your organization asynchronously. This call is removed as of API version 31.0 and is
available in earlier versions only. Use updateMetadata() or renameMetadata() instead.
This call can be used to update any of the objects that extend Metadata. For more details, see Metadata Components and Types on page
117.

Syntax
AsyncResult[] = metadataConnection.update(UpdateMetadata[] metadata);

Usage
Use this call to update one or more components. This call is analogous to the ALTER TABLE statement in SQL.

Version
This call is available in API version 30.0 and earlier only. This call is not available in API version 31.0 and later. Use updateMetadata()
instead to update metadata components or renameMetadata() to rename a metadata component.

CRUD-Based Calls

update()

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Required Fields
You must supply values for all the required fields in the component.

Valid Field Values
You must supply values that are valid for the field’s data type, such as integers for integer fields (not alphabetic characters). In your client
application, follow the data formatting rules specified for your programming language and development tool (your development tool
handles the appropriate mapping of data types in SOAP messages).

Basic Steps for Updating Metadata Components
Use this process to update metadata components:
1. Create an array of UpdateMetadata components and populate it with the components you wish to update. All components
must be of the same type.
2. Invoke the update() call, passing in the array of metadata components to update.
3. An AsyncResult object is returned for each component you try to update, and is updated with status information as the operation
moves from a queue to completed or error state. In a loop, call checkStatus() until the status values in AsyncResult indicate
that all the update operations are completed. Start with a wait time of one second between iterations of checkStatus() calls,
and double the wait time each time you make a subsequent call.

Sample Code—Java
public void updateCustomObject() {
try {
CustomObject co = new CustomObject();
String name = "MyCustomObject";
co.setFullName(name + "__c");
co.setDeploymentStatus(DeploymentStatus.Deployed);
co.setDescription("Created by the Metadata API");
co.setEnableActivities(true);
co.setLabel(name + " Object");
co.setPluralLabel(co.getLabel() + "s");
co.setSharingModel(SharingModel.ReadWrite);
CustomField nf = new CustomField();
nf.setType(FieldType.Text);
nf.setLabel(co.getFullName() + " Name");

CRUD-Based Calls

update()

co.setNameField(nf);
UpdateMetadata updateMetadata = new UpdateMetadata();
updateMetadata.setMetadata(co);
updateMetadata.setCurrentName("TheCurrentName");
AsyncResult[] ars = metadataConnection.update(new UpdateMetadata[]
{ updateMetadata });
AsyncResult asyncResult = ars[0];
// set initial wait time to one second in milliseconds
long waitTimeMilliSecs = 1000;
while (!asyncResult.isDone()) {
Thread.sleep(waitTimeMilliSecs);
// double the wait time for the next iteration
waitTimeMilliSecs *= 2;
asyncResult = metadataConnection.checkStatus(
new String[] {asyncResult.getId()})[0];
System.out.println("Status is: " + asyncResult.getState());
}
if (asyncResult.getState() != AsyncRequestState.Completed) {
System.out.println(asyncResult.getStatusCode() + " msg: " +
asyncResult.getMessage());
}
} catch (InterruptedException ie) {
ie.printStackTrace();
} catch (ConnectionException ce) {
ce.printStackTrace();
}
}

Arguments
Name

Type

Description

metadata

UpdateMetadata[]

Array of one or more UpdateMetadata data structures that represent the
components you wish to update.
Limit: 10.
You must submit arrays of only one type of component. For example, you
could submit an array of 10 custom objects or 10 profiles, but not a mix
of both types.

UpdateMetadata
One or more UpdateMetadata objects are defined in the metadata argument. This object can be used to update any of the objects
that extend Metadata. For more details, see Metadata Components and Types on page 117. Each UpdateMetadata object has the following
fields:

CRUD-Based Calls

update()

Field

Field Type

Description

currentName

string

The API name of the component or field before the update. For example,
if you wanted to update a CustomObject named Foo, the value of this
field would be Foo__c. This value is supplied because this call may
change the name, and the value here provides mapping.

metadata

Metadata

Full specification of the component or field you wish to update.

Response
AsyncResult[]
SEE ALSO:
updateMetadata()
create()
delete()
checkStatus()

CHAPTER 8

Utility Calls

Use the following utility calls to gather information that is useful for working with the file-based or CRUD-based calls.
• (Deprecated) checkStatus()
• describeMetadata()
• describeValueType()
• listMetadata()

checkStatus()
Deprecated. Checks the status of asynchronous metadata calls create(), update(), or delete(), or the declarative metadata
call retrieve(). This call is removed as of API version 31.0 and is available only in earlier versions.
Note: Starting in API version 29.0, you no longer have to call checkStatus() after a deploy() call to get information
about deployments. Similarly, starting in API version 31.0, you no longer have to call checkStatus() after a retrieve()
call. The checkStatus() call has been replaced by checkDeployStatus() and checkRetrieveStatus() for deploy and retrieve
operations respectively.

Syntax
AsyncResult[] = metadatabinding.checkStatus(ID[] ids);

Usage
Use this call to check whether or not an asynchronous metadata call or declarative metadata call has completed.

Version
This call is available only in API version 30.0 and earlier. This call is not available in API version 31.0 and later.

Sample Code—Java
See Step 3: Walk Through the Java Sample Code on page 6 for sample Java code using this call.

Utility Calls

describeMetadata()

Arguments
Name

Type

Description

ids

ID[]

Array of one or more IDs. Each ID is returned in an AsyncResult and corresponds to a component
being created, updated, deleted, deployed, or retrieved.

Response
AsyncResult[]

describeMetadata()
This call retrieves the metadata that describes your organization. This information includes Apex classes and triggers, custom objects,
custom fields on standard objects, tab sets that define an app, and many other metadata types.

Syntax
DescribeMetadataResult = metadataConnection.describeMetadata(double apiVersion);

Arguments
Name

Type

Description

apiVersion

double

The API version for which you want metadata; for example, 39.0.

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Sample Code—Java
public void describeMetadata() {
try {
double apiVersion = 21.0;
// Assuming that the SOAP binding has already been established.
DescribeMetadataResult res =
metadataConnection.describeMetadata(apiVersion);
StringBuffer sb = new StringBuffer();
if (res != null && res.getMetadataObjects().length > 0) {
for (DescribeMetadataObject obj : res.getMetadataObjects()) {
sb.append("***************************************************\n");
sb.append("XMLName: " + obj.getXmlName() + "\n");
sb.append("DirName: " + obj.getDirectoryName() + "\n");
sb.append("Suffix: " + obj.getSuffix() + "\n");

Utility Calls

describeValueType()

sb.append("***************************************************\n");
}
} else {
sb.append("Failed to obtain metadata types.");
}
System.out.println(sb.toString());
} catch (ConnectionException ce) {
ce.printStackTrace();
}
}

Response
DescribeMetadataResult

When to Use describeMetadata() and describeValueType()?
Use the describeMetadata() call to get high-level information about all the metadata types that are available for your organization,
such as type names and file suffixes. Use the describeValueType() call to get granular information about a specific metadata
type, such as fields contained within the type.

describeValueType()
Retrieves the metadata describing a given metadata type (value type).
describeValueType() accepts a namespace and a type name, and returns a DescribeValueTypeResult object. This

call is available in API version 33.0 and later.

Syntax
DescribeValueTypeResult = connection.describeValueType("{namespace}type_name");

Example
Describe Apex class metadata in the Metadata namespace:
DescribeValueTypeResult =
metadataConnection.describeValueType("{http://soap.sforce.com/2006/04/metadata}ApexClass");

Describe Apex class metadata in the Tooling namespace:
DescribeValueTypeResult =
toolingConnection.describeValueType("{urn:metadata.tooling.soap.sforce.com}ApexClass");

Utility Calls

describeValueType()

Arguments
Name

Type

Description

type

string

The name of the metadata type for which you want metadata; for example, ApexClass.
Include the namespace.

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Sample Code—Java
The following example describes several metadata types by specifying the Metadata namespace. Each metadata type is described using
the helper method, doDescribe(), which calls the describeValueType() Metadata API call. The sample retrieves information
from the returned DescribeValueTypeResult: a property, the parent field (if any), and the fields. Next, the sample iterates
through the fields and outputs information about each field.
public void describeValueType() throws ConnectionException {
doDescribe("{http://soap.sforce.com/2006/04/metadata}CustomObject");
doDescribe("{http://soap.sforce.com/2006/04/metadata}CustomField");
doDescribe("{http://soap.sforce.com/2006/04/metadata}EmailTemplate");
}
public void doDescribe(String type) throws ConnectionException {
DescribeValueTypeResult result = metadataConnection.describeValueType(type);
StringBuffer sb = new StringBuffer();
sb.append("Describing " + type + " ...\n");
if (result.getApiCreatable() == true) {
sb.append("Is API creatable.\n");
} else {
sb.append("Is not API creatable.\n");
}
ValueTypeField parentField = result.getParentField();
if (parentField != null) {
sb.append("** Parent type fields **\n");
if (parentField.getIsForeignKey()) {
sb.append("This field is a foreign key.\n");
for (String fkDomain : parentField.getForeignKeyDomain()) {
sb.append("Foreign key domain: " + fkDomain + "\n");
}
}
}
sb.append("** Value type fields **\n");
for(ValueTypeField field : result.getValueTypeFields()) {
sb.append("***************************************************\n");
sb.append("Name: " + field.getName() + "\n");

Utility Calls

describeValueType()

sb.append("SoapType: " + field.getSoapType() + "\n");
if (field.getIsForeignKey()) {
sb.append("This field is a foreign key.\n");
for (String fkDomain : field.getForeignKeyDomain()) {
sb.append("Foreign key domain: " + fkDomain + "\n");
}
}
sb.append("***************************************************\n");
}
System.out.println(sb.toString());
}

To run the previous example with the Tooling WSDL, replace the namespace with the Tooling namespace in the helper function call as
follows. Also, use the Tooling connection instead of the Metadata connection to make the describeValueType() call.
doDescribe("{urn:metadata.tooling.soap.sforce.com}CustomObject");
doDescribe("{urn:metadata.tooling.soap.sforce.com}CustomField");
doDescribe("{urn:metadata.tooling.soap.sforce.com}EmailTemplate");

After you run the sample, the output looks similar to the following.
Describing {http://soap.sforce.com/2006/04/metadata}CustomObject ...
Is API creatable.
** Value type fields **
***************************************************
Name: actionOverrides
SoapType: ActionOverride
***************************************************
***************************************************
Name: allowInChatterGroups
SoapType: boolean
***************************************************
***************************************************
Name: articleTypeChannelDisplay
SoapType: ArticleTypeChannelDisplay
***************************************************
***************************************************
Name: businessProcesses
SoapType: BusinessProcess
***************************************************
***************************************************
Name: compactLayoutAssignment
SoapType: string
***************************************************
***************************************************
Name: compactLayouts
SoapType: CompactLayout
***************************************************
***************************************************
Name: customHelp
SoapType: string
This field is a foreign key.
Foreign key domain: ApexPage
Foreign key domain: Scontrol

Utility Calls

listMetadata()

***************************************************

Describing {http://soap.sforce.com/2006/04/metadata}CustomField ...
Is API creatable.
** Parent type fields **
This field is a foreign key.
Foreign key domain: CustomObject
** Value type fields **
***************************************************
Name: caseSensitive
SoapType: boolean
***************************************************
***************************************************
Name: customDataType
SoapType: string
***************************************************
***************************************************
Name: defaultValue
SoapType: string
***************************************************

Response
DescribeValueTypeResult

listMetadata()
This call retrieves property information about metadata components in your organization. Data is returned for the components that
match the criteria specified in the queries parameter. The queries array can contain up to three ListMetadataQuery queries for
each call. This call supports every metadata type: both top-level, such as CustomObject and ApexClass, and child types, such as CustomField
and RecordType.

Syntax
FileProperties[] = metadataConnection.listMetadata(ListMetadataQuery[] queries, double
asOfVersion);

Usage
This call is useful when you want to identify individual components in package.xml for a retrieve() call or if you want a
high-level view of particular metadata types in your organization. For example, you could use this call to return a list of names of all the
CustomObject or Layout components in your organization, and use this information to make a subsequent retrieve() call to return
a subset of these components. For more information about working with package.xml, see Deploying and Retrieving Metadata on
page 15.

Utility Calls

listMetadata()

Note: This is a synchronous call so the results are returned in one call. This differs from asynchronous calls, such as retrieve(),
where at least one subsequent call is needed to get the results.

Permissions
Your client application must be logged in with the “Modify All Data” permission.

Sample Code—Java
The sample code below lists information about your custom objects. The code assumes that the SOAP binding has already been
established.
public void listMetadata() {
try {
ListMetadataQuery query = new ListMetadataQuery();
query.setType("CustomObject");
//query.setFolder(null);
double asOfVersion = 39.0;
// Assuming that the SOAP binding has already been established.
FileProperties[] lmr = metadataConnection.listMetadata(
new ListMetadataQuery[] {query}, asOfVersion);
if (lmr != null) {
for (FileProperties n : lmr) {
System.out.println("Component fullName: " + n.getFullName());
System.out.println("Component type: " + n.getType());
}
}
} catch (ConnectionException ce) {
ce.printStackTrace();
}
}

Arguments
Name

Type

Description

queries

ListMetadataQuery[] A list of objects that specify which components you are interested in.

asOfVersion

double

The API version for the metadata listing request. If you don't specify a value in this field, it
defaults to the API version specified when you logged in. This field allows you to override
the default and set another API version so that, for example, you could list the metadata for
a metadata type that was added in a later version than the API version specified when you
logged in. This field is available in API version 18.0 and later.

Response
FileProperties

Utility Calls

ListMetadataQuery

ListMetadataQuery
The ListMetadataQuery parameter specified in a listMetadata() call consists of the following properties:
Name

Type

Description

folder

string

The folder associated with the component. This field is required
for components that use folders, such as Dashboard, Document,
EmailTemplate, or Report.

type

string

Required. The metadata type, such as CustomObject,
CustomField, or ApexClass.

CHAPTER 9

Result Objects

Use the following objects to get the results of your file-based or CRUD-based calls.
IN THIS SECTION:
AsyncResult
Contains the ID of a deployment or retrieval. In API version 28.0 and earlier, contains status information of any asynchronous metadata
call.
CancelDeployResult
Contains information about a deployment cancellation—whether the cancellation completed and the deployment ID.
DeployResult
Contains information about the success or failure of the associated deploy() call.
DescribeMetadataResult
Contains information about the organization that is useful for developers working with declarative metadata.
DescribeValueTypeResult
Contains information about a value type that is useful for developers working with declarative metadata.
ReadResult
Contains result information for the readMetadata call.
RetrieveResult
Contains information about the success or failure of the associated retrieve() call.
SaveResult
Contains result information for the createMetadata, updateMetadata, or renameMetadata call.
DeleteResult
Contains result information for the deleteMetadata call.
UpsertResult
Contains information about the result of the associated upsertMetadata() call.
Error
Represents an error that occurred during a synchronous CRUD (createMetadata(), updateMetadata(), or
deleteMetadata()) operation.

AsyncResult
Contains the ID of a deployment or retrieval. In API version 28.0 and earlier, contains status information of any asynchronous metadata
call.

Result Objects

AsyncResult

API Version 31.0 and Later
In API version 31.0, the process of retrieving metadata has been simplified and retrieval properties have been moved to RetrieveResult.
Also, the asynchronous create(), update(), and delete() calls have been removed. Therefore, only the id field in AsyncResult
is used. The id field is the ID of a deployment or retrieval.
AsyncResult is returned by the following asynchronous calls.
• deploy()
• retrieve()
AsyncResult has the following field that is in use.
Name

Type

Description

Required. The ID of the component that’s being deployed or retrieved.

All fields in AsyncResult other than id are deprecated as of API version 31.0. These fields exist but are no longer in use.
• done
• message
• state
• statusCode

API Versions 29.0 and 30.0
In API version 29.0, Salesforce moved several properties from the AsyncResult object to the DeployResult object and added several new
ones, to improve the process for getting information about deployments. For more information about these changes, see deploy().
In API versions 29.0 and 30.0, AsyncResult is returned by the same asynchronous calls as in API version 28.0 and earlier, but it has different
fields.
Name

Type

Description

done

boolean

Required. Indicates whether the call has been completed (true) or not
(false).

Required. The ID of the component that’s being created, updated, deleted,
deployed, or retrieved.

message

string

The message that corresponds to the returned statusCode field, if any.

state

AsyncRequestState Required. The AsyncRequestState object has one of four possible values.
(enumeration of • Queued: This call has not started. It is waiting in a queue.
type string)
• InProgress: This call has started but has not been completed.
• Completed: This call has been completed.
• Error: An error occurred. See the statusCode for more information.

Result Objects

AsyncResult

Name

Type

Description

statusCode

StatusCode
(enumeration of
type string)

If an error occurred during the create(), update(), or delete() call,
a status code is returned, and the message that corresponds to the status code
is returned in the message field.
For a description of each StatusCode value, see “StatusCode” in the SOAP API
Developer's Guide.

API Version 28.0 and Earlier
In API version 28.0 and earlier, AsyncResult is returned by the following asynchronous calls.
• deploy()
• retrieve()
• create()
• update()
• delete()
Use the checkStatus() call against each object to discover when the call is completed for that object. Salesforce updates each
AsyncResult object as the call is completed or when errors occur.
Similarly, the deploy() and retrieve() calls use AsyncResult, though you must subsequently use checkDeployStatus()
or checkRetrieveStatus() respectively to get more status information for the deployment or retrieval.
AsyncResult has the following fields.
Name

Type

Description

checkOnly

boolean

Indicates whether this deployment is being used to check the validity of the
deployed files without making any changes in the organization (true) or not
(false). A check-only deployment does not deploy any components or
change the organization in any way. This field is available in API version 16.0
and later and is relevant only for the deploy() call.

done

boolean

Required. Indicates whether the call has been completed (true) or not
(false).

Required. The ID of the component that’s being created, updated, deleted,
deployed, or retrieved.

message

string

The message that corresponds to the returned statusCode field, if any.

numberComponentErrors int

The number of components that generated errors during this deployment.
This field is available in API version 16.0 and later and is relevant only for the
deploy() call.

numberComponentsDeployed int

The number of components that have been deployed for this deployment.
This field in conjunction with the numberComponentsTotal field gives
you an indication of the progress of the deployment. This field is available in
API version 16.0 and later and is relevant only for the deploy() call.

Result Objects

Name

AsyncResult

Type

Description

numberComponentsTotal int

The total number of components in the deployment. This field in conjunction
with the numberComponentsDeployed field gives you an indication of
the progress of the deployment. This field is available in API version 16.0 and
later and is relevant only for the deploy() call.

numberTestErrors

int

The number of Apex tests that generated errors during this deployment. This
field is available in API version 16.0 and later and is relevant only for the
deploy() call.

numberTestsCompleted

int

The number of Apex tests that have been completed for this deployment. This
field in conjunction with the numberTestsTotal field gives you an
indication of the progress of tests for the deployment. This field is available in
API version 16.0 and later and is relevant only for the deploy() call.

numberTestsTotal

int

The total number of Apex tests in the deployment. This field in conjunction
with the numberTestsCompleted field gives you an indication of the
progress of tests for the deployment. The value in this field is not accurate until
the deployment has started running tests for the components that are being
deployed. This field is available in API version 16.0 and later and is relevant only
for the deploy() call.

secondsToWait

int

This field is no longer supported for API version 13.0 and later and is provided
only for backward compatibility. The field was removed in API version 17.0.
Indicates the number of seconds before the call is likel to be completed. This
is an estimate only. A reasonable approach is to wait one second before calling
checkStatus() to see if the operation is complete. Double your wait time
for each successive iteration of checkStatus() calls until the operation
is complete.

state

stateDetail

string

stateDetailLastModifiedDate dateTime

statusCode

StatusCode
(enumeration of
type string)

Indicates which component is being deployed or which Apex test class is
running. This field is available in API version 16.0 and later and is relevant only
for the deploy() call.
The date and time when the stateDetail field was last modified. This field
is available in API version 16.0 and later and is relevant only for the deploy()
call.
If an error occurred during the create(), update(), delete(), or
deploy() call, a status code is returned, and the message that corresponds
to the status code is returned in the message field.
For a description of each StatusCode value, see “StatusCode” in the SOAP API
Developer's Guide.

Result Objects

CancelDeployResult

CancelDeployResult
Contains information about a deployment cancellation—whether the cancellation completed and the deployment ID.
The asynchronous metadata call cancelDeploy() returns a CancelDeployResult object.

Version
Available in API version 30.0 and later.
CancelDeployResult has the following properties.

Name

Type

Description

done

boolean

Indicates whether the deployment cancellation, which is started through
cancelDeploy(), has completed (true) or not (false).
When a deployment hasn’t started yet and is still in the queue, the deployment
is canceled immediately with the cancelDeploy() call and this field returns
true. Otherwise, this field returns false when the cancellation is in progress.

ID of the deployment being canceled.

DeployResult
Contains information about the success or failure of the associated deploy() call.
The asynchronous metadata call checkDeployStatus() returns a DeployResult object.
In API version 29.0, Salesforce moved several properties from the AsyncResult on page 87 object to the DeployResult object to improve
the process for getting information about deployments. For more information about these changes, see deploy() on page 33.
For API version 29.0 and later, the DeployResult object has the following properties.
Name

Type

Description

ID of the component being deployed.

canceledBy

The ID of the user who canceled the deployment.
This field is available in API version 30.0 and later.

canceledByName

string

The full name of the user who canceled the deployment.
This field is available in API version 30.0 and later.

checkOnly

boolean

completedDate

dateTime

Timestamp for when the deployment process ended.

Result Objects

DeployResult

Name

Type

Description

createdBy

The ID of the user who created the deployment.
This field is available in API version 30.0 and later.

createdByName

string

The full name of the user who created the deployment.
This field is available in API version 30.0 and later.

createdDate

dateTime

Timestamp for when the deploy() call was received.

details

DeployDetails[]

Provides the details of a deployment that is in-progress or ended, if the
includeDetails parameter is set to true in the
checkDeployStatus() call.

done

boolean

Indicates whether the server finished processing the deploy() call for the
specified id.

errorMessage

string

Message corresponding to the values in the errorStatusCode field, if any.

errorStatusCode

string

If an error occurred during the deploy() call, a status code is returned, and the
message corresponding to the status code is returned in the
errorMessagefield.
For a description of each StatusCode value, see “StatusCode” in the SOAP API
Developer's Guide.

ignoreWarnings

boolean

Optional. Defaults to false. Specifies whether a deployment should continue
even if the deployment generates warnings. Do not set this argument to true
for deployments to production organizations.

lastModifiedDate

dateTime

Timestamp of the last update for the deployment process.

numberComponentErrors int

The number of components that generated errors during this deployment.

numberComponentsDeployed int

The number of components deployed in the deployment process. Use this value
with the numberComponentsTotal value to get an estimate of the
deployment’s progress.

numberComponentsTotal int

The total number of components in the deployment. Use this value with the
numberComponentsDeployed value to get an estimate of the deployment’s
progress.

numberTestErrors

int

The number of Apex tests that have generated errors during this deployment.

numberTestsCompleted int

The number of completedApex tests for this deployment. Use this value with the
numberTestsTotal value to get an estimate of the deployment’s test
progress.

int

The total number of Apex tests for this deployment. Use this value with the
numberTestsCompleted value to get an estimate of the deployment’s test
progress. The value in this field is not accurate until the deployment has started
running tests for the components being deployed.

numberTestsTotal

Result Objects

DeployResult

Name

Type

Description

runTestsEnabled

boolean

Indicates whether Apex tests were run as part of this deployment (true) or not
(false). Tests are either automatically run as part of a deployment or can be set
to run in DeployOptions for the deploy() call. For information on when
tests are automatically run, see Running Tests in a Deployment.
This field is available in API version 30.0 and later.

rollbackOnError

boolean

Optional. Defaults to true. Indicates whether any failure causes a complete rollback
(true) or not (false). If false, whatever set of actions can be performed
without errors are performed, and errors are returned for the remaining actions.
This parameter must be set to true if you are deploying to a production
organization.

startDate

dateTime

Timestamp for when the deployment process began.

stateDetail

string

Indicates which component is being deployed or which Apex test class is running.

status

DeployStatus
(enumeration of
type string)

Indicates the current state of the deployment. The valid values are:
• Pending
• InProgress
• Succeeded
• SucceededPartial
• Failed
• Canceling
• Canceled

success

boolean

Indicates whether the deployment was successful (true) or not (false).

DeployDetails
These fields provide more information for the details field of the DeployResult object, if the includeDetails parameter is set
to (true in the deploy() call.
Note: While a deployment is still in-progress, the DeployDetails object only contains componentFailures data. After the
deployment process finishes, the other fields populate with the data for the entire deployment.
Name

Type

Description

componentFailures DeployMessage[]

One or more DeployMessage objects containing deployment errors for each
component.

componentSuccesses DeployMessage[]

One or more DeployMessage objects containing successful deployment details for
each component.

retrieveResult

RetrieveResult

If the performRetrieve parameter was specified for the deploy() call, a
retrieve() call is performed immediately after the deploy() process
completes. This field contains the results of that retrieval.

Result Objects

DeployResult

Name

Type

Description

runTestResult

RunTestsResult

If tests were run for the deploy() call, this field contains the test results. While a
deployment is still in-progress, this field only contains error data. After the deployment
process finishes, this field populates with the data for the entire deployment.

For API version 28.0 and earlier, the DeployResult object has the following properties.
Name

Type

Description

ID of the component being deployed.

messages

DeployMessage[]

Contains information about the success or failure of a deploy() call.

retrieveResult RetrieveResult

If the performRetrieve parameter was specified for the deploy() call, a
retrieve() call is performed immediately after the deploy() process completes.
This field contains the results of that retrieval.

runTestResult RunTestsResult

If tests were run for the deploy() call, this field contains the test results.

success

boolean

Indicates whether the deployment was successful (true) or not (false).

DeployMessage
Each DeployResult object contains one or more DeployMessage objects. Each DeployMessage object contains information about the
deployment success or failure of a component in the deployment .zip file:
Name

Type

Description

changed

boolean

If true, the component was changed as a result of this deployment. If false, the
deployed component was the same as the corresponding component already in the
organization.

columnNumber

int

Each component is represented by a text file. If an error occurred during deployment,
this field represents the column of the text file where the error occurred.

componentType

string

The metadata type of the component in this deployment.
This field is available in API version 30.0 and later.

created

boolean

If true, the component was created as a result of this deployment. If false, the
component was either deleted or modified as a result of the deployment.

createdDate

dateTime

The date and time when the component was created as a result of this deployment.
This field is available in API version 30.0 and later.

deleted

boolean

If true, the component was deleted as a result of this deployment. If false, the
component was either new or modified as result of the deployment.

fileName

string

The name of the file in the .zip file used to deploy this component.

Result Objects

DeployResult

Name

Type

Description

fullName

string

The full name of the component.
Inherited from Metadata, this field is not defined in the WSDL for this metadata type.
It must be specified when creating, updating, or deleting. See create() to see an
example of this field specified for a call.

ID of the component being deployed.

lineNumber

int

Each component is represented by a text file. If an error occurred during deployment,
this field represents the line number of the text file where the error occurred.

problem

string

If an error or warning occurred, this field contains a description of the problem that
caused the compile to fail.

problemType

DeployProblemType Indicates the problem type. The problem details are tracked in the problem field.
(enumeration of
The valid values are:
type string)
• Warning
• Error
This field is available in API version 18.0 and later. Prior to version 18.0, there was no
distinction between warnings and errors. All problems were treated as errors and
prevented a successful deployment.

success

boolean

Indicates whether the component was successfully deployed (true) or not (false).

RunTestsResult
Contains information about the execution of unit tests, including whether unit tests were completed successfully, code coverage results,
and failures.
A RunTestsResult object has the following properties
Name

Type

Description

apexLogId

string

The ID of an ApexLog object that is created at the end of a test run. The ApexLog
object is created if there is an active trace flag on the user running an Apex test,
or on a class or trigger being executed.
This field is available in API version 35.0 and later.

codeCoverage

CodeCoverageResult[]

An array of one or more CodeCoverageResult objects that contains the details
of the code coverage for the specified unit tests.

codeCoverageWarnings CodeCoverageWarning[] An array of one or more code coverage warnings for the test run. The results

include both the total number of lines that could have been executed, as well
as the number, line, and column positions of code that was not executed.
failures

RunTestFailure[]

An array of one or more RunTestFailure objects that contain information about
the unit test failures, if there are any.

numFailures

int

The number of failures for the unit tests.

Result Objects

DeployResult

Name

Type

Description

numTestsRun

int

The number of unit tests that were run.

successes

RunTestSuccess[]

An array of one or more RunTestSuccess objects that contain information about
successes, if there are any.

totalTime

double

The total cumulative time spent running tests. This can be helpful for
performance monitoring.

CodeCoverageResult
The RunTestsResult object contains this object. It contains information about whether or not the compile of the specified Apex and run
of the unit tests was successful.
Name

Type

Description

dmlInfo

CodeLocation[]

For each class or trigger tested, for each portion of code tested, this property contains
the DML statement locations, the number of times the code was executed, and the
total cumulative time spent in these calls. This can be helpful for performance
monitoring.

The ID of the CodeLocation. The ID is unique within an organization.

locationsNotCovered CodeLocation[]

For each class or trigger tested, if any code is not covered, the line and column of the
code not tested, and the number of times the code was executed.

methodInfo

CodeLocation[]

For each class or trigger tested, the method invocation locations, the number of times
the code was executed, and the total cumulative time spent in these calls. This can
be helpful for performance monitoring.

name

string

The name of the class or trigger covered.

namespace

string

The namespace that contained the unit tests, if one is specified.

numLocations

int

The total number of code locations.

soqlInfo

CodeLocation[]

For each class or trigger tested, the location of SOQL statements in the code, the
number of times this code was executed, and the total cumulative time spent in
these calls. This can be helpful for performance monitoring.

type

string

Do not use. In early, unsupported releases, used to specify class or package.

CodeCoverageWarning
The RunTestsResult object contains this object. It contains information about the Apex class which generated warnings.
This object has the following properties.
Name

Type

Description

The ID of the CodeLocation. The ID is unique within an organization.

message

string

The message of the warning generated.

Result Objects

DeployResult

Name

Type

Description

name

string

The namespace that contained the unit tests, if one is specified.

namespace

string

The namespace that contained the unit tests, if one is specified.

RunTestFailure
The RunTestsResult object returns information about failures during the unit test run.
This object has the following properties.
Name

Type

Description

The ID of the class which generated failures.

message

string

The failure message.

methodName

string

The name of the method that failed.

name

string

The name of the class that failed.

namespace

string

The namespace that contained the class, if one was specified.

seeAllData

boolean

Indicates whether the test method has access to organization data (true) or not
(false).
This field is available in API version 33.0 and later.

stackTrace

string

The stack trace for the failure.

time

double

The time spent running tests for this failed operation. This can be helpful for
performance monitoring.

type

string

Do not use. In early, unsupported releases, used to specify class or package.

RunTestSuccess
The RunTestsResult object returns information about successes during the unit test run.
This object has the following properties.
Name

Type

Description

The ID of the class which generated the success.

methodName

string

The name of the method that succeeded.

name

string

The name of the class that succeeded.

namespace

string

The namespace that contained the unit tests, if one is specified.

seeAllData

boolean

Indicates whether the test method has access to organization data (true) or not
(false).
This field is available in API version 33.0 and later.

Result Objects

DescribeMetadataResult

Name

Type

Description

time

double

The time spent running tests for this operation. This can be helpful for performance
monitoring.

CodeLocation
The RunTestsResult object contains this object in a number of fields.
This object has the following properties.
Name

Type

Description

column

int

The column location of the Apex tested.

line

int

The line location of the Apex tested.

numExecutions

int

The number of times the Apex was executed in the test run.

time

double

The total cumulative time spent at this location. This can be helpful for performance
monitoring.

DescribeMetadataResult
Contains information about the organization that is useful for developers working with declarative metadata.
The describeMetadata() call returns a DescribeMetadataResult object.
Each DescribeMetadataResult object has the following properties:
Name

Type

Description

metadataObjects

DescribeMetadataObject[] One or more metadata components and their attributes.

organizationNamespace string

The namespace of the organization. Specify only for Developer Edition
organizations that can contain a managed package. The managed package has
a namespace specified when it is created.

partialSaveAllowed boolean

Indicates whether rollbackOnError is allowed (true) or not (false).
This value is always :
• false in production organizations.
• the opposite of testRequired.

testRequired

boolean

Indicates whether tests are required (true) or not (false).
This value is always the opposite of partialSaveAllowed.

DescribeMetadataObject
This object is returned as part of the DescribeMetadataResult. Each DescribeMetadataObject has the following properties:

Result Objects

Name

DescribeValueTypeResult

Type

Description

childXmlNames string[]

List of child sub-components for this component.

directoryName string

The name of the directory in the .zip file that contains this component.

inFolder

boolean

Indicates whether the component is in a folder (true) or not (false). For example,
documents, email templates and reports are stored in folders.

metaFile

boolean

Indicates whether the component requires an accompanying metadata file. For example,
documents, classes, and s-controls are components that require an additional metadata
file.

suffix

string

The file suffix for this component.

xmlName

string

The name of the root element in the metadata file for this component. This name also
appears in the Packages > types > name field in the manifest file package.xml.

DescribeValueTypeResult
Contains information about a value type that is useful for developers working with declarative metadata.
The describeValueType() call returns a DescribeValueTypeResult object.
Each DescribeValueTypeResult object has the following properties.
Name

Type

Description

apiCreatable

boolean

Indicates whether this value type can be created through the createMetadata()
call (true) or not (false).
This field is available in API version 36.0 and later.

apiDeletable

boolean

Indicates whether this value type can be created through the deleteMetadata()
call (true) or not (false).
This field is available in API version 36.0 and later.

apiReadable

boolean

Indicates whether this value type can be created through the readMetadata()
call (true) or not (false).
This field is available in API version 36.0 and later.

apiUpdatable

boolean

Indicates whether this value type can be created through the updateMetadata()
call (true) or not (false).
This field is available in API version 36.0 and later.

parentField

ValueTypeField

Information about the parent of this value type. Parent field information is useful
for metadata types that are specified with the parent in their name, such as
custom fields, email templates, workflow rules, and reports. For example, the
full name of a custom field includes the sObject that contains it (for example,
Account.field1__c). Similarly, the full name of an email template includes

Result Objects

Name

ReadResult

Type

Description
the folder where the template is stored (for example,
MyFolder/EmailTemplate1).
If the value type has no parent, this field is null.
This field is available in API version 36.0 and later.

valueTypeFields

ValueTypeField[]

One or more metadata components and their attributes.

ValueTypeField
This object is returned as part of the DescribeValueTypeResult and represents the metadata for one field. Each ValueTypeField has the
following properties.
Name

Type

Description

fields

ValueTypeField

The ValueTypeField object for the next field, if any.

foreignKeyDomain string

isForeignKey

boolean

If isForeignKey is True, foreignKeyDomain is the type
of object, such as Account or Opportunity.
True if the field is a foreign key. That means this field is the primary

key in a different database table.
isNameField

boolean

True if this value type field is a fullName field, otherwise False.

minOccurs

int

1 if this field is required, 0 otherwise.

name

string

The name of this value type field. The name is null for parent fields.

picklistValues

PicklistEntry

The individual picklist values if the field is a picklist.

soapType

string

The data type of the field, such as boolean or double.

valueRequired

boolean

Required. Indicates whether this value type field must have a value
(true) or can be null (false).

ReadResult
Contains result information for the readMetadata call.

Version
Available in API version 30.0 and later.

100

Result Objects

RetrieveResult

Properties
Name

Type

Description

records

Metadata[]

An array of metadata components returned from readMetadata().

RetrieveResult
Contains information about the success or failure of the associated retrieve() call.
The metadata retrieve() call returns a RetrieveResult object.
Each RetrieveResult object has the following fields:
Name

Type

Description

done

boolean

Required. Indicates whether the retrieve() call is completed (true) or not (false).
This field is available in API version 31.0 and later.

errorMessage

string

If an error occurs during the retrieve() call, this field contains a descriptive message
about this error. This field is available in API version 31.0 and later.

errorStatusCode StatusCode

If an error occurs during the retrieve() call, this field contains the status code for
this error. This field is available in API version 31.0 and later.
For a description of each StatusCode value, see “StatusCode” in the SOAP API Developer's
Guide.

fileProperties FileProperties[]

Contains information about the properties of each component in the .zip file, and the
manifest file package.xml. One object per component is returned.

ID of the component being retrieved.

messages

RetrieveMessage[]

Contains information about the success or failure of the retrieve() call.

status

RetrieveStatus
The status of the retrieve() call. Valid values are:
(enumeration of type • Pending
string)
• InProgress
• Succeeded
• Failed
This field is available in API version 31.0 and later.

success

boolean

Indicates whether the retrieve() call was successful (true) or not (false). This
field is available in API version 31.0 and later.

zipFile

base64Binary

The zip file returned by the retrieve request. Base 64-encoded binary data. Prior to making
an API call, client applications must encode the binary attachment data as base64. Upon
receiving a response, client applications must decode the base64 data to binary. This
conversion is usually handled for you by a SOAP client.

101

Result Objects

RetrieveResult

FileProperties
This component contains information about the properties of each component in the .zip file, and the manifest file package.xml.
One object per component is returned. Note that this component does not contain information about any associated metadata files in
the .zip file, only the component files and manifest file. FileProperties contains the following properties:
Name

Type

Description

createdById

string

Required. ID of the user who created the file.

createdByName

string

Required. Name of the user who created the file.

createdDate

dateTime

Required. Date and time when the file was created.

fileName

string

Required. Name of the file.

fullName

string

Required. The file developer name used as a unique identifier for API access.
The value is based on the fileName but the characters allowed are more
restrictive. The fullName can contain only underscores and alphanumeric
characters. It must be unique, begin with a letter, not include spaces, not end
with an underscore, and not contain two consecutive underscores.

string

Required. ID of the file.

lastModifiedById string

Required. ID of the user who last modified the file.

lastModifiedByName string

Required. Name of the user who last modified the file.

lastModifiedDate dateTime

Required. Date and time that the file was last modified.

manageableState

ManageableState
(enumeration of type
string)

Indicates the manageable state of the specified component if it is contained in
a package:
• beta
• deleted
• deprecated
• installed
• released
• unmanaged
For more information about states of manageability for components in
Force.com AppExchange packages, see “Planning the Release of Managed
Packages” in the Salesforce online help.

namespacePrefix

string

If any, the namespace prefix of the component.

type

string

Required. The metadata type, such as CustomObject, CustomField,
or ApexClass.

RetrieveMessage
RetrieveResult returns this object, which contains information about the success or failure of the retrieve() call. One object per
problem is returned:

102

Result Objects

SaveResult

Name

Type

Description

fileName

string

The name of the file in the retrieved .zip file where a problem occurred.

problem

string

A description of the problem that occurred.

category

PlatformAction
GroupCategory
(enumeration of
type string)

Required. The location of the action link group within the feed element.
Values are:
• Primary—The action link group is displayed in the body of the
feed element.
• Overflow—The action link group is displayed in the overflow
menu of the feed element.

executionsAllowed

ActionLink
Required. The number of times an action link can be executed. Values
ExecutionsAllowed are:
(enumeration of
• Once—An action link can be executed only once across all users.
type string)
• OncePerUser—An action link can be executed only once for
each user.
• Unlimited—An action link can be executed an unlimited number
of times by each user. If the action link’s actionType is Api or
ApiAsync, you can’t use this value.

hoursUntilExpiration

int

Required. The number of hours from when the action link group is
created until it's removed from associated feed elements and can no
longer be executed. The maximum value is 8,760.

isPublished

boolean

Required. If true, the action link group template is published. Action
link group templates shouldn’t be published until at least one action
link template is associated with it.

name

string

Required. The name of the action link group template to use in code.

121

Metadata Types

ActionLinkGroupTemplate

ActionLinkTemplate
ActionLinkTemplate components are used to create multiple action links that share properties.
Field Name

Field Type

Description

actionUrl

string

Required. The action link URL. For example, a Ui action link URL is a Web page.
A Download action link URL is a link to the file to download. Ui and
Download action link URLs are provided to clients. An Api or ApiAsync
action link URL is a REST resource. Api and ApiAsync action link URLs
aren’t provided to clients. Links to Salesforce can be relative. All other links
must be absolute and start with https://.

headers

string

Template for the HTTP headers sent when corresponding action links are
invoked. This field can be used only for Api and ApiAsync action links.
This field can contain context variables and binding variables in the form
{!Bindings.key}.

isConfirmationRequired boolean

Required. If true, a confirmation dialog appears before the action is executed.

isGroupDefault

boolean

Required. If true, action links derived from this template are the default or
primary action in their action groups. There can be only one default action per
action group.

label

string

A custom label to display on the action link button. If none of the LabelKey
values make sense for an action link, use a custom label. Set the LabelKey
field to None and enter a label name in the Label field.

labelKey

string

Required. Key for the set of labels to display for these action link states: new,
pending, success, failed. For example, the Approve set contains these labels:
Approve, Pending, Approved, Failed. For a complete list of keys and labels, see
Action Links Labels in the Chatter REST API Developer Guide or the Apex Developer
Guide.

linkType

ActionLinkType
Required. The type of action link. One of these values:
(enumeration of type • Api—The action link calls a synchronous API at the action URL. Salesforce
string)
sets the status to SuccessfulStatus or FailedStatus based
on the HTTP status code returned by your server.
• ApiAsync—The action link calls an asynchronous API at the action URL.
The action remains in a PendingStatus state until a third party makes
a request to /connect/action-links/actionLinkId to set
the status to SuccessfulStatus or FailedStatus when the
asynchronous operation is complete.
• Download—The action link downloads a file from the action URL.
• Ui—The action link takes the user to a Web page at the action URL.

method

ActionLink
Required. HTTP method for the action URL. One of these values:
HttpMethod
• HttpDelete—Returns HTTP 204 on success. Response body or output
(enumeration of type
class is empty.
string)
• HttpGet—Returns HTTP 200 on success.

122

Metadata Types

Field Name

ActionLinkGroupTemplate

Field Type

Description
• HttpHead—Returns HTTP 200 on success. Response body or output
class is empty.
• HttpPatch—Returns HTTP 200 on success or HTTP 204 if the response
body or output class is empty.
• HttpPost—Returns HTTP 201 on success or HTTP 204 if the response
body or output class is empty. Exceptions are the batch posting resources
and methods, which return HTTP 200 on success.
• HttpPut—Return HTTP 200 on success or HTTP 204 if the response body
or output class is empty.
Ui and Download action links must use HttpGet.

position

int

Required. An integer specifying the position of the action link template relative
to other action links in the group. 0 is the first position.

requestBody

string

Template for the HTTP request body sent when corresponding action links are
invoked. This field can be used only for Api and ApiAsync action links.
This field can contain context variables and binding variables in the form
{!Bindings.key}.

userAlias

string

If you selected CustomUser or CustomExcludedUser for
UserVisibility, this field is the alias for the custom user. Use the alias
in a template binding to specify the custom user when an action link group is
created using the template.

userVisibility

ActionLink
Required. Who can see the action link. This value is set per action link, not per
UserVisibility
action link group. Values are:
(enumeration of type • Creator—Only the creator of the action link can see the action link.
string)
• Everyone—Everyone can see the action link.
• EveryoneButCreator—Everyone but the creator of the action link
can see the action link.
• Manager—Only the manager of the creator of the action link can see
the action link.
• CustomUser—Only the custom user can see the action link.
• CustomExcludedUser—Everyone but the custom user can see the
action link.

Declarative Metadata Sample Definition
The following is an example of an ActionLinkGroupTemplate component.

/services/data/{!Bindings.word}/chatter/feed-elements
Content-Type:{!Bindings.word3}

123

Metadata Types

AnalyticSnapshot

true
true
Add
API
httpPost
0
{"body":{"messageSegments":[{"type": "Text",
"text": "{!Bindings.word1}"}]},"subjectId": "{!Bindings.word2}",
"feedElementType": "feedItem"}
customExcludedUser
CustomExcludedUser

Primary
OncePerUser
10
true
MyPackage

The following is an example package.xml that references the previous definition.

*
ActionLinkGroupTemplate

33.0

Usage
If you modify action link group templates, you overwrite the related action link templates.
If you delete a published action link group template, you delete all related action link information which includes deleting all action links
that were instantiated using the template from feed items.

AnalyticSnapshot
Represents a reporting snapshot. A reporting snapshot lets you report on historical data. Authorized users can save tabular or summary
report results to fields on a custom object, then map those fields to corresponding fields on a target object. They can then schedule
when to run the report to load the custom object's fields with the report's data. Reporting snapshots enable you to work with report
data similarly to how you work with other records in Salesforce.

Declarative Metadata File Suffix and Directory Location
Force.com AnalyticSnapshot components are stored in the analyticSnapshots directory of the corresponding package directory.
The file name matches the unique name of the reporting snapshot, and the extension is .analyticsnapshot.

124

Metadata Types

AnalyticSnapshot

Version
Force.com AnalyticSnapshot components are available in API version 16.0 and later.

Fields
Field

Field Type

Description

description

string

A description of the reporting snapshot.

fullName

string

The reporting snapshot name used for API access. The name
can only contain characters, letters, and the underscore (_)
character, must start with a letter, and cannot end with an
underscore or contain two consecutive underscore characters.
This field is inherited from the Metadata component.

groupColumn

string

A column that specifies which level to extract data from the
source report. It is only applicable for summary reports.

mappings

AnalyticSnapshotMapping[]

A list of reporting snapshot mappings. For valid values, see
AnalyticSnapshotMapping.

name

string

Required. The display name of the reporting snapshot.

runningUser

string

The username of the user whose role and sharing settings are
used to run the reporting snapshot.

sourceReport

string

Required. The report where data will be extracted from.

targetObject

string

Required. The custom object where data will be inserted into.

AnalyticSnapshotMapping
AnalyticSnapshotMapping defines the mapping for the reporting snapshot. Valid values are:
Field

Field Type

Description

aggregateType

ReportSummaryType[]
List that defines if and how each report field is summarized. For valid
(enumeration of type string) values, see ReportSummaryType.

sourceField

string

The sourceField can be one of the following:
• The field on the sourceReport that you want to map to the targetField
in the targetObject
• A summary of a filed on the sourceReport (for Summary reports only)
• A field on the reporting snapshot, such as JobName, RunningUser, or
ExecutionTime (set through the user interface)
Note: The sourceField must correspond to the sourceType you specify.

sourceType

ReportJobSourceTypes[]
List that defines the report format for the reporting snapshot. For valid
(enumeration of type string) values, see ReportJobSourceTypes.

125

Metadata Types

AnalyticSnapshot

Field

Field Type

Description

targetField

string

A field on the targetObject into which this particular sourceField will be
inserted.

ReportJobSourceTypes
An enumeration of type string that defines the report format for the reporting snapshot. Valid values are:
Enumeration Value

Description

snapshot

Use this option if the sourceField contains snapshot-specific information such as JobName,
RunningUser, or ExecutionTime.

summary

Use this option if referencing a summary (Sum, Average, Minimum, Maximum) of a field from
the sourceReport.

tabular

Use this option if referencing an available column from the sourceReport.

Declarative Metadata Sample Definition
A sample XML definition of a reporting snapshot is shown below.

my description
INDUSTRY

Average
SALES
summary
myObject __c.Name

ExecutionTime
snapshot
myObject __c.field3__c

INDUSTRY
tabular
testObject__c.Name

my snapshot
user@salesforce.com
myFolder/mytSummaryReport
myObject__c

category

CommunityTemplate Required. The optimized use case of this CommunityTemplateDefinition.
Category
Valid values are:
(enumeration of
• IT
type string)
• Marketing
• Sales
• Service

defaultThemeDefinition

string

Required. The assigned theme definition for this
CommunityTemplateDefinition.

description

string

The optional description text of this CommunityTemplateDefinition.

enableExtendedCleanupUpOnDelete boolean

Determines if deleting this CommunityTemplateDefinition attempts to
delete other directly or indirectly referenced objects automatically, for
example, CommunityThemeDefinition on page 186, Flexipage on page
365, or StaticResource on page 660.

masterLabel

string

Required. The label for this CommunityTemplateDefinition, which displays
in Setup.

pageSetting

CommunityTemplate Required. The list of FlexiPages of this CommunityTemplateDefinition.
PageSetting [ ]

CommunityTemplateBundleInfo
Field Name

Field Type

Description

description

string

The optional description text of its CommunityTemplateBundleInfo.

image

string

Required only when the type is PreviewImage, otherwise this field is
optional. A preview image for this CommunityTemplateDefinition.

order

int

Required. An integer specifying the position of this
CommunityTemplateBundleInfo relative to others of the same Type within its
CommunityTemplateDefinition. 1 is the first position, 3 is the max position for
PreviewImage type, and 4 is the max position for Highlight type.

title

string

Required. The title of this CommunityTemplateBundleInfo to use in code.

183

Metadata Types

CommunityTemplateDefinition

Field Name

Field Type

Description

type

CommunityTemplate
BundleInfoType
(enumeration of type
string)

Required. Stores descriptive information about the template that is included
in the export (currently limited to Features and Preview Images). The template
powers the UI of the Community Creation Wizard. Valid values are:
• Highlight—This CommunityTemplateBundleInfo is used as a
highlighted feature.
• PreviewImage—This CommunityTemplateBundleInfo is used as a
preview image.

CommunityTemplatePageSetting
Field Name

Field Type

Description

page

string

Required. The list of FlexiPages of this CommunityTemplateDefinition.

themeLayout

string

Required. The name of the FlexiPage for the theme layout.
This field is available in API version 39.0 and later.

Declarative Metadata Sample Definition
The following is an example of a CommunityTemplateDefinition component.

ax
1
ax
Highlight

siteAsset_6b1cf63e4d604d16bb98b84636ab1932
1
siteAsset_6b1cf63e4d604d16bb98b84636ab1932
PreviewImage

Sales
ax
ax
true
ax

ax_Record_List

ax_Topic_Catalog

184

Metadata Types

CommunityTemplateDefinition

ax_User_Settings

ax_Error

ax_Group_Detail

ax_Sfdc_Page

ax_Related_Record_List

ax_User_Profile

ax_Record_Detail

ax_Group_List

ax_Search

ax_Create_Record

ax_Question_Detail

ax_Home

ax_Topic_Detail

ax_Report

ax_Feed_Detail

ax_Contact_Support

The following is an example package.xml that references the previous definition.

MyTemplate

185

Metadata Types

CommunityThemeDefinition

CommunityTemplateDefinition

39.0

CommunityThemeDefinition
Represents the definition of a community theme.This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location
CommunityThemeDefinition components have the suffix .communityThemeDefinition and are stored in the
communityThemeDefinitions folder.

Version
CommunityThemeDefinition components are available in API version 38.0 and later.

Special Access Rules
This object is available only if Salesforce Communities is enabled in your org.

Fields
Field Name

Field Type

Description

customThemeLayoutType

CommunityCustom The list of custom theme layout types available to the theme layout. This
ThemeLayoutType field is available in API version 39.0 and later.
[]

description

string

The optional description text of this CommunityThemeDefinition.

enableExtendedCleanupUp
OnDelete

boolean

Determines if deleting this CommunityThemeDefinition attempts to
delete other directly or indirectly referenced objects automatically, for
example, FlexiPage.

masterLabel

string

Required. The label for this CommunityThemeDefinition, which displays
in Setup.

themeSetting

CommunityTheme Required. The list of settings for this CommunityThemeDefinition.
Setting [ ]

CommunityCustomThemeLayoutType
Field Name

Field Type

Description

description

string

The description of the custom theme layout type.

186

Metadata Types

ConnectedApp

Field Name

Field Type

Description

label

string

Required. The name of the custom theme layout type. The values Inner,
Home, and Login are reserved.

CommunityThemeSetting
Field Name

Field Type

customThemeLayoutType string

Description
Required when themeLayoutType is not specified. The custom theme
layout type associated with the theme layout. This field and themeLayoutType
are mutually exclusive; you can’t specify both. This field is available in API version
39.0 and later.

themeLayout

string

Required. The configuration and layout for this theme.

themeLayoutType

CommunityTheme
LayoutType
(enumeration of type
string)

Required when customThemeLayoutType is not specified. The default
theme layout type associated with the theme layout. Valid values are Inner,
Home, or Login. This field and customThemeLayoutType are mutually
exclusive; you can’t specify both.

Declarative Metadata Sample Definition
The following is an example of a CommunityThemeDefinition component.

true
ax_theme

ax_theme_napili_themeLayout_home
Inner

The following is an example package.xml that references the previous definition.

MyTheme
CommunityThemeDefinition

39.0

ConnectedApp
Represents a connected app configuration. A connected app integrates an application with Salesforce using APIs. Connected apps use
standard SAML and OAuth protocols to authenticate, provide single sign-on, and provide tokens for use with Salesforce APIs. In addition

187

Metadata Types

ConnectedApp

to standard OAuth capabilities, connected apps allow Salesforce admins to set various security policies and have explicit control over
who can use the corresponding apps. This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location
ConnectedApp components have the suffix .connectedapp and are stored in the connectedapps folder.

Version
ConnectedApp components are available in API version 29.0 and later.

Fields
Field Name

Field Type

Description

attributes

ConnectedAppAttribute

A custom attribute of the connected app.

canvasConfig

ConnectedAppCanvasConfig

The configuration options of the connected app if it’s exposed as a
canvas app.

contactEmail

string

The email address Salesforce should use for contacting you or your
support team.

contactPhone

string

The phone number for Salesforce to use in case we need to contact
you.

description

string

An optional description for your application.

iconUrl

string

Reserved for future use.

infoUrl

string

An optional URL for a Web page with more information about your
application.

ipRanges

ConnectedAppIpRange

Specifies the ranges of IP addresses that can access the app without
requiring the user to authenticate with the connected app.

label

string

The name of the app.

logoUrl

string

An optional application logo. The logo appears with the application’s
entry in the list of apps and on the consent page the user sees when
authenticating. The URL must use HTTPS, and the logo can’t be larger
than 125 pixels high or 200 pixels wide. The default logo is a cloud.

mobileStartUrl

string

Users are directed to this URL after they’ve authenticated when the
app is accessed from a mobile device. If you don’t give a URL, the user
is sent to the application’s default start page after authentication
completes. If the connected app that you’re creating is a canvas app,
then you don’t need to enter a value for this field. The Canvas App
URL field contains the URL that gets called for the connected app.

oauthConfig

ConnectedAppOauthConfig

Specifies how your application communicates with Salesforce.

188

Metadata Types

ConnectedApp

Field Name

Field Type

Description

plugin

string

The name of a custom Apex class that extends
Auth.ConnectedAppPlugin to customize the behavior of the
app.

samlConfig

ConnectedAppSamlConfig

Controls how the app uses single sign-on.

startUrl

string

If the app is not accessed from a mobile device, users are directed to
this URL after they’ve authenticated. If you don’t give a URL, the user
is sent to the application’s default start page after authentication
completes. If the app is accessed from a mobile device, see
mobileStartUrl. If the connected app that you’re creating is a
canvas app, then you don’t need to enter a value for this field. The
Canvas App URL field contains the URL that gets called for the
connected app.

ConnectedAppAttribute
Represents the field names that make up a custom attribute when using SAML with a ConnectedApp. These values should be tailored
to a specific service provider.
Field Name

Field Type

Description

formula

string

The value of the attribute.

key

string

The attribute’s identifier.

ConnectedAppCanvasConfig
The configuration options of the connected app if it’s exposed as a canvas app.
Field Name

Field Type

Description

accessMethod

AccessMethod (enumeration of
type string)

Indicates how the canvas app initiates the OAuth authentication flow.
The valid values are:
• Get—OAuth authentication is used, and the user is prompted to
allow the third-party application to access their information. When
you use this access method, the canvas app must initiate the OAuth
authentication flow.
• Post—OAuth authentication is used, but when the administrator
installs the canvas app, they implicitly allow access for users.
Therefore, the user won’t be prompted to allow the third-party to
access their user information. When you use this access method,
the authentication is posted directly to the canvas app URL.

canvasUrl

string

The URL of the third-party app that’s exposed as a canvas app.

189

Metadata Types

ConnectedApp

Field Name

Field Type

Description

lifecycleClass

string

The name of the Canvas.CanvasLifecycleHandler Apex
class, if you’ve implemented this class for custom parameters.
This field is available in API version 31.0 and later.

locations

CanvasLocationOptions
(enumeration of type string)

Indicates where the canvas app can appear to the user. The valid values
are:
• Aura—Reserved for future use.
• AppLauncher—Reserved for future use.
• Chatter—The canvas app can appear in the app navigation
list on the Chatter tab.
• ChatterFeed—The canvas app can appear as a Chatter feed
item.
• MobileNav—The canvas app can appear in a mobile card in
the Salesforce1 app. This value is available in API version 31.0 and
later.
• None—The canvas app can appear only in the Canvas App
Previewer.
• OpenCTI—The canvas app can appear in the call control tool.
• PageLayout—The canvas app can appear on a page layout.
When viewed in the Salesforce1 app, the canvas app appears in
the record detail page. This value is available in API version 31.0
and later.
• Publisher—The canvas app can appear as a global action.
• ServiceDesk—The canvas app can appear in the footer or
sidebars of a Salesforce console.
• UserProfile—Reserved for future use.
• Visualforce—The canvas app can appear on a Visualforce
page.

options

CanvasOptions (enumeration of
type string)

Indicates whether you want to hide the share button and header in
the publisher for your canvas app, and whether the app is a canvas
personal app. Valid values are:
• HideShare—The Share button is hidden in the publisher for
the related canvas app.
Available in API version 30.0 and later.
• HideHeader—The header is hidden in the publisher for the
related canvas app.
Available in API version 30.0 and later.
• PersonalEnabled—The app can be installed by end users
as a canvas personal app.
Available in API version 32.0 and later.

190

Metadata Types

Field Name

ConnectedApp

Field Type

samlInitiationMethod SamlInitiationMethod

(enumeration of type string)

Description
If you’re using SAML single sign-on (SSO), indicates which provider
initiates the SSO flow.
• IdpInitiated—Identity provider initiated. Salesforce makes
the initial request to start the SSO flow.
• SpInitiated—Service provider initiated. The canvas app starts
the SSO flow after it’s invoked.
• None—The canvas app isn’t using SAML SSO.
This field is available in API version 31.0 and later.

ConnectedAppIpRange
The list of IP addresses that can access the app without requiring the user to authenticate.
Field Name

Field Type

Description

description

string

Use this field to identify the purpose of the range, such as which part
of a network corresponds to this range. This field is available in API
version 31.0 and later.

startAddress

string

The first address in the IP range, inclusive.

endAddress

string

The last address in the IP range, inclusive.

ConnectedAppOauthConfig
Represents the field names that make up a custom attribute in a ConnectedApp.
Field Name

Field Type

Description

callbackUrl

string

The endpoint that Salesforce calls back to your application during
OAuth; it’s the OAuth redirect_uri.

certificate

string

The PEM-encoded certificate string, if the app uses a certificate.

consumerKey

string

A value used by the consumer for identification to Salesforce. Referred
to as client_id in OAuth 2.0.
In API version 32.0 and later, this field write-enabled. Once set, the value
cannot be edited. The value must be alphanumeric (no special
characters and no spaces) and a minimum of eight characters
(maximum of 256 characters). If you specify a key already in use for
another connected app in the organization, you’ll get an error.

consumerSecret

string

A value that is combined with the consumerKey and used by the
consumer for identification to Salesforce. Referred to as
client_secret in OAuth 2.0. Typically, this value is generated by
Salesforce when you create the connected app. However, the field is

191

Metadata Types

Field Name

ConnectedApp

Field Type

Description
write-enabled so you can customize the shared secret value. Once set,
the value is not returned in metadata API requests.
The value must be alphanumeric (no special characters and no spaces)
and a minimum of eight characters (maximum of 256 characters). If
you specify a secret already in use for another connected app in the
organization, you’ll get an error.
This field is available in API version 32.0 and later.

scopes

ConnectedAppOauthAccessScope The scopes refer to permissions given by the user running the
(enumeration of type string)
connected app. When deploying metadata, valid values are:
• Address—Allows access to the logged-in user’s street address
(the same behavior as deploying Basic).
• Api—Allows access to the logged-in user’s account over the APIs.
• Basic—Allows access to your identity URL service (the same
behavior as deploying Address, Email, Phone, and
Profile).
• Chatter—Allows access to only the Chatter REST API resources.
• CustomApplications—Provides access to custom
applications, such as those using Visualforce.
• CustomPermissions—Allows access to the custom
permissions in an organization associated with the connected app,
and shows whether the current user has each permission enabled.
• Email—Allows access to the logged-in user’s email address (the
same behavior as deploying Basic).
• Full—Allows access to all data accessible by the logged-in user.
• OfflineAccess—Allows the app to interact with the user’s
data while the user is offline, and get a refresh token (the same
behavior as deploying RefreshToken).
• OpenID—Allows access to the logged-in user’s unique identifier
for OpenID Connect apps.
• Phone—Allows access to the logged-in user’s phone number
value (the same behavior as deploying Basic).
• Profile—Allows access to the logged-in user’s profile (the
same behavior as deploying Basic).
• RefreshToken—Allows a refresh token to be returned if you’re
eligible to receive one (the same behavior as deploying
OfflineAccess).
• Wave—Allows access to the Wave REST API resources. Available
in API version 35.0 and later.
• Web—Allows the ability to use the access_token on the
Web. This also includes visualforce, allowing access to
Visualforce pages.

192

Metadata Types

Field Name

ConnectedApp

Field Type

Description
When retrieving metadata, valid values are:
• Api—Allows access to the logged-in user’s account over the APIs.
• Basic—Allows access to the user’s identity URL service, and
includes Address, Email, Phone, and Profile.
• Chatter—Allows access to only the Chatter REST API resources.
• CustomApplications—Allows access to custom
applications, such as those using Visualforce.
• Full—Allows access to all data accessible by the logged-in user.
• OpenID—Allows access to the logged in user’s unique identifier
for OpenID Connect apps.
• RefreshToken—Allows a refresh token to be returned if you
are eligible to receive one, and is synonymous with allowing
OfflineAccess.
• Wave—Allows access to the Wave REST API resources. Available
in API version 35.0 and later.
• Web—Allows the ability to use the access_token on the
Web. This also includes visualforce, allowing access to
Visualforce pages.

ConnectedAppSamlConfig
Specifies how an app uses single sign-on.
Field Name

Field Type

Description

acsUrl

string

The assertion consumer service URL from the service provider.

certificate

string

The PEM-encoded certificate string, if the app uses a certificate.

entityUrl

string

The entity ID from your service provider.

encryptionCertificate string

Note: This page is about Classic Encryption, not Shield Platform
Encryption. What's the difference?
The name of the certificate to use for encrypting SAML assertions to
the service provider. This certificate is saved in the organization’s
Certificate and Key Management list. Available in API version 30.0 and
later .

encryptionType

SamlEncryptionType

Note: This page is about Classic Encryption, not Shield Platform
Encryption. What's the difference?

(enumeration of type string)

When Salesforce is the identity provider, the SAML configuration can
specify the encryption method used for encrypting SAML assertions
to the service provider. The service provider detects the encryption
method in the SAML assertion for decryption. Valid values are:

193

Metadata Types

Field Name

ConnectedApp

Field Type

Description
• AES_128—128–bit key.
• AES_256—256–bit key.
• Triple_Des—Triple Data Encryption Algorithm.
Available in API version 30.0 and later.

issuer

string

samlNameIdFormat SamlNameIdFormatType

(enumeration of type string)

A URI that sends the SAML response. It can be used by the service
provider to determine which identity provider sent the response.
Available in API version 29.0 and later.
Indicates the format the service provider (SP) requires for the user’s
single sign-on identifier. Available in API version 29.0 and later. Valid
values are:
• Unspecified—No format given. This is the default.
• EmailAddress—Used if the subject type is the user’s name
ora federation ID (an ID internal to the SP).
• Persistent—Used with the user ID and persistent ID subject
types.
• Transient—Used when the subject type is a custom attribute
and can change every time the user logs in.

samlSubjectCustomAttr string

samlSubjectType

If the samlSubjectType is CustomAttr, include that custom
value here; otherwise, leave empty. Available in API version 29.0 and
later.

SamlSubjectType (enumeration of The single sign-on identifier for the user. Valid values are:
type string)
• Username—The user’s Salesforce name.
• FederationId—The user’s identifier at the service provider.
Get this value from the service provider.
• UserId—The user’s Salesforce identifier.
• PersistentID—A persistent opaque identifier that is specific
to the identity provider and a service provider.
• CustomAttr—The identifier is taken from a custom field value
in samlSubjectCustomAttr.

Declarative Metadata Sample Definition
The following is an example package manifest used to deploy or retrieve the ConnectedApp metadata for an organization.

PortalTestApp
ConnectedApp

194

Metadata Types

ConnectedApp

29.0

The following is an example of a ConnectedApp component.

AConnectedApp

$User.CompanyName
companyName

joe@company.com
https://m.connectedapp.company.com
A ConnectedApp

https://callback.company.com
Basic
Chatter

http://acs.company.com
http://samlentityId.company.com
Username

https://connectedapp.company.com

10.0.0.46
10.0.0.42

10.0.0.32
10.0.0.25

Usage
If you're constructing a SAML-enabled connected app using Metadata API, and need to set the IdP-Initiated Login URL for
your service provider, you have two options:
You can use the service provider app ID with the app parameter in the following format. This value is displayed in the Salesforce user
interface. From Setup, enter “Connected Apps” in the Quick Find box, then select Connected Apps, then click the name of the
connected app to see its detail page.
https:///idp/login?app=

Or, if you’re configuring the connected app using Metadata API only, you can use the apiName parameter of the service provider app
in the following format. The apiName parameter is the fullName inherited from the Metadata type.
https:///idp/login?apiName=

195

Metadata Types

ContentAsset

ContentAsset
Represents the metadata for creating an asset file. Asset files enable a Salesforce file to be used for org setup and configuration purposes.
This type extends the MetadataWithContent metadata type and inherits its content and fullName fields.

File Suffix and Directory Location
ContentAsset components have the suffix .asset and are stored in the contentassets folder.

Version
ContentAsset components are available in API version 38.0 and later.

Special Access Rules
The system prevents metadata retrieval if the total size of the asset’s file content exceeds 30 MB. All pre-existing limits for packaging
apply to asset files.

Fields
Field Name

Field Type

Description

format

ContentAssetFormat Describes the format of the asset file. Valid values are:
(enumeration of
• Original—A single asset file version.
type string)
• ZippedVersions—Contains multiple versions of the asset file.

language

string

Required. The language of the asset file label.

masterLabel

string

Required. The label for the asset file record, which displays in Setup.

originNetwork

string

For deploys, the name of the community the file is assigned upon
creation. For retrievals, the name of the community the file is assigned
to populates the field value. If null, file was not assigned to a
community.

relationships

ContentAsset
Relationships[]

The list of ContentAssetLinks that describe whether the asset file should
be shared with the org.

versions

ContentAssetVersions Required. Captures basic information about the file version(s) included
the asset metadata. Typically the file has only one version.

ContentAssetRelationships
Represents the relationships between an asset file and the locations it's linked with.

196

Metadata Types

ContentAsset

Field Name

Field Type

Description

organization

ContentAssetLink[]

Carries information about sharing the asset file with the org. Maps to
ContentDocumentLink.

ContentAssetLink
Represents a relationship link for an asset file, and includes details about the level of access for the link.
Field Name

Field Type

Description

access

ContentAssetAccess Required. The permission granted to the user of the shared file, determined by
(enumeration of type the permission the user already has. Valid values are:
string)
• VIEWER
• COLLABORATOR
• INFERRED

name

string

Reserved for future use.

ContentAssetVersions
Represents information about all file versions included in the asset metadata.
Field Name

Field Type

Description

version

ContentAssetVersion[] A list of file versions for the asset.

ContentAssetVersion
Represents information about one file version included in the asset metadata.
Field Name

Field Type

Description

number

string

Required. The version number. This field is based on, or sets, the ContentVersion.

pathOnClient

string

Required. Describes the original filename of the file. This field maps to
ContentVersion.PathOnClient. It provides the data for the ContentVersion Title
field.

zipEntry

string

If the asset file has more than one version, format is ZippedVersions.
In this case, zipEntry is the name of the file within the zip. If the asset file
has only one version, this field is empty.

197

Metadata Types

CorsWhitelistOrigin

Declarative Metadata Sample Definition
The following is an example of a ContentAsset component.

some asset

VIEWER

1
some asset.txt

For assets that include just one version, the format field can be omitted or specified with the value as Original. File assets with more
than one version have versions wrapped in a zip file.
The following is an example package.xml that references the previous definition.

MyAsset
ContentAsset

39.0

CorsWhitelistOrigin
Represents an origin in the CORS whitelist.

File Suffix and Directory Location
CorsWhitelistOrigin components have the suffix .corswhitelistorigin and are stored in the corswhitelistorigins
folder.

Version
CorsWhitelistOrigin components are available in API version 32.0 and later.

198

Metadata Types

CorsWhitelistOrigin

Fields
Field Name

Field Type

Description

developerName

String

A unique name for the entry.

urlPattern

String

A URL pattern for the origin.
The origin URL pattern must include the HTTPS protocol and a domain
name, and may include a port. The wildcard character (*) is supported
and must be in front of a second-level domain name. For example,
https://*.example.com adds all subdomains of
example.com to the whitelist.
The origin URL pattern can be an IP address. However, an IP address
and a domain that resolve to the same address are not the same origin
and you must add them to the CORS whitelist as separate entries.

Declarative Metadata Sample Definition
The following is an example package manifest used to deploy or retrieve the CorsWhitelistOrigin metadata for an organization.

*
CorsWhitelistOrigin

32.0

The following is an example of a CorsWhitelistOrigin component.

CorsWhitelistEntry1
https://*.example.com

Usage
CORS (cross-origin resource sharing) is a W3C recommendation that enables Web browsers to request resources from origins other than
their own. For example, using CORS, a JavaScript script at https://www.example.com could request a resource from
https://www.salesforce.com.
If a browser that supports CORS makes a request to an origin in the Salesforce CORS whitelist, Salesforce returns the origin in the
Access-Control-Allow-Origin HTTP header, along with any additional CORS HTTP headers. If the origin is not whitelisted,
Salesforce returns HTTP status code 404.

199

Metadata Types

CspTrustedSite

CspTrustedSite
Represents a CSP Trusted Site. The Lightning Component framework uses Content Security Policy (CSP) to control the source of content
that can be loaded on a page. To use third-party APIs that make requests to an external (non-Salesforce) server, add the server as a CSP
Trusted Site.

Declarative Metadata File Suffix and Directory Location
CspTrustedSite components are stored in the cspTrustedSites directory of the corresponding package directory. The file name
matches the unique name of the trusted site, and the extension is .cspTrustedSite.

Version
CspTrustedSite components are available in API version 39.0 and later.

Fields
Field

Field Type

Description

description

string

The description explaining what this trusted site is used for.

endpointUrl

string

Required. The URL for the trusted site.

isActive

boolean

Required. Indicates if the trusted site is active (true) or not
(false).

Declarative Metadata Sample Definition
A sample XML definition of a trusted site is shown below.

Used for Lightning component callout to mapping web service
https://www.maptestsite.net/
true

Usage
CSP is a Candidate Recommendation of the W3C working group on Web Application Security. The framework uses the ContentSecurity-Policy HTTP header recommended by the W3C. By default, the framework’s headers allow content to be loaded only
from secure (HTTPS) URLs and forbid XHR requests from JavaScript.
When you define a CSP Trusted Site, the site’s URL is added to the list of allowed sites for the following directives in the CSP header.
• connect-src
• frame-src
• img-src

200

Metadata Types

CustomApplication

• style-src
• font-src
• media-src
This change to the CSP header directives allows Lightning components to load resources, such as images, styles, and fonts, from the
site. It also allows client-side code to make requests to the site.
Important: You can’t load JavaScript resources from a third-party site, even a CSP Trusted Site. To use a JavaScript library from a
third-party site, add it to a static resource, and then add the static resource to your component. After the library is loaded from the
static resource, you can use it as normal.

CustomApplication
CustomApplication represents a custom or standard application. In API version 29.0 and earlier, CustomApplication represents only a
custom application. An application is a list of tab references, with a description and a logo. This type extends the Metadata metadata
type and inherits its fullName field.

File Suffix and Directory Location
Custom and standard applications have the suffix .app and are stored in the applications folder.
Note: Retrieving a component of this metadata type in a project makes the component appear in any Profile and PermissionSet
components that are retrieved in the same package.

Version
Custom applications are available in API version 10.0 and later. Standard applications are available in API version 30.0 and later.

Fields
Field Name

Field Type

Description

actionOverrides

AppActionOverride[]

Represents an action override for an application. Use it
to create, update, edit, or delete action overrides.
This field is available for Lightning Experience in API
version 38.0 and later.

brand

AppBrand

The color scheme and logo used for the app.
This field is available for Lightning Experience in API
version 38.0 and later.

customApplicationComponents CustomApplicationComponents

Represents custom console components (Visualforce
pages) assigned to a Salesforce console app.

defaultLandingTab

string

The fullName of a standard tab or custom tab that
opens when this application is selected.

description

string

The optional description text of the application.

201

Metadata Types

Field Name

CustomApplication

Field Type

Description

detailPageRefreshMethod string

Determines how detail pages refresh in a Salesforce
console app. Required if
isServiceCloudConsole is true. The valid
values are:
• none
• autoRefresh
• flag
This field is available in API version 25.0 and later.

domainWhitelist

DomainWhitelist

Any external domains that users can access from within
a Salesforce console app. For example,
www.yourdomain.com. This field is available in API
version 25.0 and later.

enableCustomizeMyTabs

boolean

Indicates if a Salesforce console app has Customize My
Tabs enabled. If enabled, users can hide, display, and
organize items in the navigation tab.
This field is available in API version 34.0 and later.

enableKeyboardShortcuts boolean

Indicates if a Salesforce console app has keyboard
shortcuts enabled. Shortcuts let users perform actions
by pressing a combination of keys instead of having to
use a mouse. After keyboard shortcuts are enabled,
several default shortcuts are available for customization.
Before you can create custom shortcuts, a developer
must define the shortcut’s action with the
addEventListener() method in the Salesforce
Console Integration Toolkit. You can’t create keyboard
shortcuts for actions performed outside of the console.
This field is required if isServiceCloudConsole
is true.
This field is available in API version 28.0 and later.

enableListViewHover

boolean

Indicates if a Salesforce console app has list view hovers
enabled. If set to true, summary information is
displayed about a record in a responsive list when the
user hovers over a record name. For cases, hover over
the subject field.
This field is available in API version 38.0 and later.

enableListViewReskin

boolean

Indicates if Salesforce console apps use responsive list
views instead of Salesforce Classic lists views.
This field is available in API version 38.0 and later.

enableMultiMonitorComponents boolean

Indicates if a Salesforce console app has multi-monitor
components enabled, which lets users move portions of

202

Metadata Types

Field Name

CustomApplication

Field Type

Description
a console from their browsers to locations on their
screens. This field is required if
isServiceCloudConsole is true.
This field is available in API version 30.0 and later.

enablePinTabs

boolean

Indicates if a Salesforce console app has pinned tabs
enabled, which lets users pin primary tabs to the tab bar
for quick access.
This field is available in API version 34.0 and later.

enableTabHover

boolean

Indicates if a Salesforce console app has tab hover
enabled. If enabled, summary information is displayed
about a record in an overlay when the user hovers over
a tab.
This field is available in API version 36.0 and later.

enableTabLimits

boolean

Indicates whether limits are enabled on the number of
primary tabs and subtabs that can be opened in a
Salesforce console session. When true, values for
tabLimitConfig are required
This field is available in API version 36.0 and later.

footerColor

string

Determines the footer color in a Salesforce console app.
Specify the color with a hexadecimal code, such as
#0000FF for blue.

formFactors

string

Indicates the form factors for which the app is visible for
Lightning Experience. Valid values are:
• Null (no value)—For a desktop using a Salesforce
Classic app
• Large—For a desktop using Lightning Experience
This field is available in API version 38.0 and later.
Note: As of version 38.0, formFactors is set
to Large for existing Salesforce Classic apps,
except for Salesforce Classic consoles. Salesforce
Classic apps installed from packages created
before version 38.0 also have formFactors
set to Large. For Salesforce Classic apps in
packages created with 38.0 or later, you must set
formFactors to Large for Salesforce Classic
apps to appear in the Lightning Experience
desktop.

203

Metadata Types

CustomApplication

Field Name

Field Type

Description

headerColor

string

Determines the header color in a Salesforce console app.
Specify the color with a hexadecimal code, such as
#0000FF for blue.

isServiceCloudConsole

boolean

Indicates if the application is a Salesforce console app.
For more information, see “Salesforce Console” in the
Salesforce online help.

keyboardShortcuts

KeyboardShortcuts

Represents the keyboard shortcuts for a Salesforce
console app. Keyboard shortcuts let users perform actions
by pressing a combination of keys instead of having to
use a mouse.
This field is available in API version 28.0 and later.

label

string

The name of the application.

listPlacement

ListPlacement

Represents how lists display in a Salesforce console app.
Required if isServiceCloudConsole is true.

listRefreshMethod

string

Determines how lists refresh in a Salesforce console app.
Required if isServiceCloudConsole is true.
The valid values are:
• none
• refreshList
• refreshListRows
This field is available in API version 25.0 and later.

liveAgentConfig

LiveAgentConfig

Represents the configurations for using Live Agent in the
Salesforce Console.

logo

string

The optional reference to the image document for a
Salesforce app or Salesforce console.

navType

string

Not updateable. Indicates the type of navigation the app
uses. The value Standard is for Lightning Experience. A
null value means Salesforce Classic.
This field is available in API version 38.0 and later.

primaryTabColor

string

Determines the primary tab color in a Salesforce console
app. Specify the color with a hexadecimal code, such as
#0000FF for blue.

profileActionOverrides

AppProfileActionOverride[]

A list of the Lightning Experience record page
ProfileActionOverrides that are assigned to this custom
app. When a user invokes the custom app, a matching
ProfileActionOverride assignment takes precedence over
existing overrides for the record page specified in
ActionOverride. This lets you override a record page for
the custom app by record type and profile.

204

Metadata Types

CustomApplication

Field Name

Field Type

Description

pushNotifications

PushNotifications

Represents push notifications for a Salesforce console
app. Push notifications are visual indicators on lists and
detail pages that show when a record or field has
changed during a user’s session. For example, assume
that two support agents are working on the same case.
If one agent changes the Priority, a push notification
displays to the other agent so the agent notices the
change and doesn’t duplicate the effort.
This field is available in API version 28.0 and later.

saveUserSessions

boolean

Indicates if a Salesforce console app saves user sessions
automatically. If enabled, when console users close their
browsers or log out of Salesforce, any previously open
tabs display when users log in again. Required if
isServiceCloudConsole is true.
This field is available in API version 28.0 and later.

tab

string

The list of tabs included in this application. In API version
12.0, the fullName for built-in tabs like Home,
Account, and Reports, is the name of the tab (Home, for
example). In API version 13.0 and later, built-in tabs are
prefixed with standard-. For example, to reference
the Account tab you would use standard-Account.

tabLimitConfig

TabLimitConfig

Represents the maximum number of primary tabs and
subtabs allowed in one Salesforce console session.
Required if enableTabLimits is true.
This field is available in API version 36.0 and later.

uiType

string

Not updateable. Identifies the type of custom app. The
value is:
• Aloha for Salesforce Classic
• Lightning for Lightning Experience
This field is available in API version 38.0 and later.

utilityBar

string

The developer name of the UtilityBar associated with this
app.
Note: We recommend assigning a UtilityBar to
only one Lightning App, because UtilityBars are
shared. Sharing means that if you change the
UtilityBar in one app, it automatically changes in
all apps it’s part of.
This field is available in API version 38.0 and later.

205

Metadata Types

CustomApplication

Field Name

Field Type

Description

workspaceMappings

WorkspaceMappings

Represents how records open in a Salesforce console
app. Required if isServiceCloudConsole is
true. This field is available in API version 25.0 and later.

AppActionOverride
Represents an action override for an application. Use it to create, update, edit, or delete action overrides. AppActionOverride inherits
from ActionOverride and extends it by one field, pageOrSobjectType. Available for Lightning Experience in API version 38.0 and
later.
Field Name

Field Type

Description

actionName

string

The only valid value is view.

comment

string

Any comments you want associated with the override.

content

string

Set this field if type is set to flexipage. It refers to the name of the
page to use as the override. To reference installed components, use the
format of Component_namespace__Component_name.

formFactor

FormFactor
(enumeration of type
string)

The size of the page being overridden. Only the Large value is
supported. The other values, Small and Medium, are reserved for
future use.
If the type field is set to flexipage, set this field to Large to
override the View action with a Lightning Page in Lightning Experience.
The Large value represents the Lightning Experience desktop
environment, and is only valid for the flexipage type. For the
scontrol and visualforce types, this field defaults to null.
This field is available in API version 37.0 and later, and is part of the feature
for creating and editing record pages in Lightning Experience.

pageOrSobjectType

string

The name of the sObject type being overridden. Valid values are
standard and custom.

skipRecordTypeSelect

boolean

type

ActionOverrideType
(enumeration of type
string)

Required. Represents the type of action override. The valid values are
Flexipage and Default.

AppBrand
The color scheme and logo used for the app. Available for Lightning apps in API version 38.0 and later.

206

Metadata Types

CustomApplication

Field Name

Field Type

Description

footerColor

string

Optional. Determines the footer color in the app. Specify the color with
a hexadecimal code, such as #0000FF for blue.

headerColor

string

Optional. Determines the header color in the app. Specify the color with
a hexadecimal code, such as #0000FF for blue.

logo

string

The optional reference to the image document for the application.

logoVersion

int

An optional version number for the logo.

AppProfileActionOverride
Represents a ProfileActionOverride for a custom app. This type inherits from ProfileActionOverride on page 509 and extends it by one
field, profile. Available for Lightning Experience in API version 39.0 and later.
Field Name

Field Type

Description

actionName

string

The name of the action. The only valid values are Tab.and View.
If pageOrSobjectType is record-home, this field must be
View. The View action is supported only when ProfileActionOverride
is being specified as part of a CustomApplication.

content

string

Read-only. Represents the name of the Lightning Page being used as
the override.

formFactor

FormFactor
(enumeration of type
string)

pageOrSobjectType

string

The name of the page being overridden. The only valid values are
record-home and standard-home.

profile

string

The profile associated with the ProfileActionOverride.

recordType

string

The record type associated with the override. If pageOrSobjectType
is standard-home, this field must be null. This field is required
when actionName is set to View.

type

ActionOverrideType
(enumeration of type
string)

Read-only. The type of action override. The only valid value is
flexipage.

CustomApplicationComponents
Represents custom console components (Visualforce pages) assigned to a Salesforce console app. Available in API version 25.0 and later.

207

Metadata Types

CustomApplication

Field Name

Field Type

Description

alignment

string

Determines how custom console components are aligned in the footer
of a Salesforce console app.

customApplicationComponent string

The name of a custom console component assigned to a Salesforce
console app.

CustomShortcut
Represents custom keyboard shortcuts assigned to a Salesforce console app. Before you can create custom shortcuts, a developer must
define the shortcut’s action with the addEventListener() method in the Salesforce Console Integration Toolkit. You can’t create
keyboard shortcuts for actions performed outside of the console. Available in API version 28.0 and later.
Field Name

Field Type

Description

action

string

Required. The action performed in the console when a user presses the
keyboard shortcut.

active

boolean

Required. Indicates whether the keyboard shortcut is active (true) or
not (false).

keyCommand

string

Required. The combination of keys a user presses to trigger the keyboard
shortcut. Keyboard shortcuts aren’t case-sensitive, but they display as
uppercase on setup pages in the Salesforce user interface so that they’re
easier to read.
Each key command can include up to four modifier keys followed by one
non-modifier key. Modifier and non-modifier keys are separated by the
+ key. Modifier keys can occur in any order, but you must place
non-modifier keys at the end of the key command sequence. For example,
SHIFT+CTRL+ALT+META +A.
Valid modifier keys are:
• SHIFT
• CTRL
• ALT
• META (represents the COMMAND key on Macs)
Valid non-modifier keys are letters A through Z and numbers 0 through
9. Other valid keys are:
• TAB
• ENTER
• PAUSE/BREAK
• CAPS LOCK
• ESC
• SPACE
• PAGE UP
• PAGE DOWN

208

Metadata Types

Field Name

CustomApplication

Field Type

Description
• END
• HOME
• LEFT ARROW
• UP ARROW
• RIGHT ARROW
• DOWN ARROW
• PRINT SCREEN
• INSERT
• DELETE
• RIGHT WINDOW
• NUMPAD 0
• NUMPAD 1
• NUMPAD 2
• NUMPAD 3
• NUMPAD 4
• NUMPAD 5
• NUMPAD 6
• NUMPAD 7
• NUMPAD 8
• NUMPAD 9
• MULTIPLY
• ADD
• SUBTRACT
• DECIMAL POINT
• DIVIDE
• F1
• F2
• F3
• F4
• F5
• F6
• F7
• F8
• F9
• F10
• F11
• F12
• NUM LOCK

209

Metadata Types

Field Name

CustomApplication

Field Type

Description
• SCROLL LOCK
• ;
• =
• ,
• —
• .
• /
• ‘
• [
• ]
• \
• '

description

string

The optional description text for the keyboard shortcut.

eventName

string

Required. Code available to developers who want to add custom shortcut
functions to the console via the Salesforce Console Integration Toolkit.

DefaultShortcut
Represents default keyboard shortcuts assigned to a Salesforce console app. Once you enable keyboard shortcuts for a console, several
default shortcuts are available for customization. These include opening and closing tabs, moving between tabs, and saving records.
Available in API version 28.0 and later.
Field Name

Field Type

Description

action

string

Required. The action performed in the console when a user presses the
keyboard shortcut. Valid values are:
• FOCUS_CONSOLE
• FOCUS_NAVIGATOR_TAB
• FOCUS_DETAIL_VIEW
• FOCUS_PRIMARY_TAB_PANEL
• FOCUS_SUBTAB_PANEL
• FOCUS_LIST_VIEW
• FOCUS_FIRST_LIST_VIEW
• FOCUS_SEARCH_INPUT
• MOVE_LEFT
• MOVE_RIGHT
• UP_ARROW
• DOWN_ARROW
• OPEN_TAB_SCROLLER_MENU

210

Metadata Types

Field Name

CustomApplication

Field Type

Description
• OPEN_TAB
• CLOSE_TAB
• ENTER
• EDIT
• SAVE
For a list and description of the default keyboard shortcuts, see “Default
Keyboard Shortcuts for a Salesforce Console in Salesforce Classic” in the
Salesforce online help.

active

boolean

Required. Indicates whether the keyboard shortcut is active (true) or
not (false).

keyCommand

string

211

Metadata Types

Field Name

CustomApplication

Field Type

Description
• DOWN ARROW
• PRINT SCREEN
• INSERT
• DELETE
• RIGHT WINDOW
• NUMPAD 0
• NUMPAD 1
• NUMPAD 2
• NUMPAD 3
• NUMPAD 4
• NUMPAD 5
• NUMPAD 6
• NUMPAD 7
• NUMPAD 8
• NUMPAD 9
• MULTIPLY
• ADD
• SUBTRACT
• DECIMAL POINT
• DIVIDE
• F1
• F2
• F3
• F4
• F5
• F6
• F7
• F8
• F9
• F10
• F11
• F12
• NUM LOCK
• SCROLL LOCK
• ;
• =
• ,
• —

212

Metadata Types

Field Name

CustomApplication

Field Type

Description
• .
• /
• ‘
• [
• ]
• \
• '

DomainWhitelist
Represents any external domains that users can access from within a Salesforce console app. For example, www.yourdomain.com.
Available in API version 25.0 and later.
Field Name

Field Type

Description

domain

string

The external domains that users can access from within this Salesforce
console app.

KeyboardShortcuts
Represents keyboard shortcuts assigned to a Salesforce console app. Required if isServiceCloudConsole is true. Available
in API version 28.0 and later.
Field Name

Field Type

Description

customShortcut

KeyboardShortcuts[]

Represents custom keyboard shortcuts assigned to a Salesforce console
app. Before you can create custom shortcuts, a developer must define
the shortcut’s action with the addEventListener() method in
the Salesforce Console Integration Toolkit. You can’t create keyboard
shortcuts for actions performed outside of the console.

defaultShortcut

KeyboardShortcuts[]

Represents default keyboard shortcuts assigned to a Salesforce console
app. Once you enable keyboard shortcuts for a console, several default
shortcuts are available for customization. These include opening and
closing tabs, moving between tabs, and saving records.
For a list and description of the default keyboard shortcuts, see “Default
Keyboard Shortcuts for a Salesforce Console in Salesforce Classic” in the
Salesforce online help.

ListPlacement
Represents how lists display in a Salesforce console app. Required if isServiceCloudConsole is true. Available in API version
25.0 and later.

213

Metadata Types

CustomApplication

Field Name

Field Type

Description

height

int

Height of the list in pixels or percentage. Required if location is top.

location

string

Required. Location of the list on the screen. Valid values are:
• full
• top
• left

units

string

Required. Represents if height or width is in pixels or percentage.

width

int

Width of the list in pixels or percentage. Required if location is left.

LiveAgentConfig
Represents your organization’s settings for using Live Agent in the Salesforce Console.
Field Name

Field Type

Description

enableLiveChat

boolean

Specifies whether Live Agent is enabled in your organization (true) or
not (false).

openNewAccountSubtab

boolean

Specifies whether to open a new Account subtab in the Salesforce
Console automatically (true) or not (false) when an agent accepts
a chat.

openNewCaseSubtab

boolean

Specifies whether to open a new Case subtab in the Salesforce Console
automatically (true) or not (false) when an agent accepts a chat.

openNewContactSubtab

boolean

Specifies whether to open a new Contact subtab in the Salesforce Console
automatically (true) or not (false) when an agent accepts a chat.

openNewLeadSubtab

boolean

Specifies whether to open a new Lead subtab in the Salesforce Console
automatically (true) or not (false) when an agent accepts a chat.

openNewVFPageSubtab

boolean

Specifies whether to open a new Visualforce page as a subtab in the
Salesforce Console automatically (true) or not (false) when an agent
accepts a chat.

pagesToOpen

PagesToOpen on page Specifies the Visualforce pages to open in subtabs when an agent accepts
214
a chat in the Salesforce Console.

showKnowledgeArticles

boolean

Specifies whether to display the Knowledge component while using Live
Agent in the Salesforce Console (true) or not (false).

PagesToOpen
Represents the Visualforce pages you want to open in subtabs when an agent accepts a chat request in the Salesforce Console. Available
in API version 28.0 and later.

214

Metadata Types

CustomApplication

Field Name

Field Type

Description

pagesToOpen

string

The name of the Visualforce pages you want to open in subtabs when
an agent accepts a chat in the Salesforce Console.

PushNotifications
Represents a set of push notifications, which are visual indicators on lists and detail pages that show when a record or field has changed
during a user’s session. Available for use if isServiceCloudConsole is true. Available in API version 28.0 and later.
Field Name

Field Type

Description

pushNotification

PushNotification[]

The set of push notifications.

PushNotification
Represents if visual indicators on lists and detail pages display in a Salesforce console app when a record or field has changed during a
user’s session. Available for use if isServiceCloudConsole is true. Available in API version 28.0 and later.
Field Name

Field Type

Description

fieldNames

string

Required. The name of the field, or fields, that trigger push notifications
for the selected object.

objectName

string

Required. Name of the object that triggers push notifications.

TabLimitConfig
Represents the maximum number of primary tabs and subtabs allowed in one Salesforce console session. Required if
enableTabLimits is true. Available in API version 36.0 and later.
Field Name

Field Type

maxNumberOfPrimaryTabs string

Description
The maximum number of primary tabs allowed in one console session.
Valid values are:
• 5
• 10
• 20
• 30

maxNumberOfSubTabs

string

The maximum number of subtabs allowed in one console session. Valid
values are:
• 5
• 10
• 15

215

Metadata Types

CustomApplication

WorkspaceMappings
Represents how records open in a Salesforce console app. Required if isServiceCloudConsole is true. Available in API version
25.0 and later.
Field Name

Field Type

Description

mapping

WorkspaceMapping

Represents how records for a specific tab open in a Salesforce console
app. Required for each tab specified in the CustomApplication.

WorkspaceMapping
Represents how records for a specific tab open in a Salesforce console app. Required for each tab specified in the CustomApplication.
Available in API version 25.0 and later.
Field Name

Field Type

Description

fieldName

string

The name of the field that specifies the primary tab in which to display
tab as a subtab. If not specified, tab opens as a primary tab.

tab

string

Required. Name of the tab.

Retrieving Apps
To retrieve apps in your organization, use the CustomApplication type name in the package.xml manifest file. You can either retrieve
all apps or specify which apps to retrieve in the types section of package.xml.
To retrieve all apps in your organization—custom and standard apps, specify the wildcard character (*), as follows.

*
CustomApplication

Note: In API version 29.0 and earlier, use of the wildcard returns only all custom applications but not standard applications.
To retrieve a custom app, specify the app name.

MyCustomApp
CustomApplication

To retrieve a standard app, add the standard__ prefix to the app name. For example, to retrieve the Chatter standard app, specify
standard__Chatter.

standard__Chatter
CustomApplication

216

Metadata Types

CustomApplication

To retrieve an app that is part of an installed package, add the package namespace prefix followed by two underscores and the app
name. For example, if the package namespace is myInstalledPackageNS and the app name is PackageApp, specify
myInstalledPackageNS__PackageApp, as follows.

myInstalledPackageNS__PackageApp
CustomApplication

Declarative Metadata Sample Definition
The following is the definition of a custom app:

Myriad_Publishing__c
App to manage Myriad Publishing
Myriad
MyriadFolder/Myriad_Logo.jpg
standard-Chatter
standard-File
Myriad_Publishing__c
standard-report
standard-Dashboard

The following is a definition of a standard app (Chatter):

standard-home
Collaboration
standard-Chatter
standard-UserProfile
standard-OtherUserProfile
standard-CollaborationGroup
standard-File

Declarative Metadata Sample Definition—Salesforce Console
The following is the definition of a custom app where isServiceCloudConsole is true:

left
MyComponent

standard-home
autoRefresh
true

217

Metadata Types

CustomApplication

MyCustomShortcutAction
true
X
Custom Shortcut example
myCustomShortcutExample

FOCUS_CONSOLE
true
ESC

FOCUS_NAVIGATOR_TAB
true
V

FOCUS_DETAIL_VIEW
true
SHIFT+S

FOCUS_PRIMARY_TAB_PANEL
true
P

FOCUS_SUBTAB_PANEL
true
S

FOCUS_LIST_VIEW
true
N

FOCUS_FIRST_LIST_VIEW
true
SHIFT+F

FOCUS_SEARCH_INPUT
true
R

MOVE_LEFT
true
LEFT ARROW

MOVE_RIGHT
true

218

Metadata Types

CustomApplication

RIGHT ARROW

UP_ARROW
true
UP ARROW

DOWN_ARROW
true
DOWN ARROW

OPEN_TAB_SCROLLER_MENU
true
D

OPEN_TAB
true
T

CLOSE_TAB
true
C

ENTER
true
ENTER

EDIT
true
E

SAVE
true
CTRL+S

MyConsole

left
percent
20

refreshList

CreatedBy
Campaign

219

Metadata Types

CustomApplicationComponent

CustomField1__c
CustomObject1__c

false
standard-Case
standard-Account
standard-Contact
standard-Contract

standard-Case

AccountId
standard-Contract

standard-Contract

ParentId
standard-Account

category

ReportTypeCategory
(enumeration of type string)

Required. This field controls the category for the report. The valid values
are:
• accounts
• opportunities
• forecasts
• cases
• leads
• campaigns
• activities
• busop
• products
• admin
• territory
• territory2 (This value is available in API version 31.0 and later.)
• usage_entitlement
• wdc (This value is available in API version 29.0 and later.)
• calibration (This value is available in API version 29.0 and later.)
• other
• content

deployed

boolean

Required. Indicates whether the report type is available to users (true)
or whether it's still in development (false).

546

Metadata Types

ReportType

Field Name

Field Type

Description

description

string

The description of the custom report type.

fullName

string

The report type developer name used as a unique identifier for API access.
The fullName can contain only underscores and alphanumeric
characters. It must be unique, begin with a letter, not include spaces, not
end with an underscore, and not contain two consecutive underscores.

join

ObjectRelationship

The object joined to the baseObject. For example, Contacts may be
joined to the primary Accounts object.

label

string

Required. The report type label.

sections

ReportLayoutSection[]

The groups of columns available for the report type. Though columns are
not strictly required, a report without columns is not very useful.

ObjectRelationship
ObjectRelationship represents a join to another object. For more information, see “Add Child Objects To Your Custom Report Type” in
the Salesforce online help.
Field Name

Field Type

Description

join

ObjectRelationship

This field is a recursive reference that allows you to join more than two objects.
A maximum of four objects can be joined in a custom report type. When more
than two objects are joined, an inner join is not allowed if there has been an
outer join earlier in the join sequence. The baseObject is first joined to the
object specified in relationship; the resulting data set is then joined with
any objects specified in this field.

outerJoin

boolean

Required. Indicates whether this is an outer join (true) or not (false). An
outer join returns a row even if the joined table does not contain a matching
value in the join column.

relationship

string

Required. The object joined to the primary object; for example, Contacts.

ReportLayoutSection
ReportLayoutSection represents a group of columns used in the custom report type.
Field Name

Field Type

Description

columns

ReportTypeColumn[]

The list of columns projected from the query, defined by
this custom report type.

masterLabel

string

Required. The label for this group of columns in the report
wizard.

547

Metadata Types

ReportType

ReportTypeColumn
ReportTypeColumn represents a column in the custom report type.
Field Name

Field Type

Description

checkedByDefault boolean

Required. Indicates whether this column is selected be default (true) or not
(false).

displayNameOverride string

A customized column name, if desired.

field

string

Required. The field name associated with the report column.

table

string

Required. The table associated with the field; for example, Account.

Declarative Metadata Sample Definition
The definition of a custom report type is shown below. Account is joined to Contacts and the resulting data set is joined with Assets.

Account
accounts
true
Account linked to Contacts and Assets

false
Assets

false
Contacts

Account Contacts and Assets

true
obj_lookup__c.Id
Account

false
obj_lookup__c.Name
Account

false
Opportunity__c.Amount
Account

false
Owner.IsActive
Account

548

Metadata Types

Role

Accounts

false
Owner.Email
Account.Contacts

false
byr__c
Account.Contacts

true
ReportsTo.CreatedBy.Contact.Owner.MobilePhone
Account.Contacts

Contacts

Usage
The custom report type refers to fields by using their API names. For a historical field (one that has trackTrending set to true)
the API name includes hst, such as Field2__c_hst.

false
Field2__c_hst
CustomTrendedObject__c.CustomTrendedObject__c_hst

History

For more information, see trackTrending on page 256.

Role
Represents a role in your organization.

Declarative Metadata File Suffix and Directory Location
The file suffix for role components is .role and components are stored in the roles directory of the corresponding package
directory.

Version
Role components are available in API version 24.0 and later.

549

Metadata Types

RoleOrTerritory

Fields
This metadata type extends to subtype RoleOrTerritory on page 550.
Field Name

Field Type

Description

fullName

string

parentRole

string

The role above this role in the hierarchy.

Declarative Metadata Sample Definition
The following is the definition of a role.

Edit
Edit
Sample Role
false
R22
Read

RoleOrTerritory
Represents the common base type and valid values for role or territory.

Version
RoleOrTerritory components are available in API version 24.0 and later.
Note: You can’t create a RoleOrTerritory component directly. Use the Role or Territory metadata types instead.

Fields
Field Name

Field Type

Description

caseAccessLevel

string

Specifies whether a user can access other users’ cases that are associated
with accounts the user owns. Valid values are:
• Read
• Edit
• None

550

Metadata Types

Field Name

RoleOrTerritory

Field Type

Description
This field is not visible if your organization’s sharing model for cases is
Public Read/Write.
If no value is set for this field, this field value uses the default access level
that is specified in the Manage Territory page in Setup.

contactAccessLevel

string

Specifies whether a user can access other users’ contacts that are
associated with accounts the user owns. Valid values are:
• Read
• Edit
• None
This field is not visible if your organization’s sharing model for contacts
is Public Read/Write or Controlled by Parent.
If no value is set for this field, this field value uses the default access level
that is specified in the Manage Territory page in Setup.

description

string

The description of the role or territory.

fullName

string

mayForecastManagerShare boolean

name

string

opportunityAccessLevel string

Indicates whether the forecast manager can manually share their own
forecast.
Required. The name of the role or territory.
Specifies whether a user can access other users’ opportunities that are
associated with accounts the user owns. Valid values are:
• Read
• Edit
• None
This field is not visible if your organization’s sharing model for
opportunities is Public Read/Write.
If no value is set for this field, this field value uses the default access level
that is specified in the Manage Territory page in Setup.

Declarative Metadata Sample Definition
The following is the definition of a role.

Edit

551

Metadata Types

SamlSsoConfig

Edit
Sample Role
false
R22
Read

The following is the definition of a territory.

Edit
Edit
Edit
Sample Territory
false
T22name
Read

SEE ALSO:
Settings

ActivitiesSettings
Represents an organization’s activity settings, and its user interface settings for the calendar. Use the ActivitiesSettings component type
to control the following activity settings:
• Configure group and recurring tasks, recurring and multiday events, and email tracking
• Relate multiple contacts to tasks and events (shared activities)
• Display custom logos in meeting requests

559

Metadata Types

ActivitiesSettings

Also use the ActivitiesSettings component type to control user interface settings for the calendar, including hover links and drag-and-drop
editing.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

File Suffix and Directory Location
ActivitiesSettings values are stored in the Activities.settings file in the settings directory. The .settings files are
different from other named components because there is only one settings file for each settings component.

Version
ActivitiesSettings is available in API versions 28.0 and later.

Fields
Settings for all types listed below are controlled on the Activity settings page or the User Interface settings page as noted.
Field Name

Field Type

allowUsersToRelateMultipleContactsToTasksAndEvents boolean

Description
This read only field indicates whether Shared Activities is enabled. When
the value is true, allows users to relate multiple contacts to a task or
event.
Important: Beginning with API v36.0, this field is read-only in
all versions of the API. You can’t change the value of this field.
Even though this field was updateable before Spring '16, changing
this field’s value wasn't supported and could have resulted in an
incorrect integration. If you have code in older API versions that
changes the value of this field, ensure you update that code to
prevent any errors.

enableActivityReminders

boolean

Enables popup activity reminders for an organization.
Administrators control this field on the Activity settings page.

enableClickCreateEvents

boolean

Lets users create events in day and weekly calendar views by
double-clicking a specific time slot and entering the details of the event
in an overlay. Hovering over an event displays an overlay where users
can view the event details or delete the event without leaving the page.
Administrators use a mini page layout to configure the fields shown in
the overlays. Does not support recurring events or multi-person events.
Administrators control this field on the User Interface settings page.

enableDragAndDropScheduling boolean

Lets users create events associated with records by dragging a record
from a list view onto a calendar view and entering the details of the
event in an overlay. Hovering over an event displays an overlay where
users can view the event details or delete the event without leaving the
page. Administrators use a mini page layout to configure the fields shown
in the overlays.

560

Metadata Types

Field Name

ActivitiesSettings

Field Type

Description
Administrators control this field on the User Interface settings page.

enableEmailTracking

boolean

Enables tracking of outbound HTML emails if an organization uses HTML
email templates.
Administrators control this field on the Activity settings page.

enableGroupTasks

boolean

Lets users assign independent copies of a new task to multiple users.
Administrators control this field on the Activity settings page.

enableListViewScheduling boolean

Extends the functionality of enableDragAndDropScheduling
and enableClickCreateEvents to list view calendars.
Administrators control this field on the User Interface settings page.

enableMultidayEvents

boolean

Enables creation of events that end more than 24 hours after they start.
Administrators control this field on the Activity settings page.

enableRecurringEvents

boolean

Enables creation of events that repeat at specified intervals.
Administrators control this field on the Activity settings page.

enableRecurringTasks

boolean

Enables creation of tasks that repeat at specified intervals.
Administrators control this field on the Activity settings page.

enableSidebarCalendarShortcut boolean

In the sidebar, displays a shortcut link to a user’s last-used calendar view.
Administrators control this field on the Activity settings page.

enableSimpleTaskCreateUI boolean

Allows administrators to specify whether tapping New Task in Salesforce1
opens a regular task record edit page or a page that displays key task
fields first.
Administrators control this field on the Activity settings page.

enableUNSTaskDelegatedToNotifications boolean

meetingRequestsLogo

string

On the Activity settings page, exposes a setting for administrators to
hide or show a user setting that lets individual users enable or disable
email notifications when tasks are assigned to them.
Available when showCustomLogoMeetingRequests is enabled.
Uploads a custom logo. An administrator can select only a logo that has
been uploaded to certain folders in the Documents tab.
Administrators control this field on the Activity settings page.

showCustomLogoMeetingRequests boolean

Displays a custom logo in meeting request emails and on a meeting’s
Web page. Invitees see the logo when a user either invites them to an
event or requests a meeting.
Administrators control this field on the Activity settings page.

561

Metadata Types

Field Name

ActivitiesSettings

Field Type

showEventDetailsMultiUserCalendar boolean

Description
Displays event details on-screen rather than in hover text.
Administrators control this field on the Activity settings page.

showHomePageHoverLinksForEvents boolean

In the calendar section of the Home tab:
• When a user hovers over the subject of an event, a hover link displays
an overlay with selected event details. (Hover links are always
available in other calendar views.)
• When a user clicks the subject of an event, displays the event detail
page.
Administrators use a mini page layout to configure the fields shown in
the overlay.
Administrators control this field on the User Interface settings page.

showMyTasksHoverLinks

boolean

In the My Tasks section of the Home tab and on the calendar day view:
• When a user hovers over the subject of a task, a hover link displays
an overlay with selected task details.
• When a user clicks the subject of a task, displays the task detail page.
Administrators use a mini page layout to configure the fields shown in
the overlay.
Administrators control this field on the User Interface settings page.

showRequestedMeetingsOnHomePage boolean

In the Calendar on the Home tab, displays the Requested Meetings
subtab, listing the meetings a user has requested but not confirmed.
Disabling this feature removes the New Meeting Request button from
the calendar on the Home tab.
Administrators control this field on the Activity settings page.

Example Package Manifest
The following is an example package manifest used to deploy or retrieve the Activity settings metadata for an organization:

Activities
Settings

28.0

562

Metadata Types

AddressSettings

Declarative Metadata Sample Definition
The following is an example of an activity settings file:

true
true
true
true
true
true
true
true
true
true
Folder02/logo03.png
true
true
true
true
true

SEE ALSO:
Settings

BusinessHoursSettings
Represents the metadata used to manage settings for business hours and holidays in entitlements, entitlement templates, campaigns,
and cases. This type extends the Metadata metadata type and inherits its fullName field.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

File Suffix and Directory Location
Business hours and holidays settings are stored in a single file named businessHours.settings in the settings directory.
The .settings files are different from other named components because there is only one settings file for each settings component.

Version
BusinessHoursSettings is available in API version 29.0 and later.

Fields
Field Name

Field Type

Description

businessHours

BusinessHoursEntry[]

Represents the application of business hours to entitlements,
entitlement templates, campaigns, and cases.

holidays

Holidays[]

Represents a holiday and its usage in businessHours.

BusinessHoursEntry
Represents the application of business hours to entitlements, entitlement templates, campaigns, and cases.
Field Name

Field Type

Description

timeZoneId

string

The time zone for the time that defines business hours.

name

string

Name of the business hours. This name should be unique.

active

string

Indicates whether the business hours are active.

default

string

Indicates whether the business hours are used as the default business
hours.

567

Metadata Types

BusinessHoursSettings

Field Name

Field Type

Description

mondayStartTime

string

Start time for the business hours on Monday. Uses the format
HH:mm:ss.SSSZ.

mondayEndTime

string

End time for the business hours on Monday. Uses the format
HH:mm:ss.SSSZ. The value 00:00:00.000Z specifies midnight
on Monday.

tuesdayStartTime

string

Start time for the business hours on Tuesday. Uses the format
HH:mm:ss.SSSZ.

tuesdayEndTime

string

End time for the business hours on Tuesday. Uses the format
HH:mm:ss.SSSZ. The value 00:00:00.000Z specifies midnight
on Tuesday.

wednesdayStartTime

string

Start time for the business hours on Wednesday. Uses the format
HH:mm:ss.SSSZ.

wednesdayEndTime

string

End time for the business hours on Wednesday. Uses the format
HH:mm:ss.SSSZ. The value 00:00:00.000Z specifies midnight
on Wednesday.

thursdayStartTime

string

Start time for the business hours on Thursday. Uses the format
HH:mm:ss.SSSZ.

thursdayEndTime

string

End time for the business hours on Thursday. Uses the format
HH:mm:ss.SSSZ. The value 00:00:00.000Z specifies midnight
on Thursday.

fridayStartTime

string

Start time for the business hours on Friday. Uses the format
HH:mm:ss.SSSZ.

fridayEndTime

string

End time for the business hours on Friday. Uses the format
HH:mm:ss.SSSZ. The value 00:00:00.000Z specifies midnight
on Friday.

saturdayStartTime

string

Start time for the business hours on Saturday. Uses the format
HH:mm:ss.SSSZ.

saturdayEndTime

string

End time for the business hours on Saturday. Uses the format
HH:mm:ss.SSSZ. The value 00:00:00.000Z specifies midnight
on Saturday.

sundayStartTime

string

Start time for the business hours on Sunday. Uses the format
HH:mm:ss.SSSZ.

sundayEndTime

string

End time for the business hours on Sunday. Uses the format
HH:mm:ss.SSSZ. The value 00:00:00.000Z specifies midnight
on Sunday.

Holidays
Represents a holiday and its usage in businessHours.

568

Metadata Types

BusinessHoursSettings

Field Name

Field Type

Description

name

string

Name of the holiday. This name does not have to be unique.

description

string

The description of the holiday.

isRecurring

string

Indicates whether the holiday is recurring.

activityDate

string

The date of the holiday. Use for non-recurring holidays. Uses the format
HH:mm:ss.SSSZ.

recurrenceStartDate

string

The date the holiday starts recurring. Uses the format yyyy-mm-dd.

recurrenceEndDate

string

The date the holiday stops recurring. Uses the format yyyy-mm-dd.
Optional.

startTime

string

The start time on the date of the holiday. Uses the format
HH:mm:ss.SSSZ. startTime and endTime must be both null
or both not null. If they are both null, indicates the whole day.

endTime

string

The end time on the date of the holiday. Uses the format
HH:mm:ss.SSSZ. startTime and endTime must be both null
or both not null. If they are both null, indicates the whole day.

recurrenceType

string

The recurrence type of the holiday. Valid values are: RecursDaily,
RecursEveryWeekday, RecursMonthly, RecursMonthlyNth, RecursWeekly,
RecursYearly, RecursYealyNth.

recurrenceInterval

string

The interval of weeks, months, or years the holiday recurs.

recurrenceDayOfWeek

string

The day of week the holiday recurs. Valid values: Monday, Tuesday,
Wednesday, Thursday, Friday, Saturday, Sunday.

recurrenceDayOfMonth

string

The day of month the holiday recurs. Valid values: integers 1-31.

recurrenceInstance

string

Valid values: First, Second, Third, Fourth, Last. Only used for
recurrenceType RecursMonthlyNth and RecursYearlyNth. For example,
if the recurenceInstance value is First, the holiday recurs on the
first Monday of the month every 3 months.

recurrenceMonthOfYear

string

Valid values: January, February, March, April, May, June, July, August,
September, October, November, December.

businessHours

string

The name of the business hours setting that applies to this holiday.

Declarative Metadata Sample Definition
The following is an example businesshours.settings metadata file:

true
true
00:00:00.000Z

569

Metadata Types

BusinessHoursSettings

00:00:00.000Z
00:00:00.000Z
00:00:00.000Z
Default
00:00:00.000Z
00:00:00.000Z
00:00:00.000Z
00:00:00.000Z
00:00:00.000Z
00:00:00.000Z
America/Los_Angeles
00:00:00.000Z
00:00:00.000Z
00:00:00.000Z
00:00:00.000Z

true
false
00:00:00.000Z
00:00:00.000Z
15:00:00.000Z
09:00:00.000Z
bh1
00:00:00.000Z
00:00:00.000Z
00:00:00.000Z
00:00:00.000Z
17:00:00.000Z
10:50:00.000Z
America/Los_Angeles
13:00:00.000Z
09:00:00.000Z
15:00:00.000Z
09:00:00.000Z

2013-09-02
Default
bh1
false
Labor Day

bh1
true
Thanksgiving
21
November
2013-11-21
RecursYearly

570

Metadata Types

CaseSettings

The following is an example package.xml manifest that references the BusinessHoursSettings definitions:

BusinessHours
Settings

29.0

CaseSettings
Represents an organization’s case settings, such as the default case owner, which case-related features are enabled, and which email
templates are used for various case activities.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

File Suffix and Directory Location
CaseSettings values are stored in the Case.settings file in the settings directory. The .settings files are different from
other named components because there is only one settings file for each settings component.

Version
CaseSettings is available in API version 27.0 and later.

Fields
Field Name

Field Type

Description

caseAssignNotificationTemplate string

Specifies the email template used for case assignment
notifications. The format must be
folderName/emailTemplateName.

caseCloseNotificationTemplate string

Specifies the email template used for case close notifications.
The format must be
folderName/emailTemplateName.

caseCommentNotificationTemplate string

Specifies the email template used for case comment
notifications. The format must be
folderName/emailTemplateName.

caseCreateNotificationTemplate string

Specifies the email template used for case create
notifications. The format must be
folderName/emailTemplateName.

caseFeedItemSettings

FeedItemSettings[]

closeCaseThroughStatusChange boolean

Specifies the settings for feed items in feed-based case page
layouts. This field is available in API version 32.0 and later.
Indicates whether Closed is included in the Case Status
field on case edit pages (true) or not (false).

571

Metadata Types

CaseSettings

Field Name

Field Type

Description

defaultCaseOwner

string

Specifies the default owner of a case when assignment rules
fail to locate an owner.

defaultCaseOwnerType

string

Specifies whether the default case owner is a user or a queue.

defaultCaseUser

string

Specifies the user listed in the Case History related list for
automated case changes from:
• Assignment rules
• Escalation rules
• On-Demand Email-to-Case
• Cases logged in the Self-Service portal

emailToCase

EmailToCaseSettings

The organization’s Email-to-Case settings.

enableCaseFeed

boolean

Indicates whether Case Feed is enabled (true) or not
(false).

enableDraftEmails

boolean

Indicates whether draft emails are enabled (true) or not
(false). Enabling email drafts requires that Case Feed and
Email-to-Case are also enabled.

enableEarlyEscalationRuleTriggers boolean

Indicates whether early triggers on escalation rules are
enabled (true) or not (false).

enableNewEmailDefaultTemplate boolean

Indicates whether default email templates are enabled
(true) or not (false). Default email templates are
available only if draft emails are enabled.

enableSuggestedArticlesApplication boolean

Indicates whether the Suggested Articles list appears on case
pages.(true) or not (false). Is only valid if
enableSuggestedSolutions=false.

enableSuggestedArticlesCustomerPortal boolean

Indicates whether the Suggested Articles list appears on
customer portal pages (true) or not (false). Is only valid
if enableSuggestedSolutions=false.

enableSuggestedArticlesPartnerPortal boolean

Indicates whether the Suggested Articles list appears on
partner portal pages (true) or not (false). Is only valid if
enableSuggestedSolutions=false.

boolean

Indicates whether the View Suggested Solutions or Find
Articles button appears on case detail pages (true) or not
(false). Is only valid if
enableSuggestedArticlesApplication,
enableSuggestedArticlesCustomerPortal,
and
enableSuggestedArticlesPartnerPortal=false.

enableSuggestedSolutions

keepRecordTypeOnAssignmentRule boolean

Indicates whether, when applying assignment rules to
manually created records, to keep the existing record type

572

Metadata Types

Field Name

CaseSettings

Field Type

Description
(true) or to override the existing record type with the
assignee’s default record type (false).

newEmailDefaultTemplateClass string

Specifies the Apex class that defines the default email
template for new email messages in Case Feed. This field
appears only when
enableNewEmailDefaultTemplate=true.

notifyContactOnCaseComment

boolean

Indicates whether contacts who are not members of your
Self-Service portal can be notified when a new comment is
added to a case.(true) or not (false).

notifyDefaultCaseOwner

boolean

Indicates whether the default case owner is notified when
assigned a new case (true) or not (false).

notifyOwnerOnCaseComment

boolean

Indicates whether the case owner is notified when a
comment is added to a case (true) or not (false).

notifyOwnerOnCaseOwnerChange boolean

Indicates whether the Send Notification Email
checkbox on cases is automatically selected when users
change a case owner to another user (true).

showFewerCloseActions

boolean

Indicates whether the Save & Close button on case edit
pages and the Cls link on Cases related lists are hidden
(true) or shown (false).

systemUserEmail

string

Specifies the email address used when the default case user
is the system user.

useSystemEmailAddress

boolean

Indicates whether case comment, case attachment, and case
assignment email notifications are sent from a system
address (true) or whether case notifications appear to be
sent from the user or contact updating the case (false).

useSystemUserAsDefaultCaseUser boolean

Indicates whether the system user is used as the automated
case user (true) or not (false). If false, then you must
specify a value for the defaultCaseUser field.

webToCase

WebToCaseSettings

EmailToCaseSettings
Represents an organization’s Email-to-Case settings.

573

The organization’s Web-to-Case settings.

Metadata Types

CaseSettings

Fields
Field Name

Field Type

Description

enableEmailToCase

boolean

Indicates whether Email-to-Case is enabled (true) or not
(false). Note: once Email-to-Case is enabled, it can’t be
disabled.

enableHtmlEmail

boolean

Indicates whether HTML email is enabled (true) or not
(false).

enableOnDemandEmailToCase boolean

Indicates whether On-Demand Email-to-Case is enabled
(true) or not (false).

boolean

Indicates whether the Thread ID for a case is inserted in the
body of an email (true) or not (false).

enableThreadIDInSubject boolean

Indicates whether the Thread ID for a case is inserted in the
subject line of an email (true) or not (false).

notifyOwnerOnNewCaseEmail boolean

Indicates whether the owner of a case receives a notification
when a new email related to the case is received (true) or
not (false).

enableThreadIDInBody

overEmailLimitAction

EmailToCaseOnFailureActionType Specifies what happens to email messages received after an
(enumeration of type string)
organization exceeds its daily Email-to-Case limits. Valid values
are:
• Bounce
• Discard
• Requeue

preQuoteSignature

boolean

Indicates whether the user signature is inserted after the reply
but before the email thread in an outbound email (true) or
at the end of the email (false).

routingAddresses

EmailToCaseRoutingAddress[]

The organization’s Email-to-Case routing address settings.

unauthorizedSenderAction EmailToCaseOnFailureActionType Specifies what happens to email messages received from

(enumeration of type string)

invalid senders. Valid values are:
• Bounce
• Discard

EmailToCaseRoutingAddress
Represents an organization’s Email-to-Case routing address.

574

Metadata Types

CaseSettings

Fields
Field Name

Field Type

Description

addressType

EmailToCaseRoutingAddressType Specifies the type of Email-to-Case routing address. Valid
(enumeration of type string)
values are:
• EmailToCase—A routing address used with
Email-to-Case or On-Demand Email-to-Case.
• Outlook—A routing address used with
Salesforce for Outlook to create cases from Outlook.
Requires that On-Demand Email-to-Case is enabled.

authorizedSenders

string

Specifies the email addresses or domains from which
On-Demand Email-to-Case can receive email. Include multiple
entries in a comma-separated list.

caseOrigin

string

Specifies the default case origin for cases created through this
routing address.

caseOwner

string

Specifies the default owner of cases created through this
routing address. The case owner can be either a user or a
queue. Specify the case owner using a Salesforce username.
Specifying a case owner here in the routing address settings
value of defaultCaseOwner in CaseSettings.

caseOwnerType

string

Specifies whether the default case owner is a user or a queue.

casePriority

string

Specifies the default case priority for cases created through
this routing address.

createTask

boolean

Indicates whether a task is automatically assigned to the case
owner when a case is created through an email (true) or
not (false).

emailAddress

string

Specifies the email address used to route email messages that
are submitted as cases.

emailServicesAddress

string

Reserved for future use.

isVerified

boolean

Reserved for future use.

routingName

string

Specifies the name of the Email-to-Case routing address.

saveEmailHeaders

boolean

Indicates whether email routing and envelope information
are saved (true) or not (false).

taskStatus

string

Specifies the default status on tasks automatically assigned
to the case owner when email is submitted as a case. Only
applies if createTask is set to true.

575

Metadata Types

CaseSettings

FeedItemSettings
Represents an organization’s feed item settings. Available in API version 32.0 and later.
Field Name

Field Type

Description

characterLimit

int

Specifies the maximum number of characters displayed for
each feed item.

collapseThread

boolean

Indicates whether earlier messages in an email thread are
removed from email feed items(true) or not (false).

displayFormat

FeedItemDisplayFormat
(enumeration of type string)

Indicates how email feed items are displayed. Valid values are:
• Default—Blank lines in email feed items are displayed.
• HideBlankLines—Blank lines in email feed items
are not displayed.

feedItemType

FeedItemType (enumeration of The type of feed item to which the settings apply. For
type string)
FeedItemSettings, the only valid feedItemType
value is EmailMessageEvent.

WebToCaseSettings
Represents an organization’s Web-to-Case settings.

Fields
Field Name

Field Type

Description

caseOrigin

string

Specifies the default case origin for cases created through this web form.
Only applies if enableWebToCase is set to true.

defaultResponseTemplate

string

Specifies the default template used for email responses to cases
submitted through a Self-Service portal. Only applies if
enableWebToCase is set to true.

enableWebToCase

boolean

Indicates whether Web-to-Case is enabled (true) or not (false).

Declarative Metadata Sample Definition
This code sample is an example of a case settings file.

unfiled$public/SupportCaseAssignmentNotification

unfiled$public/SupportCaseCloseNotification

576

Metadata Types

CaseSettings

unfiled$public/SupportCaseCommentNotification

unfiled$public/SupportCaseCreateNotification

true
admin@acme.com
User
admin@acme.com

true
false
true
true
true
false
Bounce
true

EmailToCase
user@acme.com
Email
Medium
true
support@acme.com
EmailToCaseRoutingAddress1
true
Not Started

Outlook
user@acme.com
Email
admin@acme.com
User
High
OutlookRoutingAddress1

Discard

true
true
true
true
true
true
false
false
true
CaseTemplateController
true
true
true

577

Metadata Types

ChatterAnswersSettings

false
false
true

Web
unfiled$public/SupportCaseResponse
true

SEE ALSO:
Settings

ChatterAnswersSettings
Represents the metadata used to manage settings for Chatter Answers.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

File Suffix and Directory Location
Chatter Answers settings are stored in a single file named ChatterAnswers.settings in the settings directory. The
.settings files are different from other named components because there is only one settings file for each settings component.

Version
ChatterAnswersSettings is available in API version 27.0 and later.

Fields
Field Name

Field Type

Description

emailFollowersOnBestAnswer boolean

Indicates whether users are notified when a best answer is selected for
a question that they’re following (true) or not (false).

boolean

Indicates whether users are notified when other users reply to questions
they’re following (true) or not (false).

emailOwnerOnPrivateReply boolean

Indicates whether users are notified when customer support responds
to their questions privately (true) or not (false).

emailFollowersOnReply

emailOwnerOnReply

boolean

Indicates whether users are notified when other users reply to their
questions (true) or not (false).

enableAnswerViaEmail

boolean

Indicates whether users can post answers by replying to email
notifications (true) or not (false). This field is available in API version
29.0 and later.

enableChatterAnswers

boolean

Indicates whether Chatter Answers is enabled in the organization (true)
or not (false).

578

Metadata Types

ChatterAnswersSettings

Field Name

Field Type

Description

enableFacebookSSO

boolean

Indicates whether users sign in to your Chatter Answers communities
with their Facebook logins (true) or not (false). To enable this
feature, you must define and enable a Facebook authentication provider
in your organization’s security controls and enable Auth Providers in
your organization.

enableInlinePublisher

boolean

Indicates whether users can filter search results by articles or questions
before they post a question to any of your Chatter Answers communities
(true) or not (false). Also, adds Title and Body fields to
questions for easier text input and scanning. This field is available in API
version 29.0 and later.

enableReputation

boolean

Indicates whether reputations display for users as hover text on their
profile pictures (true) or not (false). Reputation is enabled across
all zones. To enable the reputation setting, you must enable Reputation
in your organization.

enableRichTextEditor

boolean

Indicates whether the rich text editor is enabled for users to format text
and upload images when posting questions (true) or not (false).
To enable rich text editor, you must enable Optimize Question Flow.

facebookAuthProvider

string

The name of an existing Facebook authentication provider. You must
choose a Facebook authentication provider to implement Facebook
Single Sign On for your Chatter Answers communities.

showInPortals

boolean

Indicates whether Chatter Answers can be added as a tab to your
Customer portal or partner portal (true) or not (false).

Declarative Metadata Sample Definition
The following is an example chatteranswers.settings metadata file:

true
true
true
true
true
true
true
true
true
FacebookAuthProvider
true

The following is an example package.xml manifest that references the ChatterAnswersSettings definitions:

579

Metadata Types

CompanySettings

ChatterAnswers
Settings

29.0

SEE ALSO:
Settings

CompanySettings
Represents global settings that affect multiple features in your organization.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

Declarative Metadata File Suffix and Directory Location
CompanySettings values are stored in a single file named Company.settings in the settings directory of the corresponding
package directory. The .settings files are different from other named components because there is only one settings file for each
settings component.

Version
Company Profile Settings are available in API version 27.0 and later.

Fields
Field Name

Field Type

Description

fiscalYear

FiscalYearSetting

The organization’s fiscal year setting based on year and start
month. Not available if Custom Fiscal Year or Forecasts (Classic)
is enabled. When changing fiscal year settings, quotas and
adjustments can be purged. For example changing your start
month results in purging this data.

FiscalYearSetting
Represents your organization’s fiscal year setting.
Field

Field Type

Description

fiscalYearNameBasedOn

string

This field is used to determine the fiscal year name. Valid values
are endingMonth or startingMonth. For example, if
your fiscal year starts in April 2012 and ends in March 2013, and
this value is:
• endingMonth, then 2013 is used for the fiscal year name.

580

Metadata Types

Field

ContractSettings

Field Type

Description
• startingMonth, then 2012 is used for the fiscal year
name.

startMonth

string

The month on which the fiscal year is based.

Declarative Metadata Sample Definition — Fiscal Year Setting
A sample XML definition of a fiscal year setting is shown below. Note that this example is supported in API version 27.0 and later.

endingMonth
January

SEE ALSO:
Settings

ContractSettings
Represents contract settings. For more information, see “Customize Contracts” in the Salesforce online help.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

File Suffix and Directory Location
There is one contract settings file stored in a file named Contract.settings in the settings directory. The .settings
files are different from other named components because there is only one settings file for each settings component.

Version
ContractSettings is available in API version 27.0 and later.

Fields
Field Name

Field Type

Description

autoCalculateEndDate

boolean

Indicates whether the end date of a contract is automatically calculated
(true) or not (false).

notifyOwnersOnContractExpiration boolean

Indicates whether account and contract owners are automatically sent
email notifications when a contract expires (true) or not (false).

581

Metadata Types

EntitlementSettings

Declarative Metadata Sample Definition
This is a sample contract settings file.

true
false

SEE ALSO:
Settings

EntitlementSettings
Represents an organization’s entitlement settings.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

File Suffix and Directory Location
EntitlementSettings values are stored in the Entitlements.settings file in the settings directory. The .settings files
are different from other named components because there is only one settings file for each settings component.

Version
EntitlementSettings is available in API version 27.0 and later.

Fields
Field Name

Field Type

Description

assetLookupLimitedToActiveEntitlementsOnAccount boolean

Indicates whether entitlements-related lookup filters on
cases return only the assets related to the active
entitlements on the case’s account (true) or not (false).

assetLookupLimitedToActiveEntitlementsOnContact boolean

Indicates whether entitlements-related lookup filters on
cases return only the assets related to the active
entitlements on the case’s contact (true) or not (false).

assetLookupLimitedToSameAccount

boolean

Indicates whether entitlements-related lookup filters on
cases return only the assets related to the case’s account
(true) or not (false).

assetLookupLimitedToSameContact

boolean

Indicates whether entitlements-related lookup filters on
cases return only the assets related to the case’s contact
(true) or not (false).

enableEntitlements

boolean

Indicates whether entitlements are enabled (true) or not
(false).

582

Metadata Types

EntitlementSettings

Field Name

Field Type

Description

enableEntitlementVersioning

boolean

Indicates whether entitlement versioning is enabled
(true) or not (false).
This field is available in API version 28.0 and later.

entitlementLookupLimitedToActiveStatus boolean

Indicates whether entitlements-related lookup filters on
cases return only active entitlements (true) or not
(false).

entitlementLookupLimitedToSameAccount boolean

Indicates whether entitlements-related lookup filters on
cases return only the entitlements related to the case’s
account (true) or not (false).

entitlementLookupLimitedToSameAsset boolean

Indicates whether entitlements-related lookup filters on
cases return only the entitlements related to the case’s
asset (true) or not (false).

entitlementLookupLimitedToSameContact boolean

Indicates whether entitlements-related lookup filters on
cases return only the entitlements related to the case’s
contact (true) or not (false).

Declarative Metadata Sample Definition
This is a sample entitlements settings file.

false

true

false

583

Metadata Types

FileUploadAndDownloadSecuritySettings

false

SEE ALSO:
Settings

FileUploadAndDownloadSecuritySettings
Represents the security settings for uploading and downloading files. This type extends the Metadata metadata type and inherits its
fullName field.

File Suffix and Directory Location
FileUploadAndDownloadSecuritySettings components have the suffix .settings and are stored in the settings folder.

Version
FileUploadAndDownloadSecuritySettings components are available in API version 39.0 and later.

Fields
Field Name

Field Type

Description

dispositions

FileTypeDispositionAssignmentBean[] Represents the metadata used to manage filetype behavior.
This field is available in API version 39.0 and later.

noHtmlUploadAsAttachment boolean

Indicates whether to allow HTML uploads as attachments or
document records. This field is available in API version 39.0 and
later.

FileTypeDispositionAssignmentBean
Represents the metadata used to manage filetype behavior.
Field Name

Field Type

Description

behavior

FileDownloadBehavior
(enumeration of type string)

One of the following values:
• DOWNLOAD
• EXECUTE
• HYBRID
The following filetypes are a security risk and can not have EXECUTE
behavior:
• EXE
• FLASH

584

Metadata Types

Field Name

FileUploadAndDownloadSecuritySettings

Field Type

Description
• HTML
• RFC822
• SVG
• TXML
• UNKNOWN
• WEBVIEW
• XHTML
• XML

filetype

FileType (enumeration of type
string)

Although more filetypes exist, these are the only ones supported
by FileTypeDispositionAssignmentBean:
• AVI
• EXCEL
• EXCEL_X
• EXE
• FLASH
• HTML
• MOV
• MP3
• MP4
• MPEG
• PDF
• POWER_POINT
• POWER_POINT_X
• RFC822
• SVG
• TXML
• UNKNOWN
• WAV
• WEBVIEW
• WMA
• WMV
• WORD
• WORD_X
• XHTML
• XML

securityRiskFileType boolean

Indicates filetypes that cannot have behavior set to EXECUTE, due
to security risks. This field is read-only.

585

Metadata Types

FileUploadAndDownloadSecuritySettings

Declarative Metadata Sample Definition
The following is an example of a FileUploadAndDownloadSecuritySettings component.

HYBRID
AVI
false

HYBRID
WORD
false

HYBRID
WORD_X
false

DOWNLOAD
EXE
true

DOWNLOAD
HTML
true

DOWNLOAD
WEBVIEW
true

DOWNLOAD
RFC822
true

HYBRID
MOV
false

HYBRID
MP3
false

HYBRID
MP4
false

586

Metadata Types

FileUploadAndDownloadSecuritySettings

HYBRID
MPEG
false

HYBRID
PDF
false

HYBRID
POWER_POINT
false

HYBRID
POWER_POINT_X
false

DOWNLOAD
SVG
true

DOWNLOAD
FLASH
true

DOWNLOAD
TXML
true

DOWNLOAD
UNKNOWN
true

HYBRID
WAV
false

HYBRID
WMA
false

HYBRID
WMV
false

587

Metadata Types

ForecastingSettings

DOWNLOAD
XHTML
true

HYBRID
EXCEL
false

HYBRID
EXCEL_X
false

DOWNLOAD
XML
true

false

The following is an example package.xml that references the previous definition.

FileUploadAndDownloadSecurity
Settings

39.0

ForecastingSettings
Represents the Collaborative Forecasts settings options. This type extends the Metadata metadata type and inherits its fullName
field.
Note: This information only applies to Collaborative Forecasts.

File Suffix and Directory Location
ForecastingSettings values are stored in a single file named Forecasting.settings in the settings directory of the
corresponding package directory. The .settings files are different from other named components because there is only one settings
file for each settings component.

Version
ForecastingSettings components are available in API version 28 and later. The structure of the ForecastingSettings type changed
significantly in API version 30.0.

588

Metadata Types

ForecastingSettings

Fields
Field Name

Field Type

Description

displayCurrency

DisplayCurrency
(enumeration of
type string)

The currency for displaying forecasts; either the organization's corporate
currency or each forecast owner's personal currency setting. This is the
default currency used in Collaborative Forecasts and selected in setup.
The selection must be one of the currencies enabled for use in the
organization, and only one selection is allowed. The default is
Corporate. The valid values are:
• Corporate
• Personal

enableForecasts

boolean

Indicates if Collaborative Forecasts is enabled or not. Set to true to
enable Collaborative Forecasts and false to disable the functionality.
Warning: Disabling Forecasts can result in data loss. Refer to
the online Help before disabling any functionality.

forecastingTypeSettings

ForecastingType
Settings[]

A list of forecast types. For field values, see ForecastingTypeSettings. The
maximum number of forecast types is four.

forecastingCategoryMappings ForecastingCategoryMappings[] A list of mappings associating forecast types with forecast rollups.

ForecastingTypeSettings
The settings for each forecast type. An organization can have up to 4 forecast types active. Omitting a previously enabled forecast type
that has a minimum API version less than or equal to the metadata package version deletes its quota and adjustment data from the
organization.
Warning: Omitting a forecast type field from the XML can deactivate that forecast type: if the forecast type was available in the
release specified by the XML package version, that forecast type is deactivated and its quota and adjustment data are deleted.
Field Name

Field Type

Description

active

boolean

This indicates whether the forecast type specified in the name field is
active.
Note: Setting the active field to false purges all forecasting
data, adjustments, and quotas for the forecast type. When
active is set to true, some values on the Forecasts tab may
not appear immediately. An in-process icon appears to indicate
that the values are being calculated.

adjustmentsSettings

AdjustmentsSettings This enables or disables the Forecasts adjustments option in Forecasts.

forecastRangeSettings

ForecastRangeSettings The default periods and range selections in Collaborative Forecasts.

name

string

The name of the forecast type. Each forecast type requires a specific
string.
Valid values include:

589

Metadata Types

Field Name

ForecastingSettings

Field Type

Description
• OpportunityRevenue : Opportunities - Revenue
• OpportunityQuantity : Opportunities - Quantity
• OpportunitySplitRevenue : Opportunity Revenue Splits Revenue
• OpportunityOverlayRevenue : Opportunity Overlay Splits
- Revenue
• OpportunityLineItemRevenue : Product Families Revenue
• OpportunityLineItemQuantity : Product Families Quantity
• The name of a custom opportunity split type that has been enabled
as a forecast type. Custom split types are based on currency fields,
which can contain revenue amounts only.

opportunityListFieldsLabelMappings OpportunityListFieldsLabelMappings A read-only list of the API names and UI labels for all fields on the

Opportunity object.
opportunityListFields
SelectedSettings

OpportunityListFields The fields selected to appear in the opportunity pane of the forecast
SelectedSettings
page for the forecast type. Opportunity Name is required. You
can select up to 15 fields.

opportunityListFields
UnselectedSettings

OpportunityListFields The fields not selected to appear in the opportunity pane of the forecast
UnselectedSettings page for the forecast type.

quotasSettings

QuotasSettings

forecastedCategoryApiNames string

This enables or disables the quota option in Forecasts.
This field appears four times to specify the four forecast rollup categories
used in the organization, for either cumulative forecast rollups, or
individual forecast category rollups.
Valid values for organizations using cumulative forecast rollups:
• openpipeline
• bestcaseforecast
• commitforecast
• closedonly
Valid values for organizations using individual forecast category rollups:
• pipelineonly
• bestcaseonly
• commitonly
• closedonly
Changing from one set of four values to the other changes the
organization setting for Enable Cumulative Forecast Rollups in Setup. If
this field is omitted, the setting is not changed.

590

Metadata Types

ForecastingSettings

Field Name

Field Type

Description

isAmount

boolean

This read-only field indicates whether the forecast type is based on
revenue amounts. The value of isAmount is always the opposite of
the value of isQuantity.

isAvailable

boolean

This read-only field indicates whether the forecast type can currently be
used in the organization. For example, the revenue splits forecast type
can’t be used in an organization that doesn’t have Opportunity Splits
enabled.

isQuantity

boolean

This read-only field indicates whether the forecast type is based on
product quantities. The value of isQuantity is always the opposite
of the value of isAmount.

displayedCategoryApiNames string

This read-only field appears four times to specify the four forecast rollup
categories displayed in the Forecasts tab, for either cumulative forecast
rollups, or individual forecast category rollups. Always use the same 4
values for both displayedCategoryApiNames and
forecastedCategoryApiNames.
Valid values for organizations using cumulative forecast rollups:
• openpipeline
• bestcaseforecast
• commitforecast
• closedonly
Valid values for organizations using individual forecast category rollups:
• pipelineonly
• bestcaseonly
• commitonly
• closedonly

managerAdjustableCategoryApiNames string

This read-only field appears twice to specify the two forecast rollup
categories that forecast managers can adjust in the organization for
either cumulative forecast rollups or individual forecast category rollups.
This field can only be used when the enableAdjustments field
contains a value of true. If both the
managerAdjustableCategoryApiNames and
ownerAdjustableCategoryApiNames fields are being used,
they must contain the same two values. Their values must also be
consistent with the values of the enableAdjustments and
enableOwnerAdjustments fields.
Valid values for organizations using cumulative forecast rollups:
• bestcaseforecast
• commitforecast
Valid values for organizations using individual forecast category rollups:
• bestcaseonly

591

Metadata Types

Field Name

ForecastingSettings

Field Type

Description
• commitonly

masterLabel

string

ownerAdjustableCategoryApiNames string

This read-only field indicates the UI label for the forecast type.
This read-only field appears twice to specify the two forecast rollup
categories that forecast owners can adjust in the organization, for either
cumulative forecast rollups, or individual forecast category rollups. This
field can only be used when the enableOwnerAdjustments field
contains a value of true. If both the
managerAdjustableCategoryApiNames and
ownerAdjustableCategoryApiNames fields are being used,
they must contain the same two values. Their values must also be
consistent with the values of the enableAdjustments and
enableOwnerAdjustments fields.
Valid values for organizations using cumulative forecast rollups:
• bestcaseforecast
• commitforecast
Valid values for organizations using individual forecast category rollups:
• bestcaseonly
• commitonly

AdjustmentsSettings
The adjustment options for Collaborative Forecasts.
Field

Field Type

Description

enableAdjustments

boolean

Set to true to enable Collaborative Forecasts manager
adjustments and false to disable them. All forecast types
must contain the same enableAdjustments value.
Warning: Disabling adjustments results in Collaborative
Forecasts adjustment data being purged.

enableOwnerAdjustments boolean

Set to true to enable Collaborative Forecasts owner
adjustments and false to disable them. All forecast types
must contain the same enableAdjustments value.
Warning: Disabling adjustments results in Collaborative
Forecasts adjustment data being purged.

ForecastRangeSettings
The default periods and range selections in Collaborative Forecasts. Users can forecast up to 12 months or eight quarters in the future
or past. If your forecast range includes the current month or quarter, the forecasts page displays the current month or quarter by default.

592

Metadata Types

ForecastingSettings

If not, the first month or quarter of the range is selected. All forecast types must contain the same forecastRangeSettings field
values.
Warning: If you change the time period from monthly to quarterly or quarterly to monthly, or you change the standard fiscal
year, all adjustments and quotas are purged. If you enable custom fiscal years, creating the first custom fiscal year deletes any
quotas and adjustments in the corresponding and subsequent standard fiscal years. These changes trigger a forecast recalculation
that can take significant time, depending on the quantity of your data.
Field

Field Type

Description

beginning

int

Indicates the beginning month or quarter to display by default.

displaying

int

Indicates the number of months or quarters to display by default.
The maximum number of months is 12 and quarters is 8.

periodType

PeriodTypes (enumeration of
type string)

Indicates what type of period to use. Valid values are:
• Month
• Quarter

OpportunityListFieldsLabelMappings
A read-only list of the API names and UI labels for all fields on the Opportunity object.
Field

Field Type

Description

field

string

The API name of the Opportunity field.

label

string

The UI label of the Opportunity field.

OpportunityListFieldsSelectedSettings
The fields selected to appear in the opportunity pane of the forecast page for the forecast type. Opportunity Name is required.
You can select up to 15 fields.
Field

Field Type

Description

field

string

Specifies names of fields to display in the opportunity pane.

OpportunityListFieldsUnselectedSettings
The fields not selected to appear in the opportunity pane of the forecast page for the forecast type.
Field

Field Type

Description

field

string

Specifies names of fields not displayed in the opportunity pane.

QuotasSettings
QuotasSettings indicates if quotas are available in Collaborative Forecasts.

593

Metadata Types

ForecastingSettings

Field

Field Type

Description

showQuotas

boolean

Set to true to enable quotas. All forecast types must contain
the same showQuotas field value.

ForecastingCategoryMappings
The forecasting category mappings for Collaborative Forecasts. This subtype appears eight times within the ForecastingSettings
type. Each occurrence includes fields that specify a type of forecast category rollup, which forecast categories each rollup includes, and
the weight of each forecast category in the rollup. Organizations using either cumulative forecast rollups or individual forecast category
columns must include all eight occurrences of this subtype.
Field

Field Type

Description

forecastingItemCategoryApiName string

This field specifies the API name of the rollup type. The valid
values are:
• openpipeline
• bestcaseforecast
• commitforecast
• pipelineonly
• bestcaseonly
• commitonly
• closedonly
• omittedonly

weightedSourceCategories WeightedSourceCategories[]

This field can occur more than once when specifying more than
one forecast category to include in the rollup type. Each
occurrence contains two subfields that specify a forecast
category to include in the forecast rollup type and its weight.
Some rollup types include more than one forecast category. This
list shows the forecast categories that are included in each rollup
type.
• Rollup: openpipeline, Forecast categories: pipeline, best
case, commit
• Rollup: bestcaseforecast, Forecast categories: best case,
commit, closed
• Rollup: commitforecast, Forecast categories: commit, closed
• Rollup: pipelineonly, Forecast categories: pipeline
• Rollup: bestcaseonly, Forecast categories: best case
• Rollup: commitonly, Forecast categories: commit
• Rollup: closedonly, Forecast categories: closed
• Rollup: omittedonly, Forecast categories: omitted

594

Metadata Types

ForecastingSettings

WeightedSourceCategories
This field can occur more than once when specifying more than one forecast category to include in the rollup type. Each occurrence
contains two subfields that specify a forecast category to include in the forecast rollup type and its weight. Some rollup types include
more than one forecast category. This table shows the forecast categories that are included in each rollup type.
Field

Field Type

Description

sourceCategoryApiName

string

Specifies the API name of a forecast category to include in the
rollup type. The valid values are.
• pipeline
• best case
• commit
• closed
• omitted

weight

double

Specifies the weight given to the forecast category when
calculating the forecast for the rollup type. The only supported
value is 1.0.

Declarative Metadata Sample Definition
The following is an example of a ForecastingSettings component that enables the Opportunity-Revenue and Product Family-Quantity
forecast types:

true

OpportunityRevenue

0
6
Month

OPPORTUNITY.NAME

true

false

595

Metadata Types

ForecastingSettings

true

OpportunityLineItemQuantity

0
6
Month

OPPORTUNITY.NAME

true

pipelineonly
bestcaseonly
commitonly
closedonly
commitonly
closedonly
bestcaseonly
pipelineonly
commitonly
bestcaseonly
commitonly
bestcaseonly

commitonly

commit
1.0

closedonly

closed
1.0

bestcaseforecast

commit
1.0

best case
1.0

596

Metadata Types

ForecastingSettings

closed
1.0

omittedonly

omitted
1.0

openpipeline

commit
1.0

best case
1.0

pipeline
1.0

bestcaseonly

best case
1.0

commitforecast

closed
1.0

commit
1.0

pipelineonly

pipeline
1.0

597

Metadata Types

IdeasSettings

SEE ALSO:
Settings

IdeasSettings
Represents the metadata used to manage settings for Ideas.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

File Suffix and Directory Location
IdeasSettings is stored in one file named Ideas.settings in the settings folder of the corresponding package directory. The
.settings files are different from other named components because there is only one settings file for each settings component.

Version
IdeasSettings is available in API version 27.0 and later.

Ideas
Represents settings for Ideas and Idea Themes.

Fields
Field Name

Field Type

Description

enableIdeaThemes

boolean

Indicates whether Idea Themes is enabled (true) or not (false).

enableIdeas

boolean

Indicates whether Ideas is enabled (true) or not (false).

enableIdeasReputation

boolean

Indicates whether Reputation is enabled (true) or not (false). You
can’t enable IdeasReputation without enabling the Ideas Reputation
permission in your organization. This field is available in API version 28.0
and later.

enableChatterProfile

boolean

Indicates that the Chatter user profile is used for Ideas user profiles. If
enableChatterProfile is true, the ideasProfilePage
value must not be specified. If enableChatterProfile is false,
then specify a ideasProfilePage value, otherwise the Ideas zone
profile is used. This field is available in API version 29.0 and later.

ideasProfilePage

string

The name of the Visualforce page to use for a custom Ideas user profile,
if enableChatterProfile is false. If
enableChatterProfile is false, then specify a
ideasProfilePage value, otherwise the Ideas zone profile is used.
This field is available in API version 29.0 and later.

598

Metadata Types

KnowledgeSettings

Field Name

Field Type

Description

halfLife

double

Indicates how quickly old ideas drop in ranking on the Popular Ideas
subtab. The half-life setting determines how the number of days after
which old ideas drop in ranking on the Popular Ideas subtab, to make
room for ideas with more recent votes. A shorter half-life moves older
ideas down the page faster than a longer half-life.

Declarative Metadata Sample Definition
The following is an example ideas.settings metadata file:

true
true
true
false
name of Visualforce page
2.6

SEE ALSO:
Settings

KnowledgeSettings
Represents the metadata used to manage settings for Salesforce Knowledge.
This type extends the Metadata metadata type and inherits its fullName field.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

File Suffix and Directory Location
KnowledgeSettings values are stored in a single file named Knowledge.settings in the settings directory. The .settings
files are different from other named components because there is only one settings file for each settings component.

Version
KnowledgeSettings is available in API version 27.0 and later.

Fields
Field Name

Field Type

Description

answers

KnowledgeAnswerSettings

Represents the metadata used to manage settings
for Salesforce Knowledge and Answers.

599

Metadata Types

KnowledgeSettings

Field Name

Field Type

Description

cases

KnowledgeCaseSettings

Represents the metadata used to manage settings
for Salesforce Knowledge and Cases.

defaultLanguage

string

Required. The default language for Salesforce
Knowledge. Use the abbreviation for the
language, for example, en_US for United States
English.

languages

KnowledgeLanguageSettings

A list of languages enabled for Salesforce
Knowledge.

enableChatterQuestionKBDeflection boolean

Indicates whether tracking for case deflection via
Chatter is enabled (true) or not (false).

enableCreateEditOnArticlesTab boolean

Indicates whether users can create and edit
articles on the articles tab (true) or not
(false).

enableExternalMediaContent

boolean

Indicates whether connecting to external media
is enabled (true) or not (false).

enableKnowledge

boolean

Indicates whetherSalesforce Knowledge is
enabled (true) or not (false).

showArticleSummariesCustomerPortal boolean

Indicates whether article summaries appear in
the Customer Portal (true) or not (false).

showArticleSummariesInternalApp boolean

Indicates whether article summaries appear in
the internal knowledge base (true) or not
(false).

showArticleSummariesPartnerPortal boolean

Indicates whether article summaries appear in
the partner portal (true) or not (false).

showValidationStatusField

boolean

Indicates whether validation status appears on
articles (true) or not (false).

suggestedArticles

KnowledgeSuggestedArticlesSettings Represents the metadata used to manage settings
for the case fields used to suggest articles for
cases. Available in API version 37.0 and later.

KnowledgeAnswerSettings
Represents the metadata used to manage settings for Salesforce Knowledge and Answers.
Field Name

Field Type

Description

assignTo

string

Specifies the username an article is assigned to from Answers.

defaultArticleType

string

The default article type for articles created from Answers. Uses the API
name of the article type.

600

Metadata Types

KnowledgeSettings

Field Name

Field Type

Description

enableArticleCreation

boolean

Indicates whether users can create articles from Answers (true) or not
(false).

KnowledgeCaseField
Represents the name of the case field used to suggest articles for the case. Available in API version 37.0 and later.
Field Name

Field Type

Description

name

string

Specifies the name of the case field used to suggest
articles for the case.

KnowledgeCaseFieldsSettings
Represents a list of the case fields used to suggest articles for the case. Available in API version 37.0 and later.
Field Name

Field Type

Description

field

KnowledgeCaseField[]

Specifies the names of the case fields used to suggest
articles for the case.

KnowledgeWorkOrderField
Represents the name of the work order field used to suggest articles for the work order. Available in API version 39.0 and later.
Field Name

Field Type

Description

name

string

Specifies the name of the work order field used to
suggest articles for the work order.

KnowledgeWorkOrderFieldsSettings
Represents a list of the work order fields used to suggest articles for the work order. Available in API version 39.0 and later.
Field Name

Field Type

Description

field

KnowledgeWorkOrderField[]

Specifies the names of the work order fields used to
suggest articles for the work order.

KnowledgeWorkOrderLineItemField
Represents the name of the work order line item field used to suggest articles for the work order line item. Available in API version 39.0
and later.

601

Metadata Types

KnowledgeSettings

Field Name

Field Type

Description

name

string

Specifies the name of the work order line item field
used to suggest articles for the work order line item.

KnowledgeWorkOrderLineItemFieldsSettings
Represents a list of the work order line item fields used to suggest articles for the work order line item. Available in API version 39.0 and
later.
Field Name

Field Type

Description

field

KnowledgeWorkOrderLineItemField[]

Specifies the names of the work order line item fields
used to suggest articles for the work order line item.

KnowledgeSuggestedArticlesSettings
Represents the metadata used to manage settings for the articles suggested for cases, work orders, and work order line items.
Field Name

Field Type

Description

caseFields

KnowledgeCaseFieldsSettings

Represents a list of the case fields used to suggest
articles for the case.

useSuggestedArticlesForCase boolean

workOrderFields

Indicates whether case content is used to suggest
articles for cases (true) or not (false).

KnowledgeWorkOrderFieldsSettings

Represents a list of the work order fields used to
suggest articles for the work order.

workOrderLineItemFields KnowledgeWorkOrderLineItemFieldsSettings Represents a list of the work order line item fields used

to suggest articles for the work order line item.

KnowledgeCaseSettings
Represents the metadata used to manage settings for Salesforce Knowledge and Cases.
Field Name

Field Type

Description

articlePDFCreationProfile

string

The profile used to create a PDF of an article from
Cases.

articlePublicSharingSites

KnowledgeSitesSettings

Represents the metadata used to manage settings
for Salesforce Knowledge and Sites.

articlePublicSharingCommunities KnowledgeSitesSettings

Represents the metadata used to manage settings
for Salesforce Knowledge and Communities.

articlePublicSharingSitesChatterAnswers KnowledgeSitesSettings

Represents the metadata used to manage settings
for Salesforce Knowledge and Sites with Chatter
Answers.

602

Metadata Types

KnowledgeSettings

Field Name

Field Type

Description

assignTo

string

Specifies the username an article is assigned to from
Cases.

customizationClass

string

Specifies the Apex class used for customization.

defaultContributionArticleType

string

The default article type for articles created from
Cases.

editor

KnowledgeCaseEditor
(enumeration of type string)

Indicates the rich text editor type. Valid values are:
• simple
• standard

boolean

Indicates whether users can create articles from
Cases (true) or not (false). Controls whether
other fields on KnowledgeCaseSettings can be set.

enableArticlePublicSharingSites boolean

Indicates whether articles can be shared via a public
site (URL) from Cases (true) or not (false).

boolean

Indicates whether a profile is used to create a PDF
of an article from Cases (true) or not (false).

enableArticleCreation

useProfileForPDFCreation

KnowledgeSitesSettings
Represents the metadata used to manage settings for Salesforce Knowledge and Sites.
Field Name

Field Type

Description

site

string[]

Specifies the site used for Salesforce Knowledge and Sites.

KnowledgeLanguageSettings
A list of languages enabled for Salesforce Knowledge. KnowledgeLanguageSettings is available in API version 28.0 and later.
Field Name

Field Type

Description

language

KnowledgeLanguage

Represents the metadata used to manage settings for
the languages enabled for Salesforce Knowledge.

KnowledgeLanguage
Represents the metadata used to manage settings for the languages enabled for Salesforce Knowledge. KnowledgeLanguage is available
in API version 28.0 and later.
Field Name

Field Type

Description

active

boolean

Indicates whether the language is enabled (true) or
not (false).

603

Metadata Types

KnowledgeSettings

Field Name

Field Type

Description

defaultAssignee

string

The default assignee for articles in the language.

defaultAssigneeType

KnowledgeLanguageLookupValueType
(enumeration of type string)

Indicates the default assignee type. Valid values are:
• user
• queue

defaultReviewer

string

The default reviewer for articles in the language.

defaultReviewerType

KnowledgeLanguageLookupValueType
(enumeration of type string)

Indicates the default reviewer type. Valid values are:
• user
• queue

name

string

The code for the language name, for example: English
is en. See “What languages does Salesforce support?”
in the Salesforce online help for a list of supported
languages and their codes.

Declarative Metadata Sample Definition
This is a sample Knowledge settings file.

false

partner portal knowledge
profile

KnowledgeSite
PKB2Site
ChatterAnswersSite

ChatterAnswersSite

testall@kb.org
Support
simple
true
true
true

ja
true
true
true
true
true

604

Metadata Types

LeadConvertSettings

true
true

Subject

SuppliedEmail

true

SEE ALSO:
Settings

LeadConvertSettings
Represents an organization’s custom field mappings for lead conversion. Custom fields can be mapped from Leads to Accounts, Contacts,
and Opportunities. Options for creating opportunities during lead conversion can also be specified. This type extends the Metadata
metadata type and inherits its fullName field.

Version
LeadConvertSettings is available in API versions 39.0 and later.

Fields
Field Name

Field Type

Description

allowOwnerChange

boolean

Indicates whether to include the RecordOwner field in the Convert Lead
dialog box (true) or not (false).

objectMapping

metadata type

A set of inputObject, mappingFields, and outputObject
entries. Up to three objectMapping types can be declared—one
each for Account, Contact, and Opportunity.

inputObject

string

The name of the object type containing the source fields for mapping.
The value will always be Lead.

mappingFields

metadata type

A set of inputField and outputField entries.

inputField

string

The name of a custom lead field supplying source data during lead
conversion.

outputField

string

The name of a custom account, contact, or opportunity field that will
receive data from source field named in the accompanying
inputField entry.

605

Metadata Types

LeadConvertSettings

Field Name

Field Type

Description

outputObject

string

The name of the object type receiving data during lead
conversion—Account, Contact, or Opportunity.

opportunityCreationOptions string

This optional field determines whether the Opportunity field is visible
or required in the Convert Lead dialog box. Valid values include:
• VisibleOptional—The Opportunity field is included in the
dialog box but not required. A new opportunity is created if the user
enters an opportunity name. This is the default value.
• VisibleRequired—The Opportunity field is included in the
dialog box and is required. A new opportunity is created based on
the name entered by the user.
• NotVisible—The Opportunity field is not included in the dialog
box. No opportunity is created.

Declarative Metadata Sample Definition
The following is an example of the LeadConvertSettings type:

false

Lead

custom_lead_field_1
custom_account_field_1

custom_lead_field_2
custom_account_field_2

custom_lead_field_3
custom_account_field_3

Account

Lead

custom_lead_field_4
custom_opportunity_field_1

Opportunity

VisibleOptional

606

Metadata Types

LiveAgentSettings

LiveAgentSettings
Represents an organization’s Live Agent settings, such as whether or not Live Agent is enabled. This type extends the Metadata metadata
type and inherits its fullName field.

File Suffix and Directory Location
LiveAgentSettings values are stored in the LiveAgent.settings file in the settings directory. The .settings files are
different from other named components because there is only one settings file for each settings component.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

Version
LiveAgentSettings is available in API version 28.0 and later.

Fields
Field Name

Field Type

Description

enableLiveAgent

boolean

Indicates whether Live Agent is enabled (true) or not
(false).

Declarative Metadata Sample Definition
This is a sample Live Agent settings file.

true

MobileSettings
Represents an organization’s mobile settings. For more information, see “Manage Salesforce Mobile Classic Devices” in the Salesforce
online help.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

Declarative Metadata File Suffix and Directory Location
MobileSettings values are stored in a single file named Mobile.settings in the settings directory. The .settings files
are different from other named components because there is only one settings file for each settings component.
Note: MobileSettings is no longer available in API versions 25.0 and 26.0.

Version
Mobile settings are available in API version 27.0 and later.

607

Metadata Types

MobileSettings

Fields
Field

Field Type

Description

chatterMobile (Deprecated)

ChatterMobileSettings

The settings for devices running Chatter
mobile.

dashboardMobile (Deprecated)

DashboardMobileSettings

The settings for devices running the mobile
dashboards app.

salesforceMobile

SFDCMobileSettings

The settings for devices running Salesforce
Classic Mobile.

touchMobile (Deprecated)

TouchMobileSettings

The settings for devices running Salesforce
Touch.

ChatterMobileSettings
These fields are deprecated. Represents your organization’s Chatter Mobile settings.
Field

Field Type

Description

IPadAuthorized

boolean

Indicates whether iPad devices are enabled
for Chatter Mobile (true) or not (false).

IPhoneAuthorized

boolean

Indicates whether iPhone devices are
enabled for Chatter Mobile (true) or not
(false).

androidAuthorized

boolean

Indicates whether Android devices are
enabled for Chatter Mobile (true) or not
(false).

blackBerryAuthorized

boolean

Indicates whether Blackberry devices are
enabled for Chatter Mobile (true) or not
(false).

enableChatterMobile

boolean

Indicates whether Chatter Mobile has been
enabled for your organization (true) or
not (false).
Note: Setting this to true enables
you to set all of the other settings. If
you change this setting from true
to false, and also try to change
any of the other ChatterMobile
settings, your deploy will fail with an
error.

enablePushNotifications

boolean

Indicates whether Chatter push notifications
have been enabled for your organization
(true) or not (false)

608

Metadata Types

MobileSettings

Field

Field Type

Description

sessionTimeout

MobileSessionTimeout (enumeration of type The length of time after which users without
string)
activity are prompted to log out or continue
working. Valid values are:
• Never
• OneMinute
• FiveMinutes
• TenMinutes
• ThirtyMinutes

DashboardMobileSettings
These fields are deprecated. Represents your organization’s Mobile Dashboards iPad app settings.
Field

Field Type

Description

enableDashboardIPadApp

boolean

Indicates whether Mobile Dashboards iPad
app has been enabled for your organization
(true) or not (false)

SFDCMobileSettings
Represents your organization’s Salesforce Classic Mobile app settings.
Field

Field Type

Description

enableUserToDeviceLinking

boolean

Permanently link users to their mobile
devices. Set this option to true only if you
want to prevent your users from switching
devices without administrative intervention..

enableMobileLite

boolean

Indicates whether your organization has the
free version of Salesforce Mobile Classic
enabled (true) or not (false).
Note that the free version of Salesforce
Mobile Classic is available only for orgs that
turned on this option prior to Summer ’16.

TouchMobileSettings
These fields are deprecated. Salesforce Touch has been upgraded to the Salesforce1 app.

609

Metadata Types

NameSettings

Field

Field Type

Description

enableTouchBrowserIPad

boolean

Indicates whether your organization has the
Salesforce Touch mobile browser app
enabled (true) or not (false).

enableTouchAppIPad

boolean

Indicates whether your organization has the
Salesforce Touch downloadable app
enabled (true) or not (false)

Declarative Metadata Sample Definition
This is a sample mobile.settings metadata file.

true
true
true
true
true
true
Never

true

false
false

false
true

SEE ALSO:
Settings

NameSettings
Enables or disables middle name and suffix attributes for the following person objects: Contact, Lead, Person Account, and User.

File Suffix and Directory Location
NameSettings values are stored in a single file named Name.settings in the settings folder. The .settings files are
different from other named components because there is only one settings file for each settings component.

610

Metadata Types

OpportunitySettings

Version
NameSettings components are available in API version 31.0 and later.

Fields
Field Name

Field Type

Description

enableMiddleName

boolean

Indicates whether middle names are enabled (true) or disabled
(false) for person objects.

enableNameSuffix

boolean

Indicates whether suffixes are enabled (true) or disabled (false) for
person objects.

Declarative Metadata Sample Definition
The following is an example of a NameSettings component.

true
false

The following is an example package.xml manifest that references the NameSettings definitions.

Name
Settings

31.0

OpportunitySettings
Represents organization preferences for features such as automatic opportunity updates and similar-opportunity filters. This type extends
the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location
Opportunities values are stored in a single file named Opportunity.settings in the settings directory of the corresponding
package directory. The .settings files are different from other named components because there is only one settings file for each
settings component.

Version
OpportunitySettings is available in API version 28.0 and later.

611

Metadata Types

OpportunitySettings

Fields
Field Name

Field Type

Description

enableUpdateReminders

boolean

Lets users enable automatic, scheduled updates on opportunities.

autoActivateNewReminders boolean

Automatically uses scheduled updates for new opportunities.

enableFindSimilarOpportunities boolean

Lets users see related or similar existing opportunities.

findSimilarOppFilter

multipicklist

Defines parameters for similar opportunities.

enableOpportunityTeam

boolean

Lets users associate team members with opportunities.

promptToAddProducts

boolean

Prompts users to add related products to an opportunity.

FindSimilarOppFilter
Defines whether to match by entire columns or fields.
Field

Field Type

Description

similarOpportunitiesDisplayColumns string

The columns to compare.

similarOpportunitiesMatchFields string

The fields to compare.

Declarative Metadata Sample Definition
The following is an example of the package file.

Opportunity
Settings

28.0

The package file references the following Opportunity.settings file.

true
true

OPPORTUNITY.Account
OPPORTUNITY.OpportunityCompetitors
CustomField__c

612

Metadata Types

OrderSettings

CustomField__c

true
true
false

OrderSettings
Represents order settings. This type extends the Metadata metadata type and inherits its fullName field. For more information, see
“Customize Order Settings” in the Salesforce Help.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

File Suffix and Directory Location
There is one OrderSettings component in a file named Order.settings in the settings folder. The .settings files are
different from other named components because there is only one settings file for each settings component.

Version
OrderSettings components are available in API version 30.0 and later.

Fields
Field Name

Field Type

Description

enableNegativeQuantity

boolean

Indicates whether users in the organization can add order products with
quantities of less than zero (true) or not (false).
To enable this preference, enableOrders must be set to true.

enableOrders

boolean

Indicates whether orders are enabled for the organization (true) or
not (false).

enableReductionOrders

boolean

Indicates whether reduction orders are enabled for the organization
(true) or not (false). For more information, see “Reduction Orders”
in the Salesforce Help.
To enable this preference, enableOrders must be set to true.

Declarative Metadata Sample Definition
This is a sample OrderSettings component.

true
false

613

Metadata Types

OrgPreferenceSettings

true

The following is an example package.xml that references the previous definition.

Order
Settings

30.0

OrgPreferenceSettings
Represents the unique org preference settings in a Salesforce org. This type extends the Metadata metadata type and inherits its
fullName field.

File Suffix and Directory Location
OrgPreferenceSettings values are stored in the OrgPreference.settings file in the settings directory. The .settings files
are different from other named components because there is only one settings file for each settings component.

Version
OrgPreferenceSettings components are available in API version 37.0 and later.

Fields
Field Name

Field Type

Description

preferences

OrganizationSettingsDetail[] The preferences associated with the org settings. Possible values are:
• ChatterEnabled
• EnhancedEmailEnabled
• EventLogWaveIntegEnabled
• LoginForensicsEnabled
• NotesReservedPref01
• OfflineDraftsEnabled
• PathAssistantsEnabled
• S1DesktopEnabled
• S1EncryptedStoragePref2
• S1OfflinePref
• SendThroughGmailPref
• SocialProfilesEnable
• VoiceEnabled

614

Metadata Types

OrgPreferenceSettings

OrganizationSettingsDetail
Field Name

Field Type

Description

settingName

string

The name of the setting. For example,
“S1EncryptedStoragePref2.”

setttingValue

boolean

Indicates whether the setting is enabled
(true) or not (false).

Declarative Metadata Sample Definition
The following is an example of a OrgPreferenceSettings component.

EventLogWaveIntegEnabled
true

SendThroughGmailPref
false

LoginForensicsEnabled
false

EnhancedEmailEnabled
true

NotesReservedPref01
false

S1OfflinePref
true

S1EncryptedStoragePref2
true

OfflineDraftsEnabled
false

ChatterEnabled
true

615

Metadata Types

PathAssistantSettings

SocialProfilesEnable
true

PathAssistantsEnabled
false

S1DesktopEnabled
true

VoiceEnabled
false

PathAssistantSettings
Represents the Path preference setting. This type extends the Metadata metadata type and inherits its fullName field.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

File Suffix and Directory Location
PathAssistantSettings components have the suffix .settings and are stored in the settings folder.

Version
PathAssistantSettings components are available in API version 34.0 and later.

Fields
Field Name

Field Type

Description

pathAssistantForOpportunityEnabled boolean

Determines whether the preference is enabled for Path in Opportunity
or not. Available in API version 34.0 only.

boolean

Determines whether the preference is enabled for Path or not. Available
in API version 35.0 and later.

pathAssistantEnabled

Declarative Metadata Sample Definition
The following is an example of a PathAssistantSettings component.

true

616

Metadata Types

PersonalJourneySettings

The following is an example package.xml that references the previous definition.

PathAssistant
Settings

API

Product
Settings

28.0

The package file references the following Product.settings file.

true
false
false

QuoteSettings
Enables or disables Quotes, which show proposed prices for products and services. This type extends the Metadata metadata type and
inherits its fullName field.

618

Metadata Types

SearchSettings

File Suffix and Directory Location
QuoteSettings values are stored in a single file named Quote.settings in the settings directory of the corresponding package
directory. The .settings files are different from other named components because there is only one settings file for each settings
component.

Version
QuoteSettings is available in API version 28.0 and later.

Fields
Field Name

Field Type

Description

enableQuote

boolean

When set to true, users can access Quotes.

Declarative Metadata Sample Definition
The following is an example of the package file.

Quote
Settings

28.0

The package file references the following Quote.settings file.

true

SearchSettings
Represents an org's search settings.
This type extends the Metadata metadata type and inherits its fullName field.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

File Suffix and Directory Location
SearchSettings values are stored in a single file named Search.settings in the settings folder. The .settings files are
different from other named components because there is only one settings file for each settings component.

619

Metadata Types

SearchSettings

Version
SearchSettings is available in API version 37.0 and later.

Fields
Field Name

Field Type

Description

documentContentSearchEnabled

boolean

Indicates if a full-text document search is performed.

optimizeSearchForCJKEnabled

boolean

Indicates whether the search is optimized for the Japanese,
Chinese, and Korean languages. This setting affects sidebar
search and the account search for Find Duplicates on a lead
record in sidebar search and global search. Enable this option
if users are searching mostly in Japanese, Chinese, or Korean,
and if the text in searchable fields is mostly in those languages.

recentlyViewedUsersForBlankLookupEnabled boolean

Indicates whether the list of records that are returned from a
user autocomplete lookup and from a blank user lookup is
taken from the user’s recently viewed user records. Otherwise
this setting is false if the lookup shows a list of recently
accessed user records from across your org (false). Only
applies to User object blank lookup searches.

searchSettingsByObject

SearchSettingsByObject Represents a list of search settings for each object.

sidebarAutoCompleteEnabled

boolean

Indicates if autocomplete is enabled for sidebar search.
Autocomplete is when users start typing search terms and
sidebar search displays a matching list of recently viewed
records.

sidebarDropDownListEnabled

boolean

Indicates if a drop-down list appears in the sidebar search
section. From this list, users can select to search within tags,
within a specific object, or across all objects.

sidebarLimitToItemsIOwnCheckboxEnabled boolean

Indicates if the Limit to Items I Own checkbox appears. The
checkbox allows your users to include only records for which
they are the record owner when entering search queries in
the sidebar.

singleSearchResultShortcutEnabled boolean

Indicates if a shortcut is enabled. With the shortcut, users skip
the search results page and go directly to the record’s detail
page when their search returns only a single item. This setting
doesn't apply to tags, case comments (in advanced search),
and global search.

spellCorrectKnowledgeSearchEnabled boolean

Indicates if spell check is enabled for Knowledge search.

SearchSettingsByObject
Includes ObjectSearchSetting field type, which is a list of search settings for each object.

620

Metadata Types

SearchSettings

Field Name

Field Type

Description

searchSettingsByObject

ObjectSearchSetting Contains a list of search settings for each object.

ObjectSearchSetting
A list of search settings for each object.
Field Name

Field Type

Description

enhancedLookupEnabled

boolean

Indicates if enhanced lookups is enabled for the object.

lookupAutoCompleteEnabled boolean

Indicates if autocomplete is enabled for lookup search. Autocomplete
is when users edit the lookup field inline by choosing an autosuggestion.

name

string

The entity name of the object being configured.

resultsPerPageCount

int

The number of search results per page.

Declarative Metadata Sample Definition
The following is an example of the Search.settings file.

true
true
true

false
false
Account
25

false
false
Activity
25

false
false
Asset
25

true
true
true

621

Metadata Types

SecuritySettings

true
true

Example Package Manifest
The following is an example package manifest used to deploy or retrieve the Account settings metadata for an organization.

Search
Settings

37.0

SecuritySettings
Represents an organization’s security settings. Security settings define trusted IP ranges for network access, password and login
requirements, and session expiration and security settings.
In the package manifest, all organization settings metadata types are accessed using the “Settings” name. See Settings for more details.

Declarative Metadata File Suffix and Directory Location
SecuritySettings values are stored in a single file named Security.settings in the settings directory. The .settings
files are different from other named components because there is only one settings file for each settings component.
Note: SecuritySettings is no longer available in API versions 25.0 and 26.0.

Version
Security settings are available in API version 27.0 and later.

Fields
Field Name

Field Type

Description

networkAccess

NetworkAccess

The trusted IP address ranges from which users can always log
in without requiring computer activation.

passwordPolicies

PasswordPolicies

The requirements for passwords and logins, and assistance with
retrieving forgotten passwords.

sessionSettings

SessionSettings

The settings for session expiration and security.

622

Metadata Types

SecuritySettings

NetworkAccess
Represents your organization’s trusted IP address ranges for network access.
Field

Field Type

Description

ipRanges

IpRange[]

The trusted IP address ranges from which users can always log
in without requiring computer activation.
Note: In order to add an IP range, deploy all existing IP
ranges, as well as the one you want to add. Otherwise,
the existing IP ranges are replaced with the ones you
deploy. To remove all the IP ranges in an organization,
leave the networkAccess field blank
().

IpRange
Defines a range of trusted IP addresses for network access.
Field

Field Type

Description

description

string

The description of the trusted IP range. Use this field to identify
the range, such as which corporate network corresponds to this
range. This field is available in API version 34.0 and later.

end

string

The IP address that defines the high end of a range of trusted
addresses.

start

string

The IP address that defines the low end of a range of trusted
addresses.

PasswordPolicies
Represents your organization’s password and login policies.
Field

Field Type

Description

apiOnlyUserHomePageURL string

complexity

The URL to which users with the “API Only User” permission are
redirected instead of the login page.

Complexity (enumeration of
type string)

Required. The requirement for which types of characters must
be used in a user’s password. Valid values are:
• NoRestriction—allows any password value and is
the least secure option.
• AlphaNumeric—requires at least one alphabetic
character and one number. This value is the default value.
• SpecialCharacters—requires at least one alphabetic
character, one number, and one of the following special
characters: ! # $ % - _ = + < >.

623

Metadata Types

Field

SecuritySettings

Field Type

Description
• UpperLowerCaseNumeric—requires at least one
number, one uppercase letter, and one lowercase letter.
This value is available in API version 31.0 and later.
• UpperLowerCaseNumericSpecialCharacters—requires
at least one number, one uppercase letter, and one
lowercase letter, and one of the following special characters:
! # $ % - _ = + < >. This value is available in API
version 31.0 and later.

expiration

Expiration (enumeration of type Required. The length of time until user passwords expire and
string)
must be changed. Valid values are:
• Never
• ThirtyDays
• SixtyDays
• NinetyDays. This value is the default value.
• SixMonths
• OneYear

minimumPasswordLifetime boolean

passwordAssistanceURL

Indicates whether a one-day minimum password lifetime is
required (true) or not (false). This field is available in API
version 31.0 and later.

string

The URL that users can click to retrieve forgotten passwords.

passwordAssistanceMessage string

The text that appears in the Account Lockout email and at the
bottom of the Confirm Identity screen for users resetting their
passwords.

historyRestriction

string

Required. The number of previous passwords saved for users so
that they must always reset a new, unique password. Valid values
are 0 through 24 passwords remembered. The maximum
value of 24 applies to API version 31.0 and later. In earlier
versions, the maximum value is 16. The default value is 3.

lockoutInterval

LockoutInterval (enumeration
of type string)

Required. The duration of the login lockout. Valid values are:
• FifteenMinutes. This value is the default value.
• ThirtyMinutes
• SixtyMinutes
• Forever (must be reset by admin)

maxLoginAttempts

MaxLoginAttempts
(enumeration of type string)

Required. The number of login failures allowed for a user before
they become locked out. Valid values are:
• NoLimit
• ThreeAttempts
• FiveAttempts

624

Metadata Types

Field

SecuritySettings

Field Type

Description
• TenAttempts. This value is the default value.

minimumPasswordLength

string

Required. The minimum number of characters required for a
password. Valid values are from 5 to 50. The default value is 8.
This field is available in API version 35.0 and later.
Before API version 35.0, specify minimum password length with
the enumeration minPasswordLength, with valid values
FiveCharacters, EightCharacters (default),
TenCharacters, TwelveCharacters (API version
31.0 and later), and FifteenCharacters ( API version
34.0 and later).

obscureSecretAnswer

boolean

Hides the secret answer associated with a password (true) or
not (false).
Note: If your org uses the Microsoft Input Method Editor
(IME) with the input mode set to Hiragana, when you
type ASCII characters, they’re converted in Japanese
characters in normal text fields. However, the IME doesn’t
work properly in fields with obscured text. If your org’s
users cannot properly enter their passwords or other
values after enabling this feature, disable the feature.

questionRestriction

QuestionRestriction
(enumeration of type string)

Required. The restriction on whether the answer to the password
hint question can contain the password itself. Valid values are:
• None
• DoesNotContainPassword. This value is the default
value.

SessionSettings
Represents your organization’s session expiration and security settings.
Field

Field Type

Description

disableTimeoutWarning

boolean

Indicates whether the session timeout warning popup is
disabled (true) or enabled (false).

enableCSPOnEmail

boolean

Indicates whether a content security policy is enabled for the
email template. A content security policy helps prevent
cross-site scripting attacks by whitelisting sources of images
and other content.

enableCSRFOnGet

boolean

Indicates whether Cross-Site Request Forgery (CSRF) protection
on GET requests on non-setup pages is enabled (true) or
disabled (false).

625

Metadata Types

SecuritySettings

Field

Field Type

Description

enableCSRFOnPost

boolean

Indicates whether Cross-Site Request Forgery (CSRF) protection
on POST requests on non-setup pages is enabled (true) or
disabled (false).

enableCacheAndAutocomplete boolean

Indicates whether the user’s browser is allowed to store user
names and auto-fill the User Name field on the login page
(true) or not (false).

enableClickjackNonsetupSFDC boolean

Indicates whether clickjack protection for non-setup Salesforce
pages is enabled (true) or disabled (false).

enableClickjackNonsetupUser boolean

Indicates whether clickjack protection for customer Visualforce
pages with standard headers turned on is enabled (true) or
disabled (false).

enableClickjackNonsetupUserHeaderless boolean

Indicates whether clickjack protection for customer Visualforce
pages with standard headers turned off is enabled (true) or
disabled (false). Available in API version 34.0 and later.

enableClickjackSetup

boolean

Indicates whether clickjack protection for setup pages is enabled
(true) or disabled (false).

enablePostForSessions

boolean

Indicates whether cross-domain session information is
exchanged using a POST request instead of a GET request, such
as when a user is using a Visualforce page. In this context, POST
requests are more secure than GET requests. Available in API
version 31.0 and later.

enableSMSIdentity

boolean

Indicates whether users can receive a one-time PIN delivered
via SMS (true) or not (false).

enforceIpRangesEveryRequest boolean

If true, the IP addresses in Login IP Ranges are enforced when
a user accesses Salesforce (on every page request), including
access from a client application. If false, the IP addresses in
Login IP Ranges are enforced only when a user logs in. This field
affects all user profiles that have login IP restrictions. Available
in API version 34.0 and later.

forceLogoutOnSessionTimeout boolean

Indicates that when sessions time out for inactive users, current
sessions become invalid. The browser refreshes and returns to
the login page. To access the org, the user must log in again.
Enabled (true) or not (false). Available in API version 31.0
and later.

forceRelogin

boolean

If true, an administrator that is logged in as another user is
required to log in again to their original session, after logging
out as the secondary user. If false, the administrator is not
required to log in again.

lockSessionsToDomain

boolean

Indicates whether the current UI session for a user, such as a
community user, is associated with a specific domain. This check
helps prevent unauthorized use of the session ID in another

626

Metadata Types

Field

SecuritySettings

Field Type

Description
domain. The value is true by default for organizations created
with the Spring ’15 release or later. Available in API version 33.0
and later.

lockSessionsToIp

boolean

Indicates whether user sessions are locked to the IP address
from which the user logged in (true) or not (false).

logoutURL

string

The URL to which users are redirected when they log out of
Salesforce. If no value is specified, the default is
https://login.salesforce.com unless MyDomain
is enabled. If My Domain is enabled, the default is
https://customdomain.my.salesforce.com.
Available in API version 34.0 and later.

sessionTimeout

SessionTimeout (enumeration
of type string)

The length of time after which users without activity are
prompted to log out or continue working. Valid values are:
• FifteenMinutes
• ThirtyMinutes
• SixtyMinutes
• TwoHours
• FourHours
• EightHours
• TwelveHours

Declarative Metadata Sample Definition
The following is a sample security.settings metadata file.

127.0.0.1
127.0.0.1

http://www.altPage.com
SpecialCharacters
OneYear
http://www.acme.com/forgotpassword
Forgot your password? Reset it
here.
3
ThirtyMinutes
ThreeAttempts
10

627

Metadata Types

Territory2Settings

None

true
false
false
false
true
true
true
true
true
true
TwelveHours

SEE ALSO:
Settings

Territory2Settings
Represents the metadata for the default settings for Territory Management 2.0 users to access and modify records associated with sales
territories. The standard record access settings apply to accounts and opportunities. If your Salesforce org uses Private default internal
access for contacts or cases, you can also set access for those records. This type extends the Metadata metadata type and inherits its
fullName field. Available only if Territory Management 2.0 has been enabled for your org.

File Suffix and Directory Location
Territory2Settings components have the suffix settings and are stored in the Settings folder.

Version
Territory2Settings components are available in API version 32.0 and later.

Special Access Rules
The Territory2Model object has a State field in the SOAP API. States include Planning, Active, Archived, and a number of
other states, such as Cloning, that indicate that a process is underway. Users who do not have the “Manage Territories” permission
can access only territories that belong to the model in Active state. The “Manage Territories” permission is required for deploy()
calls for all territory management entities, in addition to the “Modify All Data” permission required by Metadata API. Using retrieve()
without the “Manage Territories” permission will return only entities that belong to a Territory2Model in Active state. We recommend
against retrieving without the “Manage Territories” permission because the call will retrieve only partial data.

628

Metadata Types

SharedTo

Fields
Field Name

Field Type

defaultAccountAccessLevel string

defaultCaseAccessLevel

string

Description
The default level of access users will have to account records in territories:
view and edit accounts assigned to territories or view, edit,
transfer, and delete accounts assigned to territories.
The default level of access users will have to case records in territories:
view and edit accounts assigned to territories or view, edit,
transfer, and delete accounts assigned to territories.

defaultContactAccessLevel string

The default level of access users will have to contact records in territories:
view and edit accounts assigned to territories or view, edit,
transfer, and delete accounts assigned to territories.

defaultOpportunityAccessLevel string

The default level of access users will have to opportunity records in
territories: view and edit accounts assigned to territories or view,
edit, transfer, and delete accounts assigned to territories.

Declarative Metadata Sample Definition
The following example shows the definition of a Territory2Settings component.

Owner
Read
None
Edit

Usage
Territory Management 2.0 components don’t support packaging or change sets and aren’t supported in CRUD calls.

SharedTo
SharedTo defines the sharing access for a list view or a folder. It can be used to specify the target and source for owner-based sharing
rules. See “Sharing Considerations” and “What Is a Group?” in the Salesforce online help.

Declarative Metadata File Suffix and Directory Location
SharedTo is used with ListView, Folder, and SharingRules.

Version
SharedTo is available in API version 17.0 and later.

629

Metadata Types

SharedTo

Fields
Field

Field Type

Description

allCustomerPortalUsers string

A group containing all customer portal users.
This field is available in API version 24.0 and later.

allInternalUsers

string

A group containing all internal and nonportal users.
This field is available in API version 24.0 and later.

allPartnerUsers

string

A group containing all partner users.
This field is available in API version 24.0 and later.

group

string[]

A list of groups with sharing access. Use this field instead of the
groups field.
This field is available in API version 22.0 and later.

groups

string[]

A list of groups with sharing access.
Use the group field instead for API version 22.0 and later.

managerSubordinates

string[]

A list of users whose direct and indirect subordinates receive
sharing access. This field is available in API version 24.0 and later.

managers

string[]

A list of users whose direct and indirect managers receive sharing
access. This field is available in API version 24.0 and later.

portalRole

string[]

A list of groups with sharing access containing all users in a
portal role.
This field is available in API version 24.0 and later.

portalRoleandSubordinates string[]

A list of groups with sharing access containing all users in a
portal role or those under that role.
This field is available in API version 24.0 and later.

role

string[]

A list of roles with sharing access. Use this field instead of the
roles field.
This field is available in API version 22.0 and later.

roleAndSubordinates

string[]

A list of roles with sharing access. All roles below each of these
roles in the role hierarchy also have sharing access. If portal
accounts are enabled, then all roles and portal accounts below
each of these roles in the role hierarchy also have sharing access.
Use this field instead of the rolesAndSubordinates field
.
This field is available in API version 22.0 and later.

630

Metadata Types

Field

SharingBaseRule

Field Type

Description

roleAndSubordinatesInternal string[]

A list of roles with sharing access. All roles below each of these
roles in the role hierarchy also have sharing access.
This field is available in API version 22.0 and later.

roles

string[]

A list of roles with sharing access.
Use the role field instead for API version 22.0 and later.

rolesAndSubordinates

string[]

A list of roles with sharing access. All roles below each of these
roles in the role hierarchy also have sharing access. If portal
accounts are enabled, then all roles and portal accounts below
each of these roles in the role hierarchy also have sharing access.
Use the roleAndSubordinates field instead for API
version 22.0 and later.

territories

string[]

A list of territories with sharing access.
Use the territory field instead for API version 22.0 and
later.

territoriesAndSubordinates string[]

A list of territories with sharing access. All territories below each
of these territories in the territory hierarchy also have sharing
access.
Use the territoryAndSubordinates field instead for
API version 22.0 and later.

territory

string[]

A list of territories with sharing access. Use this field instead of
the territories field.
This field is available in API version 22.0 and later.

territoryAndSubordinates string[]

A list of territories with sharing access. All territories below each
of these territories in the territory hierarchy also have sharing
access. Use this field instead of the
territoriesAndSubordinates field.
This field is available in API version 22.0 and later.

queue

string[]

A list of queues with sharing access. Applies only to lead, case,
and CustomObject sharing rules.
This field is available in API version 24.0 and later.

SharingBaseRule
Represents sharing rule settings such as access level and to whom access is granted. This type extends the Metadata metadata type and
inherits its fullName field.

631

Metadata Types

SharingBaseRule

Note: You can’t create a SharingBaseRule component directly. Use the components under SharingRules instead.

Version
SharingBaseRule replaces BaseSharingRule and is available in API version 33.0 and later.

Fields
Field

Field Type

Description

accessLevel

string

Required. The access level that the sharing rule
grants.

accountSettings

AccountSharingRuleSettings[]

The access level for the account’s children (case,
contact, and opportunity).

description

string

Describes the sharing rule. Maximum of 1000
characters.

label

string

Required. Label for the sharing rule.

sharedTo

SharedTo

Required. Specifies who the record should be
shared with.

AccountSharingRuleSettings
Defines the access level for the case, contact, and opportunity associated with the account.
Field

Field Type

Description

caseAccessLevel

string

Required. The access level that the user or group
has to cases associated with the account.
Possible values are:
• None
• Read
• Edit

contactAccessLevel

string

Required. The access level that the user or group
has to contacts associated with the account.
Possible values are:
• None
• Read
• Edit

632

Metadata Types

Field

SharingRules

Field Type

Description

opportunityAccessLevel string

Required. The access level that the user or group
has to opportunities associated with the account.
Possible values are:
• None
• Read
• Edit

SharingRules
Represents the base container for sharing rules, which can be criteria-based, ownership-based, or territory-based. SharingRules enables
you to share records with a set of users, using rules that specify the access level for the target user group.
This type extends the Metadata metadata type and inherits its fullName field. For more information, see “Sharing Rules” in the
Salesforce online help.
In API version 33.0 and later, retrieving, deleting, or deploying of all sharing rules in an organization is available . Wildcard support is also
available. You can’t retrieve, delete, or deploy manual sharing rules or sharing rules by their type (owner, criteria-based, or territory).

Declarative Metadata File Suffix and Directory Location
In API version 33.0 and later, components are stored in the sharingRules folder and their file name matches the object name with the
suffix .sharingRules. Criteria-based, owner-based, and territory-based sharing rules are all contained in a object.sharingRule
file.
Prior to API version 33.0, SharingRules components are stored in their corresponding object directory and the file name matches the
object name. For example, the accountSharingRules directory contains an Account.sharingRules file for account
sharing rules. SharingRules for custom objects are stored in the customObjectSharingRules directory, which contains files
with the .sharingRules extension such as ObjA__c.sharingRules, where ObjA refers to the developer name of a custom
object type.

Version
SharingRules components are available in API version 24.0 and later, but these components are no longer available in API version 33.0
and later: AccountSharingRules, CampaignSharingRules, CaseSharingRules, ContactSharingRules, LeadSharingRules,
OpportunitySharingRules, AccountTerritorySharingRules, CustomObjectSharingRules, UserSharingRules.
In API version 33.0 and later, use SharingCriteriaRule, SharingOwnerRule and SharingTerritoryRule.

Fields
The following information assumes that you are familiar with implementing sharing rules for standard objects and custom objects. For
more information on these fields, see “Sharing Settings” in the Salesforce online help.

633

Metadata Types

Field

SharingRules

Field Type

Description

sharingCriteriaRules SharingCriteriaRule[]

An array of criteria-based sharing rules. Available in API
version 33.0 and later.

SharingOwnerRule[]

An array of ownership-based sharing rules. Available in
API version 33.0 and later.

sharingOwnerRules

sharingTerritoryRules SharingTerritoryRule[]

An array of territory-based sharing rules. Available in API
version 33.0 and later.

SharingCriteriaRule
Defines a criteria-based sharing rule. It extends SharingBaseRule and inherits all its fields. Available in API version 33.0 and later.
Field

Field Type

Description

booleanFilter

string

Advanced filter conditions that are specified for the sharing
rule.

criteriaItems

FilterItem[]

An array of the boolean criteria (conditions) for the sharing
rule.

SharingOwnerRule
Defines a ownership-based sharing rule. It extends SharingBaseRule and inherits all its fields. Available in API version 33.0 and later.
Field

Field Type

Description

sharedFrom

SharedTo

Required. Specifies the record owners.

SharingTerritoryRule
Defines a territory-based sharing rule. It extends SharingOwnerRule and inherits all its fields. Available in API version 33.0 and later.

AccountSharingRules
Represents the sharing rules for accounts. It extends the SharingRules metadata type and inherits its fullName field. Only available
in API version 32.0 and earlier.
Field

Field Type

Description

criteriaBasedRules

AccountCriteriaBasedSharingRule[]

List that defines user criteria-based rules.

ownerRules

AccountOwnerSharingRule[]

List that defines user membership-based rules.

634

Metadata Types

SharingRules

CampaignSharingRules
Represents the sharing rules for campaigns. It extends the SharingRules metadata type and inherits its fullName field. Only available
in API version 32.0 and earlier.
Field

Field Type

Description

criteriaBasedRules

CampaignCriteriaBasedSharingRule[]

List that defines user criteria-based rules.

ownerRules

CampaignOwnerSharingRule[]

List that defines user membership-based rules.

CaseSharingRules
Represents the sharing rules for cases. It extends the SharingRules metadata type and inherits its fullName field. Only available in
API version 32.0 and earlier.
Field

Field Type

Description

criteriaBasedRules

CaseCriteriaBasedSharingRule[]

List that defines user criteria-based rules.

ownerRules

CaseOwnerSharingRule[]

List that defines user membership-based rules.

ContactSharingRules
Represents the sharing rules for contacts. It extends the SharingRules metadata type and inherits its fullName field. Only available
in API version 32.0 and earlier.
Field

Field Type

Description

criteriaBasedRules

ContactCriteriaBasedSharingRule[]

List that defines user criteria-based rules.

ownerRules

ContactOwnerSharingRule[]

List that defines user membership-based rules.

LeadSharingRules
Represents the sharing rules for leads. It extends the SharingRules metadata type and inherits its fullName field. Only available in
API version 32.0 and earlier.
Field

Field Type

Description

criteriaBasedRules

LeadCriteriaBasedSharingRule[]

List that defines user criteria-based rules.

ownerRules

LeadOwnerSharingRule[]

List that defines user membership-based rules.

OpportunitySharingRules
Represents the sharing rules for opportunities. It extends the SharingRules metadata type and inherits its fullName field. Only available
in API version 32.0 and earlier.

635

Metadata Types

SharingRules

Field

Field Type

Description

criteriaBasedRules

OpportunityCriteriaBasedSharingRule[]

List that defines user criteria-based rules.

ownerRules

OpportunityOwnerSharingRule[]

List that defines user membership-based rules.

AccountTerritorySharingRules
Represents the sharing rules for account territories. It extends the SharingRules metadata type and inherits its fullName field. Only
available in API version 32.0 and earlier.
Field

Field Type

Description

rules

AccountTerritorySharingRule[]

List that defines user membership-based rules. The list of
acceptable values for the sharedFrom fields are:
• territory
• territoryAndSubordinates

CustomObjectSharingRules
Represents the sharing rules for custom objects. It extends the SharingRules metadata type and inherits its fullName field. Only
available in API version 32.0 and earlier.
Field

Field Type

Description

criteriaBasedRules

CustomObjectCriteriaBasedSharingRule[] List that defines user criteria-based rules.

ownerRules

CustomObjectOwnerSharingRule[]

List that defines user membership-based rules.

UserSharingRules
Represents the sharing rules for users. With user sharing rules, you can share members of a group with members of another group. It
extends the SharingRules metadata type and inherits its fullName field. Only available in API version 32.0 and earlier.
Field

Field Type

Description

criteriaBasedRules

UserCriteriaBasedSharingRule[]

List that defines user criteria-based rules.

membershipRules

UserMembershipSharingRule[]

List that defines user membership-based rules.

Declarative Metadata Sample Definition
For retrieving sharing rules, see package.xml sample at Sharing Rules.
The following sample XML definition represents a criteria-based sharing rule in API version 33.0.

636

Metadata Types

SharingRules

AccountCriteriaShareWithCEO
Edit

Read
Edit
Edit

Name
startsWith
Test

my account criteria rule description
AccountCriteriaShareWithCEO

CEO

The following sample XML definition represents an ownership-based sharing rule in API version 33.0.

MyCase
Edit
my case test owner sharing rule desc
MyCase

COO

CEO

The following sample XML definition represents a territory-based sharing rule in API version 33.0.

MyAccountTerritoryRule
Read

None
Read
None

MyAccountTerritoryRule desc
MyAccountTerritoryRule

My_territory

637

Metadata Types

SharingRules

CEO

The following is the definition of two account owner-based sharing rules in API version 32.0 and earlier. The file name corresponds to
Account.sharingRules under the accountSharingRules directory. In this definition, ownerRules corresponds to
AccountOwnerSharingRule.

G1Dev_G2New

G1Dev

G2New

Read
None
Read
G1Dev_G2New
Edit

G2New_R1New

G2New

R1New

Edit
Read
Edit
G2New_R1New
None

The following is the definition of a user criteria-based sharing rule and a user membership-based sharing rule in API version 32.0 and
earlier. The file name corresponds to User.sharingRules under the userSharingRules directory.

shareUsers2

Asia_Division

FirstName

638

Metadata Types

BaseSharingRule

equals
John

shareUsers2
Read

shareUsers1

South_America_Division

Asia_Division

shareUsers1
Read

The following shows a sample package.xml file.

ObjA__c.*
SharingCriteriaRule

ObjA__c.*
SharingOwnerRule

39.0

BaseSharingRule
This component is removed as of API version 33.0 and is available in earlier versions only. Use SharingBaseRule instead.
Represents the base container for criteria-based and owner-based sharing rules. This type extends the Metadata metadata type and
inherits its fullName field.
Note: You can’t create a BaseSharingRule component directly. Use the components under the CriteriaBasedSharingRule or
OwnerSharingRule metadata types instead.

Version
BaseSharingRule components are available in API version 24.0 and later.

Fields
For more information on these fields, see “Sharing Settings” in the Salesforce online help.

639

Metadata Types

CriteriaBasedSharingRule

Field

Field Type

Description

sharedTo

SharedTo

Required. Specifies who the record should be
shared with.

fullName

string

The unique identifier for API access. The
fullName can contain only underscores and
alphanumeric characters. It must be unique,
begin with a letter, not include spaces, not end
with an underscore, and not contain two
consecutive underscores. This field is inherited
from the Metadata component.

CriteriaBasedSharingRule
This component is removed as of API version 33.0 and is available in earlier versions only. Use SharingRules instead.
Represents a criteria-based sharing rule. CriteriaBasedSharingRule enables you to share records based on specific criteria. It extends the
BaseSharingRule metadata type and inherits its sharedTo field. For more information, see “Criteria-Based Sharing Rules Overview”
in the Salesforce online help.
Note: You can’t create a CrteriaBasedSharingRule component directly. Use the child components instead.

Declarative Metadata File Suffix and Directory Location
CriteriaBasedSharingRule components are stored within the SharingRules component in the criteriaBasedRules field.

Version
CriteriaBasedSharingRule components are available in API version 24.0 and later.

Field Type

Description

criteriaItems

FilterItem[]

List that represents the criteria for the sharing
rule. The possible values are:
• field
• operation
• value

AccountCriteriaBasedSharingRule
Represents a criteria-based sharing rule for accounts. It extends the CriteriaBasedSharingRule metadata type and inherits its
criteriaItems field.

640

Metadata Types

CriteriaBasedSharingRule

AccountCriteriaBasedSharingRule is used by the criteriaBasedRules field in AccountSharingRules.
Field

Field Type

Description

accountAccessLevel

ShareAccessLevelNoNone Required. A value that represents the level of access that the

(enumeration of type string)

user or group has to the account. The possible values are:
• Read
• Edit
• All

booleanFilter

string

Represents the filter logic of the sharing rule.

caseAccessLevel

ShareAccessLevelNoAll Required. A value that represents the level of access that the

(enumeration of type string)

user or group has to cases associated with the account. The
possible values are:
• None
• Read
• Edit

contactAccessLevel

ShareAccessLevelNoAll Required. A value that represents the level of access that the

(enumeration of type string)

user or group has to contacts associated with the account. The
possible values are:
• None
• Read
• Edit

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

opportunityAccessLevel ShareAccessLevelNoAll Required. A value that represents the level of access that a target

(enumeration of type string)

group is granted for any associated opportunity. The possible
values are:
• None
• Read
• Edit

CampaignCriteriaBasedSharingRule
Represents a criteria-based sharing rule for campaigns. It extends the CriteriaBasedSharingRule metadata type and inherits its
criteriaItems field.
CampaignCriteriaBasedSharingRule is used by the criteriaBasedRules field in CampaignSharingRules.

641

Metadata Types

CriteriaBasedSharingRule

Field

Field Type

Description

booleanFilter

string

Represents the filter logic of the sharing rule.

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

campaignAccessLevel

ShareAccessLevelNoNone Required. A value that represents the level of access that a target

(enumeration of type string)

group is granted for a campaign. The possible values are:
• Read
• Edit
• All

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

CaseCriteriaBasedSharingRule
Represents a criteria-based sharing rule for cases. It extends the CriteriaBasedSharingRule metadata type and inherits its
criteriaItems field.
CaseCriteriaBasedSharingRule is used by the criteriaBasedRules field in CaseSharingRules.
Field

Field Type

Description

booleanFilter

string

Represents the filter logic of the sharing rule.

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

caseAccessLevel

ShareAccessLevelReadEdit Required. A value that represents the level of access being

(enumeration of type string)

granted for a case. The possible values are:
• Read
• Edit

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

ContactCriteriaBasedSharingRule
Represents a criteria-based sharing rule for contacts. It extends the CriteriaBasedSharingRule metadata type and inherits its
criteriaItems field.
ContactCriteriaBasedSharingRule is used by the criteriaBasedRules field in ContactSharingRules.

642

Metadata Types

CriteriaBasedSharingRule

Field

Field Type

Description

booleanFilter

string

Represents the filter logic of the sharing rule.

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

contactAccessLevel

ShareAccessLevelReadEdit Required. A value that represents the level of access being

(enumeration of type string)

granted to the target group, role, or user for a contact. The
possible values are:
• Read
• Edit

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

LeadCriteriaBasedSharingRule
Represents a criteria-based sharing rule for leads. It extends the CriteriaBasedSharingRule metadata type and inherits its criteriaItems
field.
LeadCriteriaBasedSharingRule is used by the criteriaBasedRules field in LeadSharingRules.
Field

Field Type

Description

booleanFilter

string

Represents the filter logic of the sharing rule.

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

leadAccessLevel

ShareAccessLevelReadEdit Required. A value that represents the level of allowed access.

(enumeration of type string)

The possible values are:
• Read
• Edit

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

OpportunityCriteriaBasedSharingRule
Represents a criteria-based sharing rule for opportunities. It extends the CriteriaBasedSharingRule metadata type and inherits its
criteriaItems field.
OpportunityCriteriaBasedSharingRule is used by the criteriaBasedRules field in OpportunitySharingRules.

643

Metadata Types

CriteriaBasedSharingRule

Field

Field Type

Description

booleanFilter

string

Represents the filter logic of the sharing rule.

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

opportunityAccessLevel ShareAccessLevelReadEdit Required. A value that represents the level of allowed access.

(enumeration of type string)

The possible values are:
• Read
• Edit

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

CustomObjectCriteriaBasedSharingRule
Represents a criteria-based sharing rule for custom objects. It extends the CriteriaBasedSharingRule metadata type and inherits its
criteriaItems field.
CustomObjectCriteriaBasedSharingRule is used by the criteriaBasedRules field in CustomObjectSharingRules.
Field

Field Type

Description

accessLevel

string

Required. A value that represents the type of allowed sharing.
The possible values are:
• Read
• Edit
• All

booleanFilter

string

Represents the filter logic of the sharing rule.

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

UserCriteriaBasedSharingRule
Represents a criteria-based sharing rule for users. It extends the CriteriaBasedSharingRule metadata type and inherits its criteriaItems
field.
UserCriteriaBasedSharingRule is used by the criteriaBasedRules field in UserSharingRules.

644

Metadata Types

CriteriaBasedSharingRule

Field

Field Type

Description

booleanFilter

string

Represents the filter logic of the sharing rule.

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

userAccessLevel

ShareAccessLevelReadEdit Required. A value that represents the type of allowed sharing.

(enumeration of type string)

The possible values are:
• Read
• Edit

Declarative Metadata Sample Definition
The following is the definition of two owner-based sharing rules and one criteria-based sharing rule containing two criteria items. The
file name corresponds to the Account.sharingRules file under the accountSharingRules directory.

G1Dev_G2New

G2New

G1Dev

Read
None
Read

G2New_R1New

R1New

G2New

Edit
Read
Edit
G2New_R1New
None

AccountCriteria

645

Metadata Types

OwnerSharingRule

BillingCity
equals
San Francisco

MyChkBox__c
notEqual
False

Read
1 OR 2
None
Read
AccountCriteria
None

OwnerSharingRule
This component is removed as of API version 33.0 and is available in earlier versions only.
Represents an ownership-based sharing rule. OwnerSharingRule enables you to share records owned by a set of users with another set,
using rules that specify the access level of the target user group. It extends the BaseSharingRule metadata type and inherits its SharedTo
field. For more information, see “Sharing Rules” in the Salesforce online help.
Note: You can’t create a OwnerSharingRule component directly. Use the child components instead.

Declarative Metadata File Suffix and Directory Location
OwnerSharingRules components are stored within the SharingRules component in the ownerRules field.

Version
OwnerSharingRules components are available in API version 24.0 and later.

Field Type

Description

sharedFrom

SharedTo

Required. Specifies the record owners.

sharedTo

SharedTo

Required. Specifies who the record should be
shared with.

fullName

string

The unique identifier for API access. The
fullName can contain only underscores and

646

Metadata Types

Field

OwnerSharingRule

Field Type

Description
alphanumeric characters. It must be unique,
begin with a letter, not include spaces, not end
with an underscore, and not contain two
consecutive underscores. This field is inherited
from the Metadata component.

AccountOwnerSharingRule
Represents a sharing rule for an account with users other than the owner. It extends the OwnerSharingRule metadata type and inherits
its fullName, sharedFrom, and sharedTo fields.
AccountOwnerSharingRule is used by the ownerRules field in AccountSharingRules.
Field

Field Type

Description

accountAccessLevel

ShareAccessLevelNoNone Required. A value that represents the level of access that a group

(enumeration of type string)

or role has to the account. The possible values are:
• Read
• Edit
• All

caseAccessLevel

ShareAccessLevelNoAll Required. A value that represents the level of access that a group

(enumeration of type string)

or role has to cases associated with the account. The possible
values are:
• None
• Read
• Edit

contactAccessLevel

ShareAccessLevelNoAll Required. A value that represents the level of access that a group

(enumeration of type string)

or role has to contacts associated with the account. The possible
values are:
• None
• Read
• Edit

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

647

Metadata Types

Field

OwnerSharingRule

Field Type

Description

opportunityAccessLevel ShareAccessLevelNoAll Required. A value that represents the level of access that a group

(enumeration of type string)

or role is granted for any associated opportunity. The possible
values are:
• None
• Read
• Edit

CampaignOwnerSharingRule
Represents a sharing rule for a campaign with users other than the owner. It extends the OwnerSharingRule metadata type and inherits
its fullName, sharedFrom, and sharedTo fields.
CampaignOwnerSharingRule is used by the ownerRules field in CampaignSharingRules.
Field

Field Type

Description

campaignAccessLevel

ShareAccessLevelNoNone A value that represents the level of access that a group or role

(enumeration of type string)

is granted for a campaign. The possible values are:
• Read
• Edit
• All

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

name

string

Name for the sharing rule. Corresponds to Label in the user
interface.

CaseOwnerSharingRule
Represents a sharing rule for a case with users other than the owner. It extends the OwnerSharingRule metadata type and inherits its
fullName, sharedFrom, and sharedTo fields.
CaseOwnerSharingRule is used by the ownerRules field in CaseSharingRules. All the following fields are required.
Field

Field Type

Description

caseAccessLevel

ShareAccessLevelReadEdit Required. A value that represents the level of access that a group

(enumeration of type string)

or role is granted for a case. The possible values are:
• Read
• Edit

648

Metadata Types

OwnerSharingRule

Field

Field Type

Description

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

ContactOwnerSharingRule
Represents a sharing rule for a contact with users other than the owner. It extends the OwnerSharingRule metadata type and inherits
its fullName, sharedFrom, and sharedTo fields.
ContactOwnerSharingRule is used by the ownerRules field in ContactSharingRules.
Field

Field Type

Description

contactAccessLevel

ShareAccessLevelReadEdit Required. A value that represents the level of access that a group

(enumeration of type string)

or role is granted for a contact. The possible values are:
• Read
• Edit

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

LeadOwnerSharingRule
Represents a sharing rule for a lead with users other than the owner. It extends the OwnerSharingRule metadata type and inherits its
fullName, sharedFrom, and sharedTo fields.
LeadOwnerSharingRule is used by the ownerRules field in LeadSharingRules.
Field

Field Type

Description

leadAccessLevel

ShareAccessLevelReadEdit Required. A value that represents the level of access that a group

(enumeration of type string)

or role is granted for a lead. The possible values are:
• Read
• Edit

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

649

Metadata Types

OwnerSharingRule

Field

Field Type

Description

name

string

Required. Required. Name for the sharing rule. Corresponds to
Label in the user interface.

OpportunityOwnerSharingRule
Represents a sharing rule for an opportunity with users other than the owner. It extends the OwnerSharingRule metadata type and
inherits its fullName, sharedFrom, and sharedTo fields.
OpportunityOwnerSharingRule is used by the ownerRules field in OpportunitySharingRules.
Field

Field Type

Description

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

opportunityAccessLevel ShareAccessLevelReadEdit Required. A value that represents the level of access that a group

(enumeration of type string)

or role is granted for an opportunity. The possible values are:
• Read
• Edit

AccountTerritorySharingRule
Represents a rule for sharing an account within a territory. It extends the OwnerSharingRule metadata type and inherits its fullName,
sharedFrom, and sharedTo fields.
AccountTerritorySharingRule is used by the ownerRules field in AccountTerritorySharingRules.
Field

Field Type

Description

accountAccessLevel

ShareAccessLevelNoNone Required. A value that represents the level of access that a

(enumeration of type string)

Territory or TerritoryAndSubordinates group is granted for an
account territory. The possible values are:
• Read
• Edit
• All

caseAccessLevel

ShareAccessLevelNoAll Required. A value that represents the level of access that a

(enumeration of type string)

Territory or TerritoryAndSubordinates group is granted for all
child cases to an account. The possible values are:
• None
• Read

650

Metadata Types

Field

OwnerSharingRule

Field Type

Description
• Edit

contactAccessLevel

ShareAccessLevelNoAll Required. A value that represents the level of access that a

(enumeration of type string)

Territory or TerritoryAndSubordinates group is granted for all
related contacts on an account. The possible values are:
• None
• Read
• Edit

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

opportunityAccessLevel ShareAccessLevelNoAll Required. A value that represents the level of access that a

(enumeration of type string)

Territory or TerritoryAndSubordinates group is granted for all
opportunities associated with an account. The possible values
are:
• None
• Read
• Edit

CustomObjectOwnerSharingRule
Represents a sharing rule for custom objects. It extends the OwnerSharingRule metadata type and inherits its fullName, sharedFrom,
and sharedTo fields.
CustomObjectOwnerSharingRule is used by the ownerRules field in CustomObjectSharingRules.
Field

Field Type

Description

accessLevel

string

Required. A value that represents the level of access that a group
or role is granted to a custom object. The possible values are:
• Read
• Edit
• All

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

651

Metadata Types

SharingSet

UserMembershipSharingRule
Represents a sharing rule to share members of a group with another group of users. It extends the OwnerSharingRule metadata type
and inherits its fullName, sharedFrom, and sharedTo fields.
UserMembershipSharingRule is used by the ownerRules field in UserSharingRules on page 636.
Field

Field Type

Description

description

string

Represents the description of the sharing rule. Maximum of 1000
characters.
This field is available in API version 29.0 and later.

name

string

Required. Name for the sharing rule. Corresponds to Label in
the user interface.

userAccessLevel

ShareAccessLevelReadEdit Required. A value that represents the level of access that a group

(enumeration of type string)

or role is granted for a user. The possible values are:
• Read
• Edit

SharingSet
Represents a sharing set. A sharing set defines an access mapping that grants portal or community users access to objects that are
associated with their accounts or contacts. This type extends the Metadata metadata type and inherits its fullName field.
For example, you can grant portal or community users access to all cases related to their account record. Similarly, you can grant portal
or community users access to all cases related to a parent account that is identified on the user’s account record. For more information,
see “Sharing Set Overview” in the Salesforce Help.

File Suffix and Directory Location
SharingSet components have the suffix .sharingSet and are stored in the sharingSets folder.

Version
SharingSet components are available in API version 30.0 and later.

Fields
Field Name

Field Type

Description

accessMappings

AccessMapping[]

A list of access mappings on a sharing set.

description

string

The sharing set description. Limit: 255 characters.

name

string

Required. The unique identifier for API access. Corresponds to Sharing
Set Name on the user interface.

652

Metadata Types

SharingSet

Field Name

Field Type

Description

profiles

string[]

The profiles of users that are granted access to the target objects. Valid
values are:
• Authenticated Website
• Customer Community User
• Customer Community Login User
• High Volume Customer Portal User
• Overage Authenticated Website User
• Overage High Volume Customer Portal User

AccessMapping
AccessMapping represents an access mapping in the sharing set, which grants access to a target object by looking up to an account or
contact associated with the user.
You can grant portal users access to a target object, or to both a target object and its associated objects, such as an account and its
contacts and cases.
Field Name

Field Type

Description

accessLevel

string

The target object access level granted to the portal user. Valid values are:
• Read
• Edit

objectField

string

A lookup to the target object, which supports standard or custom fields, or an
Id. For accounts or cases associated with entitlements, use
Entitlement.Account or Entitlement.Case.

object

string

The target object to which the portal user is gaining access, and refers to one
of the following:
• Account
• Contact
• Case
• ServiceContract
• User
• Custom Objects (e.g. ObjA__c)
Portal users gain access to all order entitlements and order items under an
account to which they have access.

userField

string

The user’s lookup to an account, contact, or a standard or custom field derived
from an account or contact. Either the user or the user’s manager can be used
in the lookup. Valid values are:
• Account
• Account.Field

653

Metadata Types

Field Name

SharingSet

Field Type

Description
• Contact
• Contact.Field
• Manager.Account
• Manager.Contact
Field refers to a standard or custom field based on an account or contact.

Declarative Metadata Sample Definition
The following is an example of a SharingSet component that grants users access to all contacts whose ReportsTo fields match the
users’ contacts.

Read
ReportsTo

Contact

User Access Mapping
User
customer community user

The following is an example of a SharingSet component that grants users access to all cases that are related to an entitlement, which is
associated with the user’s account.

Case

Edit
Entitlement.Account

Account

The following is an example of a SharingSet component with a list of access mappings.

This is a basic sharing set with several access mappings.
Basic
customer community user

Read
Id

Account

654

Metadata Types

SiteDotCom

Edit
Account

Account

Edit
Contact

Contact

Read
AccountLookup__c

Account

The following is an example package.xml that references the previous definition.

SharingSetBasic

HVPUAccessible__c.AccountLookup__c
HVPUAccessible__c.ContactLookup__c
CustomField

HVPUAccessible__c
CustomObject

Basic
SharingSet

30.0

SiteDotCom
Represents a site for deployment. It extends the MetadataWithContent type and inherits its fullName and content fields.

Declarative Metadata File Suffix and Directory Location
SiteDotCom components are stored in the siteDotComSites directory of the corresponding package directory. The file name for
the metadata .xml file is [sitename].site-meta.xml. The file name for the site file is [sitename].site

655

Metadata Types

Skill

Note: There is a file size limitation when using the Metadata API to deploy a site from sandbox to production. The assets in the
.site file can’t be larger than 40 MB. The site gets created, but the assets show in the new site as broken. To fix the assets, export
the assets from the sandbox environment separately and then import them into your new site.

Version
SiteDotCom components are available in API version 30.0 and later.

Fields
Field

Field Type

Description

label

string

The name of the site you are deploying.

siteType

(enumeration of type
string)

Required. Identifies whether the site is a
ChatterNetworkPicasso site for Salesforce
Communities sites, or a Siteforce site for
Site.com sites.

Declarative Metadata Sample Definition
Sample XML definitions for SiteDotCom are shown below.

testsite
Siteforce

testCommunity
ChatterNetworkPicasso

Skill
Represents the settings for a skill used for field service or to route chats to agents in Live Agent, such as the name of the skill and which
agents the skills are assigned to. This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location
Skill values are stored in the .skill file in the skills directory.

656

Metadata Types

Skill

Version
Skill is available in API version 28.0 and later.

Fields
Field Name

Field Type

Description

assignments

SkillAssignments

Specifies how skills are assigned to Live Agent users. Skills
can be assigned to sets of users or sets of profiles.

description

string

Specifies the description of the skill. This field is available in
API version 38.0 and later.

label

string

Specifies the name of the skill.

SkillAssignments
Represents which users and user profiles to whom specific skills are assigned.

Fields
Field Name

Field Type

Description

profiles

SkillProfileAssignments

Specifies the profiles that are associated with a specific skill.

users

SkillUserAssignments

Specifies the users that are associated with a specific skill.

SkillProfileAssignments
Represents the profiles that are associated with a specific skill.

Fields
Field Name

Field Type

Description

profile

string

Specifies the custom name of the profile associated with a
specific skill.

SkillUserAssignments
Represents the users that are associated with a specific skill.

657

Metadata Types

StandardValueSet

Fields
Field Name

Field Type

Description

user

string

Specifies the username of the user associated with a specific
skill.

Declarative Metadata Sample Definition
This is a sample of a skill file.

My Skill 1

LiveAgentOperator
LiveAgentSupervisor

jdoe@acme.com

StandardValueSet
Represents the set of values in a standard picklist field. This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location
StandardValueSet components have the suffix .standardValueSet and are stored in the standardValueSets folder.

Version
StandardValueSet components are available in API version 38.0 and later.
Note: StandardValueSet isn’t available in Tooling API. Picklist elements in Tooling API are represented as in API version 37.0.

Fields
Field Name

Field Type

Description

sorted

boolean

Required. Indicates whether a global value set is sorted in alphabetical
order. By default, this value is false.

standardValue

StandardValue[]

Defines each value in a standard picklist’s value set.

658

Metadata Types

StandardValueSetTranslation

Declarative Metadata Sample Definition
The following example shows a StandardValueSet component that’s defined as the Stage standard picklist on a customized opportunity
object.

OpportunityStage

Closed Abandoned

Closed Won

Closed Lost

Opportunity

StageName
Stage
Picklist

ObjectWithValueSet
ObjectWithValueSet
ReadWrite

For a list of standard value set names for standard picklists, see StandardValueSet Names and Standard Picklist Fields.

StandardValueSetTranslation
Contains details for a standard picklist translation. It returns a translated standard value set.This type extends the Metadata metadata
type and inherits its fullName field.

File Suffix and Directory Location
StandardValueSetTranslation components have the suffix .standardValueSetTranslation and are stored in the
standardValueSetTranslations folder.
Translations are stored in a file with a format of ValueSetName-lang.standardValueSetTranslation, where
ValueSetName is the global value set’s name, and lang is the translation language.

Version
StandardValueSetTranslation components are available in API version 38.0 and later.

659

Metadata Types

StaticResource

Fields
Field

Field Type

Description

valueTranslation

ValueTranslation[]

A list of values from global value sets to be translated.

Declarative Metadata Sample Definition
The following is an example of a StandardValueSetTranslation component. When a value isn’t translated, its translation becomes a
comment that’s paired with its masterLabel.

Cold

Hot

Warm

The following is an example package.xml that references the StandardValueSetTranslation definition.

AccountRating-fr
StandardValueSetTranslation

38.0

category

LogCategory

Specify the type of information returned in the debug log. Valid values are:
• Db
• Workflow
• Validation
• Callout
• Apex_code
• Apex_profiling
• Visualforce
• System
• All

level

LogCategoryLevel

Specifies the level of detail returned in the debug log.
Valid log levels are (listed from lowest to highest):
• NONE
• ERROR
• WARN
• INFO
• DEBUG
• FINE
• FINER
• FINEST

718

Headers

SessionHeader

Sample Code—Java
Add the DebuggingHeader to the metadata connection before you perform the deploy() call as follows.
LogInfo[] logs = new LogInfo[1];
logs[0] = new LogInfo();
logs[0].setCategory(LogCategory.Apex_code);
logs[0].setLevel(LogCategoryLevel.Fine);
metadataConnection.setDebuggingHeader(logs);

The result of the deploy() call is obtained by calling checkDeployStatus(). After the deployment finishes, and if tests were run, the response
of checkDeployStatus() contains the debug log output in the debugLog field of a DebuggingInfo output header.

SessionHeader
Specifies the session ID that the login call returns. This session ID is used to authenticate all subsequent Metadata API calls.

Version
This header is available in all API versions.

Supported Calls
All Metadata API calls.

Fields
Field Name

Type

Description

sessionId

string

The session ID that the login call returns.

Sample Code—Java
Add the SessionHeader to the metadata connection before you perform a call as follows:
metadataConnection.setSessionHeader("");

719

APPENDICES

APPENDIX A CustomObjectTranslation Language Support: Fully
Supported Languages
Not every language supports all the possible values for the fields in CustomObjectTranslation. Use this appendix to determine which
field values a language supports.
Note: Salesforce offers three levels of language support: fully supported languages, end-user languages, and platform-only
languages. This appendix provides information only for fully supported languages. For more information, see Supported Languages

Chinese (Simplified)
plural
false
caseType
Nominative
possessive
None
startwith
Consonant
plural
false

Chinese (Traditional)
caseType
Nominative
possessive
None
startwith
Consonant
plural
false

720

CustomObjectTranslation Language Support: Fully Supported
Languages

Danish
caseType
Nominative
article
Zero
Definite
Indefinite
possessive
None
gender
Feminine
Neuter
startwith
Consonant
plural
true

Dutch
CaseType
Nominative
article
Definite
Indefinite
gender
Feminine
Neuter
possessive
None
plural
true

Finnish
caseType
Ablative
Adessive
Allative
Dative

721

CustomObjectTranslation Language Support: Fully Supported
Languages
Elative
Essive
Genitive
Illative
Inessive
Nominative
Partitive
Translative
plural
true
possessive
None
First
Second
startwith
Consonant

French
article
Zero
Definite
Indefinite
gender
Masculine
Feminine
possessive
None
plural
true
startwith
Consonant
Vowel

German
article
Zero
Definite

722

CustomObjectTranslation Language Support: Fully Supported
Languages
Indefinite
caseType
Accusative
Dative
Genitive
Nominative
gender
Masculine
Feminine
Neuter
possessive
None
plural
true

Italian
article
Zero
Indefinite
Definite
CaseType
Nominative
gender
Masculine
Feminine
possessive
None
plural
true
startwith
Consonant
Vowel
Special

Japanese
CaseType
Nominative

723

CustomObjectTranslation Language Support: Fully Supported
Languages
possessive
None
startwith
Consonant
plural
false

Korean
CaseType
Nominative
possessive
None
startwith
Consonant
plural
false

Portuguese (Brazilian)
article
Zero
Definite
Indefinite
article
Zero
Indefinite
Definite
plural
true

Russian
caseType
Accusative
Dative
Genitive
Instrumental
Nominative
Prepositional

724

CustomObjectTranslation Language Support: Fully Supported
Languages
gender
Masculine
Feminine
Neuter
Animate_Masculine
plural
true
false

Spanish
article
Zero
Definite
Indefinite
CaseType
Nominative
gender
Masculine
Feminine
startwith
Consonant
plural
true

Thai
CaseType
Nominative
possessive
None
startwith
Consonant
plural
false

725

APPENDIX B CustomObjectTranslation Language Support:
End-User Languages
Not every language supports all the possible values for the fields in CustomObjectTranslation. Use this appendix to determine which
field values a language supports.
Note: Salesforce offers three levels of language support: fully supported languages, end-user languages, and platform-only
languages. This appendix provides information only for end-user languages. For more information, see Supported Languages

Arabic
article
Zero
Definite
CaseType
Nominative
Accusative
gender
Masculine
Feminine
plural
true
possessive
None
First
Second
startwith
Consonant

Bulgarian
article
Zero
Definite

726

CustomObjectTranslation Language Support: End-User
Languages
CaseType
Nominative
Objective
gender
Masculine
Feminine
Neuter
possessive
None
plural
true
startwith
Consonant

Czech
CaseType
Accusative
Dative
Genitive
Instrumental
Locative
Vocative
Nominative
gender
Masculine
Feminine
Neuter
Animate_Masculine
plural
true

Greek
article
Zero
Definite
Indefinite

727

CustomObjectTranslation Language Support: End-User
Languages
CaseType
Accusative
Genitive
Nominative
Vocative
gender
Masculine
Feminine
Neuter
possessive
None
plural
true

Hebrew
article
Zero
Definite
CaseType
Nominative
gender
Masculine
Feminine
possessive
None
plural
true

Hungarian
article
Zero
Definite
Indefinite
CaseType
Ablative
Accusative
Allative
Causalfinal

728

CustomObjectTranslation Language Support: End-User
Languages
Dative
Delative
Distributive
Elative
Essiveformal
Illative
Inessive
Instrumental
Nominative
Sublative
Terminative
Translative
plural
true
possessive
None
First
Second
startwith
Consonant
Vowel

Indonesian
plural
true
CaseType
Nominative
Possessive
None
startwith
Consonant

Norwegian
article
Zero
Definite
Indefinite

729

CustomObjectTranslation Language Support: End-User
Languages
CaseType
Nominative
gender
Masculine
Feminine
Neuter
possessive
None
plural
true

Polish
CaseType
Nominative
Accusative
Dative
Genitive
Instrumental
Locative
Vocative
gender
Masculine
Feminine
Neuter
Animate_Masculine
plural
true

Romanian
article
Zero
Definite
Indefinite
CaseType
Nominative
Dative

730

CustomObjectTranslation Language Support: End-User
Languages
gender
Masculine
Feminine
Neuter
possessive
None
plural
true

Spanish (Mexico)
article
Zero
Definite
Indefinite
CaseType
Nominative
gender
Masculine
Feminine
possessive
None
plural
true

Turkish
article
Zero
Indefinite
CaseType
Ablative
Accusative
Dative
Genitive
Nominative
possessive
None
First
Second

731

CustomObjectTranslation Language Support: End-User
Languages
startwith
Consonant
plural
true

Ukrainian
CaseType
Accusative
Dative
Genitive
Instrumental
Nominative
Locative
Vocative
gender
Masculine
Feminine
Neuter
Animate_Masculine
plural
true

Vietnamese
CaseType
Nominative
possessive
None
startwith
Consonant
plural
false

732

APPENDIX C StandardValueSet Names and Standard Picklist
Fields
In API version 38.0 and later, standard picklists are represented by the StandardValueSet type. In previous versions, standard picklists are
represented by the CustomField type. This table lists the names of standard picklists as standard value sets and their corresponding field
names.
Note: The names of standard value sets and picklist fields are case-sensitive.
Standard Value Set Name (API version 38.0 and later) Field Name (API version 37.0 and earlier)
AccountContactMultiRoles

AccountContactRelation.Roles

AccountContactRole

AccountContactRole.Role

AccountOwnership

Account.Ownership

AccountRating

Account.Rating
Lead.Rating

AccountType

Account.Type

AddressCountryCode

Country picklist

AddressStateCode

State picklist

AssetStatus

Asset.Status

CampaignMemberStatus

CampaignMember.Status

CampaignStatus

Campaign.Status

CampaignType

Campaign.Type

CaseContactRole

CaseContactRole.Role

CaseOrigin

Case.Origin

CasePriority

Case.Priority

CaseReason

Case.Reason

CaseStatus

Case.Status

CaseType

Case.Type

ContactRole

OpportunityContactRole.Role

733

StandardValueSet Names and Standard Picklist Fields

Standard Value Set Name (API version 38.0 and later) Field Name (API version 37.0 and earlier)
ContractContactRole

ContractContactRole.Role

ContractStatus

Contract.Status

EntitlementType

Entitlement.Type

EventSubject

Event.Subject

EventType

Event.Type

FiscalYearPeriodName

Period.PeriodLabel

FiscalYearPeriodPrefix

FiscalYearSettings.PeriodPrefix

FiscalYearQuarterName

Period.QuarterLabel

FiscalYearQuarterPrefix

FiscalYearSettings.QuarterPrefix

IdeaCategory1

IdeaTheme.Categories1

IdeaMultiCategory

Idea.Categories

IdeaStatus

Idea.Status

IdeaThemeStatus

IdeaTheme.Status

Industry

Account.Industry
Lead.Industry

InvoiceStatus

Invoice.Status

LeadSource

Account.AccountSource
Lead.LeadSource
Opportunity.Source

LeadStatus

Lead.Status

OpportunityCompetitor

Opportunity.Competitors

OpportunityStage

Opportunity.StageName

OpportunityType

Opportunity.Type

OrderStatus1

Order.Status1

OrderType

Order.Type

PartnerRole

Account.PartnerRole

Product2Family

Product2.Family

QuestionOrigin1

Question.Origin1

QuickTextCategory

QuickText.Category

QuickTextChannel

QuickText.Channel

734

StandardValueSet Names and Standard Picklist Fields

Standard Value Set Name (API version 38.0 and later) Field Name (API version 37.0 and earlier)
QuoteStatus

Quote.Status

SalesTeamRole

OpportunityTeamMember.TeamMemberRole
UserAccountTeamMember.TeamMemberRole
UserTeamMember.TeamMemberRole
AccountTeamMember.TeamMemberRole

Salutation

Contact.Name
Lead.Name

ServiceContractApprovalStatus

ServiceContract.ApprovalStatus

SocialPostClassification

SocialPost.Classification

SocialPostEngagementLevel

SocialPost.EngagementLevel

SocialPostReviewedStatus

SocialPost.ReviewedStatus

SolutionStatus

Solution.Status

TaskPriority

Task.Priority

TaskStatus

Task.Status

TaskSubject

Task.Subject

TaskType

Task.Type

WorkOrderLineItemStatus

WorkOrderLineItem.Status

WorkOrderPriority

WorkOrder.Priority

WorkOrderStatus

WorkOrder.Status

You can’t read or update this standard value set or picklist field.

735

GLOSSARY
A |B |C |D |E |F |G |H |I |J |K |L |M |N |O |P |Q |R |S |T |U |V |W |X |Y |Z

A
Apex
Apex is a strongly typed, object-oriented programming language that allows developers to execute flow and transaction control
statements on the Force.com platform server in conjunction with calls to the Force.com API. Using syntax that looks like Java and
acts like database stored procedures, Apex enables developers to add business logic to most system events, including button clicks,
related record updates, and Visualforce pages. Apex code can be initiated by Web service requests and from triggers on objects.
Apex-Managed Sharing
Enables developers to programmatically manipulate sharing to support their application’s behavior. Apex-managed sharing is only
available for custom objects.
App
Short for “application.” A collection of components such as tabs, reports, dashboards, and Visualforce pages that address a specific
business need. Salesforce provides standard apps such as Sales and Service. You can customize the standard apps to match the way
you work. In addition, you can package an app and upload it to the AppExchange along with related components such as custom
fields, custom tabs, and custom objects. Then, you can make the app available to other Salesforce users from the AppExchange.
AppExchange
The AppExchange is a sharing interface from Salesforce that allows you to browse and share apps and services for the Force.com
platform.
AppExchange Upgrades
Upgrading an app is the process of installing a newer version.
Application Programming Interface (API)
The interface that a computer system, library, or application provides to allow other computer programs to request services from it
and exchange data.
Asynchronous Calls
A call that does not return results immediately because the operation may take a long time. Calls in the Metadata API and Bulk API
are asynchronous.

B
Boolean Operators
You can use Boolean operators in report filters to specify the logical relationship between two values. For example, the AND operator
between two values yields search results that include both values. Likewise, the OR operator between two values yields search results
that include either value.
Bulk API
The REST-based Bulk API is optimized for processing large sets of data. It allows you to query, insert, update, upsert, or delete a large
number of records asynchronously by submitting a number of batches which are processed in the background by Salesforce. See
also SOAP API.

736

Glossary

C
Class, Apex
A template or blueprint from which Apex objects are created. Classes consist of other classes, user-defined methods, variables,
exception types, and static initialization code. In most cases, Apex classes are modeled on their counterparts in Java.
Client App
An app that runs outside the Salesforce user interface and uses only the Force.com API or Bulk API. It typically runs on a desktop or
mobile device. These apps treat the platform as a data source, using the development model of whatever tool and platform for
which they are designed.
Component, Metadata
A component is an instance of a metadata type in the Metadata API. For example, CustomObject is a metadata type for custom
objects, and the MyCustomObject__c component is an instance of a custom object. A component is described in an XML file
and it can be deployed or retrieved using the Metadata API, or tools built on top of it, such as the Force.com IDE or the Force.com
Migration Tool.
Component, Visualforce
Something that can be added to a Visualforce page with a set of tags, for example, . Visualforce includes a
number of standard components, or you can create your own custom components.
Component Reference, Visualforce
A description of the standard and custom Visualforce components that are available in your organization. You can access the
component library from the development footer of any Visualforce page or the Visualforce Developer's Guide.
Controller, Visualforce
An Apex class that provides a Visualforce page with the data and business logic it needs to run. Visualforce pages can use the standard
controllers that come by default with every standard or custom object, or they can use custom controllers.
Controlling Field
Any standard or custom picklist or checkbox field whose values control the available values in one or more corresponding dependent
fields.
Custom App
See App.
Custom Field
A field that can be added in addition to the standard fields to customize Salesforce for your organization’s needs.
Custom Help
Custom text administrators create to provide users with on-screen information specific to a standard field, custom field, or custom
object.
Custom Links
Custom links are URLs defined by administrators to integrate your Salesforce data with external websites and back-office systems.
Formerly known as Web links.
Custom Object
Custom records that allow you to store information unique to your organization.
Custom S-Control
Note: S-controls have been superseded by Visualforce pages. After March 2010 organizations that have never created
s-controls, as well as new organizations, won't be allowed to create them. Existing s-controls will remain unaffected, and can
still be edited.
Custom Web content for use in custom links. Custom s-controls can contain any type of content that you can display in a browser,
for example a Java applet, an Active-X control, an Excel file, or a custom HTML Web form.

737

Glossary

D
Database
An organized collection of information. The underlying architecture of the Force.com platform includes a database where your data
is stored.
Database Table
A list of information, presented with rows and columns, about the person, thing, or concept you want to track. See also Object.
Data Manipulation Language (DML)
An Apex method or operation that inserts, updates, or deletes records.
Decimal Places
Parameter for number, currency, and percent custom fields that indicates the total number of digits you can enter to the right of a
decimal point, for example, 4.98 for an entry of 2. Note that the system rounds the decimal numbers you enter, if necessary. For
example, if you enter 4.986 in a field with Decimal Places of 2, the number rounds to 4.99. Salesforce uses the round half-up
rounding algorithm. Half-way values are always rounded up. For example, 1.45 is rounded to 1.5. –1.45 is rounded to –1.5.
Dependent Field
Any custom picklist or multi-select picklist field that displays available values based on the value selected in its corresponding
controlling field.
Developer Edition
A free, fully-functional Salesforce organization designed for developers to extend, integrate, and develop with the Force.com platform.
Developer Edition accounts are available on developer.salesforce.com.
Salesforce Developers
The Salesforce Developers website at developer.salesforce.com provides a full range of resources for platform developers, including
sample code, toolkits, an online developer community, and the ability to obtain limited Force.com platform environments.
Document Library
A place to store documents without attaching them to accounts, contacts, opportunities, or other records.

E
Email Alert
Email alerts are actions that send emails, using a specified email template, to specified recipients.
Email Template
A form email that communicates a standard message, such as a welcome letter to new employees or an acknowledgement that a
customer service request has been received. Email templates can be personalized with merge fields, and can be written in text,
HTML, or custom format.
Enterprise Edition
A Salesforce edition designed for larger, more complex businesses.
Enterprise WSDL
A strongly-typed WSDL for customers who want to build an integration with their Salesforce organization only, or for partners who
are using tools like Tibco or webMethods to build integrations that require strong typecasting. The downside of the Enterprise WSDL
is that it only works with the schema of a single Salesforce organization because it is bound to all of the unique objects and fields
that exist in that organization's data model.
Entity Relationship Diagram (ERD)
A data modeling tool that helps you organize your data into entities (or objects, as they are called in the Force.com platform) and
define the relationships between them. ERD diagrams for key Salesforce objects are published in the SOAP API Developer's Guide.

738

Glossary

Enumeration Field
An enumeration is the WSDL equivalent of a picklist field. The valid values of the field are restricted to a strict set of possible values,
all having the same data type.

F
Field
A part of an object that holds a specific piece of information, such as a text or currency value.
Field-Level Security
Settings that determine whether fields are hidden, visible, read only, or editable for users. Available in Professional, Enterprise,
Unlimited, Performance, and Developer Editions.
Filter Condition/Criteria
Condition on particular fields that qualifies items to be included in a list view or report, such as “State equals California.”
Force.com
The Salesforce platform for building applications in the cloud. Force.com combines a powerful user interface, operating system, and
database to allow you to customize and deploy applications in the cloud for your entire enterprise.
Force.com IDE
An Eclipse plug-in that allows developers to manage, author, debug and deploy Force.com applications in the Eclipse development
environment.
Force.com Migration Tool
A toolkit that allows you to write an Apache Ant build script for migrating Force.com components between a local file system and
a Salesforce organization.
Foreign Key
A field whose value is the same as the primary key of another table. You can think of a foreign key as a copy of a primary key from
another table. A relationship is made between two tables by matching the values of the foreign key in one table with the values of
the primary key in another.
Formula Field
A type of custom field. Formula fields automatically calculate their values based on the values of merge fields, expressions, or other
values.
Function
Built-in formulas that you can customize with input parameters. For example, the DATE function creates a date field type from a
given year, month, and day.

G
Gregorian Year
A calendar based on a 12-month structure used throughout much of the world.

H
HTTP Debugger
An application that can be used to identify and inspect SOAP requests that are sent from the AJAX Toolkit. They behave as proxy
servers running on your local machine and allow you to inspect and author individual requests.

739

Glossary

I
ID
See Salesforce Record ID.
Inline S-Control
Note: S-controls have been superseded by Visualforce pages. After March 2010 organizations that have never created
s-controls, as well as new organizations, won't be allowed to create them. Existing s-controls will remain unaffected, and can
still be edited.
An s-control that displays within a record detail page or dashboard, rather than on its own page.
Instance
The cluster of software and hardware represented as a single logical server that hosts an organization's data and runs their applications.
The Force.com platform runs on multiple instances, but data for any single organization is always stored on a single instance.
Integration User
A Salesforce user defined solely for client apps or integrations. Also referred to as the logged-in user in a SOAP API context.
ISO Code
The International Organization for Standardization country code, which represents each country by two letters.

J
Junction Object
A custom object with two master-detail relationships. Using a custom junction object, you can model a “many-to-many” relationship
between two objects. For example, you may have a custom object called “Bug” that relates to the standard case object such that a
bug could be related to multiple cases and a case could also be related to multiple bugs.

K
No Glossary items for this entry.

L
License Management Application (LMA)
A free AppExchange app that allows you to track sales leads and accounts for every user who downloads your managed package
(app) from the AppExchange.
License Management Organization (LMO)
The Salesforce organization that you use to track all the Salesforce users who install your package. A license management organization
must have the License Management Application (LMA) installed. It automatically receives notification every time your package is
installed or uninstalled so that you can easily notify users of upgrades. You can specify any Enterprise, Unlimited, Performance, or
Developer Edition organization as your license management organization. For more information, go to
http://www.salesforce.com/docs/en/lma/index.htm.
List View
A list display of items (for example, accounts or contacts) based on specific criteria. Salesforce provides some predefined views.

740

Glossary

In the Agent console, the list view is the top frame that displays a list view of records based on specific criteria. The list views you
can select to display in the console are the same list views defined on the tabs of other objects. You cannot create a list view within
the console.
Local Project
A .zip file containing a project manifest (package.xml file) and one or more metadata components.
Locale
The country or geographic region in which the user is located. The setting affects the format of date and number fields, for example,
dates in the English (United States) locale display as 06/30/2000 and as 30/06/2000 in the English (United Kingdom) locale.
In Professional, Enterprise, Unlimited, Performance, and Developer Edition organizations, a user’s individual Locale setting overrides
the organization’s Default Locale setting. In Personal and Group Editions, the organization-level locale field is called Locale,
not Default Locale.
Logged-in User
In a SOAP API context, the username used to log into Salesforce. Client applications run with the permissions and sharing of the
logged-in user. Also referred to as an integration user.
Lookup Field
A type of field that contains a linkable value to another record. You can display lookup fields on page layouts where the object has
a lookup or master-detail relationship with another object. For example, cases have a lookup relationship with assets that allows
users to select an asset using a lookup dialog from the case edit page and click the name of the asset from the case detail page.

M
Managed Package
A collection of application components that is posted as a unit on the AppExchange and associated with a namespace and possibly
a License Management Organization. To support upgrades, a package must be managed. An organization can create a single
managed package that can be downloaded and installed by many different organizations. Managed packages differ from unmanaged
packages by having some locked components, allowing the managed package to be upgraded later. Unmanaged packages do not
include locked components and cannot be upgraded. In addition, managed packages obfuscate certain components (like Apex) on
subscribing organizations to protect the intellectual property of the developer.
Manifest File
The project manifest file (package.xml) lists the XML components to retrieve or deploy when working with the Metadata API,
or clients built on top of the Metadata API, such as the Force.com IDE or the Force.com Migration Tool.
Manual Sharing
Record-level access rules that allow record owners to give read and edit permissions to other users who might not have access to
the record any other way.
Many-to-Many Relationship
A relationship where each side of the relationship can have many children on the other side. Many-to-many relationships are
implemented through the use of junction objects.
Master-Detail Relationship
A relationship between two different types of records that associates the records with each other. For example, accounts have a
master-detail relationship with opportunities. This type of relationship affects record deletion, security, and makes the lookup
relationship field required on the page layout.
Metadata
Information about the structure, appearance, and functionality of an organization and any of its parts. Force.com uses XML to describe
metadata.

741

Glossary

Metadata WSDL
A WSDL for users who want to use the Force.com Metadata API calls.
Multitenancy
An application model where all users and apps share a single, common infrastructure and code base.

N
Namespace
In a packaging context, a one- to 15-character alphanumeric identifier that distinguishes your package and its contents from packages
of other developers onAppExchange, similar to a domain name. Salesforce automatically prepends your namespace prefix, followed
by two underscores (“__”), to all unique component names in your Salesforce organization.
Native App
An app that is built exclusively with setup (metadata) configuration on Force.com. Native apps do not require any external services
or infrastructure.

O
Object
An object allows you to store information in your Salesforce organization. The object is the overall definition of the type of information
you are storing. For example, the case object allow you to store information regarding customer inquiries. For each object, your
organization will have multiple records that store the information about specific instances of that type of data. For example, you
might have a case record to store the information about Joe Smith's training inquiry and another case record to store the information
about Mary Johnson's configuration issue.
Object-Level Help
Custom help text that you can provide for any custom object. It displays on custom object record home (overview), detail, and edit
pages, as well as list views and related lists.
Object-Level Security
Settings that allow an administrator to hide whole objects from users so that they don't know that type of data exists. Object-level
security is specified with object permissions.
onClick JavaScript
JavaScript code that executes when a button or link is clicked.
One-to-Many Relationship
A relationship in which a single object is related to many other objects. For example, an account may have one or more related
contacts.
Organization-Wide Defaults
Settings that allow you to specify the baseline level of data access that a user has in your organization. For example, you can set
organization-wide defaults so that any user can see any record of a particular object that is enabled via their object permissions, but
they need extra permissions to edit one.
Outbound Message
An outbound message sends information to a designated endpoint, like an external service. Outbound messages are configured
from Setup. You must configure the external endpoint and create a listener for the messages using the SOAP API.
Overlay
An overlay displays additional information when you hover your mouse over certain user interface elements. Depending on the
overlay, it will close when you move your mouse away, click outside of the overlay, or click a close button.

742

Glossary

Owner
Individual user to which a record (for example, a contact or case) is assigned.

P
Package
A group of Force.com components and applications that are made available to other organizations through the AppExchange. You
use packages to bundle an app along with any related components so that you can upload them to AppExchange together.
Partner WSDL
A loosely-typed WSDL for customers, partners, and ISVs who want to build an integration or an AppExchange app that can work
across multiple Salesforce organizations. With this WSDL, the developer is responsible for marshaling data in the correct object
representation, which typically involves editing the XML. However, the developer is also freed from being dependent on any particular
data model or Salesforce organization. Contrast this with the Enterprise WSDL, which is strongly typed.
Picklist
Selection list of options available for specific fields in a Salesforce object, for example, the Industry field for accounts. Users can
choose a single value from a list of options rather than make an entry directly in the field. See also Master Picklist.
Picklist (Multi-Select)
Selection list of options available for specific fields in a Salesforce object. Multi-select picklists allow users to choose one or more
values. Users can choose a value by double clicking on it, or choose additional values from a scrolling list by holding down the CTRL
key while clicking a value and using the arrow icon to move them to the selected box.
Picklist Values
Selections displayed in drop-down lists for particular fields. Some values come predefined, and other values can be changed or
defined by an administrator.
Primary Key
A relational database concept. Each table in a relational database has a field in which the data value uniquely identifies the record.
This field is called the primary key. The relationship is made between two tables by matching the values of the foreign key in one
table with the values of the primary key in another.
Production Organization
A Salesforce organization that has live users accessing data.
Professional Edition
A Salesforce edition designed for businesses who need full-featured CRM functionality.

Q
Queue
A holding area for items before they are processed. Salesforce uses queues in a number of different features and technologies.
Query String Parameter
A name-value pair that's included in a URL, typically after a '?' character. For example:
https://yourInstance.salesforce.com/001/e?name=value

743

Glossary

R
Record
A single instance of a Salesforce object. For example, “John Jones” might be the name of a contact record.
Record Name
A standard field on all Salesforce objects. Whenever a record name is displayed in a Force.com application, the value is represented
as a link to a detail view of the record. A record name can be either free-form text or an autonumber field. Record Name does
not have to be a unique value.
Record Type
A record type is a field available for certain records that can include some or all of the standard and custom picklist values for that
record. You can associate record types with profiles to make only the included picklist values available to users with that profile.
Record-Level Security
A method of controlling data in which you can allow a particular user to view and edit an object, but then restrict the records that
the user is allowed to see.
Recycle Bin
A page that lets you view and restore deleted information. Access the Recycle Bin by using the link in the sidebar.
Related Object
Objects chosen by an administrator to display in the Agent console's mini view when records of a particular type are shown in the
console's detail view. For example, when a case is in the detail view, an administrator can choose to display an associated account,
contact, or asset in the mini view.
Relationship
A connection between two objects, used to create related lists in page layouts and detail levels in reports. Matching values in a
specified field in both objects are used to link related data; for example, if one object stores data about companies and another
object stores data about people, a relationship allows you to find out which people work at the company.
Relationship Query
In a SOQL context, a query that traverses the relationships between objects to identify and return results. Parent-to-child and
child-to-parent syntax differs in SOQL queries.
Report Type
A report type defines the set of records and fields available to a report based on the relationships between a primary object and its
related objects. Reports display only records that meet the criteria defined in the report type. Salesforce provides a set of pre-defined
standard report types; administrators can create custom report types as well.
Role Hierarchy
A record-level security setting that defines different levels of users such that users at higher levels can view and edit information
owned by or shared with users beneath them in the role hierarchy, regardless of the organization-wide sharing model settings.
Roll-Up Summary Field
A field type that automatically provides aggregate values from child records in a master-detail relationship.

S
SaaS
See Software as a Service (SaaS).

744

Glossary

S-Control
Note: S-controls have been superseded by Visualforce pages. After March 2010 organizations that have never created
s-controls, as well as new organizations, won't be allowed to create them. Existing s-controls will remain unaffected, and can
still be edited.
Custom Web content for use in custom links. Custom s-controls can contain any type of content that you can display in a browser,
for example a Java applet, an Active-X control, an Excel file, or a custom HTML Web form.
Salesforce Record ID
A unique 15- or 18-character alphanumeric string that identifies a single record in Salesforce.
Salesforce SOA (Service-Oriented Architecture)
A powerful capability of Force.com that allows you to make calls to external Web services from within Apex.
Sandbox
A nearly identical copy of a Salesforce production organization for development, testing, and training. The content and size of a
sandbox varies depending on the type of sandbox and the editioin of the production organization associated with the sandbox.
Search Layout
The organization of fields included in search results, in lookup dialogs, and in the key lists on tab home pages.
Session ID
An authentication token that is returned when a user successfully logs in to Salesforce. The Session ID prevents a user from having
to log in again every time he or she wants to perform another action in Salesforce. Different from a record ID or Salesforce ID, which
are terms for the unique ID of a Salesforce record.
Session Timeout
The period of time after login before a user is automatically logged out. Sessions expire automatically after a predetermined length
of inactivity, which can be configured in Salesforce from Setup by clicking Security Controls. The default is 120 minutes (two hours).
The inactivity timer is reset to zero if a user takes an action in the Web interface or makes an API call.
Setup
A menu where administrators can customize and define organization settings and Force.com apps. Depending on your organization’s
user interface settings, Setup may be a link in the user interface header or in the drop-down list under your name.
Sharing
Allowing other users to view or edit information you own. There are different ways to share data:
• Sharing Model—defines the default organization-wide access levels that users have to each other’s information and whether
to use the hierarchies when determining access to data.
• Role Hierarchy—defines different levels of users such that users at higher levels can view and edit information owned by or
shared with users beneath them in the role hierarchy, regardless of the organization-wide sharing model settings.
• Sharing Rules—allow an administrator to specify that all information created by users within a given group or role is automatically
shared to the members of another group or role.
• Manual Sharing—allows individual users to share records with other users or groups.
• Apex-Managed Sharing—enables developers to programmatically manipulate sharing to support their application’s behavior.
See Apex-Managed Sharing.
Sharing Model
Behavior defined by your administrator that determines default access by users to different types of records.
Sharing Rule
Type of default sharing created by administrators. Allows users in a specified group or role to have access to all information created
by users within a given group or role.

745

Glossary

Sites
Force.com Sites enables you to create public websites and applications that are directly integrated with your Salesforce
organization—without requiring users to log in with a username and password.
Snippet
Note: S-controls have been superseded by Visualforce pages. After March 2010 organizations that have never created
s-controls, as well as new organizations, won't be allowed to create them. Existing s-controls will remain unaffected, and can
still be edited.
A type of s-control that is designed to be included in other s-controls. Similar to a helper method that is used by other methods in
a piece of code, a snippet allows you to maintain a single copy of HTML or JavaScript that you can reuse in multiple s-controls.
SOAP (Simple Object Access Protocol)
A protocol that defines a uniform way of passing XML-encoded data.
Software as a Service (SaaS)
A delivery model where a software application is hosted as a service and provided to customers via the Internet. The SaaS vendor
takes responsibility for the daily maintenance, operation, and support of the application and each customer's data. The service
alleviates the need for customers to install, configure, and maintain applications with their own hardware, software, and related IT
resources. Services can be delivered using the SaaS model to any market segment.
SOQL (Salesforce Object Query Language)
A query language that allows you to construct simple but powerful query strings and to specify the criteria that should be used to
select data from the Force.com database.
SOSL (Salesforce Object Search Language)
A query language that allows you to perform text-based searches using the Force.com API.
Standard Object
A built-in object included with the Force.com platform. You can also build custom objects to store information that is unique to
your app.
System Log
Part of the Developer Console, a separate window console that can be used for debugging code snippets. Enter the code you want
to test at the bottom of the window and click Execute. The body of the System Log displays system resource information, such as
how long a line took to execute or how many database calls were made. If the code did not run to completion, the console also
displays debugging information.

T
Test Method
An Apex class method that verifies whether a particular piece of code is working properly. Test methods take no arguments, commit
no data to the database, and can be executed by the runTests() system method either through the command line or in an
Apex IDE, such as the Force.com IDE.
Translation Workbench
The Translation Workbench lets you specify languages you want to translate, assign translators to languages, create translations for
customizations you’ve made to your Salesforce organization, and override labels and translations from managed packages. Everything
from custom picklist values to custom fields can be translated so your global users can use all of Salesforce in their language.
Trigger
A piece of Apex that executes before or after records of a particular type are inserted, updated, or deleted from the database. Every
trigger runs with a set of context variables that provide access to the records that caused the trigger to fire, and all triggers run in
bulk mode—that is, they process several records at once, rather than just one record at a time.

746

Glossary

Trigger Context Variable
Default variables that provide access to information about the trigger and the records that caused it to fire.

U
Unit Test
A unit is the smallest testable part of an application, usually a method. A unit test operates on that piece of code to make sure it
works correctly. See also Test Method.
Unlimited Edition
Unlimited Edition is Salesforce’s solution for maximizing your success and extending that success across the entire enterprise through
the Force.com platform.
Unmanaged Package
A package that cannot be upgraded or controlled by its developer.
URL (Uniform Resource Locator)
The global address of a website, document, or other resource on the Internet. For example, http://www.salesforce.com.
URL S-Control
Note: S-controls have been superseded by Visualforce pages. After March 2010 organizations that have never created
s-controls, as well as new organizations, won't be allowed to create them. Existing s-controls will remain unaffected, and can
still be edited.
An s-control that contains an external URL that hosts the HTML that should be rendered on a page. When saved this way, the HTML
is hosted and run by an external website. URL s-controls are also called Web controls.

V
Validation Rule
A rule that prevents a record from being saved if it does not meet the standards that are specified.
Visualforce
A simple, tag-based markup language that allows developers to easily define custom pages and components for apps built on the
platform. Each tag corresponds to a coarse or fine-grained component, such as a section of a page, a related list, or a field. The
components can either be controlled by the same logic that is used in standard Salesforce pages, or developers can associate their
own logic with a controller written in Apex.

W
Web Control
See URL S-Control.
Web Links
See Custom Links.
Web Service
A mechanism by which two applications can easily exchange data over the Internet, even if they run on different platforms, are
written in different languages, or are geographically remote from each other.

747

Glossary

WebService Method
An Apex class method or variable that can be used by external systems, like a mash-up with a third-party application. Web service
methods must be defined in a global class.
Web Services API
A Web services application programming interface that provides access to your Salesforce organization's information. See also SOAP
API and Bulk API.
Web Tab
A custom tab that allows your users to use external websites from within the application.
Workflow Action
A workflow action, such as an email alert, field update, outbound message, or task, fires when the conditions of a workflow rule are
met.
Workflow Email Alert
A workflow action that sends an email when a workflow rule is triggered. Unlike workflow tasks, which can only be assigned to
application users, workflow alerts can be sent to any user or contact, as long as they have a valid email address.
Workflow Field Update
A workflow action that changes the value of a particular field on a record when a workflow rule is triggered.
Workflow Outbound Message
A workflow action that sends data to an external Web service, such as another cloud computing application. Outbound messages
are used primarily with composite apps.
Workflow Queue
A list of workflow actions that are scheduled to fire based on workflow rules that have one or more time-dependent workflow actions.
Workflow Rule
A workflow rule sets workflow actions into motion when its designated conditions are met. You can configure workflow actions to
execute immediately when a record meets the conditions in your workflow rule, or set time triggers that execute the workflow
actions on a specific day.
Workflow Task
A workflow action that assigns a task to an application user when a workflow rule is triggered.
WSDL (Web Services Description Language) File
An XML file that describes the format of messages you send and receive from a Web service. Your development environment's SOAP
client uses the Salesforce Enterprise WSDL or Partner WSDL to communicate with Salesforce using the SOAP API.

X
XML (Extensible Markup Language)
A markup language that enables the sharing and transportation of structured data. All Force.com components that are retrieved or
deployed through the Metadata API are represented by XML definitions.

Y
No Glossary items for this entry.

748

Glossary

Z
Zip File
A data compression and archive format.
A collection of files retrieved or deployed by the Metadata API. See also Local Project.

749

INDEX
component 686

A
Account Team Roles 17
AccountSettings components 558
ActionLinkGroupTemplate component 120
ActionOverride component 244
ActivitiesSettings component 559
AddressSettings component 563
AllOrNoneHeader header 714
Analytics 405
AnalyticSnapshot component 124
ApexClass component 136
ApexComponent component 138
ApexPage component 139
ApexTestSuite component 141
ApexTrigger component 142
API support policy 3
AppMenu component 144
ApprovalProcess components 147
ArticleType component
Channel Layout 132
Layout 130, 333
AssignmentRules component 158
AuraDefinitionBundle component 160
AuthProvider object 163
AutoResponseRules component 167

B
Backward compatibilty 3
BaseSharingRule component 639
BusinessHoursSettings component 567
BusinessProcess component 246

C
call deprecation 3
CallCenter component 170
CallOptions header 716
Calls
cancelDeploy 43
checkDeployStatus 42
checkRetrieveStatus 56
checkStatus 79
create (asynchronous) 71
createMetadata (synchronous) 59
delete (asynchronous) 73

Calls (continued)
deleteMetadata (synchronous) 68
deploy 33
deployRecentValidation 45
describeMetadata 80
describeValueType 81
listMetadata 84, 86
readMetadata (synchronous) 62
renameMetadata (synchronous) 70
retrieve 50
update (asynchronous) 75
updateMetadata (synchronous) 63
upsertMetadata (synchronous) 66
CampaignInfluenceModel component 172
cancel deploy call 43
CaseSettings components 571
Certificate component 173
Channel Layout (for article types) 132
ChatterAnswersSettings component 578
checkDeployStatus metadata call 42
checkRetrieveStatus metadata call 56
checkStatus metadata call 79
CleanDataService component 174
Community (Zone)component 179
CommunityTemplateDefinition component 182, 196
CommunityThemeDefinition component 186
CompactLayout component 248
CompanySettings component 580
component 222
Components
AccountSettings 558
ActionLinkGroupTempalte 120
ActionOverride 244
ActivitiesSettings 559
Activity Settings 559
AddressSettings 563
AnalyticSnapshot 124
ApexClass 136
ApexComponent 138
ApexPage 139
ApexTestSuite 141
ApexTrigger 142
AppMenu 144
ApprovalProcess 147
Article Type 133
ArticleType 127

750

Index

Components (continued)
AssignmentRules 158
AuraDefinitionBundle 160
AutoResponseRules 167
BaseSharingRule 639
BusinessHoursSettings 567
BusinessProcess 246
CallCenter 170
CampaignInfluenceModel 172
CaseSettings 571
Certificate 173
Channel Layout (for article types) 132
ChatterAnswersSettings 578
CleanDataService 174
Community (Zone) 179
CommunityTemplateDefinition 182, 196
CommunityThemeDefinition 186
CompactLayout 248
CompanySettings 580
ConnectedApp 187
ContractSettings 581
CorsWhitelistOrigin 198
CriteriaBasedSharingRule 640
CspTrustedSite 200
custom metadata type 226
CustomApplication 201
CustomApplicationComponent 220
CustomFeedFilter 222
CustomField 250
CustomLabels 224
CustomMetadata 229
CustomObject 233
CustomObjectTranslation 288
CustomPageWebLink 297
CustomPermission 300
CustomSite 302
CustomTab 308
CustomValue 311
Dashboard 314
DelegateGroup 338
Dependent Picklist (see Picklist) 269
Document 340
DuplicateRule 342
EclairGeoData 347
EmailTemplate 349
EntitlementProcess 353
EntitlementSettings 582
EntitlementTemplate 357
EscalationRules 358

Components (continued)
ExternalDataSource 361
ExternalServiceRegistration 401
FieldSet 261
FileUploadAndDownloadSecuritySettings 584
FlexiPage 365
Flow 373
Folder 403
FolderShare 405
ForecastingSettings 588
GlobalPicklist 407
GlobalPicklistValue 408
GlobalValueSet 411
GlobalValueSetTranslation 413
Group 414
HistoryRetentionPolicy 262
HomePageComponent 415
HomePageLayout 417
IdeasSettings 598
InstalledPackage 418
KeywordList 419
KnowledgeSettings 599
Layout 421
Layout (for article types) 130, 333
LeadConvertSettings 605
Letterhead 441
list of types 106
ListView 263
LiveAgentSettings 607
LiveChatAgentConfig 444
LiveChatButton 448
LiveChatDeployment 451
LiveChatSensitiveDataRule 453
ManagedTopics 455
MatchingRule 457
Metadata 460
MetadataWithContent 461
MilestoneType 461
MobileSettings 607
ModerationRule 462
NamedCredential 466
NamedFilter 266
NameSettings 610
network 467
OpportunitySettings 611
OrderSettings 613
OrgPreferenceSettings 614
OwnerSharingRule 646
PathAssistant 482

751

Index

Components (continued)
PathAssistantSettings 616
PermissionSet 484
PersonalJourneySettings 617
Picklist 269
PlatformCachePartition 491
Portal 493
PostTemplate 495
ProductSettings 617
Profile 496
ProfileActionOverride 509
Queue 511
QuickAction 512
QuoteSettings 618
RecordType 273
RemoteSiteSetting 517
Report 519
ReportType 545
Role 549
RoleOrTerritory 550
SamlSsoConfig 552
Scontrol 555
SearchLayouts 275
SearchSettings 619
SecuritySettings 622
Settings 557
SharedTo 629
SharingBaseRule 631
SharingReason 278
SharingRecalculation 279
SharingRules 633
SharingSet 652
SiteDotCom 655
Skill 656
StandardValueSet 658
StandardValueSetTranslation 659
StaticResource 660
SynonymDictionary 662
Territory 664
Territory2 665
Territory2Model 669
Territory2Rule 671
Territory2Settings 628
Territory2Type 673
TransactionSecurityPolicy 675
Translations 677
unsupported 118
UserCriteria 686
ValidationRule 279

Components (continued)
WaveApplication 687
WaveDashboard 689
WaveDataflow 688
WaveDataset 690
WaveLens 690
WaveTemplateBundle 692
WaveXmd 693
WebLink 281
Workflow 698
Components in deployments 119
ConnectedApp component 187
ContractSettings component 581
CorsWhitelistOrigin component 198
create call (asynchronous) 71
createMetadata call (synchronous) 59
CriteriaBasedSharingRule component 640
CspTrustedSite component 200
Custom metadada type component 226
CustomApplication component 201
CustomApplicationComponent component 220
CustomField component 250
CustomLabels component 224
CustomMetadata component 229
CustomObject
WebLink component 281
CustomObject component 233
CustomObjectTranslation
language support 720, 726
CustomObjectTranslation component 288
CustomPageWebLink component 297
CustomPermission component 300
CustomSite component 302
CustomTab component 308
CustomValue component 311

D
Dashboard component 314
DebuggingHeader header 717
DelegateGroup component 338
delete call (asynchronous) 73
Delete components 41
deleteMetadata call (synchronous) 68
Dependent Picklist 269
Deploy 15
deploy call
running tests 23–25
Deployment issues 119
deployRecentValidation call 45

752

Index

Deprecated calls 3
describeMetadata call 80
describeValueType call 81
destructiveChanges.xml 41
destructiveChangesPost.xml 41
destructiveChangesPre.xml 41
Developer resources 3
Development platforms 2
Document component 340
DuplicateRule component 342

E
EclairGeoData component 347
Editions 1
EmailTemplate component 349
EntitlementProcess components 353
EntitlementSettings components 582
EntitlementTemplate component 357
Error handling 32
EscalationRules component 358
Expiration of session ID 32
ExternalDataSource component 361
ExternalServiceRegistration component 401

F
Field types 285
FieldSet component 261
File-based metadata 15
FileUploadAndDownloadSecuritySettings component 584
FlexiPage component 365
Flow component 373
FlowDefinition 402
Folder component 403
ForecastingSettings component 588

G
Global picklist 311, 407–408, 411
Global value set 411
global value sets
translation of 413
GlobalPicklist component 407
GlobalPicklistValue component 408
GlobalValueSet component 311, 411
GlobalValueSetTranslation component 413
Group component 414

H
Headers
AllOrNoneHeader 714

Headers (continued)
CallOptions 716
DebuggingHeader 717
SessionHeader 719
HistoryRetentionPolicy component 262
HomePageComponent component 415
HomePageLayout component 417

I
IdeasSettings component 598
InstalledPackage component 418

K
KeywordList component 419
KnowledgeSettings component 599

L
Layout component 421
Layout component (for article types) 130, 333
LeadConvertSettings components 605
Letterhead component 441
listMetadata call 84
ListMetadataQuery 86
ListView component 263
LiveAgentSettings components 607
LiveChatAgentConfig components 444
LiveChatButton components 448
LiveChatDeployment components 451
LiveChatSensitiveDataRule component 453

M
ManagedTopics component 455
Manifest file 15, 17
MatchingRule component 457
Metadata calls 1
Metadata component 460
Metadata components 117
Metadata types 106, 117–118
MetadataWithContent component 461
MilestoneType component 461
MobileSettings component 607
ModerationRule component 462

N
NamedCredential component 466
NamedFilter component 266
NameSettings component 610
Network component 467

753

Index

O
Object relationship 545
Objects
AuthProvider 163
Opportunity Team Roles 17
OpportunitySettings component 611
OrderSettings component 613
OrgPreferenceSettings component 614
Outer join 545
OwnerSharingRule component 646

P
Package 480
Package versions 136
package.xml
samples 17
PackageVersion 136
PathAssistant component 482
PathAssistantSettings component 616
PermissionSet component 484
PersonalJourneySettings component 617
Picklist component 269
Picklist value set 407–408
PicklistValue component 408
PlatformCachePartition component 491
Portal component 493
PostTemplate component 495
Prerequisites 4
ProductSettings component 617
Profile component 496
ProfileActionOverride component 509

Q
Queue component 511
Quick start
Generate WSDLs 4
Import WSDLs 5
Java sample 6
Prerequisites 4
QuickAction component 512
QuoteSettings component 618

R
readMetadata call (synchronous) 62
RecordType component 273
Recycle Bin 340
RemoteSiteSetting component 517
renameMetadata call (synchronous) 70
Report component 519

ReportType component 545
Retrieve 15
retrieve call 50
RetrieveRequest 55
Role component 549
RoleOrTerritory component 550

S
SamlSsoConfig component 552
Sample code 6
Sandbox 1
Scontrol component 555
SearchLayouts component 275
SearchSettings components 619
SecuritySettings component 622
Session ID expiration 32
SessionHeader header 719
Settings 557
SharedTo component 629
SharingBaseRule component 631
SharingReason component 278
SharingRecalculation component 279
SharingRules 633
SharingSet component 652
SiteDotCom component 655
Skill component 656
Standard Picklist
standard value set names in API version 38.0 and later 733
standard value sets
translation of 659
Standards compliance 2
StandardValueSet
names 733
StandardValueSetTranslation component 659
StaticResource component 660
Support policy 3
Supported calls 117
SynonymDictionary component 662

T
Territory component 664
Territory2 component 665
Territory2Model component 669
Territory2Rule component 671
Territory2Settings component 628
Territory2Type component 673
TransactionSecurityPolicy component 675
Translations component 677
Types of fields 285

754

Index

U
Understanding metadata calls and components 1
update call (asynchronous) 75
updateMetadata call (synchronous) 63
upsertMetadata call (synchronous) 66
Usernames 25

V
ValidationRule component 279
Versions 136
Visualforce component, see ApexComponent 138
Visualforce page, see ApexPage 139

WaveDashboard component 689
WaveDataflow component 688
WaveDataset component 690
WaveLens component 690
WaveTemplateBundle component 692
WaveXmd component 693
WebLink component 281
Workflow component 698
WSC 5
WSDL integration 4–5

Z
Zip file 15

W
WaveApplication component 687

755

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : Yes
Create Date                     : 2017:04:17 17:20:06Z
Author                          : salesforce.com, inc.
Date Time Generated             : 2017-04-17T10:19:40.261-07:00
Trapped                         : False
DRC                             : 206.19
Modify Date                     : 2017:04:17 17:20:06Z
Format                          : application/pdf
Title                           : Metadata API Developer Guide
Creator                         : salesforce.com, inc.
Producer                        : XEP 4.20 build 20120720
Creator Tool                    : Unknown
Page Count                      : 765
Page Mode                       : UseOutlines

EXIF Metadata provided by EXIF.tools

Metadata API Developer Guide

Congratulations

Navigation menu

Versions of this User Manual:

Views

Navigation