Salesforce Metadata API Developer Guide

Metadata API Developer Guide

Version 39.0, Spring ’17

@salesforcedocs

Last updated: April 17, 2017

©

Copyright 2000–2017 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc., as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.

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

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Step 1: Generate or Obtain the Web Service WSDLs for Your Organization

. . . . . . . . . . . . . . . . 4

Step 2: Import the WSDL Files Into Your Development Platform

. . . . . . . . . . . . . . . . . . . . . . . . 5

Step 3: Walk Through the Java Sample Code

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714

CallOptions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716

DebuggingHeader

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717

SessionHeader

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719

APPENDICES

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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

.

1

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

Simple Object Access Protocol (SOAP) 1.1

Website

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

Web Service Description Language (WSDL)

1.1

http://www.w3.org/TR/2001/NOTE-wsdl-20010315

WS-I Basic Profile 1.1

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

2

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.

3

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

4

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.

5

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 com.sforce.soap.enterprise.EnterpriseConnection; import com.sforce.soap.enterprise.LoginResult; import com.sforce.soap.metadata.MetadataConnection; import com.sforce.ws.ConnectionException; import com.sforce.ws.ConnectorConfig;

/**

* Login utility.

*/ public class MetadataLoginUtil { public static MetadataConnection login() throws ConnectionException { final String USERNAME = "[email protected]" ;

// 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);

}

6

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >CustomObject </name >

</types >

<types >

<members >* </members >

<name >CustomTab </name >

</types >

<types >

<members >* </members >

<name >Layout </name >

</types >

<version >39.0

</version >

</Package >

Note the error handling code that follows each API call.

7

Quick Start Step 3: Walk Through the Java Sample Code

Note: This sample requires API version 34.0 or later.

import java.io.*; import java.nio.channels.Channels; import java.nio.channels.FileChannel; import java.nio.channels.ReadableByteChannel; import java.rmi.RemoteException; import 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" )) {

8

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 {

9

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" );

}

10

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);

11

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());

12

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<PackageTypeMembers> listPackageTypes = new ArrayList<PackageTypeMembers>();

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< String > members = new ArrayList< String >(); 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 + "" );

13

Quick Start

}

} return packageManifest;

Step 3: Walk Through the Java Sample Code

14

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.

15

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

<members >* </members >

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >MyCustomObject__c </members >

<name >CustomObject </name >

</types >

<types >

<members >* </members >

<name >CustomTab </name >

</types >

<types >

<members >Standard </members >

<name >Profile </name >

</types >

<version >39.0

</version >

</Package >

The following elements can be defined in package.xml

.

•

<fullName >

contains the name of the server-side package. If no

<fullName >

exists, this is a client-side unpackaged package.

•

<types >

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

<types >

elements in a manifest file.

•

<members >

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

<members >

element and Settings in the name element when retrieving the SecuritySettings component type.

•

<name >

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.

•

<version >

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 .

16

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

<types >

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Account </members >

<name >CustomObject </name >

</types >

<version >39.0

</version >

</Package >

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.

17

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >CustomObject </name >

</types >

<version >39.0

</version >

</Package >

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Industry </members >

<name >StandardValueSet </name >

</types >

<version >39.0

</version >

</Package >

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Account.Industry

</members >

<name >CustomField </name >

</types >

<version >37.0

</version >

</Package >

Note:

The name of a picklist field is case-sensitive.

Note the

objectName.picklistField

syntax in the

<members >

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >SalesTeamRole </members >

18

Deploying and Retrieving Metadata Sample package.xml Manifest Files

<name >StandardValueSet </name >

</types >

<version >39.0

</version >

</Package >

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >OpportunityTeamMember.TeamMemberRole

</members >

<name >CustomField </name >

</types >

<version >37.0

</version >

</Package >

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >MyCustomObject__c.MyCustomField__c

</members >

<name >CustomField </name >

</types >

<types >

<members >Account.SLA__c

</members >

<members >Account.Phone

</members >

<name >CustomField </name >

</types >

<version >39.0

</version >

</Package >

Note the

objectName.field

syntax in the

<members >

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.

19

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Account.AccountTeam

</members >

<name >ListView </name >

</types >

<version >39.0

</version >

</Package >

Note the

objectName.listViewUniqueName

syntax in the

<members >

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

<fullName >

element in package.xml

contains the name of the retrieved package.

If you use an asterisk wildcard in a

<members >

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >myns__MyCustomObject__c </members >

<name >CustomObject </name >

</types >

<version >39.0

</version >

</Package >

Note the

namespacePrefix

__

objectName

syntax in the

<members >

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.

20

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

<members >

element and Settings in the name element when retrieving the SecuritySettings component type.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Security </members >

<name >Settings </name >

</types >

<version >39.0

</version >

</Package >

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Case </members >

<members >Lead </members >

<name >AssignmentRules </name >

</types >

<version >39.0

</version >

</Package >

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

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Case.samplerule

</members >

<members >Lead.newrule

</members >

<name >AssignmentRule </name >

</types >

<version >39.0

</version >

</Package >

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

21

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Lead.testShareRule

</members >

<name >SharingCriteriaRule </name >

</types >

<types >

<members >* </members >

<name >SharingOwnerRule </name >

</types >

<types >

<members >Account.* </members >

<name >SharingTerritoryRule </name >

</types >

<version >33.0

</version >

</Package >

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:

<objectPermissions >

<allowCreate >true </allowCreate >

<allowDelete >true </allowDelete >

<allowEdit >true </allowEdit >

<allowRead >true </allowRead >

<viewAllRecords >false </viewAllRecords >

<modifyAllRecords >false </modifyAllRecords >

<object >MyNamespace__JobRequest__c </object >

</objectPermissions >

22

Deploying and Retrieving Metadata Running Tests in a Deployment

To retrieve:

<types >

<members >MyNamespace__JobRequest__c </members >

<name >CustomObject </name >

</types >

<types >

<members >MyProfile </members >

<name >Profile </name >

</types >

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

23

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();

24

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.

25

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 [email protected]

becomes [email protected]

. 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.

26

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 {

27

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); etc" );

// 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 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());

}

}

28

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.

29

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: " +

30

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);

}

31

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

.

32

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

33

File-Based Calls 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

zipFile

Type

base64

Description

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.

deploy()

DeployOptions

The following deployment options can be selected for this call:

Name

allowMissingFiles

Type

boolean autoUpdatePackage boolean

Description

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.

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.

34

File-Based Calls

Name

checkOnly

Type

boolean ignoreWarnings boolean performRetrieve purgeOnDelete boolean boolean rollbackOnError boolean

35

Description

Do not set this argument for deployment to production orgs.

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()

.

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.

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.

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.

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

.

deploy()

File-Based Calls

Name

runAllTests runTests singlePackage testLevel

Type

boolean string[] boolean

TestLevel (

enumeration of type

string)

Description

(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.

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

.

Indicates whether the specified

.zip

file points to a directory structure with a single package ( true

) or a set of packages

( false)

.

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.

deploy()

36

File-Based Calls

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 com.sforce.soap.metadata.AsyncResult; import com.sforce.soap.metadata.DeployDetails; import com.sforce.soap.metadata.MetadataConnection; import com.sforce.soap.metadata.DeployOptions; import com.sforce.soap.metadata.DeployResult; import com.sforce.soap.metadata.DeployMessage; import com.sforce.soap.metadata.RunTestsResult; import com.sforce.soap.metadata.RunTestFailure; import com.sforce.soap.metadata.CodeCoverageWarning; import com.sforce.soap.enterprise.LoginResult; import com.sforce.soap.enterprise.EnterpriseConnection; import com.sforce.ws.ConnectionException; import 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 = "[email protected]" ; deploy()

37

File-Based Calls

// 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());

} deploy()

38

File-Based Calls 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 ?

"" :

39 deploy()

File-Based Calls

( "(" + 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()); deploy()

40

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:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >MyCustomObject__c </members >

<name >CustomObject </name >

</types >

</Package >

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

:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<version >39.0

</version >

</Package >

41

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:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >SampleClass </members >

<name >ApexClass </name >

</types >

<version >39.0

</version >

</Package >

Sample destructiveChangesPost.xml

, which specifies the custom object to delete after the class update:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >MyCustomObject__c </members >

<name >CustomObject </name >

</types >

</Package >

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()

.

42

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

id

Type

ID includeDetails boolean

Description

ID obtained from an

AsyncResult object returned by

deploy()

or a subsequent

checkDeployStatus()

call.

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

)

43

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

id

Type

string

Description

The ID of the deployment to cancel.

Response

CancelDeployResult

44

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.

45

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;

46

File-Based Calls deployRecentValidation() import com.sforce.soap.metadata.DeployDetails; import com.sforce.soap.metadata.DeployMessage; import com.sforce.soap.metadata.DeployResult; import com.sforce.soap.metadata.MetadataConnection; import com.sforce.soap.metadata.RunTestFailure; import com.sforce.soap.metadata.RunTestsResult; import com.sforce.soap.partner.Connector; import com.sforce.ws.ConnectionException; import 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 {

47

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() + ")" ));

48

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());

49

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

.

50

File-Based Calls

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.

retrieve()

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 java.io.*; import java.util.*; import java.nio.ByteBuffer; import java.nio.channels.*; import java.rmi.RemoteException; import javax.xml.parsers.DocumentBuilder; import javax.xml.parsers.DocumentBuilderFactory; import javax.xml.parsers.ParserConfigurationException; import org.w3c.dom.Element; import org.w3c.dom.Node; import org.w3c.dom.NodeList; import org.xml.sax.SAXException; import com.sforce.soap.metadata.AsyncResult; import com.sforce.soap.metadata.MetadataConnection; import com.sforce.soap.enterprise.EnterpriseConnection; import com.sforce.soap.metadata.RetrieveMessage; import com.sforce.soap.metadata.RetrieveRequest; import com.sforce.soap.metadata.RetrieveResult; import com.sforce.soap.metadata.RetrieveStatus; import com.sforce.soap.enterprise.LoginResult; import com.sforce.ws.ConnectionException; import com.sforce.ws.ConnectorConfig; import com.sforce.soap.metadata.PackageTypeMembers; public class RetrieveSample {

// Binding for the metadata WSDL used for making metadata API calls private MetadataConnection metadataConnection;

51

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 = "[email protected]" ;

// 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." );

}

52

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();

}

53

File-Based Calls

} 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<PackageTypeMembers> pd = new ArrayList<PackageTypeMembers>();

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< String > members = new ArrayList< String >(); 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) { retrieve()

54

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

apiVersion

Type

double

Description

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.

55

File-Based Calls

Name

packageNames singlePackage specificFiles

Type

string[] boolean string[] checkRetrieveStatus()

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.

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.

Specifies whether only a single package is being retrieved

( true

) or not ( false)

. If false

, then more than one package is being retrieved.

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

.

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

unpackaged

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.

56

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

id

Type

ID

Description

ID obtained from an

AsyncResult object returned by a

retrieve()

call or a subsequent

RetrieveResult object returned by a

checkRetrieveStatus()

call.

57

File-Based Calls

Name

includeZip

Type

boolean checkRetrieveStatus()

Description

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

58

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);

59

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.

60

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

metadata

Type

Metadata

[]

Description

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.

61

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" });

62

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);

} else {

System.out.println( "Empty metadata." );

}

System.out.println( "Sharing model: "

+ obj.getSharingModel());

}

} 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);

63

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 {

64

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

metadata

Type

Metadata []

Description

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 []

65

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"

.

66

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 {

}

} else {

System.out.println( "Updated component: "

+ r.getFullName());

System.out

.println( "Errors were encountered while upserting "

+ r.getFullName()); for (Error e : r.getErrors()) {

System.out.println( "Error message: " + e.getMessage());

67

CRUD-Based Calls deleteMetadata()

}

System.out.println( "Status code: " + e.getStatusCode());

}

}

}

} catch (ConnectionException ce) { ce.printStackTrace();

}

Arguments

Name

metadata

Type

Metadata []

Description

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.

68

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();

}

}

69

CRUD-Based Calls

Arguments

Name Type

metadataType string fullNames string[] renameMetadata()

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.

70

CRUD-Based Calls

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.

create()

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 oldFullName string newFullName string

Description

The metadata type of the components to rename.

The current component full name.

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.

71

CRUD-Based Calls

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.

create()

72

CRUD-Based Calls

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

metadata

Type

Metadata

[]

Description

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.

delete()

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.

73

CRUD-Based Calls

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 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();

}

} delete()

74

CRUD-Based Calls

Arguments

Name

metadata

Type

Metadata

[]

Description

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.

update()

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.

75

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).

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

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" );

76

CRUD-Based Calls 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

metadata

Type

UpdateMetadata

[]

Description

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.

update()

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:

77

CRUD-Based Calls

Field

currentName metadata

Response

AsyncResult

[]

SEE ALSO:

updateMetadata()

create()

delete()

checkStatus()

Field Type

string

Metadata

Description

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.

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

update()

78

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.

79

Utility Calls

Arguments

Name

ids

Type

ID[] describeMetadata()

Description

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

apiVersion

Type

double

Description

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" );

80

Utility Calls describeValueType()

} sb.append( "***************************************************\n" );

}

} else { sb.append( "Failed to obtain metadata types." );

} catch (ConnectionException ce) { ce.printStackTrace();

}

}

System.out.println(sb.toString());

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" );

81

Utility Calls

Arguments

Name

type

Type

string describeValueType()

Description

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" );

82

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

83

Utility Calls listMetadata()

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

<The rest of the output for CustomObject has been omitted for brevity.>

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

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

<The rest of the output has been omitted for brevity.>

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.

84

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

queries asOfVersion

Type Description

ListMetadataQuery

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

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

85

Utility Calls ListMetadataQuery

ListMetadataQuery

The ListMetadataQuery parameter specified in a

listMetadata()

call consists of the following properties:

Name

folder type

Type

string string

Description

The folder associated with the component. This field is required

for components that use folders, such as Dashboard

,

Document ,

EmailTemplate , or

Report .

Required. The metadata type, such as

CustomObject

,

CustomField

, or

ApexClass

.

86

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.

87

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

id

Type

ID

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

done id message state

Type

boolean

ID

Description

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.

The message that corresponds to the returned

statusCode

field, if any.

string

AsyncRequestState

(

enumeration of

type string)

Required. The

AsyncRequestState

object has one of four possible values.

•

Queued

: This call has not started. It is waiting in a queue.

•

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.

88

Result Objects

Name

statusCode

AsyncResult

Type

StatusCode

(

enumeration of

type string)

Description

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

checkOnly done id

Type

boolean boolean

ID message string numberComponentErrors int numberComponentsDeployed int

Description

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.

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.

The message that corresponds to the returned

statusCode

field, if any.

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.

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.

89

Result Objects AsyncResult

Name

numberComponentsTotal numberTestErrors numberTestsCompleted numberTestsTotal secondsToWait state

Type

int int int int int

Description

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.

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.

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.

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.

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.

AsyncRequestState

(

enumeration of

type string)

Required. The

AsyncRequestState

object has one of four possible values.

•

Queued

: This call has not started. It is waiting in a queue.

•

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.

stateDetail stateDetailLastModifiedDate statusCode string dateTime

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 .

90

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

done

Type

boolean id

ID

Description

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

id canceledBy canceledByName checkOnly completedDate

Type

ID

ID string boolean dateTime

Description

ID of the component being deployed.

The ID of the user who canceled the deployment.

This field is available in API version 30.0 and later.

The full name of the user who canceled the deployment.

This field is available in API version 30.0 and later.

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.

Timestamp for when the deployment process ended.

91

Result Objects DeployResult

Name

createdBy createdByName createdDate details done errorMessage errorStatusCode ignoreWarnings lastModifiedDate numberComponentErrors int numberComponentsDeployed int numberComponentsTotal numberTestErrors dateTime int numberTestsCompleted int numberTestsTotal

Type

ID string dateTime

DeployDetails []

boolean string string boolean int int

Description

The ID of the user who created the deployment.

This field is available in API version 30.0 and later.

The full name of the user who created the deployment.

This field is available in API version 30.0 and later.

Timestamp for when the deploy()

call was received.

Provides the details of a deployment that is in-progress or ended, if the includeDetails

parameter is set to true

in the

checkDeployStatus()

call.

Indicates whether the server finished processing the deploy()

call for the specified id

.

Message corresponding to the values in the errorStatusCode

field, if any.

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 errorMessage field.

For a description of each StatusCode value, see “StatusCode” in the

SOAP API

Developer's Guide

.

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.

Timestamp of the last update for the deployment process.

The number of components that generated errors during this deployment.

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.

The total number of components in the deployment. Use this value with the

numberComponentsDeployed

value to get an estimate of the deployment’s

progress.

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

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.

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.

92

Result Objects DeployResult

Name

runTestsEnabled rollbackOnError startDate stateDetail status success

Type

boolean boolean dateTime string

DeployStatus

(

enumeration of

type string) boolean

Description

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.

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.

Timestamp for when the deployment process began.

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

Indicates the current state of the deployment. The valid values are:

•

Pending

•

InProgress

•

Succeeded

•

SucceededPartial

•

Failed

•

Canceling

•

Canceled

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

componentFailures

DeployMessage []

componentSuccesses

DeployMessage []

retrieveResult

RetrieveResult

Description

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

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

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.

93

Result Objects DeployResult

Name

runTestResult

Type

RunTestsResult

Description

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

id

Type

ID messages

DeployMessage []

retrieveResult

RetrieveResult

runTestResult success

RunTestsResult

boolean

Description

ID of the component being deployed.

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

call.

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.

If tests were run for the deploy()

call, this field contains the test results.

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

changed columnNumber componentType created createdDate deleted fileName

Type

boolean int string boolean dateTime boolean string

Description

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.

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.

The metadata type of the component in this deployment.

This field is available in API version 30.0 and later.

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.

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.

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.

The name of the file in the

.zip

file used to deploy this component.

94

Result Objects DeployResult

Name

fullName id lineNumber problem problemType success

Type

string

Description

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 ID of the component being deployed.

int string

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.

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

DeployProblemType

( enumeration

of type string)

Indicates the problem type. The problem details are tracked in the problem

field.

The valid values are:

•

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.

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

apexLogId

Type

string

Description

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

[] numFailures int

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

The number of failures for the unit tests.

95

Result Objects DeployResult

Name

numTestsRun successes totalTime

Type

int

RunTestSuccess

[] double

Description

The number of unit tests that were run.

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

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

dmlInfo name namespace numLocations soqlInfo

Type

CodeLocation

[] id

ID locationsNotCovered

CodeLocation

[] methodInfo type

CodeLocation

[] string string int

CodeLocation

[] string

Description

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.

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.

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.

The name of the class or trigger covered.

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

The total number of code locations.

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.

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

id message

Type

ID string

Description

The ID of the

CodeLocation . The ID is unique within an organization.

The message of the warning generated.

96

Result Objects DeployResult

Name

name namespace

Type

string string

Description

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

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

id message methodName name namespace seeAllData stackTrace time type

Type

ID string string string string boolean string double string

Description

The ID of the class which generated failures.

The failure message.

The name of the method that failed.

The name of the class that failed.

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

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.

The stack trace for the failure.

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

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

id methodName name namespace seeAllData

Type

ID string string string boolean

Description

The ID of the class which generated the success.

The name of the method that succeeded.

The name of the class that succeeded.

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

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.

97

Result Objects DescribeMetadataResult

Name

time

Type

double

Description

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

column line numExecutions time

Type

int int int double

Description

The column location of the Apex tested.

The line location of the Apex tested.

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

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

metadataObjects

Type Description

DescribeMetadataObject

[] One or more metadata components and their attributes.

organizationNamespace string partialSaveAllowed boolean

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.

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:

98

Result Objects DescribeValueTypeResult

Name Type

childXmlNames string[] directoryName string inFolder boolean metaFile boolean suffix xmlName string string

Description

List of child sub-components for this component.

The name of the directory in the

.zip

file that contains this component.

Indicates whether the component is in a folder ( true

) or not ( false

). For example, documents, email templates and reports are stored in folders.

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

The file suffix for this component.

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

apiCreatable apiDeletable apiReadable apiUpdatable parentField

Type

boolean boolean boolean boolean

ValueTypeField

Description

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.

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.

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.

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.

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

99

Result Objects ReadResult

Name Type

valueTypeFields

ValueTypeField

[]

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.

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

fields

Type

ValueTypeField foreignKeyDomain string isForeignKey isNameField minOccurs name picklistValues soapType valueRequired boolean boolean int string

PicklistEntry string boolean

Description

The

ValueTypeField

object for the next field, if any.

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.

True

if this value type field is a fullName

field, otherwise

False

.

1 if this field is required, 0 otherwise.

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

The individual picklist values if the field is a picklist.

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

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

Properties

Name

records

RetrieveResult

Type

Metadata []

Description

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

done errorMessage errorStatusCode

Type

boolean string

StatusCode

Description

Required. Indicates whether the retrieve()

call is completed ( true

) or not ( false

).

This field is available in API version 31.0 and later.

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.

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 id messages status

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.

ID

RetrieveMessage []

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

call.

RetrieveStatus

( enumeration of type

string)

The status of the retrieve()

call. Valid values are:

•

Pending

•

InProgress

•

Succeeded

•

Failed

This field is available in API version 31.0 and later.

success zipFile boolean base64Binary

Indicates whether the retrieve()

call was successful ( true

) or not ( false

). This field is available in API version 31.0 and later.

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

createdById createdByName createdDate fileName fullName

Type

string string dateTime string string id string lastModifiedById string lastModifiedByName string lastModifiedDate dateTime manageableState

ManageableState

( enumeration of type

string) namespacePrefix type string string

Description

Required. ID of the user who created the file.

Required. Name of the user who created the file.

Required. Date and time when the file was created.

Required. Name of the file.

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.

Required. ID of the file.

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

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

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

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.

If any, the namespace prefix of the component.

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

Name

fileName problem

Type

string string

Description

The name of the file in the retrieved

.zip

file where a problem occurred.

A description of the problem that occurred.

SEE ALSO:

retrieve()

SaveResult

Contains result information for the createMetadata

, updateMetadata

, or renameMetadata

call.

Version

Available in API version 30.0 and later.

Properties

Name

errors fullName success

Type

Error []

string boolean

Description

An array of errors returned if the operation wasn’t successful.

The full name of the component processed.

Indicates whether the operation was successful ( true

) or not ( false

).

DeleteResult

Contains result information for the deleteMetadata

call.

Version

Available in API version 30.0 and later.

Properties

Name

errors fullName success

Type

Error []

string boolean

Description

An array of errors returned if the operation wasn’t successful.

The full name of the deleted component.

Indicates whether the deletion was successful ( true

) or not ( false

).

SaveResult

103

Result Objects UpsertResult

UpsertResult

Contains information about the result of the associated upsertMetadata()

call.

Version

Available in API version 31.0 and later.

Properties

Name

created

Type

boolean errors fullName success

Error []

string boolean

Description

Indicates whether the upsert operation resulted in the creation of the component ( true

) or not ( false

). If false

and the upsert operation was successful, this means that the component was updated.

An array of errors that were returned if the operation wasn’t successful.

The full name of the component that was created or updated if the operation was successful.

Indicates whether the operation was successful ( true

) or not ( false

).

Error

Represents an error that occurred during a synchronous CRUD ( createMetadata()

, updateMetadata()

, or deleteMetadata()

) operation.

Version

Available in API version 30.0 and later.

Properties

Name Type

extendedErrorDetails

ExtendedErrorDetails fields message string[] string

Description

More details about the error, including an extended error code and extra error properties, when available. Reserved for future use.

For a description of the ExtendedErrorDetails element, see

“ExtendedErrorDetails” in the

SOAP API Developer's Guide

.

An array containing names of fields that affected the error condition.

The error message text.

104

Result Objects

Name

statusCode

Type

StatusCode

Description

A status code corresponding to the error.

For a description of each StatusCode value, see “StatusCode” in the

SOAP API Developer's Guide

.

Error

105

CHAPTER 10 Metadata Types

Metadata API enables you to access some entities and feature settings that you can customize in the user interface. The following table lists the metadata types that you can retrieve or deploy and whether you can retrieve the metadata type with the wildcard character (*) in package.xml

. For more information about using wildcards, see Working with the Zip File

.

Note:

•

Metadata type names are case-sensitive. Specifying a type name with an invalid case results in a deployment error.

•

Metadata types don’t always correspond directly to their related data types. In some cases, the information is accessible but not organized as expected. For example, dependent picklists are exposed as a type of picklist, not a separate metadata type.

•

The wildcard character doesn’t apply to metadata types for feature settings, like AccountSettings. The wildcard applies only

when retrieving all settings and not an individual setting. See Settings .

Metadata Type

AccountSettings

ActionLinkGroupTemplate

ActionOverride

ActivitiesSettings

AddressSettings

AnalyticSnapshot

Allows Wildcard

(*)?

Not Applicable

Description

Yes

No

Not Applicable

Not Applicable

No

Represents an organization’s account settings for account teams, account owner report, and the View Hierarchy link.

Represents the action link group template. Action link templates let you reuse action link definitions and package and distribute action links. An action link is a button on a feed element. Clicking on an action link can take a user to another Web page, initiate a file download, or invoke an API call to an external server or Salesforce. Use action links to integrate Salesforce and third-party services into the feed. Every action link belongs to an action link group and action links within the group are mutually exclusive.

Represents an action override on a standard or custom object. Use it to create, update, edit, or delete action overrides.

Represents an organization’s activity settings, and its user interface settings for the calendar.

Represents the configuration of country and state picklists.

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.

106

Metadata Types

Metadata Type

ApexClass

ApexComponent

ApexPage

ApexTrigger

AppMenu

ApprovalProcess

ArticleType

AssignmentRules

AuthProvider

AuraDefinitionBundle

AutoResponseRules

BaseSharingRule

BusinessHoursSettings

BusinessProcess

Allows Wildcard

(*)?

Yes

Description

Yes

Yes

Yes

Yes

Yes

(See description.)

Represents an Apex class. An Apex class is 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.

Represents a Visualforce component.

Represents a Visualforce page.

Represents an Apex trigger. A trigger is Apex code that executes before or after specific data manipulation language (DML) events occur, such as before object records are inserted into the database, or after records have been deleted.

Represents the Force.com app menu or the Salesforce1 navigation menu.

Represents the metadata associated with an approval process. An approval process automates how records are approved in Salesforce. An approval process specifies each step of approval, including who to request approval from and what to do at each point of the process.

Use the wildcard (*) symbol to retrieve all approval processes for all objects.

You can’t use it to retrieve a subset of approval processes; syntax such as

Lead.*

is not supported.

Yes

Yes

Yes

Yes

Yes

Yes

Not Applicable

(See description.)

Represents the metadata associated with an article type.

Represents assignment rules that allow you to automatically route cases to the appropriate users or queues.

Represents an authentication provider (or auth provider) in your organization.

An auth provider enables users to log in to your Salesforce organization using their login credentials from an external service provider such as Facebook

© or Janrain

©

.

Represents a Lightning definition bundle. A bundle contains a Lightning definition and all its related resources. The definition can be a component, application, event, interface, or a tokens collection.

Represents an auto-response rule that sets conditions for sending automatic email responses to lead or case submissions based on the attributes of the submitted record.

Represents the base container for criteria-based and owner-based sharing rules.

Represents the metadata used to manage settings for business hours and holidays in entitlements, entitlement templates, campaigns, and cases.

The BusinessProcess metadata type enables you to display different picklist values for users based on their profile.

Supports wildcard (*) only if a

RecordType

is specified.

107

Metadata Types

Metadata Type

CallCenter

CaseSettings

Certificate

ChatterAnswersSettings

CleanDataService

CompanySettings

Community (Zone)

CommunityTemplateDefinition

CommunityThemeDefinition

CompactLayout

ConnectedApp

ContentAsset

ContractSettings

CorsWhitelistOrigin

CriteriaBasedSharingRule

CustomApplication

CustomApplicationComponent

Allows Wildcard

(*)?

Yes

Description

Not Applicable

Yes

Not Applicable

Yes

Not Applicable

Yes

Yes

Yes

Yes

Yes

Yes

Not Applicable

Yes

Yes

Yes

Yes

Represents the Call Center definition used to integrate Salesforce with a third-party computer-telephony integration (CTI) system.

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.

Represents a certificate used for digital signatures which verify that requests are coming from your org. Certificates are used for either authenticated single sign-on with an external website, or when using your org as an identity provider.

Represents the metadata used to manage settings for Chatter Answers.

Represents a data service that adds and updates data in standard objects.

Represents global settings that affect multiple features in your organization.

Represents a zone that contains Ideas or Chatter Answers objects. Zones are shared by the Ideas, Answers, and Chatter Answers features, allowing you to view and create zones from those locations.

Represents the definition of a community template.

Represents the definition of a community theme.

Represents the metadata associated with a compact layout.

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 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.

Represents the metadata for creating an asset file.

Represents contract settings.

Represents an origin in the CORS whitelist.

Represents a criteria-based sharing rule. CriteriaBasedSharingRule enables you to share records based on specific criteria. It contains metadata for the following criteria-based sharing rules: Accounts, Campaigns, Cases, Contacts,

Custom Objects, Leads, and Opportunities.

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.

Represents a custom console component (Visualforce page) assigned to a

CustomApplication

that is marked as a Salesforce console. Custom console components extend the capabilities of Salesforce console apps.

108

Metadata Types

Metadata Type

CustomFeedFilter

CustomField

CustomLabel

Custom Metadata Types

(CustomObject)

CustomMetadata

CustomLabels

CustomObject

CustomObjectTranslation

CustomPageWebLink

CustomPermission

CustomSite

CustomTab

Allows Wildcard

(*)?

Yes

Description

No

No

Yes

Represents a custom feed filter that limits the feed view to feeds from the

Cases object. The custom feed filter shows only feed items that satisfy the criteria specified in the CustomFeedFilter definition.

Represents the metadata associated with a field. Use this metadata type to create, update, or delete custom field definitions on standard, custom, and external objects or standard field definitions on standard objects.

Represents a custom label that can be localized and used in different languages, countries, and currencies. Use this type instead of CustomLabels if you want to retrieve custom labels by name.

Represents the metadata associated with a custom metadata type.

Yes

Yes

(See description.)

Yes

Yes

Yes

Yes

Yes

Represents a record of a custom metadata type.

This metadata type allows you to create custom labels that can be localized for use in different languages, countries, and currencies.

Represents a custom object that stores data unique to your organization or an external object that maps to data stored outside Salesforce.

You can also use this metadata type to work with customizations of standard objects, such as Accounts. It contains the following types: Action Overrides,

Business Processes, Custom Fields, Field Sets, List Views, Named Filters (Lookup

Filters), Picklists (including Dependent Picklists), Record Types, Search Layouts,

Sharing Reasons, Sharing Recalculations, Validation Rules, Weblinks, and Field

Types.

Supports wildcard (*) for Field Sets and Record Types, but not for other components.

This metadata type allows you to translate custom objects for a variety of languages.

Represents a custom link defined in a home page component.

Represents a permission that grants access to a custom feature.

Represents a Force.com site. 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.

Represents a custom tab. Custom tabs let you display custom object data or other web content in Salesforce. When you add a custom tab to an app in

Salesforce Classic, it displays as a tab. When you add a custom tab to an app in Lightning Experience, it displays as an item in the app’s navigation bar.

When a tab displays a custom object, the tab name is the same as the custom object name; for page, s-control, or URL tabs, the name is arbitrary.

109

Metadata Types

Metadata Type

Dashboard

DataCategoryGroup

DelegateGroup

Document

DuplicateRule

EclairGeoData

EmailTemplate

EntitlementProcess

EntitlementSettings

EntitlementTemplate

EventDelivery

EventSubscription

ExternalServiceRegistration

ExternalDataSource

FieldSet

FileUploadAndDownloadSecuritySettings

FlexiPage

Flow

Allows Wildcard

(*)?

No

Description

Yes

Yes

No

Yes

Yes

No

Yes

Not Applicable

Yes

Yes

Yes

Yes

Yes

Yes

Not Applicable

Yes

Yes

Represents a dashboard. Dashboards are visual representations of data that allow you to see key metrics and performance at a glance.

Represents a data category group.

Represents a group of users who have the same administrative privileges.

These groups are different from public groups used for sharing.

Represents a Document. All documents must be in a document folder, for example sampleFolder/TestDocument

.

Represents a rule that specifies how duplicate records in an object are detected.

Represents a Wave custom map chart. Custom maps are user-defined maps that are uploaded to Wave and are used just as standard maps are. Custom maps are accessed in Wave from the list of maps available with the map chart type.

Represents an email template.

Represents the settings for an entitlement process.

Represents an organization’s entitlement settings.

Represents an entitlement template. Entitlement templates are predefined terms of customer support that you can quickly add to products. For example, you can create entitlement templates for Web or phone support so that users can easily add entitlements to products offered to customers.

Reserved for future use.

Reserved for future use.

Represents the External Service configuration for an org.

Represents the metadata associated with an external data source. Create external data sources to manage connection details for integration with data and content that are stored outside your Salesforce org.

Represents a field set. A field set is a grouping of fields. For example, you could have a field set that contains fields describing a user's first name, middle name, last name, and business title.

Represents the security settings for uploading and downloading files.

Represents the metadata associated with a Lightning Page. A Lightning Page represents a customizable screen containing Lightning components.

Represents the metadata associated with a flow. With Flow, you can create an application that navigates users through a series of screens to query and update records in the database. You can also execute logic and provide branching capability based on user input to build dynamic applications.

110

Metadata Types

Metadata Type

FlowDefinition

Folder

FolderShare

ForecastingSettings

GlobalValueSet

GlobalValueSetTranslation

GlobalPicklistValue

Group

HomePageComponent

HomePageLayout

IdeasSettings

InstalledPackage

KeywordList

KnowledgeSettings

Layout

Letterhead

Allows Wildcard

(*)?

Yes

No

No

Not Applicable

Yes

Yes

No

Yes

Yes

Yes

Not Applicable

Yes

Yes

Not Applicable

Yes

No

Description

Represents the flow definition’s description and active flow version number.

Represents a folder. A folder can contain documents, email templates, reports, or dashboards. You must specify the folder type (Document, EmailTemplate,

Report, or Dashboard) to retrieve or deploy.

Represents the settings for enhanced analytics folder sharing. Users can control access to reports or dashboards by giving others Viewer, Editor or Manager access to the folder that contains the report or dashboard.

Represents the Collaborative Forecasts settings options.

Represents the metadata for a global picklist value set, which is the set of shared values that custom picklist fields can use. A global value set isn't a field itself. (In contrast, the custom picklist fields that are based on a global picklist are of type ValueSet.)

Contains details for a global value set translation. Global value sets are lists of values that can be shared by multiple custom picklist fields, optionally across objects.

Represents the definition of a value used in a global picklist. Custom picklist fields can inherit the picklist value set from a global picklist. This type extends

the Metadata metadata type and inherits its

fullName

field.

Represents a set of public groups, which can have users, roles, and other groups.

Represents the metadata associated with a home page component. You can customize the Home tab to include components such as sidebar links, a company logo, a dashboard snapshot, or custom components that you create.

Represents the metadata associated with a home page layout. You can customize home page layouts and assign the layouts to users based on their user profile.

Represents the metadata used to manage settings for Ideas.

Represents a package to be installed or uninstalled. Deploying a newer version of a currently installed package upgrades the package.

Represents a list of keywords used in community moderation. This keyword list is a type of moderation criteria that defines offensive language or inappropriate content that you don’t want in your community.

Represents the metadata used to manage settings for Salesforce Knowledge.

Represents the metadata associated with a page layout.

Represents formatting options for the letterhead in an email template.

Letterheads define the look and feel of your HTML email templates. Your

HTML email templates can inherit the logo, color, and text settings from a letterhead.

111

Metadata Types

Metadata Type

ListView

LiveAgentSettings

LiveChatAgentConfig

LiveChatButton

LiveChatDeployment

LiveChatSensitiveDataRule

ManagedTopics

MatchingRule

Metadata

MetadataWithContent

MilestoneType

MobileSettings

ModerationRule

NamedCredential

NamedFilter

Allows Wildcard

(*)?

No

Description

Not Applicable

Yes

Yes

Yes

Yes

Yes

Yes

No

No

Yes

Not Applicable

Yes

Yes

ListView allows you to see a filtered list of records, such as contacts, accounts, or custom objects.

Represents an organization’s Live Agent settings, such as whether or not Live

Agent is enabled.

Represents the configuration of an organization’s Live Agent deployment, such as how many chats can be assigned to an agent and whether or not chat sounds are enabled.

Represents a Live Agent deployment’s settings for the button that customers click to chat with an agent and the chat window, such as the label that appears on the button and the pre-chat form that appears before a live chat begins.

Represents the configuration settings for a specific Live Agent deployment, such as the branding image for the deployment and whether or not chat transcripts are automatically saved.

Represents a rule for masking or deleting data of a specified pattern. Written as a regular expression (regex). This object is available in API version 35.0 and later.

Represents navigational and featured topics managed in a community.

Represents a matching rule that is used to identify duplicate records.

This is the base class for all metadata types. You cannot edit this object. A component is an instance of a metadata type.

This is the base type for all metadata types that contain content, such as documents or email templates.

Represents the name and description of a milestone, which you can use in an entitlement process to track important steps in cases.

Represents an organization’s mobile settings.

Represents a rule used in your community to moderate member-generated content.Each rule specifies the member-generated content the rule applies to, the criteria to enforce the rule on, and the moderation action to take.

Moderation rules help protect your community from spammers, bots, and offensive or inappropriate content.

Represents a named credential, which specifies the URL of a callout endpoint and its required authentication parameters in one definition. A named credential can be specified as an endpoint to simplify the setup of authenticated callouts.

No

This component has been removed as of API version 30.0 and is only provided for backward compatibility. The metadata associated with a lookup filter is now represented by the lookupFilter

field in the CustomField component.

112

Metadata Types

Metadata Type

NameSettings

Network

OpportunitySettings

OrderSettings

OrgPreferenceSettings

OwnerSharingRule

Package

PathAssistant

PathAssistantSettings

PermissionSet

PersonalJourneySettings

Picklist (Including Dependent

Picklist)

PlatformCachePartition

Portal

PostTemplate

Allows Wildcard

(*)?

Description

Not Applicable

Yes

Not Applicable

Not Applicable

No applicable

Yes

No

Yes

Not Applicable

Yes

No

No

Yes

Yes

Yes

Represents the metadata associated with a lookup filter. Use this metadata type to create, update, or delete lookup filter definitions.

Enables or disables middle name and suffix attributes for the following person objects: Contact, Lead, Person Account, and User.

Represents a community. Communities are branded spaces for your employees, customers, and partners to connect. You can customize and create communities to meet your business needs, then transition seamlessly between them. Use the Network component for Salesforce Communities. If you want to create zones that contain Chatter Answers and Ideas, use the Community

(Zone) component.

Represents organization preferences for features such as automatic opportunity updates and similar-opportunity filters.

Represents order settings.

Represents the unique org preference settings in a Salesforce org.

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 contains metadata for the following specific owner-sharing rules: Accounts, Campaigns, Cases, Contacts,

Custom Objects, Leads, Account Territory and Opportunities.

Specifies which metadata components to retrieve as part of a retrieve()

call or defines a package of components.

Represents Path records.

Represents the Path preference setting.

Represents a set of permissions that's used to grant additional access to one or more users without changing their profile or reassigning profiles. You can use permission sets to grant access, but not to deny access.

Represents an organization’s Adoption Manager setting, which enables or disables the Adoption Manager tool.

Deprecated. Represents a picklist (or dependent picklist) definition for a custom field in a custom object or a custom or standard field in a standard object, such as an account.

Represents a partition in the Platform Cache.

The Portal metadata type represents a partner portal or Customer Portal.

Represents the metadata associated with an approval post template for

Approvals in Chatter. With approval post templates, you can customize the information included in approval request posts that appear in Chatter feeds.

113

Metadata Types

Metadata Type

ProductSettings

Profile

ProfileActionOverride

Queue

QuickAction

QuoteSettings

RecordType

RemoteSiteSetting

Report

ReportType

Role

SamlSsoConfig

Scontrol

SearchLayouts

SearchSettings

Allows Wildcard

(*)?

Not Applicable

Description

Yes

No

Yes

Yes

Not Applicable

No

Not Applicable

No

Yes

Yes

Yes

Yes

No

No

Represents organization preferences for quantity schedules, revenue schedules, and active flag interaction with prices.

Represents a user profile. A profile defines a user’s permission to perform different functions within Salesforce.

Represents an override of an ActionOverride by a user profile. You can use it to override an ActionOverride on a standard Home tab or object record page in Lightning Experience. When a user logs in with a profile, a matching

ProfileActionOverride assignment takes precedence over existing overrides for the Home tab or record page specified in ActionOverride.

Represents a holding area for items before they are processed.

Represents a specified create or update quick action for an object that then becomes available in the Chatter publisher. For example, you can create an action that, on the detail page of an account, allows a user to create a contact related to that account from the Chatter feed on that page. QuickAction can be created on objects that allow custom fields.

Enables or disables Quotes, which show proposed prices for products and services.

Represents the metadata associated with a record type. Record types let you offer different business processes, picklist values, and page layouts to different users.

Represents a remote site setting. Before any Visualforce page, Apex callout, or JavaScript code using XmlHttpRequest in an s-control or custom button can call an external site, that site must be registered in the Remote Site Settings page, or the call fails.

Represents a custom report.

Represents the metadata associated with a custom report type. Custom report types allow you to build a framework from which users can create and customize reports.

Represents a role in your organization.

Represents a SAML Single Sign-On configuration.

Deprecated. Represents an Scontrol component, corresponding to an s-control in the Salesforce user interface.

Represents the metadata associated with the Search Layouts for an object.

You can customize which fields to display for users in search results, search filter fields, lookup dialogs, and recent record lists on tab home pages.

Represents an org's search settings.

114

Metadata Types

Metadata Type

SecuritySettings

SharingBaseRule

SharingReason

SharingRecalculation

SharingRules

SharingSet

SiteDotCom

Skill

StandardValueSet

StandardValueSetTranslation

StaticResource

SynonymDictionary

Territory

Territory2

Territory2Model

Territory2Rule

Allows Wildcard

(*)?

Not Applicable

Description

No

No

No

Yes

Yes

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.

Represents sharing rule settings such as access level and to whom access is granted.

Represents an Apex sharing reason, which is used to indicate why sharing was implemented for a custom object.

Represents Apex classes that recalculate the Apex managed sharing for a specific custom object.

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.

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.

Yes

Represents a site for deployment. It extends the

MetadataWithContent type

and inherits its fullName

and content

fields.

Yes

No

Yes

Yes

Yes

Yes

Yes

Yes

Yes

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.

Represents the set of values in a standard picklist field. This type extends the

Metadata metadata type and inherits its

fullName

field.

Contains details for a standard picklist translation. It returns a translated standard value set.

Represents a static resource file, often a code library in a ZIP file.

Represents a set of synonym groups, which are groups of words or phrases that are treated as equivalent in users’ searches. You can define synonym groups to optimize search results for acronyms, variations of product names, and other terminology unique to your organization.

Represents a territory in your organization.

Represents the metadata associated with a sales territory in Territory

Management 2.0.

Represents the metadata associated with a territory model in Territory

Management 2.0.

Represents the metadata associated with a territory assignment rule associated with an object, such as Account, in Territory Management 2.0.

115

Metadata Types

Metadata Type

Territory2Settings

Territory2Type

TransactionSecurityPolicy

Translations

ValidationRule

WaveApplication

WaveDashboard

WaveDataflow

WaveDataset

WaveLens

WaveTemplateBundle

Wavexmd

WebLink

Workflow

Allows Wildcard

(*)?

No

Description

Yes

Yes

Yes

No

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

Yes

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.

Represents the metadata for a category of territories in Territory Management

2.0. Every Territory2 must have a Territory2Type.

Represents a transaction security policy definition. Transaction Security policies give you a way to look through events in your organization and specify actions to take when certain combinations occur.

This metadata type allows you to work with translations for various supported languages.

Represents a validation rule, which is used to verify that the data a user enters in a record is valid and can be saved. A validation rule contains a formula or expression that evaluates the data in one or more fields and returns a value of true

or false

. Validation rules also include an error message that your client application can display to the user when the rule returns a value of true

due to invalid data.

Represents the Wave Analytics application.

Represents the WaveDashboard object in the Wave Analytics application.

Represents the WaveDataflow object in the Wave Analytics application.

Represents the WaveDataset object in the Wave Analytics application.

Represents the WaveLens object in the Wave Analytics application.

Represents a Wave Analytics template bundle, which can be used to create

Wave apps. A bundle contains a Wave template definition and all its related resources.

Represents the WaveXmd object in the Wave Analytics application.

Represents a custom button or link defined in a custom object.

Represents the metadata associated with a 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.

116

Metadata Types Metadata Components and Types

Metadata Components and Types

Metadata components are not based on sObjects, like objects in the API. Instead, they are based on metadata types, such as ApexClass

and CustomObject, which extend Metadata

. 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.

A metadata type can be identified in the metadata WSDL as any complexType that extends the Metadata complexType. A complexType

that is a metadata type includes the following element in its WSDL definition:

<xsd:extension base= "tns:Metadata">

CustomObject and BusinessProcess extend Metadata so they are metadata types; ActionOverride doesn't extend Metadata so it's not a metadata type.

You can individually deploy or retrieve a component for a metadata type. For example, you can retrieve an individual BusinessProcess component, but you can't retrieve an individual ActionOverride component. You can only retrieve an ActionOverride component by retrieving its encompassing CustomObject component.

Metadata components can be manipulated by

asynchronous Metadata API calls or

declarative (or file-based) Metadata API calls .

Most of the components can be accessed using Force.com IDE. Exceptions are noted in the description of the object.

Field Data Types

Each component field has a specific field type. These field types can correspond to other components defined in the WSDL, or primitive data types, like string

, that are commonly used in strongly typed programming languages.

These field data types are used in the SOAP messages that are exchanged between your client application and the API. When writing your client application, follow the data typing rules defined for your programming language and development environment. Your development tool handles the mapping of typed data in your programming language with these SOAP data types.

For more information about primitive data types, see the

SOAP API Developer's Guide

.

Enumeration Fields

Some component fields have a data type that is an enumeration. An enumeration is the API equivalent of a picklist. The valid values of the field are restricted to a strict set of possible values, all having the same data type. These values are listed in the field description

column for each enumeration field. See sortBy

for an example of an enumeration field of type string. The XML below shows a sample definition of an enumeration of type string in the WSDL.

<xsd:simpleType name= "DashboardComponentFilter">

<xsd:restriction base= "xsd:string">

<xsd:enumeration value= "RowLabelAscending"/>

<xsd:enumeration value= "RowLabelDescending"/>

<xsd:enumeration value= "RowValueAscending"/>

<xsd:enumeration value= "RowValueDescending"/>

</xsd:restriction >

</xsd:simpleType >

Supported Calls

All of the metadata types are supported by the main calls, unless it is stated otherwise in the individual component sections. The main

Metadata API calls are:

117

Metadata Types Unsupported Metadata Types

•

CRUD calls

, such as

createMetadata()

and

deleteMetadata()

•

File-based calls

, such as

deploy()

and retrieve()

•

Utility calls

, such as

listMetadata() and

describeMetadata()

Unsupported Metadata Types

Some things you can customize in a Salesforce organization aren’t available in Metadata API.

The following components can’t be retrieved or deployed with Metadata API, and changes to them must be made manually in each of your organizations:

•

Account Teams

•

Activity Button Overrides

•

Analytic Settings

•

Automated Case User Settings

•

Auto-number on Customizable Standard Fields

•

Campaign Influences

•

Case Contact Roles

•

Case Feed Layouts

•

Case Team Roles

•

Console Layouts

•

Currency Exchange Rates

•

Data Category Visibility Settings

•

Delegated Administration

•

Divisions

•

Email Services

•

Fiscal Year

•

HTML Document and Attachment Settings

•

Lead Settings

•

Mail Merge Templates

•

Mobile Administration

•

Mobile Users and Devices

•

Multiline layout fields for opportunity teams

•

Offline Briefcase Configurations

•

Opportunity Big Deal Alerts

•

Opportunity Update Reminders

•

Organization Wide Email Addresses

•

Partner Management

•

The following standard picklists: IdeaTheme.Categories, Order.Status, Question.Origin. (All other standard picklists are supported.)

•

Predefined Case Teams

•

Product Schedule Setup

•

Public and Resource Calendars

118

Metadata Types Special Behavior in Metadata API Deployments

•

Quote Templates

•

Salesforce to Salesforce

•

Standard fields that aren’t customizable, such as autonumber fields or system fields

•

Self-Service Portal Font and Colors

•

Self-Service Portal Settings

•

Self-Service Portal Users

•

Self-Service Public Solutions

•

Self-Service Web-to-Case

•

Site.com

•

Social Account/Contact Settings

•

SoftPhone Layout

•

Solution Categories

•

Solution Settings

•

Tag Settings

•

Territory Assignment Rules

•

User Interface Settings (except calendar features, which are supported in

ActivitiesSettings

on page 559)

•

Web Links on Person Account Page Layouts

•

Web-to-Lead

Special Behavior in Metadata API Deployments

Important considerations for specific types and contents of a deployment.

When deploying changes to a Salesforce org, consider how individual components in your deployment behave so you’re including all the necessary changes. Use the following information to determine what to include in your deployment, and how the changes appear in the destination org.

Apex Classes and Apex Triggers

By default, changes to Apex code that have Apex jobs pending or in progress can’t be deployed. To deploy these changes, do one of the following.

•

Cancel Apex jobs before deploying changes to Apex code. Reschedule the jobs after the deployment.

•

Enable deployments with Apex jobs in the Salesforce user interface in the Deployment Settings page.

Approval Processes

•

To use approval processes on Salesforce Knowledge articles with the Metadata API, the article type must be deployed. For article version (_kav) in approval processes, the supported action types are: Knowledge Action, Email Alert, Field Update, and Outbound

Message.

•

If the approval process references any post templates that contain custom fields, then you need to resave those post templates in the originating organization before adding them to the change set. From Setup, enter

Post Templates

in the

Quick

Find

box, then select Post Templates. For each post template, click Edit and then Save.

•

The metadata doesn’t include the order of active approval processes. You might need to reorder the approval processes in the destination org after deployment.

•

If you change the

Unique Name

of an approval process that was previously included in a change set and deployed in another organization, and you resend the approval process via a change set, a new approval process will be created upon deployment in the other organization. The previously deployed approval process will not be modified.

119

Metadata Types

Custom Fields

Starting in API version 30.0, when deploying a new custom field, the default values for the editable

and readable

fields in profile field permissions are false

. To override the default values, include field permissions for the new field in your profiles.

Custom Objects

Using API version 29.0, you can’t change the sharingModel

of an object using the Metadata API. You must manually make this change to the target org through the user interface.

Starting with API version 30.0, you can change the sharingModel

of an object for internal users using the Metadata API and the user interface.

Connected App

•

You cannot set the consumerKey

in the Metadata API. It is included in a retrieve operation for informational purposes. If you try to move the connected app to another org, you must remove the consumerKey

from the .zip file before the deployment to an org. A new key will be generated in the destination org.

•

Mobile settings of connected apps are not supported in change sets and must be manually migrated.

Named Credentials

The following callout options for named credentials can be set only via the user interface. If the default values aren’t appropriate in the destination org, the admin for that org must manually configure the named credential after deployment.

•

Generate Authorization Header

—Default: Enabled

•

Allow Merge Fields in HTTP Header

—Default: Disabled

•

Allow Merge Fields in HTTP Body

—Default: Disabled

Page Layout

A deployment containing page layout assignments replaces all existing page layout assignments in the destination org with those specified in the .zip file. Existing page layouts in the org disappear if they’re not included in the .zip file. Always include all page layouts for all required record types in the .zip file.

Profiles

If a package includes a profile with a name that doesn’t exist in the target org, a new profile is created with that name. If the deployed profile doesn’t specify any permissions or settings, the resulting profile consists of all the permissions and settings in the Standard

Profile.

Sharing

•

Simultaneously updating the sharingModel

field for an object and adding a new sharing rule isn’t supported in the Metadata

API, regardless of which object you’re updating. For example, you can add a sharing rule when the org-wide default is public, and subsequently update the sharingModel

. This would result in a single sharing recalculation.

•

You might encounter an error if you’re deploying a change set with a custom object that has a parent-child relationship without the master/detail field in the same change set. To resolve this error, include the master/detail custom field in the change set, even if you haven’t changed the org-wide default.

Workflow

Test mode for flow triggers isn’t supported in the Metadata API. If you want a flow trigger to run the latest flow version when an administrator causes the workflow rule to fire, enable test mode via the user interface after deployment.

ActionLinkGroupTemplate

Represents the action link group template. Action link templates let you reuse action link definitions and package and distribute action links. An action link is a button on a feed element. Clicking on an action link can take a user to another Web page, initiate a file download, or invoke an API call to an external server or Salesforce. Use action links to integrate Salesforce and third-party services into the feed.

120

ActionLinkGroupTemplate

Metadata Types ActionLinkGroupTemplate

Every action link belongs to an action link group and action links within the group are mutually exclusive. This type extends the

Metadata

metadata type and inherits its fullName

field.

File Suffix and Directory Location

ActionLinkGroupTemplate components have the suffix

.actionLinkGroupTemplate

and are stored in the actionLinkGroupTemplates

folder.

Version

ActionLinkGroupTemplate components are available in API version 33.0 and later.

Fields

Field Name

actionLinkTemplates category executionsAllowed hoursUntilExpiration isPublished name

Field Type Description

ActionLinkTemplate

on page 122[]

Action link templates that are associated with the action link group template.

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.

ActionLink

ExecutionsAllowed

(

enumeration of

type string)

Required. The number of times an action link can be executed. Values are:

•

Once

—An action link can be executed only once across all users.

•

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.

int boolean string

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.

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.

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

actionUrl headers

Field Type

string string

Description

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://

.

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 isGroupDefault label labelKey linkType boolean boolean string string

Required. If true

, a confirmation dialog appears before the action is executed.

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.

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.

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.

ActionLinkType

( enumeration of type

string)

Required. The type of action link. One of these values:

•

Api

—The action link calls a synchronous API at the action URL. Salesforce 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

HttpMethod

( enumeration of type

string)

Required. HTTP method for the action URL. One of these values:

•

HttpDelete class is empty.

—Returns HTTP 204 on success. Response body or output

•

HttpGet

—Returns HTTP 200 on success.

122

Metadata Types

Field Name

position requestBody userAlias userVisibility

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

.

int string

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

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}

.

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.

ActionLink

UserVisibility

( enumeration of type

string)

Required. Who can see the action link. This value is set per action link, not per action link group. Values are:

•

Creator

—Only the creator of the action link can see the action link.

•

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<ActionLinkGroupTemplate xmlns= "http://soap.sforce.com/2006/04/metadata">

<actionLinkTemplates >

<actionUrl >/services/data/{!Bindings.word}/chatter/feed-elements </actionUrl >

<headers >Content-Type:{!Bindings.word3} </headers >

123

Metadata Types AnalyticSnapshot

<isConfirmationRequired >true </isConfirmationRequired >

<isGroupDefault >true </isGroupDefault >

<labelKey >Add </labelKey >

<linkType >API </linkType >

<method >httpPost </method >

<position >0 </position >

<requestBody >{"body":{"messageSegments":[{"type": "Text",

"text": "{!Bindings.word1}"}]},"subjectId": "{!Bindings.word2}",

"feedElementType": "feedItem"} </requestBody >

<userAlias >customExcludedUser </userAlias >

<userVisibility >CustomExcludedUser </userVisibility >

</actionLinkTemplates >

<category >Primary </category >

<executionsAllowed >OncePerUser </executionsAllowed >

<hoursUntilExpiration >10 </hoursUntilExpiration >

<isPublished >true </isPublished >

<name >MyPackage </name >

</ActionLinkGroupTemplate >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >ActionLinkGroupTemplate </name >

</types >

<version >33.0

</version >

</Package >

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

description fullName groupColumn mappings name runningUser sourceReport targetObject

Field Type

string string string

AnalyticSnapshotMapping []

string string string string

Description

A description of the reporting snapshot.

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.

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

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

AnalyticSnapshotMapping

.

Required. The display name of the reporting snapshot.

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

Required. The report where data will be extracted from.

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

AnalyticSnapshotMapping

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

Field

aggregateType sourceField sourceType

Field Type Description

ReportSummaryType []

( enumeration

of type string)

List that defines if and how each report field is summarized. For valid

values, see ReportSummaryType

.

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.

ReportJobSourceTypes

[]

( enumeration

of type string)

List that defines the report format for the reporting snapshot. For valid

values, see ReportJobSourceTypes .

125

Metadata Types AnalyticSnapshot

Field

targetField

Field Type

string

Description

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

snapshot summary tabular

Description

Use this option if the

sourceField contains snapshot-specific information such as JobName,

RunningUser, or ExecutionTime.

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

the sourceReport .

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<AnalyticSnapshot xmlns= "http://soap.sforce.com/2006/04/metadata">

<description >my description </description >

<groupColumn >INDUSTRY </groupColumn >

<mappings >

<aggregateType >Average </aggregateType >

<sourceField >SALES </sourceField >

<sourceType >summary </sourceType >

<targetField > myObject __c.Name

</targetField >

</mappings >

<mappings >

<sourceField >ExecutionTime </sourceField >

<sourceType >snapshot </sourceType >

<targetField > myObject __c.field3__c

</targetField >

</mappings >

<mappings >

<sourceField >INDUSTRY </sourceField >

<sourceType >tabular </sourceType >

<targetField >testObject__c.Name

</targetField >

</mappings >

<name >my snapshot </name >

<runningUser >[email protected]

</runningUser >

<sourceReport >myFolder/mytSummaryReport </sourceReport >

<targetObject >myObject__c </targetObject >

</AnalyticSnapshot >

SEE ALSO:

Report

126

Metadata Types ArticleType

ArticleType

Represents the metadata associated with an article type.

All articles in Salesforce Knowledge are assigned to an article type. An article's type determines the type of content it contains, its appearance, and which users can access it. For example, a simple FAQ article type might have two custom fields,

Question

and

Answer

, where article managers enter data when creating or updating FAQ articles. A more complex article type may require dozens of fields organized into several sections. Using layouts and templates, administrators can structure the article type in the most effective way for its particular content. User access to article types is controlled by permissions. For each article type, an administrator can grant

“Create,” “Read,” “Edit,” or “Delete” permissions to users. For example, the article manager might want to allow internal users to read, create, and edit FAQ article types, but let partner users only read FAQs. See “Knowledge Article Types” in the Salesforce online help and

“Articles” in the

SOAP API Developer's Guide

.

Declarative Metadata File Suffix and Directory Location

An ArticleType is defined as a custom object and is stored in the objects

folder. ArticleTypes have a suffix

__kav

(instead of

__c for custom objects). ArticleType field names have a suffix of

__c

like other custom objects, and must be dot-qualified with the name of the article type to which they belong. This is shown in the following sample package.xml

file:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<fullName >articlefilemetadata </fullName >

<apiAccessLevel >Unrestricted </apiAccessLevel >

<types >

<members >newarticle__kav.description__c

</members >

<name >CustomField </name >

</types >

<types >

<members >newarticle__kav </members >

<name >CustomObject </name >

</types >

</Package >

Version

ArticleTypes are available in API version 19.0 and later.

Fields

Field Name Field Type

articleTypeChannel

Display

articleTypeChannelDisplay

Description

Represents the article-type templates used to display an article in the various channels. See “Article Type Templates” in the Salesforce online help.

127

Metadata Types ArticleType

Field Name

deploymentStatus

Field Type

DeploymentStatus

( enumeration

of type string)

Description

A string which represents the deployment status of a custom object or field. Valid values are:

•

InDevelopment

•

Deployed description fields gender label pluralLabel startsWith string

CustomField[]

Gender

string string

StartsWith

(

enumeration

of type string)

A description of the article type. Maximum of 1000 characters.

Represents one or more fields in the article type.

Indicates the gender of the noun that represents the object. This is used for languages where words need different treatment depending on their gender.

Label that represents the object throughout the Salesforce user interface.

Plural version of the

label

value.

Indicates whether the noun starts with a vowel, consonant, or is a special character. This is used for languages where words need different treatment depending on the first character. Valid values are listed in

StartsWith .

articleTypeChannelDisplay

Determines the article-type templates that are used to display an article in its channels. Unless otherwise noted, all fields are createable, filterable, and nillable.

Field Name Field Type

articleTypeTemplates

articleTypeTemplates

Description

Indicates which article-type template applies in the specified channel.

articleTypeTemplates

Sets the article-type template for a specific channel. If not specified, the default article-type template applies.

Field Name

channel page

Field Type

string string

Description

Specifies the channel where the article-type template applies:

•

AllChannels

: all the available channels.

•

App

: the Articles tab in Salesforce Knowledge.

•

Pkb

: the public knowledge base.

•

Csp

: the Customer Portal.

•

Prm

: the partner portal.

Represents the name of the custom Visualforce page used as a custom article-type template. Use this field when you select

Page

in the template field.

128

Metadata Types

Field Name

template

Field Type

string

ArticleType

Description

Indicates the article-type template used for the specified channel:

•

Page

: custom Visualforce page. When specifying this value, you must also set the page

field with the Visualforce page name.

•

Tab

: display the sections you defined in the layout as tabs.

•

Toc

: display the sections you defined in the layout as table of content.

Declarative Metadata Sample Definitions

A sample article type definition follows:

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<articleTypeChannelDisplay >

<articleTypeTemplates >

<channel >App </channel >

<template >Tab </template >

</articleTypeTemplates >

<articleTypeTemplates >

<channel >Prm </channel >

<template >Tab </template >

</articleTypeTemplates >

<articleTypeTemplates >

<channel >Csp </channel >

<template >Tab </template >

</articleTypeTemplates >

<articleTypeTemplates >

<channel >Pkb </channel >

<template >Toc </template >

</articleTypeTemplates >

</articleTypeChannelDisplay >

<deploymentStatus >Deployed </deploymentStatus >

<description >Article type with custom fields </description >

<fields >

<fullName >description__c </fullName >

<label >Description </label >

<length >48 </length >

<type >Text </type >

</fields >

<label >newarticle </label >

<pluralLabel >newarticles </pluralLabel >

</CustomObject >

SEE ALSO:

ArticleType Layout

ArticleType CustomField

129

Metadata Types ArticleType Layout

ArticleType Layout

Represents the metadata associated with an article type page layout. Article type layouts determine which fields users can view and edit when entering data for an article, they also determine which sections appear when users view articles.

The format of the article, for example whether layout sections display as subtabs or as a single page with links, is defined by the

article-type template

. Each article type has only one layout, but you can choose a different template for each of the article type's four channels. For more information, see "Knowledge Article Types" in the Salesforce online help and “Articles” in the

SOAP API Developer's Guide

File Suffix and Directory Location

ArticleType layouts are stored in the layouts

directory of the corresponding package directory. The prefix must match with the article type API name. The extension is

.layout

.

Version

ArticleType layouts are available in API version 19.0 and later.

Fields

Field Name

layoutSections

Field Type

LayoutSection

[]

Description

The main sections of the layout containing the article fields. The order here determines the layout order.

LayoutSection

LayoutSection represents a section of an ArticleType layout.

Field Name

customLabel label layoutColumns style

Field Type

boolean string

LayoutColumn

[]

Description

Indicates if this section's label is custom or standard (built-in). Custom labels can be any text, but must be translated. Standard labels have a predefined set of valid values, for example 'System Information', which are automatically translated.

The label; either standard or custom, based on the customLabel

flag.

The columns of the layout, depending on the style. Salesforce Knowledge only supports one column in article type layouts.

LayoutSectionStyle

(

enumeration of type

string)

The style of the layout. Salesforce Knowledge only supports the value

OneColumn

which displays a one column page.

LayoutColumn

LayoutColumn represents the items in a column within a layout section.

130

Metadata Types ArticleType Layout

Field Name

layoutItems

Field Type

LayoutItem []

Description

The individual items within a column (ordered from top to bottom).

LayoutItem

LayoutItem represents the valid values that define a layout item.

Field Name

field

Field Type

string

Description

The field name reference, for example

MyField__c

.

Declarative Metadata Sample Definition

The following is the definition of an ArticleType page layout:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Layout xmlns= "http://soap.sforce.com/2006/04/metadata">

<layoutSections >

<customLabel >true </customLabel >

<label >Description </label >

<layoutColumns >

<layoutItems >

<field >description__c </field >

</layoutItems >

<layoutItems >

<field >dateTime__c </field >

</layoutItems >

</layoutColumns >

<style >OneColumn </style >

</layoutSections >

<layoutSections >

<label >Data Sheet </label >

<layoutColumns >

<layoutItems >

<field >file__c </field >

</layoutItems >

</layoutColumns >

<style >OneColumn </style >

</layoutSections >

</Layout >

SEE ALSO:

ArticleType

ArticleType CustomField

131

Metadata Types ChannelLayout

ChannelLayout

Represents the metadata associated with an communication channel layout. Communication channel layouts allow admins to share article contents inline into communication channels (eg. email publisher, portal publisher, social publisher etc.). Admins can create a list of fields of an article type that they want to share for each communication channels and customize its order.

File Suffix and Directory Location

Channel layout components have the suffix

.channelLayout

and are stored in the channelLayouts

folder of the corresponding package directory. The prefix must match with the article type API name.

Version

Channel layout components are available in API version 32.0 and later.

Fields

Field Name

label layoutItems enabledChannels

Field Type

string layoutItem enabledChannel

Description

The label

The article fields contained in the layout. The order here determines the field order.

The channels where this layout applies.

layoutItem

Field Name

field enabledChannel

Field Type

string enum

Description

Name of the field. The format is <ArticleType name>.<Field name>

Enum name of the communcation channel (eg. email, portal etc)

Declarative Metadata Sample Definition

The following is an example of a Channel Layout component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<ChannelLayout xmlns= "http://soap.sforce.com/2006/04/metadata">

<label >layoutaaaa </label >

<layoutItems >

<field >ArticleTypeA.FieldA

</field >

</layoutItems >

<layoutItems >

<field >ArticleTypeA.FieldC

</field >

</layoutItems >

<enabledChannels >email </enabledChannels >

<enabledChannels >portal </enabledChannels >

</ChannelLayout >

132

Metadata Types ArticleType CustomField

The following is an example package.xml

that references the previous definition.

ArticleType CustomField

Represents the metadata associated with an article type custom field. Use this metadata type to create, update, or delete article type custom field definitions.

This type extends the

Metadata metadata type and inherits its

fullName

field.

Always specify the full name whenever you create or update a custom field. For example, a custom field on a custom object:

MyArticleType__kav.MyCustomField__c

Declarative Metadata File Suffix and Directory Location

Custom fields are defined as part of the article type. ArticleType field names have a suffix of

__c

like other custom objects, and must

be dot-qualified with the name of the article type to which they belong. See ArticleType

for more information.

Retrieving Custom Fields on Custom or Standard Objects

When you retrieve a custom or standard object, you return everything associated with the object. However, you can also retrieve only the custom fields for an object by explicitly naming the object and fields in package.xml

. The following definition in package.xml

retrieves the files objects/MyCustomObject__c.object

, objects/Account.object__c.object

, and objects/MyArticleType__kav.object

, each containing one custom field definition.

<types >

<members >MyCustomObject__c.MyCustomField__c

</members >

<members >Account.MyCustomAccountField__c

</members >

<members >MyArticleType__kav.MyOtherCustomField__c

</members >

<name >CustomField </name >

</types >

Version

ArticleTypes custom fields are available in API version 19.0 and later.

Fields for ArticleType

Unless otherwise noted, all fields are createable, filterable, and nillable.

Note:

If you create a knowledge validation rule, the errors always display at the top of the page, even if you add it beside the field. Therefore, write the errors descriptively so authors know how to satisfy the validation rule. For example, identify which field is causing the error. The Salesforce Classic user interface does not support field level error messages for articles.

Field Name

defaultValue

Field Type

string

Description

If specified, represents the default value of the field.

133

Metadata Types

Field Name

deleteConstraint description formula formulaTreatBlankAs fullName inlineHelpText label length picklist referenceTo relationshipLabel relationshipName

ArticleType CustomField

Field Type

DeleteConstraint

( enumeration

of type string) string string

TreatBlanksAs

( enumeration

of type string) string string string int

Picklist (Including

Dependent Picklist)

string string string

Description

Provides deletion options for lookup relationships. Valid values are:

SetNull

This is the default. If the lookup record is deleted, the lookup field is cleared.

Restrict

Prevents the record from being deleted if it’s in a lookup relationship.

Cascade

Deletes the lookup record as well as associated lookup fields.

For more information on lookup relationships, see “Object

Relationships” in the Salesforce Help.

Description of the field.

If specified, represents a formula on the field.

Indicates how to treat blanks in a formula. Valid values are

BlankAsBlank

and

BlankAsZero

.

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.

This value cannot be null

.

Represents the content of field-level help. For more information, see “Define Field-Level Help” in the Salesforce Help.

Label for the field. You cannot update the label for standard fields in Article Type such as Title, UrlName, Summary, etc.

Length of the field.

(Deprecated. Use this field in API version 37.0 and earlier only.

In later versions, use valueSet

instead.) If specified, the field is a picklist, and this field enumerates the picklist values and labels.

If specified, indicates a reference this field has to another object.

Label for the relationship.

If specified, indicates the value for one-to-many relationships.

For example, in the object MyObject that had a relationship to

YourObject, the relationship name might be YourObjects.

134

Metadata Types ArticleType CustomField

Field Name

required type

Field Type

boolean

FieldType

Description

Indicates whether the field requires a value on creation ( true

) or not ( false

).

Required. Indicates the field type for the field. Valid values are:

•

Checkbox

available in version 30.0 and later

•

Currency

•

ArticleCurrency

•

Date

•

DateTime

•

Email

•

File

•

Formula

•

Html

•

Lookup

•

Number

•

Percent

•

Phone

•

Picklist

•

DependentPicklist

•

MultiselectPicklist

•

Text

•

TextArea

•

LongTextArea

•

URL

Indicates the number of lines displayed for the field.

visibleLines int

Declarative Metadata Sample Definition

<?xml version="1.0" encoding="UTF-8"?>

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">

....

<fields>

<fullName>Comments__c</fullName>

<description>add your comments about this object here</description>

<label>Comments</label>

<length>32000</length>

<type>LongTextArea</type>

<visibleLines>30</visibleLines>

</fields>

135

Metadata Types ApexClass

....

</CustomObject>

SEE ALSO:

ArticleType

ArticleType Layout

ApexClass

Represents an Apex class. An Apex class is 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. For more information, see the

Force.com Apex Code

Developer's Guide

. This type extends the MetadataWithContent metadata type and inherits its

content

and fullName

fields.

Note: By default, you can’t deploy updates to an Apex class if there are one or more active jobs for that class. To deploy updates in this case, do one of the following.

•

Cancel Apex jobs before deploying changes to Apex code. Reschedule the jobs after the deployment.

•

Enable deployments with Apex jobs in the Salesforce user interface in the Deployment Settings page.

Supported Calls

All Metadata API calls except CRUD-Based Calls .

Declarative Metadata File Suffix and Directory Location

The file suffix is

.cls

for the class file. The accompanying metadata file is named

ClassName-meta.xml

.

Apex classes are stored in the classes

folder in the corresponding package directory.

Version

Apex classes are available in API version 10.0 and later.

Fields

This metadata type contains the following fields:

Field Name

apiVersion

Field Type

double content base64

Description

The API version for this class. Every class has an API version specified at creation.

The Apex class definition. 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. This field is inherited from the

MetadataWithContent component.

136

Metadata Types ApexClass

Field Name

fullName packageVersions status

Field Type

string

PackageVersion

[]

Description

The Apex class name. 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.

The list of installed managed package versions that are referenced by this Apex class.

For more information about managed packages, see the Force.com Quick

Reference for Developing Packages . For more information about package versions, see “About Package Versions” in the Salesforce online help. This field is available in API version 16.0 and later.

ApexCodeUnitStatus

(

enumeration of type string)

The current status of the Apex class. The following string values are valid:

•

Active

- The class is active.

•

Deleted

- The class is marked for deletion. This is useful for managed packages, because it allows a class to be deleted when a managed package is updated.

Note:

ApexCodeUnitStatus includes an

Inactive

option, but it is only supported for

ApexTrigger ; it is not supported for ApexClass.

PackageVersion

PackageVersion identifies a version of a managed package. A package version is a number that identifies the set of components uploaded in a package. The version number has the format

majorNumber.minorNumber.patchNumber

(for example, 2.1.3). The major and minor numbers increase to a chosen value during every major release. The

patchNumber

is generated and updated only for a patch release. It is available in API version 16.0 and later.

Field Name

namespace

Field Type

string majorNumber int

Description

Required. In a packaging context, a namespace prefix is a one to 15-character alphanumeric identifier that distinguishes your package and its contents from packages of other developers on AppExchange. Namespace prefixes are case-insensitive. For example, ABC and abc are not recognized as unique. Your namespace prefix must be globally unique across all Salesforce organizations.

It keeps your managed package under your control exclusively.

Salesforce automatically prepends your namespace prefix, followed by two underscores (“__”), to all unique component names in your Salesforce organization. A unique package component is one that requires a name that no other component has within Salesforce, such as custom objects, custom fields, custom links, s-controls, and validation rules. For more information about namespaces, see “Register a Namespace Prefix” in the Salesforce online help.

Required. The major number of the package version. A package version number has a

majorNumber.minorNumber

format.

137

Metadata Types ApexComponent

Field Name

minorNumber

Field Type

int

Description

Required. The minor number of the package version. A package version number has a

majorNumber.minorNumber

format.

Declarative Metadata Sample Definition

The following sample creates the

MyhelloWorld.cls

class, and the corresponding

MyHelloWorld.cls-meta.xml

metadata file.

MyHelloWorld.cls

file: public class MyHelloWorld {

// This method updates the Hello field on a list

// of accounts.

public static void addHelloWorld(Account[] accs){ for (Account a:accs){ if (a.Hello__c != 'World' )

}

} a.Hello__c = 'World' ;

}

MyHelloWorld.cls-meta.xml

:

<?xml

version= "1.0" encoding= "UTF-8"?>

<ApexClass xmlns= "http://soap.sforce.com/2006/04/metadata">

<apiVersion >39.0

</apiVersion >

</ApexClass >

SEE ALSO:

ApexTrigger

ApexComponent

Represents a Visualforce component. For more information, see “Visualforce” in the Salesforce online help. This type extends the

MetadataWithContent metadata type and inherits its

content

and fullName

fields.

Declarative Metadata File Suffix and Directory Location

The file suffix is

.component

for the page file. The accompanying metadata file is named

ComponentName-meta.xml

.

Visualforce components are stored in the components

folder in the corresponding package directory.

Version

Visualforce components are available in API version 12.0 and later.

138

Metadata Types ApexPage

Fields

This metadata type contains the following fields:

Field Name

apiVersion

Field Type

double content base64Binary description fullName string string label string packageVersions

PackageVersion

[]

Description

The API version for this Visualforce component. Every component has an API version specified at creation. This field is available in API version 16.0 and later.

The component content. 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. This field is inherited from the

MetadataWithContent component.

A description of what the component does.

The component 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. This field is inherited from the

Metadata

component.

Required. The label for this component.

The list of installed managed package versions that are referenced by this

Visualforce component.

Note: Package components and Visualforce custom component are distinct concepts. A package is comprised of many elements, such as custom objects, Apex classes and triggers, and custom pages and components.

For more information about managed packages, see the Force.com Quick

Reference for Developing Packages . For more information about package versions, see “About Package Versions” in the Salesforce online help. This field is available in API version 16.0 and later.

SEE ALSO:

ApexPage

ApexPage

Represents a Visualforce page. For more information, see “Visualforce” in the Salesforce online help. This type extends the

MetadataWithContent metadata type and inherits its

content

and fullName

fields.

Declarative Metadata File Suffix and Directory Location

The file suffix is

.page

for the page file. The accompanying metadata file is named

PageName-meta.xml

.

Visualforce pages are stored in the pages

folder in the corresponding package directory.

139

Metadata Types ApexPage

Version

Visualforce pages are available in API version 11.0 and later.

Fields

This metadata type contains the following fields:

Field Name

apiVersion

Field Type

double content description fullName availableInTouch label packageVersions base64Binary string string boolean confirmationTokenRequired boolean string

PackageVersion []

Description

Required. The API version for this page. Every page has an API version specified at creation. This field is available in API version 15.0 and later.

If you set this field to a number lower than 15.0, it will be changed to

15.0.

The page content. 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. This field is inherited from the MetadataWithContent

component.

A description of what the page does.

The page 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. This field is inherited from the

Metadata component.

Indicates if Visualforce tabs associated with the Visualforce page can be used in the Salesforce1 app. (Use of this field for Salesforce Touch is deprecated.). This field is available in API version 27.0 and later.

Standard object tabs that are overridden with a Visualforce page aren’t supported in Salesforce1, even if you set this field for the page. The default Salesforce1 page for the object is displayed instead of the

Visualforce page.

Indicates whether

GET

requests for the page require a CSRF confirmation token. This field is available in API version 28.0 and later.

If you change this field’s value from false

to true

, links to the page require a CSRF token to be added to them, or the page will be inaccessible.

Required. The label for this page.

The list of installed managed package versions that are referenced by this Visualforce page.

For more information about managed packages, see the Force.com

Quick Reference for Developing Packages . For more information about

140

Metadata Types

Field Name Field Type

ApexTestSuite

Description

package versions, see “About Package Versions” in the Salesforce online help. This field is available in API version 16.0 and later.

Declarative Metadata Sample Definition

The following sample creates the

MyPage.page

page, and the corresponding

MyPage.page-meta.xml

metadata file.

SampleApexPage.page

file:

<apex:page >

<h1 >Congratulations </h1 >

This is your new Page.

</apex:page >

SampleApexPage.page-meta.xml

:

<?xml

version= "1.0" encoding= "UTF-8"?>

<ApexPage xmlns= "http://soap.sforce.com/2006/04/metadata">

<description >This is a sample Visualforce page.

</description >

<label >SampleApexPage </label >

</ApexPage >

SEE ALSO:

ApexComponent

ApexTestSuite

Represents a suite of Apex test classes to include in a test run.

File Suffix and Directory Location

ApexTestSuite components have the suffix

.testSuite

and are stored in the testSuites

folder.

Version

ApexTestSuite components are available in API version 38.0 and later.

Fields

Field Name

testClassName

Field Type

string[]

Description

A list of Apex test classes, specified by name, to include in this test suite.

141

Metadata Types ApexTrigger

Declarative Metadata Sample Definition

To include namespaced tests in an Apex test suite, specify each namespace individually. Local Apex tests consist of all tests in the org that don’t originate from managed packages.

<?xml

version= "1.0" encoding= "UTF-8"?>

<ApexTestSuite xmlns= "http://soap.sforce.com/2006/04/metadata">

<testClassName >

LocalTestClass

</testClassName >

<!--

LocalTestClass

adds the test class named LocalTestClass. -->

<testClassName >

A*Class

</testClassName >

<!--

A*Class

adds AClass, AnotherClass, AwesomeClass, and so on. -->

<testClassName >

Namespace1.NamespacedTestClass

</testClassName >

<testClassName >* </testClassName > <!-- Adds all local tests. -->

<testClassName >

Namespace1

.* </testClassName > <!-- Adds all tests in Namespace1. -->

<testClassName >

Namespace2

.* </testClassName > <!-- Adds all tests in Namespace2. -->

</ApexTestSuite >

These syntaxes are supported in package.xml

. If the test classes in your suites are already present in the target org, you can omit the

ApexClass

type in package.xml

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >ApexClass </name >

</types >

<types >

<members >* </members >

<name >ApexTestSuite </name >

</types >

<version >38.0

</version >

</Package >

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >ApexClass </name >

</types >

<types >

<members >

Suite1

</members >

<members >

Suite2

</members >

<name >ApexTestSuite </name >

</types >

<version >38.0

</version >

</Package >

ApexTrigger

Represents an Apex trigger. A trigger is Apex code that executes before or after specific data manipulation language (DML) events occur, such as before object records are inserted into the database, or after records have been deleted. For more information, see “Manage

142

Metadata Types ApexTrigger

Apex Triggers” in the Salesforce online help. This type extends the MetadataWithContent metadata type and inherits its

content

and fullName

fields.

Supported Calls

All Metadata API calls except CRUD-Based Calls .

Declarative Metadata File Suffix and Directory Location

The file suffix is

.trigger

for the trigger file. The accompanying metadata file is named

TriggerName-meta.xml

.

Apex triggers are stored in the triggers

folder in the corresponding package directory.

Version

Triggers are available in API version 10.0 and later.

Fields

This metadata type contains the following fields:

Field Name

apiVersion content fullName packageVersions status

Field Type

double base64 string

PackageVersion

[]

Description

Required. The API version for this trigger. Every trigger has an API version specified at creation.

The Apex trigger definition. This field is inherited from the MetadataWithContent

component.

The Apex trigger name. 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.

The list of installed managed package versions that are referenced by this Apex trigger.

For more information about managed packages, see the Force.com Quick

Reference for Developing Packages . For more information about package versions, see “About Package Versions” in the Salesforce online help. This field is available in API version 16.0 and later.

ApexCodeUnitStatus

(

enumeration of type string)

Required. The current status of the Apex trigger. The following string values are valid:

•

Active

- The trigger is active.

•

Inactive

- The trigger is inactive, but not deleted.

•

Deleted

- The trigger is marked for deletion. This is useful for managed packages, because it allows a trigger to be deleted when a managed package is updated.

143

Metadata Types AppMenu

Declarative Metadata Sample Definition

The following sample creates the

MyhelloWorld.trigger

trigger, and the corresponding

MyHelloWorld.trigger-meta.xml

metadata file.

MyHelloWorld.

trigger

file: trigger helloWorldAccountTrigger on Account (before insert) {

Account[] accs = Trigger.new;

MyHelloWorld.addHelloWorld(accs);

}

MyHelloWorld.trigger-meta.xml

:

<?xml

version= "1.0" encoding= "UTF-8"?>

<ApexTrigger xmlns= "http://soap.sforce.com/2006/04/metadata">

<apiVersion >39.0

</apiVersion >

</ApexTrigger >

SEE ALSO:

ApexClass

AppMenu

Represents the Force.com app menu or the Salesforce1 navigation menu.

File Suffix and Directory Location

Each AppMenu component gets stored in a single file in the folder of the corresponding package directory. The filename uses the format

Feature.appMenu

.

•

There’s one app switcher app menu file stored in a file named

AppSwitcher.appMenu

.

•

There’s one Salesforce1 app menu file stored in a file named

Salesforce1.appMenu

.

These two files are located in the appMenus

folder. The

.appMenu

files are different from other named components, as there’s only one file for each AppMenu component. App menu files can’t be created or deleted.

Version

AppMenu components are available in API version 30.0 and later.

Fields

Field Name

appMenuItems

Field Type

AppMenuItem []

Description

A list of menu items in the app menu.

144

Metadata Types

AppMenuItem

Represents a menu item in the app menu.

Field Name

name type

Field Type

string string

Description

The API name of the item.

The type of application represented by this item.

Acceptable values for

AppSwitcher.appMenu

are:

•

ConnectedApp

•

CustomApplication

•

ServiceProvider

Acceptable values for

Salesforce1.appMenu

are:

•

CustomApplication

•

CustomTab

•

StandardAppMenuItem

.

The name for this item can be:

–

MyDay

–

Feed

–

Tasks

–

Dashboards

–

Search

–

People

(available only when Chatter is enabled)

–

Groups

(available only when Chatter is enabled)

Declarative Metadata Sample Definition

The following is an example of an AppSwitcher.appMenu file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<AppMenu xmlns= "http://soap.sforce.com/2006/04/metadata">

<appMenuItems >

<appMenuItem >

<name >standard__Sales </name >

<type >CustomApplication </type >

</appMenuItem >

<appMenuItem >

<name >standard__Support </name >

<type >CustomApplication </type >

</appMenuItem >

<appMenuItem >

<name >CustomApp1 </name >

<type >CustomApplication </type >

</appMenuItem >

<appMenuItem >

145

AppMenu

Metadata Types

<name >CustomApp2 </name >

<type >CustomApplication </type >

</appMenuItem >

<appMenuItem >

<name >ConnectedApp1 </name >

<type >ConnectedApp </type >

</appMenuItem >

</appMenuItems >

</AppMenu >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >AppSwitcher </members >

<name >AppMenu </name >

</types >

The following is an example of a

Salesforce1.appMenu

component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<AppMenu xmlns= "http://soap.sforce.com/2006/04/metadata">

<appMenuItems >

<appMenuItem >

<name >StandardItem1 </name >

<type >StandardAppMenuItem </type >

</appMenuItem >

<appMenuItem >

<name >StandardItem2 </name >

<type >StandardAppMenuItem </type >

</appMenuItem >

<appMenuItem >

<name >StandardItem3 </name >

<type >StandardAppMenuItem </type >

</appMenuItem >

<appMenuItem >

<name >CustomTab1 </name >

<type >CustomTab </type >

</appMenuItem >

</appMenuItems >

</AppMenu >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Salesforce1 </members >

<name >AppMenu </name >

</types >

146

AppMenu

Metadata Types ApprovalProcess

The following is an example of a package manifest used to deploy or retrieve all the available app menu metadata for an organization, using a wildcard:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >AppMenu </name >

</types >

<version >30.0

</version >

</Package >

Usage

Use

AppSwitcher.appMenu

to reorder the list of menu items that appears in the Force.com app menu. You can’t add app menu items to or remove app menu items from

AppSwitcher.appMenu

.

Use

Salesforce1.appMenu

to customize the list of menu items that appears in the Salesforce1 navigation menu by reordering, adding, or removing the app menu items.

ApprovalProcess

Represents the metadata associated with an approval process. An approval process automates how records are approved in Salesforce.

An approval process specifies each step of approval, including who to request approval from and what to do at each point of the process.

This type extends the

Metadata metadata type and inherits its

fullName

field.

Note:

•

To use approval processes on Salesforce Knowledge articles with the Metadata API, the article type must be deployed. For article version (_kav) in approval processes, the supported action types are: Knowledge Action, Email Alert, Field Update, and

Outbound Message.

•

Send actions and approval processes for email drafts aren’t supported in the Metadata API.

•

The metadata doesn’t include the order of active approval processes. You might need to reorder the approval processes in the destination org after deployment.

•

Before you implement an approval process for your organization, see “Considerations for Approvals” in the Salesforce Help.

File Suffix and Directory Location

ApprovalProcess components have the suffix

.approvalProcess

and are stored in the approvalProcesses

folder.

Version

ApprovalProcess components are available in API version 28.0 and later.

147

Metadata Types

Fields

Field Name

active

ApprovalProcess allowRecall allowedSubmitters approvalPageFields approvalStep description emailTemplate enableMobileDeviceAccess entryCriteria

Field Type

boolean boolean

ApprovalSubmitter

ApprovalPageField

ApprovalStep

string string boolean

[]

[]

ApprovalEntryCriteria

Description

Required. Whether the approval process is active.

After an approval process is activated, you can’t add, delete, or change the order of the steps or change its reject or skip behavior, even if the process is inactive.

Whether to allow submitters to recall approval requests.

If set to false

, only administrators can recall approval requests.

Required. An array of users who are allowed to submit records for approval.

Specifies which fields to display on the approval page, where the approver goes to approve or reject the record. By default, the approval page displays the following:

•

Name

field

•

Owner

field (except for child objects)

If you enable notifications in Salesforce1, keep in mind that approvers may view this list of fields on a mobile device. Select only the fields necessary for users to decide whether to approve or reject records.

An array of approval step definitions.

Describes the approval process.

Specifies which email template to use for approval requests.

If not specified, the default email template is used.

When an approval process assigns an approval request to a user, Salesforce sends the user an approval request email.

Whether users can access an external version of the approval page from any browser, including those on mobile devices, without logging in to Salesforce. Corresponds to

Security

Settings

in the user interface.

If set to true

, approval steps can’t have approvers of type adhoc

.

If set to false

, approvers must log in to Salesforce to access the approval page.

Determines which records can enter the approval process.

Exclude this field to allow all records to enter the approval process.

148

Metadata Types ApprovalProcess

Field Name

finalApprovalActions finalApprovalRecordLock finalRejectionActions finalRejectionRecordLock initialSubmissionActions label nextAutomatedApprover postTemplate recallActions recordEditability

Field Type

ApprovalAction

boolean

ApprovalAction

boolean

ApprovalAction

string

NextAutomatedApprover

string

Description

Specifies which workflow actions to execute when all required approvals have been given for a record.

Whether to keep the record locked after it receives all necessary approvals. Default: false

.

Specifies which workflow actions to execute after a record enters the final rejection state.

Whether to keep the record locked after it’s finally rejected.

Default: false

.

Specifies which workflow actions to execute when a record is initially submitted for approval.

Required. Name of the approval process.

Specifies a standard or custom user hierarchy field that can be used to automatically assign the approver for an approval step.

If you exclude this field, then no approval step can use a user hierarchy field to automatically assign the approver.

Post template to use for Approvals in Chatter.

Chatter post approval notifications are only available for approval processes associated with an object that has been enabled for feed tracking.

ApprovalAction

RecordEditabilityType

(enumeration of type string)

Specifies which workflow actions to execute when a pending approval request is withdrawn.

Specifies which users can edit records that are pending approval. When a record is submitted for approval, it is automatically locked to prevent other users from editing it during the approval process. Valid values are:

•

AdminOnly

—Records pending approval can be edited by:

–

Users with the “Modify All Data” permission

–

Users with the “Modify All” object-level permission for the given object

•

AdminOrCurrentApprover

—Records pending approval can be edited by:

–

Users with the “Modify All Data” permission

–

Users with the “Modify All” object-level permission for the given object

–

The assigned approver, who must have edit access to the record through user permissions and the organization-wide sharing defaults for the given object

149

Metadata Types

Field Name

showApprovalHistory

Field Type

boolean

ApprovalProcess

Description

Whether to add the Approval History related list to the approval page, which is where the approver can view the approval request details and approve or reject the record. The

Approval History related list tracks a record through the approval process.

If you also want to add the Approval History related list to record detail and edit pages, use the Salesforce user interface to customize the page layouts for the given object.

ApprovalSubmitter

Represents a user or set of users who can submit records for approval.

Field Name

submitter

Field Type

string

Description

Identifies a specific user or set of users who can submit records for approval. This field is required, except when the following types are specified and the submitter field is ignored:

•

owner

•

creator

•

allInternalUsers

Example:

<allowedSubmitters >

<type >allInternalUsers </type >

</allowedSubmitters >

<allowedSubmitters >

<submitter >myGroup </submitter >

<type >group </type >

</allowedSubmitters > type

ProcessSubmitterType

(enumeration of type string)

Required. Type of user or set of users who can submit records for approval. Valid values are:

•

group

•

role

•

user

•

roleSubordinates

•

roleSubordinatesInternal

•

owner

•

creator

•

partnerUser

•

customerPortalUser

•

portalRole

150

Metadata Types

Field Name Field Type

ApprovalProcess

Description

•

portalRoleSubordinates

•

allInternalUsers

—all Salesforce users in the organization

ApprovalPageField

Represents the selection of fields to display on the approval page, where an approver can view the approval request details and approve or reject the record.

Field Name

field

Field Type

string[]

Description

An array of fields that are displayed on the page for the approver to approve or reject the record.

ApprovalStep

Represents a step in the approval process. Approval steps define the chain of approval for a particular approval process. Each step determines which records can advance to that step, who to assign approval requests to, and whether to let each approver’s delegate respond to the requests. The first step specifies what to do if a record doesn’t advance to that step. Later steps specify what happens if an approver rejects the request.

Note:

•

The order of the

ApprovalStep

entries in the approval process definition determines the order in which the approval steps are executed.

•

After an approval process is activated, you can’t add, delete, or change the order of the steps or change its reject or skip behavior, even if the process is inactive.

•

Each approval process supports up to 30 steps.

Field Name

allowDelegate approvalActions assignedApprover description entryCriteria

Field Type

boolean

ApprovalAction

ApprovalStepApprover

string

ApprovalEntryCriteria

Description

Whether to allow delegated approvers in this step of the approval process. A delegated approver is a user appointed by an assigned approver as an alternate for approval requests.

Specifies which workflow actions to execute when a record is approved in this step of the approval process.

Specifies the assigned approvers for this step of the approval process.

Describes the approval step.

Determines which records can enter this step of the approval process.

151

Metadata Types ApprovalProcess

Field Name

ifCriteriaNotMet label name rejectBehavior rejectionActions

Field Type

StepCriteriaNotMetType

(enumeration of type string) string string

ApprovalStepRejectBehavior

ApprovalAction

Description

Specifies what to do for records that don’t meet the entry criteria. Valid values are:

•

ApproveRecord

—Approve the request and execute all final approval actions.

•

RejectRecord

—Reject the request and execute all final rejection actions. This option is available only for the first step in the approval process.

•

GotoNextStep

—Skip to the next approval step. If you select this option for the first approval step, and a record doesn’t meet the entry criteria for any other step, the record is rejected.

Required. Name of the approval step.

Required. Unique name of the approval step. It must contain only underscores and alphanumeric characters, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. The requirement for uniqueness is only within the specific approval process.

Required, except for the first step in the approval process.

Specifies what happens if the approver rejects the request during this approval step, unless it’s the first step in the approval process.

If the approver rejects the request in the first step in the approval process, the reject behavior is determined by the finalRejectionActions

.

Specifies which workflow actions to execute when a record is rejected in this step of the approval process.

ApprovalAction

Represents the actions that occur as a result of an approval process.

Field Name

action

Field Type

WorkflowActionReference []

Description

An array of workflow actions to execute.

ApprovalStepApprover

Represents the assigned approvers for an approval step. Each step supports up to 25 approvers.

Field Name

approver

Field Type

Approver []

Description

An array of assigned approvers for this step of the approval process.

152

Metadata Types ApprovalProcess

Field Name

whenMultipleApprovers

Field Type

RoutingType

(enumeration of type string)

Description

Specifies how to handle approval or rejection when multiple approvers are assigned to the step. Valid values are:

•

Unanimous

—(Default) Require unanimous approval from all approvers for this step. The approval request for this step is rejected if any of the approvers reject the request.

•

FirstResponse

—Approve or reject based on the first response.

Approver

Represents an assigned approver for an approval step. Check out the Salesforce Help for Considerations for Setting Approvers.

Field Name

name

Field Type

string type

NextOwnerType

(enumeration of type string)

Description

Identifies an assigned approver. This field is required, except when the type

is one of the following and the name

is ignored:

•

adhoc

•

userHierarchyField

Combined with the specified name

, this identifies an assigned approver. Valid values are:

•

adhoc

—The approver for the step must be selected manually. For the first step, the submitter selects the approver. For the second and later steps, the approver for the previous step selects the approver. For this value, exclude the name

field.

•

user

—A user in your organization. For this value, enter a username for the name field.

•

userHierarchyField

—A user specified in a standard or custom user hierarchy field, such as the standard

Manager

field. For this value, exclude the name

field.

The user hierarchy field must be defined in the

nextAutomatedApprover

for the approval process.

•

relatedUserField

—A user specified in a user lookup field on the submitted record, such as the

Last Modified By

field. For this value, enter the name of the user lookup field for the name

field.

•

queue

—Automatically assign to a queue. For this value, enter the name of the queue for the name

field.

ApprovalEntryCriteria

Represents the criteria that records must meet to enter the approval process or an approval step. Specify either filter criteria or a formula, but not both.

Field Name

booleanFilter

Field Type

string

Description

Filter logic for criteriaItems

. Exclude this field if you enter a formula

.

153

Metadata Types ApprovalProcess

Field Name

criteriaItems formula

Field Type

FilterItem

[] string

Description

Filter criteria that a record must meet to enter the approval process or approval step.

Approval processes don’t support valueField

entries in filter criteria.

Formula that must evaluate to true for a record to enter the approval process or approval step.

ApprovalStepRejectBehavior

Represents what happens if the approver rejects the request during this approval step, unless it’s the first step in the approval process.

For the first step in the approval process, the reject behavior is determined by the approval process’s final rejection actions.

Field Name

type

Field Type Description

StepRejectBehaviorType

(enumeration of type string)

Not allowed in the first step of the approval process. Valid values are:

•

RejectRequest

—Rejects the request completely even if previous steps were approved. Salesforce performs all rejection actions specified for this step and all final rejection actions.

•

BackToPrevious

—Rejects the request, and returns the approval request to the previous approver. Salesforce performs all rejection actions specified for this step.

NextAutomatedApprover

Represents the user hierarchy field to use as the next automated approver for the approval process. If defined, the user specified in the hierarchy field can be automatically assigned as the approver in one or more approval steps.

Description Field Name Field

Type

useApproverFieldOfRecordOwner boolean userHierarchyField string

Required. Whether the first executed approval step should use the specified userHierarchyField

in the record owner’s user record—instead of the submitter’s user record—as the approver. All remaining steps use the specified userHierarchyField

in the user record of the preceding step’s approver.

Required. Standard or custom user hierarchy field whose value specifies which user to assign as the approver. For example, the standard

Manager

hierarchy field can be used to assign approvers for employee

PTO (paid time off) requests.

154

Metadata Types

Declarative Metadata Sample Definition

The following is an example of an ApprovalProcess component:

<?xml

version= "1.0" encoding= "UTF-8"?>

<ApprovalProcess xmlns= "http://soap.sforce.com/2006/04/metadata">

<active >false </active >

<allowRecall >false </allowRecall >

<allowedSubmitters >

<type >owner </type >

</allowedSubmitters >

<allowedSubmitters >

<submitter >USSalesRep </submitter >

<type >role </type >

</allowedSubmitters >

<allowedSubmitters >

<submitter >MarketingGroup </submitter >

<type >group </type >

</allowedSubmitters >

<allowedSubmitters >

<submitter >[email protected]

</submitter >

<type >user </type >

</allowedSubmitters >

<approvalPageFields >

<field >Name </field >

<field >Owner </field >

<field >MyLeadCustomField__c </field >

<field >Address </field >

</approvalPageFields >

<approvalStep >

<allowDelegate >false </allowDelegate >

<approvalActions >

<action >

<name >LeadApprovedTask1 </name >

<type >Task </type >

</action >

<action >

<name >LeadApprovedTask2 </name >

<type >Task </type >

</action >

</approvalActions >

<assignedApprover >

<approver >

<type >adhoc </type >

</approver >

</assignedApprover >

<label >Step1 </label >

<name >Step1 </name >

<rejectionActions >

<action >

<name >LeadRejectedTask </name >

<type >Task </type >

</action >

</rejectionActions >

</approvalStep >

155

ApprovalProcess

Metadata Types

<approvalStep >

<allowDelegate >false </allowDelegate >

<assignedApprover >

<approver >

<type >userHierarchyField </type >

</approver >

</assignedApprover >

<entryCriteria >

<criteriaItems >

<field >Lead.CreatedDate

</field >

<operation >greaterThan </operation >

<value >3/25/2013 </value >

</criteriaItems >

<criteriaItems >

<field >User.IsActive

</field >

<operation >notEqual </operation >

<value >true </value >

</criteriaItems >

</entryCriteria >

<ifCriteriaNotMet >ApproveRecord </ifCriteriaNotMet >

<label >Step2 </label >

<name >Step2 </name >

<rejectBehavior >

<type >RejectRequest </type >

</rejectBehavior >

</approvalStep >

<approvalStep >

<allowDelegate >true </allowDelegate >

<assignedApprover >

<approver >

<name >MarketingTeamQueue </name >

<type >queue </type >

</approver >

<approver >

<name >LastModifiedBy </name >

<type >relatedUserField </type >

</approver >

<approver >

<name >[email protected]

</name >

<type >user </type >

</approver >

<whenMultipleApprovers >FirstResponse </whenMultipleApprovers >

</assignedApprover >

<entryCriteria >

<formula >CONTAINS( MyLeadCustomField__c , 'Salesforce') </formula >

</entryCriteria >

<label >Step3 </label >

<name >Step3 </name >

<rejectBehavior >

<type >BackToPrevious </type >

</rejectBehavior >

</approvalStep >

<emailTemplate >MyFolder/LeadsNewassignmentnotification </emailTemplate >

<enableMobileDeviceAccess >false </enableMobileDeviceAccess >

ApprovalProcess

156

Metadata Types

<entryCriteria >

<criteriaItems >

<field >Lead.AnnualRevenue

</field >

<operation >greaterThan </operation >

<value >10500 </value >

</criteriaItems >

<criteriaItems >

<field >Lead.MyLeadCustomField__c

</field >

<operation >equals </operation >

<value >Salesforce </value >

</criteriaItems >

</entryCriteria >

<finalApprovalActions >

<action >

<name >LeadEmailContacted </name >

<type >Alert </type >

</action >

</finalApprovalActions >

<finalApprovalRecordLock >true </finalApprovalRecordLock >

<finalRejectionActions >

<action >

<name >ProcessRejectedMessageAction </name >

<type >OutboundMessage </type >

</action >

</finalRejectionActions >

<finalRejectionRecordLock >false </finalRejectionRecordLock >

<initialSubmissionActions >

<action >

<name >LeadFieldUpdate </name >

<type >FieldUpdate </type >

</action >

<action >

<name >NewLeadEmail </name >

<type >Alert </type >

</action >

</initialSubmissionActions >

<label >SampleProcess </label >

<nextAutomatedApprover >

<useApproverFieldOfRecordOwner >false </useApproverFieldOfRecordOwner >

<userHierarchyField >customlookupuserfield__c </userHierarchyField >

</nextAutomatedApprover >

<postTemplate >MyPostTemplate </postTemplate >

<recallActions >

<action >

<name >ProcessRecalledMessageAction </name >

<type >OutboundMessage </type >

</action >

</recallActions >

<recordEditability >AdminOnly </recordEditability >

<showApprovalHistory >false </showApprovalHistory >

</ApprovalProcess >

ApprovalProcess

157

Metadata Types AssignmentRules

AssignmentRules

Represents assignment rules that allow you to automatically route cases to the appropriate users or queues. You can access rules metadata for all applicable objects, for a specific object, or for a specific rule on a specific object. The package.xml

syntax for accessing all assignment rules for all objects is:

<types>

<members>*</members>

<name>AssignmentRules</name>

</types>

All rules for a specific object uses a similar syntax without the wildcard. For example, all assignment rules for the Case object would use this syntax:

<types>

<members>Case</members>

<name>AssignmentRules</name>

</types>

You can also access specific assignment rules for an object. The following example only accesses the “samplerule” and “newrule” assignment rules on the Case object. Notice that for this example the type name syntax is

AssignmentRule

and not

AssignmentRules

.

<types>

<members>Case.samplerule</members>

<members>Case.newrule</members>

<name>AssignmentRule</name>

</types>

File Suffix and Directory Location

Assignment rules for an object have the suffix

.assignmentRules

and are stored in the assignmentRules

folder. For example, all Case assignment rules are stored in the

Case.assignmentRules

file.

Version

AssignmentRules components are available in API version 27.0 and later.

Fields

Field Name

assignmentRule

Field Type

AssignmentRule[]

Description

Represents the definitions of the named assignment rules.

AssignmentRule

Specifies whether the rule is active or not and its definition. Rules are processed in the order they appear within the AssignmentRules container.

158

Metadata Types AssignmentRules

Field Name

active fullname ruleEntry

Field Type

boolean string

RuleEntry[]

Description

Indicates whether the assignment rule is active ( true

) or not ( false

).

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.

This value cannot be null

.

Represents the type and description for the assignment rule.

RuleEntry

Represents the fields used by the rule.

Field Name

assignedTo assignedToType booleanFilter criteriaItems formula notifyCcRecipients overrideExistingTeams team template

Field Type

string

Description

The name of the user or queue the item is assigned to.

AssignToLookupValueType

(

enumeration

of type string)

Valid values are:

•

User

•

Queue string

FilterItem[]

string boolean boolean string[] string

Advanced filter conditions that were specified for the rule.

The items in the list that define the assignment criteria.

The validation formula.

Note: Specify either formula

or criteriaItems

, but not both fields.

Specifies whether email addresses included on the Cc line of an incoming Email-to-Case or Web-to-Lead message should be included on the Cc line of the auto-response to that message ( true

) or not ( false

). Available in API version 32.0 and later.

Specifies whether the case team should be reset when the assignment is done true

) or if the current team is added to the case instead of replacing the previous team ( false

).

The name of the case team. It may occur 0 or more times.

Specifies the template to use for the email that is automatically sent to the designated recipient.

159

Metadata Types AuraDefinitionBundle

Declarative Metadata Sample Definition

The following is an example file showing two assignment rules on the Case object:

<AssignmentRules xmlns= "http://soap.sforce.com/2006/04/metadata" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance">

<assignmentRule >

<fullName >samplerule </fullName >

<active >false </active >

<ruleEntry >

<assignedTo >[email protected]

</assignedTo >

<assignedToType >User </assignedToType >

<criteriaItems >

<field >Case.IsEscalated

</field >

<operation >equals </operation >

<value >True </value >

</criteriaItems >

<template >emailtemplate </template >

</ruleEntry >

</assignmentRule >

<assignmentRule >

<fullName >Another samplerule </fullName >

<active >false </active >

<ruleEntry >

<assignedTo >[email protected]

</assignedTo >

<assignedToType >User </assignedToType >

<criteriaItems >

<field >Case.IsEscalated

</field >

<operation >equals </operation >

<value >False </value >

</criteriaItems >

<template >emailtemplate </template >

</ruleEntry >

</assignmentRule >

</AssignmentRules >

AuraDefinitionBundle

Represents a Lightning definition bundle. A bundle contains a Lightning definition and all its related resources. The definition can be a component, application, event, interface, or a tokens collection.

File Suffix and Directory Location

A Lightning bundle is a folder that contains definition files. Unlike other metadata components, an AuraDefinitionBundle component isn’t represented by a single component file but instead by a collection of component definition files. Each definition file represents a resource in a bundle, such as markup, applications, code files (including controllers and helpers), events, documentation, and interfaces.

For example, this directory structure shows the hierarchy of the folders and files for two bundles: bundle1

and bundle2

.

aura bundle1 bundle1.cmp

bundle1Controller.js

160

Metadata Types AuraDefinitionBundle

Suffix

.app

.cmp

.design

.evt

.intf

.js

.svg

.css

.auradoc

.tokens

bundle2 bundle2.app

bundle2.cmp

bundle2Controller.js

bundle2.auradoc

Lightning bundles must be under a top-level folder that’s named aura

. Each bundle must have its own subfolder under the aura folder. The name of each definition file must start with the bundle name.

A bundle doesn’t have a suffix. Definition files can have one of these suffixes:

Component Type

Application

Component

Design

Event

Interface

Controller, Helper, or Renderer

SVG image

Style

Documentation

Tokens collection

Each bundle can have only one file each with a suffix of

.app

,

.cmp

,

.design

,

.evt

,

.intf

, or

.tokens

.

Version

AuraDefinitionBundle components are available in API version 32.0 and later.

Design and SVG components are available in API version 33.0 and later.

Special Access Rules

Definitions can be created only in organizations with defined namespaces.

Fields

Field Name

apiVersion

Field Type

double

Description

The API version for this definition bundle. When you create an Aura bundle, you can specify the API version to save it with. Available in API version 35.0 and later.

161

Metadata Types

Field Name

controllerContent description designContent documentationContent helperContent markup modelContent packageVersions rendererContent styleContent

SVGContent testsuiteContent type

AuraDefinitionBundle

Field Type

base64Binary string base64Binary base64Binary base64Binary base64Binary base64Binary

PackageVersion[]

base64Binary base64Binary base64Binary base64Binary

AuraBundleType

(enumeration of type string)

Description

The content of a JavaScript client-side controller.

The specification of the Aura bundle. Available in API version 35.0 and later.

The content of a design definition. Only valid inside a component bundle.

The content of a documentation definition.

The content of a JavaScript helper.

The content of the markup for a definition.

Deprecated. Do not use.

The list of installed managed package versions that this Aura definition bundle references. Available in API version 35.0 and later.

The content of a JavaScript client-side renderer.

The CSS for the definition.

The SVG image for the definition.

Reserved for future use.

The definition type. Valid values are:

•

Application

•

Component

•

Event

•

Interface

•

Tokens

Declarative Metadata Sample Definition

This example shows the directory structure of an AuraDefinitionBundle component.

aura sampleCmp sampleCmp.cmp

sampleCmpController.js

The following samples show the contents of the metadata definition files that correspond to the sample aura

directory.

Content of sampleCmp.cmp

:

<aura:component >

<aura:attribute name= "val1" type= "String" default= "Value"/>

<aura:attribute name= "val2" type= "String" />

<aura:handler name= "init" value= "{!this}" action= "{!c.myAction}"/>

<ui:outputText value= 'Hello world!'/>

<ui:outputText value= '{!v.val1}'/>

162

Metadata Types AuthProvider

<ui:outputText value= '{!v.val2}'/>

</aura:component >

Content of sampleCmpController.js

:

({ myAction : function(component) { component.set('v.val1','Value1');

}) component.set('v.val2','Value2');

}

This package.xml

references the definitions of all Lightning components that are present in the sampleCmp

bundle.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >sampleCmp </members >

<name >AuraDefinitionBundle </name >

</types >

<version >39.0

</version >

</Package >

AuthProvider

Represents an authentication provider (or auth provider) in your organization. An auth provider enables users to log in to your Salesforce organization using their login credentials from an external service provider such as Facebook

©

or Janrain

©

. This type extends the Metadata

metadata type and inherits its fullName

field.

File Suffix and Directory Location

Authentication providers are stored in the authproviders

directory. The file name matches the URL suffix and the extension is

.authprovider

. For example, an auth provider with URL suffix

FacebookProvider

is stored in authproviders/FacebookProvider.authprovider

.

Version

Authentication providers are available in API version 27.0 and later.

Special Access Rules

Only users with the “Customize Application” and “Manage AuthProviders” permissions can access this object.

163

Metadata Types

Fields

Field Name

authorizeUrl

AuthProvider consumerKey consumerSecret customMetadataTypeRecord defaultScopes

Field Type

string string string string string

Description

Required, but only if providerType

is

OpenIdConnect

. The OAuth authorization endpoint URL. Used only with OpenID Connect authentication providers. Available in API version 29.0 and later.

In API version 33.0 and later, the behavior of this field changed to support the Salesforce-managed auth provider configuration, which allows

Salesforce to manage the value for Facebook, Salesforce, LinkedIn, Twitter

or Google authentication. For more information, see the Usage section.

Required. The app’s key that is registered at the third-party single sign-on provider.

In API version 33.0 and later, the behavior of this field changed to support the Salesforce-managed auth provider configuration, which allows

Salesforce to manage the value for Facebook, Salesforce, LinkedIn, Twitter

or Google authentication. For more information, see the Usage section.

Required. The consumer secret of the app that is registered at the third-party single sign-on provider. This field cannot be updated. When using create()

this field must be encrypted. To create an encrypted form of the consumer secret from plain text:

1. Create an auth provider with the consumerSecret

plain text value.

2. Save the auth provider.

3. Create an outbound change set that includes the auth provider component.

The new change set .xml file will have an entry in the form

<consumerSecret >++XYZ++ </consumerSecret >

where

++XYZ++ is the encrypted secret.

In API version 33.0 and later, the behavior of this field changed to support the Salesforce-managed auth provider configuration, which allows

Salesforce to manage the value for Facebook, Salesforce, LinkedIn, Twitter

or Google authentication. For more information, see the Usage section.

Required, but only with custom authentication provider plug-ins, when

ProviderType

is

Custom

. The API name of the authentication provider. Available in API version 36.0 and later.

Required, but only if providerType

is

OpenIdConnect

The scopes to be sent with the authorization request, if not specified when a flow is started. Used only with OpenID Connect authentication providers. Available in API version 29.0 and later.

In API version 33.0 and later, the behavior of this field changed to support the Salesforce-managed auth provider configuration, which allows

164

Metadata Types

Field Name

DeveloperName errorUrl executionUserId friendlyName iconUrl idTokenIssuer logoutUrl plugin providerType

AuthProvider

Field Type Description

Salesforce to manage the value for Facebook, Salesforce, LinkedIn, Twitter

or Google authentication. For more information, see the Usage section.

string string string string string string string

Required. Used when referring to the auth provider from a program.

A custom error URL for the provider to use to report any errors.

The user that runs the Apex handler class. The user must have the “Manage

Users” permission. A user is required if you specify a registration handler class.

Required. A user-friendly name for the provider.

The path to an icon to use as a button on the login page for a community.

Users click the button to log in to a community with the associated authentication provider, such as Twitter

©

or LinkedIn

©

. Available in API version 32.0 and later.

Only available if providerType

is

OpenIdConnect

. This value identifies the source of the authentication token in the form

https:

URI

. Used only with OpenID Connect authentication providers. If provided,

Salesforce validates the returned id_token

value. The OpenID Connect specification requires an id_token

value to be returned with the access_token

value. Available in API version 30.0 and later.

Provides a specific destination for users after they log out if they authenticated using the single sign-on flow. The URL must be fully qualified with an http

or https

prefix, such as https://acme.my.salesforce.com

. Available in API version

33.0 and later.

string An existing Apex class that extends the

Auth.AuthProviderPluginClass

abstract class. Available in

API version 36.0 and later.

AuthProviderType

( enumeration of

type string)

Required. The third-party single sign-on provider to use. Valid values are:

•

Facebook

•

Google

•

Salesforce

•

Janrain

•

LinkedIn

(Available in API version 32.0 and later.)

•

Twitter

(Available in API version 32.0 and later.)

•

OpenIdConnect

(Available in API version 29.0 and later.)

Note: This type requires values for the following fields:

–

authorizeUrl

–

defaultScopes

–

tokenUrl

165

Metadata Types

Field Name

registrationHandler string sendAccessTokenInHeader boolean sendClientCredentialsInHeader tokenUrl userInfoUrl

Field Type

boolean string string

AuthProvider

Description

–

userInfoUrl

•

MicrosoftACS

Microsoft Access Control Service typically provides authentication for a Microsoft Office 365 service like SharePoint

®

Online.

(Available in API version 31.0 and later.)

•

GitHub

—Use the

GitHub

provider to log in users of your Force.com

app to GitHub using OAuth. When logged in to GitHub, your app can make calls to GitHub APIs. The

GitHub

provider isn’t available as a single sign-on provider, so users can’t log in to your Salesforce org using their GitHub login credentials. (Available in API version 35.0 and later.)

•

Custom

—A provider configured with a custom authentication provider plug-in. (Available in API version 36.0 and later.)

An existing Apex class that implements the

Auth.RegistrationHandler

interface.

Required only if providerType

is

OpenIdConnect

. When true

, the access token is sent to the userInfoUrl

in a header instead of a query string. Used only with OpenID Connect authentication providers.

Available in API version 30.0 and later.

Required only if providerType

is

OpenIdConnect

. When true

, the client credentials are sent in a header, instead of a query string, to the tokenUrl

. The credentials are in the standard OpenID Connect Basic

Credentials header form, which is

Basic <token>

, where

<token> is the base64-encoded string

"clientkey:clientsecret"

. Used only with OpenID Connect authentication providers. Available in API version

30.0 and later.

Required, but only if providerType

is

OpenIdConnect

. The OAuth token endpoint URL. Used only with OpenID Connect authentication providers. Available in API version 29.0 and later.

In API version 33.0 and later, the behavior of this field changed to support the Salesforce-managed auth provider configuration, which allows

Salesforce to manage the value for Facebook, Salesforce, LinkedIn, Twitter

or Google authentication. For more information, see the Usage section.

Required, but only if providerType

is

OpenIdConnect

. The

OpenID Connect endpoint URL. Used only with OpenID Connect authentication providers. Available in API version 29.0 and later.

In API version 33.0 and later, the behavior of this field changed to support the Salesforce-managed auth provider configuration, which allows

Salesforce to manage the value for Facebook, Salesforce, LinkedIn, Twitter

or Google authentication. For more information, see the Usage section.

166

Metadata Types AutoResponseRules

Declarative Metadata Sample Definition

<?xml

version= "1.0" encoding= "UTF-8"?>

<AuthProvider xmlns= "http://soap.sforce.com/2006/04/metadata">

<consumerKey >yourappkey </consumerKey >

<consumerSecret>PwdVxXjzu3NCZ3MD4He+wA= = </consumerSecret >

<executionUser >[email protected]

</executionUser >

<friendlyName >FacebookAuthProvider </friendlyName >

<providerType >Facebook </providerType >

<registrationHandler >RegistrationHandler </registrationHandler >

</AuthProvider >

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

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >FacebookAuthProvider </members >

<name >AuthProvider </name >

</types >

<version >28.0

</version >

</Package >

Usage

For API version 33.0 and later when implementing the Salesforce-managed authentication provider configuration, you can have Salesforce create and manage the following fields for you:

•

authorizeUrl

•

consumerKey

•

consumerSecret

•

defaultScopes

•

tokenURL

•

userInfoUrl

To configure a Salesforce-managed authentication provider, set up a Facebook, Salesforce, LinkedIn, Twitter or Google auth provider and leave all of the listed fields blank. Salesforce automatically creates values for you. However, if you provide a value for any of these fields, then consumerKey

and consumerSecret

must also be specified.

AutoResponseRules

Represents an auto-response rule that sets conditions for sending automatic email responses to lead or case submissions based on the attributes of the submitted record. You can access rules metadata for all applicable objects, for a specific object, or for a specific rule on a specific object. The package.xml

syntax for accessing all auto-response rules for all objects is:

<types>

<members>*</members>

<name>AutoResponseRules</name>

</types>

167

Metadata Types AutoResponseRules

All rules for a specific object uses a similar syntax without the wildcard. For example, all auto-response rules for the Case object would use this syntax:

<types>

<members>Case</members>

<name>AutoResponseRules</name>

</types>

You can also access specific auto-response rules for an object. The following example only accesses the “samplerule” and “newrule” auto-response rules on the Case object. Notice that for this example the type name syntax is

AutoResponseRule

and not

AutoResponseRules

.

<types>

<members>Case.samplerule</members>

<members>Case.newrule</members>

<name>AutoResponseRule</name>

</types>

File Suffix and Directory Location

AutoResponseRules for an object have the suffix

.autoResponseRules

and are stored in the autoResponseRules

folder.

For example, all Case auto-response rules are stored in the

Case.autoResponseRules

file.

Version

AutoResponseRules components are available in API version 27.0 and later.

Fields

Field Name

autoresponseRule

Field Type Description

AutoResponseRule[]

Represents the definitions of the named auto-response rules.

AutoResponseRule

Represents whether a rule is active or not and the order in which the entry is processed in the rule.

Field Name

active fullname

Field Type

boolean string

Description

Indicates whether the autoresponse rule is active ( true

) or not ( false

).

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.

This value cannot be null

.

168

Metadata Types AutoResponseRules

Field Name

ruleEntry

Field Type

RuleEntry[]

Description

Represents the type and description for the auto-response rule.

RuleEntry

Represents the fields used by the rule.

Field Name

booleanFilter criteriaItems formula replyToEmail senderEmail senderName template string string string string

Field Type

string

FilterItem[]

string

Description

Advanced filter conditions that were specified for the rule.

The items in the list that define the assignment criteria.

The validation formula.

Note: Specify either formula

or criteriaItems

, but not both fields.

The email address that appears in the reply-to header.

The email address of the person or queue sending the email notification.

The name of the person or queue sending the email notification.

Specifies the template to use for the email that is automatically sent to the designated recipient.

Declarative Metadata Sample Definition

The following is an example AutoResponseRules component:

<AutoResponseRules xmlns= "http://soap.sforce.com/2006/04/metadata">

<autoResponseRule >

<fullName >ajbdeploytest2 </fullName >

<active >false </active >

<ruleEntry >

<criteriaItems >

<field >Case.Description

</field >

<operation >contains </operation >

<value >testing </value >

</criteriaItems >

<senderEmail >[email protected]

</senderEmail >

<senderName >tester name j </senderName >

<replyToEmail >test@@test.org

</replyToEmail >

<template >emailtemplate </template >

</ruleEntry >

</autoResponseRule >

</AutoResponseRules >

169

Metadata Types

CallCenter

Represents the Call Center definition used to integrate Salesforce with a third-party computer-telephony integration (CTI) system.

File Suffix and Directory Location

CallCenter components have the suffix callCenter

and are stored in the callCenters

folder.

Version

CallCenter components are available in API version 27.0 and later.

Fields

Field Name

adapterUrl displayName displayNameLabel internalNameLabel version sections

Field Type

string string string

Description

Optional field. A URL that points to a CTI 4 adapter.

The display name of this call center.

The label of the displayName

field in Call Center setup page.

string string

The label of the internalName

field in Call Center setup page.

The version of this call center.

CallCenterSection[]

Custom setup items defined for this call center.

CallCenter

CallCenterSection

Field Name

items label name

CallCenterItem

Field Name

label name value

Field Type

CallCenterItem[] on page 170

string string

Field Type

string string int or URL

Description

Contains the label, name, and value that describe the sections.

The label of the section.

The name of the section.

Description

The label of the custom setup item.

The name of the custom setup item.

The value of the custom setup item.

170

Metadata Types

Declarative Metadata Sample Definition

The following is an example of a CallCenter component:

<?xml

version= "1.0" encoding= "UTF-8"?>

<CallCenter xmlns= "http://soap.sforce.com/2006/04/metadata">

<adapterUrl >http://localhost:11000 </adapterUrl >

<displayName >Demo Call Center Adapter </displayName >

<displayNameLabel >Display Name </displayNameLabel >

<internalNameLabel >Internal Name </internalNameLabel >

<sections >

<items >

<label >Description </label >

<name >reqDescription </name >

<value >Demo Call Center Adapter </value >

</items >

<items >

<label >CTI Connector ProgId </label >

<name >reqProgId </name >

<value >DemoAdapter.DemoAdapter.1

</value >

</items >

<items >

<label >Version </label >

<name >reqVersion </name >

<value >3.0

</value >

</items >

<items >

<label >CTI Adapter URL </label >

<name >reqAdapterUrl </name >

<value >http://localhost:11000 </value >

</items >

<label >General Information </label >

<name >reqGeneralInfo </name >

</sections >

<sections >

<items >

<label >Outside Prefix </label >

<name >reqOutsidePrefix </name >

<value >1 </value >

</items >

<items >

<label >Long Distance Prefix </label >

<name >reqLongDistPrefix </name >

<value >1 </value >

</items >

<items >

<label >International Prefix </label >

<name >reqInternationalPrefix </name >

<value >01 </value >

</items >

<label >Dialing Options </label >

<name >reqDialingOptions </name >

</sections >

<version >4 </version >

</CallCenter >

171

CallCenter

Metadata Types CampaignInfluenceModel

CampaignInfluenceModel

Represents a campaign influence model used by Customizable Campaign Influence.

You can’t configure Customizable Campaign Influence via the Metadata API, but you can add a campaign influence model.

Note: This information applies only to Customizable Campaign Influence and not to the original version of Campaign Influence.

File Suffix and Directory Location

CampaignInfluenceModel values are stored in the campaignInfluenceModels

directory of the corresponding package directory.

The file name matches the model name, and the extension is

.campaignInfluenceModel

.

Version

CampaignInfluenceModel components are available in API version 38.0 and later.

Fields

Field Name

isDefaultModel

Field Type

boolean isModelLocked modelDescription name boolean string string

Description

Indicates if the model is the primary model or not. Only campaign influence records associated with the primary model appear on

Campaigns and Opportunities.

Indicates if the model is locked or not. Campaign Influence records for locked models can be manipulated only via the API.

A description of the influence model.

A unique name for the model.

Declarative Metadata Sample Definition

The following is an example of a CampaignInfluenceModel component that represents the default Salesforce campaign influence attribution model. The default isDefaultModel

value of true

can be changed if another model is created and set as the primary model. The isModelLocked

value of true

means that Campaign Influence records for this model can be seen in the UI, but not created, updated, or deleted.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CampaignInfluenceModel xmlns= "http://soap.sforce.com/2006/04/metadata">

<isDefaultModel >true </isDefaultModel >

<isModelLocked >true </isModelLocked >

<modelDescription >Primary Campaign gets 100% of the revenue share </modelDescription >

<name >Salesforce Model </name >

</CampaignInfluenceModel >

172

Metadata Types Certificate

The following is an example of a CampaignInfluenceModel component that creates an influence model called Last Touch, which will not be the primary model.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CampaignInfluenceModel xmlns= "http://soap.sforce.com/2006/04/metadata">

<isDefaultModel >false </isDefaultModel >

<isModelLocked >true </isModelLocked >

<modelDescription >This model gives 100% influence attribution to the last campaign that touched the contact.

</modelDescription >

<name >Last Touch </name >

</CampaignInfluenceModel >

Certificate

Represents a certificate used for digital signatures which verify that requests are coming from your org. Certificates are used for either authenticated single sign-on with an external website, or when using your org as an identity provider. This type extends the

MetadataWithContent metadata type and inherits its

content

and fullName

fields.

File Suffix and Directory Location

Certificate components have the suffix

.crt

and are stored in the certs

folder.

Version

Certificate components are available in API version 36.0 and later.

Fields

Field Name

caSigned

Field Type

boolean encryptedWithPlatformEncryption boolean expirationDate dateTime keySize int

Description

Required. Indicates whether this certificate is signed by the issuer (true) or not (false).

Indicates whether this certificate is encrypted with Platform Encryption.

The date that this certificate expires and is no longer usable. For self-signed certificates, if keySize

is 2048 bits, the expiration date is automatically 1 year after you create the certificate. If keySize

is 4096 bits, the expiration date is automatically 2 years after you create the certificate. For CA-signed certificates, expirationDate

is automatically updated to the signed certificate’s expiration date when a signed certificate chain is uploaded. The date format is YYYY-MM-DD.

Certificate keys can be either 2048 bits or 4096 bits. A certificate with

4096-bit keys lasts 2 years, and a certificate with 2048-bit keys lasts 1 year. Certificates with 2048-bit keys are faster than certificates with

4096-bit keys. If keySize

isn’t specified when you create a certificate, the key size defaults to 2048 bits.

173

Metadata Types CleanDataService

Field Name

masterLabel privateKeyExportable

Field Type

string boolean

Description

Required. A user-friendly name for the certificate that appears in the

Salesforce user interface, such as in Certificate and Key Management.

Limit: 64 characters.

Indicates whether this certificate’s private key is exportable. If privateKeyExportable

isn’t specified when you create a certificate, its default value is true

.

Usage

The Metadata API can be used to create a self-signed or a CA-signed certificate. The .crt file’s contents are the certificate chain, which can be updated when you renew or update the intermediate certificate chain of a CA-signed certificate. After creating a CA-signed certificate, the .crt file contains a certificate signing request (CSR). For details, see About Salesforce Certificates and Keys in the Salesforce

Help.

To copy an existing certificate’s X.509 parameter data to a new certificate, upload the existing certificate. You can also use this procedure to renew a certificate. A new private+public key pair is created with a new certificate. Salesforce doesn’t allow the import or export of the private key via the API. For details, see Repeating an Upload of a CA-Signed Certificate in Salesforce Help.

Using the Metadata API, you can download a CSR. After it’s CA-signed, you can upload it back to Salesforce.

•

Downloading a CSR. The CSR is downloadable after a CA-signed cert is created. If a signed certificate hasn’t been uploaded to that certificate, the content of the downloaded .crt file is the CSR.

•

Uploading a CA-Signed Certificate. To upload the signed certificate chain back to Salesforce, save the signed certificate chain as the content of the .crt file and update it via the Metadata API.

Note: After the signed certificate chain is uploaded via the Metadata API, the CSR of that certificate can’t be downloaded via the

API anymore. This is because the content of the .crt file is the signed certificate chain. However, the CSR can still be downloaded via the UI.

Declarative Metadata Sample Definition

The following is an example of a Certificate component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Certificate xmlns= "http://soap.sforce.com/2006/04/metadata">

<caSigned >true </caSigned >

<encryptedWithPlatformEncryption >true </encryptedWithPlatformEncryption >

<expirationDate >2017-03-19 </expirationDate >

<keySize >4096 </keySize >

<masterLabel >My Certificate Name </masterLabel >

<privateKeyExportable >true </privateKeyExportable >

</Certificate >

CleanDataService

Represents a data service that adds and updates data in standard objects. This type extends the

Metadata metadata type and inherits

its fullName

field.

174

Metadata Types CleanDataService

File Suffix and Directory Location

CleanDataService components have the

.cleanDataService

suffix and are stored in the cleanDataServices

directory.

The name of the component file is based on the name of the object associated with the data service. For example, the component file name cleanDataServices/DataCloudCompanyMatch.cleanDataService

describes a data service component called DataCloudCompanyMatch that's associated with the company name in account objects.

Version

CleanDataService components are available in API version 39.0 and later.

Fields

Field Name

cleanRules description masterLabel matchEngine

Field Type

CleanRule

[] string string string

Description

Required. A list of data integration rules

Required. A description of the data service

Required. Master label for this data service. Although this value is displayed, it’s an internal label for the data service and isn’t translated.

Required. A key that maps to the internal data service identifier.

CleanRule

Represents information that controls how the data service adds and updates data in an org.

Field Name

bulkEnabled bypassTriggers bypassWorkflow description developerName fieldMappings masterLabel

Field Type

boolean boolean boolean string string

FieldMapping []

string

Description

Required. If this field is set to true

, Salesforce applies the data integration rule to existing records whenever the rule is updated or saved.

Required. If this field is set to true

, Salesforce bypasses triggers when it applies the rule; otherwise, it applies triggers after it applies the rule.

Required. If this field is set to true

, Salesforce bypasses workflow rules when it applies the data integration rule; otherwise, it applies workflow rules after it applies the rule.

Required. User-friendly text that describes the data integration rule.

Required. This name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.

This unique name prevents conflicts with rules from other packages that have the same MasterLabel.

Required. A list of FieldMapping entries for the rule.

Required. Master label for this object. This display value is the internal label that is not translated.

175

Metadata Types CleanDataService

Field Name

matchRule

Field Type

string sourceSobjectType string status string targetSobjectType string

Description

Required. An internal label for a matching rule in the data service that’s associated with the CleanRule.

Required. A virtual object in the data service that is associated with the

CleanRule. Specifying a non-existent object causes an error.

Required. Status of the data integration rule. Valid values are

Active

and

Inactive

.

Required. A standard object that’s the target of additions and updates specified by this CleanRule. Specifying an object that the data service does not support causes an error.

FieldMapping

Represents a mapping between fields in the data service and fields in an object in the org.

Field Name

developerName fieldMappingRows masterLabel

SObjectType

Field Type

string

FieldMappingRow []

string string

Description

Required. This name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.

This unique name prevents conflicts with field mappings from other packages that have the same MasterLabel.

Required. A list of FieldMappingRow entries. Each entry represents a field in a standard object that maps to a field in the data service.

Required. Master label for this object. This display value is the internal label that is not translated.

Required. The standard object associated with this FieldMapping. Specifying an object that the data service does not support causes an error.

FieldMappingRow

Represents the status of a CleanRule.

Field Name

fieldName fieldMappingFields mappingOperation

Field Type

string

FieldMappingField []

string

Description

The display name for the field represented by the FieldMappingRow.

Required. A list of FieldMappingField entries. Each entry is a field in a standard object that maps to a field in the data service.

The comparison operation the data service applies when it compares the value of this FieldMappingRow to the mapped field in the object specified in

SObjectType. The value of this field is

AutoFill

, which indicates that the data service only adds data if the object field is blank.

176

Metadata Types CleanDataService

Field Name

SObjectType

Field Type

string

Description

The standard object for the field mapped to the FieldMappingRow. Specifying an object that the data service does not support causes an error.

FieldMappingField

Represents a field in a standard object. A FieldMappingField maps to a FieldMappingRow entry in a data service.

Field Name

dataServiceField

Field Type

string dataServiceObjectName string priority int

Description

Required. A field in the data service that is mapped to this field.

Required. An object in the data service that contains the FieldMappingRow associated with this FieldMappingField. Specifying a non-existent object causes an error.

Required. Represents the priority that the data service uses when it updates the field, relative to other update rules for the same field. Valid values are 1-100.

Declarative Metadata Sample Definition

The following is an example of a CleanDataService component for the lead standard object.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CleanDataService xmlns= "http://soap.sforce.com/2006/04/metadata">

<cleanRules >

<bulkEnabled >false </bulkEnabled >

<bypassTriggers >false </bypassTriggers >

<bypassWorkflow >false </bypassWorkflow >

<description >Adds data info to leads </description >

<developerName >DataService_Leads_Enrichment </developerName >

<fieldMappings >

<SObjectType >DataServiceCompanyObject </SObjectType >

<developerName >DataService_Leads_Enrichment_InputMapping </developerName >

<fieldMappingRows >

<SObjectType >DataServiceCompanyObject </SObjectType >

<fieldMappingFields >

<dataServiceField >Email </dataServiceField >

<dataServiceObjectName >Lead </dataServiceObjectName >

<priority >1 </priority >

</fieldMappingFields >

<fieldName >Email </fieldName >

<mappingOperation >Autofill </mappingOperation >

</fieldMappingRows >

<fieldMappingRows >

<SObjectType >DataServiceCompanyObject </SObjectType >

<fieldMappingFields >

<dataServiceField >Company </dataServiceField >

<dataServiceObjectName >Lead </dataServiceObjectName >

<priority >1 </priority >

</fieldMappingFields >

177

Metadata Types CleanDataService

<fieldName >Name </fieldName >

<mappingOperation >Autofill </mappingOperation >

</fieldMappingRows >

<masterLabel >DataServiceInputMapping </masterLabel >

</fieldMappings >

<fieldMappings >

<SObjectType >Lead </SObjectType >

<developerName >DataService_Leads_Enrichment_OutputMapping </developerName >

<fieldMappingRows >

<SObjectType >Lead </SObjectType >

<fieldMappingFields >

<dataServiceField >EmployeesTotal </dataServiceField >

<dataServiceObjectName >DataServiceCompanyObject </dataServiceObjectName >

<priority >1 </priority >

</fieldMappingFields >

<fieldName >NumberOfEmployees </fieldName >

<mappingOperation >Autofill </mappingOperation >

</fieldMappingRows >

<fieldMappingRows >

<SObjectType >Lead </SObjectType >

<fieldMappingFields >

<dataServiceField >Revenue </dataServiceField >

<dataServiceObjectName >DataServiceCompanyObject </dataServiceObjectName >

<priority >1 </priority >

</fieldMappingFields >

<fieldName >AnnualRevenue </fieldName >

<mappingOperation >Autofill </mappingOperation >

</fieldMappingRows >

<fieldMappingRows >

<SObjectType >Lead </SObjectType >

<fieldMappingFields >

<dataServiceField >Industry </dataServiceField >

<dataServiceObjectName >DataServiceCompanyObject </dataServiceObjectName >

<priority >1 </priority >

</fieldMappingFields >

<fieldName >Industry </fieldName >

<mappingOperation >Autofill </mappingOperation >

</fieldMappingRows >

<masterLabel >DataServiceOutputMapping </masterLabel >

</fieldMappings >

<masterLabel >Data Service Company Info for Leads </masterLabel >

<matchRule >DataServiceLeadAppendMatchRule </matchRule >

<sourceSobjectType >DataServiceCompanyObject </sourceSobjectType >

<status >Active </status >

<targetSobjectType >Lead </targetSobjectType >

</cleanRules >

<description >Data Service Companies for Leads </description >

<masterLabel >Data Service Companies for Leads </masterLabel >

<matchEngine >LeadEnrichmentMatchEngine </matchEngine >

</CleanDataService >

178

Metadata Types Community (Zone)

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >DataService_Leads_Enrichment </members >

<name >CleanDataService </name >

</types >

<version >38.0

</version >

</Package >

Usage

Use CleanDataService to retrieve all the metadata that describes a data enrichment service. To configure the service in a new org, deploy the metadata you retrieved. Avoid using CRUD-Based Calls with CleanDataService.

To make small modifications to the CleanDataService component, use the Tooling API.

Community (Zone)

Note: Starting with the Summer ’13 release, Chatter Answers and Ideas “communities” have been renamed to “zones.” In API version 28, the API object label has changed to

Zone

, but the API type is still

Community

.

Represents a zone that contains Ideas or Chatter Answers objects. Zones are shared by the Ideas, Answers, and Chatter Answers features, allowing you to view and create zones from those locations. This type extends the

Metadata metadata type and inherits its

fullName field.

Note:

When enableChatterAnswers

is set to false

, values specified for the following fields are ignored and not saved: communityFeedPage

, emailFooterDocument

, emailHeaderDocument

, enablePrivateQuestions

, emailNotificationUrl

, and site

.

File Suffix and Directory Location

Zones have the suffix community

and are stored in the communities

folder.

Version

Community (Zone) components are available in API version 27.0 and later.

Fields

Field Name

active

Field Type

boolean chatterAnswersFacebookSsoUrl string

Description

Indicates whether the zone is active ( true

) or not ( false

).

(Read only) The Facebook sign-on URL, which is based on the Facebook authentication provider selected in your Chatter Answers settings. This field is available only if Chatter Answers and Facebook Single Sign-On for Chatter Answers are enabled.

179

Metadata Types Community (Zone)

Field Name

communityFeedPage description emailFooterDocument emailHeaderDocument emailNotificationUrl enableChatterAnswers enablePrivateQuestions expertsGroup portal portalEmailNotificationUrl reputationLevels showInPortal site

Field Type

string string string string string boolean boolean string string string

ReputationLevels

boolean string

Description

The Visualforce page that hosts the zone’s feeds. This field is available when Chatter Answers is enabled in the organization.

The description of the zone.

The text or HTML file that incorporates your organization’s branding into the footer of email notifications. This field is available when Chatter

Answers is enabled in the organization.

The text or HTML file that incorporates your organization’s branding into the header of email notifications. This field is available when Chatter

Answers is enabled in the organization.

The URL that’s included in email notifications. This field is available when

Chatter Answers is enabled in the organization. This field replaces portalEmailNotificationUrl

in API version 28.0 and later.

Indicates whether the zone has Chatter Answers enabled ( true

) or not

( false

). This field is available when Chatter Answers is enabled in the organization.

Indicates whether Chatter Answers questions can be escalated to cases

( true

) or not ( false

). This field is available when Chatter Answers is enabled in the organization.

The name of the public group that act as experts in the zone. This field is available when eitherIdeas or Answers are enabled in the organization.

The name of the portal in which to display the zone.

The portal URL that’s included in email notifications. This field is available when Chatter Answers is enabled in the organization. This field has been replaced by emailNotificationUrl

in API version 28.0 and later.

The fields that define the points and name of each reputation level you define. You can create up to 25 reputation levels per zone.

Indicates whether the zone is available to all portals ( true

) or not available to any portals ( false

).

The name of the site for the zone. This field is available when Chatter

Answers is enabled in the organization.

ReputationLevels

Represents the points and reputation label that displays on hover over a user’s photo in the feed.

Field Name Field Type Description

chatterAnswersReputationLevels

ChatterAnswersReputationLevel

[]

Contains the name and value pair that describes the reputation level for Chatter Answers. Available in API version

28.0 and later.

180

Metadata Types Community (Zone)

Field Name

ideaReputationLevels

Field Type

IdeaReputationLevel

Description

Contains the name and value pair that describes the reputation for Ideas. Available in API version 28.0 and later.

ChatterAnswersReputationLevel

Represents the reputation name and the number of points for that level for Chatter Answers.

Field Name

name value

Field Type

string int

Description

The name of the reputation level, for example, “Expert.”

The minimum number of points for the reputation level.

IdeaReputationLevel

Represents the reputation name and the number of points for that level for Ideas. Available in API version 28.0 and later.

Field Name

name value

Field Type

string int

Description

The name of the reputation level, for example, “Expert.”

The minimum number of points for the reputation level.

Declarative Metadata Sample Definition

The following is the definition of a community (zone) component:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Community xmlns= "http://soap.sforce.com/2006/04/metadata">

<active >true </active >

<communityFeedPage >communityWithHeaderAndFooter_main </communityFeedPage >

<description >Metadata Test </description >

<emailFooterDocument >sampleFolder/emailFooter.html

</emailFooterDocument >

<emailHeaderDocument >sampleFolder/emailHeader.html

</emailHeaderDocument >

<enableChatterAnswers >true </enableChatterAnswers >

<enablePrivateQuestions >true </enablePrivateQuestions >

<expertsGroup >CommunityExperts </expertsGroup >

<portal >Customer Portal </portal >

<emailNotificationUrl >http://yourURL </emailNotificationUrl >

<reputationLevels >

<chatterAnswersReputationLevels >

<name >Newbie </name >

<value >0 </value >

</chatterAnswersReputationLevels >

<chatterAnswersReputationLevels >

<name >Smartie </name >

<value >500 </value >

</chatterAnswersReputationLevels >

<chatterAnswersReputationLevels >

181

Metadata Types CommunityTemplateDefinition

<name >Pro </name >

<value >2000 </value >

</chatterAnswersReputationLevels >

<chatterAnswersReputationLevels >

<name >All Star </name >

<value >5000 </value >

</chatterAnswersReputationLevels >

<ideaReputationLevels >

<name >Observer </name >

<value >0 </value >

</ideaReputationLevels >

<ideaReputationLevels >

<name >Contributor </name >

<value >100 </value >

</ideaReputationLevels >

<ideaReputationLevels >

<name >Influencer </name >

<value >400 </value >

</ideaReputationLevels >

<ideaReputationLevels >

<name >Thought Leader </name >

<value >1500 </value >

</ideaReputationLevels >

</reputationLevels >

<showInPortal >true </showInPortal >

<site >ChatterAnswersSite </site >

</Community >

CommunityTemplateDefinition

Represents the definition of a community template. This type extends the Metadata

metadata type and inherits its fullName

field.

File Suffix and Directory Location

CommunityTemplateDefinition components have the suffix

.communityTemplateDefinition

and are stored in the communityTemplateDefinitions

folder.

Version

CommunityTemplateDefinition 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.

182

Metadata Types CommunityTemplateDefinition

Fields

Field Name

bundlesInfo category

Field Type Description

CommunityTemplate

BundleInfo

[ ]

Required. The list of preview images and feature descriptions of this

CommunityTemplateDefinition.

CommunityTemplate

Category

(

enumeration of

type string)

Required. The optimized use case of this CommunityTemplateDefinition.

Valid values are:

•

IT

•

Marketing

•

Sales

•

Service defaultThemeDefinition description string string

Required. The assigned theme definition for this

CommunityTemplateDefinition.

The optional description text of this CommunityTemplateDefinition.

enableExtendedCleanupUpOnDelete masterLabel pageSetting boolean string

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.

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

CommunityTemplate

PageSetting [ ]

Required. The list of FlexiPages of this CommunityTemplateDefinition.

CommunityTemplateBundleInfo

Field Name

description image order title

Field Type

string string int string

Description

The optional description text of its CommunityTemplateBundleInfo.

Required only when the type

is

PreviewImage

, otherwise this field is optional. A preview image for this CommunityTemplateDefinition.

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.

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

183

Metadata Types

Field Name

type

CommunityTemplateDefinition

Field Type Description

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

page themeLayout

Field Type

string string

Description

Required. The list of FlexiPages of this CommunityTemplateDefinition.

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CommunityTemplateDefinition xmlns= "http://soap.sforce.com/2006/04/metadata">

<bundlesInfo >

<description >ax </description >

<order >1 </order >

<title >ax </title >

<type >Highlight </type >

</bundlesInfo >

<bundlesInfo >

<image >siteAsset_6b1cf63e4d604d16bb98b84636ab1932 </image >

<order >1 </order >

<title >siteAsset_6b1cf63e4d604d16bb98b84636ab1932 </title >

<type >PreviewImage </type >

</bundlesInfo >

<category >Sales </category >

<defaultThemeDefinition >ax </defaultThemeDefinition >

<description >ax </description >

<enableExtendedCleanUpOnDelete >true </enableExtendedCleanUpOnDelete >

<masterLabel >ax </masterLabel >

<pageSetting >

<page >ax_Record_List </page >

</pageSetting >

<pageSetting >

<page >ax_Topic_Catalog </page >

</pageSetting >

<pageSetting >

184

Metadata Types

<page >ax_User_Settings </page >

</pageSetting >

<pageSetting >

<page >ax_Error </page >

</pageSetting >

<pageSetting >

<page >ax_Group_Detail </page >

</pageSetting >

<pageSetting >

<page >ax_Sfdc_Page </page >

</pageSetting >

<pageSetting >

<page >ax_Related_Record_List </page >

</pageSetting >

<pageSetting >

<page >ax_User_Profile </page >

</pageSetting >

<pageSetting >

<page >ax_Record_Detail </page >

</pageSetting >

<pageSetting >

<page >ax_Group_List </page >

</pageSetting >

<pageSetting >

<page >ax_Search </page >

</pageSetting >

<pageSetting >

<page >ax_Create_Record </page >

</pageSetting >

<pageSetting >

<page >ax_Question_Detail </page >

</pageSetting >

<pageSetting >

<page >ax_Home </page >

</pageSetting >

<pageSetting >

<page >ax_Topic_Detail </page >

</pageSetting >

<pageSetting >

<page >ax_Report </page >

</pageSetting >

<pageSetting >

<page >ax_Feed_Detail </page >

</pageSetting >

<pageSetting >

<page >ax_Contact_Support </page >

</pageSetting >

</CommunityTemplateDefinition >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >MyTemplate </members >

185

CommunityTemplateDefinition

Metadata Types CommunityThemeDefinition

<name >CommunityTemplateDefinition </name >

</types >

<version >39.0

</version >

</Package >

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

customThemeLayoutType description enableExtendedCleanupUp

OnDelete masterLabel themeSetting

Field Type

string

Description

CommunityCustom

ThemeLayoutType

[ ]

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

The optional description text of this CommunityThemeDefinition.

boolean string

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

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

CommunityTheme

Setting [ ]

Required. The list of settings for this CommunityThemeDefinition.

CommunityCustomThemeLayoutType

Field Name

description

Field Type

string

Description

The description of the custom theme layout type.

186

Metadata Types ConnectedApp

Field Name

label

Field Type

string

Description

Required. The name of the custom theme layout type. The values

Inner

,

Home

, and

Login

are reserved.

CommunityThemeSetting

Field Name

customThemeLayoutType themeLayout themeLayoutType

Field Type

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.

Required. The configuration and layout for this theme.

string

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.

<CommunityThemeDefinition xmlns= "http://soap.sforce.com/2006/04/metadata">

<enableExtendedCleanUpOnDelete >true </enableExtendedCleanUpOnDelete >

<masterLabel >ax_theme </masterLabel >

<themeSetting >

<themeLayout >ax_theme_napili_themeLayout_home </themeLayout >

<themeLayoutType >Inner </themeLayoutType >

</themeSetting >

</CommunityThemeDefinition >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >MyTheme </members >

<name >CommunityThemeDefinition </name >

</types >

<version >39.0

</version >

</Package >

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

attributes canvasConfig contactEmail contactPhone description iconUrl infoUrl ipRanges label logoUrl mobileStartUrl oauthConfig

Field Type

ConnectedAppAttribute

ConnectedAppCanvasConfig

string string string string string

ConnectedAppIpRange

string string string

ConnectedAppOauthConfig

Description

A custom attribute of the connected app.

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

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

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

An optional description for your application.

Reserved for future use.

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

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

The name of the app.

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.

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.

Specifies how your application communicates with Salesforce.

188

Metadata Types ConnectedApp

Field Name

plugin samlConfig startUrl

Field Type

string

ConnectedAppSamlConfig

string

Description

The name of a custom Apex class that extends

Auth.ConnectedAppPlugin

to customize the behavior of the app.

Controls how the app uses single sign-on.

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

formula key

Field Type

string string

Description

The value of the attribute.

The attribute’s identifier.

ConnectedAppCanvasConfig

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

Field Name

accessMethod canvasUrl

Field Type

AccessMethod (

enumeration

of type string)

Description

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.

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

189

Metadata Types ConnectedApp

Field Name

lifecycleClass locations options

(

Field Type

string

CanvasLocationOptions

enumeration

of type string)

Description

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.

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.

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 ConnectedApp

Field Name 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

description startAddress endAddress

Field Type

string string string

Description

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.

The first address in the IP range, inclusive.

The last address in the IP range, inclusive.

ConnectedAppOauthConfig

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

Field Name

callbackUrl certificate consumerKey consumerSecret

Field Type

string string string string

Description

The endpoint that Salesforce calls back to your application during

OAuth; it’s the OAuth redirect_uri

.

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

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.

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

scopes

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.

ConnectedAppOauthAccessScope

(enumeration of type string)

The scopes refer to permissions given by the user running the 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 Field Type

ConnectedApp

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

acsUrl certificate entityUrl

Field Type

string string string encryptionCertificate string encryptionType

SamlEncryptionType

(enumeration of type string)

Description

The assertion consumer service URL from the service provider.

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

The entity ID from your service provider.

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 .

Note: This page is about Classic Encryption, not Shield Platform

Encryption. What's the difference?

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 ConnectedApp

Field Name

issuer samlNameIdFormat

Field Type

string

SamlNameIdFormatType

(enumeration of type string)

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.

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 samlSubjectType string If the samlSubjectType

is

CustomAttr

, include that custom value here; otherwise, leave empty. Available in API version 29.0 and later.

SamlSubjectType (enumeration of type string)

The single sign-on identifier for the user. Valid values are:

•

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >PortalTestApp </members >

<name >ConnectedApp </name >

</types >

194

Metadata Types ConnectedApp

<version >29.0

</version >

</Package >

The following is an example of a ConnectedApp component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<ConnectedApp xmlns= "http://soap.sforce.com/2006/04/metadata">

<fullName >AConnectedApp </fullName >

<attributes >

<formula >$User.CompanyName

</formula >

<key >companyName </key >

</attributes >

<contactEmail >[email protected]

</contactEmail >

<mobileStartUrl >https://m.connectedapp.company.com

</mobileStartUrl >

<label >A ConnectedApp </label >

<oauthConfig >

<callbackUrl >https://callback.company.com

</callbackUrl >

<scopes >Basic </scopes >

<scopes >Chatter </scopes >

</oauthConfig >

<samlConfig >

<acsUrl >http://acs.company.com

</acsUrl >

<entityUrl >http://samlentityId.company.com

</entityUrl >

<samlSubjectType >Username </samlSubjectType >

</samlConfig >

<startUrl >https://connectedapp.company.com

</startUrl >

<ipRanges >

<endAddress >10.0.0.46

</endAddress >

<startAddress >10.0.0.42

</startAddress >

</ipRanges >

<ipRanges >

<endAddress >10.0.0.32

</endAddress >

<startAddress >10.0.0.25

</startAddress >

</ipRanges >

</ConnectedApp >

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://

<Salesforce_base_URL>

/idp/login?app=

<app_id>

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://

<Salesforce_base_URL>

/idp/login?apiName=

<fullName>

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

format language masterLabel originNetwork relationships versions

Field Type Description

ContentAssetFormat

(

enumeration of

type string)

Describes the format of the asset file. Valid values are:

•

Original

—A single asset file version.

•

ZippedVersions

—Contains multiple versions of the asset file.

string string

Required. The language of the asset file label.

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

string

ContentAsset

Relationships[]

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.

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

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

organization

Field Type

ContentAssetLink[]

Description

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

access name

Field Type Description

ContentAssetAccess

( enumeration of type

string)

Required. The permission granted to the user of the shared file, determined by the permission the user already has. Valid values are:

•

VIEWER

•

COLLABORATOR

•

INFERRED string Reserved for future use.

ContentAssetVersions

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

Field Name

version

Field Type Description

ContentAssetVersion[]

A list of file versions for the asset.

ContentAssetVersion

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

Field Name

number pathOnClient zipEntry

Field Type

string string string

Description

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

Required. Describes the original filename of the file. This field maps to

ContentVersion.PathOnClient. It provides the data for the ContentVersion Title field.

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<ContentAsset xmlns= "http://soap.sforce.com/2006/04/metadata">

<masterLabel >some asset </masterLabel >

<relationships >

<organization >

<access >VIEWER </access >

</organization >

</relationships >

<versions >

<version >

<number >1 </number >

<pathOnClient >some asset.txt

</pathOnClient >

</version >

</versions >

</ContentAsset >

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >MyAsset </members >

<name >ContentAsset </name >

</types >

<version >39.0

</version >

</Package >

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

Fields

Field Name

developerName urlPattern

Field Type

String

String

CorsWhitelistOrigin

Description

A unique name for the entry.

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >CorsWhitelistOrigin </name >

</types >

<version >32.0

</version >

</Package >

The following is an example of a CorsWhitelistOrigin component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CorsWhitelistOrigin xmlns= "http://soap.sforce.com/2006/04/metadata">

<developerName >CorsWhitelistEntry1 </developerName >

<urlPattern >https://*.example.com

</urlPattern >

</CorsWhitelistOrigin >

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

description endpointUrl isActive

Field Type

string string boolean

Description

The description explaining what this trusted site is used for.

Required. The URL for the trusted site.

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CspTrustedSite xmlns= "http://soap.sforce.com/2006/04/metadata">

<description >Used for Lightning component callout to mapping web service </description >

<endpointUrl >https://www.maptestsite.net/ </endpointUrl >

<isActive >true </isActive >

</CspTrustedSite >

Usage

CSP is a Candidate Recommendation of the W3C working group on Web Application Security. The framework uses the

Content-

Security-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

actionOverrides brand

Field Type

AppActionOverride[]

customApplicationComponents

CustomApplicationComponents

defaultLandingTab description

AppBrand

string string

Description

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.

The color scheme and logo used for the app.

This field is available for Lightning Experience in API version 38.0 and later.

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

The

fullName

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

The optional description text of the application.

201

Metadata Types

Field Name Field Type

detailPageRefreshMethod string domainWhitelist

DomainWhitelist

enableCustomizeMyTabs boolean enableKeyboardShortcuts boolean enableListViewHover enableListViewReskin enableMultiMonitorComponents boolean boolean boolean

202

CustomApplication

Description

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.

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.

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.

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.

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.

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.

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

Metadata Types

Field Name Field Type

enablePinTabs enableTabHover boolean boolean enableTabLimits boolean footerColor formFactors string string

CustomApplication

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.

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.

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.

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.

Determines the footer color in a Salesforce console app.

Specify the color with a hexadecimal code, such as

#0000FF for blue.

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

Field Name

headerColor keyboardShortcuts label listPlacement listRefreshMethod liveAgentConfig logo navType

Field Type

string isServiceCloudConsole boolean

KeyboardShortcuts

string

ListPlacement

string

LiveAgentConfig

string string primaryTabColor string profileActionOverrides

AppProfileActionOverride []

CustomApplication

Description

Determines the header color in a Salesforce console app.

Specify the color with a hexadecimal code, such as

#0000FF for blue.

Indicates if the application is a Salesforce console app.

For more information, see “Salesforce Console” in the

Salesforce online help.

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.

The name of the application.

Represents how lists display in a Salesforce console app.

Required if isServiceCloudConsole

is true

.

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.

Represents the configurations for using Live Agent in the

Salesforce Console.

The optional reference to the image document for a

Salesforce app or Salesforce console.

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.

Determines the primary tab color in a Salesforce console app. Specify the color with a hexadecimal code, such as

#0000FF for blue.

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

Field Name

pushNotifications

Field Type

PushNotifications

saveUserSessions tab tabLimitConfig uiType utilityBar boolean string

TabLimitConfig

string string

CustomApplication

Description

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.

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.

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

.

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.

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.

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

workspaceMappings

Field Type

WorkspaceMappings

Description

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

actionName comment content formFactor pageOrSobjectType skipRecordTypeSelect type

Field Type

string string string

Description

The only valid value is view

.

Any comments you want associated with the override.

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

(

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.

string boolean

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

and custom

.

Set this field to true

if you prefer that any new records created by this action override aren’t forwarded to the record type selection page. This field is only valid if the actionName

is a “create” type (like new

), and type

is set to visualforce

.

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

footerColor headerColor logo logoVersion

Field Type

string string string int

Description

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

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

The optional reference to the image document for the application.

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

actionName content formFactor pageOrSobjectType profile recordType type

Field Type

string

Description

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.

string

FormFactor

(

enumeration of type

string)

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

The size of the page being overridden. Only the

Large

value is supported. The other values,

Small

and

Medium

, are reserved for future use. The

Large

value represents the Lightning Experience desktop environment.

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

and standard-home

.

The profile associated with the ProfileActionOverride.

string string

ActionOverrideType

(

enumeration of type

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

.

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

alignment

Field Type

string customApplicationComponent string

Description

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

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

action active keyCommand

Field Type

string boolean string

Description

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

Required. Indicates whether the keyboard shortcut is active ( true

) or not ( false

).

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 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

•

F4

•

F5

•

F6

•

F7

•

F8

•

F9

•

SUBTRACT

•

DECIMAL POINT

•

DIVIDE

•

F1

•

F2

•

F3

•

F10

•

F11

•

F12

•

NUM LOCK

209

CustomApplication

Metadata Types CustomApplication

Field Name

description eventName

Field Type

string string

Description

•

SCROLL LOCK

•

;

•

=

•

,

•

—

•

.

•

/

•

‘

•

[

•

]

•

\

•

'

The optional description text for the keyboard shortcut.

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

action

Field Type

string

Description

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

active keyCommand

Field Type

boolean string

CustomApplication

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.

Required. Indicates whether the keyboard shortcut is active ( true

) or not ( false

).

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

•

END

•

HOME

•

LEFT ARROW

•

UP ARROW

•

RIGHT ARROW

211

Metadata Types

Field Name 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

CustomApplication

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

domain

Field Type

string

Description

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

customShortcut defaultShortcut

Field Type

KeyboardShortcuts[]

KeyboardShortcuts[]

Description

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.

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

height location units width

Field Type

int string string int

Description

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

is top.

Required. Location of the list on the screen. Valid values are:

•

full

•

top

•

left

Required. Represents if height

or width

is in pixels or percentage.

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

enableLiveChat openNewAccountSubtab openNewCaseSubtab openNewContactSubtab openNewLeadSubtab openNewVFPageSubtab pagesToOpen showKnowledgeArticles

Field Type

boolean boolean boolean

Description

Specifies whether Live Agent is enabled in your organization ( true

) or not ( false

).

Specifies whether to open a new Account subtab in the Salesforce

Console automatically ( true

) or not ( false

) when an agent accepts a chat.

Specifies whether to open a new Case subtab in the Salesforce Console automatically ( true

) or not ( false

) when an agent accepts a chat.

boolean boolean

Specifies whether to open a new Contact subtab in the Salesforce Console automatically ( true

) or not ( false

) when an agent accepts a chat.

Specifies whether to open a new Lead subtab in the Salesforce Console automatically ( true

) or not ( false

) when an agent accepts a chat.

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

on page

214

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

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

pagesToOpen

Field Type

string

Description

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

pushNotification

Field Type

PushNotification[]

Description

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

fieldNames objectName

Field Type

string string

Description

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

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 maxNumberOfSubTabs string

Description

The maximum number of primary tabs allowed in one console session.

Valid values are:

•

5

•

10

•

20

•

30

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

mapping

Field Type

WorkspaceMapping

Description

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

fieldName tab

Field Type

string string

Description

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.

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.

<types >

<members >* </members >

<name >CustomApplication </name >

</types >

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.

<types >

<members >MyCustomApp </members >

<name >CustomApplication </name >

</types >

To retrieve a standard app, add the standard__

prefix to the app name. For example, to retrieve the Chatter standard app, specify standard__Chatter

.

<types >

<members >standard__Chatter </members >

<name >CustomApplication </name >

</types >

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.

<types >

<members >myInstalledPackageNS__PackageApp </members >

<name >CustomApplication </name >

</types >

Declarative Metadata Sample Definition

The following is the definition of a custom app:

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomApplication xmlns= "http://soap.sforce.com/2006/04/metadata">

<defaultLandingTab >Myriad_Publishing__c </defaultLandingTab >

<description >App to manage Myriad Publishing </description >

<label >Myriad </label >

<logo >MyriadFolder/Myriad_Logo.jpg

</logo >

<tab >standard-Chatter </tab >

<tab >standard-File </tab >

<tab >Myriad_Publishing__c </tab >

<tab >standard-report </tab >

<tab >standard-Dashboard </tab >

</CustomApplication >

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

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomApplication xmlns= "http://soap.sforce.com/2006/04/metadata">

<defaultLandingTab >standard-home </defaultLandingTab >

<label >Collaboration </label >

<tab >standard-Chatter </tab >

<tab >standard-UserProfile </tab >

<tab >standard-OtherUserProfile </tab >

<tab >standard-CollaborationGroup </tab >

<tab >standard-File </tab >

</CustomApplication >

Declarative Metadata Sample Definition—Salesforce Console

The following is the definition of a custom app where isServiceCloudConsole

is true

:

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomApplication xmlns= "http://soap.sforce.com/2006/04/metadata">

<customApplicationComponents >

<alignment >left </alignment >

<customApplicationComponent >MyComponent </customApplicationComponent >

</customApplicationComponents >

<defaultLandingTab >standard-home </defaultLandingTab >

<detailPageRefreshMethod >autoRefresh </detailPageRefreshMethod >

<isServiceCloudConsole >true </isServiceCloudConsole >

<keyboardShortcuts >

<customShortcut >

217

Metadata Types

<action >MyCustomShortcutAction </action >

<active >true </active >

<keyCommand >X </keyCommand >

<description >Custom Shortcut example </description >

<eventName >myCustomShortcutExample </eventName >

</customShortcut >

<defaultShortcut >

<action >FOCUS_CONSOLE </action >

<active >true </active >

<keyCommand >ESC </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >FOCUS_NAVIGATOR_TAB </action >

<active >true </active >

<keyCommand >V </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >FOCUS_DETAIL_VIEW </action >

<active >true </active >

<keyCommand >SHIFT+S </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >FOCUS_PRIMARY_TAB_PANEL </action >

<active >true </active >

<keyCommand >P </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >FOCUS_SUBTAB_PANEL </action >

<active >true </active >

<keyCommand >S </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >FOCUS_LIST_VIEW </action >

<active >true </active >

<keyCommand >N </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >FOCUS_FIRST_LIST_VIEW </action >

<active >true </active >

<keyCommand >SHIFT+F </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >FOCUS_SEARCH_INPUT </action >

<active >true </active >

<keyCommand >R </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >MOVE_LEFT </action >

<active >true </active >

<keyCommand >LEFT ARROW </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >MOVE_RIGHT </action >

<active >true </active >

218

CustomApplication

Metadata Types

<keyCommand >RIGHT ARROW </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >UP_ARROW </action >

<active >true </active >

<keyCommand >UP ARROW </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >DOWN_ARROW </action >

<active >true </active >

<keyCommand >DOWN ARROW </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >OPEN_TAB_SCROLLER_MENU </action >

<active >true </active >

<keyCommand >D </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >OPEN_TAB </action >

<active >true </active >

<keyCommand >T </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >CLOSE_TAB </action >

<active >true </active >

<keyCommand >C </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >ENTER </action >

<active >true </active >

<keyCommand >ENTER </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >EDIT </action >

<active >true </active >

<keyCommand >E </keyCommand >

</defaultShortcut >

<defaultShortcut >

<action >SAVE </action >

<active >true </active >

<keyCommand >CTRL+S </keyCommand >

</defaultShortcut >

</keyboardShortcuts >

<label >MyConsole </label >

<listPlacement >

<location >left </location >

<units >percent </units >

<width >20 </width >

</listPlacement >

<listRefreshMethod >refreshList </listRefreshMethod >

<pushNotifications >

<pushNotification >

<fieldNames >CreatedBy </fieldNames >

<objectName >Campaign </objectName >

219

CustomApplication

Metadata Types CustomApplicationComponent

</pushNotification >

<pushNotification >

<fieldNames >CustomField1__c </fieldNames >

<objectName >CustomObject1__c </objectName >

</pushNotification >

</pushNotifications >

<saveUserSessions >false </saveUserSessions >

<tab >standard-Case </tab >

<tab >standard-Account </tab >

<tab >standard-Contact </tab >

<tab >standard-Contract </tab >

<workspaceMappings >

<mapping >

<tab >standard-Case </tab >

</mapping >

<mapping >

<fieldName >AccountId </fieldName >

<tab >standard-Contract </tab >

</mapping >

<mapping >

<tab >standard-Contract </tab >

</mapping >

<mapping >

<fieldName >ParentId </fieldName >

<tab >standard-Account </tab >

</mapping >

</workspaceMappings >

</CustomApplication >

SEE ALSO:

CustomTab

CustomApplicationComponent

Represents a custom console component (Visualforce page) assigned to a CustomApplication that is marked as a Salesforce console.

Custom console components extend the capabilities of Salesforce console apps. See “Customize a Console with Custom Components in Salesforce Classic” in the Salesforce online help.

File Suffix and Directory Location

Custom application components have the suffix

.customApplicationComponent

and are stored in the customApplicationComponents

folder.

Version

Custom applications are available in API version 25.0 and later.

220

Metadata Types

Fields

Field Name

buttonIconUrl buttonStyle buttonText buttonWidth height isHeightFixed isHidden isWidthFixed visualforcePage width

CustomApplicationComponent boolean boolean boolean string int

Field Type

string string string int int

Description

The address of a page that hosts an icon for the button.

The inline style used to define how the button looks.

The label on the button used to launch the custom console component.

The pixel width of the button as it should display in the Salesforce console.

The pixel height of the window used to display the custom console component.

Required. Indicates whether users can change the custom console component height ( false

) or not ( true

).

Required. Indicates whether the custom console component is hidden from users ( true

) or not ( false

).

Required. Indicates whether users can change the component width

( false

) or not ( true

).

Required. Name of the Visualforce page that represents the custom console component.

The pixel width of the window used to display the custom console component.

Declarative Metadata Sample Definition

The following is the definition of a custom application component:

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomApplicationComponent xmlns= "http://soap.sforce.com/2006/04/metadata">

<buttonIconUrl >http://www.salesforce.com

</buttonIconUrl >

<buttonStyle >buttonStyleCSS </buttonStyle >

<buttonText >buttonText </buttonText >

<buttonWidth >200 </buttonWidth >

<height >200 </height >

<isHeightFixed >false </isHeightFixed >

<isHidden >false </isHidden >

<isWidthFixed >false </isWidthFixed >

<visualforcePage >MyVisualforcePage </visualforcePage >

<width >50 </width >

</CustomApplicationComponent >

221

Metadata Types CustomFeedFilter

CustomFeedFilter

Represents a custom feed filter that limits the feed view to feeds from the Cases object. The custom feed filter shows only feed items

that satisfy the criteria specified in the CustomFeedFilter definition.This type extends the Metadata

metadata type and inherits its fullName

field.

File Suffix and Directory Location

CustomFeedFilter components have the suffix

.feedFilter

and are stored in the feedFilters

folder.

Version

CustomFeedFilter components are available in API version 35.0 and later.

Fields

Field Name

description criteria label

Field Type

string

FeedFilterCriterion

[] string

Description

The description of the custom feed filter. For example, specify what feed items that filter shows.

The criterion that defines which feed items are shown when the filter is applied. The feed filter displays all feed items that satisfy the criteria.

Required. The API label of the custom feed filter.

FeedFilterCriterion

Represents the conditions that a feed item must satisfy to be displayed when a feed filter is applied.

Field Name

feedItemType

Field Type Description

FeedItemType ( enumeration

of type string)

Required. The type of feed items that the filter shows.

The feed item type can be one of the following values:

•

AttachArticleEvent

•

CallLogPost

•

CanvasPost

•

CaseCommentPost

•

ChangeStatusPost

•

ChatTranscriptPost

•

ContentPost

•

CreateRecordEvent

•

EmailMessageEvent

•

LinkPost

222

Metadata Types

Field Name

feedItemVisibility relatedSObjectType

CustomFeedFilter

Field Type

FeedItemVisibility (

enumeration

of type string)

The visibility of feed items that the filter shows. For example, you can show only poll posts that are visible internally.

Valid values are:

•

AllUsers

•

InternalUsers string

Description

•

MilestoneEvent

•

QuestionPost

•

PollPost

•

ReplyPost

•

SocialPost

•

TextPost

The API name of the object that the feed item refers to.

This field is typically used with the CreateRecordEvent feed item type.

For example, a feed filter can show CreateRecordEvent feed items for the Cases object.

Declarative Metadata Sample Definition

The following is an example of a CustomFeedFilter component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomFeedFilter xmlns= "http://soap.sforce.com/2006/04/metadata">

<criteria >

<feedItemType >CreateRecordEvent </feedItemType >

<relatedSObjectType >MyCO01__c </relatedSObjectType >

</criteria >

<criteria >

<feedItemType >CreateRecordEvent </feedItemType >

<relatedSObjectType >Case </relatedSObjectType >

</criteria >

<criteria >

<feedItemType >PollPost </feedItemType >

<feedItemVisibility >InternalUsers </feedItemVisibility >

</criteria >

<label >Sample Custom Feed Filter </label >

</CustomFeedFilter >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

223

Metadata Types CustomLabels

<members >myCaseFeedFilter </members >

<name >CustomFeedFilter </name >

</types >

<version >39.0

</version >

</Package >

CustomLabels

This metadata type allows you to create custom labels that can be localized for use in different languages, countries, and currencies.

This type extends the

Metadata metadata type and inherits its

fullName

field. Custom labels are custom text values, up to 1,000 characters in length, that can be accessed from Apex classes or Visualforce pages. For more information, see “Custom Labels” in the

Salesforce online help.

Declarative Metadata File Suffix and Directory Location

Master custom label values are stored in the

CustomLabels.labels

file. Translations are stored in a file with a name format of

Translation-localeCode.translation

, where

localeCode

is the locale code of the translation language. The supported locale codes are listed in

Language

on page 677.

Custom label translations are stored in the labels

folder in the corresponding package directory.

Version

CustomLabels components are available in API version 14.0 and later.

Fields

Field

fullName

Field Type

string labels

CustomLabel

[]

Description

Required. The name of the custom label bundle.

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.

A list of custom labels.

CustomLabel

This metadata type represents a custom label. This type extends the Metadata metadata type and inherits its

fullName

field.

Field

categories

Field Type

string

Description

A comma-separated list of categories for the label. This field can be used in filter criteria when creating custom label list views.

Maximum of 255 characters.

224

Metadata Types CustomLabels

Field

fullName language protected shortDescription value

Field Type

string string boolean string string

Description

Required. The name of the custom label.

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.

Required. The language of the translated custom label.

Required. Indicates whether this component is protected ( true

) or not ( false

). Protected components cannot be linked to or referenced by components created in the installing organization.

Required. An easily recognizable term to identify this custom label. This description is used in merge fields.

Required. The translated custom label. Maximum of 1000 characters.

Usage

Use CustomLabels with the wildcard character (*) for members in the package.xml

manifest file to retrieve all custom labels that are defined in your organization. CustomLabels doesn’t support retrieving one or more custom labels by name. To retrieve specific labels by name, use CustomLabel and specify the label names as members.

Declarative Metadata Sample Definition

A sample XML definition of a custom label components is shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomLabels xmlns= "http://soap.sforce.com/2006/04/metadata">

<labels >

<fullName >quoteManual </fullName >

<value >This is a manual quote.

</label >

<language >en_US </language >

<protected >false </protected >

<shortDescription >Manual Quote </shortDescription >

</labels >

<labels >

<fullName >quoteAuto </fullName >

<value >This is an automatically generated quote.

</label >

<language >en_US </language >

<protected >false </protected >

<shortDescription >Automatic Quote </shortDescription >

</labels >

</CustomLabels >

This is a sample manifest file for retrieving all custom labels in the organization by using the CustomLabels type.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

225

Metadata Types Custom Metadata Types (CustomObject)

<fullName >MyPkg </fullName >

<types >

<members >* </members >

<name >CustomLabels </name >

</types >

<version >39.0

</version >

</Package >

This is a sample manifest file for retrieving two custom labels by name. Notice it uses the CustomLabel singular type.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<fullName >MyPkg </fullName >

<types >

<members >quoteManual </members >

<members >quoteAuto </members >

<name >CustomLabel </name >

</types >

<version >39.0

</version >

</Package >

SEE ALSO:

Translations

Custom Metadata Types (CustomObject)

Represents the metadata associated with a custom metadata type.

For more information, see the

Custom Metadata Types Implementation Guide

.

File Suffix and Directory Location

A custom metadata type is defined as a custom object and is stored in the objects folder. Custom metadata types have a suffix of

__mdt

(instead of

__c

for custom objects). Custom metadata type field names have a suffix of

__c

, like other custom fields. Custom metadata type field names must be dot-qualified with the name of the custom metadata type to which they belong.

Names of custom metadata types must be unique within their namespace. All custom metadata types belong to the

CustomMetadata namespace and can optionally belong to a second namespace. In your organization, you can use custom metadata types with your namespace as well as other organizations’ namespaces.

Version

Custom metadata type components are available in API version 31.0 and later.

Special Access Rules

To create custom metadata types, you must have the “Author Apex” permission. Only managed package developers can add new fields to the custom metadata types in their managed packages. Customers who install a managed custom metadata type can’t add new custom fields to it.

226

Metadata Types Custom Metadata Types (CustomObject)

Fields

Custom metadata types can contain the following CustomObject fields.

To make the fields on your custom metadata types unique and indexable, mark your fields as

Unique

and

ExternalId

.

Field Name

description fields gender

Protected label pluralLabel startsWith

Field Type

string

CustomField[]

Gender

boolean string string

StartsWith

( enumeration of type string)

Description

A description of the custom metadata type. This field can contain a maximum of 1,000 characters.

Represents one or more custom fields in the custom metadata type.

Indicates the gender of the noun that represents the object.

This field is used for languages where words need different treatment depending on their gender.

When a custom metadata type is released in a managed package, access is limited in specific ways.

•

Code that’s in the same managed package as custom metadata records can read the records.

•

Code that’s in the same managed package as custom metadata types can read the records that belong to that type.

•

Code that’s in a managed package that doesn’t contain either the type or the protected record can’t read the protected records.

•

Code that the subscriber creates and code that’s in an unmanaged package can’t read the protected records.

•

The developer can modify protected records only with a package upgrade. The subscriber can’t read or modify protected records. The developer name of a protected record can’t be changed after release.

•

The subscriber can’t create records of a protected type.

Records that are hidden by these access rules are also unavailable to REST, SOAP, SOQL, and Setup.

A label that represents the object throughout the Salesforce

Setup user interface. Custom metadata types are visible only through the recently used objects list on the Force.com

Home Page and in the packaging user interface.

The plural version of the label value.

Indicates whether the noun starts with a vowel, a consonant, or a special character. This field is used for languages where words need different treatment depending on their first character.

227

Metadata Types

Field Name

visibility

Custom Metadata Types (CustomObject)

Field Type Description

SetupObjectVisibility (enumeration of type string)

When this field is present, this component is not a custom object, but a custom setting or custom metadata type. This field returns the visibility of the custom setting or custom metadata type. The following values are valid.

•

Public

—If the custom setting or custom metadata type is packaged, it’s accessible to all subscribing organizations.

•

Protected

—If the custom setting or custom metadata type is in a managed package, it’s only accessible to the developer organization; subscribing organizations can’t access it.

The default value is

Public

.

Declarative Metadata Sample Definition

In this example, Picklists R Us creates its Reusable Picklist custom metadata type by deploying a file in the objects folder, named

ReusablePicklistOption__mdt.object

, with these contents.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<fields >

<fullName >AlphaSort__c </fullName >

<defaultValue >false </defaultValue >

<externalId >false </externalId >

<label >Sorted Alphabetically </label >

<type >Checkbox </type >

</fields >

<label >Reusable Picklist </label >

<pluralLabel >Reusable Picklist </pluralLabel >

<visibility >Public </visibility >

</CustomObject >

This excerpt from a package.xml

file shows the use of dot notation and the

__mdt

suffix. If you’re using a namespace, for example picklist1234

, the full name of

ReusablePicklistOption__mdt

would be picklist1234

__ReusablePicklistOption__mdt

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

...

<types >

<members >PicklistTest__c.PicklistTestField__c

</members >

<members >ReusablePicklistOption__mdt.Picklist__c

</members >

<members >ReusablePicklistOption__mdt.SortOrder__c

</members >

<members >PicklistUsage__mdt.Field__c

</members >

<members >PicklistUsage__mdt.Picklist__c

</members >

<members >PicklistUsage__mdt.SObjectType__c

</members >

<members >ReusablePicklist__mdt.AlphaSort__c

</members >

<name >CustomField </name >

</types >

228

Metadata Types CustomMetadata

...

<types >

<members >PicklistTest__c </members >

<members >ReusablePicklistOption__mdt </members >

<members >PicklistUsage__mdt </members >

<members >ReusablePicklist__mdt </members >

<name >CustomObject </name >

</types >

...

<version >39.0

</version >

</Package >

CustomMetadata

Represents a record of a custom metadata type.

This type extends the

Metadata metadata type and inherits its

fullName

field.

File Suffix and Directory Location

CustomMetadata components have the suffix

.md

and are stored in the customMetadata

folder. Unlike custom metadata types, custom metadata records don’t have a double-underscore suffix. Custom metadata record names are prepended with their custom metadata type name, excluding the

__mdt

suffix but including the namespace of any types in an installed managed package.

Version

CustomMetadata components are available in API version 31.0 and later.

Special Access Rules

To create custom metadata records, you must have the “Customize Application” permission.

Fields

Field Name

description

Field Type

string label values string

CustomMetadataValue []

Description

A description of the custom metadata record. This field can contain a maximum of 1,000 characters.

A label that represents the object throughout the

Salesforce Setup user interface. Custom metadata records are currently visible only through the packaging user interface.

Represents one or more values for custom fields on the custom metadata record.

CustomMetadataValue

Represents a value for a custom field on the custom metadata record.

229

Metadata Types

Field Name

field value

Field Type

string

Any type

CustomMetadata

Description

Required. The non-object-qualified name of a custom field in the custom metadata type. This value corresponds to the name of a field on the custom metadata record’s custom metadata type. Include the namespace (if the type is from a managed package) and the

__c

suffix.

The name of the custom metadata type isn’t required.

For example, picklist1234__AlphaSort__c

.

The value on a custom metadata record. Where fields are

EntityDefinition and FieldDefinition, the qualified API names of the entity and the field it points to. This value can be null.

For more information, see Usage on page 233.

Declarative Metadata Sample Definitions

The following is an example of a CustomMetadata component. In this example, the sample app TravelApp deploys a Planets picklist, specifies its sort order, and adds picklist items to it.

Assuming Picklists R Us’s namespace is picklist1234

, to define the

Planets

picklist, TravelApp deploys a file in the customMetadata

folder, named picklist1234__ReusablePicklist.Planets.md

, with these contents. The xsi:type

attribute specifies the type for the value of the

AlphaSort__c

checkbox field.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomMetadata xmlns= "http://soap.sforce.com/2006/04/metadata" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd= "http://www.w3.org/2001/XMLSchema">

<description >All the planets in the solar system. Does not include asteroids.

</description >

<label >Planets </label >

<values >

<field >picklist1234__AlphaSort__c </field >

<value xsi:type= "xsd:boolean">false </value >

</values >

</CustomMetadata >

Picklists R Us creates its Reusable Picklist Option custom metadata type by deploying a file in the objects folder, named

ReusablePicklist__mdt.object

, with these contents.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<fields >

<fullName >Picklist__c </fullName >

<externalId >false </externalId >

<label >Picklist </label >

<length >40 </length >

<required >true </required >

<type >Text </type >

<unique >false </unique >

</fields >

230

Metadata Types CustomMetadata

<fields >

<fullName >SortOrder__c </fullName >

<externalId >false </externalId >

<label >Non-Alphabetical Sort Order </label >

<precision >3 </precision >

<scale >0 </scale >

<required >false </required >

<type >Number </type >

<unique >false </unique >

</fields >

<label >Reusable Picklist Option </label >

<pluralLabel >Reusable Picklist Options </pluralLabel >

</CustomObject >

To define the

Mars

picklist item, TravelApp deploys a file, named picklist1234__ReusablePicklistOption.Mars.md

, with these contents. This component file specifies types that apply to the

ReusablePicklistOption__mdt

custom fields.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomMetadata xmlns= "http://soap.sforce.com/2006/04/metadata" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd= "http://www.w3.org/2001/XMLSchema">

<label >Mars </label >

<values >

<field >picklist1234__Picklist__c </field >

<value xsi:type= "xsd:string">Planets </value >

</values >

<values >

<field >picklist1234__SortOrder__c </field >

<value xsi:type= "xsd:int">4 </value >

</values >

</CustomMetadata >

To define the

Motel6

picklist item, TravelApp deploys a file, named picklist1234__ReusablePicklistOption.Motel6.md

, with these contents.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomMetadata xmlns= "http://soap.sforce.com/2006/04/metadata" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd= "http://www.w3.org/2001/XMLSchema">

<label >Motel 6 </label >

<values >

<field >picklist1234__Picklist__c </field >

<value xsi:type= "xsd:string">Hotels </value >

</values >

</CustomMetadata >

Because the

SortOrder__c

field isn’t required, this file doesn’t require a value for

SortOrder__c

. Alternatively, the file could have explicitly specified a value with xsi:nil

to ensure that

SortOrder__c

was cleared of any previous value.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomMetadata xmlns= "http://soap.sforce.com/2006/04/metadata" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd= "http://www.w3.org/2001/XMLSchema">

<label >Motel 6 </label >

<values >

231

Metadata Types CustomMetadata

<field >picklist1234__Picklist__c </field >

<value xsi:type= "xsd:string">Hotels </value >

</values >

<values >

<field >picklist1234__SortOrder__c </field >

<value xsi:nil= "true" />

</values >

</CustomMetadata >

This excerpt from a package.xml

file illustrates the inclusion of custom metadata types and their namespaces in custom metadata records’ names. Assume that Picklists R Us’s namespace is picklist1234

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<package xmlns= "http://soap.sforce.com/2006/04/metadata">

…

<types >

<members >picklist1234__ReusablePicklist.Hotels

</members >

<members >picklist1234__ReusablePicklist.Planets

</members >

<members >picklist1234__ReusablePicklistOption.Bellagio

</members >

<members >picklist1234__ReusablePicklistOption.Motel6

</members >

<members >picklist1234__ReusablePicklistOption.Mercury

</members >

<members >picklist1234__ReusablePicklistOption.Venus

</members >

<members >picklist1234__ReusablePicklistOption.Earth

</members >

<members >picklist1234__PicklistUsage.BookedHotel

</members >

<members > picklist1234__PicklistUsage.DestinationPlanetPL

</members >

<members >picklist1234__PicklistUsage.PlanetVisitedPl

</members >

<name >CustomMetadata </name >

</types >

…

</package >

TravelApp, Inc.’s package.xml

file uses a wildcard to install custom metadata, as is shown in this excerpt from their package.xml

file. Unless you want to deploy or retrieve specific records, using a wildcard is easier than listing all of your custom metadata records in your package.xml

file.

<types >

<members >*</members>

<name >CustomMetadata </name >

</types >

If the custom metadata is from a managed package, the name after the dot in the package.xml

file—between the two dots in the file name—is qualified by the managed package’s namespace. For example, assuming TravelApp uses the namespace travelApp1234

, the first member element in the TravelApp package.xml

file appears to Galactic Tours as:

<members >picklist1234__ReusablePicklist.travelApp1234__Hotels

</members >

Here’s another example. In this case, we have an instance of custom metadata record, whose EntityDefinition field points to a custom object named

SalesAgreement__c

. The FieldDefinition field points to the custom field

CustomerReference__c

on

SalesAgreement__c

. You can deploy new custom metadata records and retrieve existing ones with EntityDefinition and

FieldDefinition fields using qualified API names of custom and standard entities and their fields.

<?xml

version= "1.0" encoding= "UTF-8"?> <values >

<field >EntityDefintionField__c </field >

232

Metadata Types CustomObject

<value xsi:type= "xsd:string">v1__SalesAgreement__c </value >

</values >

<values >

<field >FieldDefinitionField__c </field >

<value xsi:type= "xsd:string">v1__CustomerReference__c </value >

</values >

Usage

When specifying the value

field in the CustomMetadataValue subtype, specify an appropriately typed object that’s based on your field type definition. In declarative metadata definitions for CustomMetadataValue, use the xsi:type

attribute of the value element.

For example, to specify a boolean value:

<value xsi:type= "xsd:boolean">true </value >

. Valid xsi:type

attributes are:

Custom metadata value

xsi:type="xsd:boolean" xsi:type="xsd:date" xsi:type="xsd:dateTime" xsi:type="xsd:picklist" xsi:type="xsd:string" xsi:type="xsd:string" xsi:type="xsd:string" xsi:type="xsd:string" xsi:type="xsd:string" xsi:type="xsd:int" xsi:type="xsd:double"

Custom field definition

Checkbox

Date

Date/Time

Picklist

Text

Phone

TextArea

URL

Email

Number/Percent, with scale equal to 0

Number/Percent, with scale not equal to 0

You can also omit the xsi:type

attribute. For example,

<value >true </value >

.

Although this attribute must be specified for any CustomMetadataValue, you can use an element with the xsi:nil

attribute set to true

to explicitly set the field’s value to null

. For example,

<value xsi:nil= "true"/>

.

Using null

field values differs from leaving out the CustomMetadataValue for a particular field entirely. If you leave out the

CustomMetadataValue, the value of the field doesn’t change. The field’s value is null

for newly deployed custom metadata records and left at its previous value for updated custom metadata records.

When you retrieve CustomMetadataValue objects, the value

field of the returned object holds a value of the correct type, specified by xsi:type

in the case of declarative metadata definitions.

CustomObject

Represents a custom object that stores data unique to your organization or an external object that maps to data stored outside Salesforce.

This type extends the

Metadata metadata type and inherits its

fullName

field. You must specify all relevant fields when you create

233

Metadata Types CustomObject or update a custom object. You cannot update a single field on the object. For more information about custom objects, see Administer

Custom Objects in the Salesforce online help.

You can also use this metadata type to work with customizations of standard objects, such as accounts. For an example, see

Standard

Objects on page 17.

All metadata components have a

fullName

field, which must be fully specified for any custom object.

For example, the following are fully specified names for a standard object and a custom object respectively:

Account

MyCustomObject__c

And the following is a fully specified name for an external object:

MyExternalObject__x

For sample Java code that creates a custom object, see Step 3: Walk Through the Java Sample Code on page 6.

Declarative Metadata File Suffix and Directory Location

Custom object names are automatically appended with __c. The file suffix is

.object

for the custom object or standard object file.

External object names are automatically appended with __x. The file suffix is

.object

for the external object file.

Custom, standard, and external objects are stored in the objects

folder in the corresponding package directory.

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 objects are available in API version 10.0 and later. External objects are available in API version 32.0 and later.

Fields

Unless otherwise noted, all fields are createable, filterable, and nillable.

Field Name

actionOverrides

Field Type

ActionOverride []

allowInChatterGroups businessProcesses compactLayoutAssignment boolean

BusinessProcess

[] string

Description

A list of action overrides on the object.

This field is available in API version 18.0 and later.

Indicates whether records of this custom object type can be added to Chatter groups.

This field is available in API version 34.0 and later.

A list of business processes associated with the object.

This field is available in API version 17.0 and later.

The compact layout assigned to the object.

This field is available in API version 29.0 and later.

234

Metadata Types CustomObject

Field Name

compactLayouts customHelp customHelpPage customSettingsType

Field Type

CompactLayout

[]

Description

A list of compact layouts associated with the object.

This field is available in API version 29.0 and later.

string The s-control that contains the help content if the object has customized help content. This field is available in API version

14.0 and later.

string

CustomSettingsType

(enumeration of type string)

The Visualforce page that contains the help content if the object has customized help content. This field is available in

API version 16.0 and later.

When this field is present, this component is not a custom object, but a custom setting. This field returns the type of custom setting. The following string values are valid:

•

List

—static data stored in cache and accessed as part of your application and available organization-wide.

•

Hierarchy

—static data stored in cache and accessed as part of your application and available based on a hierarchy of user, profile or organization. This is the default value.

This field is available in API version 17.0 and later.

customSettingsVisibility

CustomSettingsVisibility

(enumeration of type string)

When this field is present, this component is not a custom object, but a custom setting. This field returns the visibility of the custom setting. The following string values are valid:

•

Public

—if the custom setting is packaged, it is accessible to all subscribing organizations.

•

Protected

—if the custom setting is in a managed package, it is only accessible to the developer organization. Subscribing organizations cannot access it.

This is the default value.

This field is available in API versions 17.0 through 33.0. In versions 34.0 and later, use the visibility

field instead of this field.

deploymentStatus deprecated description enableActivities

DeploymentStatus

( enumeration of type string)

Indicates the deployment status of the object.

boolean string boolean

Reserved for future use.

A description of the object. Maximum of 1000 characters.

Indicates whether the object is enabled for activities ( true

) or not ( false

).

Not available for external objects.

235

Metadata Types

Field Name

enableBulkApi enableDivisions enableEnhancedLookup enableFeeds enableHistory enableReports enableSearch

Field Type

boolean boolean boolean boolean boolean boolean boolean

CustomObject

Description

When enabled, the object is classified as an Enterprise

Application object for usage tracking.

When enabled, enableSharing

and enableStreamingApi

must also be enabled.

This field is available in API version 31.0 and later.

Indicates whether the object is enabled for divisions ( true

) or not ( false

). For more information about the Division object, see the

SOAP API Developer's Guide

.

Indicates whether the object is enabled for enhanced lookups

( true

) or not ( false

). In API version 28.0 and later, this field can also be used for the Account, Contact, and User objects. Enhanced lookups provide an updated lookup dialog interface that gives users the ability to filter, sort, and page through search results as well as customize search result columns. For more information about enhanced lookups, see

“Enable Enhanced Lookups” in the Salesforce online help.

Indicates whether the object is enabled for feed tracking

( true

) or not ( false

). For more information, see “Customize

Chatter Feed Tracking” in the Salesforce online help.

This field is available in API version 18.0 and later.

Indicates whether the object is enabled for history tracking

( true

) or not ( false

). Also available for standard objects in API version 29.0 and later.

Indicates whether the object is enabled for reports ( true

) or not ( false

). Support for external objects is available in

API version 38.0 and later.

Indicates whether the object’s records can be found via SOSL and Salesforce searches. Corresponds to

Allow Search in the user interface.

By default, search is disabled for new custom objects. This field is available for custom objects in API version 35.0 and later.

By default, search is disabled for new external objects.

However, you can validate and sync an external data source to automatically create external objects. Syncing always enables search on the external object when search is enabled on the external data source, and vice versa. This field is available for external objects in API version 37.0 and later.

236

Metadata Types

Field Name

enableSharing enableStreamingApi externalDataSource externalName externalRepository externalSharingModel

CustomObject

Field Type

boolean boolean string

Description

When enabled, the object is classified as an Enterprise

Application object for usage tracking.

When enabled, enableBulkApi

and enableStreamingApi

must also be enabled.

This field is available in API version 31.0 and later.

When enabled, the object is classified as an Enterprise

Application object for usage tracking.

When enabled, enableBulkApi

and enableSharing must also be enabled.

This field is available in API version 31.0 and later.

Required and available for external objects only. The name of the external data source that stores the data for the external object. The data source is represented by the

ExternalDataSource component.

This field is available in API version 32.0 and later.

string string

Required and available for external objects only. The name of the table in the external data source that contains the data for the external object.

This field is available in API version 32.0 and later.

Available for Salesforce Connect external objects only.

Corresponds to

Display URL Reference Field in the user interface.

The external object’s

Display URL

standard field values are automatically generated from the external system. For example, with the OData 2.0 adapter for Salesforce Connect, the value is based on the link href

that’s defined on the

OData producer. You can override the default values with the values of a custom field on the same external object. Select the field name, and make sure that the custom field’s values are valid URLs.

This field is available in API version 32.0 and later.

SharingModel (

enumeration

of type string)

Indicates the external organization-wide defaults for the object, which determines the access level for external users, such as portal and community users. This field is supported for these objects:

•

Accounts and their associated contracts and assets

•

Cases

•

Contacts

237

Metadata Types CustomObject

Field Name

fields fieldSets

fullName

gender household listViews namedFilter

CustomField[]

FieldSet

string historyRetentionPolicy label

HistoryRetentionPolicy

string nameField

Field Type

Gender

boolean

ListView

[]

NamedFilter

CustomField

[]

Description

•

Opportunities

•

Custom Objects

•

Users

This field is available in API version 31.0 and later.

Represents one or more fields in the object.

Defines the field set that exists on this object.

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.

This value cannot be null

.

Indicates the gender of the noun that represents the object.

This is used for languages where words need different treatment depending on their gender.

This field supports relationship groups, a feature available only with Salesforce for Wealth Management. For more information, see “Salesforce for Wealth Management

Overview” in the Salesforce online help.

Reserved for future use.

Label that represents the object throughout the Salesforce user interface.

We recommend that you make object labels unique across all standard, custom, and external objects in the org.

Represents one or more list views associated with the object.

Represents the metadata associated with a lookup filter. Use this metadata type to create, update, or delete lookup filter definitions.

This field is available in API version 17.0 and later.

This field has been removed as of API version 30.0 and is only available in prior versions. The metadata associated with a lookup filter is now represented by the lookupFilter field in the CustomField component.

Required for custom objects. External objects may instead specify the name field by setting isNameField

to true in the CustomField component.

The field that this object's name is stored in. Every custom object must have a name, usually a string or autonumber.

238

Metadata Types CustomObject

Field Name

pluralLabel recordTypes recordTypeTrackFeedHistory recordTypeTrackHistory searchLayouts sharingModel sharingReasons sharingRecalculations startsWith validationRules visibility

Field Type

string

RecordType

boolean boolean

[]

Description

Identifier for the custom object record. This name appears in page layouts, related lists, lookup dialogs, search results, and key lists on tab home pages. By default, this field is added to the custom object page layout as a required field.

Plural version of the

label

value.

An array of one or more record types defined for this object.

Indicates whether the record type is enabled for feed tracking

( true

) or not ( false

). To set this field to true

, the

enableFeeds

field on the associated CustomObject

must also be true

. For more information, see “Customize Chatter

Feed Tracking” in the Salesforce online help.

This field is available in API version 19.0 and later.

Indicates whether history tracking is enabled for this record type ( true

) or not ( false

). To set recordTypeTrackHistory

to true the enableHistory

field on the associated custom object must also be true

.

This field is available in API version 19.0 and later.

SearchLayouts

SharingModel (

enumeration

of type string)

The Search Layouts related list information for the object.

Indicates the organization-wide defaults for the object.

Note: Using API version 29.0 and earlier, this field is read-only and you can't set this field through Metadata

API; you must use the Salesforce user interface. Using

API version 30.0 and later, you can set this field for internal users using the API and the Salesforce user interface.

SharingReason

[]

SharingRecalculation []

The reasons why the object is being shared.

A list of custom sharing recalculations associated with the object.

StartsWith

type string)

( enumeration

of Indicates whether the noun starts with a vowel, consonant, or is a special character. This is used for languages where words need different treatment depending on the first character. Valid values are listed in

StartsWith .

An array of one or more validation rules on the object.

ValidationRule

[]

SetupObjectVisibility

(enumeration of type string)

When this field is present, this component is not a custom object, but a custom setting or custom metadata type. This field returns the visibility of the custom setting or custom metadata type. The following values are valid.

239

Metadata Types CustomObject

Field Name

webLinks

Field Type

WebLink []

Description

•

Public

—If the custom setting or custom metadata type is packaged, it’s accessible to all subscribing organizations.

•

Protected

—If the custom setting or custom metadata type is in a managed package, it’s only accessible to the developer organization; subscribing organizations can’t access it.

The default value is

Public

.

This field is available in API version 34.0 and later. For custom settings, this field replaces the customSettingsVisibility

field.

An array of one or more weblinks defined for the object.

Declarative Metadata Additional Components

CustomObject definitions may include additional components which are defined in the custom object for declarative metadata. The following components are defined in the CustomObject:

•

ActionOverride

•

BusinessProcess

•

CompactLayout

•

CustomField

•

FieldSet

•

HistoryRetentionPolicy

•

ListView

•

RecordType

•

SearchLayouts

•

SharingReason

•

SharingRecalculation

•

ValidationRule

•

WebLink

Declarative Metadata Sample Definition

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<deploymentStatus >Deployed </deploymentStatus >

<description >test object with one field for eclipse ide testing </description >

<fields >

<fullName >Comments__c </fullName >

<description >add your comments about this object here </description >

<inlineHelpText >This field contains comments made about this object </inlineHelpText >

240

Metadata Types

<label >Comments </label >

<length >32000 </length >

<type >LongTextArea </type >

<visibleLines >30 </visibleLines >

</fields >

<label >MyFirstObject </label >

<nameField >

<label >MyFirstObject Name </label >

<type >Text </type >

</nameField >

<pluralLabel >MyFirstObjects </pluralLabel >

<sharingModel >ReadWrite </sharingModel >

</CustomObject >

The following is the metadata definition of an external object for Salesforce Connect.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<actionOverrides >

<actionName >CancelEdit </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >Delete </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >Edit </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >Follow </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >List </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >New </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >SaveEdit </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >Tab </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >View </actionName >

<type >Default </type >

</actionOverrides >

241

CustomObject

Metadata Types

<deploymentStatus >InDevelopment </deploymentStatus >

<description >Products </description >

<enableFeeds >false </enableFeeds >

<externalDataSource >OData </externalDataSource >

<externalIndexAvailable >false </externalIndexAvailable >

<externalName >Products </externalName >

<fields >

<fullName >DiscontinuedDate__c </fullName >

<description >DiscontinuedDate </description >

<externalDeveloperName >DiscontinuedDate </externalDeveloperName >

<externalId >false </externalId >

<isFilteringDisabled >false </isFilteringDisabled >

<isNameField >false </isNameField >

<isSortingDisabled >false </isSortingDisabled >

<label >DiscontinuedDate </label >

<required >false </required >

<type >DateTime </type >

</fields >

<fields >

<fullName >ID__c </fullName >

<description >ID </description >

<externalDeveloperName >ID </externalDeveloperName >

<externalId >false </externalId >

<isFilteringDisabled >false </isFilteringDisabled >

<isNameField >false </isNameField >

<isSortingDisabled >false </isSortingDisabled >

<label >ID </label >

<precision >18 </precision >

<required >false </required >

<scale >0 </scale >

<type >Number </type >

<unique >false </unique >

</fields >

<fields >

<fullName >Name__c </fullName >

<description >Name </description >

<externalDeveloperName >Name </externalDeveloperName >

<externalId >false </externalId >

<isFilteringDisabled >false </isFilteringDisabled >

<isNameField >false </isNameField >

<isSortingDisabled >false </isSortingDisabled >

<label >Name </label >

<length >128 </length >

<required >false </required >

<type >Text </type >

<unique >false </unique >

</fields >

<fields >

<fullName >Price__c </fullName >

<description >Price </description >

<externalDeveloperName >Price </externalDeveloperName >

<externalId >false </externalId >

<isFilteringDisabled >false </isFilteringDisabled >

<isNameField >false </isNameField >

242

CustomObject

Metadata Types

<isSortingDisabled >false </isSortingDisabled >

<label >Price </label >

<precision >16 </precision >

<required >false </required >

<scale >2 </scale >

<type >Number </type >

<unique >false </unique >

</fields >

<fields >

<fullName >Products__c </fullName >

<externalDeveloperName >Products </externalDeveloperName >

<externalId >false </externalId >

<isFilteringDisabled >false </isFilteringDisabled >

<isNameField >false </isNameField >

<isSortingDisabled >false </isSortingDisabled >

<label >Products </label >

<length >20 </length >

<referenceTo >Products__x </referenceTo >

<relationshipLabel >Products </relationshipLabel >

<relationshipName >Products </relationshipName >

<type >ExternalLookup </type >

</fields >

<fields >

<fullName >Rating__c </fullName >

<description >Rating </description >

<externalDeveloperName >Rating </externalDeveloperName >

<externalId >false </externalId >

<isFilteringDisabled >false </isFilteringDisabled >

<isNameField >false </isNameField >

<isSortingDisabled >false </isSortingDisabled >

<label >Rating </label >

<precision >18 </precision >

<required >false </required >

<scale >0 </scale >

<type >Number </type >

<unique >false </unique >

</fields >

<fields >

<fullName >ReleaseDate__c </fullName >

<description >ReleaseDate </description >

<externalDeveloperName >ReleaseDate </externalDeveloperName >

<externalId >false </externalId >

<isFilteringDisabled >false </isFilteringDisabled >

<isNameField >false </isNameField >

<isSortingDisabled >false </isSortingDisabled >

<label >ReleaseDate </label >

<required >false </required >

<type >DateTime </type >

</fields >

<label >Products </label >

<pluralLabel >Products </pluralLabel >

<searchLayouts >

<customTabListAdditionalFields >ExternalId </customTabListAdditionalFields >

<lookupDialogsAdditionalFields >ExternalId </lookupDialogsAdditionalFields >

CustomObject

243

Metadata Types ActionOverride

<lookupPhoneDialogsAdditionalFields >ExternalId </lookupPhoneDialogsAdditionalFields >

<searchResultsAdditionalFields >ExternalId </searchResultsAdditionalFields >

<searchResultsAdditionalFields >DisplayUrl </searchResultsAdditionalFields >

<searchResultsAdditionalFields >ID__c </searchResultsAdditionalFields >

</searchLayouts >

</CustomObject >

SEE ALSO:

CustomField

Metadata

Picklist (Including Dependent Picklist)

SearchLayouts

WebLink

CustomObjectTranslation

ListView

CompactLayout

ActionOverride

Represents an action override on a standard or custom object. Use it to create, update, edit, or delete action overrides. You can only access ActionOverride by accessing its encompassing CustomObject.

Declarative Metadata File Suffix and Directory Location

Action overrides are defined as part of a standard or custom object.

Version

Action overrides are available in API version 18.0 and later. Beginning in Summer ’13, action overrides can be applied to both standard or custom objects. Previously, action overrides only applied to custom objects.

Fields

Unless otherwise noted, all fields are createable, filterable, and nillable.

Field Name

actionName

Field Type

string

Description

Required. The possible values are the same as the actions you can override:

•

accept

•

clone

•

delete

•

edit

•

list

•

new

244

Metadata Types ActionOverride

Field Name

comment content formFactor

Field Type Description

•

tab

•

view string string

FormFactor ( enumeration of

type string)

Any comments you want associated with the override.

Set this field if type

is set to flexipage

, scontrol

, or visualforce

. It refers to the name of the Lightning Page, s-control, or Visualforce page to use as the override. To reference installed components, use the format of

Component_namespace__Component_name

.

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.

skipRecordTypeSelect type boolean

ActionOverrideType

( enumeration

of type string)

Set this field to true

if you prefer that any new records created by this action override aren’t forwarded to the record type selection page. This field is only valid if the actionName

is a “create” type (like new

), and type

is set to visualforce

. This field is available in API version 21.0

and later.

Required. Represents the type of action override. Valid values are described in

ActionOverrideType

.

ActionOverrideType

ActionOverrideType is an enumeration of type string that defines which kind of action override to use. The valid values are:

•

default

—The override uses a custom override provided by an installed package. If there isn’t one available, the standard Salesforce behavior is used.

•

flexipage

—The override uses behavior from a Lightning Page, and is only valid for the View action in Lightning Experience.

•

scontrol

—The override uses behavior from an s-control.

•

standard

—The override uses regular Salesforce behavior.

•

visualforce

—The override uses behavior from a Visualforce page.

245

Metadata Types BusinessProcess

Declarative Metadata Sample Definitions

You can define an action like this:

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<actionOverrides >

<actionName >edit </actionName >

<type >visualforce </type >

<content >myEditVFPage </content >

<comment >This edit action is a lot safer.

</comment >

</actionOverrides >

</CustomObject >

With the previous definition, calling

retrieve()

presents:

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<actionOverrides >

<actionName >edit </actionName >

<type >default </type >

</actionOverrides >

</CustomObject >

If a subscriber installed a package with the previous metadata, you can override the behavior by editing the XML. For example, if you want the regular Salesforce behavior, use:

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<actionOverrides >

<actionName >edit </actionName >

<type >standard </type >

</actionOverrides >

</CustomObject >

To set a Lightning Page action override on the View standard button in Lightning Experience, use:

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<actionOverrides >

<actionName >View </actionName >

<content >myLightningPage </content >

<formFactor >Large </formFactor >

<type >flexipage </type >

</actionOverrides >

</CustomObject >

SEE ALSO:

CustomObject

BusinessProcess

The BusinessProcess metadata type enables you to display different picklist values for users based on their profile. This type extends the

Metadata

metadata type and inherits its fullName

field.

Multiple business processes allow you to track separate sales, support, and lead lifecycles. A sales, support, lead, or solution process is assigned to a record type. The record type determines the user profiles that are associated with the business process. For more information, see “ Managing Multiple Business Processes ” in the Salesforce online help.

246

Metadata Types BusinessProcess

Declarative Metadata File Suffix and Directory Location

Business processes are defined as part of the custom object or standard object definition. See CustomObject

for more information.

Version

BusinessProcess components are available in API version 17.0 and later.

Fields

Field

description fullName

Field Type

string string isActive namespacePrefix values boolean string

PicklistValue []

Description

Description for the business process.

The 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. This field is inherited from the

Metadata

component.

Indicates if the business process is active ( true

) or not

( false

).

The namespace of the developer organization where the package was created.

A list of picklist values associated with this business process.

Declarative Metadata Sample Definition

A sample XML definition of a lead business process is shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

....

<businessProcesses >

<fullName >HardwareLeadProcess </fullName >

<description >Lead Process for hardware division </description >

<isActive >true </isActive >

<values >

<fullName >Closed - Converted </fullName >

<default >false </default >

</values >

<values >

<fullName >CustomLeadStep1 </fullName >

<default >false </default >

</values >

<values >

<fullName >CustomLeadStep2 </fullName >

<default >false </default >

</values >

247

Metadata Types CompactLayout

<values >

<fullName >Open - Not Contacted </fullName >

<default >false </default >

</values >

<values >

<fullName >Working - Contacted </fullName >

<default >true </default >

</values >

....

</businessProcesses >

</CustomObject >

SEE ALSO:

CustomObject

CompactLayout

Represents the metadata associated with a compact layout. This type extends the Metadata

metadata type and inherits its fullName field.

Compact layouts display a record’s key fields at a glance in both Salesforce1 and Lightning Experience.

Compact layouts support all field types except:

•

text area

•

long text area

•

rich text area

•

multi-select picklist

For more information on compact layouts, see “Compact Layouts” in the Salesforce Help.

File Suffix and Directory Location

Compact layouts are defined as part of the custom object or standard object definition. See

CustomObject

for more information.

Version

CompactLayout components are available in API version 29.0 and later.

Fields

Field Name

fields label

Field Type

string string

Description

The fields assigned to the compact layout. Their order represents the prioritization given to them when defining the compact layout.

Label that represents the object throughout the Salesforce user interface.

248

Metadata Types

Declarative Metadata Sample Definition

The following is an example of a CompactLayout component:

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<actionOverrides >

<actionName >Accept </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >Clone </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >Delete </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >Edit </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >List </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >New </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >Tab </actionName >

<type >Default </type >

</actionOverrides >

<actionOverrides >

<actionName >View </actionName >

<type >Default </type >

</actionOverrides >

<compactLayouts >

<fullName >testCompactLayout </fullName >

<compactLayoutItems >textfield__c </compactLayoutItems >

<label >testCompactLayoutLabel </label >

</compactLayouts >

<defaultCompactLayoutAssignment >SYSTEM </defaultCompactLayoutAssignment >

<deploymentStatus >Deployed </deploymentStatus >

<enableActivities >false </enableActivities >

<enableFeeds >false </enableFeeds >

<enableHistory >false </enableHistory >

<enableReports >false </enableReports >

<fields >

<fullName >textfield__c </fullName >

<externalId >false </externalId >

<label >textfield </label >

<length >255 </length >

<required >false </required >

<type >Text </type >

249

CompactLayout

Metadata Types CustomField

<unique >false </unique >

</fields >

<label >customObj </label >

<nameField >

<label >customObj Name </label >

<type >Text </type >

</nameField >

<pluralLabel >customObjs </pluralLabel >

<recordTypes >

<fullName >RT1 </fullName >

<active >true </active >

<label >RT1 </label >

<compactLayoutAssignment >testCompactLayout </compactLayoutAssignment >

</recordTypes >

<recordTypes >

<fullName >RT2 </fullName >

<active >true </active >

<label >RT2 </label >

</recordTypes >

<searchLayouts/ >

<sharingModel >ReadWrite </sharingModel >

</CustomObject >

CustomField

Represents the metadata associated with a field. Use this metadata type to create, update, or delete custom field definitions on standard, custom, and external objects or standard field definitions on standard objects. This type extends the

Metadata

metadata type and inherits its fullName

field.

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.Some standard picklist fields aren’t supported. See

Unsupported Metadata Types .

Specify the full name whenever you create or update a field. For example, a custom field on a custom object:

MyCustomObject__c.MyCustomField__c

An example of a custom field on a standard object:

Account.MyAcctCustomField__c

An example of a standard field on a standard object:

Account.Phone

An example of a custom field on an external object:

MyExternalObject__x.MyCustomField__c

Note: In the Metadata API, external objects are represented by the CustomObject metadata type.

The following custom field types aren’t available for external objects.

•

Auto-number (available only with the cross-org adapter for Salesforce Connect)

•

Currency

•

Formula

250

Metadata Types CustomField

•

Geolocation

•

Master-detail relationship

•

Picklist (available only with the cross-org adapter for Salesforce Connect)

•

Picklist (multi-select)

•

Roll-up summary

•

Text (encrypted)

•

Text Area (rich)

Declarative Metadata File Suffix and Directory Location

Custom fields are user-defined fields and are part of the custom object or standard object definition. See CustomObject

for more information. Standard fields are predefined on standard objects.

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.

Retrieving Fields on Custom or Standard Objects

When you retrieve a custom or standard object, you return everything associated with the object, except for standard fields that aren’t customizable. You can also retrieve only specific fields for an object by explicitly naming the object and fields in package.xml

. The following definition in package.xml

will create the files objects/MyCustomObject__c.object

and objects/Account.object

, each containing the requested field definitions.

<types >

<members >MyCustomObject__c.MyCustomField__c

</members >

<members >Account.MyCustomAccountField__c

</members >

<members >Account.Phone

</members >

<name >CustomField </name >

</types >

Version

Custom and standard fields are available in API version 10.0 and later.

Fields

Unless otherwise noted, all fields are createable, filterable, and nillable.

Field Name

caseSensitive

Field Type

boolean customDataType string

Description

Indicates whether the field is case-sensitive ( true

) or not

( false

).

For indirect lookup relationship fields on external objects, this attribute affects how this custom field’s values are matched against the values of the referenceTargetField

.

Reserved for future use.

251

Metadata Types CustomField

Field Name

defaultValue deleteConstraint deprecated description displayFormat displayLocationInDecimal

Field Type

string

Description

If specified, represents the default value of the field.

DeleteConstraint

(

enumeration

of type string)

Provides deletion options for lookup relationships. Valid values are:

SetNull

This is the default. If the lookup record is deleted, the lookup field is cleared.

Restrict

Prevents the record from being deleted if it’s in a lookup relationship.

Cascade

Deletes the lookup record as well as associated lookup fields.

For more information on lookup relationships, see “Object

Relationships” in the Salesforce Help.

boolean string string boolean

Reserved for future use.

Description of the field.

The display format.

Indicates how the value of a Geolocation custom field appears in the user interface. If true

, the geolocation appears in decimal notation. If false

, the geolocation appears as degrees, minutes, and seconds.

encrypted boolean externalDeveloperName externalId fieldManageability string boolean string

Note:

This page is about Shield Platform Encryption, not

Classic Encryption. What's the difference?

Indicates whether this field is encrypted ( true

) or not ( false

).

This field is available in API version 34.0 and later.

Available only for external objects. Name of the table column on the external data source that maps to this custom field in Salesforce.

Corresponds to

External Column Name

in the user interface. This field is available in API version 32.0 and later.

Indicates whether the field is an external ID field ( true

) or not

( false

).

Determines who can update the field after it’s released in a managed package. Valid values:

•

Locked—The field can’t be updated.

•

DeveloperControlled—The creator of the record can update the field with a package upgrade.

•

SubscriberControlled—Anyone with proper permissions can update the field. The field can’t be updated with a package upgrade.

252

Metadata Types CustomField

Field Name Field Type Description

Available only for fields on custom metadata types. If the field type is

MetadataRelationship

, and the manageability of the entity definition field is:

•

Subscriber-controlled, then the Field Definition field must be subscriber-controlled.

•

Upgradeable, then the Field Definition field must be either upgradeable or subscriber-controlled.

formula formulaTreatBlankAs fullName string If specified, represents a formula on the field.

TreatBlanksAs

( enumeration

of type string) string

Indicates how to treat blanks in a formula. Valid values are

BlankAsBlank

and

BlankAsZero

.

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.

This value cannot be null

.

globalPicklist indexed inlineHelpText isFilteringDisabled isNameField isSortingDisabled string.

boolean string boolean boolean boolean

(This field is available in API version 37.0 only and removed from later versions.) If this custom field is a picklist that’s based on a global picklist, globalPicklist

is the name of the global picklist whose value set this picklist inherits. A custom picklist that’s based on a global picklist is restricted. You can only add or remove values by editing the global picklist.

Indicates if the field is indexed. If this field is unique or the externalId

is set true, the isIndexed

value is set to true.

This field has been deprecated as of version 14.0 and is only provided for backward compatibility.

Represents the content of field-level help. For more information, see “Define Field-Level Help” in the Salesforce Help.

Available only for external objects. Indicates whether the custom field is available in filters. This field is available in API version 32.0

and later.

Available only for external object fields of type text. For each external object, you can specify one field as the name field. If you set this to true

, make sure that the external table column identified by the externalDeveloperName

attribute contains name values. This field is available in API version 32.0 and later.

Available only for external objects. Indicates whether the custom field is sortable. This field is available in API version 32.0 and later.

253

Metadata Types CustomField

Field Name

reparentableMasterDetail label length lookupFilter maskChar

Field Type

boolean string int

LookupFilter

Description

Indicates whether the child records in a master-detail relationship on a custom object can be reparented to different parent records.

The default value is false

.

This field is available in API version 25.0 and later.

Label for the field. You cannot update the label for standard picklist fields, such as the

Industry

field for accounts.

Length of the field.

Represents the metadata associated with a lookup filter. Use this metadata type to create, update, or delete lookup filter definitions.

This field is available in API version 30.0 and later.

Note: LookupFilter is not supported on the article type object.

EncryptedFieldMaskChar

( enumeration of type string)

Note: This page is about Classic Encryption, not Shield

Platform Encryption. What's the difference?

For encrypted fields, specifies the character to be used as a mask.

Valid values are enumerated in

EncryptedFieldMaskChar .

For more information on encrypted fields, see “Classic Encryption for Custom Fields” in the Salesforce Help.

maskType

EncryptedFieldMaskType

( enumeration of type string)

metadataRelationship

ControllingField picklist populateExistingRows string

Picklist

boolean

Note: This page is about Classic Encryption, not Shield

Platform Encryption. What's the difference?

For encrypted text fields, specifies the format of the masked and unmasked characters in the field. Valid values are enumerated in

EncryptedFieldMaskType For more information on encrypted fields,

see “Classic Encryption for Custom Fields” in the Salesforce Help.

In custom metadata relationships, represents the controlling field that specifies the standard or custom object in an entity definition metadata relationship. Required when creating a field definition metadata relationship on a custom metadata type. The object specified in the controlling field determines the values available in its dependent field definition. For example, specifying the

Account object filters the available fields in the field definition to

Account fields only. This field is available in API version 39.0 and later.

(Deprecated. Use this field in API version 37.0 and earlier only. In later versions, use valueSet

instead.) If specified, the field is a picklist, and this field enumerates the picklist values and labels.

Indicates whether existing rows will be populated ( true

) or not

( false

).

254

Metadata Types

Field Name

precision

Field Type

int referenceTargetField string referenceTo relationshipLabel relationshipName relationshipOrder required scale startingNumber string string string int boolean int int

CustomField

Description

The precision for number values. Precision is the number of digits in a number. For example, the number 256.99 has a precision of

5.

Available only for indirect lookup relationship fields on external objects. Specifies the custom field on the parent object to match against this indirect lookup relationship field, whose values come from an external data source. The specified custom field on the parent object must have both externalId

and unique

set to true

. This field is available in API version 32.0 and later.

If specified, indicates a reference this field has to another object.

Label for the relationship.

If specified, indicates the value for one-to-many relationships. For example, in the object MyObject that had a relationship to

YourObject, the relationship name might be YourObjects.

This field is valid for all master-detail relationships, but the value is only non-zero for junction objects. A junction object has two master-detail relationships, and is analogous to an association table in a many-to-many relationship. Junction objects must define one parent object as primary (0), the other as secondary (1). The definition of primary or secondary affects delete behavior and inheritance of look and feel, and record ownership for junction objects. For more information, see the Salesforce Help.

0 or 1 are the only valid values, and 0 is always the value for objects that are not junction objects.

Indicates whether the field requires a value on creation ( true

) or not ( false

).

The scale for the field. Scale is the number of digits to the right of the decimal point in a number. For example, the number 256.99

has a scale of 2.

If specified, indicates the starting number for the field. When you create records,

Starting Number

’s value increments to store the number that will be assigned to the next auto-number field created.

Note:

•

You can’t retrieve the starting number of an auto-number field through Metadata API. To specify a

Starting Number

while deploying, add a startingNumber

tag for your field to your package.xml

file. For example:

<startingNumber >42 </startingNumber >

255

Metadata Types CustomField

Field Name Field Type Description

•

If you deploy without specifying a

Starting

Number

value in your package.xml

file, the default starting number for standard fields is

0

. The default starting number for custom fields is

1

.

stripMarkup summarizedField summaryFilterItems summaryForeignKey summaryOperation trackFeedHistory trackHistory trackTrending boolean string

FilterItem[]

string

SummaryOperations

( enumeration of type string)

boolean boolean boolean

Set to true

to remove markup, or false

to preserve markup.

Used when converting a rich text area to a long text area.

Represents the field on the detail row that is being summarized.

This field cannot be null unless the

summaryOperation

value

is count

.

Represents the set of filter conditions for this field if it is a summary field. This field will be summed on the child if the filter conditions are met.

Represents the master-detail field on the child that defines the relationship between the parent and the child.

Represents the sum operation to be performed. Valid values are enumerated in

SummaryOperations

.

Indicates whether the field is enabled for feed tracking ( true

) or not ( false

). To set this field to true

, the enableFeeds

field on the associated

CustomObject must also be

true

. For more information, see “Customize Chatter Feed Tracking” in the

Salesforce Help.

This field is available in API version 18.0 and later.

Indicates whether history tracking is enabled for the field ( true

) or not ( false

). Also available for standard object fields (picklist and lookup fields only) in API version 30.0 and later.

To set trackHistory

to true

, the enableHistory

field on the associated standard or custom object must also be true

.

For more information, see “Field History Tracking” in the Salesforce

Help.

Field history tracking isn’t available for external objects.

Indicates whether historical trending data is captured for the field

( true

) or not ( false

). An object is enabled for historical trending if this attribute is true

for at least one field. Available in API version 29.0 and later.

For more information, see “Report on Historical Changes” in the

Salesforce Help.

256

Metadata Types

Field Name

trueValueIndexed

Field Type

boolean type unique valueSet visibleLines

FieldType

boolean

ValueSet int writeRequiresMasterRead boolean

CustomField

Description

This is only relevant for a checkbox field. If set, true values are built into the index. This field has been deprecated as of API version 14.0

and is only provided for backward compatibility.

Indicates the field type for the field. Valid values are enumerated in

FieldType

.

For standard fields on standard objects, the type

field is optional.

This field is included for some standard field types, such as Picklist or Lookup, but not for others. The type

field is included for custom fields.

Indicates whether the field is unique ( true

) or not ( false

).

Represents the set of values that make up a picklist on a custom field. Each value is defined as a

CustomValue on page 311. If this

custom field is a picklist that uses a global value set, valueSet is the name of the global value set whose values this picklist inherits. A custom picklist that uses a global value set is restricted.

You can only add or remove values by editing the global value set.

Note:

A ValueSet component has either a valueSetDefinition

or a valueName

specified, but never both.

This field is available in API version 38.0 and later.

Indicates the number of lines displayed for the field.

Sets the minimum sharing access level required on the master record to create, edit, or delete child records. This field applies only to master-detail or junction object custom field types.

•

true

—Allows users with “Read” access to the master record permission to create, edit, or delete child records. This setting makes sharing less restrictive.

•

false

—Allows users with “Read/Write” access to the master record permission to create, edit, or delete child records. This setting is more restrictive than true

, and is the default value.

For junction objects, the most restrictive access from the two parents is enforced. For example, if you set to true

on both master-detail fields, but users have “Read” access to one master record and “Read/Write” access to the other master record, users won't be able to create, edit, or delete child records.

Fields use additional data types. For more information, see Metadata Field Types on page 285.

257

Metadata Types CustomField

EncryptedFieldMaskChar

This field type is used in

maskChar

. It is a string with two valid values:

asterisk

or

X

. For more information on encrypted fields, see Classic Encryption for Custom Fields in the Salesforce online help.

EncryptedFieldMaskType

This field type is used in

maskType

. Valid values are:

all

All characters in the field are hidden. This option is equivalent to the

Mask All Characters

option in Salesforce.

creditCard

The first 12 characters are hidden and the last four display. This option is equivalent to the

Credit Card Number

option in

Salesforce.

ssn

The first five characters are hidden and the last four display. This option is equivalent to the

Social Security Number option in Salesforce.

lastFour

All characters are hidden but the last four display. This option is equivalent to the

Last Four Characters Clear

option in Salesforce.

sin

All characters are hidden but the last four display. This option is equivalent to the

Social Insurance Number

option in

Salesforce.

nino

All characters are hidden. Salesforce automatically inserts spaces after each pair of characters if the field contains nine characters.

This option is equivalent to the

National Insurance Number

option in Salesforce.

For more information on encrypted fields, see Classic Encryption for Custom Fields in the Salesforce online help.

LookupFilter

Represents the metadata associated with a lookup filter. Replaces the NamedFilter component, which was removed as of API version

30.0. LookupFilter is available in API version 30.0 and later.

Field

active booleanFilter description errorMessage filterItems

Field Type

boolean string string string

FilterItem[]

Description

Required. Indicates whether or not the lookup filter is active.

Specifies advanced filter conditions. For more information on advanced filter conditions, see “Getting the Most Out of Filter Logic” in the Salesforce Help.

A description of what this filter does.

The error message that appears if the lookup filter fails.

Required. The set of filter conditions. You can have up to 10 FilterItems per lookup filter.

258

Metadata Types CustomField

Field

infoMessage isOptional

Field Type

string boolean

Description

The information message displayed on the page. Use to describe things the user might not understand, such as why certain items are excluded in the lookup filter.

Required. Indicates whether or not the lookup filter is optional.

Lookup filters use additional data types. For more information, see Metadata Field Types .

FilterItem

Represents one entry in a set of filter criteria.

Field

field operation value

Field Type

string

FilterOperation

( enumeration of

type string) string valueField string

Description

Represents the field specified in the filter.

Represents the filter operation for this filter item. Valid values are

enumerated in FilterOperation

.

Represents the value of the filter item being operated upon, for example, if the filter is my_number_field__c > 1

, the value of value

is

1

.

Specifies if the final column in the filter contains a field or a field value.

Approval processes don’t support valueField

entries in filter criteria.

FilterOperation

This is an enumeration of type string that lists different filter operations. Valid values are:

•

equals

•

notEqual

•

lessThan

•

greaterThan

•

lessOrEqual

•

greaterOrEqual

•

contains

•

notContain

•

startsWith

•

includes

•

excludes

•

within

(

DISTANCE

criteria only)

259

Metadata Types CustomField

SummaryOperations

Represents the type of a

summaryOperation

. Valid values are:

•

Count

•

Min

•

Max

•

Sum

Declarative Metadata Sample Definition

The following example shows a field definition for a custom field that is named

Comments__c

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

....

<fields >

<fullName >Comments__c </fullName >

<description >Add your comments about this object here </description >

<inlineHelpText >This field contains help text for this object </inlineHelpText >

<label >Comments </label >

<length >32000 </length >

<type >LongTextArea </type >

<visibleLines >30 </visibleLines >

</fields >

....

</CustomObject >

The following is the definition for two fields on the Account standard object—a custom field (

MyCustomAccountField__c

), and a standard field (

Phone

) that has history tracking enabled.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<fields >

<fullName >MyCustomAccountField__c </fullName >

<description >A custom field on the Account standard object.

</description >

<externalId >false </externalId >

<inlineHelpText >Some help text.

</inlineHelpText >

<label >MyCustomAccountField </label >

<length >100 </length >

<required >false </required >

<trackFeedHistory >false </trackFeedHistory >

<trackHistory >false </trackHistory >

<type >Text </type >

<unique >false </unique >

</fields >

<fields >

<fullName >Phone </fullName >

<trackFeedHistory >false </trackFeedHistory >

<trackHistory >true </trackHistory >

260

Metadata Types

</fields >

</CustomObject >

SEE ALSO:

CustomObject

Picklist (Including Dependent Picklist)

Metadata

NamedFilter

FieldSet

Represents a field set. A field set is a grouping of fields. For example, you could have a field set that contains fields describing a user's first name, middle name, last name, and business title. Field sets can be referenced on Visualforce pages dynamically. If the page is added to a managed package, administrators can add, remove, or reorder fields in a field set to modify the fields presented on the Visualforce page without modifying any code.

Version

FieldSet components are available in API version 21.0 and later.

Fields

Field

availableFields description

Field Type

FieldSetItem []

string displayedFields label

FieldSetItem []

string

Description

An array containing all the possible fields in the field set.

Required. A description provided by the developer that describes the field set. This is required.

An array containing all the fields that are presented on the

Visualforce page. The order in which a field is listed determines the order of appearance on the page.

Required. The label used to reference the field set.

FieldSetItem

FieldSetItem represents an individual field in a field set.

Field

field isFieldManaged

Field Type

string boolean isRequired boolean

Description

Required. The name of a field in a standard or custom object.

Read-only. Denotes whether the field was added to the field set via a managed or unmanaged package.

Read-only. Indicates whether the field is universally required

( true

) or not ( false

).

FieldSet

261

Metadata Types HistoryRetentionPolicy

Declarative Metadata Sample Definition

A sample XML definition of a FieldSet component is shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<fieldSets >

<fullName >FieldSetNames </fullName >

<availableFields >

<field >MiddleName__c </field >

</availableFields >

<availableFields >

<field >Title__c </field >

</availableFields >

<description >FieldSet containing how to properly address someone </description >

<displayedFields >

<field >FirstName__c </field >

</displayedFields >

<displayedFields >

<field >LastName__c </field >

</displayedFields >

<label >FieldSet Names </label >

</fieldSets >

</CustomObject >

HistoryRetentionPolicy

Represents the policy for retaining field history data. By setting a policy, you can specify the number of months you want to maintain field history in Salesforce, and the number of years that you want to retain field history in the archive.

This component is only available to users with the “RetainFieldHistory” permission.

Declarative Metadata File Suffix and Directory Location

Field history retention policies are defined as part of a standard or custom object. You can set field history retention policies for objects

individually. See CustomObject for more information.

Version

Available in API version 31.0 and later.

Fields

Field Name Field Type

archiveAfterMonths int

Description

Required. The number of months that you want to keep field history data in Salesforce before archiving. You can set a minimum of 1 month and a maximum of 18 months. If you don’t set a number, the default is 18 months. (That is, Salesforce maintains data for 18 months before archiving.)

262

Metadata Types

Field Name Field Type

archiveRetentionYears int description gracePeriodDays string int

Description

Required. The number of years that you want to retain data in the archive.

You can set a minimum of zero years, and a maximum of 10 years. If no number is set, the default is 10 years.

A text description for the history retention.

The number of days of extra time after the archiveAfterMonths period before the data is archived. The gracePeriodDays

interval applies only to the first time that the data is archived; because all the data is copied the first time, the operation may take longer than subsequent times when only the data that changed since the last archival operation is copied. The gracePeriodDays

provides extra time for the administrator to prepare the organization before the initial archive operation. You can set a minimum of zero days and a maximum of 10 days. If no number is set, the default is 1 day.

Declarative Metadata Sample Definition

This sample shows the definition of a history retention policy for a custom object:

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<historyRetentionPolicy >

<archiveAfterMonths >6 </archiveAfterMonths >

<archiveRetentionYears >5 </archiveRetentionYears >

<description >My field history retention </description >

</historyRetentionPolicy >

<fields >

<fullName >AccountSource </fullName >

...

</CustomObject >

ListView

ListView allows you to see a filtered list of records, such as contacts, accounts, or custom objects. This type extends the Metadata

metadata type and inherits its fullName

field. See “Create a Custom List View in Salesforce Classic” in the Salesforce online help.

Note: List views with the Visible only to me

Restrict Visibility

option are not accessible in Metadata API. Each of these list views is associated with a particular user.

Declarative Metadata File Suffix and Directory Location

List views are stored within a CustomObject component. The component can represent a custom object or a standard object, such as an account.

Version

ListView components for custom objects are available in API version 14.0 and later. ListView components for standard objects, such as accounts, are available in API version 17.0 and later.

263

ListView

Metadata Types

Fields

Field

booleanFilter columns division filterScope filters fullName label language

Field Type

string string[] string

FilterScope

( enumeration of

type string)

ListViewFilter []

string string

Language

Description

This field represents an Advanced Option for a filter. Advanced

Options in filters allow you to build up filtering conditions that use a mixture of AND and OR boolean operators across multiple filter line items. For example,

(1 AND 2) OR 3

finds records that match both the first two filter line items or the third. See

“Getting the Most Out of Filter Logic” in the Salesforce online help.

The list of fields in the list view. The field name relative to the object name, for example

MyCustomField__c

, is specified for each custom field.

Note: Field names in the ListView columns don’t always match their API name counterparts. In particular, if person accounts is enabled in your organization, standard fields merged from a contact into an account start with the

PC_

prefix, while the corresponding API name starts with the

Person

prefix. For example, the ListView column name is

PC_Email

for a corresponding API field name of

PersonEmail

.

If your organization uses divisions to segment data and you have the “Affected by Divisions” permission, records in the list view must match this division. This field is only available if you are searching all records.

This field is available in API version 17.0 and later.

Required. This field indicates whether you are filtering by owner or viewing all records.

The list of filter line items.

Required. 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.

Required. The list view name.

The language used for filtering if your organization uses the

Translation Workbench and you are using the startsWith or contains

operator. The values entered as search terms must be in the same language as the filter language. See “Enter

Filter Criteria” in the Salesforce online help.

For a list of valid language values, see

Language .

This field is available in API version 17.0 and later.

264

ListView

Metadata Types

Field

queue sharedTo

Field Type

string

SharedTo

Description

The name of a queue. Objects are sometimes assigned to a queue so that the users who have access to the queue can monitor and manage them. When you create a queue, a corresponding list view is automatically created. See “Create

Queues” in the Salesforce online help.

Sharing access for the list view.

This field is available in API version 17.0 and later.

ListViewFilter

ListViewFilter represents a filter line item.

Field

filter operation value

Field Type

string

Description

Required. Represents the field specified in the filter.

FilterOperation

( enumeration

of type string)

Required. The operation used by the filter, such as equals

.

The valid values are listed in FilterOperation

.

string Represents the value of the filter item being operated upon, for example, if the filter is my_number_field__c > 1

, the value of value

is

1

.

FilterScope

This is an enumeration of type string that represents the filtering criteria for the records. The valid values are listed in the table below:

Enumeration Value

Everything

Mine

Queue

Delegated

MyTerritory

MyTeamTerritory

Team

Description

All records, for example All Opportunities.

Records owned by the user running the list view, for example My Opportunities.

Records assigned to a queue.

Records delegated to another user for action: for example, a delegated task. This option is available in API version 17.0 and later.

Records in the territory of the user seeing the list view. This option is available if territory management is enabled for your organization. This option is available in API version 17.0 and later.

Records in the territory of the team of the user seeing the list view. This option is available if territory management is enabled for your organization. This option is available in API version

17.0 and later.

Records assigned to a team. This option is available in API version 17.0 and later.

ListView

265

Metadata Types NamedFilter

Declarative Metadata Sample Definition

A sample XML definition of a list view in a custom object is shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

. . .

<listViews >

<fullName >All_Mileages </fullName >

<filterScope >all </filterScope >

<label >All Mileages </label >

</listViews >

<listViews >

<fullName >My_Mileages </fullName >

<booleanFilter >1 AND 2 </booleanFilter >

<columns >NAME </columns >

<columns >CREATED_DATE </columns >

<filterScope >mine </filterScope >

<filters >

<field >NAME </field >

<operation >equals </operation >

<value >Eric Bristow </value >

</filters >

<filters >

<field >City__c </field >

<operation >equals </operation >

<value >Paris </value >

</filters >

<label >My Mileages </label >

</listViews >

. . .

</CustomObject >

SEE ALSO:

CustomObject

Sample package.xml Manifest Files

NamedFilter

Note:

This component has been removed as of API version 30.0 and is only available in previous API versions. The metadata associated with a lookup filter is now represented by the lookupFilter

field in the CustomField component.

Represents the metadata associated with a lookup filter. Use this metadata type to create, update, or delete lookup filter definitions. This type extends the

Metadata metadata type and inherits its

fullName

field. You can also use this metadata type to work with customizations of lookup filters on standard fields.

Note: The namedFilter appears as a child of the target object of the associated lookup field.

Declarative Metadata File Suffix and Directory Location

Lookup filters are defined as part of the custom object or standard object definition. See CustomObject

for more information.

266

Metadata Types NamedFilter

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

Lookup filters are available in API version 17.0 and later.

Fields

Unless otherwise noted, all fields are createable, filterable, and nillable.

Field Name

active booleanFilter

Field Type

boolean string description errorMessage field filterItems infoMessage fullName isOptional name sourceObject string string string

FilterItems[]

string string boolean string string

Description

Required. Indicates whether or not the lookup filter is active.

Specifies advanced filter conditions. For more information on advanced filter conditions, see “Getting the Most Out of Filter

Logic” in the Salesforce online help.

A description of what this filter does.

The error message that appears if the lookup filter fails.

Required. The fullName

of the custom or standard field associated with the lookup filter. You can associate one relationship field with each lookup filter, and vice-versa.

Note: You cannot update a field associated with a lookup filter.

Required. The set of filter conditions.

The information message displayed on the page. Use to describe things the user might not understand, such as why certain items are excluded in the lookup filter.

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.

This value cannot be null

.

Required. Indicates whether or not the lookup filter is optional.

Required. The name of the lookup filter. If you create this field in the user interface, a name is automatically assigned. If you create this field through Metadata API, you must include the name

field.

The object that contains the lookup field that uses this lookup filter. Set this field if the lookup filter references fields on the source object.

267

Metadata Types NamedFilter

Lookup filters use additional data types. For more information, see Metadata Field Types .

FilterItems

FilterItems contains the following properties:

Field

field operation value

Field Type

string

FilterOperation

( enumeration of

type string) string

Description

Represents the field specified in the filter.

Represents the filter operation for this filter item. Valid values are

enumerated in FilterOperation

.

Represents the value of the filter item being operated upon, for example, if the filter is my_number_field__c > 1

, the value of value

is

1

.

FilterOperation

This is an enumeration of type string that lists different filter operations. Valid values are:

•

equals

•

notEqual

•

lessThan

•

greaterThan

•

lessOrEqual

•

greaterOrEqual

•

contains

•

notContain

•

startsWith

•

includes

•

excludes

Declarative Metadata Sample Definition

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

....

<namedfilters >

<fullName >nf_Acc </fullName >

<active >true </active >

<booleanFilter >1 OR 2 </booleanFilter >

<field >Account.lk__c

</field >

<filterItems >

<field >Account.Phone

</field >

<operation >notEqual </operation >

<value >x </value >

</filterItems >

268

Metadata Types Picklist (Including Dependent Picklist)

<filterItems >

<field >Account.Fax

</field >

<operation >notEqual </operation >

<value >y </value >

</filterItems >

<name >Acc </name >

<sourceObject >Account </sourceObject >

</namedfilters >

....

</CustomObject >

SEE ALSO:

CustomObject

Picklist (Including Dependent Picklist)

Metadata

CustomField

Picklist (Including Dependent Picklist)

Deprecated. Represents a picklist (or dependent picklist) definition for a custom field in a custom object or a custom or standard field in a standard object, such as an account.

Version

Use this type in API version 37.0 and earlier only. In later versions, Picklist is replaced by ValueSet. Picklists for custom fields in custom objects are available in API version 12.0 and later. Picklists for custom or standard fields in standard objects, such as accounts, are available in API version 16.0 and later.

Declarative Metadata File Suffix and Directory Location

Picklist definitions are included in the custom object and field with which they are associated.

Fields

Picklist contains the following fields:

Field Name

controllingField

Field Type

string picklistValues

PicklistValue[]

Description

The fullName

of the controlling field if this is a dependent picklist. A

dependent picklist works in conjunction with a controlling picklist or checkbox to filter the available options. The value chosen in the controlling field affects the values available in the dependent field. This field is available in API version 14.0 and later.

Required. Represents a set of values for a picklist.

269

Metadata Types

Field Name

restrictedPicklist sorted

Field Type

boolean boolean

Picklist (Including Dependent Picklist)

Description

Indicates whether the picklist’s value list is restricted. With a restricted picklist, only an admin can add or change values; users can’t load or remove values through the API. By default this value is false

.

This field is available in API version 37.0 and later.

Indicates whether values should be sorted ( true

), or not ( false

). By default this value is false

.

Java Sample

The following sample uses a picklist. For a complete sample of using a picklist with record types and profiles, see

Profile

on page 496.

public void setPicklistValues() {

// Create a picklist

Picklist expenseStatus = new Picklist();

PicklistValue unsubmitted = new PicklistValue(); unsubmitted.setFullName( "Unsubmitted" );

PicklistValue submitted = new PicklistValue(); submitted.setFullName( "Submitted" );

PicklistValue approved = new PicklistValue(); approved.setFullName( "Approved" );

PicklistValue rejected = new PicklistValue(); rejected.setFullName( "Rejected" ); expenseStatus.setPicklistValues( new PicklistValue[]

{unsubmitted, submitted, approved, rejected});

}

CustomField expenseStatusField = new CustomField(); expenseStatusField.setFullName(

"ExpenseReport__c.ExpenseStatus__c" ); expenseStatusField.setLabel( "Expense Report Status" ); expenseStatusField.setType(FieldType.Picklist); expenseStatusField.setPicklist(expenseStatus); try {

AsyncResult[] ars = metadataConnection.create( new Metadata[] {expenseStatusField});

} catch (ConnectionException ce) { ce.printStackTrace();

}

Declarative Metadata Sample Definition

The following sample shows usage for picklists, including dependent picklists, in a custom object. The isAmerican__c

checkbox controls the list of manufacturers shown in the manufacturer__c

picklist. The manufacturer__c

checkbox in turn controls the list of models shown in the model__c

picklist.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<deploymentStatus >Deployed </deploymentStatus >

270

Metadata Types Picklist (Including Dependent Picklist)

<enableActivities >true </enableActivities >

<fields >

<fullName >isAmerican__c </fullName >

<defaultValue >false </defaultValue >

<label >American Only </label >

<type >Checkbox </type >

</fields >

<fields >

<fullName >manufacturer__c </fullName >

<label >Manufacturer </label >

<picklist >

<controllingField >isAmerican__c </controllingField >

<picklistValues >

<fullName >Chrysler </fullName >

<controllingFieldValues >checked </controllingFieldValues >

<default >false </default >

</picklistValues >

<picklistValues >

<fullName >Ford </fullName >

<controllingFieldValues >checked </controllingFieldValues >

<default >false </default >

</picklistValues >

<picklistValues >

<fullName >Honda </fullName >

<controllingFieldValues >unchecked </controllingFieldValues >

<default >false </default >

</picklistValues >

<picklistValues >

<fullName >Toyota </fullName >

<controllingFieldValues >unchecked </controllingFieldValues >

<default >false </default >

</picklistValues >

<sorted >false </sorted >

</picklist >

<type >Picklist </type >

</fields >

<fields >

<fullName >model__c </fullName >

<label >Model </label >

<picklist >

<controllingField >manufacturer__c </controllingField >

<picklistValues >

<fullName >Mustang </fullName >

<controllingFieldValues >Ford </controllingFieldValues >

<default >false </default >

</picklistValues >

<picklistValues >

<fullName >Taurus </fullName >

<controllingFieldValues >Ford </controllingFieldValues >

<default >false </default >

</picklistValues >

<picklistValues >

<fullName >PT Cruiser </fullName >

<controllingFieldValues >Chrysler </controllingFieldValues >

271

Metadata Types Picklist (Including Dependent Picklist)

<default >false </default >

</picklistValues >

<picklistValues >

<fullName >Pacifica </fullName >

<controllingFieldValues >Chrysler </controllingFieldValues >

<default >false </default >

</picklistValues >

<picklistValues >

<fullName >Accord </fullName >

<controllingFieldValues >Honda </controllingFieldValues >

<default >false </default >

</picklistValues >

<picklistValues >

<fullName >Civic </fullName >

<controllingFieldValues >Honda </controllingFieldValues >

<default >false </default >

</picklistValues >

<picklistValues >

<fullName >Prius </fullName >

<controllingFieldValues >Toyota </controllingFieldValues >

<default >false </default >

</picklistValues >

<picklistValues >

<fullName >Camry </fullName >

<controllingFieldValues >Toyota </controllingFieldValues >

<default >false </default >

</picklistValues >

<sorted >false </sorted >

</picklist >

<type >Picklist </type >

</fields >

....

</CustomObject >

The following sample shows usage for the standard

Stage

field in opportunities.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<fields >

<fullName >StageName </fullName >

<picklist >

<picklistValues >

<fullName >Prospecting </fullName >

<default >false </default >

<forecastCategory >Pipeline </forecastCategory >

<probability >10 </probability >

</picklistValues >

<picklistValues >

<fullName >Qualification </fullName >

<default >false </default >

<forecastCategory >Pipeline </forecastCategory >

<probability >10 </probability >

</picklistValues >

<picklistValues >

<fullName >Needs Analysis </fullName >

272

Metadata Types RecordType

<default >false </default >

<forecastCategory >Pipeline </forecastCategory >

<probability >20 </probability >

</picklistValues >

...

</picklist >

</fields >

<CustomObject >

RecordType

Represents the metadata associated with a record type. Record types let you offer different business processes, picklist values, and page layouts to different users. For more information, see “Tailor Business Processes to Different Users” in the Salesforce online help. Use this

metadata type to create, update, or delete record type definitions for a custom object. This type extends the Metadata

metadata type and inherits its fullName

field.

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

Record types are available in API version 12.0 and later.

Fields

Field

active businessProcess

Field Type

boolean string compactLayoutAssignment string description fullName string string

Description

Required. Indicates whether or not the record type is active.

The fullName

of the business process associated with the record type. This field is required in record types for lead, opportunity, solution, and case, and not allowed otherwise.

See BusinessProcess

on page 246.

This field is available in API version 17.0 and later.

Represents the compact layout that is assigned to the record type.

This field is available in API version 29.0 and later.

Record type description. Maximum of 255 characters.

Record type name. 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.

If this field contained characters before version 14.0 that are no longer allowed, the characters were stripped out of this field, and the previous value of the field was saved in the

label

field.

273

Metadata Types RecordType

Field

label picklistValues

Field Type

string

RecordTypePicklistValue

[]

Description

Inherited from the Metadata component, this field is not

defined in the WSDL for this component. It must be specified

when creating, updating, or deleting. See create()

to

see an example of this field specified for a call.

This value cannot be null

.

Required. Descriptive label for the record type. The list of

characters allowed in the fullName

field has been reduced for versions 14.0 and later. This field contains the value contained in the

fullName

field before version 14.0.

Represents a set of values for a picklist.

RecordTypePicklistValue

RecordTypePicklistValue represents the combination of picklists and valid values that define a record type:

Field Name

picklist values

Field Type

string

PicklistValue

Description

Required. The name of the picklist.

One or more of the picklist values in the picklist. Each value defined is available in the record type that contains this component.

Java Sample

The following sample uses two record types. For the complete sample that includes profiles and picklists, see

Profile on page 496.

public void recordTypeSample() { try {

// Employees and managers have different access

// to the state of the expense sheet

RecordType edit = new RecordType(); edit.setFullName( "ExpenseReport__c.Edit" ); edit.setLabel( "ExpenseReport__c.Label" );

PicklistValue unsubmitted = new PicklistValue(); unsubmitted.setFullName( "Unsubmitted" );

PicklistValue submitted = new PicklistValue(); submitted.setFullName( "Submitted" );

RecordTypePicklistValue editStatuses = new RecordTypePicklistValue(); editStatuses.setPicklist( "ExpenseStatus__c" ); editStatuses.setValues( new PicklistValue[] {unsubmitted, submitted}); edit.setPicklistValues( new RecordTypePicklistValue[] {editStatuses});

AsyncResult[] arsEdit = metadataConnection.create( new Metadata[] {edit});

274

Metadata Types SearchLayouts

}

RecordType approve = new RecordType(); approve.setFullName( "ExpenseReport__c.Approve" );

PicklistValue approved = new PicklistValue(); approved.setFullName( "Approved" );

PicklistValue rejected = new PicklistValue(); rejected.setFullName( "Rejected" );

RecordTypePicklistValue approveStatuses = new RecordTypePicklistValue(); approveStatuses.setPicklist( "ExpenseStatus__c" ); approveStatuses.setValues( new PicklistValue[] {approved, rejected}); approve.setPicklistValues( new RecordTypePicklistValue[] {approveStatuses});

AsyncResult[] arsApprove = metadataConnection.create( new Metadata[] {approve});

} catch (ConnectionException ce) { ce.printStackTrace();

}

Declarative Metadata Sample Definition

The definition of a record type in a custom object is shown below:

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

. . .

<recordTypes >

<fullName >My First Recordtype </fullName >

</recordTypes >

. . .

</CustomObject >

SearchLayouts

Represents the metadata associated with the Search Layouts for an object. You can customize which fields to display for users in search results, search filter fields, lookup dialogs, and recent record lists on tab home pages.

For more information, see ”Customize Search Layouts” and ”Customize Search Layouts for Custom Objects” in the Salesforce online help.

Version

Search layouts for custom objects are available in API version 14.0 and later. The ability to modify search layouts for standard objects

(except events and tasks) is available in API version 27.0 and later.

Fields

Field

customTabListAdditionalFields

Field Type

string[]

Description

The list of fields displayed in the Recent

Object Name

list view on a tab associated with the object. The name

field

275

Metadata Types

Field

excludedStandardButtons listViewButtons lookupDialogsAdditionalFields lookupFilterFields

Field Type

string[] string[] string[] string[]

SearchLayouts

Description

is mandatory and is always displayed as the first column header, so it is not included in this list; all additional fields are included. The field name relative to the object name, for example

MyCustomField__c

, is specified for each custom field.

The list of standard buttons excluded from the search layout.

The list of buttons available in list views for an object.

This field is equivalent to the Buttons Displayed value in the

Object Name List View

in the Search Layouts related list on the object detail page in the Salesforce user interface. For more information, see “Standard and Enhanced

Lookups in Salesforce Classic” in the Salesforce online help.

The list of fields displayed in a lookup dialog for the object.

The name

field is mandatory and is always displayed as the first column header, so it is not included in this list; all additional fields are included. The field name relative to the object name, for example

MyCustomField__c

, is specified for each custom field.

Salesforce objects often include one or more lookup fields that allow users to associate two records together in a relationship. For example, a contact record includes an

Account

lookup field that represents the relationship between the contact and the organization with which the contact is associated. A lookup search dialog helps you search for the record associated with the one being edited. Lookup filter fields allow you to filter your lookup search by a customized list of fields in the object.

This field is equivalent to the

Lookup Dialogs

in the

Search Layouts related list on the object detail page in the application user interface. For more information, see

“Standard and Enhanced Lookups in Salesforce Classic” in the Salesforce online help.

The list of fields that can be used to filter enhanced lookups for an object. Enhanced lookups are optionally enabled by your administrator. The field name relative to the object name, for example

MyCustomField__c

, is specified for each custom field.

This field is equivalent to the

Lookup Filter Fields in the Search Layouts related list on the object detail page in the application user interface. For more information, see

“Standard and Enhanced Lookups in Salesforce Classic” in the Salesforce online help.

276

Metadata Types SearchLayouts

Field Field Type

lookupPhoneDialogsAdditionalFields string[] searchFilterFields string[] searchResultsAdditionalFields string[] searchResultsCustomButtons string[]

Description

The list of phone-related fields displayed in a lookup dialog for the object. The name

field is mandatory and is always displayed as the first column header, so it is not included in this list; all additional fields are included. The field name relative to the object name, for example

MyCustomField__c

, is specified for each custom field.

This list enables integration of the fields with a SoftPhone dial pad. For more information, see “About CTI 1.0 and 2.0

SoftPhones” in the Salesforce online help.

This field is equivalent to the

Lookup Phone Dialogs in the Search Layouts related list on the object detail page in the application user interface.

The list of fields that can be used to filter a search for the object. The field name relative to the object name, for example

MyCustomField__c

, is specified for each custom field.

This field is equivalent to the

Search Filter Fields in the Search Layouts related list on the object detail page in the application user interface.

The list of fields displayed in a search result for the object.

The name

field is mandatory and is always displayed as the first column header, so it is not included in this list; all additional fields are included. The field name relative to the object name, for example

MyCustomField__c

, is specified for each custom field.

This field is equivalent to the

Search Results

in the

Search Layouts related list on the object detail page in the application user interface.

The list of custom buttons available in a search result for the object. The actions associated with the buttons can be applied to any of the records returned in the search result.

Declarative Metadata Sample Definition

A sample definition of search layouts in an object is shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

. . .

<searchLayouts >

<listViewButtons >New </listViewButtons >

<listViewButtons >Accept </listViewButtons >

<listViewButtons >ChangeOwner </listViewButtons >

277

Metadata Types SharingReason

<lookupDialogsAdditionalFields >firstQuote__c </lookupDialogsAdditionalFields >

<lookupDialogsAdditionalFields >finalQuote__c </lookupDialogsAdditionalFields >

<searchResultsAdditionalFields >CREATEDBY_USER </searchResultsAdditionalFields >

</searchLayouts >

. . .

</CustomObject >

SEE ALSO:

CustomObject

SharingReason

Represents an Apex sharing reason, which is used to indicate why sharing was implemented for a custom object. Apex managed sharing allows developers to use Apex to programmatically share custom objects. When you use Apex managed sharing to share a custom object, only users with the “Modify All Data” permission can add or change the sharing on the custom object's record, and the sharing access is maintained across record owner changes. For more information, see “Sharing Settings” in the Salesforce online help.

Use SharingReason to create, update, or delete sharing reason definitions for a custom object. This type extends the

Metadata metadata

type and inherits its fullName

field.

Version

Sharing reasons are available in API version 14.0 and later.

Fields

Field

fullName

Field Type

string label string

Description

Required. Sharing reason name. The __c suffix is appended to custom sharing reasons.

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.

Required. Descriptive label for the sharing reason. Maximum of 40 characters.

Declarative Metadata Sample Definition

The definition of a sharing reason in a custom object:

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

. . .

<sharingReasons >

278

Metadata Types SharingRecalculation

<fullName >recruiter__c </fullName >

<label >Recruiter </label >

</sharingReasons >

. . .

</CustomObject >

SharingRecalculation

Represents Apex classes that recalculate the Apex managed sharing for a specific custom object. For more information, see “Recalculate

Apex Managed Sharing” in the Salesforce online help.

Version

Sharing recalculations are available in API version 14.0 and later.

Fields

Field

className

Field Type

string

Description

Required. The Apex class that recalculates the Apex sharing for a custom object. This class must implement the

Database.Batchable

interface.

Declarative Metadata Sample Definition

The definition of a sharing recalculation in a custom object:

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

. . .

<sharingRecalculations >

<className >RecruiterRecalculation </className >

</sharingRecalculations >

. . .

</CustomObject >

ValidationRule

Represents a validation rule, which is used to verify that the data a user enters in a record is valid and can be saved. A validation rule contains a formula or expression that evaluates the data in one or more fields and returns a value of true

or false

. Validation rules also include an error message that your client application can display to the user when the rule returns a value of true

due to invalid

data. This type extends the Metadata

metadata type and inherits its fullName

field.

As of API version 20.0, validation rules can't have compound fields. Examples of compound fields include addresses, first and last names, dependent picklists, and dependent lookups.

Version

Validation rules are available in API version 12.0 and later.

279

Metadata Types

Fields

Field Name

active errorDisplayField errorMessage fullName

Field Type

boolean description errorConditionFormula string string string string string

ValidationRule

Description

Required. Indicates whether this validation rule is active, ( true

), or not active ( false

).

A description of the validation rule.

Required. The formula defined in the validation rule. If the formula returns a value of true

, an error message is displayed.

See “Define Validation Rules” in the Salesforce online help.

The fully specified name of a field in the application. If a value is supplied, the error message appears next to the specified field. If you do not specify a value or the field isn’t visible on the page layout, the value changes automatically to

Top of Page

.

Required. The message that appears if the validation rule fails. The message must be 255 characters or less.

The internal name of the object. White spaces and special characters are escaped for validity. The name must:

•

Contain characters, letters, or the underscore (_) character

•

Must start with a letter

•

Can’t end with an underscore

•

Can't contain two consecutive underscore characters.

Inherited from the

Metadata component, this field is not defined in the

WSDL for this component. It must be specified when creating, updating,

or deleting. See create()

to see an example of this field specified for a call.

Declarative Metadata Sample Definition

A sample XML definition of a validation rule in a custom object is shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

<deploymentStatus >Deployed </deploymentStatus >

<fields >

<fullName >Mommy_Cat__c </fullName >

<label >Mommy Cat </label >

<referenceTo >Cat__c </referenceTo >

<relationshipName >Cats </relationshipName >

<type >Lookup </type >

</fields >

<label >Cat </label >

<nameField >

<label >Cat Name </label >

<type >Text </type >

280

Metadata Types

</nameField >

<pluralLabel >Cats </pluralLabel >

<sharingModel >ReadWrite </sharingModel >

<validationRules >

<fullName >CatsRule </fullName >

<active >true </active >

<errorConditionFormula >OR(Name = &apos;Milo&apos;,Name =

&apos;Moop&apos;) </errorConditionFormula >

<validationMessage >Name must be that of one of my cats </validationMessage >

</validationRules >

</CustomObject >

WebLink

Represents a custom button or link defined in a custom object. This type extends the Metadata

metadata type and inherits its fullName field.

Version

WebLinks are available in API version 12.0 and later.

Fields

Field Name

availability description displayType encodingKey

Field Type

WebLinkAvailability

( enumeration

of type string) string

WebLinkDisplayType

( enumeration

of type string)

Description

Required. Indicates whether the button or link is only available online

( online

, or if it is also available offline ( offline

).

A description of the button or link.

Represents how ththe button or link is rendered. Valid values are:

•

link

for a hyperlink

•

button

for a button

•

massAction

for a button attached to a related list

Encoding ( enumeration

of type string)

Required. The default encoding setting is Unicode:

UTF-8

. Change it if your template requires data in a different format. This is available if your content source is URL.

Valid values include:

•

UTF-8

—Unicode (UTF-8)

•

ISO-8859-1

—General US & Western Europe (ISO-8859–1,

ISO-LATIN-1)

•

Shift_JIS

—Japanese (Shift-JIS)

•

ISO-2022-JP

—Japanese (JIS)

•

EUC-JP

—Japanese (EUC-JP)

•

x-SJIS_0213

—Japanese (Shift-JIS_2004)

•

ks_c_5601-1987

—Korean (ks_c_5601-1987)

WebLink

281

Metadata Types

Field Name

fullName hasMenubar hasScrollbars hasToolbar height isResizable linkType masterLabel

Field Type Description

•

Big5

—Traditional Chinese (Big5)

•

GB2312

—Simplified Chinese (GB2312)

•

Big5-HKSCS

—Traditional Chinese Hong Kong (Big5–HKSCS) string The name of the custom button or link with white spaces and special characters escaped for validity. 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.

Inherited from the Metadata component, this field is not defined in the

WSDL for this component. It must be specified when creating, updating, or deleting. See

create()

to see an example of this field specified for a call.

boolean boolean boolean int boolean

WebLinkType (

enumeration of

type string)

If the openType

is

newWindow

, this field indicates whether to show the browser menu bar for the window ( true

) or not ( false

).

Otherwise, leave this field empty.

If the openType

is

newWindow

, this field indicates whether to show the scroll bars for the window ( true

) or not ( false

). Otherwise, leave this field empty.

If the openType

is

newWindow

, this field indicates whether to show the browser toolbar for the window ( true

) or not ( false

). Otherwise, leave this field empty.

Height in pixels of the window opened by the custom button or link.

Required if the openType

is newWindow

. Otherwise, leave this field empty.

If the openType

is

newWindow

, this field indicates whether to allow resizing of the window ( true

) or not ( false

). Otherwise, leave this field empty.

Required. Represents whether the content of the button or link is specified by a URL, an sControl, a JavaScript code block, or a Visualforce page.

•

url

•

sControl

•

javascript

•

page

•

flow

—Reserved for future use.

string Master label for this object. This display value is the internal label that is not translated.

WebLink

282

Metadata Types

Field Name

openType page position protected requireRowSelection scontrol showsLocation showsStatus url

Field Type

WebLinkWindowType

( enumeration

of type string)

Description

Required. When the button or link is clicked, specifies the window style that will be used to display the content. Valid values:

•

newWindow

•

sidebar

•

noSidebar

•

replace

•

onClickJavaScript string

WebLinkPosition (

enumeration

of type string)

If the value of linkType

is

page

, this field represents the Visualforce page. Otherwise, leave this field empty.

If the value of

OpenType

is newWindow

, this field indicates how the new window should be displayed. Otherwise, don’t specify a value.

Valid values are:

•

fullScreen

•

none

•

topLeft boolean boolean string boolean boolean string

Required. Indicates whether this sub-component is protected ( true

) or not ( false

). Protected sub-components can’t be linked to or referenced by components or sub-components created in the installing organization.

If the

openType

is massAction

, this field indicates whether to require individual row selection to execute the action for this button

( true

) or not ( false

). Otherwise, leave this field empty.

If the value of

linkType

is sControl

, this field represents the name of the sControl. Otherwise, leave this field empty.

If the openType

is

newWindow

, this field indicates whether to show the browser location bar for the window ( true

) or not ( false

).

Otherwise, leave this field empty.

If the

openType

is newWindow

, this field indicates whether or not to show the browser status bar for the window. Otherwise, leave this field empty.

If the value of

linkType

is url

, this is the URL value. If the value of

linkType

is

javascript

, this is the JavaScript content. If the value is neither of these, leave this field empty.

Content must be escaped in a manner consistent with XML parsing rules.

width int Width in pixels of the window opened by the button or link.

Required if the openType

is newWindow

. Otherwise, leave this field empty.

WebLink

283

Metadata Types WebLink

Java Sample

The following Java sample shows sample values for WebLink fields: public void WebLinkSample(String name) throws Exception {

WebLink WebLink = new WebLink();

// name variable represents the full name of the object

// on which to create the WebLink, for example, customObject__c

WebLink.setFullName(name + ".googleButton" );

WebLink.setUrl( "http://www.google.com" );

WebLink.setAvailability(WebLinkAvailability.online);

WebLink.setLinkType(WebLinkType.url);

WebLink.setEncodingKey(Encoding.fromString( "UTF-8" ));

WebLink.setOpenType(WebLinkWindowType.newWindow);

WebLink.setHeight(600);

WebLink.setWidth(600);

WebLink.setShowsLocation(false);

WebLink.setHasScrollbars(true);

WebLink.setHasToolbar(false);

WebLink.setHasMenubar(false);

WebLink.setShowsStatus(false);

WebLink.setIsResizable(true);

WebLink.setPosition(WebLinkPosition.none);

WebLink.setMasterLabel( "google" );

WebLink.setDisplayType(WebLinkDisplayType.link);

AsyncResult[] asyncResults = metadataConnection.create( new WebLink[]{WebLink});

// After the create() call completes, we must poll the results of checkStatus()

//

}

Declarative Metadata Sample Definition

The following is the definition of a WebLink in a custom object. For related samples, see HomePageComponent and

HomePageLayout .

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObject xmlns= "http://soap.sforce.com/2006/04/metadata">

....

<WebLinks >

<fullName >googleButton </fullName >

<availability >online </availability >

<displayType >link </displayType >

<encodingKey >UTF-8 </encodingKey >

<hasMenubar >false </hasMenubar >

<hasScrollbars >true </hasScrollbars >

<hasToolbar >false </hasToolbar >

<height >600 </height >

<isResizable >true </isResizable >

<linkType >url </linkType >

<masterLabel >google </masterLabel >

<openType >newWindow </openType >

<position >none </position >

<protected >false </protected >

284

Metadata Types Metadata Field Types

<showsLocation >false </showsLocation >

<showsStatus >false </showsStatus >

<url >http://www.google.com

</url >

<width >600 </width >

....

</WebLinks >

</CustomObject >

SEE ALSO:

HomePageComponent

HomePageLayout

CustomPageWebLink

Metadata Field Types

These field types extend the field types described in the

SOAP API Developer's Guide

.

Field Type

CustomField

DeleteConstraint

DeploymentStatus

FieldType

Objects

Custom object

Custom field

What the Field Contains

Represents a custom field.

Custom field A string that represents deletion options for lookup relationships. Valid values are:

•

SetNull

•

Restrict

•

Cascade

Custom object

Custom field

A string which represents the deployment status of a custom object or field. Valid values are:

•

InDevelopment

•

Deployed

Custom field Indicates the type of a custom field. Valid values are:

•

AutoNumber

•

Lookup

•

MasterDetail

•

MetadataRelationship

•

Checkbox

•

Currency

•

Date

•

DateTime

•

Email

•

EncryptedText

285

Metadata Types

Field Type

Gender

Metadata Field Types

Objects What the Field Contains

Custom object

Note: This page is about Classic Encryption, not Shield Platform

Encryption. What's the difference?

•

ExternalLookup

•

IndirectLookup

•

Number

1

•

Percent

•

Phone

•

Picklist

•

MultiselectPicklist

•

Summary

•

Text

•

TextArea

•

LongTextArea

•

Summary

•

Url

•

Hierarchy

•

File

•

CustomDataType

•

Html

•

Geolocation

1

A

Number

custom field is internally represented as a field of type double.

Setting the scale of the

Number

field to 0 gives you a double that behaves like an int.

Indicates the gender of the noun that represents the object. This is used for languages where words need different treatment depending on their gender.

Valid values are:

•

Masculine

•

Feminine

•

Neuter

•

AnimateMasculine

(Slavic languages—currently Czech, Polish, Russian,

Slovak, Slovenian, and Ukrainian)

Note:

The following genders are displayed on the Rename Tabs and

Labels page in Setup but are stored internally as “Feminine”. When setting them through the Metadata API, use “Feminine”.

•

Euter (Swedish)

•

Common (Dutch)

286

Metadata Types Metadata Field Types

Field Type

Picklist (Including Dependent

Picklist)

SharingModel

StartsWith

TreatBlanksAs

ValueSet

Objects

Custom field

Custom object

What the Field Contains

(This field type isn’t used in Metadata API. CustomField includes this field type for

Tooling API support). Represents a picklist, a set of labels and values that can be selected from a picklist.

Represents the sharing model for the custom object. Depending on the object, valid values are:

•

Private

•

Read

•

ReadWrite

•

ReadWriteTransfer

•

FullAccess

•

ControlledByParent

For example, the User object supports

Private

and

Read

values. Accounts, opportunities, and custom objects support

Private

,

Read

and

ReadWrite values.

Custom object

Custom field

Indicates whether the noun starts with a vowel, consonant, or is a special character.

This is used for languages where words need different treatment depending on the first character. Valid values are:

•

Consonant

•

Vowel

•

Special (for nouns starting with z, or s plus consonants)

Custom field

Custom field

Indicates how blanks should be treated. Valid values are:

•

BlankAsBlank

•

BlankAsZero

Represents a set of values that can be selected from a custom picklist field. Defines the valueSet of a the custom picklist field.

ValueSet

Represents a set of values that can be selected from a custom picklist field. Defines the valueSet of a the custom picklist field.

Field Type

controllingField restricted

Field Type

string boolean

Description

The fullname

of the controlling field if this is a dependent picklist. A controlling field can be a checkbox or picklist field, but in this case it’s a picklist.

The controlling picklist filters the available values in the dependent picklist.

Whether the picklist’s values are limited to only the values defined by a

Salesforce admin. Values are true

or false

.

287

Metadata Types CustomObjectTranslation

Field Type Field Type Description

valueSetDefinition

ValueSetValuesDefinition Defines value-specific settings for a custom dependent picklist. Indicates whether the value set of the custom picklist field is sorted alphabetically.

valueSetName valueSettings string

ValueSettings

The masterLabel

of the global value set to be used for this picklist field.

Used for the settings that describe a value in a custom picklist field. The picklist can have its own unique value set, or inherit the values from a global value set.

ValueSetValuesDefinition

Field Name

sorted

Field Type

boolean value

CustomValue

Description

Whether the picklist’s value set is displayed in alphabetical order in the user interface.

Required. The list of values for this local, custom picklist.

ValueSettings

Field Name Field Type

controllingFieldValue string[] valueName string

Description

Applies only to dependent custom picklists. A list of values in the controlling or parent picklist (that the custom picklist values depend on).

Defines the values in the custom dependent picklist.

CustomObjectTranslation

This metadata type allows you to translate custom objects for a variety of languages. This type extends the Metadata

metadata type and inherits its fullName

field. The ability to translate component labels is part of the Translation Workbench. For more information, see

“Enable and Disable the Translation Workbench” in the Salesforce online help.

Declarative Metadata File Suffix and Directory Location

Translations are stored in a file with a format of

customObjectName__c-lang.objectTranslation

, where

customObjectName__c

is the custom object name, and

lang

is the translation language. A sample file name for German translations is myCustomObject__c-de.objectTranslation

.

Custom object translations are stored in the objectTranslations

folder in the corresponding package directory.

Version

CustomObjectTranslation components are available in API version 14.0 and later.

288

Metadata Types

Fields

Field

caseValues fields fullName gender layouts nameFieldLabel namedFilters quickActions recordTypes sharingReasons startsWith validationRules webLinks workflowTasks

CustomObjectTranslation

Field Type

ObjectNameCaseValue

CustomFieldTranslation

string

Gender

LayoutTranslation

string

[]

NamedFilterTranslation

[]

[]

[]

Description

Different combinations of the custom object with regard to article, plural, possessive, and case.

A list of translations for the custom fields associated with the custom object.

The name of the custom object and the translation language with a format of

customObjectName

-

lang

, where

customObjectName

is the custom object name, and

lang

is the translation language.

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.

Indicates the gender of the noun that represents the object. This is used for languages where words need different treatment depending on their gender.

A list of page layout translations.

The label for the name field. Maximum of 765 characters.

A list of translations for lookup filter error messages associated with the custom object.

This field has been removed as of API version 30.0 and is only available in prior versions. The translation metadata associated with a lookup filter is now represented by the lookupFilter field in the CustomFieldTranslation subtype.

QuickActionTranslation

[]

RecordTypeTranslation

[]

WebLinkTranslation

[]

WorkflowTaskTranslation

[]

A list of translations for actions.

A list of record type translations.

SharingReasonTranslation

[] A list of sharing reason translations.

StartsWith

(

enumeration

of type string)

Indicates whether the noun starts with a vowel, consonant, or is a special character. This is used for languages where words need different treatment depending on the first character.

ValidationRuleTranslation []

A list of validation rule translations.

A list of web link translations.

A list of workflow task translations.

289

Metadata Types CustomObjectTranslation

CustomFieldTranslation

CustomFieldTranslation contains details for a custom field translation. In API versions 37.0 and earlier standard picklist values could be

translated with CustomFieldTranslation. In API version 38.0, use StandardValueSetTranslation instead. For more details, see CustomField .

Note:

Not every language supports all the possible values for the fields in CustomFieldTranslation. For language-specific supported

values, see the fully supported languages

and

end-user languages

appendices.

Field

caseValues description gender help label lookupFilter name picklistValues relationshipLabel startsWith

Field Type

ObjectNameCaseValue

string

Gender

string string

LookupFilterTranslation

[]

Description

Different combinations of the custom object with regard to article, plural, possessive, and case. Available in API version 29.0

and later.

Translation for the custom field description.

Indicates the gender of the noun that represents the object. This is used for languages where words need different treatment depending on their gender. Available in API version 29.0 and later.

Translation for the text that displays in the field-level help hover text for this field.

Translation for the label. Maximum of 765 characters.

Represents the translation metadata associated with a lookup filter.

This field is available in API version 30.0 and later.

Note: LookupFilter is not supported on the article type object.

string

PicklistValueTranslation []

Required. The name of the field relative to the custom object; for example,

MyField__c

.

List of translations for picklist values. See

PicklistValue .

Note: “Subject” on the Task object is a text field, not a picklist value. It can’t be retrieved via the Metadata API. Translations can be provided via the Translation Workbench.

string Translation for a lookup relationship label. A lookup relationship allows a field to be associated with another field. The relationship field allows users to select an option from a list of values defined by the other field. Maximum of 765 characters.

StartsWith

(

enumeration

of type string)

Indicates whether the noun starts with a vowel, consonant, or is a special character. This is used for languages where words need different treatment depending on the first character.

Available in API version 29.0 and later.

290

Metadata Types

LayoutTranslation

LayoutTranslation contains details for a page layout translation. For more details, see Fields

.

Field

layout layoutType sections

Field Type

string string

LayoutSectionTranslation

[]

Description

Required. The layout name.

An array of layout section translations.

CustomObjectTranslation

LayoutSectionTranslation

LayoutSectionTranslation contains details for a page layout section translation. For more details, see

LayoutSection .

Field

label section

Field Type

string string

Description

Required. Translation for the label. Maximum of 765 characters.

Required. The section name.

LookupFilterTranslation

LookupFilterTranslation shows a translation for a lookup filter error message associated with the custom object. Replaces

NamedFilterTranslation.

LookupFilterTranslation is available in API version 30.0 and later.

Field

errorMessage informationalMessage

Field Type

string string

Description

The error message that appears if the lookup filter fails.

The information message displayed on the page. Use to describe things the user might not understand, such as why certain items are excluded in the lookup filter.

NamedFilterTranslation

NamedFilterTranslation has been removed as of API version 30.0 and is only available in previous API versions.

NamedFilterTranslation shows a list of translations for lookup filter error messages associated with the custom object. See

NamedFilter

for more information.

Field

errorMessage informationalMessage

Field Type

string string

Description

The error message that appears if the lookup filter fails.

The information message displayed on the page. Use to describe things the user might not understand, such as why certain items are excluded in the lookup filter.

291

Metadata Types CustomObjectTranslation

Field

name

Field Type

string

Description

Required. The name of the lookup filter. If you create this field in the user interface, a name is automatically assigned. If you create this field through Metadata API, you must include the name

field.

ObjectNameCaseValue

ObjectNameCaseValue supports multiple cases and definitions of the custom object name to allow usage in various grammatical contexts.

Note:

Not every language supports all the possible values for the fields in ObjectNameCaseValue. For language-specific supported

values, see the fully supported languages

and

end-user languages

appendices.

Field

article caseType

Field Type

Article ( enumeration

of type string)

Description

English has two types of articles: definite (

the

) and indefinite

(

a

,

an

). The usage of these articles depends mainly on whether you are referring to any member of a group, or to a specific member of a group. The valid values are:

•

Definite

•

Indefinite

•

None

CaseType (

enumeration of type

string)

The case of the custom object name. The valid values are:

•

Ablative

•

Accusative

•

Adessive

•

Allative

•

Causalfinal

•

Dative

•

Delative

•

Distributive

•

Elative

•

Essive

•

Essiveformal

•

Genitive

•

Illative

•

Inessive

•

Instrumental

•

Lative

•

Locative

•

Nominative

•

Objective

292

Metadata Types CustomObjectTranslation

Field

plural possessive value

Field Type Description

•

Partitive

•

Prepositional

•

Subjective

•

Sublative

•

Superessive

•

Termanative

•

Translative

•

Vocative boolean Indicates whether the

value

field is plural (

true

) or singular

( false

).

Possessive (

enumeration

of type string)

The possessive case of a language is a grammatical case used to indicate a relationship of possession.The valid values are:

•

First

•

None

•

Second string Required. The value or label in this grammatical context.

PicklistValueTranslation

PicklistValueTranslation contains details for translation of a picklist value from a local, custom picklist field. For more details, see Picklist

(Including Dependent Picklist) .

Field

masterLabel translation

Field Type

string string

Description

Required. The picklist value defined on the setup page in the application is your master label. The master label is displayed wherever a translated label is not available.

Required. Translation for the value.

QuickActionTranslation

QuickActionTranslation contains details for an action label in the user interface. For more information, see QuickAction .

Field

label name

Field Type

string string

Description

Required. Translation for the label. Maximum of 765 characters.

Required. The quick action name.

293

Metadata Types CustomObjectTranslation

RecordTypeTranslation

RecordTypeTranslation contains details for a record type name translation. For more details, see

RecordType .

Field

label name

Field Type

string string

Description

Required. Translation for the label. Maximum of 765 characters.

Required. The record type name.

SharingReasonTranslation

SharingReasonTranslation contains details for a sharing reason translation. For more details, see SharingReason

.

Field

label name

Field Type

string string

Description

Required. Translation for the sharing reason.

Required. The sharing reason name.

ValidationRuleTranslation

ValidationRuleTranslation contains details for a validation rule translation. For more details, see ValidationRule

.

Field

errorMessage name

Field Type

string string

Description

Required. Translation for the error message associated with the validation rule failure.

Required. The validation rule name.

WebLinkTranslation

WebLinkTranslation contains details for a web link translation. For more details, see WebLink

.

Field

label name

Field Type

string string

Description

Required. Translation for the web link label. Maximum of 765 characters.

Required. The web link name.

WorkflowTaskTranslation

WorkflowTaskTranslation contains details for a workflow task translation. For more details, see

Workflow

.

Field

description

Field Type

string

Description

Translation for the workflow task description.

294

Metadata Types CustomObjectTranslation

Field

name subject

Field Type

string string

Description

Required. The workflow task name.

Translation for the workflow task subject.

Declarative Metadata Sample Definitions

This is a sample XML definition of a CustomObjectTranslation for the Description__c object in German, with one custom field, Summary__c.

The name and location of the file containing this definition would be objectTranslations/Description__c-de.objectTranslation

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObjectTranslation xmlns= "http://soap.sforce.com/2006/04/metadata">

<caseValues >

<caseType >Nominative </caseType >

<plural >false </plural >

<value >Beschreibung </value >

</caseValues >

<caseValues >

<caseType >Nominative </caseType >

<plural >true </plural >

<value >Beschreibungen </value >

</caseValues >

<caseValues >

<caseType >Accusative </caseType >

<plural >false </plural >

<value >Beschreibung </value >

</caseValues >

<caseValues >

<caseType >Accusative </caseType >

<plural >true </plural >

<value >Beschreibungen </value >

</caseValues >

<caseValues >

<caseType >Genitive </caseType >

<plural >false </plural >

<value >Beschreibung </value >

</caseValues >

<caseValues >

<caseType >Genitive </caseType >

<plural >true </plural >

<value >Beschreibungen </value >

</caseValues >

<caseValues >

<caseType >Dative </caseType >

<plural >false </plural >

<value >Beschreibung </value >

</caseValues >

<caseValues >

<caseType >Dative </caseType >

<plural >true </plural >

<value >Beschreibungen </value >

295

Metadata Types CustomObjectTranslation

</caseValues >

<fields >

<label >Zusammenfassung </label >

<name >Summary__c </name >

</fields >

<gender >Feminine </gender >

<nameFieldLabel >Beschreibungen </nameFieldLabel >

</CustomObjectTranslation >

This is a sample XML definition of a CustomObjectTranslation for the Account object, renaming Account to Client (Kunde) in German.

The Account object has one standard field, account_number, and one custom field, Account_Code__c. The name and location of the file containing this definition would be objectTranslations/Account-de.objectTranslation

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomObjectTranslation xmlns= "http://soap.sforce.com/2006/04/metadata">

<caseValues >

<caseType >Nominative </caseType >

<plural >false </plural >

<value >Kunde </value >

</caseValues >

<caseValues >

<caseType >Nominative </caseType >

<plural >true </plural >

<value >Kunden </value >

</caseValues >

<caseValues >

<caseType >Accusative </caseType >

<plural >false </plural >

<value >Kunden </value >

</caseValues >

<caseValues >

<caseType >Accusative </caseType >

<plural >true </plural >

<value >Kunden </value >

</caseValues >

<caseValues >

<caseType >Genitive </caseType >

<plural >false </plural >

<value >Kunden </value >

</caseValues >

<caseValues >

<caseType >Genitive </caseType >

<plural >true </plural >

<value >Kunden </value >

</caseValues >

<caseValues >

<caseType >Dative </caseType >

<plural >false </plural >

<value >Kunden </value >

</caseValues >

<caseValues >

<caseType >Dative </caseType >

<plural >true </plural >

<value >Kunden </value >

</caseValues >

296

Metadata Types CustomPageWebLink

<fields >

<caseValues >

<caseType >Nominative </caseType >

<plural >false </plural >

<value >Kundennummer </value >

</caseValues >

<caseValues >

<caseType >Nominative </caseType >

<plural >true </plural >

<value >Kundennummern </value >

</caseValues >

<gender >Feminine </gender >

<name >account_number </name >

</fields >

<fields >

<label >Kunden-Code </label >

<name >Account_Code__c </name >

</fields >

<gender >Masculine </gender >

</CustomObjectTranslation >

SEE ALSO:

CustomObject

Translations

CustomPageWebLink

Represents a custom link defined in a home page component. This type extends the Metadata

metadata type and inherits its fullName

field. All other custom links are stored as a WebLink in a

CustomObject

.

Declarative Metadata File Suffix and Directory Location

There is one file per custom link definition, stored in the weblinks

folder in the corresponding package directory. The file suffix is

.weblink

.

Version

CustomPageWebLinks are available in API version 13.0 and later.

Fields

Field Name

availability description

Field Type

WebLinkAvailability

(

enumeration

of type string) string

Description

Required. Indicates whether the link is only available online ( online

, or if it is also available offline ( offline

).

A description of the link.

297

Metadata Types CustomPageWebLink

Field Name

displayType encodingKey fullName hasMenubar hasScrollbars hasToolbar height isResizable

Field Type

WebLinkDisplayType

(

enumeration

of type string)

Description

Represents how this link is rendered.

Valid values:

•

link

for a hyperlink

•

button

for a button

•

massAction

for a button attached to a related list

Encoding ( enumeration

of type string)

Required. The default encoding setting is Unicode:

UTF-8

. Change it if your template requires data in a different format. This is available if your content source is URL.Valid values include:

•

UTF-8

—Unicode (UTF-8)

•

ISO-8859-1

—General US & Western Europe (ISO-8859–1,

ISO-LATIN-1)

•

Shift_JIS

—Japanese (Shift-JIS)

•

ISO-2022-JP

—Japanese (JIS)

•

EUC-JP

—Japanese (EUC-JP)

•

x-SJIS_0213

—Japanese (Shift-JIS_2004)

•

ks_c_5601-1987

—Korean (ks_c_5601-1987)

•

Big5

—Traditional Chinese (Big5)

•

GB2312

—Simplified Chinese (GB2312)

•

Big5-HKSCS

—Traditional Chinese Hong Kong (Big5–HKSCS) string boolean boolean boolean int boolean

The 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.

If the openType

is

newWindow

, this field indicates whether to show the browser menu bar for the window ( true

or not ( false

). Otherwise, leave this field empty.

If the openType

is

newWindow

, this field indicates whether to show the scroll bars for the window ( true

) or not ( false

). Otherwise, leave this field empty.

If the openType

is

newWindow

, this field indicates whether to show the browser toolbar for the window ( true

) or not ( false

). Otherwise, leave this field empty.

Height in pixels of the window opened by the link. Required if the

openType

is newWindow

. Otherwise, leave this field empty.

If the openType

is

newWindow

, this field indicates whether to allow resizing of the window ( true

) or not ( false

). Otherwise, leave this field empty.

298

Metadata Types CustomPageWebLink

Field Name

linkType masterLabel openType

Field Type

WebLinkType (

enumeration of

type string)

Description

Required. Represents whether the content of the button or link is specified by a URL, an sControl, a JavaScript code block, or a Visualforce page.

•

url

•

sControl

•

javascript

•

page

•

flow

—Reserved for future use.

string

WebLinkWindowType

(

enumeration

of type string)

The master label for the link.

Required. When the link is clicked, this field specifies the window style used to display the content.

Valid values are:

•

newWindow

•

sidebar

•

noSidebar

•

replace

•

onClickJavaScript page position protected requireRowSelection scontrol showsLocation string If the value of

linkType

is page

, this field represents the Visualforce page. Otherwise, leave this field empty.

WebLinkPosition ( enumeration

of type string)

If the

openType

is newWindow

, this field indicates how the new window should be displayed. Otherwise, leave this field empty.

Valid values are:

•

fullScreen

•

none

•

topLeft boolean boolean string boolean

Required. Indicates whether this component is protected ( true

) or not

( false

). Protected components cannot be linked to or referenced by components created in the installing organization.

If the openType

is massAction

, this field indicates whether to require individual row selection to execute the action for this button ( true

) or not ( false

). Otherwise, leave this field empty.

If the value of linkType

is

sControl

, this field represents the name of the sControl. Otherwise, leave this field empty.

If the

openType

is newWindow

, this field indicates whether or not to show the browser location bar for the window. Otherwise, leave this field empty.

299

Metadata Types

Field Name

showsStatus

Field Type

boolean url width string int

CustomPermission

Description

If the

openType

is newWindow

, this field indicates whether or not to show the browser status bar for the window. Otherwise, leave this field empty.

If the value of

linkType

is url

, this field represents the URL value. If

the value of linkType

is javascript

, this field represents the

JavaScript content. If the value is neither of these, leave this field empty.

Content must be escaped in a manner consistent with XML parsing rules.

Width in pixels of the window opened by the link.

Required if the

openType

is newWindow

. Otherwise, leave this field empty.

Declarative Metadata Sample Definition

The following is the definition of a Weblink. For related samples, see HomePageComponent and

HomePageLayout

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomPageWebLink xmlns= "http://soap.sforce.com/2006/04/metadata">

<availability >online </availability >

<displayType >button </displayType >

<encodingKey >UTF-8 </encodingKey

<hasMenubar >false </hasMenubar >

<hasScrollbars >true </hasScrollbars >

<hasToolbar >false </hasToolbar >

<height >600 </height >

<isResizable >true </isResizable >

<linkType >url </linkType >

<masterLabel >detailPageButon </masterLabel >

<openType >newWindow </openType >

<position >none </position >

<protected >false </protected >

<showsLocation >false </showsLocation >

<showsStatus >false </showsStatus >

<url >http://google.com

</url >

</CustomPageWebLink >

SEE ALSO:

HomePageComponent

HomePageLayout

WebLink

CustomPermission

Represents a permission that grants access to a custom feature. This type extends the Metadata

metadata type and inherits its fullName field.

300

Metadata Types CustomPermission

File Suffix and Directory Location

CustomPermission components have the suffix

.customPermission

and are stored in the customPermissions

folder.

Version

CustomPermission components are available in API version 31.0 and later.

Fields

Field Name

connectedApp description label requiredPermission

Field Type

string string string

Description

The name of the connected app that’s associated with this permission. Limit: 80 characters.

The custom permission description. Limit:

255 characters.

Required. The custom permission label.

Limit: 80 characters.

CustomPermissionDependencyRequired[]

Indicates which custom permissions are required by the parent custom permission.

This field is available in API version 32.0 and later.

CustomPermissionDependencyRequired

CustomPermissionDependencyRequired determines whether a custom permission is required by the parent custom permission. A required custom permission must be enabled when its parent is enabled.

Field Name

customPermission dependency

Field Type

string boolean

Description

Required. The custom permission name.

Required. Indicates whether this custom permission is required by the parent custom permission ( true

) or not ( false

).

Declarative Metadata Sample Definition

The following is an example of a CustomPermission component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomPermission xmlns= "http://soap.sforce.com/2006/04/metadata">

<connectedApp >Acme </connectedApp >

<description >Read and edit access for Acme accounts.

</description >

<label >Acme Account Full Access </label >

<requiredPermission >

<customPermission >Acme_Account_Read </customPermission >

301

Metadata Types CustomSite

<dependency >true </dependency >

</requiredPermission >

</CustomPermission >

The following is an example package.xml

that references the previous definition, as well as other custom permissions that are associated with a connected app.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Acme </members >

<name >ConnectedApp </name >

</types >

<types >

<members >Acme_Account_Email_Read </members >

<members >Acme_Account_Phone_Edit </members >

<members >Acme_Account_Full_Access </members >

<members >Acme_Account_Read </members >

<name >CustomPermission </name >

</types >

<types >

<members >Acme_Account_Email_Read </members >

<members >Acme_Account_Phone_Edit </members >

<members >Acme_Account_Full_Access </members >

<members >Acme_Account_Read </members >

<name >PermissionSet </name >

</types >

<version >39.0

</version >

</Package >

CustomSite

Represents a Force.com site. 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. For more information, see “Force.com

Sites” in the Salesforce online help.

Note: CustomSite does not support syndication feeds at this time.

This type extends the

Metadata metadata type and inherits its

fullName

field.

Declarative Metadata File Suffix and Directory Location

Force.com CustomSite components are stored in the sites

directory of the corresponding package directory. The file name matches the site name, and the extension is

.site

.

Version

Force.com CustomSite components are available in API version 14.0 and later.

302

Metadata Types

Fields

Field

active allowHomePage allowStandardAnswersPages allowStandardIdeasPages allowStandardLookups allowStandardPortalPages

Field Type

boolean boolean boolean boolean boolean boolean allowStandardSearch analyticsTrackingCode boolean string authorizationRequiredPage bandwidthExceededPage changePasswordPage string string string chatterAnswersForgotPasswordConfirmPage string

CustomSite

Description

Required. Determines whether or not the site is active.

Required. Determines whether or not the standard home page is visible to public users. This is a new field in API version 15.0.

Determines whether the standard answer pages are visible to public users. This is a new field in API version

19.0.

Required. Determines whether or not the standard

Ideas pages are visible to public users. This is a new field in API version 15.0.

Required. Determines whether or not the standard lookup pages are visible to public users. This is a new field in API version 15.0.

Required. When enabled, authenticated users in this site can access standard Salesforce pages as allowed by their access controls. When disabled, authenticated users in this site can't access standard Salesforce pages, even if their access controls allow it. If your site serves only Visualforce pages, disabling this setting helps add a layer of access protection to your site. This is a new field in API version 39.0.

Determines whether or not the standard search pages are visible to public users. This is a new field in API version 15.0.

The tracking code associated with your site. This code can be used by services like Google Analytics to track page request data for your site. This field is available in API version 17.0 and later.

The name of the Visualforce page to be displayed when the guest user tries to access a page for which they are not authorized.

The name of the Visualforce page to be displayed when the site has exceeded its bandwidth quota.

The name of the Visualforce page to be displayed when the portal user attempts to change his or her password for either the portal or for Chatter Answers, when enabled.

The name of the Visualforce page to be displayed that informs the user that an email has been sent to them

303

Metadata Types CustomSite

Field

chatterAnswersForgotPasswordPage chatterAnswersHelpPage chatterAnswersLoginPage chatterAnswersRegistrationPage clickjackProtectionLevel customWebAddresses description favoriteIcon

Field Type

string

Description

with a temporary password. This field is available if

Chatter Answers is enabled for your organization. This field is available in API version 27.0 and later.

The name of the Visualforce page to be displayed when a user clicks the link to retrieve a forgotten password. This field is available if Chatter Answers is enabled for your organization. This field is available in

API version 27.0 and later.

string string

The name of the Visualforce page to be displayed when the user clicks the help link. This field is available if Chatter Answers is enabled for your organization.

This field is available in API version 27.0 and later.

The name of the Visualforce page to be displayed to allow users to log in to the portal. This field is available if Chatter Answers is enabled for your organization.

This field is available in API version 27.0 and later.

string

SiteClickjackProtectionLevel

(enumeration of type string)

Required. Sets the clickjack protection level. The options are:

•

AllowAllFraming

— Allow framing by any page (no protection)

•

SameOriginOnly

— Allow framing by the same origin only (recommended)

•

NoFraming

— Don’t allow framing by any page (most protection)

This field is available in API version 30.0 and later.

SiteWebAddress[]

The name of the Visualforce page to be displayed to allow users to register themselves and access the portal. This field is available in API version 27.0 and later.

string string

The root custom URLs associated with the site. Saving or deploying a CustomSite replaces all root custom

URLs in the site with the root custom URLs in this list.

Custom URLs that use a non-root path prefix are not included in this list and are not affected when saving or deploying a CustomSite. This field is available in API version 21.0 and later.

The site description.

The name of the file to be used for the icon that appears in the browser's address field when visiting the site. Sets the favorite icon for the entire site.

304

Metadata Types

Field

fileNotFoundPage forgotPasswordPage

Field Type

string string genericErrorPage guestProfile inMaintenancePage inactiveIndexPage indexPage masterLabel portal requireHttps robotsTxtPage serverIsDown string string string boolean string string string string requireInsecurePortalAccess boolean string string

CustomSite

Description

The name of the Visualforce page to be displayed when the guest user tries to access a non-existent page.

The name of the Visualforce page to be displayed when a user clicks the Forgot Password link on the site’s login page. This field is only applicable for

Communities sites.

The name of the Visualforce page to be displayed for errors not otherwise specified.

Read only. The name of the profile associated with the guest user.

The name of the Visualforce page to be displayed when the site is down for maintenance.

The name of the Visualforce page set as the inactive site home page.

Required. The name of the Visualforce page set as the active site home page.

The name of the site label in the Salesforce user interface.

The name of the portal associated with this site for login access.

Determines whether the site requires secure connections (true) or not (false). When false, the site operates normally via insecure connections instead of redirecting to a secure connection.

Required. Determines whether to override your organization's security settings and exclusively use

HTTP when logging in to the associated portal from your site.

The name of the Visualforce page to be displayed for the robots.txt

file used by web crawlers.

The name of the static resource to be displayed from the cache server when Salesforce servers are down.

The static resource must be a public zip file 1 MB or smaller and must contain a page named maintenance.html

at the root level of the zip file. Other resources in the zip file, such as images or

CSS files, can follow any directory structure. This field is available in API version 17.0 and later.

305

Metadata Types CustomSite

Field

siteRedirectMappings siteAdmin siteTemplate siteType subdomain urlPathPrefix

Field Type

SiteRedirectMapping[] string string siteType string string

Description

An array of all URL redirect rules set for your site. This field is available in API version 20.0 and later.

The username of the site administrator.

The name of the Visualforce page to be used as the site template.

Identifies whether the site is a Visualforce (Force.com

Sites) or a Site.com site.

If Salesforce Communities is enabled for your organization, the site could also be a ChatterNetwork

(Force.com Sites) or ChatterNetworkPicasso (Site.com) site.

This is a new field in API version 27.0.

Required. Read only. The custom subdomain prefix for the site. For example, if your site URL is mycompany.force.com/partners

, mycompany.force.com

is the subdomain.

The first part of the path on the site's URL that distinguishes this site from other sites. For example, if your site URL is mycompany.force.com/partners

, partners

is the urlPathPrefix.

SiteRedirectMapping

SiteRedirectMapping represents a URL redirect rule on your Force.com site. For more information, see “Force.com Sites URL Redirects” in the Salesforce online help.

Field

action isActive source target

Field Type

SiteRedirect (

enumeration

of type string)

Description

The type of the redirect. Available string values are:

•

Permanent

•

Temporary boolean string string

The status of the redirect: active or inactive.

The URL that you want to redirect. It must be a relative URL, but can have any valid extension type, such as

.html

or

.php

.

The new URL you want users to visit. It can be a relative URL or a fully-qualified URL with an http://

or https://

prefix.

306

Metadata Types

SiteWebAddress

Represents the web address of a Force.com site.

Field

certificate

Field Type

string

CustomSite domainName primary string boolean

Description

Although this field is visible in the Metadata

API version 39.0, it’s not functional and should be left blank.

The domain of the website, in the form of www.acme.com.

Indicates whether this is the primary domain

(

true)

. If

false

, this is not the primary domain.

Declarative Metadata Sample Definition

A sample XML definition of a site is shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomSite xmlns= "http://soap.sforce.com/2006/04/metadata">

<active >true </active >

<allowHomePage >true </allowHomePage >

<allowStandardIdeasPages >true </allowStandardIdeasPages >

<allowStandardLookups >true </allowStandardLookups >

<allowStandardPortalPages >true </allowStandardPortalPages >

<allowStandardSearch >true </allowStandardSearch >

<authorizationRequiredPage >Unauthorized </authorizationRequiredPage >

<bandwidthExceededPage >BandwidthExceeded </bandwidthExceededPage >

<changePasswordPage >ChangePassword </changePasswordPage >

<chatterAnswersForgotPasswordConfirmPage >ChatterAnswersForgotPasswordConfirm </chatterAnswersForgotPasswordConfirmPage >

<chatterAnswersForgotPasswordPage >ChatterAnswersForgotPassword </chatterAnswersForgotPasswordPage >

<chatterAnswersHelpPage >ChatterAnswersHelp </chatterAnswersHelpPage >

<chatterAnswersLoginPage >ChatterAnswersLogin </chatterAnswersLoginPage >

<chatterAnswersRegistrationPage >ChatterAnswersRegistration </chatterAnswersRegistrationPage >

<clickjackProtectionLevel >SameOriginOnly </clickjackProtectionLevel >

<customWebAddresses >

<domainName >www.testing123.com

</domainName >

<primary >true </primary >

</customWebAddress >

<favoriteIcon >myFavIcon </favoriteIcon >

<fileNotFoundPage >FileNotFound </fileNotFoundPage >

<genericErrorPage >Exception </genericErrorPage >

<inMaintenancePage >InMaintenance </inMaintenancePage >

<serverIsDown >MyServerDownResource </serverIsDown >

307

Metadata Types CustomTab

<indexPage >UnderConstruction </indexPage >

<masterLabel >customSite </masterLabel >

<portal >Customer Portal </portal >

<requireInsecurePortalAccess >false </requireInsecurePortalAccess >

<siteAdmin >[email protected]

</siteAdmin >

<siteTemplate >SiteTemplate </siteTemplate >

<subdomain >myco </subdomain >

</CustomSite >

SEE ALSO:

Portal

CustomTab

Represents a custom tab. Custom tabs let you display custom object data or other web content in Salesforce. When you add a custom tab to an app in Salesforce Classic, it displays as a tab. When you add a custom tab to an app in Lightning Experience, it displays as an item in the app’s navigation bar. When a tab displays a custom object, the tab name is the same as the custom object name; for page, s-control, or URL tabs, the name is arbitrary. For more information, see “Show Custom Object Data for Your Users” in the Salesforce online help. This type extends the

Metadata

metadata type and inherits its fullName

field.

File Suffix and Directory Location

The file suffix is

.tab

. There is one file for each tab, stored in the tabs

folder in the corresponding package directory.

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

Tabs are available in API version 10.0 and later.

Fields

This metadata type contains the following fields:

Field Name

actionOverrides

Field Type

ActionOverride

[] auraComponent string

Description

A list of the action overrides that are assigned to the tab. Only one

override is allowed per formFactor

for a given tab.

This field is available in API version 37.0 and later.

Indicates whether this tab is for a Lightning component ( true

) or not

( false

). If set to true

, the name of the tab matches the name of the

Lightning component.

Only one of these fields should have a value set:

•

auraComponent

308

Metadata Types

Field Name

customObject description flexiPage frameHeight fullName

Field Type

boolean string string int string

CustomTab

Description

•

customObject

•

flexiPage

•

page

•

scontrol

•

url

Note: auraComponent

is part of the Lightning Components

(Beta) feature.

Indicates whether this tab is for a custom object ( true

) or not ( false

).

If set to true

, the name of the tab matches the name of the custom object.

Only one of these fields should have a value set:

•

auraComponent

•

customObject

•

flexiPage

•

page

•

scontrol

•

url

The optional description text for the tab.

The name of the Lightning Page to display in this tab.

Only one of these fields should have a value set:

•

auraComponent

•

customObject

•

flexiPage

•

page

•

scontrol

•

url

The height, in pixels of the tab frame. Required for s-control and page tabs.

The name of the tab. The value of this field depends on the type of tab, and the API version.

•

For custom object tabs, the fullName

is the developer-assigned name of the custom object (MyCustomObject__c, for example). For custom object tabs, this name must be the same as the custom object name, and

customObject

should be set to

true

.

•

For Web tabs, the fullName

is the developer-assigned name of the tab (MyWebTab, for example).

309

Metadata Types

Field Name

hasSidebar icon label mobileReady motif page scontrol splashPageLink url

Field Type

boolean string string boolean string string string string string

CustomTab

Description

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.

Indicates if the tab displays the sidebar panel.

The optional reference to the image document for the tab if the tab is not using one of the standard tab styles. This is a new field in API version

14.0.

This is the label of the tab, for Web tabs only.

Required. Indicates if the custom tab is available for Mobile Edition

( true

) or not ( false

).

Required. The tab style for the color scheme and icon for the custom tab. For example, “'Custom70: Handsaw,” is the handsaw icon.

The name of the Visualforce page to display in this tab.

Only one of these fields should have a value set:

•

auraComponent

•

customObject

•

flexiPage

•

page

•

scontrol

•

url

The name of the s-control to display in this tab.

Only one of these fields should have a value set:

•

auraComponent

•

customObject

•

flexiPage

•

page

•

scontrol

•

url

The custom link used as the introductory splash page when users click

the tab. References a HomePageComponent .

The URL for the external web-page to embed in this tab.

Only one of these fields should have a value set:

•

auraComponent

•

customObject

•

flexiPage

310

Metadata Types CustomValue

Field Name

urlEncodingKey

Field Type

Encoding

(

enumeration of

type string)

Description

•

page

•

scontrol

•

url

The default encoding setting is Unicode:

UTF-8

. Change it if you are passing information to a URL that requires data in a different format. This option is available when the value

URL

is selected in the tab type.

Declarative Metadata Sample Definition

The following is the definition of a tab:

<?xml

version= "1.0" encoding= "UTF-8"?>

<CustomTab xmlns= "http://soap.sforce.com/2006/04/metadata">

<description >Myriad Publishing </description >

<frameHeight >600 </frameHeight >

<mobileReady >true </mobileReady >

<motif >Custom53: Bell </motif >

<url >http://www.myriadpubs.com

</url >

<urlEncodingKey >UTF-8 </urlEncodingKey >

</CustomTab >

SEE ALSO:

CustomApplication

CustomValue

Represents the definition of a value used in a global value set or local custom picklist. Custom picklist fields can be local and unique, or can inherit their values from a global picklist (called a global value set in API version 38.0). This type extends the

Metadata metadata type

and inherits its fullName

field.

To deactivate a global picklist value, you can invoke an update()

call on GlobalPicklist (API version 37.0) or GlobalValueSet (API version 38.0 and later) with the value omitted, or with the value’s isActive

field set to false

. Or, you can invoke an update() call directly on GlobalPicklistValue (API version 37.0) or CustomValue (API version 38.0 and later) with the isActive

field set to false

.

Note: If picklist values are missing from a component definition, they get deactivated when deployed. Deactivation occurs for picklist values of both standard and custom fields.

CustomValue doesn’t support file-based operations and only supports CRUD-based calls. CustomValue is retrieved or deployed together with a GlobalValueSet or CustomObject component.

File Suffix and Directory Location

CustomValue components have the suffix

.customValue

. A CustomValue component is returned with either a GlobalValueSet or

CustomObject component.

311

Metadata Types CustomValue

Version

CustomValue components are available in API version 38.0 and later. CustomValue replaces GlobalPicklistValue from API version 37.0.

Fields

Field Name

color

Field Type

string default description isActive label boolean string boolean string

Description

The color assigned to the picklist value when it’s used in charts on reports and dashboards. The color is in hexadecimal format; for example,

#FF6600. If a color is not specified, it’s assigned dynamically upon chart generation.

Required. Indicates whether this value is the default selection for the global picklist and the custom picklists that share its picklist value set.

This field is set to

true

by default.

A picklist value’s description. It’s useful to include a description for a picklist value so the reason for creating it can be tracked. Limit: 255 characters.

Indicates whether this value is currently active or inactive. The default value is

true

. Users can select only active values from a picklist. An API retrieve operation for global picklist values returns all active and inactive values in the picklist. (Meanwhile, retrieving the values of a non-global, unrestricted picklist returns only the active values.)

The value’s display label. If you don’t specify the label when creating a value it defaults to the API name. Available in API version 39.0 and later.

StandardValue

This metadata type defines a value in a value set for a standard picklist and specifies whether this value is the default value. This type extends the CustomValue metadata type and inherits all its fields.

When you deploy changes to standard picklist fields, picklist values are added as needed.

Field Name

allowEmail closed

Field Type

boolean boolean

Description

Indicates whether this value lets users email a quote PDF ( true

), or not

( false

). This field is only relevant for the

Status

field in quotes. This field is available in API version 18.0 and later.

Indicates whether this value is associated with a closed status ( true

), or not ( false

). This field is only relevant for the standard

Status field in cases and tasks. This field is available in API version 16.0 and up to version 36.0. In version 37.0, this field is in GlobalPicklistValue.

converted boolean Indicates whether this value is associated with a converted status ( true

), or not ( false

). This field is relevant for only the standard

Lead

Status

field in leads. Your organization can set its own guidelines for

312

Metadata Types

Field Name

cssExposed forecastCategory highPriority probability reverseRole

CustomValue

Field Type

boolean

Description

determining when a lead is qualified, but typically, you want to convert a lead as soon as it becomes a real opportunity that you want to forecast.

For more information, see “Convert Qualified Leads” in the Salesforce online help. This field is available in API version 16.0 and later.

Indicates whether this value is available in your Self-Service Portal ( true

), or not ( false

). This field is only relevant for the standard

Case

Reason

field in cases.

Self-Service provides an online support channel for your customers allowing them to resolve their inquiries without contacting a customer service representative. For more information about Self-Service, see

“Setting Up Self-Service” in the Salesforce online help.

Note: Starting with Spring ’12, the Self-Service portal isn’t available for new orgs. Existing orgs continue to have access to the Self-Service portal.

This field is available in API version 16.0 and later.

ForecastCategories

(

enumeration of

type string)

Indicates whether this value is associated with a forecast category

( true

), or not ( false

). This field is only relevant for the standard

Stage

field in opportunities. For more information about forecast categories, including the valid string values listed below, see “ Working with Forecast Categories ” in the Salesforce online help.

•

Omitted

•

Pipeline

•

BestCase

•

Forecast

•

Closed

This field is available in API version 16.0 and later.

boolean int string

Indicates whether this value is a high priority item ( true

), or not

( false

). This field is only relevant for the standard

Priority

field in tasks. For more information about tasks, see “Considerations for Using

Tasks” in the Salesforce online help. This field is available in API version

16.0 and later.

Indicates whether this value is a probability percentage ( true

), or not

( false

). This field is only relevant for the standard

Stage

field in opportunities. This field is available in API version 16.0 and later.

A picklist value corresponding to a reverse role name for a partner. If the role is “subcontractor”, then the reverse role might be “general contractor”. Assigning a partner role to an account in Salesforce creates a reverse partner relationship so that both accounts list the other as a partner. This field is only relevant for partner roles.

For more information, see “Partner Fields” in the Salesforce online help.

313

Metadata Types Dashboard

Field Name

reviewed won

Field Type

boolean boolean

Description

This field is available in API version 18.0 and later.

Indicates whether this value is associated with a reviewed status ( true

), or not ( false

). This field is only relevant for the standard

Status field in solutions. For more information about opportunities, see “Creating

Solutions” in the Salesforce online help. This field is available in API version 16.0 and later.

Indicates whether this value is associated with a closed or won status

( true

), or not ( false

). This field is only relevant for the standard

Stage

field in opportunities. This field is available in API version 16.0

and later.

Declarative Metadata Sample Definition

For an example of CustomValue components within a GlobalValueSet component that’s referenced by a package.xml

, see

GlobalValueSet

.

Dashboard

Represents a dashboard. Dashboards are visual representations of data that allow you to see key metrics and performance at a glance.

This type extends the

Metadata metadata type and inherits its

fullName

field. For more information, see “Edit Dashboards in

Accessibility Mode in Salesforce Classic” in the Salesforce online help.

Declarative Metadata File Suffix and Directory Location

Dashboards are stored in the dashboards

directory of the corresponding package directory. The file name matches the dashboard title and the extension is

.dashboard

.

Retrieving Dashboards

You can’t use the wildcard (*) symbol with dashboards in package.xml

. To retrieve the list of dashboards for populating package.xml

with explicit names, call listMetadata()

and pass in

DashboardFolder

as the type. Note that

DashboardFolder is not returned as a type in describeMetadata()

. Dashboard is returned from describeMetadata() with an associated attribute of inFolder

set to true. If that attribute is set to true, you can construct the type by using the component name with the word Folder, such as DashboardFolder.

The following example shows folders in package.xml

:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >MyDBFolder/MyDBName </members >

<name >Dashboard </name >

</types >

<types >

<members >MyDocumentFolder/MyDocumentName </members >

314

Metadata Types Dashboard

<name >Document </name >

</types >

<types >

<members >unfiled$public/MarketingProductInquiryResponse </members >

<members >unfiled$public/SalesNewCustomerEmail </members >

<name >EmailTemplate </name >

</types >

<types >

<members >MyReportFolder/MyReportName </members >

<name >Report </name >

</types >

<version >39.0

</version >

</Package >

Version

Dashboard components are available in API version 14.0 and later.

Fields

Field

backgroundEndColor

Field Type

string backgroundFadeDirection

ChartBackgroundDirection

( enumeration

of type string) backgroundStartColor dashboardFilters string

DashboardFilters

[]

Description

Required. A dashboard can have a gradient color change on its charts. This field defines the second color for the gradient and

backgroundStartColor

defines the first color. If you

prefer your background to be all one color or do not want a gradient color change, select the same color for this field and

backgroundStartColor

. The color is in hexadecimal

format; for example #FF6600.

Required. The direction of the gradient color change, defined

by the backgroundStartColor

and

backgroundEndColor

fields. The valid values are:

•

diagonal

•

leftToRight

•

topToBottom

Required. The starting color for the gradient color change on the dashboard's charts. See

backgroundEndColor

for

more information. The color is in hexadecimal format; for example #FF6600.

The list of filters in a dashboard.

This field is available in API version 23.0 and later.

315

Metadata Types Dashboard

Field

dashboardGridLayout dashboardType description folderName fullName isGridLayout leftSection middleSection rightSection

Field Type

DashboardGridLayout

Description

Lists the included

DashboardGridComponent

objects, specifies the number of dashboard columns, and sets each dashboard row’s height in pixels.

This field is available in API version 35.0 and later.

DashboardType ( enumeration

of type string)

Determines the way visibility settings are set for a dashboard.

The valid values are:

•

SpecifiedUser

—All users see data at the access level of one specific running user, specified in the

runningUser

field, regardless of their own security settings.

•

LoggedInUser

—Each logged-in user sees data according to his or her own access level.

•

MyTeamUser

—Managers can choose to view the dashboard from the point of view of their subordinates in the role hierarchy. This value is available in API version 20.0

and later.

This field is available in API version 19.0 and later.

string string

Description for the dashboard. Maximum of 255 characters.

Name of the folder that houses the dashboard.

This field is available in API version 35.0 and later.

string boolean

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.

This field specifies the folder and dashboard title; for example folderSales/California

.

Specifies whether a dashboard uses the Lightning Experience layout ( true

) or not ( false

).

Lightning Experience allows dashboards with more than three columns with components that span multiple columns and multiple rows in size.

This field is available in API version 35.0 and later.

DashboardComponentSection

Required. The left section or column of the dashboard.

DashboardComponentSection

The middle section or column of the dashboard.

DashboardComponentSection

Required. The right section or column of the dashboard.

316

Metadata Types Dashboard

Field

runningUser textColor title titleColor titleSize

Field Type

string string string string int

Description

The username of the user whose role and sharing settings are used to determine the data shown in the dashboard.

When you deploy a dashboard and the value in this field is not defined or does not correspond to a valid user, the field is populated with the username of the user performing the deployment.

Regardless of their security settings, all users viewing a dashboard see exactly the same data, because dashboards are always run using the security settings of a particular user.

Tip: To avoid inappropriate exposure of sensitive data, save the dashboard to a folder that is visible only to appropriate users.

Required. Color of the text on each chart in the dashboard. The color is in hexadecimal format; for example #FF6600.

Required. The dashboard title.

Required. Color of the titles on each dashboard component. The color is in hexadecimal format; for example #FF6600.

Required. Size of characters in title text. For example, a value of

12 indicates 12pt text.

DashboardComponentSection

DashboardComponentSection represents one of the sections or columns in a dashboard.

Field

columnSize components

Field Type

DashboardComponentSize

( enumeration

of type string)

DashboardComponent

[]

Description

Required. The size of the column in the dashboard. See

DashboardComponentSize for details on valid values.

The list of

DashboardComponent objects in the dashboard

column.

DashboardComponentSize

DashboardComponentSize is an enumeration of type string that lists different size categories. The valid values are listed in the table below:

Enumeration Value

medium narrow wide

Description

Medium component size.

Smallest component size.

Largest component size.

317

Metadata Types Dashboard

DashboardComponent

A dashboard consists of a group of different components or elements that display data. Each component can use a custom report or a custom s-control as their data source to display corporate metrics or key performance indicators. You can create several dashboard components and display them all in one dashboard aligned in up to three columns.

Field

chartAxisRange chartAxisRangeMax chartAxisRangeMin chartSummary componentType

Field Type Description

ChartRangeType (

enumeration

of type string)

A manual or automatic axis range for bar or line charts.

The valid values are:

•

auto

•

manual double double

ChartSummary

The maximum axis range to be displayed. This only applies to bar and line charts in which the manual

axis range

is selected for the chartAxisRange

field.

The minimum axis range to be displayed. This only applies to bar and line charts in which the manual

axis range

is selected for the chartAxisRange

field.

Specifies the summary field for the chart data. Required if isAutoSelectFromReport

is set to false

.

This field is available in API version 25.0 and later.

DashboardComponentType

(

enumeration

of type string)

Required. Dashboard component type. The valid values are:

•

Bar

•

BarGrouped

•

BarStacked

•

BarStacked100

•

Column

•

ColumnGrouped

•

ColumnLine

•

ColumnLineGrouped

•

ColumnLineStacked

•

ColumnLineStacked100

•

ColumnStacked

•

ColumnStacked100

•

Donut

•

Funnel

•

Gauge

•

Line

•

lineCumulative

•

LineGrouped

318

Metadata Types Dashboard

Field

dashboardFilterColumns

Field Type

dashboardTableColumn

DashboardTableColumn

[] displayUnits

ChartUnits ( enumeration of type

string) drillDownUrl drillEnabled drillToDetailEnabled

DashboardFilterColumns []

string boolean boolean

Description

•

lineGroupedCumulative

•

Metric

•

Pie

•

Scatter

•

ScatterGrouped

•

Scontrol

•

Table

A list of dashboard filter columns. Each report-based component must have a dashboard filter column that defines the column that the filter applies to.

This field is available in API version 23.0 and later.

Represents a list of columns on a customized dashboard table component.

Chart Units. The valid values are:

•

Auto

•

Integer

•

Hundreds

•

Thousands

•

Millions

•

Billions

•

Trillions

For charts, specifies a URL that users go to when they click the dashboard component. Use this option to send users to another dashboard, report, record detail page, or other system that uses a Web interface. This field overrides the

drillEnabled

and drillToDetailEnabled

fields.

Specifies whether to take users to the full or filtered source report when they click the dashboard component. Set to false

to drill to the full source report; set to true

to drill to the source report filtered by what they clicked. If set to true

, users can click individual groups, axis values, or legend entries.

This overrides the

drillToDetailEnabled

field.

This field is available in API version 17.0 and later.

When enabled, users are taken to the record detail page when they click a record name, record owner, or feed post in a table or chart. When set to true

users can click axis

319

Metadata Types

Field

enableHover expandOthers

Field Type

boolean boolean footer gaugeMax gaugeMin groupingColumn string double double string header string indicatorBreakpoint1 double indicatorBreakpoint2 double indicatorHighColor string indicatorLowColor indicatorMiddleColor string string

320

Dashboard

Description

and legend values, chart elements, and table entries. The

drillDownUrl

and drillEnabled

fields override this field. This field is available in API version 20.0 and later.

Specifies whether to display values, labels, and percentages when hovering over charts. Hover details depend on chart type. Percentages apply to pie, donut, and funnel charts only. This field is available in API version

17.0 and later.

Specifies whether to combine all groups less than or equal to 3% of the total into a single 'Others' wedge or segment.

This only applies to pie, donut, and funnel charts. Set to true

to show all values individually on the chart; set to false

to combine small groups into 'Others.' This field is available in API version 17.0 and later.

Footer displayed at the bottom of the dashboard component. Maximum of 255 characters.

The maximum value on a gauge. A gauge is used to see how far you are from reaching a goal. It looks like a speedometer in a car.

The minimum value on a gauge.

Specifies the field by which to group data. This data is displayed on the X-axis for vertical column charts and on the Y-axis for horizontal bar charts.

This field is available in API version 25.0 and later.

Header displayed at the top of the dashboard component.

Maximum of 80 characters.

The value that separates the indicatorLowColor from the indicatorMiddleColor

on the dashboard.

The value that separates the

indicatorMiddleColor

from the

indicatorHighColor

on the dashboard.

The color representing a high number range on the gauge.

The color representing a low number range on the gauge.

The color representing a medium number range on the gauge.

Metadata Types Dashboard

Field

legendPosition maxValuesDisplayed metricLabel page pageHeightInPixels report scontrol scontrolHeightInPixels showPercentage showPicturesOnCharts showPicturesOnTables

Field Type Description

ChartLegendPosition (

enumeration

of type string)

The location of the legend with respect to the chart. The valid values are:

•

Bottom

•

OnChart

•

Right int string string int string string int boolean boolean boolean

The maximum number of elements to include in the top-level grouping of the horizontal axis of a horizontal chart, vertical axis of a vertical chart, or selected axis of a stacked bar chart. For example, if you want to list only your top five salespeople, create an opportunity report that lists total opportunity amounts by owner and enter

5

in this field.

Descriptive label for the metric. This is relevant if metric

is the value of the componentType

field.

Visualforce page associated with the component.

Display height of the Visualforce page in pixels.

Name of the report associated with the component.

S-control associated with component if scontrol

is

the value of the componentType

field. For more information, see “Defining Custom S-Controls” in the

Salesforce online help.

Display height of the s-control in pixels.

Indicates if percentages are displayed for regions of gauges and wedges and segments of pie, donut, and funnel charts ( true

), or not ( false

).

Display Chatter photos for up to 20 records in a horizontal bar chart component whose source report is grouped by a user or group name field. If there are more than 20 records with photos, record names are shown instead of photos. Set

Grouping Display

to

None

to show photos. Set the

Drill Down to

option to

Record

Detail Page

to take users directly to user profile or group pages when they click photos. Chatter must be enabled for photos to be displayed. Depending on your organization's setup, you may not see photos on tables and charts.

Display Chatter photos for up to 20 records in a horizontal bar chart component whose source report is grouped by a user or group name field. If there are more than 20 records with photos, record names are shown instead of

321

Metadata Types Dashboard

Field

showTotal showValues sortBy title useReportChart

Field Type

boolean boolean

DashboardComponentFilter

(

enumeration

of type string) string boolean

Description

photos. Set

Grouping Display

to

None

to show photos. Set the

Drill Down to

option to

Record

Detail Page

to take users directly to user profile or group pages when they click photos. Chatter must be enabled for photos to be displayed. Depending on your organization's setup, you may not see photos on tables and charts.

Indicates if the total of all wedges is displayed for gauges and donut charts ( true

), or not ( false

).

Indicates if the values of individual records or groups are displayed for charts ( true

), or not ( false

).

The sort option for the dashboard component.

The title of the dashboard component. Maximum of 40 characters.

Specifies whether to use the chart defined in the source report on this dashboard component. The chart settings in the source report determine how the chart displays in the dashboard, and any chart settings you define for the dashboard are overridden. If you defined a combination chart in the source report, use this option to use that combination chart on this dashboard.

DashboardFilters

DashboardFilters represents a filter in a dashboard.

Field Field Type

dashboardFilterOptions

DashboardFilterOptions

[] name string

Description

The list of items you can select in the

Filter Options section of the Add Filter dialog.

Required. The filter label.

DashboardFilterColumns

DashboardFilterColumns represents a filter column in a dashboard.

Field

column

Field Type

string

Description

Required. The report column code for the filter.

322

Metadata Types Dashboard

DashboardFilterOptions

DashboardFilterOptions represents a filter option in a dashboard.

Field

operator

Field Type

DashboardFilterOperation

( enumeration

of type string) value values string string[]

Description

Required. Represents the filter operation for this filter item. Valid

values are enumerated in DashboardFilterOperation

. This field is available in API version 24.0 and later.

With API version 23.0, valid values are enumerated in

FilterOperation .

Required. The value in the

Filter Options

area of the

Add Filter

dialog. This field is available in API version 23.0.

Required. One or more values in the

Filter Options

area of the

Add Filter

dialog. This field is available in API version

24.0 and later.

DashboardFilterOperation

This is an enumeration of type string that lists dashboard filter operations. Valid values are:

•

equals

•

notEqual

•

lessThan

•

greaterThan

•

lessOrEqual

•

greaterOrEqual

•

contains

•

notContain

•

startsWith

•

includes

•

excludes

•

between

Note: The “between” operator takes two operands (for example, “between MinimumValue, MaximumValue”). Note also that the minimum value is inclusive, while the maximum value is exclusive. All other dashboard filter operations take a single operand only.

DashboardTableColumn

DashboardTableColumn represents a column in a customized table component in a dashboard.

323

Metadata Types Dashboard

Field

aggregateType column showTotal sortBy

(

Field Type

ReportSummaryType []

( enumeration

of type string) string boolean

DashboardComponentFilter

enumeration

of type string)

Description

Specifies the aggregation type for the table column.

Required. The label of the column to use in the table.

Displays the totals for each summarizable column in the dashboard table. This field is available in API version 19.0 and later.

The sort option for the dashboard table component. Sort on just one column per table.

DashboardComponentFilter

DashboardComponentFilter is an enumeration of type string that lists the sort values for dashboard components. The valid values are:

Enumeration Value

RowLabelAscending

RowLabelDescending

RowValueAscending

RowValueDescending

Description

Sorts in alphabetical order by the label.

Sorts in reverse alphabetical order by the label.

Sorts lowest to highest by the value.

Sorts highest to lowest by the value.

DashboardGridComponent

Lightning Experience features dashboards with more than three columns and components that span multiple columns and multiple rows in size. DashboardGridComponent specifies location and size of a given dashboard component.

Field

colSpan columnIndex dashboardComponent rowIndex rowSpan

Field Type

int int

DashboardComponent

int int

Description

Required. The width of the dashboard component in columns.

For example, if colSpan

is 5, then the dashboard component spans five columns.

Required. The left-most column that is occupied by the dashboard component.

Required. The dashboard component that is being sized and placed.

Required. The top-most row that is occupied by the dashboard component.

Required. The height of the dashboard component in rows.

324

Metadata Types Dashboard

DashboardGridLayout

Lightning Experience features dashboards with more than three columns and components that span multiple columns and multiple rows in size. DashboardGridLayout lists the included dashboard components, specifies the number of dashboard columns, and sets each dashboard row’s height in pixels.

Field Field Type

dashboardGridComponents

DashboardGridComponent []

numberOfColumns rowHeight int int

Description

List of

DashboardGridComponent

objects in the dashboard.

Required. Total number of columns in the dashboard.

Required. Height of each row in pixels.

Declarative Metadata Sample Definition — Filtered Dashboard

A sample XML definition of a filtered dashboard is shown below. Note that this example is supported in API version 24.0 and later. The file name matches the dashboard title and the extension is

.dashboard

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Dashboard xmlns= "http://soap.sforce.com/2006/04/metadata">

<backgroundEndColor >#FFFFFF </backgroundEndColor >

<backgroundFadeDirection >Diagonal </backgroundFadeDirection >

<backgroundStartColor >#FFFFFF </backgroundStartColor >

<dashboardFilters >

<dashboardFilterOptions >

<operator >equals </operator >

<values >Media </values >

</dashboardFilterOptions >

<dashboardFilterOptions >

<operator >lessThan </operator >

<values >Working </values >

</dashboardFilterOptions >

<dashboardFilterOptions >

<operator >between </operator >

<values >ABC </values >

<values >XYZ </values >

</dashboardFilterOptions >

<name >Industry </name >

</dashboardFilters >

<dashboardFilters >

<dashboardFilterOptions >

<operator >equals </operator >

<values >Analyst,Partner </values >

</dashboardFilterOptions >

<dashboardFilterOptions >

<operator >startsWith </operator >

<values >Integrator </values >

</dashboardFilterOptions >

<name >Account Type </name >

</dashboardFilters >

<dashboardType >SpecifiedUser </dashboardType >

<leftSection >

325

Metadata Types

<columnSize >Medium </columnSize >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >Bar </componentType >

<dashboardFilterColumns >

<column >INDUSTRY </column >

</dashboardFilterColumns >

<dashboardFilterColumns >

<column >TYPE </column >

</dashboardFilterColumns >

<displayUnits >Auto </displayUnits >

<drillEnabled >false </drillEnabled >

<drillToDetailEnabled >false </drillToDetailEnabled >

<enableHover >false </enableHover >

<expandOthers >false </expandOthers >

<legendPosition >Bottom </legendPosition >

<report >unfiled$public/SampleReportofAccounts </report >

<showPercentage >false </showPercentage >

<showPicturesOnCharts >false </showPicturesOnCharts >

<showValues >false </showValues >

<sortBy >RowLabelAscending </sortBy >

<useReportChart >false </useReportChart >

</components >

</leftSection >

<middleSection >

<columnSize >Medium </columnSize >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >Funnel </componentType >

<dashboardFilterColumns >

<column >ACCOUNT_INDUSTRY </column >

</dashboardFilterColumns >

<dashboardFilterColumns >

<column >ACCOUNT.TYPE

</column >

</dashboardFilterColumns >

<displayUnits >Auto </displayUnits >

<drillEnabled >false </drillEnabled >

<drillToDetailEnabled >false </drillToDetailEnabled >

<enableHover >false </enableHover >

<expandOthers >false </expandOthers >

<legendPosition >Bottom </legendPosition >

<report >unfiled$public/SampleReportofCases </report >

<showPercentage >false </showPercentage >

<showValues >true </showValues >

<sortBy >RowLabelAscending </sortBy >

<useReportChart >false </useReportChart >

</components >

</middleSection >

<rightSection >

<columnSize >Medium </columnSize >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >Column </componentType >

<dashboardFilterColumns >

326

Dashboard

Metadata Types Dashboard

<column >INDUSTRY </column >

</dashboardFilterColumns >

<dashboardFilterColumns >

<column >ACCOUNT_TYPE </column >

</dashboardFilterColumns >

<displayUnits >Auto </displayUnits >

<drillEnabled >false </drillEnabled >

<drillToDetailEnabled >false </drillToDetailEnabled >

<enableHover >false </enableHover >

<expandOthers >false </expandOthers >

<legendPosition >Bottom </legendPosition >

<report >unfiled$public/SampleReportofOpportunities </report >

<showPercentage >false </showPercentage >

<showValues >false </showValues >

<sortBy >RowLabelAscending </sortBy >

<useReportChart >false </useReportChart >

</components >

</rightSection >

<runningUser >admin@TESTORGNUM </runningUser >

<textColor >#000000 </textColor >

<title >My Dashboard </title >

<titleColor >#000000 </titleColor >

<titleSize >12 </titleSize >

</Dashboard >

Declarative Metadata Sample Definition — Unfiltered Dashboard

A sample XML definition of a dashboard is shown below. The file name matches the dashboard title and the extension is

.dashboard

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Dashboard xmlns= "http://soap.sforce.com/2006/04/metadata">

<backgroundEndColor >#FFFFFF </backgroundEndColor >

<backgroundFadeDirection >LeftToRight </backgroundFadeDirection >

<backgroundStartColor >#FFFFFF </backgroundStartColor >

<description >Dashboard with all possible chart types </description >

<leftSection >

<columnSize >Medium </columnSize >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >BarStacked100 </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

<components >

<componentType >Table </componentType >

<dashboardTableColumn >

<column >CLOSE_DATE </column >

<sortBy >RowLabelAscending </sortBy >

</dashboardTableColumn >

<dashboardTableColumn >

<aggregateType >Sum </aggregateType >

327

Metadata Types

<column >AMOUNT </column >

<showTotal >true </showTotal >

</dashboardTableColumn >

<dashboardTableColumn >

<column >STAGE_NAME </column >

</dashboardTableColumn >

<dashboardTableColumn >

<column >PROBABILITY </column >

<aggregateType >Maximum </aggregateType >

</dashboardTableColumn >

<displayUnits >Integer </displayUnits >

<header >Opportunities Table </header >

<indicatorHighColor >#54C254 </indicatorHighColor >

<indicatorLowColor >#C25454 </indicatorLowColor >

<indicatorMiddleColor >#C2C254 </indicatorMiddleColor >

<maxValuesDisplayed >10 </maxValuesDisplayed >

<report >testFolder/sourceRep </report >

</components >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >Bar </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >Column </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<legendPosition >Bottom </legendPosition >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

<useReportChart >true </useReportChart >

</components >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >Funnel </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<expandOthers >true </expandOthers >

<legendPosition >Bottom </legendPosition >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

</leftSection >

<middleSection >

<columnSize >Medium </columnSize >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >ColumnStacked100 </componentType >

328

Dashboard

Metadata Types

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >ColumnStacked </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >ColumnStacked </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >ColumnGrouped </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >Column </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

</middleSection >

<rightSection >

<columnSize >Medium </columnSize >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >Bar </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

329

Dashboard

Metadata Types

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >Pie </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<expandOthers >true </expandOthers >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >LineGroupedCumulative </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >LineGrouped </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >LineCumulative </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

<components >

<chartAxisRange >Auto </chartAxisRange >

<componentType >Donut </componentType >

<displayUnits >Auto </displayUnits >

<drillEnabled >true </drillEnabled >

<enableHover >true </enableHover >

<expandOthers >true </expandOthers >

<report >testFolder/sourceRep </report >

<sortBy >RowLabelAscending </sortBy >

</components >

</rightSection >

<runningUser >admin@TESTORGNUM </runningUser >

<textColor >#000000 </textColor >

<title >Db Title </title >

<titleColor >#000000 </titleColor >

<titleSize >12 </titleSize >

</Dashboard >

330

Dashboard

Metadata Types Dashboard

Declarative Metadata Sample Definition — Lightning Experience Dashboard with

isGridLayout

Equals

true

A sample XML definition of a Lightning Experience dashboard with isGridLayout

equals true

is shown below. Note that this example is supported in API version 35.0 and later. The file name matches the dashboard title and the extension is

.dashboard

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Dashboard xmlns= "http://soap.sforce.com/2006/04/metadata">

<backgroundEndColor >#FFFFFF </backgroundEndColor >

<backgroundFadeDirection >Diagonal </backgroundFadeDirection >

<backgroundStartColor >#FFFFFF </backgroundStartColor >

<dashboardType >SpecifiedUser </dashboardType >

<gridLayout >

<dashboardGridComponents >

<colSpan >3 </colSpan >

<columnIndex >0 </columnIndex >

<dashboardComponent >

<autoselectColumnsFromReport >false </autoselectColumnsFromReport >

<chartAxisRange >Auto </chartAxisRange >

<chartSummary >

<axisBinding >y </axisBinding >

<column >RowCount </column >

</chartSummary >

<componentType >Donut </componentType >

<drillEnabled >false </drillEnabled >

<drillToDetailEnabled >false </drillToDetailEnabled >

<enableHover >false </enableHover >

<expandOthers >false </expandOthers >

<groupingColumn >TITLE </groupingColumn >

<legendPosition >Bottom </legendPosition >

<report >unfiled$public/lead_rpt </report >

<showPercentage >false </showPercentage >

<showTotal >false </showTotal >

<showValues >true </showValues >

<sortBy >RowLabelAscending </sortBy >

<useReportChart >false </useReportChart >

</dashboardComponent >

<rowIndex >0 </rowIndex >

<rowSpan >3 </rowSpan >

</dashboardGridComponents >

<dashboardGridComponents >

<colSpan >3 </colSpan >

<columnIndex >0 </columnIndex >

<dashboardComponent >

<autoselectColumnsFromReport >false </autoselectColumnsFromReport >

<chartAxisRange >Auto </chartAxisRange >

<chartSummary >

<axisBinding >y </axisBinding >

<column >RowCount </column >

</chartSummary >

<componentType >Pie </componentType >

<drillEnabled >false </drillEnabled >

<drillToDetailEnabled >false </drillToDetailEnabled >

<enableHover >false </enableHover >

331

Metadata Types

<expandOthers >false </expandOthers >

<groupingColumn >TITLE </groupingColumn >

<legendPosition >Bottom </legendPosition >

<report >unfiled$public/lead_rpt </report >

<showPercentage >false </showPercentage >

<showValues >true </showValues >

<sortBy >RowLabelAscending </sortBy >

<useReportChart >false </useReportChart >

</dashboardComponent >

<rowIndex >3 </rowIndex >

<rowSpan >3 </rowSpan >

</dashboardGridComponents >

<dashboardGridComponents >

<colSpan >3 </colSpan >

<columnIndex >0 </columnIndex >

<dashboardComponent >

<autoselectColumnsFromReport >false </autoselectColumnsFromReport >

<chartAxisRange >Auto </chartAxisRange >

<chartSummary >

<axisBinding >y </axisBinding >

<column >RowCount </column >

</chartSummary >

<componentType >Column </componentType >

<drillEnabled >false </drillEnabled >

<drillToDetailEnabled >false </drillToDetailEnabled >

<enableHover >false </enableHover >

<expandOthers >false </expandOthers >

<groupingColumn >TITLE </groupingColumn >

<legendPosition >Bottom </legendPosition >

<report >unfiled$public/lead_rpt </report >

<showPercentage >false </showPercentage >

<showValues >false </showValues >

<sortBy >RowLabelAscending </sortBy >

<useReportChart >false </useReportChart >

</dashboardComponent >

<rowIndex >9 </rowIndex >

<rowSpan >3 </rowSpan >

</dashboardGridComponents >

<numberOfColumns >9 </numberOfColumns >

<rowHeight >90 </rowHeight >

</gridLayout >

<isGridLayout >true </isGridLayout >

<runningUser >[email protected]

</runningUser >

<textColor >#000000 </textColor >

<title >sfx </title >

<titleColor >#000000 </titleColor >

<titleSize >12 </titleSize >

</Dashboard >

SEE ALSO:

Folder

Report

Dashboard

332

Metadata Types DataCategoryGroup

DataCategoryGroup

Represents a data category group.

This type extends the

Metadata metadata type and inherits its

fullName

field.

Warning: Using Metadata API to deploy category changes from one organization to another permanently removes categories and record categorizations that are not specified in your XML file. Salesforce recommends that you manually create data categories and record associations in an organization from Setup by entering

Data Categories

in the

Quick Find

box, then selecting Data Categories rather than deploying changes from a sandbox to a production organization. For more information,

see Usage .

Data category groups are provided to:

•

Classify and filter data.

•

Share data among users.

Every data category group contains items or data categories that can be organized hierarchically.

The example below shows the

Geography

data category group and its data categories.

Geography

Worldwide

North America

United States of America

Canada

Mexico

Europe

Asia

Note: See "Data Categories in Salesforce.com" in the Salesforce online help for more information on data category groups, data categories, parent and sub categories.

File Suffix and Directory Location

The file suffix is

.datacategorygroup

. There is one file for each data category group stored in the datacategorygroups folder in the corresponding package directory.

Version

Data category groups are available in API version 18.0 and later.

Fields

This metadata type contains the following fields:

Field Name

active

Field Type

boolean dataCategory

DataCategory

Description

Required. The status of the category group. Indicates whether this category group is active, ( true

), or not active ( false

).

Required. The top-level category within the data category group.

333

Metadata Types DataCategoryGroup

Field Name

description fullName label objectUsage

Field Type

string string string

ObjectUsage

Description

The description of the data category group.

Required. The unique name of the data category group. When creating a data category group, the fullName

field and the file name (without its suffix) must match.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.

Required. Label that represents the object in Salesforce.

The objects that are associated with the data category group.

DataCategory

Represents an item (or data category) in the data category group. A data category can recursively contain a list of other data categories.

Field Name

dataCategory label name

Field Type

DataCategory

[] string string

Description

A recursive list of sub data categories. For example, a list of countries within a continent. You can create up to 100 categories in a data category group and have up to 5 levels in a data category group hierarchy.

Required. Label for the data category throughout the Salesforce user interface.

Required. The developer name of the data category used as a unique identifier 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.

Important:

The value for this field is defined once and cannot be changed later.

Warning: If you deploy a category group that already exists in an organization, any category that is not defined in the XML file is permanently removed from your organization. For more

information see Usage

.

ObjectUsage

Represents the objects that can be associated with the data category group. This association allows the object to be classified and filtered using the data categories.

334

Metadata Types

Field Name

object

Field Type

string[]

DataCategoryGroup

Description

A list of the object names that can be associated with the data category group. Valid values are:

•

KnowledgeArticleVersion

—to associate articles. See

"Modify Default Category Group Assignments for Articles" in the

Salesforce online help for more information on data category groups association to articles.

•

Question

—to associate questions. You can associate the

Question

object with at most one category group. See "Assigning

Data Categories to Answers" in the Salesforce online help for more information on data category groups association to questions.

Warning: If you deploy a category group that already exists in an organization, any object association that is not defined in the

XML file is permanently removed from your organization. Ensure that your XML file specifies all the records associated with your category group in the organization. For more information see

Usage .

Declarative Metadata Sample Definition

This sample is the definition of the

Geography

data category group and its data categories:

<?xml

version= "1.0" encoding= "UTF-8"?>

<DataCategoryGroup xmlns= "http://soap.sforce.com/2006/04/metadata">

<label >Geography </label >

<description >Geography structure of service center locations </description >

<fullName >geo </fullName >

<dataCategory > <name >WW </name > <label >Worldwide </label >

<dataCategory > <name >AMER </name > <label >North America </label >

<dataCategory >

<name >USA </name >

<label >United States of America </label >

</dataCategory >

<dataCategory >

<name >CAN </name >

<label >Canada </label >

</dataCategory >

<dataCategory >

<name >MEX </name >

<label >Mexico </label >

</dataCategory >

</dataCategory >

<dataCategory > <name >EMEA </name > <label >Europe, Middle East, Africa </label >

<dataCategory >

<name >FR </name >

<label >France </label >

</dataCategory >

<dataCategory >

335

Metadata Types DataCategoryGroup

<name >SP </name >

<label >Spain </label >

</dataCategory >

<dataCategory >

<name >UK </name >

<label >United-Kingdom </label >

</dataCategory >

</dataCategory >

<dataCategory >

<name >APAC </name >

<label >Asia </label >

</dataCategory >

</dataCategory >

<objectUsage >

<object >KnowledgeArticleVersion </object >

<objectUsage >

</DataCategoryGroup >

Usage

When you deploy a category group XML file, Metadata API checks whether the category group exists in the target organization. If the category group does not exist, it is created. If the category group already exists, then Metadata API:

•

Adds any new category or object defined in the XML file.

•

Deletes any category that is not defined in the XML file. Records associated with the deleted categories are re-associated with the parent category.

•

Deletes any object association that is not defined in the XML file.

•

Moves any category if its hierarchical position differs from the position specified in the XML file.

Note: When a category moves to a new parent category, users that have no visibility on the new parent category lose their visibility to the repositioned category.

Note: For more information about category deletion, category repositioning and its impact on record categorization and visibility see "Delete a Data Category" and "Modify and Arrange Data Categories" in the Salesforce online help.

Using Metadata API to deploy category changes from one organization to another permanently removes categories and record categorizations that are not specified in your XML file. Salesforce recommends that you manually create data categories and record associations in an organization from Setup by entering

Data Categories

in the

Quick Find

box, then selecting Data

Categories rather than deploying changes from a sandbox to a production organization.

The following example illustrates what happens if you deploy an XML representation of a

Geography

data category group hierarchy to an organization that already has this data category group defined. Note that the organization contains a

US

category, while the XML file includes a

USA

category in the same hierarchical position. The Metadata API deployment process deletes the

US

category from the organization and moves associations for any records from

US

to the parent

AMER

category. It also adds the

USA

category under

AMER

. Note that all records that were previously categorized with

US

are now associated with the

AMER

category.

336

Metadata Types DataCategoryGroup

The next example illustrates what can happen when you delete or move a category in a data category group and deploy its XML representation from a sandbox to a production organization that already has this data category group defined. Hierarchy 1 shows the initial data category group in the sandbox organization. In hierarchy 2, we add an

EU

category under

EMEA

and move

FR

,

SP

and

UK

below

EU

. In hierarchy 3, we delete

FR

and associate its records with its new parent,

EU

. Finally, we deploy the changes from the sandbox to the production organization.

337

Metadata Types DelegateGroup

Metadata API has no concept of the order of the changes made to the sandbox organization. It just deploys the changes from one organization to another. During the deployment, it first notices the deletion of the

FR

category and removes it from the production organization. Consequently, it moves associations for any records from

FR

to its parent on the production organization,

EMEA

. Metadata

API then adds the

EU

category and moves

SP

and

UK

below it. Although the category group hierarchy looks the same in both organizations, record categorization in production is different from the sandbox organization. The records that were originally associated with

FR

in hierarchy 1 are associated with

EU

in the sandbox organization, but are associated with

EMEA

in the production organization.

DelegateGroup

Represents a group of users who have the same administrative privileges. These groups are different from public groups used for sharing.

This type extends the

Metadata metadata type and inherits its

fullName

field.

File Suffix and Directory Location

DelegateGroup components have the suffix

.delegateGroup

and are stored in the delegateGroups

folder. The file prefix must match the developer name of the delegate group. For example, a delegate group with a developer name of MyDelegateGroup would have a file name of

MyDelegateGroup.delegateGroup

.

Version

DelegateGroup components are available in API version 36.0 and later.

Special Access Rules

Only users with the “View Setup and Configuration” permission can be delegated administrators.

338

Metadata Types

Fields

Field Name

customObjects

DelegateGroup groups label loginAccess permissionSets profiles roles

Field Type

string[] string[] string boolean string[] string[] string[]

Description

The custom objects associated with the group. Delegated administrators can customize nearly every aspect of each of those custom objects, including creating a custom tab. However, they cannot create or modify relationships on the objects or set organization-wide sharing defaults.

Delegated administrators must have access to custom objects to access the merge fields on those objects from formulas.

The groups with users assigned by delegated administrators.

Required. The delegated group’s non-API name.

Required. Allows users in this group to log in as users in the role hierarchy that they administer ( true

) or not ( false

). Depending on your organization settings, individual users must grant login access to allow their administrators to log in as them.

The permission sets assignable to users in specified roles and all subordinate roles by delegated administrators.

The profiles assignable to users by delegated administrators.

The roles and subordinates for which delegated administrators of the group can create and edit users.

Declarative Metadata Sample Definition

The following is an example of a DelegateGroup component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<DelegateGroup xmlns= "http://soap.sforce.com/2006/04/metadata">

<label >MyDelegateGroup </label >

<loginAccess >true </loginAccess >

<name >MyDelegateGroup </name >

<profiles >Chatter Free User </profiles >

<profiles >Chatter Moderator User </profiles >

<profiles >Marketing User </profiles >

<permissionSets >My Permset </permissionSets >

<roles >LesserBossMan </roles >

</DelegateGroup >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >DelegateGroup </name >

</types >

<version >39.0

</version >

</Package >

339

Metadata Types Document

Document

Represents a Document. All documents must be in a document folder, for example sampleFolder/TestDocument

. This type extends the

MetadataWithContent metadata type and inherits its

content

and fullName

fields.

Currently, users are not able to export document metadata to a local file system using the Force.com IDE.

Retrieving Documents

You can’t use the wildcard (*) symbol with documents in package.xml

. To retrieve the list of documents for populating package.xml

with explicit names, call listMetadata()

and pass in

DocumentFolder

as the type. Note that DocumentFolder is not returned as a type in describeMetadata()

. Document is returned from describeMetadata()

with an associated attribute of inFolder

set to true. If that attribute is set to true, you can construct the type by using the component name with the word Folder, such as DocumentFolder.

The following example shows folders in package.xml

:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >MyDBFolder/MyDBName </members >

<name >Dashboard </name >

</types >

<types >

<members >MyDocumentFolder/MyDocumentName </members >

<name >Document </name >

</types >

<types >

<members >unfiled$public/MarketingProductInquiryResponse </members >

<members >unfiled$public/SalesNewCustomerEmail </members >

<name >EmailTemplate </name >

</types >

<types >

<members >MyReportFolder/MyReportName </members >

<name >Report </name >

</types >

<version >39.0

</version >

</Package >

For each document an accompanying metadata file named

DocumentFilename-meta.xml

is created in the document folder.

For example, for a document

TestDocument.png

in the sampleFolder folder, there’s a

TestDocument.png-meta.xml

in the documents/sampleFolder

of the package.

Version

Documents are available in API version 10.0 and later.

In API version 17.0 and later, you can delete a folder containing documents moved to the Recycle Bin. When you delete the folder, any related documents in the Recycle Bin are permanently deleted.

In API version 18.0 and later, documents do not need an extension.

340

Metadata Types

Fields

This metadata type contains the following fields:

Field Name

content

Field Type

base64 description fullName internalUseOnly keywords name public string string boolean string string boolean

Document

Description

Content of the document. 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. This field is inherited from the

MetadataWithContent

component.

A description of the document. Enter a description to distinguish this document from others.

The name of the document, including the folder name. In version 17.0

and earlier, the fullName

included the document extension. In version

18.0 and later, the fullName

does not include the file extension. 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. If this field contained characters before version 14.0 that are no longer allowed, the characters were stripped out of this field, and the previous value of the

field was saved in the name

field. This field is inherited from the Metadata

component.

Required. Indicates whether the document is confidential ( true

) or not

( false

). This field and public

are mutually exclusive; you cannot

set both to true

.

Contains one or more words that describe the document. A check for matches to words in this field is performed when doing a search.

The list of characters allowed in the

fullName

field has been reduced for versions 14.0 and later. This field contains the value contained in the

fullName

field before version 14.0. This field is only populated if the value of the fullName

field contained characters that are no longer

accepted in that field.

Required. Indicates whether the document is an image available for

HTML email templates and does not require a Salesforce username and password to view in an email ( true

) or not ( false

). If the images will be used as a custom app logo or custom tab icon, both of which require a Salesforce username and password to view, set this field to false

.

This field and internalUseOnly

are mutually exclusive; you cannot set both to true

.

341

Metadata Types DuplicateRule

Declarative Metadata Sample Definition

The following is the definition of a document:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Document xmlns= "http://soap.sforce.com/2006/04/metadata">

<internalUseOnly >false </internalUseOnly >

<name >Q2 Campaign Analysis </name >

<public >false </public >

<description >Analyze Q2 campaign effectiveness </description >

</Document >

SEE ALSO:

Folder

DuplicateRule

Represents a rule that specifies how duplicate records in an object are detected. This type extends the Metadata

metadata type and inherits its fullName

field.

File Suffix and Directory Location

DuplicateRule components have the

.duplicateRule

suffix and are stored in the duplicateRules/

directory. The name of the component file is based on the name of the object associated with the rule. For example, the component file name duplicateRules/Account.Standard_Account_Duplicate_Rule.duplicateRule

describes a duplicate rule component associated with the Account object.

Version

DuplicateRule components are available in API version 39.0 and later.

Fields

Field Name

actionOnInsert

Field Type

DupeActionType

(

enumeration of

type string)

Description

Required. Determines what the duplicate rule does when users or the

DuplicateRule API try to insert a record that is a duplicate. Valid values are:

Allow

For users, if operationsOnInsert

is set to alert

, the UI displays the value of alertText

in a dialog. The dialog prompts users to continue or cancel. If the user chooses to continue, the insertion proceeds. If the user chooses to cancel, the record isn’t inserted.

342

Metadata Types

Field Name

actionOnUpdate alertText description duplicateRuleFilter

DuplicateRule

Field Type Description

The DuplicateRule API returns an error code and a message. To complete the insertion, the code must set the allowSave

field in DuplicateRuleHeader to true

and reissue the request.

If operationsOnInsert isn’t set to alert

, the UI inserts the record without issuing an alert. The API inserts the record and doesn’t return an error code.

Block

For users, the UI displays an error message and prevents them from inserting the new record. The DuplicateRule API returns an error and doesn’t insert the record.

(

DupeActionType

enumeration

type string) string

of

Required. Determines what the duplicate rule does when users or the

DuplicateRule API try to update a record, and the result is a duplicate.

Valid values are:

Allow

For users, if operationsOnUpdate

is set to alert

, the UI displays the value of alertText

in a dialog. The dialog prompts users to continue or cancel. If the user chooses to continue, the update proceeds. If the user chooses to cancel, the record isn’t updated.

The DuplicateRule API returns a message. To complete the update, the code must set the allowSave

field in DuplicateRuleHeader to true

and reissue the request.

If operationsOnUpdate isn’t set to alert

, the UI updates the record without issuing an alert. The API updates the record and doesn’t return an error code.

Block

For users, the UI displays an error message and prevents them from continuing. The DuplicateRule API returns an error.

Text that’s sent when the duplicate rule is triggered. The text is only sent if isActive

is true

. In the UI, the text displays as a message. The

DuplicateRule API returns the message in its response.

You can set a value for alertText

only when you have actionOnInsert

or actionOnUpdate

(or both) set to

Allow

.

Otherwise, you receive a validation error when you add or update this component.

string Required. Text that describes the duplicate rule. The value is customer-supplied, but is not visible in the UI.

DuplicateRuleFilter

Required. Criteria that define how to find records to consider when looking for duplicates. For example, use duplicateRuleFilter to exclude records from the match when looking for duplicates.

343

Metadata Types DuplicateRule

Field Name

duplicateRuleMatchRules isActive masterLabel operationsOnInsert

Field Type Description

DuplicateRuleMatchRule

[]

Required. One or more MatchingRule components for the DuplicateRule.

A

MatchingRule

controls what constitutes a match between records.

boolean Required. If true

, the DuplicateRule detects duplicate records.

Otherwise, the rule has no effect.

string string[]

Required. Master label for this DuplicateRule. This value is the internal label for the rule.

Required. Controls the action to take when actionOnInsert

is set to

Allow

and the duplicate rule is triggered. Either one or both of these values can be set in the array:

alert

If set, the action specified in actionOnInsert

occurs; otherwise, the insert proceeds.

report

If set, the insert operation is added to the report of duplicates.

operationsOnUpdate securityOption sortOrder string[] Required. Controls the action to take when actionOnUpdate

is set to

Allow

and the duplicate rule is triggered. Either one or both of these values can be set in the array:

alert

If set, the action specified in actionOnUpdate

occurs; otherwise, the update proceeds.

report

If set, the update operation is added to the report of duplicates.

DupeSecurityOptionType

(

enumeration of

type string)

Required. Determines how record sharing rules affect duplicate management. Valid values are:

EnforceSharingRules

Sharing rules affect duplicate management. If a duplicate rule is triggered because an insert or update duplicates an existing record, but the running user doesn’t have sharing access to that record, the insert or update proceeds. The sharing rule doesn’t prevent the user from creating or updating the record because the record is hidden from the user. No message is issued.

BypassSharingRules

Sharing rules don’t affect duplicate management. If a duplicate rule is triggered because an insert or update duplicates an existing record, sharing rules are ignored, but other access restrictions apply.

int Required. Determines the order in which duplicate rules are applied.

DuplicateRuleMatchRule

Describes the MatchingRule associated with the

DuplicateRule

. The

MatchingRule

identifies duplicate records.

344

Metadata Types DuplicateRule

Field Name

matchRuleSObjectType matchingRule objectMapping

Field Type

string string

ObjectMapping

Description

Required. The name of the target object of the matching rule. For example, if you define a duplicate rule for Contact records, and you want to match with Lead records, the value of matchRuleSObjectType is Lead.

Required. Value that corresponds to the value of developerName

in the MatchingRule

for this duplicate rule.

Required. Foreign key to an

ObjectMapping that maps fields from the

duplicate rule’s object to fields in the target object specified by matchRuleSObjectType

.

DuplicateRuleFilter

Specifies filter criteria for a DuplicateRule. Salesforce only applies the DuplicateRule if the record matches the criteria.

Field Name

booleanFilter

Field Type

string

Description

Required. A string of boolean operators that establishes the filter logic for the filter items specified in duplicateRuleFilterItems

.

duplicateRuleFilterItems

DuplicateRuleFilterItem []

Required. A list of

DuplicateRuleFilterItem components.

DuplicateRuleFilterItem

This type extends the

FilterItem type and inherits all its fields.

Field Name

sortOrder table

Field Type

int string

Description

Required. The order of this item in the duplicate rule filter.

Required. The object that has the field specified in the field

field of

DuplicateRuleFilterItem.

See the documentation for

FilterItem

for the definition of field

.

ObjectMapping

Represents a map of fields in the input object of the DuplicateRule to fields in the output object of DuplicateRule. The input object is the object associated with the DuplicateRule. The output object can be the same object or a different object with similar fields.

For example, you can have a DuplicateRule that looks for duplicates between the Contact object and the Lead object. In this case, the input object is Contact, and the output object is Lead.

Field Name

inputObject

Field Type

string

Description

Required. The input object for the duplicate rule. The DuplicateRule is associated with this object. For example, if you define a duplicate rule

345

Metadata Types DuplicateRule

Field Name

mappingFields outputObject

Field Type Description

for Contact records, and you want to match with Lead records, the value of inputObject

is Contact.

ObjectMappingField

[] Required. The mapping of source object fields to target object fields for the duplicate rule.

string Required. The output object for the duplicate rule. This value is the same as the value of the matchRuleSObjectType

field in

DuplicateRuleMatchRule

. Any duplicate rules that this object has are ignored when the DuplicateRule API uses the ObjectMapping.

ObjectMappingField

A field name in the input object of the DuplicateRule, and the corresponding field name in the output object.

Field Name

inputField outputField

Field Type

string string

Description

Required. Field in the object specified by the inputObject

field in

ObjectMapping . This field is mapped to the field in

outputField

, which is assumed to be a field in the object specified by the outputObject

field in ObjectMapping .

Required. Field in the object specified by the outputObject

field

in ObjectMapping

. The field is mapped to the field name in inputField

, which is assumed to be a field in the object specified by the inputObject

in

ObjectMapping

.

Declarative Metadata Sample Definition

The following is an example of a DuplicateRule component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<DuplicateRule xmlns= "http://soap.sforce.com/2006/04/metadata" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance">

<actionOnInsert >Allow </actionOnInsert >

<actionOnUpdate >Allow </actionOnUpdate >

<alertText >You are creating a duplicate record. Use an existing record instead.

</alertText >

<description >Detects a contact that duplicates a Lead </description >

<duplicateRuleFilter >

<booleanFilter xsi:nil= "true"/>

<duplicateRuleFilterItems >

<field >Username </field >

<operation >equals </operation >

<value >[email protected]

</value >

<sortOrder >1 </sortOrder >

<table >User </table >

</duplicateRuleFilterItems >

</duplicateRuleFilter >

346

Metadata Types EclairGeoData

<duplicateRuleMatchRules >

<matchRuleSObjectType >Lead </matchRuleSObjectType >

<matchingRule >ContactToLeadDuplicate_matching_rule </matchingRule >

<objectMapping >

<inputObject >Contact </inputObject >

<mappingFields >

<inputField >FirstName </inputField >

<outputField >FirstName </outputField >

</mappingFields >

<mappingFields >

<inputField >LastName </inputField >

<outputField >LastName </outputField >

</mappingFields >

<outputObject >Lead </outputObject >

</objectMapping >

</duplicateRuleMatchRules >

<isActive >true </isActive >

<masterLabel >ContactToLeadDuplicate </masterLabel >

<operationsOnInsert >Alert </operationsOnInsert >

<operationsOnInsert >Report </operationsOnInsert >

<operationsOnUpdate >Alert </operationsOnUpdate >

<operationsOnUpdate >Report </operationsOnUpdate >

<securityOption >EnforceSharingRules </securityOption >

<sortOrder >1 </sortOrder >

</DuplicateRule >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >ContactToLeadDuplicate </members >

<name >DuplicateRule </name >

</types >

<version >38.0

</version >

</Package >

EclairGeoData

Represents a Wave custom map chart. Custom maps are user-defined maps that are uploaded to Wave and are used just as standard maps are. Custom maps are accessed in Wave from the list of maps available with the map chart type.

File Suffix and Directory Location

EclairGeoData components have the suffix geodata

and are stored in the eclair

folder.

Version

EclairGeoData components are available in API version 39.0 and later.

347

Metadata Types

Fields

Field Name

maps masterLabel

EclairMap

Field Name

boundingBoxBottom boundingBoxLeft boundingBoxRight

Field Type

double double double boundingBoxTop mapLabel double string mapName projection string string

EclairGeoData

Field Type

EclairMap []

string

Description

A list of EclairMap objects. Each EclairMap object specifies the bounding box (if any) and the map name that appears in the user interface.

Required. Master label for this object. This display value is the internal label that is not translated.

Description

When bounding-box coordinates are used, this contains the bottom coordinate.

When bounding-box coordinates are used, this contains the left side coordinate.

When bounding-box coordinates are used, this contains the right side coordinate.

When bounding-box coordinates are used, this contains the top coordinate.

Required. The user-interface name of the map. This name appears in the maps list for the map chart in Wave.

Required. Label for this object. This display value is the internal label that is not translated.

Required. The type of map projection used to create the map. Valid values are:

•

Equirectangular

•

Mercator

•

AlbersUSA

Declarative Metadata Sample Definition

The following is an example of an EclairGeoData component:

<EclairGeoData xmlns= "http://soap.sforce.com/2006/04/metadata" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance">

<content xsi:nil= "true"/>

<maps >

<boundingBoxBottom >0.0

</boundingBoxBottom >

<boundingBoxLeft >100.0

</boundingBoxLeft >

<boundingBoxRight >100.0

</boundingBoxRight >

<boundingBoxTop >0.0

</boundingBoxTop >

<mapLabel >WorldMap0 Label </mapLabel >

<mapName >WorldMap0 </mapName >

<projection >Equirectangular </projection >

348

Metadata Types

</maps >

<maps >

<boundingBoxBottom >1.0

</boundingBoxBottom >

<boundingBoxLeft >101.0

</boundingBoxLeft >

<boundingBoxRight >101.0

</boundingBoxRight >

<boundingBoxTop >1.0

</boundingBoxTop >

<mapLabel >WorldMap1 Label </mapLabel >

<mapName >WorldMap1 </mapName >

<projection >Mercator </projection >

</maps >

<masterLabel >WorldMapGeoDataToCreate Label </masterLabel >

</EclairGeoData >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >EclairGeoData </name >

</types >

<version >39.0

</version >

</Package >

EmailTemplate

EmailTemplate

Represents an email template. This type extends the

MetadataWithContent

metadata type and inherits its content

and fullName fields.

File Suffix and Directory Location

The file suffix is

.email

for the template file. The accompanying metadata file is named

EmailTemplateName-meta.xml

.

EmailTemplate components are stored in the email

folder in the corresponding package directory. For example, for an email template named SampleTemplate in the sampleFolder folder, there’s a

SampleTemplate-meta.xml

in the email/sampleFolder of the package.

Retrieving Email Templates

You can’t use the wildcard (*) symbol with email templates in package.xml

. To retrieve the list of email templates for populating package.xml

with explicit names, call listMetadata()

and pass in

EmailTemplate

as the type.

The following example shows folders in package.xml

:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >MyDBFolder/MyDBName </members >

<name >Dashboard </name >

349

Metadata Types EmailTemplate

</types >

<types >

<members >MyDocumentFolder/MyDocumentName </members >

<name >Document </name >

</types >

<types >

<members >unfiled$public/MarketingProductInquiryResponse </members >

<members >unfiled$public/SalesNewCustomerEmail </members >

<name >EmailTemplate </name >

</types >

<types >

<members >MyReportFolder/MyReportName </members >

<name >Report </name >

</types >

<version >39.0

</version >

</Package >

Version

Email templates are available in API version 12.0 and later.

Fields

This metadata type contains the following fields:

Field Name

apiVersion

Field Type

double attachedDocuments string[] attachments available content

Attachment

[] boolean base64Binary

Description

The API version if this is a Visualforce email template. Every Visualforce email template has an API version specified at creation. This field is available in API version 16.0 and later.

A list of references to documents in your organization. These documents are included as attachments in the email template. Each document is referenced by its path, for example

MyFolder/MyDocument.txt

.

A list of attachments for the email template.

Required. Indicates whether this template is offered to users when sending an email ( true

) or not ( false

).

Content of the email template. 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. This field contains:

•

Binary content of the email body if

type

is set to text

•

HTML email content if type

is set to html

•

HTML body if type

is set to

custom

•

Visualforce body if

type

is set to

visualforce

This field is inherited from the MetadataWithContent

component.

350

Metadata Types EmailTemplate

Field Name

description encodingKey fullName letterhead name packageVersions

Field Type

string

Encoding ( enumeration

of type string)

Description

The email template description. This can be useful to describe the reason for creating the template.

Required. The default encoding setting is Unicode:

UTF-8

. Change it if your template requires data in a different format.

Valid values include:

•

UTF-8

—Unicode (UTF-8)

•

ISO-8859-1

—General US & Western Europe (ISO-8859–1, ISO-LATIN-1)

•

Shift_JIS

—Japanese (Shift-JIS)

•

ISO-2022-JP

—Japanese (JIS)

•

EUC-JP

—Japanese (EUC-JP)

•

x-SJIS_0213

—Japanese (Shift-JIS_2004)

•

ks_c_5601-1987

—Korean (ks_c_5601-1987)

•

Big5

—Traditional Chinese (Big5)

•

GB2312

—Simplified Chinese (GB2312)

•

Big5-HKSCS

—Traditional Chinese Hong Kong (Big5–HKSCS) string string string

PackageVersion

[]

The email template 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. If this field contained characters before version 14.0 that are no longer allowed, the characters were stripped out of this field, and the previous value of the field was saved in the

name

field. This field is inherited from the Metadata

component.

The letterhead name associated with this email template. Only available when

type

is set to

html

.

Required. Email template name. The list of characters allowed in the fullName

field has been reduced for versions 14.0 and later. This field contains the value contained in the

fullName

field before version 14.0.

The list of package versions for any managed packages containing components that are referenced by this email template. This field is only relevant for Visualforce email templates.

For more information about managed packages, see the Force.com Quick

Reference for Developing Packages . For more information about package versions, see “About Package Versions” in the Salesforce online help. This field is available in API version 16.0 and later.

style

EmailTemplateStyle

(

enumeration

of type string)

Required. The style of the template. This field is only available when

type

is set to html

.

Valid style values include:

•

none

•

freeForm

351

Metadata Types

Field Name

subject textOnly type

EmailTemplate

Field Type

string string

EmailTemplateType

(

enumeration

of type string)

Description

•

formalLetter

•

promotionRight

•

promotionLeft

•

newsletter

•

products

The email subject.

The text of the email body if type

is set to html

or custom

.

Required. The email template type.

The valid values are:

•

text

-all users can create or change text email templates.

•

html

- administrators and users with the “Edit HTML Templates” permission can create HTML email templates based on a letterhead.

•

custom

- administrators and users with the “Edit HTML Templates” permission can create custom HTML email templates without using a letterhead. You must either know HTML or obtain the HTML code to insert in your email template.

•

visualforce

- administrators and users with the “Customize Application” permission can create email templates using Visualforce.

Attachment

Attachment represents an email attachment.

Field

content name

Field Type

base64Binary string

Description

Required. The attachment content. 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.

Required. The attachment file name.

Declarative Metadata Sample Definition

A sample XML definition of an email template is shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<EmailTemplate xmlns= "http://soap.sforce.com/2006/04/metadata">

<available >true </available >

<description >Sample Email Template </description >

352

Metadata Types EntitlementProcess

<encodingKey >ISO-8859-1 </encodingKey >

<name >Sample Email Template </name >

<style >none </style >

<subject >Sample email subject </subject >

<textOnly >Your case has been resolved.

</textOnly >

<type >custom </type >

</EmailTemplate >

SEE ALSO:

Letterhead

EntitlementProcess

Represents the settings for an entitlement process. This type extends the Metadata

metadata type and inherits its fullName

field.

File Suffix and Directory Location

Entitlement process values are stored in files in the entitlementProcesses

directory. Each file has the name of a process and the suffix

.entitlementProcess

. Each file contains one entitlement process or, if entitlement versioning is enabled, one version of an entitlement process. The name of the file is the name of the entitlement process with the version appended to the end, if applicable

(for example, an entitlement process named ”gold_support” might have the file name “gold_support_v2.entitlementProcess”). This file name corresponds to the slaProcess.NameNorm

field exposed through the SOAP API. This file name is distinct from the name field, which represents what displays in the user interface and, if versioning is enabled, might be shared among multiple versions of the same entitlement process.

Version

Entitlement processes are available in API version 27.0 and later.

Fields

Field Name

active

Field Type

boolean businessHours description entryStartDateField string string string

Description

Indicates whether the entitlement process is active

( true

) or not ( false

).

The business hours that apply to the entitlement process.

This field is available in API version 30.0 and later.

The description of the entitlement process.

For milestone processes on which a case enters the process based on a custom date/time field on the case, specifies which date and time are used. Valid values are:

•

SlaStartDate (entitlement process start date)

•

CreatedDate (date case was opened)

353

Metadata Types EntitlementProcess

Field Name

exitCriteriaBooleanFilter exitCriteriaFilterItems exitCriteriaFormula isVersionDefault milestones name

SObjectType versionMaster versionNotes versionNumber

Field Type

string

FilterItem []

string boolean

EntitlementProcessMilestoneItem

[] string string string string int

Description

•

ClosedDate (date case was closed)

•

LastModifiedDate (date case was last modified)

•

StopStartDate (date case was stopped)

For milestone processes on which a case exits the process when custom criteria are met, and for which filter logic is added, specifies that logic.

For milestone processes on which a case exits the process when custom criteria are met, specifies those criteria.

For milestone processes on which a case exits the process when a custom formula evaluates to true, specifies that formula.

Indicates whether the entitlement process is the default version ( true

) or not ( false

).

This field is available in API version 28.0 and later.

Represents a milestone on the entitlement process.

The name of the entitlement process as it displays in the user interface.

Indicates the type of record that the entitlement process can run on.

Identifies the sequence of versions to which this entitlement process belongs. This field’s contents can be any value as long as it is identical among all versions of the entitlement process.

This field is available in API version 28.0 and later.

The description of the entitlement process version.

This field is available in API version 28.0 and later.

The version number of the entitlement process. Must be

1 or greater.

This field is available in API version 28.0 and later.

EntitlementProcessMilestoneItem

Represents a milestone item on an entitlement process.

354

Metadata Types EntitlementProcess

Fields

Field Name

businessHours

Field Type

string

Description

The business hours that apply to the milestone.

This field is available in API version 30.0 and later.

criteriaBooleanFilter milestoneCriteriaFilterItems string

FilterItem []

For milestones that apply only when criteria are met and for which filter logic is added, specifies that logic.

For milestones that apply only when criteria are met, specifies those criteria.

milestoneCriteriaFormula milestoneName minutesCustomClass minutesToComplete successActions timeTriggers useCriteriaStartTime string For milestones that apply only when a formula evaluates to true, specifies that formula.

The name of the milestone.

string string int

The name of the Apex class that is used to calculate the trigger time. This field is available in API version

30.0 and later.

The number of minutes from when the case enters the entitlement process that the milestone occurs.

The actions triggered when the milestone is completed.

WorkflowActionReference

[]

EntitlementProcessMilestoneTimeTrigger []

The time triggers on an entitlement process milestone.

boolean When the milestone starts: when the milestone criteria are met (true) or when the case enters the entitlement process (false).

EntitlementProcessMilestoneTimeTrigger

Represents the time trigger on an entitlement process milestone.

Fields

Field Name

actions timeLength

Field Type Description

WorkflowActionReference []

The actions to take when the time trigger is reached, if, at that time, the milestone is not completed.

int The length of time between the time trigger activation and the milestone target completion date. This may be a negative or positive value. Negative values indicate that the target completion date has not yet arrived and correspond to warning time triggers. Positive values indicate that the target completion date has passed and correspond to violation time triggers.

355

Metadata Types EntitlementProcess

Field Name Field Type

workflowTimeTriggerUnit

MilestoneTimeUnits

(

enumeration

of type string)

Description

Specifies the type of unit used to determine when a workflow should be triggered. Valid values are:

•

Minutes

•

Hours

•

Days

Declarative Metadata Sample Definition

This is a sample entitlement process.

<?xml

version= "1.0" encoding= "UTF-8"?>

<EntitlementProcess xmlns= "http://soap.sforce.com/2006/04/metadata">

<active >true </active >

<description >eppersone </description >

<entryStartDateField >SlaStartDate </entryStartDateField >

<exitCriteriaBooleanFilter >1 OR 2 </exitCriteriaBooleanFilter >

<exitCriteriaFilterItems >

<field >Case.IsClosed

</field >

<operation >equals </operation >

<value >true </value >

</exitCriteriaFilterItems >

<exitCriteriaFilterItems >

<field >Case.Description

</field >

<operation >startsWith </operation >

<value >foo </value >

</exitCriteriaFilterItems >

<milestones >

<milestoneName >m1 </milestoneName >

<minutesToComplete >1 </minutesToComplete >

<successActions >

<name >emailBob </name >

<type >Alert </type >

</successActions >

<timeTriggers >

<actions >

<name >emailAlice </name >

<type >Alert </type >

</actions >

<actions >

<name >setEscalateToTrue </name >

<type >FieldUpdate </type >

</actions >

<timeLength >1 </timeLength >

<workflowTimeTriggerUnit >Minutes </workflowTimeTriggerUnit >

</timeTriggers >

<timeTriggers >

<actions >

<name >setStopToTrue </name >

<type >FieldUpdate </type >

356

Metadata Types EntitlementTemplate

</actions >

<timeLength >2 </timeLength >

<workflowTimeTriggerUnit >Minutes </workflowTimeTriggerUnit >

</timeTriggers >

<useCriteriaStartTime >false </useCriteriaStartTime >

</milestones >

<milestones >

<milestoneCriteriaFilterItems >

<field >Case.Priority

</field >

<operation >equals </operation >

<value >High </value >

</milestoneCriteriaFilterItems >

<milestoneName >m2 </milestoneName >

<minutesToComplete >120 </minutesToComplete >

<useCriteriaStartTime >true </useCriteriaStartTime >

<successActions >

<name >emailBob </name >

<type >Alert </type >

</successActions >

</milestones >

</EntitlementProcess >

EntitlementTemplate

Represents an entitlement template. Entitlement templates are predefined terms of customer support that you can quickly add to products. For example, you can create entitlement templates for Web or phone support so that users can easily add entitlements to products offered to customers. EntitlementTemplate extends the

Metadata

metadata type and inherits its fullName

field.

Declarative Metadata File Suffix and Directory Location

EntitlementTemplate components are stored in the entitlementTemplates

directory of the corresponding package directory.

The file name matches the unique name of the entitlement template, and the extension is

.entitlementTemplate

.

Version

Force.com EntitlementTemplate components are available in API version 18.0 and higher.

Fields

Field

businessHours casesPerEntitlement entitlementProcess isPerIncident

Field Type

string int string boolean

Description

The entitlement's supported business hours.

Lets you limit the number of cases the entitlement supports.

The entitlement process associated with the entitlement.

true

if entitlements created from this template service a limited number of cases; false

otherwise.

357

Metadata Types EscalationRules

Field

term type

Field Type

int string

Description

The number of days the entitlement is in effect.

The type of entitlement, such as Web or phone support.

Declarative Metadata Sample Definition

A sample XML definition of an entitlement template is shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<EntitlementTemplate xmlns= "http://soap.sforce.com/2006/04/metadata">

<businessHours >AlternateBusinessHours </businessHours >

<casesPerEntitlement >12 </casesPerEntitlement >

<entitlementProcess >Process1 </entitlementProcess >

<isPerIncident >true </isPerIncident >

<term >33 </term >

<type >Phone Support </type >

</EntitlementTemplate >

EscalationRules

Represents case escalation rules to escalate cases automatically if they are not resolved within a certain period of time. You can access rules metadata for all applicable objects, for a specific object, or for a specific rule on a specific object. The package.xml

syntax for accessing all escalation rules for all objects is:

<types>

<members>*</members>

<name>EscalationRules</name>

</types>

All rules for a specific object uses a similar syntax without the wildcard. For example, all escalation rules for the Case object would use this syntax:

<types>

<members>Case</members>

<name>EscalationRules</name>

</types>

You can also access specific escalation rules for an object. The following example only accesses the “samplerule” and “newrule” escalation rules on the Case object. Notice that for this example the type name syntax is

EscalationRule

and not

EscalationRules

.

<types>

<members>Case.samplerule</members>

<members>Case.newrule</members>

<name>EscalationRule</name>

</types>

File Suffix and Directory Location

EscalationRules for an object have the suffix

.escalationRules

and are stored in the escalationRules

folder. For example, all Case escalation rules are stored in the

Case.escalationRules

file.

358

Metadata Types EscalationRules

Version

EscalationRules components are available in API version 27.0 and later.

Fields

Field Name

escalationRule

Field Type

EscalationRule[]

Description

Represents one escalation rule and specifies whether it is active or not. Escalation rules are processed in the order they appear in the

EscalationRules container.

EscalationRule

Field Name

active fullname ruleEntry

Field Type

boolean string

RuleEntry[]

Description

Indicates whether the escalation rule is active ( true

) or not ( false

).

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.

This value cannot be null

.

Contains the definitions of the rule entries in the escalation rule.

RuleEntry

Represents the fields used by the rule.

Field Name

booleanFilter businessHours businessHoursSource criteriaItems

Field Type

string

Description

Advanced filter conditions that were specified for the rule.

string The hours at which escalation actions are performed. Specify only if businessHoursSource

is set to

Static

.

BusinessHoursSourceType

(

enumeration

of type string)

Valid values are:

•

None

•

Case

•

Static

FilterItem

disableEscalationWhenModified boolean

The items in the list that define the assignment criteria.

Indicates whether the escalation is disabled when the record is modified true

) or not ( false

).

359

Metadata Types

Field Name

escalationAction escalationStartTime formula

EscalationRules

Field Type Description

EscalationAction[]

on page 360

The actions to perform when the escalation criteria are met.

EscalationStartTimeType

(

enumeration

of type string)

Indicates the start time for the escalation. Valid values are:

•

CaseCreation

•

CaseLastModified string The validation formula.

Note: Specify either formula

or criteriaItems

, but not both fields.

EscalationAction

Describes the action to take for an escalation rule.

Field Name

assignedTo assignedToTemplate assignedToType minutesToEscalation notifyCaseOwner notifyEmail notifyTo notifyToTemplate

Field Type

string string

Description

The name of the user or queue the item is assigned to.

Specifies the template to use for the email that is automatically sent to the new owner specified by the escalation rule.

AssignToLookupValueType

(

enumeration

of type string)

Valid values are:

•

User

•

Queue int boolean string string string

The number of minutes until the escalation occurs.

Indicates that the owner of the case is notified when the case is escalated true

) or not ( false

).

Specifies the email address of the user to notify.

Specifies the user to notify.

Specifies the template to user for the notification email.

Declarative Metadata Sample Definition

The following is an example EscalationRules component:

<EscalationRules xmlns= "http://soap.sforce.com/2006/04/metadata">

<escalationRule >

<fullName >samplerule </fullName >

<active >false </active >

<ruleEntry >

<businessHours >test </businessHours >

360

Metadata Types ExternalDataSource

<businessHoursSource >Static </businessHoursSource >

<criteriaItems >

<field >Case.Description

</field >

<operation >contains </operation >

<value >test </value >

</criteriaItems >

<escalationAction >

<assignedTo >[email protected]

</assignedTo >

<assignedToTemplate >emailtemplatename </assignedToTemplate >

<assignedToType >User </assignedToType >

<minutesToEscalation >1440 </minutesToEscalation >

<notifyCaseOwner >false </notifyCaseOwner >

</escalationAction >

<escalationStartTime >CaseLastModified </escalationStartTime >

</ruleEntry >

</escalationRule >

</EscalationRules >

ExternalDataSource

Represents the metadata associated with an external data source. Create external data sources to manage connection details for integration with data and content that are stored outside your Salesforce org.

This type extends the

Metadata metadata type and inherits its

fullName

field.

File Suffix and Directory Location

ExternalDataSource components are stored in the dataSources

directory of the corresponding package directory. ExternalDataSource components have the suffix

.dataSource

, and the prefix is the name of the external data source.

Version

ExternalDataSource components are available in API version 28.0 and later.

Fields

Field Name

authProvider

Field Type

string certificate customConfiguration string string

Description

The authentication provider that is represented by the AuthProvider component.

If you specify a certificate, your Salesforce org supplies it when establishing each two-way SSL connection with the external system.

The certificate is used for digital signatures, which verify that requests are coming from your Salesforce org.

A string of configuration parameters that are specific to the external data source’s type

.

•

customConfiguration for Salesforce Connect—Cross-Org Adapter

361

Metadata Types

Field Name

endpoint isWritable label oauthRefreshToken oauthScope oauthToken password principalType

ExternalDataSource

Field Type

string

Description

•

customConfiguration for Salesforce Connect—OData 2.0 or 4.0

Adapter

•

customConfiguration for Salesforce Connect—Custom Adapter

The URL of the external system, or if that URL is defined in a named credential, the named credential URL. Corresponds to

URL

in the user interface.

A named credential URL contains the scheme callout:

, the name of the named credential, and an optional path. For example: callout:My_Named_Credential/some_path

.

You can append a query string to a named credential URL. Use a question mark (?) as the separator between the named credential URL and the query string. For example: callout:My_Named_Credential/some_path?format=json

.

boolean string

Lets the Force.com platform and users in this org create, update, and delete records for external objects associated with the external data source. The external object data is stored outside the org. By default, external objects are read only. Corresponds to

Writable External

Objects

in the user interface.

Available in API version 35.0 and later. However, with the cross-org adapter for Salesforce Connect, you can set this field to true

only in

API version 39.0 and later.

A user-friendly name for the external data source. The label is displayed in the Salesforce user interface, such as in list views.

Examples include Acme Team Marketing Site, or Acme SharePoint.

string string

The OAuth refresh token. Used to obtain a new access token for an end user when a token expires.

Specifies the scope of permissions to request for the access token.

Corresponds to

Scope

in the user interface.

The access token issued by the external system.

string string The password to be used by your org to access the external system.

Ensure that the credentials you use have adequate privileges to access the external system, perform searches, return data, and return information about the external system’s metadata.

External

PrincipalType

(

enumeration of

type string)

Determines whether you're using one set or multiple sets of credentials to access the external system. Corresponds to

Identity Type

in the user interface. The valid values are:

•

Anonymous

•

PerUser

362

Metadata Types

Field Name

protocol repository type username version

ExternalDataSource

Field Type

Authentication

Protocol

(

enumeration of

type string)

The authentication protocol that’s required to access the external system.

The valid values are:

•

NoAuthentication

•

Oauth

•

Password

For cloud-based Files Connect external systems, select Oauth 2.0. For on-premises systems, select Password Authentication.

For Simple URL data sources, select No Authentication.

string Used for SharePoint Online. If metadata is not accessible, use this field to create tables and default table fields.

ExternalData

SourceType

(

enumeration of

type string)

For Salesforce Connect, specifies the adapter that connects to the external system. The valid values are:

•

OData

—OData 2.0 adapter

•

OData4

—OData 4.0 adapter

•

SfdcOrg

—cross-org adapter

•

ApexClassId

—

DataSource.Provider

class that defines the custom adapter created via the Apex Connector Framework

For Files Connect, specifies the data source type. The valid values are:

•

ContentHubSharepoint

—SharePoint 2010 or 2013

•

ContentHubSharepointOffice365

—SharePoint Online

•

ContentHubSharepointOneDrive

—OneDrive for Business

•

ContentHubGDrive

—Google Drive

If Chatter is enabled, you can also specify

SimpleURL

to access data hosted on a web server that doesn’t require authentication.

•

outgoingemail

—A data source used for sending an email through a quick action.

The

Identity

and

Wrapper

types are reserved for future use.

string string

Description

•

NamedUser

The username to be used by your org to access the external system.

Ensure that the credentials you use have adequate privileges to access the external system, perform searches, return data, and return information about the external system’s metadata.

Reserved for future use.

363

Metadata Types ExternalDataSource

customConfiguration

for Salesforce Connect—Cross-Org Adapter

The following sample JSON-encoded configuration string defines parameters that apply when the external data source’s type

is set to

SfdcOrg

.

{"apiVersion":"32.0","environment":"CUSTOM",

"searchEnabled":"true","timeout":"120"}

The parameters correspond to these fields in the user interface:

•

apiVersion

—

API Version

•

environment

—

Connect to

•

searchEnabled

—

Enable Search

•

timeout

—

Connection Timeout

customConfiguration

for Salesforce Connect—OData 2.0 or 4.0 Adapter

The following JSON-encoded configuration string defines parameters that apply when the external data source’s type

is set to

OData or

OData4

.

{"inlineCountEnabled":"true","csrfTokenName":"X-CSRF-Token",

"requestCompression":"false","pagination":"CLIENT",

"noIdMapping":"false","format":"ATOM",

"searchFunc":"","compatibility":"DEFAULT",

"csrfTokenEnabled":"true","timeout":"120",

"searchEnabled":"true"}

The parameters correspond to these fields in the user interface.

•

compatibility

—

Special Compatibility

•

csrfTokenEnabled

—

CSRF Protection

•

csrfTokenName

—

Anti-CSRF Token Name

•

format

—

Format

•

inlineCountEnabled

—

Request Row Counts

•

noIdMapping

—

High Data Volume

•

pagination

—

Server Driven Pagination

•

requestCompression

—

Compress Requests

•

searchEnabled

—

Enable Search

•

searchFunc

—

Custom Query Option for Salesforce Search

•

timeout

—

Connection Timeout

customConfiguration

for Salesforce Connect—Custom Adapter

The following sample JSON-encoded configuration string defines the parameter that applies when the external data source’s type

is set to the ID of a

DataSource.Provider

class.

{"noIdMapping":"false"}

The noIdMapping

parameter corresponds to the

High Data Volume

field in the user interface.

364

Metadata Types

Declarative Metadata Sample Definition

The following is the definition of an external data source for Salesforce Connect—OData 2.0 or 4.0 adapter.

<?xml

version= "1.0" encoding= "UTF-8"?>

<ExternalDataSource xmlns= "http://soap.sforce.com/2006/04/metadata">

<authProvider >FacebookAuth </authProvider >

<customConfiguration >{"compatibility":"DEFAULT",

"noIdMapping":"false","inlineCountEnabled":"true",

"searchEnabled":"true","format":"ATOM",

"requestCompression":"false","pagination":"SERVER",

"timeout":"120"} </customConfiguration >

<endpoint >http://myappname.herokuapp.com/DataHub.svc

</endpoint >

<label >DataHub </label >

<principalType >NamedUser </principalType >

<protocol >Oauth </protocol >

<type >OData </type >

</ExternalDataSource >

FlexiPage

Represents the metadata associated with a Lightning Page. A Lightning Page represents a customizable screen containing Lightning components.

Lightning Pages are used in several places.

•

In Salesforce1, a Lightning Page is the home page for an app that appears in the navigation menu.

•

In Lightning Experience, Lightning Pages can be used as the home page for an app, and to customize the layout of record pages and the Home page.

This type extends the

Metadata metadata type and inherits its

fullName

field.

Note: These pages are known as FlexiPages in the API, but are referred to as Lightning Pages in the rest of the Salesforce documentation and UI.

For more information on Lightning Pages, see the Salesforce Help.

File Suffix and Directory Location

FlexiPage components have the suffix

.flexipage

and are stored in the flexipages

folder.

Version

FlexiPage components are available in API version 29.0 and later.

Fields

Field Name

description flexiPageRegions

Field Type

string

FlexiPageRegion []

Description

The optional description text of the Lightning Page.

Required. The list of regions of a page.

FlexiPage

365

Metadata Types

Field Name

masterLabel pageTemplate parentFlexiPage platformActionList quickActionList sobjectType template type

FlexiPage

Field Type

string string string

Description

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

Deprecated. Use this field in API versions 33.0 to 38.0 only. In later versions, use template

.

Required. The template associated with the FlexiPage.

The name of the FlexiPage that this page inherits behavior from.

This field is available in API version 37.0 or later.

PlatformActionList

QuickActionList

string

The list of all actions, and their order, that display on the

Lightning Page. In Salesforce1, the actions appear in the action bar.

This field is available in API version 34.0 and later.

The list of quick actions associated with the Lightning Page.

The object the FlexiPage is associated with. For Lightning Pages of type

AppPage

or

HomePage

, this field is null

.

After the value of this field is set, it can’t be changed.

This field is available in API version 37.0 or later.

FlexiPageTemplateInstance

Required. The template associated with the FlexiPage.

This field is available in API version 39.0 and later.

FlexiPageType (

enumeration

of type string)

Required. The type of a page. In API versions 32.0 through 36.0, this field can only have a value of

AppPage

.

Valid values are:

•

AppPage

—A Lightning Page that is used as the home page for a custom app.

•

CommAppPage

—A Lightning Page that is used to represent a custom page, as created in the Community

Builder, in Communities. This value is available in API version 37.0 and later.

•

CommForgotPasswordPage

—A Lightning Page that’s used to override a forgot-password page, as created in Community Builder, in Communities. This value is available in API version 39.0 and later.

•

CommLoginPage

—A Lightning Page that’s used to override the login page, as created in Community Builder, in Communities. This value is available in API version 39.0

and later.

•

CommObjectPage

—A Lightning Page used to override an object page, as created in Community Builder, in

366

Metadata Types

Field Name Field Type

FlexiPage

Description

Communities. This value is available in API version 38.0

and later.

•

CommQuickActionCreatePage

—A Lightning

Page used to override the create record page, as created in Community Builder, in Communities. This value is available in API version 38.0 and later.

•

CommRecordPage

—A Lightning Page used to override a record page , as created in the Community Builder, in

Communities. This value is available in API version 38.0

and later.

•

CommRelatedListPage

—A Lightning Page used to override a related list page, as created in the Community

Builder, in Communities. This value is available in API version 38.0 and later.

•

CommSearchResultPage

—A Lightning Page used to override the search result page, as created in

Community Builder, in Communities. This value is available in API version 38.0 and later.

•

CommSelfRegisterPage

—A Lightning Page used to override the self-registration page, as created in

Community Builder, in Communities. This value is available in API version 39.0 and later.

•

CommThemeLayoutPage

—A Lightning Page used to override a theme layout page, as created in the

Community Builder, in Communities. This value is available in API version 38.0 and later.

•

HomePage

—A Lightning Page that is used to override the Home page in Lightning Experience. This value is available in API version 37.0 and later.

•

MailAppAppPage

—An email application pane used to override the default layout for Lightning for Outlook.

This value is available in API version 38.0 and later.

•

RecordPage

—A Lightning Page used to override an object record page in Lightning Experience. This value is available in API version 37.0 and later.

•

UtilityBar

—A Lightning Page used as the utility bar in Lightning Experience apps. This value is available in API version 38.0 and later.

This field is available in API version 32.0 and later.

367

Metadata Types

FlexiPageRegion

FlexiPage Region represents the properties of a region of a page. A region can contain a record list component or a recent items component that can be scoped to a set of entities.

Field Name

appendable componentInstances mode name prependable replaceable type

Field Type

RegionFlagStatus

( enumeration

of type string)

Description

This field is reserved for future use.

Valid values are:

•

disabled

•

enabled

This field is available in API version 35.0 or later.

ComponentInstance

[]

FlexiPageRegionMode

( enumeration

of type string)

Properties and name of the component instance.

This field is reserved for future use.

Valid values are:

•

Append

•

Prepend

•

Replace

This field is available in API version 35.0 or later.

string

RegionFlagStatus

( enumeration

of type string)

Required. Unique name of the FlexiPage region.

This field is reserved for future use.

Valid values are:

•

disabled

•

enabled

This field is available in API version 35.0 or later.

RegionFlagStatus

( enumeration

of type string)

This field is reserved for future use.

Valid values are:

•

disabled

•

enabled

This field is available in API version 35.0 or later.

FlexiPageRegionType

( enumeration

of type string)

Required. The type of FlexiPage region.

Valid values are:

•

Facet

•

Region

This field is available in API version 35.0 or later.

FlexiPage

368

Metadata Types

ComponentInstance

Instance of a component in a page, such as a filter list.

Field Name Field Type

componentInstanceProperties

ComponentInstanceProperty []

componentName string

FlexiPage

Description

The value of a single property in a component instance.

A component instance can have no properties.

Required. The name of a single instance of a component.

ComponentInstanceProperty

Value of a single property in a component instance.

Field Name

name type value

Field Type

string

Description

Name of the property, unique within the component instance.

For Lightning components, this value is the

<aura:attribute>

as defined in the

.cmp

file.

ComponentInstancePropertyTypeEnum

(

enumeration

of type string)

If this field value is null

, then the

ComponentInstanceProperty values apply to the Lightning component. If this field value is decorator

, then the

ComponentInstanceProperty values apply to the component

decorator for the Lightning component.

The component decorator is a wrapper around a Lightning component. The decorator can apply additional capabilities to the component when it renders on a specific page in

Lightning Experience. For example, you can configure a component decorator around a component on the Lightning

Experience utility bar to set the component’s height or width when opened. The

UtilityBar

is the only page type that supports component decorators.

Valid values are:

•

decorator

This field is available in API version 38.0 or later.

string Reference or value of the property.

When defining a Related List component, to use a parent record set the parentFieldApiName

value to

object.field_name

. If you don’t want to use a parent record, set the value to

object.Id

.

When you give a standard label to a tab in a Tabs component—such as Activity, Collaborate, or Details—and when the name

field is set to title

, the value

field uses a system-defined value instead of the label. Here are some examples of the system-defined values:

369

Metadata Types

•

Standard.Tab.activity

•

Standard.Tab.collaborate

•

Standard.Tab.detail

•

Standard.Tab.feed

•

Standard.Tab.preview

•

Standard.Tab.relatedLists

For example, let’s say you have a Lightning Page that contains a tab with the standard label “Activity”. If you query the definition that page, you see the system-defined name of the tab, not the label, in value

.

<componentInstances>

<componentInstanceProperties>

<name>title</name>

<value>Standard.Tab.activity</value>

</componentInstanceProperties>

<componentName>flexipage:tab</componentName>

</componentInstances>

PlatformActionList

PlatformActionList represents the list of actions, and their order, that display on the Lightning Page. Available in API version 34.0 and later.

Field Name

actionListContext

Field Type Description

PlatformActionListContext

(

enumeration of

type string)

Required. The context of the action list. Valid values are:

•

Assistant

•

BannerPhoto

•

Chatter

•

Dockable

•

FeedElement

•

FlexiPage

•

Global

•

ListView

•

ListViewDefinition

•

ListViewRecord

•

Lookup

•

MruList

•

MruRow

•

ObjectHomeChart

•

Photo

•

Record

•

RecordEdit

•

RelatedList

•

RelatedListRecord

FlexiPage

370

Metadata Types FlexiPage

Field Name

platformActionListItems relatedSourceEntity

Field Type Description

PlatformActionListItem []

The actions in the PlatformActionList.

string When the

ActionListContext

is RelatedList or RelatedListRecord, this field represents the API name of the related list to which the action belongs.

PlatformActionListItem

PlatformActionListItem represents an action in the PlatformActionList. Available in API version 34.0 and later.

Field Name

actionName actionType sortOrder subtype

Field Type

string

Description

The API name for the action in the list.

PlatformActionType

( enumeration of type

string)

The type of action. Valid values are:

•

ActionLink

—An indicator on a feed element that targets an API, a web page, or a file, represented by a button in the Salesforce Chatter feed

UI.

•

CustomButton

—When clicked, opens a URL or a Visualforce page in a window or executes JavaScript.

•

InvocableAction

•

ProductivityAction

—Productivity actions are predefined by

Salesforce and are attached to a limited set of objects. You can’t edit or delete productivity actions.

•

QuickAction

—A global or object-specific action.

•

StandardButton

—A predefined Salesforce button such as New, Edit, and Delete.

int string

The placement of the action in the list.

The subtype of the action. For quick actions, the subtype is

QuickActionType

. For custom buttons, the subtype is

WebLinkTypeEnum

. For action links, subtypes are

Api

,

ApiAsync

,

Download

, and

Ui

. Standard buttons and productivity actions have no subtype.

FlexiPageTemplateInstance

FlexiPageTemplateInstance represents an instance of a FlexiPage template.

Field Name

name

Field Type

string

Description

Required. The name of a single instance of a template.

371

Metadata Types

Field Name

properties

FlexiPage

Field Type

ComponentInstanceProperty []

Description

The value of a single property in a template instance.

Valid only for

CommThemeLayoutPage

. Contains a name and value pair for each theme layout property associated with the FlexiPage template. In Community

Builder, the theme layout and its properties appear in the Theme area.

Declarative Metadata Sample Definition

Here’s a sample XML FlexiPage component definition for a travel app that tracks the user’s trips, expense reports, and other relevant data:

<?xml

version= "1.0" encoding= "UTF-8"?>

<FlexiPage xmlns= "http://soap.sforce.com/2006/04/metadata">

<description >Page to view recent trips </description >

<flexiPageRegions >

<componentInstances >

<componentInstanceProperties >

<name >entityName </name >

<value >Trips__c </value >

</componentInstanceProperties >

<componentInstanceProperties >

<name >filterName </name >

<value >My_Trips </value >

</componentInstanceProperties >

<componentName >flexipage:filterListCard </componentName >

</componentInstances >

<componentInstances >

<componentInstanceProperties >

<name >entityName </name >

<value >Expense_Report__c </value >

</componentInstanceProperties >

<componentInstanceProperties >

<name >filterName </name >

<value >My_Reports </value >

</componentInstanceProperties >

<componentName >flexipage:filterListCard </componentName >

</componentInstances >

<componentInstances >

<componentInstanceProperties >

<name >entityNames </name >

<value >["User","Trips__c","Expense__c","Receipt__c"] </value >

</componentInstanceProperties >

<componentName >flexipage:recentItems </componentName >

</componentInstances >

<name >main </name >

</flexiPageRegions >

<masterLabel >My Travel, Inc.

</masterLabel >

<quickActionList >

<quickActionListItems >

372

Metadata Types

<quickActionName >customAction1 </quickActionName >

</quickActionListItems >

<quickActionListItems >

<quickActionName >customAction2 </quickActionName >

</quickActionListItems >

</quickActionList >

<type >AppPage </type >

</FlexiPage >

And, here’s the sample package.xml

file that references the FlexiPage component definition:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<fullName >Travel, Inc.

</fullName >

<types >

<members >TravelIncFlexiPage </members >

<name >CustomTab </name >

</types >

<types >

<members >TravelIncFlexiPage </members >

<name >FlexiPage </name >

</types >

<types >

<members >TravelIncQuickActions </members >

<name >QuickAction </name >

</types >

<version >29.0

</version >

</Package >

Flow

Represents the metadata associated with a flow. With Flow, you can create an application that navigates users through a series of screens to query and update records in the database. You can also execute logic and provide branching capability based on user input to build dynamic applications. For information about the corresponding UI-based flow building tool, see “Cloud Flow Designer” in the Salesforce

Help.

When using the file-based Metadata API to work with flows, consider that:

•

You can’t use Metadata API to access a flow installed from a managed package.

•

Flow filenames shouldn’t contain spaces, which can cause errors at deployment. Heading and trailing spaces are allowed, but are trimmed during deployment.

•

You can’t overwrite an active flow or one that was once active when deploying a flow using Metadata API.

•

You can create a new version of a flow by giving the file a new version number and deploying it.

Warning:

Don't edit the metadata of retrieved Process Builder processes (Flow components whose processType is Workflow or

InvocableProcess.) If you deploy process metadata that you've edited, you might not be able to open the process in the target org.

Declarative Metadata File Suffix and Directory Location

Flows are stored in the

Flow

directory of the corresponding package directory. The file name matches the flow’s unique full name, and the extension is

.flow

.

373

Flow

Metadata Types

Version

The flow Metadata API is available in API version 24.0 and later.

Flow

This metadata type represents a valid definition of a flow. This type extends the

Metadata metadata type and inherits its

fullName field.

Field Name

actionCalls apexPluginCalls assignments choices constants decisions description dynamicChoiceSets formulas fullName interviewLabel label

Field Type

FlowActionCall

[]

FlowApexPluginCall

[]

FlowAssignment

[]

FlowChoice

[]

FlowConstant

[]

FlowDecision []

string

FlowDynamicChoiceSet

[]

FlowFormula

[] string string string

Description

An array of nodes that define calls to actions. This field is available in API version 31.0 and later.

An array of nodes that define calls to Apex plug-ins.

An array of assignment nodes.

An array of static choice options.

An array of constants.

An array of decision nodes.

Description of the flow.

An array that constructs a set of choice options based on a database lookup.

An array of formulas.

Required; inherited from the Metadata component. Name of the file in Metadata API.

The fullName

consists of two parts, separated by a hyphen:

•

Unique name for the flow that contains only underscores and alphanumeric characters. It must be unique across the organization, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.

•

Version number for the flow.

For example, “sampleFlow-3” specifies version 3 of the flow whose unique name is sampleFlow.

Label for the interview. This label helps users and administrators differentiate interviews from the same flow.

In the user interface, this label appears in the Paused Flow

Interviews component on the user’s Home tab and in the Paused and Waiting Interviews list on the flow management page.

Required. Label for the flow.

Flow

374

Metadata Types

Field Name

loops processMetadataValues processType

Field Type

FlowLoop []

FlowMetadataValue []

Description

An array of nodes for iterating through collections. This field is available in API version 30.0 and later.

Metadata values for the flow.

This field is available in API version 31.0 and later.

FlowProcessType (enumeration of type string)

The type of the flow, as determined by the active version (or latest version, if there’s no active version). Valid values are:

•

AutoLaunchedFlow

—A flow that doesn’t require user interaction

•

Flow

—A flow that requires user interaction because it contains one or more screens, choices, or dynamic choices

•

InvocableProcess

—A process that can be invoked by another process. This value is available in API version 38.0

and later.

•

Workflow

—A process created by using Process Builder

These values are reserved for future use.

•

ActionPlan

•

JourneyBuilderIntegration

•

LoginFlow

•

UserProvisioningFlow

Across versions, you can change the type from

Flow

to

AutoLaunchedFlow

or vice versa.

This field is available in API version 31.0 and later.

recordCreates recordDeletes recordLookups recordUpdates screens startElementReference steps subflows

FlowRecordCreate

[]

FlowRecordDelete []

FlowRecordLookup

[]

FlowRecordUpdate

[]

FlowScreen []

string

FlowStep []

FlowSubflow []

textTemplates variables waits

FlowTextTemplate

FlowVariable []

FlowWait []

[]

An array of nodes for creating records in the database.

An array of nodes for deleting records in the database.

An array of nodes for looking up records in the database.

An array of nodes for updating records in the database.

An array of screen nodes.

Specifies which node or element is the starting point in the flow.

An array of step nodes.

An array of subflows. This field is available in API version 25.0

and later.

An array of text templates.

An array of variable definitions.

An array of wait nodes. This field is available in API version 32.0

and later.

Flow

375

Metadata Types

FlowActionCall

Defines a call to an action from the flow. It extends FlowNode

.

Available in API version 31.0 and later.

Field Name

actionName actionType connector faultConnector inputParameters outputParameters

Field Type

string

Description

Required. Name for the action. Must be unique across actions with the same actionType

.

InvocableActionType (enumeration of type string)

Required. The action type. Valid values are:

•

apex

—invokes an Apex method that has the

@invocableMethod annotation

•

chatterPost

—posts to Chatter

•

contentWorkspaceEnableFolders

—enables folders in a library

•

emailAlert

—sends an email by referencing a workflow email alert

•

emailSimple

—sends an email by using flow resources

•

flow

—invokes an autolaunched flow. This action type isn’t available for flows with a processType of “Flow” or

“AutolaunchedFlow”. To invoke an autolaunched flow from one of those types, use FlowSubflow. Available in

API version 32.0 and later.

•

quickAction

—invokes a

QuickAction

•

submit

—submits a record for approval

These values are reserved for future use.

•

thanks

•

metricRefresh

FlowConnector

FlowConnector

FlowActionCallInputParameter

[]

FlowActionCallOutputParameter

[]

Specifies which node to execute after this action call.

Specifies which node to execute if the action call results in an error.

An array of input parameters from the flow to the action.

An array of output parameters from the action to the flow.

Flow

FlowActionCallInputParameter

Defines an input parameter from the flow to the action. It extends FlowBaseElement and inherits all of its fields. Available in API version

31.0 and later.

376

Metadata Types

Field Name

name value

Field Type

string

FlowElementReferenceOrValue

Description

Required. Unique name for the input parameter.

Defines the value of the input parameter.

FlowActionCallOutputParameter

Defines an output parameter from the action to the flow. It extends FlowBaseElement and inherits all of its fields. Available in API version

31.0 and later.

Field Name

assignToReference name

Field Type

string string

Description

Required. Specifies the variable to which you want to assign the output parameter value.

Required. Unique name for the output parameter.

FlowApexPluginCall

Defines a call to an Apex plug-in from the flow. It extends FlowNode

and inherits all of its fields.

Field Name

apexClass connector faultConnector inputParameters outputParameters

Field Type

string

FlowConnector

FlowConnector

FlowApexPluginCallInputParameter

[]

FlowApexPluginCallOutputParameter

[]

Description

Required. The name of the Apex class.

Specifies which node to execute after this Apex plug-in call.

Specifies which node to execute if the Apex plug-in call results in an error.

An array of input parameters from the flow to the Apex plug-in.

An array of output parameters from the Apex plug-in to the flow.

FlowApexPluginCallInputParameter

Defines an input parameter from the flow to the Apex plug-in. It extends

FlowBaseElement

and inherits all of its fields.

Field Name

name value

Field Type

string

FlowElementReferenceOrValue

Description

Required. Unique name for the input parameter.

Defines the value of the input parameter.

FlowApexPluginCallOutputParameter

Defines an output parameter from the Apex plug-in to the flow. It extends

FlowBaseElement and inherits all of its fields.

377

Flow

Metadata Types

Field Name

assignToReference name

Field Type

string string

Description

Required. Specifies the variable to which you want to assign the output parameter value.

Required. Unique name for the output parameter.

FlowAssignment

Defines an assignment node that can dynamically change the value of a variable in the flow. It extends FlowNode

and inherits all of its fields.

Field Name

assignmentItems connector

Field Type

FlowAssignmentItem

[]

FlowConnector

Description

An array of assignment operations that is executed in the given order, starting from the index 0.

Specifies which node to execute after this assignment node.

FlowAssignmentItem

Defines an operation to apply to a variable. It extends

FlowBaseElement

and inherits all of its fields.

Field Name

assignToReference operator value

Field Type

string

FlowAssignmentOperator

(enumeration of type string)

FlowElementReferenceOrValue

Description

Required. Reference to the variable to which you want to apply the specified operator.

Required. Operation to apply to the variable reference in the assignToReference field. Valid values are:

•

Assign

–assigns the specified value to the variable in the assignToReference field.

•

Add

–adds the specified value to the variable in the assignToReference field.

•

AddItem

–adds the specified value as a new item to the variable in the assignToReference field. Supported for only variables that have a data type of Multipicklist.

This operator automatically adds the semi-colon required to mark a value as a separate item. This operator is available in API version 34.0 and later.

•

Subtract

–subtracts the specified value from the variable in the assignToReference field.

Defines the value that you want the operator to apply to the variable reference in the assignToReference field.

Flow

378

Metadata Types

FlowChoice

A choice resource is a standalone choice option that you can reference or reuse throughout the flow. It extends FlowElement and inherits

all of its fields.

Field Name

choiceText dataType userInput value

Field Type

string

FlowDataType (enumeration of type string)

FlowChoiceUserInput

FlowElementReferenceOrValue

Description

Required. Choice label to display in the screen.

Required. Valid types are:

•

Currency

•

Date

•

Number

•

String

•

Boolean

Enables the choice to allow user input when the choice is selected. Not supported for choices in multi-select fields.

Actual value that’s used during flow execution, for example, in assignments, calls to Apex plug-ins, and record elements. If null, this choice always has the value of null.

Flow

FlowChoiceUserInput

Allows the choice to include a user input field that appears when the choice is selected by the user. User input isn’t supported for choices in multi-select fields. It extends

FlowBaseElement

and inherits all of its fields.

Field Name

isRequired promptText validationRule

Field Type

boolean string

FlowInputValidationRule

Description

Indicates whether users are required to enter something into the field when they select the choice.

Text that is displayed to prompt the user for input at runtime.

Supports merge fields.

Rule used at runtime to validate the user input.

FlowCondition

Defines a condition for a rule. It extends

FlowBaseElement

and inherits all of its fields.

Field Name

leftValueReference operator

Field Type

string

FlowComparisonOperator

(enumeration of type string)

Description

Required. Unique name of the element that serves as the left side of the condition expression.

Required. Valid values are:

•

EqualTo

379

Metadata Types

Field Name

rightValue

Field Type

FlowElementReferenceOrValue

Description

•

NotEqualTo

•

GreaterThan

•

LessThan

•

GreaterThanOrEqualTo

•

LessThanOrEqualTo

•

StartsWith

•

EndsWith

•

Contains

•

IsNull

•

WasSet

—This value is available in API version 30.0 and later.

•

WasSelected

—Requires a choice on the left side.

•

WasVisited

—Requires a node on the left side.

Unique name of an element or the actual value (such as text or a number) for the right side of the condition expression.

FlowConnector

Connectors determine the order in which the nodes of the flow are executed. A connector defines and links to the subsequent node. It extends

FlowBaseElement

and inherits all of its fields.

Field Name

targetReference

Field Type

string

Description

Required. Which node to execute after completing the current node.

FlowConstant

A constant resource defines a fixed value that can be used throughout your flow. It extends FlowElement

and inherits all of its fields.

Field Name

dataType

Field Type Description

FlowDataType (enumeration of type string)

Required. Valid types are:

•

Currency

•

Date

•

Number

•

String

•

Boolean

Flow

380

Metadata Types

Field Name

value

Field Type

FlowElementReferenceOrValue

Description

Default value of the constant. This field can't have merge fields, nor can it reference another resource besides

$GlobalConstant.EmptyString

.

FlowDecision

Decision node that evaluates a set of rules and routes the flow execution based on the first rule that evaluates to true. It extends FlowNode

and inherits all of its fields.

Field Name

defaultConnector

Field Type

FlowConnector

defaultConnectorLabel rules string

FlowRule []

Description

Specifies which node to execute if none of the rules evaluate to true.

Label for the default connector.

An array of rules for the decision. The rules are evaluated in the order they're listed, and the connector of the first true rule is used.

If no rules are true, then the default connector is used. In the Cloud

Flow Designer, rules are referred to as “outcomes.”

FlowDynamicChoiceSet

Looks up data or metadata from an sObject and dynamically generates a set of choices at run time. It extends FlowElement and inherits

all of its fields. Depending on the fields that are set, this element represents either a record choice or a picklist choice.

•

A record choice dynamically generates choices based on records that meet specified filter criteria. If a dynamic choice doesn’t have the picklistField

and picklistObject

parameters set, it is a record choice and can’t have a data type of

Picklist or

Multipicklist

.

•

A picklist choice dynamically generates choices based on the available values for a picklist or multi-select picklist field. If a dynamic choice has the picklistField

and picklistObject

parameters set, it is a picklist choice and must have a data type of

Picklist

or

Multipicklist

.

Note:

You can’t reference sObject custom fields of type Geolocation anywhere in a flow. For example, Geolocation fields can’t be used in record filters, in input or output field assignments, or as display, value, or sort fields.

Field Name

dataType

Field Type

FlowDataType (enumeration of type string)

Description

Required. Valid types are:

•

Currency

•

Date

•

Number

•

String

•

Boolean

•

Picklist

—Picklist choices only

•

Multipicklist

—Picklist choices only

Flow

381

Metadata Types

Field Name

displayField filters limit object picklistField

Field Type

string

FlowRecordFilter

int string string

[] outputAssignments

FlowOutputFieldAssignment []

Description

Picklist

and

Multipicklist

are available in API version 35.0 and later.

Required for record choices. Which field from the sObject to display to the user as choice labels.

For example, for an account, use the DisplayField “Name” if you want the dynamically generated choices to be displayed as the account names from the records that are retrieved from the database.

Not supported for picklist choices. Picklist choices always display the labels for the retrieved picklist values.

An array of filters to apply to the records that are retrieved from the database. For example, you may want to filter accounts to include only those that were created in the past three months.

Not supported for picklist choices.

Maximum number of choices to include in the generated set of choices. Maximum and default: 200.

If sortField

and sortOrder

are also specified, the records are sorted before the limit

takes effect.

This field is available in API version 25.0 and later.

Required for record choices. The sObject whose fields you want to retrieve from the database and use to generate the set of choices. For example, use “Account” to dynamically generate choices from the information in account records in the database.

Not supported for picklist choices.

An array that assigns fields from the user-selected record to variables that can be used elsewhere in the flow. For example, when the user selects an account name from the dynamically generated list of choice options, outputAssignments can assign the Id and AnnualRevenue from the user-selected account to variables that you specify.

Not supported for picklist choices.

Required for picklist choices. The field whose available values you want to retrieve from the database and use to generate the picklist choice. For example, use “Industry” to dynamically generate one choice for each available value on the Industry picklist field.

Not supported for record choices.

Flow

382

Metadata Types

Field Name

picklistObject sortField sortOrder valueField

Field Type

string

Description

This field is available in API version 35.0 and later.

Required for picklist choices. The sObject whose field metadata you want to retrieve from the database and use to generate the picklist choice. For example, use “Account” to dynamically generate choices from a picklist field on the

Account object.

Not supported for record choices.

This field is available in API version 35.0 and later.

string Field that is used for sorting the records that meet the filter criteria. If this field isn’t specified then the returned records are not sorted.

You can only sort records by fields that have the

Sort

API field property, as specified in SOAP API .

Not supported for picklist choices.

This field is available in API version 25.0 and later.

SortOrder (enumeration of type string) Order in which to sort the records. If this field isn’t specified, then the results are not sorted.

Valid values are:

•

Asc

—Ascending

•

Desc

—Descending

Not supported for picklist choices.

This field is available in API version 25.0 and later.

string Stored value for the choice, which may differ from what is displayed to the user as the choice options

( displayField

). For example, the displayField may be the account “Name” while the valueField is the account “Id.”

Not supported for picklist choices. Picklist choices always store the API value for the retrieved picklist values.

FlowElement

Base class for all flow elements. This is an abstract class. It extends

FlowBaseElement and inherits all of its fields.

Field Name

description name

Field Type

string string

Description

Description of the flow element.

Required. Unique name of the flow element.

Flow

383

Metadata Types

FlowBaseElement

Base class for all flow elements that require contextual information in metadata values. This is an abstract class. FlowBaseElement is available in API version 32.0 and later.

Field Name

processMetadataValues

Field Type

FlowMetadataValue []

Description

Contextual information for the element.

Flow

FlowMetadataValue

Defines contextual information that can be passed between elements in a flow. Flow metadata values can be used in an application that produces or consumes flows. FlowMetadataValue is available in API version 31.0 and later.

Field Name

name value

Field Type

string

Description

Required. Name for the metadata value. This name doesn’t need to be unique across all elements.

FlowElementReferenceOrValue

Reference or value for the metadata value.

FlowElementReferenceOrValue

Defines a reference to an existing element or a particular value that you specify. Make sure that you specify only one of the fields.

Field Name

booleanValue dateTimeValue dateValue elementReference numberValue stringValue

Field Type

boolean dateTime date string double string

Description

Use this field to specify a boolean value. Do not use this field if you want to specify a different data type or an element reference.

Use this field to specify a dateTime value. Do not use this field if you want to specify a different data type or an element reference. This field is available in API version 30.0 and later.

Use this field to specify a date value. Do not use this field if you want to specify a different data type or an element reference.

Use this field to specify the name of an existing element. Do not use this field if you want to specify a value instead of an element reference.

Use this field to specify a double value. Do not use this field if you want to specify a different data type or an element reference.

Use this field to specify a string value. Do not use this field if you want to specify a different data type or an element reference.

FlowFormula

Calculates a value using functions and elements in the flow. It extends FlowElement and inherits all of its fields.

384

Metadata Types

Field Name

dataType expression scale

Field Type Description

FlowDataType (enumeration of type string)

The data type for the formula. Valid values are:

•

Boolean

•

Currency

•

Date

•

DateTime

•

Number

•

String dataType

defaults to

Number

if it isn’t defined in a formula.

This field is available in API version 31.0 and later.

string int

Required. Salesforce formula expression. The return value must match the data type. See “Limitations for Flow Formulas” in the

Salesforce Help.

For API version 30.0 and earlier, the return value must be numeric.

Scale of the return value, specifically, the number of digits to the right of the decimal point. Only supported for Currency and Number data types.

FlowInputFieldAssignment

Assigns the value for a record field based on a resource or static value. It extends

FlowBaseElement

and inherits all of its fields.

Note:

You can’t reference sObject custom fields of type Geolocation anywhere in a flow. For example, Geolocation fields can’t be used in record filters, in input or output field assignments, or as display, value, or sort fields.

Field Name

field value

Field Type

string

FlowElementReferenceOrValue

Description

Required. Name of the field that is to be assigned a value while a record is being created or updated.

Value that is to be assigned to the field.

FlowInputValidationRule

Validation rules verify that the data entered by the user meets the specified requirements. If the validation rule evaluates to false, then the specified error message is displayed.

Field Name

errorMessage formulaExpression

Field Type

string string

Description

Required. Error message to display when formulaExpression evaluates to false.

Required. Boolean formula used to validate the user input. See

“Limitations for Flow Formulas” in the Salesforce Help.

Flow

385

Metadata Types

FlowLoop

A construct for iterating through a collection. It extends

FlowNode and inherits all of its fields. FlowLoop is available in API version 30.0

and later.

Field Name

nextValueConnector noMoreValuesConnector collectionReference assignNextValueToReference iterationOrder

Field Type

FlowConnector

FlowConnector

string string iterationOrder

(enumeration of type string)

Description

Points to the element that the flow navigates to for each of the entries in the collection. This is where the flow goes for the next value in the collection.

Points to the element to navigate to when all entries in the collection have been looped through.

Required. The collection being looped through.

Required. The variable to which the current value in the collection is assigned before navigating to the target of nextValueConnector

.

Valid values are:

•

Asc

—Iterate through the collection in the order the values are listed (first to last).

•

Desc

—Iterate through the collection in the reverse order the values are listed (last to first).

Flow

FlowNode

A node is a type of element that is visible in the flow diagram. It extends FlowElement and inherits all of its fields.

Field Name

label locationX locationY

Field Type

string int int

Description

Required. Name of the node. This non-unique label is different from the unique name of the node, which is inherited from

FlowElement

.

Required. Horizontal location of the node, in pixels from the left.

Required. Vertical location of the node, in pixels from the top.

FlowOutputFieldAssignment

Assigns an record field’s value from a record to a variable that can be used elsewhere in the flow. The record may be selected by a record lookup or via a user selection for a choice. It extends

FlowBaseElement

and inherits all of its fields.

Note: You can’t reference sObject custom fields of type Geolocation anywhere in a flow. For example, Geolocation fields can’t be used in record filters, in input or output field assignments, or as display, value, or sort fields.

Field Name

assignToReference

Field Type

string

Description

Required. Reference to the variable where you want to store the value of the record field.

386

Metadata Types

Field Name

field

Field Type

string

Description

Required. Name of the field whose value is to be assigned after a record lookup.

FlowRecordCreate

Create a new record in the database using values from the flow. It extends

FlowNode

and inherits all of its properties.

Note:

The flow record create, lookup, update, and delete operations are different from the CRUD-based metadata calls create()

,

retrieve()

,

update()

, and

delete()

. The flow record methods apply to record operations from within a flow, which aren’t the same as doing any metadata calls to CRUD setup entities.

You can’t reference sObject custom fields of type Geolocation anywhere in a flow. For example, Geolocation fields can’t be used in record filters, in input or output field assignments, or as display, value, or sort fields.

Field Name Field Type

assignRecordIdToReference string connector faultConnector inputAssignments object inputReference

FlowConnector

FlowConnector

FlowInputFieldAssignment

[] string string

Description

Reference to the variable where you want to store the

ID after the record is created.

Specifies which node to execute after creating the record.

Specifies which node to execute if the attempt to create a record results in an error.

An array that assigns values to the specified fields of the record being created.

Required. sObject for the record to be created by this element

Specifies the sObject variable whose field values are used to populate the new record’s fields.

FlowRecordDelete

Deletes one or more records in the database. It extends

FlowNode and inherits all of its fields.

Note:

The flow record create, lookup, update, and delete operations are different from the CRUD-based metadata calls create()

,

retrieve()

,

update()

, and

delete()

. The flow record methods apply to record operations from within a flow, which aren’t the same as doing any metadata calls to CRUD setup entities.

You can’t reference sObject custom fields of type Geolocation anywhere in a flow. For example, Geolocation fields can’t be used in record filters, in input or output field assignments, or as display, value, or sort fields.

Field Name

connector faultConnector

Field Type

FlowConnector

FlowConnector

Description

Specifies which node to execute after deleting the record.

Specifies which node to execute if the attempt to delete a record results in an error.

Flow

387

Metadata Types

Field Name

filters object inputReference

Field Type

FlowRecordFilter

[] string string

Description

An array that specifies the criteria used to select which records to delete from the database. For example, you may want to delete accounts whose last activity was older than a specified date.

Required. The name of the object whose records are deleted.

Specifies the sObject variable whose record ID is used to identify which record to delete in the database.

FlowRecordFilter

Sets the criteria for searching records in the database. It extends

FlowBaseElement

and inherits all of its fields.

Note: You can’t reference sObject custom fields of type Geolocation anywhere in a flow. For example, Geolocation fields can’t be used in record filters, in input or output field assignments, or as display, value, or sort fields.

Field Name

field operator value

Field Type

string

Description

Required. The field to be used for filtering records.

FlowRecordFilterOperator (enumeration of type string)

Required. Valid values are:

•

EqualTo

•

NotEqualTo

•

GreaterThan

•

LessThan

•

GreaterThanOrEqualTo

•

LessThanOrEqualTo

•

StartsWith

•

EndsWith

•

Contains

•

IsNull

FlowElementReferenceOrValue

Reference or value used with the field and operator to filter records.

FlowRecordLookup

Finds a record in the database and uses or stores the values from its fields in the flow. It extends FlowNode and inherits all of its fields.

Note:

The flow record create, lookup, update, and delete operations are different from the CRUD-based metadata calls create()

,

retrieve()

,

update()

, and

delete()

. The flow record methods apply to record operations from within a flow, which aren’t the same as doing any metadata calls to CRUD setup entities.

You can’t reference sObject custom fields of type Geolocation anywhere in a flow. For example, Geolocation fields can’t be used in record filters, in input or output field assignments, or as display, value, or sort fields.

Flow

388

Metadata Types

Field Name

assignNullValuesIfNoRecordFound connector faultConnector filters limit object outputAssignments outputReference queriedFields sortField sortOrder

Field Type

boolean

FlowConnector

FlowConnector

FlowRecordFilter

int string string string[] string

[]

FlowOutputFieldAssignment

[]

SortOrder (enumeration of type string)

Description

Specifies that all values are set to null

if the record is not found. This field is available in API version 30.0 and later.

Specifies which node to execute after completing the record lookup.

Specifies which node to execute if the attempt to look up a record results in an error.

An array that specifies the criteria used to select the record from the database.

If the filters return more than one record, they are sorted according to the specified sortField

and sortOrder

.

The first record in the sorted list is then selected.

If either the sortField

or sortOrder

is not specified, then the first record returned is selected. Note, however, that records are not returned in any particular order.

The maximum number of records to return, to limit the amount of data received. This field is available in API version

30.0 and later.

Required. Name of the sObject from which to select the record.

An array that assigns fields from the selected record to variables that can be used elsewhere in the flow.

Specifies the sObject variable that stores the queried fields’ values.

An array that specifies which fields from the selected record is saved to the specified sObject variable.

Field that is used for sorting the records that meet the filter criteria. If this field isn’t specified then the returned records are not sorted.

You can only sort records by fields that have the

Sort

API field property, as specified in SOAP API .

This field is available in API version 25.0 and later.

Order in which to sort the records. If this field isn’t specified, then the results are not sorted.

Valid values are:

•

Asc

—Ascending

•

Desc

—Descending

This field is available in API version 25.0 and later.

Flow

389

Metadata Types

FlowRecordUpdate

Finds records in the database and updates them with values from the flow. It extends

FlowNode and inherits all of its fields.

Note:

The flow record create, lookup, update, and delete operations are different from the CRUD-based metadata calls create()

,

retrieve()

,

update()

, and

delete()

. The flow record methods apply to record operations from within a flow, which aren’t the same as doing any metadata calls to CRUD setup entities.

You can’t reference sObject custom fields of type Geolocation anywhere in a flow. For example, Geolocation fields can’t be used in record filters, in input or output field assignments, or as display, value, or sort fields.

Field Name

connector faultConnector filters inputAssignments object inputReference

Field Type

FlowConnector

FlowConnector

FlowRecordFilter []

FlowInputFieldAssignment

[] string string

Description

Specifies which node to execute after completing the record update.

Specifies which node to execute if the attempt to update a record results in an error.

An array that specifies the criteria used to select the records to update in the database.

An array that assigns values to the specified fields of the record being updated.

Required. Name of the sObject whose records are updated.

Specifies the sObject variable whose field values is used to update the record’s fields.

Flow

FlowRule

Defines the conditions and logic that would enable a rule to evaluate to true. It extends FlowElement and inherits all of its fields.

Field Name

conditionLogic conditions connector

Field Type

string

FlowCondition []

FlowConnector

Description

Specifies logic for the conditions. Value can be:

•

and

—evaluates to true only if all of its conditions evaluate to true

•

or

—evaluates to true if any of its conditions evaluate to true

•

Advanced logic like

1 AND (2 OR 3)

—evaluates to true if the first condition is true and either the second or third condition is true

When you use advanced logic, the string must consist of 1,000 or fewer characters.

Advanced logic is available in API version 33.0 and later.

An array of conditions for the rule.

Specifies which node to execute if this is the first rule that evaluates to true in a decision.

390

Metadata Types

Field Name

label

Field Type

string

Description

Required. Label for the connector.

FlowScreen

Screens provide the ability to capture information from users and display information to users. It extends FlowNode

and inherits all of its fields.

Field Name

allowBack allowFinish allowPause

Field Type

boolean boolean boolean

Description

Indicates whether to show (true) or hide (false) the Previous button on the screen at runtime. When true, the Previous button appears only if the user visited a previous screen in the flow path. Set this to false when revisiting the previous screen would trigger an action that should not be repeated, such as a credit card transaction.

This field is available in API version 26.0 and later.

Default: true

You can set either allowBack

or allowFinish

to false, but not both.

Indicates whether to show (true) or hide (false) the Finish button on the screen at runtime. When true, the Finish button appears only if the screen element is the end of a flow path. Set this to false if you need the user to go back to a previous screen to continue or complete the flow. For example, you wouldn’t want to offer a Finish button on a screen that tells the user to go back and make corrections on a previous screen.

This field is available in API version 26.0 and later.

Default: true

You can set either allowBack

or allowFinish

to false, but not both.

Indicates whether to show (true) or hide (false) the Pause button on the screen at runtime.

A flow screen displays the Pause button if all of the following conditions are true.

•

In the organization’s process automation settings, “Enable Users to Pause Flows” is enabled.

•

allowPause

for the screen is set to true.

•

If the flow is embedded in a Visualforce page, the

<flow:interview> component has its showAllowPause attribute set to true.

This field is available in API version 33.0 and later.

Default: true

Flow

391

Metadata Types

Field Name

connector fields helpText pausedText rules

Field Type

FlowConnector

FlowScreenField []

string string

FlowScreenRule[][]

Description

Specifies which node to execute after the screen node.

An array of fields to display on the screen.

Text that appears if the end user clicks the “Help for this form” link.

Supports merge fields in API version 26.0 and later.

Confirmation message that appears when an end-user clicks Pause.

This field is available in API version 33.0 and later.

Reserved for future use.

FlowScreenField

Configurable field on a screen. It extends

FlowElement

and inherits all of its fields.

Field Name

choiceReferences dataType

Field Type

string[]

Description

An array of references to FlowChoices or

FlowDynamicChoiceSets. The resulting choice options appear in the order specified in this array, where the element at index 0 provides the top-most choice option. Supported for the following screen field types:

•

RadioButtons

•

DropdownBox

•

MultiSelectCheckboxes

•

MultiSelectPicklist

Multi-select checkboxes and multi-select picklist fields are available in API version 26.0

and later.

FlowDataType (enumeration of type string)

Required. Data type of this screen field. Only supported for the InputField, RadioButtons, and

DropdownBox screen field types. Valid types are:

•

Currency

•

Date

•

Number

•

String

•

Boolean

A boolean InputField appears as a checkbox field at runtime. Checkbox input fields are available in API version 26.0 and later.

Flow

392

Metadata Types

Field Name

defaultSelectedChoiceReference defaultValue fieldText fieldType

Field Type

string

Description

Only the string data type is supported for multi-select checkboxes and multi-select picklist fields. Multi-select fields are available in API version 26.0 and later.

The name of the FlowChoice element to use as the default value for the screen field.

Supported for the following screen field types:

•

RadioButtons

•

DropdownBox

•

MultiSelectCheckboxes

•

MultiSelectPicklist

For DropdownBox field types only, if the defaultSelectedChoiceReference is empty or null, the reference at index 0 of choiceReferences are used as the default value.

You can specify only one FlowChoice element as the default value for multi-select checkboxes and multi-select picklist fields. Multi-select fields are available in API version 26.0 and later.

FlowElementReferenceOrValue

string

The value that is used by default when this screen field requires users to provide input.

Only supported for InputField, LargeTextArea, and PasswordField.

Field label that is displayed on the screen.

Supports merge fields.

FlowScreenFieldType (enumeration of type string)

Required. Valid values are:

•

DisplayText

•

InputField

•

LargeTextArea

•

PasswordField

•

RadioButtons

•

DropdownBox

•

MultiSelectCheckboxes

•

MultiSelectPicklist

At runtime, each multi-select field stores its field value as a concatenation of the user-selected choice values, separated by semicolons. Any semicolons in the selected choice values are removed when added to the multi-select field value.

Flow

393

Metadata Types

Field Name

helpText isRequired isVisible scale validationRule

Field Type

string boolean boolean int

FlowInputValidationRule

Description

Multi-select checkboxes and multi-select picklist fields are available in API version 26.0

and later.

Required. Text that appears if the end user clicks the help icon ( ) for the screen field.

Supports merge fields in API version 26.0 and later.

Indicates whether the user must select a choice or provide input. Not supported for DisplayText or boolean inputField.

Reserved for future use.

The scale of this screen field if its data type is number or currency. The scale sets the number of digits to the right of the decimal point.

Rule used to validate the user input when this screen field is of type InputField, LargeTextArea, or PasswordField.

FlowStep

Steps function as placeholders when you're building a flow. It extends FlowNode and inherits all of its fields.

Field Name

connectors

Field Type

FlowConnector

[]

Description

Specifies which node to execute after the step node.

FlowSubflow

A subflow element references another flow, which it calls at run time. The flow that contains the subflow element is referred to as the master flow. FlowSubflow extends

FlowNode and inherits all of its fields. It is available in API version 25.0 and later.

Field Name

connector flowName inputAssignments

Field Type

FlowConnector

string

FlowSubflowInputAssignment []

Description

Specifies which node to execute after the subflow.

References the flow to call at runtime. The value must be a unique name of a flow and can’t contain an appended hyphen and version number. The referenced flow must have been created in the Cloud Flow Designer.

An array of input variable assignments that are set at the start of the referenced flow.

Flow

394

Metadata Types

Field Name

outputAssignments

Field Type

FlowSubflowOutputAssignment

[]

Description

An array of output variable assignments that are set at the end of the referenced flow.

FlowSubflowInputAssignment

Assigns an element or value from the master flow to a variable in the referenced flow. Input assignments occur when the subflow calls the referenced flow. It extends

FlowBaseElement

and inherits all of its fields. It is available in API version 25.0 and later.

Field Name

name value

Field Type

string

FlowElementReferenceOrValue

Description

Required. Unique name for the variable in the referenced flow.

Defines the value to assign to the variable.

FlowSubflowOutputAssignment

Assigns the value of a variable from the referenced flow to a variable in the master flow. Output assignments occur when the referenced flow is finished running. It extends

FlowBaseElement

and inherits all of its fields. It is available in API version 25.0 and later.

Field Name

assignToReference name

Field Type

string string

Description

Required. Unique name for the variable in the master flow.

Required. Unique name for the variable in the referenced flow.

Flow

FlowTextTemplate

Defines a text template that can be used throughout the flow. It extends

FlowElement

and inherits all of its fields.

Field Name

text

Field Type

string

Description

Actual text of the template. Supports merge fields.

FlowVariable

Variables allow you to create updatable values to use in the flow. FlowVariable extends FlowElement and inherits all of its fields.

Field Name

dataType

Field Type Description

FlowDataType (enumeration of type string) Required. Valid types are:

•

Boolean

•

Currency

•

Date

395

Metadata Types

Field Name Field Type

isCollection isInput isOutput boolean boolean boolean

Description

•

DateTime

—This value is available in

API version 30.0 and later.

•

Number

•

Multipicklist

—This value is available in API version 34.0 and later.

•

Picklist

—This value is available in

API version 34.0 and later.

•

String

•

sObject

Indicates whether the variable is a collection of values. This field is available in API version

30.0 and later. In API version 32.0 and later, a collection variable can be of any data type.

Default value is

False

.

Indicates whether the variable can be set at the start of the flow using URL parameters,

Visualforce controllers, or subflow inputs.

This field is available in API version 25.0 and later.

Default value:

•

False

for a variable created in API version 25.0 and later or in the Cloud

Flow Designer in Summer ’12 and later.

•

True

for a variable created in API version 24.0 or in the Cloud Flow

Designer in Spring ’12 and earlier.

Warning:

Disabling input or output access for an existing variable can break the functionality of applications and pages that call the flow and access the variable. For example, you can access variables from URL parameters, Visualforce controllers, subflows, and processes.

Indicates whether the variable’s value can be accessed from Visualforce controllers and other flows. This field is available in API version 25.0 and later.

Default value:

Flow

396

Metadata Types

Field Name

objectType scale value

Field Type

string int

FlowElementReferenceOrValue

Description

•

False

for a variable created in API version 25.0 and later or in the Cloud

Flow Designer in Summer ’12 and later.

•

True

for a variable created in API version 24.0 or in the Cloud Flow

Designer in Spring ’12 and earlier.

Warning: Disabling input or output access for an existing variable can break the functionality of applications and pages that call the flow and access the variable. For example, you can access variables from URL parameters, Visualforce controllers, subflows, and processes.

Object type of this variable if its data type is sObject

.

Scale of this variable if its data type is

Number or Currency.

Default value of this variable.

Default values aren’t supported if the variable’s data type is

Picklist

or

Multipicklist

.

FlowWait

Waits for one or more defined events to occur. FlowWait extends FlowNode

and inherits all of its fields. FlowWait is available in API version 32.0 and later.

Field Name

defaultConnector defaultConnectorLabel faultConnector

Field Type

FlowConnector

string

FlowConnector

Description

Specifies which node to execute if the conditions are false for every event in the

Wait element.

Label for the default connector.

Specifies which node to execute if the attempt to wait results in an error. If any of the wait events fail, the flow takes the fault connector.

Flow

397

Metadata Types

Field Name

waitEvents

Field Type

FlowWaitEvent []

Description

An array of events that the Wait element is waiting for.

If the conditions for every event evaluate to false

, the defaultConnector

is used.

FlowWaitEvent

An event that a FlowWait element is waiting for. FlowWaitEvent extends FlowElement and inherits all of its fields. FlowWaitEvent is

available in API version 32.0 and later.

Field Name

conditionLogic conditions connector eventType

Field Type

string

FlowCondition

FlowConnector

string

Description

Specifies logic for the conditions. Value can be:

•

and

—evaluates to true only if all of its conditions evaluate to true

•

or

—evaluates to true if any of its conditions evaluate to true

•

Advanced logic like

1 AND (2 OR

3)

—evaluates to true if the first condition is true and either the second or third condition is true

When you use advanced logic, the string must consist of 1,000 or fewer characters.

Advanced logic is available in API version

33.0 and later.

An array of conditions that must be true for the flow to wait for this event.

Specifies which node to execute if this is the first event that occurs.

Required. The event’s type. The type determines which input parameters are available to define this event. Valid values are:

•

AlarmEvent

—This event is an alarm based off of an absolute date/time value.

•

DateRefAlarmEvent

—This event is an alarm based off of a date/time field on a record.

398

Flow

Metadata Types

Field Name

inputParameters label outputParameters

Field Type

FlowWaitEventInputParameter

[] string

FlowWaitEventOutputParameter

[]

Description

An array of the event’s input parameters.

The parameter values are set by using values from the flow.

Required. Label for the wait event.

An array of the event’s output parameters.

The parameter values are assigned from the event to variables in the flow.

FlowWaitEventInputParameter

An input parameter for FlowWaitEvent. The parameter’s value is set by using values from the flow. It extends FlowBaseElement and

inherits all of its fields. FlowWaitEventInputParameter is available in API version 32.0 and later.

Field Name

name value

Field Type

string

FlowElementReferenceOrValue

Description

Required. Unique name for the input parameter.

Defines the value of the input parameter.

FlowWaitEventOutputParameter

An output parameter for FlowWaitEvent. The parameter’s value is assigned to a variable in the flow so that it can be referenced in another part of the flow. It extends

FlowBaseElement and inherits all of its fields. FlowWaitEventOutputParameter is available in API version 32.0

and later.

Field Name

assignToReference name

Field Type

string string

Description

Required. Specifies the variable to which you want to assign the output parameter value.

Required. Unique name for the output parameter.

Declarative Metadata Sample Definition

A sample XML definition of a flow is shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Flow xmlns= "http://soap.sforce.com/2006/04/metadata">

<choices >

<name >Bad </name >

<choiceText >Bad </choiceText >

<dataType >Number </dataType >

<value >

Flow

399

Metadata Types

<numberValue >0.0

</numberValue >

</value >

</choices >

<choices >

<name >Excellent </name >

<choiceText >Excellent </choiceText >

<dataType >Number </dataType >

<value >

<numberValue >20.0

</numberValue >

</value >

</choices >

<choices >

<name >Fair </name >

<choiceText >Fair </choiceText >

<dataType >Number </dataType >

<value >

<numberValue >10.0

</numberValue >

</value >

</choices >

<choices >

<name >Good </name >

<choiceText >Good </choiceText >

<dataType >Number </dataType >

<value >

<numberValue >15.0

</numberValue >

</value >

</choices >

<description >Simple Flow app to calculate a Tip according to corporate policies </description >

<formulas >

<name >fTipAmount </name >

<dataType >Number </dataType >

<expression >{!Bill_Amount} * {!Service_Quality} / 100 </expression >

<scale >0 </scale >

</formulas >

<formulas >

<name >fTotalAmount </name >

<dataType >Number </dataType >

<expression >{!fTipAmount} + {!Bill_Amount} </expression >

<scale >0 </scale >

</formulas >

<label >Tip Calculator App </label >

<screens >

<name >Simple_Tip_Calculator </name >

<label >Simple Tip Calculator </label >

<locationX >513 </locationX >

<locationY >112 </locationY >

<connector >

<targetReference >TipAmount </targetReference >

</connector >

<fields >

<name >Bill_Amount </name >

<dataType >Currency </dataType >

<fieldText >Bill Amount </fieldText >

400

Flow

Metadata Types ExternalServiceRegistration

<fieldType >InputField </fieldType >

<isRequired >false </isRequired >

<scale >2 </scale >

</fields >

<fields >

<name >Service_Quality </name >

<choiceReferences >Excellent </choiceReferences >

<choiceReferences >Good </choiceReferences >

<choiceReferences >Fair </choiceReferences >

<choiceReferences >Bad </choiceReferences >

<dataType >Number </dataType >

<fieldText >Service Quality </fieldText >

<fieldType >RadioButtons </fieldType >

<isRequired >false </isRequired >

<scale >2 </scale >

</fields >

</screens >

<screens >

<name >TipAmount </name >

<label >Tip Amount </label >

<locationX >518 </locationX >

<locationY >266 </locationY >

<fields >

<name >TipSUmmary </name >

<fieldText >&lt;TEXTFORMAT

LEADING= &quot;2&quot;&gt;&lt;P

ALIGN= &quot;LEFT&quot;&gt;&lt;FONT

FACE= &quot;Arial&quot;

STYLE= &quot;font-size:12px&quot;

COLOR= &quot;#000000&quot;

LETTERSPACING= &quot;0&quot;

KERNING= &quot;0&quot;&gt;If you think the quality of service is &lt;FONT

KERNING= &quot;1&quot;&gt;{!Service_Quality},

&lt;/FONT&gt;for a meal of {!Bill_Amount} you should tip

{!fTipAmount}, so the total recommended amount should be

{!fTotalAmount}&lt;/FONT&gt;&lt;/P&gt;&lt;/TEXTFORMAT&gt; </fieldText >

<fieldType >DisplayText </fieldType >

</fields >

</screens >

<startElementReference >Simple_Tip_Calculator </startElementReference >

</Flow >

ExternalServiceRegistration

Represents the External Service configuration for an org. This type extends the Metadata

metadata type and inherits its fullName field.

File Suffix and Directory Location

ExternalServiceRegistration components have the suffix

.externalServiceRegistration

and are stored in the externalServiceRegistrations

folder.

401

Metadata Types FlowDefinition

Version

ExternalServiceRegistration components are available as a Beta release in API version 39.0.

Note: This release contains a beta version of External Services, which means it’s a high-quality feature with known limitations.

This feature isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. We can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features. You can provide feedback and suggestions for External

Services in the IdeaExchange App Cloud (Platform) Integration group in the Success Community.

Fields

Field Name

description

Field Type

string label namedCredential schema schemaType schemaUrl status string string string string string string

Description

Required. The external service description defined when the service is created.

The service name as it appears on the External Services wizard.

Required. The reference of the named credential to be used for the service.

Required. The content of the JSON schema in the Interagent format.

Nillable.

Required. ID format of the schema, which is InteragentHyperSchema.

Nillable.

Required. The schema URL defined when registering a service. The path should begin with “/” and be a relative path.

Indicates whether the service registration is finished (complete) or not

(incomplete).

Declarative Metadata Sample Definition

The following is an example of an ExternalServiceRegistration component that references an external credit service.

<?xml

version= "1.0" encoding= "UTF-8"?>

<ExternalServicesRegistration xmlns= "http://soap.sforce.com/2016/11/metadata">

<label >creditService </label >

<namedCredential >AcmeCreditService </namedCredential >

<schema >/schema </schema >

<schemaType >InteragentHyperSchema </schemaType >

<schemaUrl >http://interagent.github.io/interagent-hyper-schema </schemaUrl >

<status >complete </status >

</ExternalServicesRegistration >

FlowDefinition

Represents the flow definition’s description and active flow version number.

402

Metadata Types

To activate a flow, modify the metadata object and set the activeVersionNumber

to the version number to activate. To deactivate an active flow version, set the activeVersionNumber

to 0 (zero) or omit the value.

Declarative Metadata File Suffix and Directory Location

FlowDefinitions are stored in the flowDefinitions

directory of the corresponding package directory. The file name matches the flow definition’s unique full name, and the extension is

.flowDefinition

.

Version

FlowDefinition is available in API version 34.0 and later.

Field Name

activeVersionNumber description masterLabel

Field Type

int string string

Description

The version number of the active flow.

Description of the flow definition.

Label for the flow definition.

Folder

Folder

Represents a folder. This type extends the Metadata

metadata type and inherits its fullName

field. Four folder types currently exist in Salesforce:

•

Document folder

•

Email folder

•

Report folder

•

Dashboard folder

Folder type names end with the “Folder” suffix. For example, the type name of an email folder is “EmailFolder”.

File Suffix and Directory Location

Folders are stored in the corresponding component directory of the package. These directories are named documents

, email

, reports

, and dashboards

. Folders do not have a text file representation—they are containers for files. For each folder, an accompanying metadata file named

FolderName-meta.xml

is created at the same directory level. The

FolderName-meta.xml

metadata file contains the metadata information for that folder, such as the accessType

. For example, for a documents folder named sampleFolder, there’s a

sampleFolder-meta.xml

within the documents

folder of the package.

Version

Folders are available in API version 11.0 and later.

Fields

This metadata type contains the following fields:

403

Metadata Types

Field Name

accessType fullName name publicFolderAccess sharedTo

Field Type Description

FolderAccessTypes

(

enumeration of

type string)

Required. The type of access for this folder. Valid values are:

•

Shared

. This folder is accessible only by the specified set of users.

•

Public

. This folder is accessible by all users, including portal users.

•

PublicInternal

. This folder is accessible by all users, excluding portal users. This setting is available for report and dashboard folders in organizations with a partner portal or Customer Portal enabled.

•

Hidden

. This folder is hidden from all users.

string The 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. This field is inherited from the

Metadata

component.

Required. The name of the document folder.

string

PublicFolderAccess

(

enumeration of

type string)

If

Public

is the value for accessType

, this field indicates the type

of access all users will have to the contents of the folder. Valid values include:

•

ReadOnly

. All users can read the contents of the folder, but no user can change the contents.

•

ReadWrite

. All users can read or change the contents of the folder.

SharedTo

Sharing access for the folder. See “Sharing Considerations” in the

Salesforce online help.

Declarative Metadata Sample Definition

The following is the package manifest definition of a document folder that contains a document:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<fullName >basic </fullName >

<types >

<members >sampleFolder </members >

<members >sampleFolder/TestDocument.txt

</members >

<name >Document </name >

</types >

<version >39.0

</version >

</Package >

The following is an example of the sampleFolder-meta.xml

metadata file for the sampleFolder document folder:

<?xml

version= "1.0" encoding= "UTF-8"?>

<DocumentFolder xmlns= "http://soap.sforce.com/2006/04/metadata">

<accessType >Public </accessType >

<name >sampleFolder </name >

Folder

404

Metadata Types FolderShare

<publicFolderAccess >ReadWrite </publicFolderAccess >

</DocumentFolder >

SEE ALSO:

Dashboard

Document

EmailTemplate

Report

FolderShare

Represents the settings for enhanced analytics folder sharing. Users can control access to reports or dashboards by giving others Viewer,

Editor or Manager access to the folder that contains the report or dashboard.

File Suffix and Directory Location

FolderShare objects are stored in the reports

and dashboards

directories. For each report or dashboard folder it contains, there is a metadata file named

FolderName-meta.xml

. The

FolderName-meta.xml

metadata file contains the metadata information for that folder, such as the accessLevel

. For example, if the reports

directory contains a reports folder named myReportsFolder

, it also has a

myReportsFolder-meta.xml

file at the same level as myReportsFolder

.

Version

FolderShare components are available in API version 28 and later.

Fields

Field Name

accessLevel

Field Type

FolderShareAccessLevel

(

enumeration of type string)

sharedTo string

Description

Required. Specifies the combination of actions that can be taken on the folder. Valid values are:

•

View

. User can run a report or refresh a dashboard, but can’t edit them. All users have at least Viewer access to report and dashboard folders that have been shared with them. (Some users may have administrative permissions that give them greater access.)

•

EditAllContents

. Users can view and modify the reports or dashboards in the folder, and move them to and from any other folders that they have equivalent access to.

•

Manage

. Users can do everything Viewers and Editors can do, plus control other users’ access to a folder.

Required. Specifies the user, group, or role that has the specified access level to the folder.

405

Metadata Types FolderShare

Field Name

sharedToType

Field Type Description

FolderSharedToType(

enumeration

of type string)

Required. Specifies the type of entity that the folder is shared with.

Valid values are:

•

Group

. Users in a specified public group have the specified access level to the folder.

•

Manager

. Available in API version 29.0 and later.

•

ManagerAndSubordinatesInternal

. Available in API version 29.0 and later.

•

Role

. Users with a specified role have the specified access level to the folder.

•

RoleAndSubordinates

. Users with a specified role, and users with a role subordinate to that role, have the specified access level to the folder.

•

RoleAndSubordinatesInternal

. Users with a specified role and users with a role subordinate to that role, except public portal users, have the specified access level to the folder.

•

Organization

. All internal users have the specified access level to the folder.

•

Territory

. Users in a specified territory have the specified access level to the folder.

•

TerritoryAndSubordinates

. Users in a specified territory, and users in territories subordinate to that, have the specified access level to the folder.

•

AllPrmUsers

. All PRM Portal users have the specified level of access to the folder.

•

User

. The specified individual user has the specified level of access to the folder.

•

PartnerUser

. The specified individual user of a partner portal has the specified level of access to the folder.

•

AllCspUsers

. All Customer Success Portal users have the specified level of access to the folder.

•

CustomerPortalUser

. The specified individual user of a customer portal has the specified level of access to the folder.

•

PortalRole

. Users with a specified role in a portal have the specified access level to the folder.

•

PortalRoleAndSubordinates

. Portal users with a specified role, and portal users with a role subordinate to that role, have the specified access level to the folder.

406

Metadata Types GlobalPicklist

Declarative Metadata Sample Definition

The following is an example of a FolderShare component for a dashboard folder:

<?xml

version= "1.0" encoding= "UTF-8"?>

<DashboardFolder xmlns= "http://soap.sforce.com/2006/04/metadata">

<folderShares >

<accessLevel >View </accessLevel >

<sharedTo >R1 </sharedTo >

<sharedToType >Role </sharedToType >

</folderShares >

</DashboardFolder >

This is an example of a FolderShare component for a report folder:

<?xml

version= "1.0" encoding= "UTF-8"?>

<ReportFolder xmlns= "http://soap.sforce.com/2006/04/metadata">

<folderShares >

<accessLevel >View </accessLevel >

<sharedTo >R1 </sharedTo >

<sharedToType >Role </sharedToType >

</folderShares >

</ReportFolder >

GlobalPicklist

Represents a global picklist, or the set of shared picklist values that custom picklist fields can use. (In contrast, the custom picklist fields

that are based on a global picklist are of type CustomValue.) This type extends the Metadata

metadata type and inherits its fullName field.

File Suffix and Directory Location

GlobalPicklist components have the suffix

.globalPicklist

and are stored in the globalPicklist

folder.

Version

GlobalPicklist components are available in API version 37.0 only. In API version 38.0 and later, GlobalPicklist is replaced by the GlobalValueSet

on page 411 type.

Fields

Field Name

description

Field Type

string

Description

It’s useful to state the global picklist’s purpose, and which objects it’s intended for. Limit: 255 characters.

globalPicklistValues

GlobalPicklistValue

on page 408[]

Requires at least one value. The list of values (or “picklist value set”) that’s defined for a global picklist. The picklist value set is inherited by any custom picklist field that’s based on that global picklist. Each value is of type GlobalPicklistValue.

A global picklist can have up to 1,000 total values (inclusive of inactive values).

407

Metadata Types GlobalPicklistValue

Field Name

masterLabel sorted

Field Type

string string

Description

Required. A global picklist’s name, which is defined when the global picklist is created. Appears as Label in the user interface.

Indicates whether a global picklist’s value set is sorted in alphabetical order.

By default this value is false

.

Declarative Metadata Sample Definition

The following Territories.globalPicklist is an example of a GlobalPicklist component.

<?xml version="1.0" encoding="UTF-8"?>

<GlobalPicklist xmlns="http://soap.sforce.com/2006/04/metadata">

<description>Updated:This is a basic global picklist</description>

<globalPicklistValues>

<fullName>Northwest</fullName>

<default>false</default>

</globalPicklistValues>

<globalPicklistValues>

<fullName>Northeast</fullName>

<default>false</default>

</globalPicklistValues>

<globalPicklistValues>

<fullName>South</fullName>

<default>true</default>

</globalPicklistValues>

<globalPicklistValues>

<fullName>Southwest</fullName>

<default>false</default>

<isActive>false</isActive>

</globalPicklistValues>

<masterLabel>Territories</masterLabel>

<sorted>true</sorted>

</GlobalPicklist>

The following is an example package.xml

that references the previous definition.

<?xml version="1.0" encoding="UTF-8"?>

<Package xmlns="http://soap.sforce.com/2006/04/metadata">

<types>

<members>Territories</members>

<name>GlobalPicklist</name>

</types>

<version>37.0</version>

</Package>

GlobalPicklistValue

Represents the definition of a value used in a global picklist. Custom picklist fields can inherit the picklist value set from a global picklist.

This type extends the

Metadata metadata type and inherits its

fullName

field.

408

Metadata Types GlobalPicklistValue

Note: GlobalPicklistValue components don’t have file suffixes or directories because they’re lists of values and not custom fields.

For file-based operations they can be accessed through GlobalPicklist (which is in API v37.0 only).

Version

GlobalPicklistValue components are available in API version 37.0 only. In API version 38.0 and later, GlobalPicklistValue is replaced by

CustomValue

on page 311.

Fields

Field Name

color

Field Type

string default description isActive boolean string boolean

Description

The color assigned to the picklist value when it’s used in charts on reports and dashboards. The color is in hexadecimal format; for example,

#FF6600. If a color is not specified, it’s assigned dynamically upon chart generation.

Required. Indicates whether this value is the default selection for the global picklist and the custom picklists that share its picklist value set.

This field is set to

true

by default.

The global picklist value’s description. It’s useful to include a description for a global picklist value so the reason for creating it can be tracked.

Limit: 255 characters.

Indicates whether this value is currently active or inactive. The default value is

true

. Users can select only active values from a picklist. An API retrieve operation for global picklist values returns all active and inactive values in the picklist. (Meanwhile, retrieving the values of a non-global, unrestricted picklist returns only the active values.)

PicklistValue

This metadata type defines a value in the picklist and specifies whether this value is the default value. This type extends the

GlobalPicklistValue metadata type and inherits all its fields. In API version 36.0 and earlier, PicklistValue extends the Metadata type and

inherits its fullName

field.

Note the following when working with picklist values:

•

When you retrieve a standard object, all picklist values are retrieved, not just the customized picklist values.

•

When you deploy changes to standard picklist fields, picklist values are added as needed.

•

To deactivate a global picklist value, you can invoke an update()

call on GlobalPicklist with the value omitted, or with the value’s isActive

field set to false

. Or, you can invoke an update()

call directly on GlobalPicklistValue with the isActive

field set to false

.

•

If picklist values are missing from a component definition, they get deactivated when deployed. Deactivation occurs for picklist values of both standard and custom fields.

409

Metadata Types GlobalPicklistValue

Field Name

allowEmail closed controllingFieldValues converted cssExposed forecastCategory

Field Type

boolean boolean string[]

Description

Indicates whether this value lets users email a quote PDF ( true

), or not

( false

). This field is only relevant for the

Status

field in quotes. This field is available in API version 18.0 and later.

Indicates whether this value is associated with a closed status ( true

), or not ( false

). This field is only relevant for the standard

Status field in cases and tasks. This field is available in API version 16.0 and up to version 36.0. In version 37.0, this field is in GlobalPicklistValue.

A list of values in the controlling field that are linked to this picklist value.

The controlling field can be a checkbox or a picklist. This field is available in API version 14.0 and later. The values in the list depend on the field type:

•

Checkbox

: checked

or unchecked

.

•

Picklist

: The fullname

of the picklist value in the controlling field.

boolean boolean

Indicates whether this value is associated with a converted status ( true

), or not ( false

). This field is relevant for only the standard

Lead

Status

field in leads. Your organization can set its own guidelines for determining when a lead is qualified, but typically, you want to convert a lead as soon as it becomes a real opportunity that you want to forecast.

For more information, see “Convert Qualified Leads” in the Salesforce online help. This field is available in API version 16.0 and later.

Indicates whether this value is available in your Self-Service Portal ( true

), or not ( false

). This field is only relevant for the standard

Case

Reason

field in cases.

Self-Service provides an online support channel for your customers allowing them to resolve their inquiries without contacting a customer service representative. For more information about Self-Service, see

“Setting Up Self-Service” in the Salesforce online help.

Note: Starting with Spring ’12, the Self-Service portal isn’t available for new orgs. Existing orgs continue to have access to the Self-Service portal.

This field is available in API version 16.0 and later.

ForecastCategories

(

enumeration of

type string)

Indicates whether this value is associated with a forecast category

( true

), or not ( false

). This field is only relevant for the standard

Stage

field in opportunities. For more information about forecast categories, including the valid string values listed below, see “ Working with Forecast Categories ” in the Salesforce online help.

•

Omitted

•

Pipeline

•

BestCase

•

Forecast

410

Metadata Types GlobalValueSet

Field Name

highPriority probability reverseRole reviewed won

Field Type

boolean int string boolean boolean

Description

•

Closed

This field is available in API version 16.0 and later.

Indicates whether this value is a high priority item ( true

), or not

( false

). This field is only relevant for the standard

Priority

field in tasks. For more information about tasks, see “Considerations for Using

Tasks” in the Salesforce online help. This field is available in API version

16.0 and later.

Indicates whether this value is a probability percentage ( true

), or not

( false

). This field is only relevant for the standard

Stage

field in opportunities. This field is available in API version 16.0 and later.

A picklist value corresponding to a reverse role name for a partner. If the role is “subcontractor”, then the reverse role might be “general contractor”. Assigning a partner role to an account in Salesforce creates a reverse partner relationship so that both accounts list the other as a partner. This field is only relevant for partner roles.

For more information, see “Partner Fields” in the Salesforce online help.

This field is available in API version 18.0 and later.

Indicates whether this value is associated with a reviewed status ( true

), or not ( false

). This field is only relevant for the standard

Status field in solutions. For more information about opportunities, see “Creating

Solutions” in the Salesforce online help. This field is available in API version 16.0 and later.

Indicates whether this value is associated with a closed or won status

( true

), or not ( false

). This field is only relevant for the standard

Stage

field in opportunities. This field is available in API version 16.0

and later.

Declarative Metadata Sample Definition

For an example of GlobalPicklistValue components with a package.xml

that references them, see GlobalPicklist

.

GlobalValueSet

Represents the metadata for a global picklist value set, which is the set of shared values that custom picklist fields can use. A global value set isn't a field itself. (In contrast, the custom picklist fields that are based on a global picklist are of type ValueSet.) This type extends the

Metadata

metadata type and inherits its fullName

field.

File Suffix and Directory Location

GlobalValueSet components have the suffix

.globalValueSet

and are stored in the globalValueSets

folder.

411

Metadata Types GlobalValueSet

Version

GlobalValueSet components are available in API version 38.0 and later. In API version 37.0, this is the GlobalPicklist type.

Fields

Field Name

customValue

Field Type

CustomValue []

description masterLabel sorted string string boolean

Description

Requires at least one value. The list of values (or “global value set”) that’s defined for a global picklist. The global value set is inherited by any custom picklist field that uses that value set. Each value is of type customValue. A global value set can have up to 1,000 total values (inclusive of inactive values).

It’s useful to state the global value set’s purpose, and which objects it’s intended for. Limit: 255 characters.

Required. A global value set’s name, which is defined when the global value set is created. Appears as Label in the user interface.

Required. Indicates whether a global value set is sorted in alphabetical order.

By default this value is false

.

Declarative Metadata Sample Definition

The following Territories.globalValueSet is an example of a GlobalValueSet component.

<?xml version="1.0" encoding="UTF-8"?>

<GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata">

<description>Updated:This is a basic global value set.</description>

<masterLabel>Territories</masterLabel>

<customValue>

<fullName>North</fullName>

<default>true</default>

</customValue>

<customValue>

<fullName>South</fullName>

</customValue>

<customValue>

<fullName>East</fullName>

</customValue>

<customValue>

<fullName>West</fullName>

</customValue>

<sorted>true</sorted>

</GlobalValueSet>

The following is an example package.xml

that references the previous definition.

<?xml version="1.0" encoding="UTF-8"?>

<Package xmlns="http://soap.sforce.com/2006/04/metadata">

412

Metadata Types GlobalValueSetTranslation

<types>

<members>Territories</members>

<name>GlobalValueSet</name>

</types>

<version>38.0</version>

</Package>

GlobalValueSetTranslation

Contains details for a global value set translation. Global value sets are lists of values that can be shared by multiple custom picklist fields, optionally across objects.This type extends the

Metadata metadata type and inherits its

fullName

field.

File Suffix and Directory Location

GlobalValueSetTranslation components have the suffix

.globalValueSetTranslation

and are stored in the globalValueSetTranslations

folder.

Translations are stored in a file with a format of

ValueSetName-lang.globalValueSetTranslation

, where

ValueSetName

is the global value set’s name, and lang is the translation language.

Version

GlobalValueSetTranslation components are available in API version 38.0 and later.

Fields

Field

valueTranslation

Field Type

ValueTranslation []

Description

The translated name of a value in a translated global value set.

Each valueTranslation

is paired with a masterLabel

, which is the original (untranslated) name of the value.

ValueTranslation

The original value name and the translated value name in a translated global value set.

Field

masterLabel translation

Field Type

string string

Description

Required. The original (untranslated) name of a value in a global value set. Each valueTranslation

has a masterLabel paired with its translation

..

The translated name of a value in a translated global value set.

413

Metadata Types

Declarative Metadata Sample Definition

The following is an example of a GlobalValueSetTranslation component. When a value isn’t translated, its translation becomes a comment that’s paired with its masterLabel.

<?xml version="1.0" encoding="UTF-8"?>

<GlobalValueSetTranslation xmlns="http://soap.sforce.com/2006/04/metadata">

<valueTranslation>

<masterLabel>Three</masterLabel>

<translation>Trois</translation>

</valueTranslation>

<valueTranslation>

<masterLabel>Four</masterLabel>

<translation>Quatre</translation>

</valueTranslation>

<valueTranslation>

<masterLabel>Five</masterLabel>

<translation><!-- Five --></translation>

</valueTranslation>

</GlobalValueSetTranslation>

The following is an example package.xml

that references the previous definition.

<?xml version="1.0" encoding="UTF-8"?>

<Package xmlns="http://soap.sforce.com/2006/04/metadata">

<types>

<members>Numbers-fr</members>

<name>GlobalValueSetTranslation</name>

</types>

<version>38.0</version>

</Package>

SEE ALSO:

Translations

Group

Represents a set of public groups, which can have users, roles, and other groups.

Declarative Metadata File Suffix and Directory Location

The file suffix for group components is

.group

and components are stored in the groups

directory of the corresponding package directory.

Version

Group components are available in API version 24.0 and later.

Group

414

Metadata Types HomePageComponent

Fields

This metadata type represents the valid values that define a group:

Field Name

doesIncludeBosses fullName name

Field Type

boolean string string

Description

Indicates whether the managers have access ( true

) or do not have access ( false

) to records shared with members of the group. This field is only available for public groups.

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. Corresponds to Group Name in the user interface.

Required. The name of the group. Corresponds to Label in the user interface.

Declarative Metadata Sample Definition

The following is the definition of a group.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Group xmlns= "http://soap.sforce.com/2006/04/metadata">

<doesIncludeBosses >true </doesIncludeBosses >

<fullName >admin </fullName >

<name >test </name >

</Group >

HomePageComponent

Represents the metadata associated with a home page component. You can customize the Home tab to include components such as sidebar links, a company logo, a dashboard snapshot, or custom components that you create. For more information, see “Customizing

Home Tab Page Layouts” in the Salesforce online help. This type extends the

Metadata metadata type and inherits its

fullName

field.

Use to create, update, or delete home page component definitions.

Declarative Metadata File Suffix and Directory Location

The file suffix for home page components is

.homePageComponent

and components are stored in the homepagecomponents directory of the corresponding package directory.

Version

Home page components are available in API version 12.0 and later.

415

Metadata Types HomePageComponent

HomePageComponent

This metadata type represents the valid values that define a home page component:

Field Name

body fullName height links page pageComponentType showLabel showScrollbars

Field Type

string string int string[]

Description

If this is an HTML page component, this is the body of the HTML.

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.

Inherited from the Metadata

component, this field is not defined in the

WSDL for this component. It must be specified when creating, updating, or deleting. See

create()

to see an example of this field specified for a call.

Required for Visualforce Area components. Indicates the height (in pixels) of the component.

This field is available in API version 31.0 and later.

If the pageComponentType

is links

, then zero or more names of custom page links can be specified.

•

ObjectWebLink

•

CustomPageWebLink string

PageComponentType

(

enumeration of type

string)

Required. Valid values are:

•

links

•

htmlArea

•

imageOrNote

•

visualforcePage

(This value is available in API version 31.0

and later.) boolean

This field is only available for Visualforce Area components and indicates the API name of the Visualforce page that is associated with the component.

This field is available in API version 31.0 and later.

boolean

This field is only available for Visualforce Area components and specifies whether the component displays with a label ( true

) or not ( false

).

This field is available in API version 31.0 and later.

This field is only available for Visualforce Area components and specifies whether the component displays with scrollbars ( true

) or not ( false

).

This field is available in API version 31.0 and later.

416

Metadata Types

Field Name

width

HomePageLayout

Field Type Description

PageComponentWidth

(

enumeration of type

string)

This field is only available for HTML and Visualforce Area components, and indicates whether this is a narrow or wide home page component.

Valid values are:

•

narrowComponents

•

wideComponents

Declarative Metadata Sample Definition

The following is the definition of a home page component. See HomePageLayout and

WebLink for related samples.

<?xml

version= "1.0" encoding= "UTF-8"?>

<HomePageComponent xmlns= "http://soap.sforce.com/2006/04/metadata">

<height >200 </height >

<page >MyVisualforcePage </page >

<pageComponentType >visualforcePage </pageComponentType >

<showLabel >true </showLabel >

<showScrollbars >true </showScrollbars >

<width >wideComponents </width >

</HomePageComponent >

SEE ALSO:

HomePageLayout

WebLink

HomePageLayout

Represents the metadata associated with a home page layout. You can customize home page layouts and assign the layouts to users based on their user profile. For more information, see “Customizing Home Tab Page Layouts” in the Salesforce online help.

File Suffix and Directory Location

Home page layouts are stored in the homePageLayouts

directory of the corresponding package directory. The extension is

.homePageLayout

.

Version

Home page components are available in API version 12.0 and later. This type extends the

Metadata metadata type and inherits its

fullName

field.

Fields

This metadata type represents the valid values that define a home page layout:

417

Metadata Types InstalledPackage

Field Name

fullName narrowComponents wideComponents

Field Type

string string[] string[]

Description

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.

Inherited from the Metadata

component, this field is not defined in the

WSDL for this component. It must be specified when creating, updating, or deleting. See

create()

to see an example of this field specified for a call.

The list of elements in the narrow column on the left side of the home page.

The list of elements in the wide column on the right side of the home page.

Declarative Metadata Sample Definition

The following is the definition of a home page layout. See

HomePageComponent

on page 417 and

WebLink

on page 284 for related samples.

<?xml

version= "1.0" encoding= "UTF-8"?>

<HomePageLayout xmlns= "http://soap.sforce.com/2006/04/metadata">

<narrowComponents >google </narrowComponents >

</HomePageLayout >

SEE ALSO:

HomePageComponent

WebLink

InstalledPackage

Represents a package to be installed or uninstalled. Deploying a newer version of a currently installed package upgrades the package.

Note:

You can’t deploy a package along with other metadata types. Hence,

InstalledPackage

must be the only metadata type specified in the manifest file.

File Suffix and Directory Location

The package is specified in the installedPackages

directory, in a file named after the package’s namespace prefix. The file extension is

.installedPackage

.

Version

InstalledPackage is available in API version 28.0 and later.

418

Metadata Types

Fields

Field Name

versionNumber

KeywordList password

Field Type

string string

Description

The version number of the package. This has the format

majorNumber.minorNumber.patchNumber

(for example,

2.1.3).

An optional field specifying the package password.

Declarative Metadata Sample Definition

This specifies a sample package to be installed or uninstalled.

<?xml

version= "1.0" encoding= "UTF-8"?>

<InstalledPackage xmlns= "http://soap.sforce.com/2006/04/metadata">

<versionNumber >1.0

</versionNumber >

<password >

optional_password

</password >

</InstalledPackage >

KeywordList

Represents a list of keywords used in community moderation. This keyword list is a type of moderation criteria that defines offensive

language or inappropriate content that you don’t want in your community. This type extends the Metadata

metadata type and inherits its fullName

field.

Keep the following things in mind when creating keyword list criteria:

•

Your org can have up to 30 keyword list criteria. This limit is per org, not per community.

•

A keyword list can have up to 2,000 keywords.

•

Capitalization and trailing punctuation are ignored when matching your keywords to user-generated content. For example, if your criteria includes

BadWord

, it’s matched when a user types

BADWORD

or

badword.

File Suffix and Directory Location

KeywordList components have the suffix

.keywords

and are stored in the moderation

directory of the corresponding package directory. The file name format follows

community_name.keyword_list_developer_name.keywords

.

Version

KeywordList components are available in API version 36.0 and later.

Special Access Rules

To view, create, edit, and delete a keyword list, you need the Manage Communities or Create and Set Up Communities permission.

419

Metadata Types

Fields

Field Name

Description keywords masterLabel

Keyword

Keywords in the keyword list.

Field Name

keyword

Field Type

string

Field Type

string

Keyword []

string

Description

A description of the keyword list.

The keywords you want moderate in your community.

Required. Label for the keyword list.

Description

Required. Keywords you want to moderate.

•

Keywords can only be up to 100 characters and can include letters, numbers, spaces, and special characters.

•

Wildcard characters aren’t supported.

KeywordList

Declarative Metadata Sample Definition

The following is an example of a KeywordList component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<KeywordList xmlns= "http://soap.sforce.com/2006/04/metadata">

<masterLabel >Bad Word List </masterLabel >

<description >List of bad words updated by Joe in Nov 2015.

</description >

<keywords >

<keyword >bad-word </keyword >

</keywords >

<keywords >

<keyword >b a d w o r d </keyword >

</keywords >

<keywords >

<keyword >b@dword </keyword >

</keywords >

</KeywordList >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<name >KeywordList </name >

<members >community1.badword_list

</members >

</types >

<version >36.0

</version >

</Package >

420

Metadata Types

Layout

Represents the metadata associated with a page layout. For more information, see “Page Layouts” in the Salesforce online help. This type extends the

Metadata metadata type and inherits its

fullName

field.

Note:

To edit the Ideas layout, specify it by name in the package.xml

file. In package.xml

, use the following code to retrieve the Ideas layout:

<types >

<members >Idea-Idea Layout </members >

<name >Layout </name >

</types >

Layout

File Suffix and Directory Location

Layouts are stored in the layouts

directory of the corresponding package directory. The extension is

.layout

.

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

Layouts are available in API version 13.0 and later.

Fields

This metadata type represents the valid values that define a page layout.

Field Name

customButtons customConsoleComponents emailDefault excludeButtons feedLayout

Field Type

string[]

CustomConsoleComponents

Represents custom console components (Visualforce pages, lookup fields, or related lists; Force.com Canvas apps not available) on a page layout. Custom console components only display in the Salesforce console.

boolean

Only relevant if showEmailCheckbox

is set; indicates

the default value of that checkbox.

string[]

FeedLayout

Description

The custom buttons for this layout. Each button is a reference to a

WebLink on the same object. For example,

a ButtonLink refers to a Weblink on the same standard or custom object named 'ButtonLink'.

List of standard buttons to exclude from this layout. For example,

<excludeButtons >Delete </excludeButtons > excludes the Delete button from this layout.

Represents the values that define the feed view of a feed-based page layout. Feed-based layouts are available

421

Metadata Types

Field Name

headers layoutSections miniLayout multilineLayoutFields platformActionList quickActionList relatedContent relatedLists relatedObjects runAssignmentRulesDefault showEmailCheckbox showHighlightsPanel

Field Type Description

on Account, Case, Contact, Lead, Opportunity, custom, and external objects. They include a feed view and a detail view.

LayoutHeader[]

(

enumeration of type string)

Layout headers are currently only used for tagging, and only appear in the UI if tagging is enabled. Valid string values are:

•

PersonalTagging

—tag is private to user.

•

PublicTagging

—tag is viewable any other user who can access the record.

LayoutSection []

MiniLayout

string[]

PlatformActionList

The main sections of the layout containing fields, s-controls, and custom links. The order here determines the layout order.

A mini layout is used in the mini view of a record in the

Console tab, hover details, and event overlays.

Fields for the special multiline layout fields which appear in OpportunityProduct layouts. These fields are otherwise similar to miniLayoutFields

miniLayout

.

The list of actions, and their order, that display in the

Salesforce1 action bar for the layout.

This field is available in API version 34.0 and later.

QuickActionList

RelatedContent

RelatedListItem

string[] boolean boolean boolean

[]

The list of quick actions that display in the full Salesforce site for the page layout. This field is available in API version

28.0 and later.

The Related Content section of the page layout. This field is available in API version 29.0 and later.

The related lists for the layout, listed in the order they appear in the user interface.

The list of related objects that appears in the mini view of the console. In database terms, these objects are foreign key fields on the object for the layout. For more information, see “Choose Related Objects for the Agent Console's Mini

View” in the Salesforce online help.

Only relevant if

showRunAssignmentRulesCheckbox

is set; indicates the default value of that checkbox.

Only allowed on Case, CaseClose, and Task layouts. If set, a checkbox appears to show email.

If set, the highlights panel displays on pages in the

Salesforce console. This field is available in API version 22.0

and later.

Layout

422

Metadata Types

Field Name

showInteractionLogPanel showKnowledgeComponent

Field Type

boolean boolean showRunAssignmentRulesCheckbox boolean showSolutionSection boolean showSubmitAndAttachButton boolean

Description

If set, the interaction log displays on pages in the Salesforce console. This field is available in API version 22.0 and later.

Only allowed on Case layouts. If set, the Knowledge sidebar displays on cases in the Salesforce console. This field is available in API version 20.0 and later.

Only allowed on Lead and Case objects. If set, a checkbox appears on the page to show assignment rules.

Only allowed on CaseClose layout. If set, the built-in solution information section shows up on the page.

Only allowed on Case layout. If set, the Submit & Add

Attachment button displays on case edit pages to portal users in the Customer Portal.

CustomConsoleComponents

Represents custom console components (Visualforce pages, lookup fields, or related lists; Force.com Canvas apps not available) on a page layout. Custom console components only display in the Salesforce console. Available in API version 25.0 and later.

Field Name

primaryTabComponents subtabComponents

Field Type Description

PrimaryTabComponents

Represents custom console components on primary tabs in the Salesforce console. Available in API version 25.0 and later.

SubtabComponents

Represents custom console components on subtabs in the Salesforce console. Available in API version 25.0 and later.

PrimaryTabComponents

Represents custom console components on primary tabs in the Salesforce console. Available in API version 25.0 and later.

Field Name

component containers

Field Type Description

ConsoleComponent []

Represents a custom console component (Visualforce page, lookup field, or related lists; Force.com Canvas apps not available) on a section of a page layout. Custom console components only display in the Salesforce console. This field is available in API version 29.0 and earlier.

Container

[] Represents a location and style in which to display more than one custom console component on the sidebars of the Salesforce console. You can specify up to five components for each of the four locations (left, right, top, and bottom). This field is available in API version 30.0 and later.

Layout

423

Metadata Types

ConsoleComponent

Represents a custom console component (Visualforce page, lookup field, or related lists; Force.com Canvas apps not available) on a section of a page layout. Custom console components only display in the Salesforce console. Available in API version 25.0 and later.

Field Name

height location visualforcePage width

Field Type

int string string int

Description

Required for components with a location of top or bottom. The height of the custom console component. The value must be specified in pixels and be greater than 0 but less than 999.

Required. The location of the custom console component on the page layout. Valid values are right, left, top, and bottom. A component can have one location for each page layout.

Required. The unique name of the custom console component. For example, ConsoleComponentPage.

Required for components with a location of left or right. The width of the custom console component. The value must be specified in pixels and be greater than 0 but less than 999.

Layout

Container

Represents a location and style in which to display more than one custom console component in the sidebars of the Salesforce console.

For example, you can display multiple components in the right sidebar of the console with a style of either stack, tabs, or accordion.

Available in API version 30.0 and later.

Field Name

height isContainerAutoSizeEnabled region sidebarComponents style

Field Type

int boolean string

Description

Required for components with a location of top or bottom. The height of the components’ container. The

unit

field determines the unit of

measurement, in pixels or percent.

Required. If set to true

, stacked console components in the sidebars autosize vertically. Set to true

by default for newly created console components. Available in API version 32.0 and later.

Required. The location of the components’ container. Valid values include:

•

right

•

left

•

top

•

bottom

SidebarComponent []

string

Represents a specific custom console component to display in the components’ container.

Required. The style of the container in which to display multiple components. Valid values include:

•

stack

—a content area with multiple frames.

424

Metadata Types

Field Name

unit width

Field Type

string int

Description

•

tabs

—a single content area with a list of multiple panels.

•

accordian

—a collapsible content area.

Required. The unit of measurement, in pixels or percent, for the height or width of the components’ container.

Pixel values are simply the number of pixels, for example,

500

, and must be greater than 0 but less than 999. Percentage values must include the percent sign, for example,

20%

, and must be greater than 0 but less than

100.

Required for components with a location of right or left. The width of the components’ container. The

unit

field determines the unit of

measurement, in pixels or percent.

SidebarComponent

Represents a specific custom console component to display in a container that hosts multiple components in one of the sidebars of the

Salesforce console. You can specify up to five components for each of the four container locations (left, right, top, and bottom). Available in API version 30.0 and later.

Field Name

componentType

Field Type

string

Description

Specifies the component type. Valid values are

KnowledgeOne

,

Lookup

,

Milestones

,

RelatedList

,

Topics

,

Files

, and

CaseExperts

. This field is available in API version 31.0 and later. The

Files

and

CaseExperts

values are available in API version 32.0

and later.

Note: Case Experts is available through a pilot program.

height label lookup page relatedlists unit int string string string

RelatedList

[] string

Required for components with a location of top or bottom. The height

of the component in the container. The unit

field determines the unit of measurement, in pixels or percent.

The name of the component as it displays to console users. Available for components in a container with the style of tabs or accordion.

If the component is a lookup field, the name of the field.

If the component is a Visualforce page, the name of the Visualforce page.

If the component is a related list, the name of the list. This field is available in API version 31.0 and later.

The unit of measurement, in pixels or percent, for the height or width of the component in the container.

Pixel values are simply the number of pixels, for example,

500

, and must be greater than 0 but less than 999. Percentage values must include the

Layout

425

Metadata Types

Field Name

width

Field Type

int

Description

percent sign, for example,

20%

, and must be greater than 0 but less than

100.

Required for components with a location of right or left. The width of the

component in the container. The unit

field determines the unit of

measurement, in pixels or percent.

RelatedList

Represents related list custom components on the sidebars of the Salesforce console. Available in API version 31.0 and later.

Field Name

hideOnDetail name

Field Type

boolean string

Description

If set to true

, the related list is hidden from detail pages where it appears as a component to prevent duplicate information from showing.

The name of the component as it appears to console users.

SubtabComponents

Represents custom console components on subtabs in the Salesforce console. Available in API version 25.0 and later.

Field Name

component containers

Field Type Description

ConsoleComponent []

Represents a custom console component (Visualforce page, lookup field, or related lists; Force.com Canvas apps not available) on a section of a page layout. Custom console components only display in the Salesforce console. This field is available in API version 29.0 and earlier.

Container

[] Represents a location and style in which to display more than one custom console component on the sidebars of the Salesforce console. You can specify up to five components for each of the four locations (left, right, top, and bottom). This field is available in API version 30.0 and later.

FeedLayout

Represents the values that define the feed view of a feed-based page layout. Feed-based layouts are available on Account, Case, Contact,

Lead, Opportunity, custom, and external objects. They include a feed view and a detail view. Available in API version 30.0 and later.

Field Name

autocollapsePublisher

Field Type

boolean compactFeed boolean

Description

Specifies whether the publisher is automatically collapsed when the page loads ( true

) or not ( false

).

Specifies whether the feed-based page layout uses a compact feed

( true

) or not ( false

). If set to true

, feed items on the page are collapsed by default, and the feed view has an updated design.

Layout

426

Metadata Types

Field Name

feedFilterPosition feedFilters fullWidthFeed hideSidebar leftComponents rightComponents

Field Type Description

FeedLayoutFilterPosition

( enumeration

of type string)

Where the feed filters list is included in the layout. Valid values are:

•

centerDropDown

—as a drop-down list in the center column.

•

leftFixed

—as a fixed list in the left column.

•

leftFloat

—as a floating list in the left column.

FeedLayoutFilter

boolean

[] The individual filters displayed in the feed filters list.

Specifies whether the feed expands horizontally to take up all available space on the page ( true

) or not ( false

).

Specifies whether the sidebar is hidden ( true

) or not ( false

).

boolean

FeedLayoutComponent []

The individual components displayed in the left column of the feed view.

FeedLayoutComponent []

The individual components displayed in the right column of the feed view.

FeedLayoutComponent

Represents a component in the feed view of a feed-based page layout. Available in API version 30.0 and later.

Field Name

componentType height page

Field Type Description

FeedLayoutComponentType

( enumeration of type

string)

Required. The type of component. Valid values are:

•

HelpAndToolLinks

—icons that link to the help topic for the page, the page layout, and, the printable view of the page. Available only on Case layouts.

•

CustomButtons

—a custom button.

•

Following

—an icon that toggles between a Follow button (if the user viewing a record doesn’t already follow it) and a Following indicator (if the user viewing a record does follow it).

•

Followers

—a list of users who follow the record.

•

CustomLinks

—a custom link.

•

Milestones

—the milestone tracker, which lets users see the status of a milestone on a case. Available only on Case layouts.

•

Topics

—a list of topics related to the record.

•

CaseUnifiedFiles

—a list of all files that are attached to the case.

•

Visualforce

—a custom Visualforce component.

int string

The height, in pixels, of the component. Doesn’t apply to standardComponents

The name of a Visualforce page being used as a custom component.

Layout

427

Metadata Types

FeedLayoutFilter

Represents a feed filter option in the feed view of a feed-based page layout. A filter must have only standardFilter

or feedItemType

set. Available in API version 30.0 and later.

Field Name

feedFilterName feedFilterType feedItemType

Field Type

string

FeedLayoutFilterType

( enumeration of type

string)

Description

The name of a CustomFeedFilter component. Names are prefixed with the name of the parent object. For example,

Case.MyCustomFeedFilter

.

The type of filter. Valid values are:

•

AllUpdates

—shows all feed items on a record.

•

FeedItemType

—shows feed items only for a particular type of activity on the record.

FeedItemType

( enumeration of type

string)

The type of feed item to display. Valid values are:

•

ActivityEvent

—feed items related to activity on tasks and events associated with a case. Available only on Case layouts.

•

AdvancedTextPost

–feed items related to group announcements posted on a feed. This value is available in API version 31.0 and later.

•

AnnouncementPost

–Not used.

•

ApprovalPost

—feed items related to approvals that are submitted on a feed.

•

AttachArticleEvent

—feed items for activity related to attaching articles to cases. Available only on Case layouts.

•

BasicTemplateFeedItem

—Not used.

•

CallLogPost

—feed items for activity from the Log a Call action.

Available only on layouts for objects that support Activities (tasks and events).

•

CanvasPost

—feed items related to posts a canvas app makes on a feed.

•

CaseCommentPost

—feed items for activity from the Case Note action. Available only on Case layouts.

•

ChangeStatusPost

—feed items for activity from the Change

Status action. Available only on Case layouts.

•

ChatTranscriptPost

—feed items for activity related to attaching Live Agent chat transcripts to cases. Available only on Case layouts.

•

CollaborationGroupCreated

—feed items related to creating a public group.

•

CollaborationGroupUnarchived

—Not used.

•

ContentPost

—feed items related to attaching a file to a post.

•

CreatedRecordEvent

—feed items related to creating a record from the publisher.

Layout

428

Metadata Types

Field Name Field Type Description

•

DashboardComponentSnapshot

—feed items related to posting a dashboard snapshot on a feed.

•

EmailMessageEvent

—feed items for activity from the Email action. Available only on Case layouts.

•

FacebookPost

—Not used.

•

LinkPost

—feed items related to attaching a URL to a post.

•

MilestoneEvent

—feed items for changes to the milestone status on a case. Available only on Case layouts.

•

PollPost

—feed items related to posting a poll on a feed.

•

ProfileSkillPost

—feed items related to skills added to a user’s Chatter profile. This value is available in API version 31.0 and later.

•

QuestionPost

—feed items related to posting a question on a feed. This value is available in API version 31.0 and later.

•

ReplyPost

—feed items for activity from the Portal action.

Available only on Case layouts.

•

RypplePost

—feed items related to creating a Thanks badge in

Work.com.

•

SocialPost

—feed items for activity on Twitter from the Social

Post action.

•

TextPost

—feed items for creating a text post from the publisher.

•

TrackedChange

—feed items related to a change or group of changes to a tracked field.

•

UserStatus

—Not used.

MiniLayout

Represents a mini view of a record in the Console tab, hover details, and event overlays.

Field Name

fields relatedLists

Field Type

string[]

RelatedListItem

[]

Description

The fields for the mini-layout, listed in the order they appear in the UI.

Fields that appear here must appear in the main layout.

The mini related list, listed in the order they appear in the UI. You cannot set sorting on mini related lists. Fields that appear here must appear in the main layout.

LayoutSection

LayoutSection represents a section of a page layout, such as the Custom Links section.

Layout

429

Metadata Types

Field Name

customLabel detailHeading editHeading label layoutColumns style summaryLayout

Field Type

boolean boolean

Description

Indicates if this section's label is custom or standard (built-in). Custom labels can be any text, but must be translated. Standard labels have a predefined set of valid values, for example 'System Information', which are automatically translated.

Controls if this section appears in the detail page. In the UI, this setting corresponds to the checkbox in the section details dialog.

boolean string

Controls if this section appears in the edit page.

The label; either standard or custom, based on the customLabel flag.

LayoutColumn

[]

LayoutSectionStyle

(

enumeration of type

string)

The columns of the layout, depending on the style. 1, 2, or 3 columns, ordered left to right, are possible.

The style of the layout:

•

TwoColumnsTopToBottom

- Two columns, tab goes top to bottom

•

TwoColumnsLeftToRight

- Two columns, tab goes left to right

•

OneColumn

- One column

•

CustomLinks

- Contains custom links only

SummaryLayout

Reserved for future use.

LayoutColumn

LayoutColumn represents the items in a column within a layout section.

Field Name

layoutItems reserved

Field Type

LayoutItem []

string

Description

The individual items within a column (ordered from top to bottom).

This field is reserved for Salesforce. The field resolves an issue with some

SOAP libraries. Any value entered in the field is ignored.

LayoutItem

LayoutItem represents the valid values that define a layout item. An item must have only one of the following values set: component, customLink, field, scontrol, page, analyticsCloudComponent, or reportChartComponent.

Field Name

behavior

Field Type Description

UiBehavior ( enumeration

of type string) Determines the field behavior. Valid string values:

•

Edit

—The layout field can be edited but is not required

Layout

430

Metadata Types

Field Name

canvas component

Field Type

string string

Description

•

Required

—The layout field can be edited and is required

•

Readonly

—The layout field is read-only

Reference to a canvas app.

This field is available in API version 31.0 and later.

Reference to a component. Value must be

sfa:socialCard

.

This field is available in API version 30.0 and later. This is only allowed inside a

RelatedContentItem

.

sfa:socialCard

is only supported on page layouts for contacts, accounts, and leads.

customLink string The customLink

reference. This is only allowed inside a

CustomLink layoutSection

.

Controls if this layout item is a blank space.

emptySpace field height page boolean string int string

The field name reference, relative to the layout object, for example

Description

or

MyField__c

.

For s-control and pages only, the height in pixels.

Reference to a Visualforce page.

analyticsCloudComponent

AnalyticsCloudComponentLayoutItem

Refers to a Wave Analytics dashboard that you can add to a standard or custom object page.

This field is available in API version 34.0 and later.

reportChartComponent

ReportChartComponentLayoutItem

scontrol showLabel showScrollbars width string boolean boolean string

Refers to a report chart that you can add to a standard or custom object page.

Reference to an s-control.

For s-control and pages only, whether to show the label.

For s-control and pages only, whether to show scrollbars.

For s-control and pages only, the width in pixels or percent. Pixel values are simply the number of pixels, for example,

500

. Percentage values must include the percent sign, for example,

20%

.

AnalyticsCloudComponentLayoutItem

Represents the settings for a Wave Analytics dashboard on a standard or custom page. Available in API version 34.0 and later.

Layout

431

Metadata Types

Field Name

assetType devName error filter height hideOnError showSharing showTitle width

Field Type

string string string string int boolean boolean boolean string

Description

Required. Specifies the type of Wave Analytics asset to add. The available asset type is dashboard

.

Required. Unique development name of the dashboard to add.

Error string; only populated if an error occurred in the underlying dashboard.

Communicates initial dashboard filters for mapping data fields in the dashboard to the object’s fields, so that the dashboard shows only the data that’s relevant for the record being viewed.

Specifies the height of the dashboard, in pixels. The default is

400

.

Controls whether users see a dashboard that has an error. When this attribute is set to true

, if the dashboard has an error, the dashboard doesn’t appear on the page. When set to false

, the dashboard appears but doesn’t show any data except the error. An error can happen when a user doesn’t have access to Wave Analytics or to the dashboard. The default is true

.

If set to true

, and the dashboard is shareable, then the dashboard shows the Share icon. Users can click the icon to open the Share dialog and post or download from the dashboard. If set to false

, the dashboard doesn't show the Share icon. This field is available in API version 37.0 and later.

If true

, includes the dashboard’s title above the dashboard. If false

, the dashboard appears without a title. The default is true

.

Specifies the width of the dashboard, in pixels or percent. Pixel values are simply the number of pixels, for example,

500

. Percentage values must include the percent sign, for example,

20%

. The default is

100%

.

ReportChartComponentLayoutItem

Represents the settings for a report chart on a standard or custom page.

Field Name

cacheData

Field Type

boolean contextFilterableField string

Description

Indicates whether to use cached data when displaying the chart. When the attribute is set to true

, data is cached for 24 hours. If the attribute is set to false

, the report is run every time the page is refreshed.

This field is available in API version 29.0 and later.

Unique development name of the field by which a report chart is filtered to return data relevant to the page. If set, the ID field for the parent object of the page or report type is the chart data filter. The parent object for the report type and the page must match for a chart to return relevant data.

Layout

432

Metadata Types

Field Name

error hideOnError includeContext reportName showTitle size

Field Type

string boolean

Description

Error string; only populated if an error occurred in the underlying report.

This field is available in API version 31.0 and later.

Controls whether users see a chart that has an error. When there’s an error and this attribute is not set, the chart doesn’t show any data except the error. An error can happen for many reasons, such as when a user doesn’t have access to fields used by the chart or a chart has been removed from the report. Set the attribute to true

to hide the chart from a page on error.

This field is available in API version 29.0 and later.

boolean string

If true

, filters the report chart to return data that’s relevant to the page.

Unique development name of a report that includes a chart.

boolean If true

, applies the title from the report to the chart.

(

ReportChartComponentSize

The chart size is medium when no value is specified. Valid values:

enumeration

string)

of type

•

SMALL

•

MEDIUM

•

LARGE

PlatformActionList

PlatformActionList represents the list of actions, and their order, that display in the Salesforce1 action bar for the layout. Available in API version 34.0 and later.

Field Name

actionListContext

Field Type Description

PlatformActionListContext

(

enumeration of

type string)

Required. The context of the action list. Valid values are:

•

Assistant

•

BannerPhoto

•

Chatter

•

Dockable

•

FeedElement

•

FlexiPage

•

Global

•

ListView

•

ListViewDefinition

•

ListViewRecord

•

Lookup

•

MruList

•

MruRow

433

Layout

Metadata Types

Field Name Field Type Description

•

ObjectHomeChart

•

Photo

•

Record

•

RecordEdit

•

RelatedList

•

RelatedListRecord platformActionListItems relatedSourceEntity

PlatformActionListItem []

The actions in the PlatformActionList.

string When the

ActionListContext

is RelatedList or RelatedListRecord, this field represents the API name of the related list to which the action belongs.

PlatformActionListItem

PlatformActionListItem represents an action in the PlatformActionList. Available in API version 34.0 and later.

Field Name

actionName actionType sortOrder subtype

Field Type

string

Description

The API name for the action in the list.

PlatformActionType

( enumeration of type

string)

The type of action. Valid values are:

•

ActionLink web page, or a file, represented by a button in the Salesforce Chatter feed

UI.

—An indicator on a feed element that targets an API, a

•

CustomButton

—When clicked, opens a URL or a Visualforce page in a window or executes JavaScript.

•

InvocableAction

•

ProductivityAction

—Productivity actions are predefined by

Salesforce and are attached to a limited set of objects. You can’t edit or delete productivity actions.

•

QuickAction

—A global or object-specific action.

•

StandardButton

—A predefined Salesforce button such as New, Edit, and Delete.

int string

The placement of the action in the list.

The subtype of the action. For quick actions, the subtype is

QuickActionType

. For custom buttons, the subtype is

WebLinkTypeEnum

. For action links, subtypes are

Api

,

ApiAsync

,

Download

, and

Ui

. Standard buttons and productivity actions have no subtype.

Layout

434

Metadata Types

QuickActionList

QuickActionList represents the list of actions associated with the page layout. Available in API version 28.0 and later.

Field Name

quickActionListItems

Field Type

QuickActionListItem []

Description

Array of zero or more QuickActionList objects.

QuickActionListItem

QuickActionListItem represents an action in the QuickActionList. Available in API version 28.0 and later.

Field Name

quickActionName

Field Type

string

Description

The API name of the action.

RelatedContent

RelatedContent represents the Mobile Cards section of the page layout. Available in API version 29.0 and later.

Field Name

relatedContentItems

Field Type

RelatedContentItem

[]

Description

A list of layout items in the Mobile Cards section of the page layout.

RelatedContentItem

RelatedContentItem represents an individual item in the RelatedContentItem

list. Available in API version 29.0 and later.

Field Name

layoutItem

Field Type

LayoutItem

Description

An individual

LayoutItem in the Mobile Cards section.

RelatedListItem

RelatedListItem represents a related list in a page layout.

Field Name

customButtons

Field Type

string[] excludeButtons fields string[] string[]

Description

A list of custom buttons used in the related list. For more information, see “Define Custom Buttons and Links” in the Salesforce online help.

A list of excluded related-list buttons.

A list of fields displayed in the related list.

Retrieval of standard fields on related lists uses aliases instead of field or

API names. For example, the

Fax

,

Mobile

, and

Home Phone

fields are retrieved as Phone2, Phone3, and Phone4, respectively.

Layout

435

Metadata Types

Field Name

relatedList sortField sortOrder

Field Type

string string

SortOrder

(

enumeration of type

string)

Description

Required. The name of the related list.

The name of the field that is used for sorting.

If the sortField

is set, the sortOrder

field determines the sort order.

•

Asc

- sort in ascending order

•

Desc

- sort in descending order

SummaryLayout

Controls the appearance of the highlights panel, which summarizes key fields in a grid at the top of a page layout, when Case Feed is enabled. Available in API version 25.0 and later.

Field Name

masterLabel sizeX sizeY sizeZ summaryLayoutItems summaryLayoutStyle

Field Type

string int

Description

Required. The name of the layout label.

Required. Number of columns in the highlights pane, between 1 and 4

(inclusive).

Required. Number of rows in each column, either 1 or 2.

int int Reserved for future use. If provided, the setting is not visible to users.

SummaryLayoutItem

[] Controls the appearance of an individual field and its column and row position within the highlights panel grid, when Case Feed is enabled. At least one is required.

SummaryLayoutStyle

(

enumeration of type

string)

Highlights panel style. Valid string values are:

•

Default

•

QuoteTemplate

•

DefaultQuoteTemplate

•

CaseInteraction

•

QuickActionLayoutLeftRight (Available in API version 28.0 and later.)

•

QuickActionLayoutTopDown (Available in API version 28.0 and later.)

SummaryLayoutItem

Controls the appearance of an individual field and its column and row position within the highlights panel grid, when Case Feed is enabled. You can have two fields per each grid in a highlights panel. Available in API version 25.0 and later.

Field Name

customLink

Field Type

string

Description

If the item is a custom link, this is the customLink

reference.

Layout

436

Metadata Types

Field Name

field posX posY posZ

Field Type

string int int int

Description

The field name reference, relative to the page layout. Must be a standard or custom field that also exists on the detail page.

Required. The item's column position in the highlights panel grid. Must

be within the range of sizeX

.

Required. The item's row position in the highlights panel grid. Must be

within the range of sizeY

.

Reserved for future use. If provided, the setting is not visible to users.

Declarative Metadata Sample Definition

The following is the definition of a page layout:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Layout xmlns= "http://soap.sforce.com/2006/04/metadata">

<customConsoleComponents >

<primaryTabComponents >

<container >

<region >left </region >

<style >Stack </style >

<unit >Pixel </unit >

<width >101 </width >

<sidebarComponent >

<width >60 </width >

<page >simplepage1 </page >

<unit >Percentage </unit >

</sidebarComponent >

<sidebarComponent >

<width >40 </width >

<page >Hello_World </page >

<unit >Percentage </unit >

</sidebarComponent >

</container >

</primaryTabComponents >

<subtabComponents >

<component >

<location >top </location >

<visualforcePage >ConsoleComponentPage2 </visualforcePage >

<height >200 </height >

</component >

</subtabComponents >

</customConsoleComponents >

<customButtons >ButtonLink </customButtons >

<layoutSections >

<editHeading >true </editHeading >

<label >Information </label >

<layoutColumns >

<layoutItems >

<behavior >Required </behavior >

<field >Name </field >

Layout

437

Metadata Types

</layoutItems >

<layoutItems >

<height >180 </height >

<scontrol >LayoutSControl </scontrol >

<showLabel >true </showLabel >

<showScrollbars >true </showScrollbars >

<width >50% </width >

</layoutItems >

<layoutItems >

<reportChartComponent >

<contextFilterableField >CUST_ID </contextFilterableField >

<includeContext >true </includeContext >

<reportName >Open_Accounts_by_Cases </reportName >

<showTitle >false </showTitle >

<size >LARGE </size >

<reportChartComponent >

</layoutItems >

</layoutColumns >

<layoutColumns >

<layoutItems >

<behavior >Edit </behavior >

<field >OwnerId </field >

</layoutItems >

<layoutItems >

<behavior >Edit </behavior >

<field >CurrencyIsoCode </field >

</layoutItems >

</layoutColumns >

<style >TwoColumnsTopToBottom </style >

</layoutSections >

<layoutSections >

<editHeading >true </editHeading >

<label >System Information </label >

<layoutColumns >

<layoutItems >

<behavior >Readonly </behavior >

<field >CreatedById </field >

</layoutItems >

<layoutItems >

<behavior >Readonly </behavior >

<field >Alpha1__c </field >

</layoutItems >

<layoutItems >

<height >200 </height >

<page >mcanvasPage </page >

<showLabel >true </showLabel >

<showScrollbars >false </showScrollbars >

<width >100% </width >

</layoutItems >

</layoutColumns >

<layoutColumns >

<layoutItems >

<behavior >Readonly </behavior >

<field >LastModifiedById </field >

438

Layout

Metadata Types

</layoutItems >

<layoutItems >

<behavior >Edit </behavior >

<field >TextArea__c </field >

</layoutItems >

</layoutColumns >

<style >TwoColumnsTopToBottom </style >

</layoutSections >

<layoutSections >

<customLabel >true </customLabel >

<detailHeading >true </detailHeading >

<label >Custom Links </label >

<layoutColumns >

<layoutItems >

<customLink >CustomWebLink </customLink >

</layoutItems >

</layoutColumns >

<style >CustomLinks </style >

</layoutSections >

<quickActionList >

<quickActionListItems >

<quickActionName >FeedItem.TextPost

</quickActionName >

</quickActionListItems >

<quickActionListItems >

<quickActionName >FeedItem.ContentPost

</quickActionName >

</quickActionListItems >

<quickActionListItems >

<quickActionName >FeedItem.LinkPost

</quickActionName >

</quickActionListItems >

<quickActionListItems >

<quickActionName >FeedItem.PollPost

</quickActionName >

</quickActionListItems >

</quickActionList >

<relatedContent >

<relatedContentItems >

<layoutItem >

<component >sfa:socialPanel </component >

</layoutItem >

<relatedContentItems >

</relatedContent >

<miniLayoutFields >Name </miniLayoutFields >

<miniLayoutFields >OwnerId </miniLayoutFields >

<miniLayoutFields >CurrencyIsoCode </miniLayoutFields >

<miniLayoutFields >Alpha1__c </miniLayoutFields >

<miniLayoutFields >TextArea__c </miniLayoutFields >

<miniRelatedLists >

<relatedList >RelatedNoteList </relatedList >

</miniRelatedLists >

<relatedLists >

<fields >StepStatus </fields >

<fields >CreatedDate </fields >

<fields >OriginalActor </fields >

<fields >Actor </fields >

<fields >Comments </fields >

439

Layout

Metadata Types

<fields >Actor.Alias

</fields >

<fields >OriginalActor.Alias

</fields >

<relatedList >RelatedProcessHistoryList </relatedList >

</relatedLists >

<relatedLists >

<relatedList >RelatedNoteList </relatedList >

</relatedLists >

</Layout >

The following is an example of a layout using

<summaryLayout >

:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Layout xmlns= "http://soap.sforce.com/2006/04/metadata">

<layoutSections >

<editHeading >true </editHeading >

<label >System Information </label >

<layoutColumns >

<layoutItems >

<behavior >Readonly </behavior >

<field >CreatedById </field >

</layoutItems >

<layoutItems >

<behavior >Required </behavior >

<field >Name </field >

</layoutItems >

</layoutColumns >

<layoutColumns >

<layoutItems >

<behavior >Readonly </behavior >

<field >LastModifiedById </field >

</layoutItems >

</layoutColumns >

<style >TwoColumnsTopToBottom </style >

</layoutSections >

<summaryLayout >

<masterLabel >Great Name </masterLabel >

<sizeX >4 </sizeX >

<sizeY >2 </sizeY >

<summaryLayoutItems >

<posX >0 </posX >

<posY >0 </posY >

<field >Name </field >

</summaryLayoutItems >

</summaryLayout >

</Layout >

The following is an example of a feed-based layout:

<Layout >

...

<feedLayout >

<leftComponents >

<componentType >customLinks </componentType >

</leftComponents >

<rightComponents >

440

Layout

Metadata Types Letterhead

<componentType >follow </componentType >

</rightComponents >

<rightComponents >

<componentType >followers </componentType >

</rightComponents >

<rightComponents >

<componentType >visualforce </componentType >

<page >accountCustomWidget </page >

<height >200 </height >

</rightComponents >

<hideSidebar >true </hideSidebar >

<feedFilterPosition >centerDropDown </feedFilterPosition >

<feedFilters >

<feedFilerType >allUpdates </feedFilerType >

</feedFilters >

<feedFilters >

<feedFilerType >feedItemType </feedFilerType >

<feedItemType >CallLogPost </feedItemType >

</feedFilters >

<feedFilters >

<feedFilerType >feedItemType </feedFilerType >

<feedItemType >TextPost </feedItemType >

</feedFilters >

</feedLayout >

...

</Layout >

Letterhead

Represents formatting options for the letterhead in an email template. Letterheads define the look and feel of your HTML email templates.

Your HTML email templates can inherit the logo, color, and text settings from a letterhead. For more information, see “Create a Letterhead” in the Salesforce online help. This type extends the

Metadata metadata type and inherits its

fullName

field.

File Suffix and Directory Location

The file suffix for letterheads is

.letter

and components are stored in the letterhead

directory of the corresponding package directory.

Version

Letterheads are available in API version 12.0 and later.

Fields

With the exception of logo, and horizontal and vertical alignment, all of these fields are required.

Field Name

available

Field Type

boolean

Description

Required. Indicates whether this letterhead can be used

( true

) or not ( false

), for example, in an email template.

441

Metadata Types Letterhead

Field Name

backgroundColor bodyColor bottomLine

Field Type

string string

LetterheadLine ( enumeration

of type string)

Description

Required. The background color, in hexadecimal, for example

#FF6600

.

Required. The body color in hexadecimal.

Required. The style for the bottom line. Valid style values include:

•

color

. The color of the line in hexadecimal, as a string value.

•

height

. The height of the line, as an int value.

description string fullName footer header middleLine name topLine string

LetterheadHeaderFooter

LetterheadHeaderFooter

LetterheadLine

string

LetterheadLine

Text description of how this letterhead differs from other letterheads.

The internal name of the letterhead, based on the name

, but with white spaces and special characters escaped out for validity.

Required. The style for the footer.

Required. The style for the header.

Required. The style for the middle border line in your letterhead. Valid style values include:

•

color

. The color of the line in hexadecimal, as a string value.

•

height

. The height of the line, as an int value.

Required. The name of the letterhead.

Required. The style for the top horizontal line below the header. Valid style values include:

•

color

. The color of the line in hexadecimal, as a string value.

•

height

. The height of the line, as an int value.

LetterheadHeaderFooter

LetterheadHeaderFooter represents the properties of a header or footer.

Field

backgroundColor height

Field Type

string

DashboardComponent

[]

Description

Required. The background color of the header or footer in hexadecimal format.

Required. The height of the header or footer.

442

Metadata Types Letterhead

Field

horizontalAlignment logo verticalAlignment

(

Field Type Description

LetterheadHorizontalAlignment

( enumeration

of type string)

The horizontal alignment of the header or footer. Valid values are:

•

None

•

Left

•

Center

•

Right string

LetterheadVerticalAlignment

enumeration

of type string)

The logo which is a reference to a document, for example

MyFolder/MyDocument.gif

.

The vertical alignment of the header or footer. Valid values are:

•

None

•

Top

•

Middle

•

Bottom

LetterheadLine

LetterheadLine represents the properties of a line.

Field

color height

Field Type

string int

Description

Required. The color of the line in hexadecimal format.

Required. The height of the line.

Declarative Metadata Sample Definition

<?xml

version= "1.0" encoding= "UTF-8"?>

<Letterhead xmlns= "http://soap.sforce.com/2006/04/metadata">

<available >true </available >

<backgroundColor >#CCCCCC </backgroundColor >

<bodyColor >#33FF33 </bodyColor >

<bottomLine >

<color >#3333FF </color >

<height >5 </height >

</bottomLine >

<description >INITIAL </description >

<footer >

<backgroundColor >#FFFFFF </backgroundColor >

<height >100 </height >

<horizontalAlignment >Left </horizontalAlignment >

<verticalAlignment >Top </verticalAlignment >

</footer >

<header >

<backgroundColor >#FFFFFF </backgroundColor >

443

Metadata Types LiveChatAgentConfig

<height >100 </height >

<horizontalAlignment >Left </horizontalAlignment >

<verticalAlignment >Top </verticalAlignment >

</header >

<middleLine >

<color >#AAAAFF </color >

<height >5 </height >

</middleLine >

<name >SimpleLetterheadLabel </name >

<topLine >

<color >#FF99FF </color >

<height >5 </height >

</topLine >

</Letterhead >

LiveChatAgentConfig

Represents the configuration of an organization’s Live Agent deployment, such as how many chats can be assigned to an agent and whether or not chat sounds are enabled. This type extends the

Metadata metadata type and inherits its

fullName

field.

File Suffix and Directory Location

LiveChatAgentConfig configurations are referenced in the

<developer_name>.liveChatAgentConfig

file in the liveChatAgentConfigs

directory.

Version

LiveChatAgentConfig is available in API version 28.0 and later.

Fields

Field Name

assignments autoGreeting capacity criticalWaitTime enableAgentSneakPeek

Field Type Description

AgentConfigAssignments

Specifies how agent configurations are assigned to Live

Agent users. Agent configurations can be assigned to sets of users or sets of profiles.

string int

Specifies the greeting that displays when a customer begins a chat with an agent.

Specifies the maximum number of chats in which an agent can be engaged at a time.

int boolean

Specifies the number of seconds an agent can wait to answer an engaged chat before the chat tab flashes to alert the agent to answer it.

Specifies whether a supervisor can see the content of an agent’s message before they send it to a customer ( true

) or not ( false

).

444

Metadata Types LiveChatAgentConfig

Field Name

enableAssistanceFlag enableAutoAwayOnDecline enableAutoAwayOnPushTimeout enableAgentFileTransfer

Field Type

boolean boolean boolean boolean

Description

Indicates whether agents can raise an assistance flag to notify a supervisor that they need help. Available in API version

35.0 and later.

Indicates whether an agent appears as “away” ( true

) or not ( false

) when an agent declines a chat with a customer.

Indicates whether an agent appears as “away” ( true

) or not ( false

) when a chat request that's been pushed to the agent times out. Available in API version 34.0 and later.

Indicates whether file transfer is enabled for agents ( true

) or not ( false

). Available in API version 31.0 and later.

enableChatConferencing enableChatTransfer enableLogoutSound enableNotifications boolean boolean boolean boolean

Indicates whether chat conferencing is enabled for agents

( true

) or not ( false

). Available in API version 34.0 and later.

Indicates whether chat transfer is enabled for agents ( true

) or not ( false

). Available in API version 31.0 and later.

Indicates whether a sound will play ( true

) or not ( false

) when an agent logs out of Live Agent.

Indicates whether notifications of incoming chats appear for agents ( true

) or not ( false

).

enableRequestSound enableSneakPeek enableVisitorBlocking label boolean boolean boolean string

Indicates whether a sound will play ( true

) or not ( false

) when a customer requests to chat with an agent.

Indicates whether previews of customers’ messages are displayed as customers type ( true

) or not ( false

) in the agent’s Live Agent window. Available in API version 29.0 and later.

Indicates whether an agent can block a visitor by IP address

( true

) or not ( false

). Available in API version 34.0 and later.

Specifies the name of the configuration for agents’ default chat settings.

supervisorDefaultAgentStatusFilter

SupervisorAgentStatusFilter

( enumeration

of type string)

Specifies the Live Agent status for filtering the Agent Status list in the Supervisor Panel. Valid values are:

•

Online

•

Away

•

Offline

Available in API version 29.0 and later.

445

Metadata Types LiveChatAgentConfig

Field Name

supervisorDefaultButtonFilter

Field Type

string supervisorDefaultSkillFilter supervisorSkills string Specifies the default skill for filtering the Agent Status list in the Supervisor Panel. Available in API version 29.0 and later.

SupervisorAgentConfigSkills

Specifies the list of agent skills that are assigned to a supervisor, as specified in their assigned Live Agent configuration. Available in API version 29.0 and later.

transferableButtons

AgentConfigButtons

Description

Specifies the default button for filtering the Agent Status list in the Supervisor Panel. Available in API version 29.0 and later.

transferableSkills

AgentConfigSkills

Specifies the list of chat buttons that agents can transfer chats to. Available in API version 31.0 and later.

Specifies the list of skill groups that agents can transfer chats to. Available in API version 31.0 and later.

AgentConfigAssignments

Represents the assignments of an organization’s profiles and users to a Live Agent configuration.

Fields

Field Name

profiles users

Field Type

AgentConfigProfileAssignments

AgentConfigUserAssignments

Description

Specifies the profiles that are associated with a specific agent configuration.

Specifies the users that are associated with a specific agent configuration.

AgentConfigButtons

Represents the chat buttons that agents who are associated with the Live Agent configuration can transfer chats to.

Fields

Field Name

button

Field Type

string[]

Description

Specifies the chat buttons that agents can transfer chats to.

AgentConfigProfileAssignments

Represents the profiles associated with a specific Live Agent configuration.

446

Metadata Types

Fields

Field Name

profile

LiveChatAgentConfig

Field Type

string

Description

Specifies the custom name of the profile associated with a specific agent configuration.

AgentConfigSkills

Represents the skill groups that agents who are associated with the Live Agent configuration can transfer chats to.

Fields

Field Name

skill

Field Type

string[]

Description

Specifies the skill groups that agents can transfer chats to.

AgentConfigUserAssignments

Represents the users associated with a specific Live Agent configuration.

Fields

Field Name

user

Field Type

string

Description

Specifies the username of the user associated with a specific agent configuration.

SupervisorAgentConfigSkills

Represents the agent skills associated with a supervisor’s Live Agent configuration. Available in API version 29.0 and later.

Fields

Field Name

skill

Field Type

string

Description

Specifies the agent skills available for filtering the Agent

Status list in the Supervisor Panel.

447

Metadata Types LiveChatButton

Declarative Metadata Sample Definition

This is a sample of a liveChatAgentConfig

file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<LiveChatAgentConfig xmlns= "http://soap.sforce.com/2006/04/metadata">

<label >My Agent Configuration 1 </label >

<autoGreeting >Hi, how can I help you?

</autoGreeting >

<capacity >5 </capacity >

<enableAutoAwayOnDecline >true </enableAutoAwayOnDecline >

<enableLogoutSound >true </enableLogoutSound >

<enableNotifications >true </enableNotifications >

<enableRequestSound >true </enableRequestSound >

<enableSneakPeek >true </enableSneakPeek >

<assignments >

<profiles >

<profile >standard </profile >

</profiles >

<users >

<user >[email protected]

</user >

</users >

</assignments >

</LiveChatAgentConfig >

LiveChatButton

Represents a Live Agent deployment’s settings for the button that customers click to chat with an agent and the chat window, such as

the label that appears on the button and the pre-chat form that appears before a live chat begins. This type extends the Metadata

metadata type and inherits its fullName

field.

File Suffix and Directory Location

LiveChatButton configurations are stored in the

<developer_name>.liveChatButton

file in the liveChatButtons directory.

Version

LiveChatButton is available in API version 28.0 and later.

Fields

Field Name

chasitorIdleTimeout

Field Type

int

Description

Specifies the amount of idle time before the chat times out. The idle time starts being counted after the agent sends the last chat message.

Available in API version 35.0 and later.

448

Metadata Types

Field Name Field Type

chasitorIdleTimeoutWarning int chatPage enableQueue string boolean label string numberOfReroutingAttempts int offlineImage onlineImage string string optionsCustomRoutingIsEnabled boolean optionsHasChasitorIdleTimeout boolean optionsHasInviteAfterAccept boolean optionsHasInviteAfterReject boolean optionsHasRerouteDeclinedRequest boolean optionsIsAutoAccept boolean

449

LiveChatButton

Description

Specifies the amount of idle time before a warning appears. The idle time starts being counted after the agent sends the last chat message. Available in API version 35.0 and later.

Specifies the page that hosts your chat if that page differs from the Live Agent chat window.

Indicates whether queuing is enabled ( true

) or not ( false

).

Specifies the text that appears on the button.

Specifies the number of times a chat request can be rerouted to available agents if all agents reject the chat request. Available in API version 30.0

and later.

Specifies the image that appears on the button when no agents are available to chat.

Specifies the image that appears on the button when agents are available to chat.

Indicates whether custom routing is enabled for incoming chat requests ( true

) or not ( false

).

Available in API version 30.0 and later.

Indicates whether the visitor idle timeout feature is enabled. Available in API version 35.0 and later.

Indicates whether a new chat invitation triggers after a customer accepts a previous chat invitation ( true

) or not ( false

).

Indicates whether a new chat invitation triggers after a customer rejects a previous chat invitation

( true

) or not ( false

).

Indicates whether a chat request, which has been rejected by all available agents, should be rerouted to available agents again ( true

) or not

( false

). Available in API version 30.0 and later.

Indicates whether a chat request should be automatically accepted by the agent it’s assigned to ( true

) or not ( false

). For chat buttons and automated chat invitations with routingType

set to

MostAvailable

or

LeastActive

. Available in API version 30.0

and later.

Metadata Types LiveChatButton

Field Name

optionsIsInviteAutoRemove overallQueueLength perAgentQueueLength postChatPage postChatUrl preChatFormPage preChatFormUrl pushTimeOut routingType

Field Type

boolean int int

Description

Indicates whether a chat invitation is set to automatically disappear from a customer’s screen after a certain amount of time ( true

) or not

( false

).

Specifies the maximum number of chat requests that are allowed to queue.

Specifies the number of chat requests that are allowed to queue for an agent with the required skills.

string string string string

Specifies the name of the post-chat form to which customers are routed when the chat ends.

Specifies the URL of the post-chat form to which customers are routed when the chat ends.

Specifies the name of the pre-chat form to which customers are routed before a chat begins.

Specifies the URL of the pre-chat form to which customers are routed when the chat begins.

int

LiveChatButtonRoutingType ( enumeration

of type string)

Specifies the number of seconds an agent has to answer an incoming chat request before the request is routed to another agent.

Specifies how incoming chats should be routed to agents when a customer pushes a button.

Valid values are:

•

Choice

•

LeastActive

•

MostAvailable site string skills windowLanguage

LiveChatButtonSkills

Language

Specifies the Force.com site that hosts your custom chat button images or custom chat page.

Note: You must have the

“CustomDomain” permission enabled in your organization before you can use a

Force.com site with Live Agent.

Specifies the skills associated with the button.

When a customer clicks the button to chat, they are automatically routed to agents with those skills.

Specifies the language preferences for the chat window associated with the button.

450

Metadata Types

LiveChatButtonSkills

Represents the skills associated with a chat button.

Fields

Field Name

skill

Field Type

string

LiveChatDeployment

Description

Specifies the name of the skill.

Declarative Metadata Sample Definition

This is a sample of a liveChatButton

file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<LiveChatButton xmlns= "http://soap.sforce.com/2006/04/metadata">

<label >My Button 1 </label >

<chatPage >ChatterAnswersLogin </chatPage >

<enableQueue >true </enableQueue >

<offlineImage >MyOfflineButton </offlineImage >

<onlineImage >MyOnlineButton </onlineImage >

<perAgentQueueLength >5 </perAgentQueueLength >

<postchatPage >AnswersHome </postchatPage >

<prechatFormPage >AccountVF </prechatFormPage >

<pushTimeOut >300 </pushTimeOut >

<routingType >LeastActive </routingType >

<site >LiveAgentSite </site >

<skills >

<skill >Skill1 </skill >

<skill >Skill2 </skill >

</skills >

</LiveChatButton >

Note: If you update your chat button through the Metadata API, be sure to update all Web pages that use the same chat button code.

LiveChatDeployment

Represents the configuration settings for a specific Live Agent deployment, such as the branding image for the deployment and whether or not chat transcripts are automatically saved. This type extends the

Metadata metadata type and inherits its

fullName

field.

File Suffix and Directory Location

LiveChatDeployment values are stored in the

<developer_name>.liveChatDeployment

file in the liveChatDeployments

directory.

451

Metadata Types LiveChatDeployment

Version

LiveChatDeployment is available in API version 28.0 and later.

Fields

Field Name

brandingImage domainWhiteList enablePrechatApi enableTranscriptSave label mobileBrandingImage site windowTitle

Field Type

string connectionTimeoutDuration int

ConnectionWarningDuration int displayQueuePosition boolean

LiveChatDeploymentDomainWhiteList

boolean boolean string string string string

Description

Specifies the branding image for the deployment.

Indicates the amount of time before the chat times out, in seconds.

Indicates the amount of time before a time-out warning is displayed to the agent, in seconds.

(Pilot) Determines whether a customer’s queue position is displayed in a standard chat window while the customer waits for an agent to respond to the chat request ( true

) or not

( false

). This field is available as a pilot in API version 32.0. To enable this field, contact

Salesforce.

Specifies the list of domains that can host the deployment.

Indicates whether or not the pre-chat API is enabled for the deployment ( true

) or not

( false

).

Indicates whether chat transcripts are automatically saved after a chat ends ( true

) or not ( false

).

Specifies the name of the deployment.

Specifies the branding image for the deployment that appears when customers access the deployment on a mobile device.

Specifies the site that hosts the images for the deployment.

Note:

You must have the

“CustomDomain” permission enabled in your organization before you can use a Force.com site with Live Agent.

Specifies the title of the window associated with the deployment.

452

Metadata Types LiveChatSensitiveDataRule

LiveChatDeploymentDomainWhiteList

Represents a Live Agent deployment’s domain whitelist.

Fields

Field Name

domain

Field Type

string

Description

Specifies a domain that can host the deployment.

Declarative Metadata Sample Definition

This is a sample of a liveChatDeployment

file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<LiveChatDeployment xmlns= "http://soap.sforce.com/2006/04/metadata">

<label >My Deployment 1 </label >

<brandingImage >pkb_image_bannerBg </brandingImage >

<mobileBrandingImage >pkb_image_bgBottom </mobileBrandingImage >

<domainWhiteList >

<domain >mydomain </domain >

<domain >test </domain >

</domainWhiteList >

<enableTranscriptSave >true </enableTranscriptSave >

<site >GL_Knowledge_Base </site >

<windowTitle >My window title </windowTitle >

</LiveChatDeployment >

Note: If you update your deployment through the Metadata API, be sure to update all Web pages that use the same deployment code.

LiveChatSensitiveDataRule

Represents a rule for masking or deleting data of a specified pattern. Written as a regular expression (regex).

Use this object to mask or delete data of specified patterns, such as credit card, social security, phone and account numbers, or even

profanity. This type extends the Metadata

metadata type and inherits its fullName

field.

File Suffix and Directory Location

LiveChatSensitiveDataRule components have the suffix

.liveChatSensitiveDataRule

and are stored in the liveChatSensitiveDataRule

folder.

Version

LiveChatSensitiveDataRule components are available in API version 35.0 and later.

453

Metadata Types

Fields

Field Name

actionType

LiveChatSensitiveDataRule description enforceOn isEnabled pattern replacement

Field Type Description

SensitiveDataActionType

(

enumeration of

type string)

Required. The action to take on the text when the sensitive data rule is triggered. Possbile values are:

•

Remove

•

Replace string int boolean string string

The description of the sensitive data rule—for example, “Block social security numbers.”

Required. Determines the roles on which the rule is enforced. The value is determined using bitwise OR operation. There are seven possible values:

1. Rule enforced on Agent

2. Rule enforced on Visitor

3. Rule enforced on Agent and Visitor

4. Rule enforced on Supervisor

5. Rule enforced on Agent and Supervisor

6. Rule enforced on Visitor and Supervisor

7. Rule enforced on Agent, Visitor, and Supervisor

Required. Specifies whether a sensitive data rule is active ( true

) or not

( false

). Default value (if none is provided) is false

.

Required. The pattern of text blocked by the rule. Written as a JavaScript regular expression (regex).

The string of characters that replaces the blocked text (if

ActionType

Replace

is selected).

Declarative Metadata Sample Definition

The following is an example of a LiveChatSensitiveDataRule component.

<LiveChatSensitiveDataRule xmlns= "http://soap.sforce.com/2006/04/metadata">

<actionType >REPLACE </actionType >

<enforceOn >7 </enforceOn >

<isEnabled >true </isEnabled >

<pattern >[aeiou] </pattern >

<replacement >œ </replacement >

</LiveChatSensitiveDataRule >

The following is an example package.xml

that references the previous definition.

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<!-- To be used from

454

Metadata Types ManagedTopics support.liveagent.testsuite.unifiedouting.testDeployButtonMDAPIWithExistingQueue -->

<apiAccessLevel >Unrestricted </apiAccessLevel >

<types >

<members >Change_For_all </members >

<name >LiveChatSensitiveDataRule </name >

</types >

<version >35.0

</version >

</Package >

ManagedTopics

Represents navigational and featured topics managed in a community. A specific community is represented by the

Network

component.

Note: The related network must exist before you deploy managed topics. (This occurs automatically when deploying an entire organization.)

File Suffix and Directory Location

Components have the suffix managedTopics and are stored in the managedTopics folder. In that folder, you’ll find separate files for each network (for example,

NetworkNameA.managedTopics

and

NetworkNameB.managedTopics

).

Version

ManagedTopics components are available in API version 32.0 and later.

Fields

Field Name

ManagedTopic

Field Type

ManagedTopic

Description

Represents a specific navigational or featured topic.

ManagedTopic

Field Name

name managedTopicType topicDescription parentName

Field Type

string string string string

Description

The topic name.

The topic type: “Navigational” or “Featured”

An optional description of topic contents. This field is accessible only via the API; there is no corollary in the user interface.

The name of a parent topic for which this topic is a child. Child topics are accessible from the subtopics section of the parent topic page and their feeds are added to the parent topic feed.

Only navigational topics support parent-child relationships.

455

Metadata Types

Field Name

position

Field Type

int

ManagedTopics

Description

The placement of this topic relative to others of the same type. The results differ depending on topic type:

•

For top-level navigational topics, position

arranges the Topics menu in the community.

•

For child navigational topics, it arranges sibling topics in the subtopics section.

•

For featured topics, it arranges topic thumbnail images on the community home page.

Enter a number between 0 and 24. (The maximum amount of navigational or featured topics is 25.)

Declarative Metadata Sample Definition

The following example retrieves or deploys managed topics for all networks:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >ManagedTopics </name >

</types >

<version >32.0

</version >

</Package >

The following example shows a package.xml file referencing the ManagedTopics component:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >NetworkName </members >

<name >ManagedTopics </name >

</types >

<version >32.0

</version >

</Package >

The following example shows the ManagedTopics component itself:

<?xml

version= "1.0" encoding= "UTF-8"?>

<ManagedTopics >

<ManagedTopic >

<name >Running </name >

<managedTopicType >Navigational </managedTopicType >

<topicDescription >Training advice </topicDescription >

<parentName > </parentName >

<position >0 </position >

</ManagedTopic >

<ManagedTopic >

<name >Hiking </name >

<managedTopicType >Navigational </managedTopicType >

<topicDescription >Routes and gear </topicDescription >

456

Metadata Types MatchingRule

<parentName > </parentName >

<position >1 </position >

</ManagedTopic >

<ManagedTopic >

<name >Trails </name >

<managedTopicType >Navigational </managedTopicType >

<topicDescription >Maps for local favorites </topicDescription >

<parentName >Hiking </parentName >

<position >0 </position >

</ManagedTopic >

<ManagedTopic >

<name >Backpacks </name >

<managedTopicType >Navigational </managedTopicType >

<topicDescription >Recommended models </topicDescription >

<parentName >Hiking </parentName >

<position >1 </position >

</ManagedTopic >

<ManagedTopic >

<name >Footwear </name >

<managedTopicType >Featured </managedTopicType >

<topicDescription >Suggested types for each sport </topicDescription >

<parentName > </parentName >

<position >0 </position >

</ManagedTopic >

<ManagedTopic >

<name >Conditioning </name >

<managedTopicType >Featured </managedTopicType >

<topicDescription >How to get fit for any activity </topicDescription >

<parentName > </parentName >

<position >1 </position >

</ManagedTopic >

</ManagedTopics >

MatchingRule

Represents a matching rule that is used to identify duplicate records. This type extends the

Metadata metadata type and inherits its

fullName

field.

File Suffix and Directory Location

Matching rule components have the

.matchingRule

suffix and are stored in the matchingRules

folder. The name of the component file is the standard or custom object name that is associated with the matching rule.

In API version 39.0 and later, MatchingRule supports the Person Account object.

•

The component file name is

PersonAccount.matchingRule

.

•

The component directory is matchingRules

.

Version

MatchingRule is available in API version 33.0 and later.

457

Metadata Types

Fields

Field Name

booleanFilter description label matchingRuleItems ruleStatus

MatchingRule

Field Type

string string string

Description

Specifies filter logic conditions. For more information on filter logic, see

“Getting the Most Out of Filter Logic” in the Salesforce Help.

The description of the matching rule.

Required. The name of the matching rule.

MatchingRuleItem

The criteria that make up a matching rule.

MatchingRuleStatus

(

enumeration of

type string)

Required. The activation status of the matching rule. Values are:

•

Inactive

•

Deactivating

•

DeactivationFailed

•

Active

•

Activating

•

ActivationFailed

Important:

The only valid values you can declare when deploying a package are

Active

and

Inactive

.

MatchingRuleItem

Field Name

blankValueBehavior

Field Type Description

BlankValueBehavior

( enumeration of type

string)

Specifies how blank fields affect whether the fields being compared are considered matches. Valid values are:

•

MatchBlanks

•

NullNotAllowed

(default) fieldName matchingMethod string Required. Indicates which field to compare when determining if a record is similar enough to an existing record to be considered a match.

MatchingMethod

( enumeration of type

string)

Required. Defines how the fields are compared. Choose between the exact matching method and various fuzzy matching methods. Valid values are:

•

Exact

•

FirstName

•

LastName

•

CompanyName

•

Phone

•

City

•

Street

•

Zip

458

Metadata Types MatchingRule

Field Name Field Type Description

•

Title

For details on each matching method, see “Matching Methods Used with

Matching Rules” in the Salesforce Help.

Declarative Metadata Sample Definition

The following is a sample XML definition of a matching rule. A matching rule can be associated with either a standard or a custom object.

<?xml

version= "1.0" encoding= "UTF-8"?>

<MatchingRules xmlns= "http://soap.sforce.com/2006/04/metadata">

<matchingRules >

<fullName >AccountMatchingRule </fullName >

<label >Matching rule for accounts </label >

<description >this is sample rule description </description >

<matchingRuleItems >

<blankValueBehavior >NullNotAllowed </blankValueBehavior >

<fieldName >BillingCity </fieldName >

<matchingMethod >City </matchingMethod >

</matchingRuleItems >

<matchingRuleItems >

<blankValueBehavior >NullNotAllowed </blankValueBehavior >

<fieldName >Name </fieldName >

<matchingMethod >CompanyName </matchingMethod >

</matchingRuleItems >

<ruleStatus >Inactive </ruleStatus >

</matchingRules >

</MatchingRules >

The following package.xml

shows how to reference a matching rule by name. It specifies the type name of MatchingRule.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Account.AccountMatchingRule

</members >

<name >MatchingRule </name >

</types >

<version >39.0

</version >

</Package >

The following package.xml

shows how to reference all matching rules by specifying the plural MatchingRules type name and using a wildcard to include all members.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >MatchingRules </name >

</types >

459

Metadata Types Metadata

<version >39.0

</version >

</Package >

Metadata

This is the base class for all metadata types. You cannot edit this object. A component is an instance of a metadata type.

Metadata is analogous to sObject, which represents all standard objects. Metadata represents all components and fields in Metadata

API. Instead of identifying each component with an ID, each custom object or custom field has a unique fullName

, which must be distinct from standard object names, as it must be when you create custom objects or custom fields in the Salesforce user interface.

Version

Metadata components are available in API version 10.0 and later.

Fields

Field Name

fullName

Field Type

string

Description

Required. The name of the component. If a field, the name must specify the parent object, for example

Account.FirstName

. The __c suffix must be appended to custom object names and custom field names when you are setting the fullName

. For example, a custom field in a custom object could have a fullName

of

MyCustomObject__c.MyCustomField__c

.

To reference a component in a package, prepend the package’s namespace prefix to the component name in the fullName

field. Use the following syntax:

namespacePrefix__ComponentName

.

For example, for the custom field component

MyCustomObject__c.MyCustomField__c

and the namespace

MyNS

, the full name is

MyNS__MyCustomObject__c.MyCustomField__c

.

Note: 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.

SEE ALSO:

CustomObject

CustomField

MetadataWithContent

460

Metadata Types MetadataWithContent

MetadataWithContent

This is the base type for all metadata types that contain content, such as documents or email templates. It extends

Metadata . You cannot

edit this object.

Version

MetadataWithContent components are available in API version 14.0 and later.

Fields

Field Name

content

Field Type

base64Binary fullName string

Description

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.

Required. The name of the component. 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.

Inherited from the

Metadata component, this field is not defined in the

WSDL for this component. It must be specified when creating, updating,

or deleting. See create()

to see an example of this field specified for a call.

SEE ALSO:

Metadata

MilestoneType

Represents the name and description of a milestone, which you can use in an entitlement process to track important steps in cases. This type extends the

Metadata metadata type and inherits its

fullName

field.

File Suffix and Directory Location

Milestone types are stored in the milestoneTypes

directory of the corresponding package directory. The extension is

.milestoneType

.

Version

MilestoneType is available in API version 27.0 and later.

461

Metadata Types

Fields

Field Name

description

RecurrenceType

ModerationRule

Field Type

string

Description

The description of the milestone.

MilestoneTypeRecurrenceType

(

enumeration of

type string)

The type of recurrence for the milestone. Available in API version 29.0

and later. Valid values are:

•

none

—Specifies no recurrence for the milestone. The milestone occurs only once until the entitlement process exits.

•

recursIndependently

—Specifies independent recurrence for the milestone.

•

recursChained

—Specifies sequential recurrence for the milestone.

Declarative Metadata Sample Definition

This is a sample milestone type.

<?xml

version= "1.0" encoding= "UTF-8"?>

<MilestoneType xmlns= "http://soap.sforce.com/2006/04/metadata">

<description >First Response Time </description >

</MilestoneType >

And, here’s the sample package.xml

file that references the MilestoneType component definition:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* or a valid name of a milestone type </members >

<name >MilestoneType </name >

</types >

<version >29.0

</version >

</Package >

ModerationRule

Represents a rule used in your community to moderate member-generated content.Each rule specifies the member-generated content the rule applies to, the criteria to enforce the rule on, and the moderation action to take. Moderation rules help protect your community

from spammers, bots, and offensive or inappropriate content. This type extends the Metadata metadata type and inherits its

fullName field.

Community moderation rules created with the Metadata API are more powerful than moderation rules set up in the Community

Management UI. For example, in the UI you could create a rule that moderates posts and comments. In the Metadata API you could create a rule that moderates only the Link Name of a Link feed type. Use the Metadata API to express complex moderation rules.

Important: Don’t update moderation rules you create using the Metadata API in the Community Management UI. If you do, you overwrite relevant Metadata API fields or the fields are ignored.

Keep the following things in mind when creating moderation rules:

462

Metadata Types ModerationRule

•

Your org can have up to 30 rules. This limit is per org, not per community. This limit includes both content rules and rate rules.

•

Each rule can have up to three keyword criteria.

•

Rules that block content run first, followed by rules to review and approve content, then rules that replace content, and last by rules that flag content. If two or more rules perform the same action, the oldest rule runs first, based on the date the rule was created.

Rules to replace content don’t run when the content also applies to a review rule—we want community managers to review the original content.

File Suffix and Directory Location

ModerationRule components have the suffix

.rule

and are stored in the moderation

directory of the corresponding package directory. The file name format follows

community_name.moderation_rule_developer_name.rule

.

Version

ModerationRule components are available in API version 36.0 and later.

Special Access Rules

To view, create, edit, and delete moderation rules, you need the Manage Communities or Create and Set Up Communities permission.

Fields

Field Name

action actionLimit active description entitiesAndFields masterLabel notifyLimit

Field Type Description

ModerationRuleAction

(

enumeration of

type string)

Required. Indicates the moderation action that you want to take. The valid values are:

•

Block

•

Review

•

Replace

•

Flag

•

FreezeAndNotify

(Reserved for future use.) int boolean

Indicates the moderation action limit. Available in API 39.0 and later.

Required. Indicates whether the moderation rule is active ( true

) or inactive ( false

).

string string

A description of the moderation rule.

ModeratedEntityField

[] Indicates the types of user-generated content this moderation rule applies to.

Required. Label for the moderation rule.

int Indicates the notification limit of the moderation rule. Available in API

39.0 and later.

463

Metadata Types ModerationRule

Field Name

userCriteria userMessage

Field Type

string string

Description

Represents the member criteria to use in community moderation rules.

Available in API 39.0 and later.

The message you want your community members to see when their content is blocked. Use the

%BLOCKED_KEYWORD%

variable to display up to five blocked words in the user message. If you don’t specify a message, the member sees the standard message: “You can’t use

%BLOCKED_KEYWORD%

or other inappropriate words in this community. Review your content and try again.”

ModeratedEntityField

The fields and entities you want to moderate.

Field Name

entityName fieldName keywordList

Field Type

string string

KeywordList

string

Description

Required. Indicates the types of user-generated content the moderation rule applies to. Post and comments only apply to content created in groups and user profiles. All feed types, such as polls and links, are supported.

Indicates the field the moderation rule applies to.

Note:

To moderate feed posts, use entityName FeedItem

with fieldName RawBody

. To moderate feed comments, use entityName FeedComment

with fieldName

RawCommentBody

. The

RawBody

and

RawCommentBody fields aren’t available in any other API.

Indicates the keyword list that you want to moderate against.

ModerationRuleType

Required. Indicates the type of rule to run on user-generated content.

Field Name

type

Field Type Description

( enumeration of type

string)

Required. Indicates the type of rule to run on user-generated content. Valid values are:

•

Content

•

Rate

Available in API 39.0 and later.

RateLimitTimePeriod

Required. Indicates the time period that is applied to the rate limit.

464

Metadata Types ModerationRule

Field Name

timePeriod

Field Type Description

( enumeration of type

string)

Required. Indicates the time period that is applied to the rate limit. Valid values are:

•

Short

•

Medium

Available in API 39.0 and later.

Declarative Metadata Sample Definition

The following is an example of a ModerationRule component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<ModerationRule xmlns= "http://soap.sforce.com/2006/04/metadata">

<description >Blocks Bad Word List in posts, comments, Link URLs, titles, and poll choices.

</description >

<masterLabel >Blocking Rule </masterLabel >

<action >Block </action >

<active >true </active >

<userMessage >You can't use %BLOCKED_KEYWORD% or other inappropriate words in this community. Review your content and try again.

</userMessage >

<!-- Applies the rule to FeedComment.RawCommentBody (an internal only field), if it contains words from the keyword list specified -->

<entitiesAndFields >

<entityName >FeedComment </entityName >

<fieldName >RawCommentBody </fieldName >

<keywordList >community1.badword_list

</keywordList >

</entitiesAndFields >

<entitiesAndFields >

<entityName >FeedItem </entityName >

<fieldName >LinkUrl </fieldName >

<keywordList >community1.badword_list

</keywordList >

</entitiesAndFields >

<!-- Applies the rule to FeedItem.RawBody (an internal only field), if it contains words from the keyword list specified -->

<entitiesAndFields >

<entityName >FeedItem </entityName >

<fieldName >RawBody </fieldName >

<keywordList >community1.badword_list

</keywordList >

</entitiesAndFields >

<entitiesAndFields >

<entityName >FeedItem </entityName >

<fieldName >Title </fieldName >

<keywordList >community1.badword_list

</keywordList >

</entitiesAndFields >

<entitiesAndFields >

<entityName >FeedPollChoice </entityName >

<fieldName >ChoiceBody </fieldName >

<keywordList >community1.badword_list

</keywordList >

</entitiesAndFields >

</ModerationRule >

465

Metadata Types NamedCredential

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<name >ModerationRule </name >

<members >community1.blocking_rule

</members >

</types >

<version >36.0

</version >

</Package >

NamedCredential

Represents a named credential, which specifies the URL of a callout endpoint and its required authentication parameters in one definition.

A named credential can be specified as an endpoint to simplify the setup of authenticated callouts.

This type extends the

Metadata metadata type and inherits its

fullName

field.

File Suffix and Directory Location

NamedCredential components have the suffix

.namedCredential

and are stored in the namedCredentials

folder.

Version

NamedCredential components are available in API version 33.0 and later.

Fields

Field Name

authProvider certificate

Field Type

string string endpoint label oauthRefreshToken oauthScope oauthToken string string string string string

Description

The authentication provider that the AuthProvider component represents.

If you specify a certificate, your Salesforce org supplies it when establishing each two-way SSL connection with the external system.

The certificate is used for digital signatures, which verify that requests are coming from your Salesforce org.

The URL or root URL of the callout endpoint. Corresponds to

URL

in the user interface.

A user-friendly name for the named credential that appears in the

Salesforce user interface, such as in list views.

The OAuth refresh token. Used to obtain a new access token for an end user when a token expires.

Specifies the scope of permissions to request for the access token.

Corresponds to

Scope

in the user interface.

The access token that’s issued by your authorization server.

466

Metadata Types Network

Field Name

password principalType protocol username

Field Type

string

Description

The password to be used by your org to access the external system.

Ensure that the credentials have adequate privileges to access the external system. Depending on how you set up access, you might need to provide the administrator password.

External

PrincipalType

(

enumeration of

type string)

Determines whether you're using one set or multiple sets of credentials to access the external system. Corresponds to

Identity Type

in the user interface. The valid values are:

•

Anonymous

•

PerUser

•

NamedUser

Authentication

Protocol

(

enumeration of

type string)

The authentication protocol for accessing the external system. The valid values are:

•

NoAuthentication

•

Oauth

•

Password string The username to be used by your org to access the external system.

Ensure that the credentials have adequate privileges for performing callouts to the external system. Depending on how you set up access, you might need to provide the administrator username.

Declarative Metadata Sample Definition

The following is an example of a NamedCredential component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<NamedCredential xmlns= "http://soap.sforce.com/2006/04/metadata">

<endpoint >https://my_endpoint.example.com

</endpoint >

<label >My Named Credential </label >

<principalType >PerUser </principalType >

<protocol >NoAuthentication </protocol >

</NamedCredential >

Network

Represents a community. Communities are branded spaces for your employees, customers, and partners to connect. You can customize and create communities to meet your business needs, then transition seamlessly between them. Use the Network component for

Salesforce Communities. If you want to create zones that contain Chatter Answers and Ideas, use the Community (Zone) component.

This type extends the

Metadata metadata type and inherits its

fullName

field.

467

Metadata Types

Declarative Metadata File Suffix and Directory Location

Network components are stored in the networks

directory of the corresponding package directory. The file name matches the community name, and the extension is

.network

.

Version

This object is available in API version 28.0 and later.

Fields

Field

allowedExtensions

Field Type

string allowMembersToFlag branding caseCommentEmailTemplate changePasswordTemplate description emailSenderAddress emailSenderName enableGuestChatter enableInvitation enableKnowledgeable boolean

Branding

string string string string string boolean boolean boolean

Description

Specifies the types of files allowed in your community.

This whitelist of file types lets you control what your community members upload and also prevents spammers from polluting your community with inappropriate files.

Available in API version 36.0 and later.

Determines whether users in the community can flag posts or comments as inappropriate. Flagged items are sent to a community moderator for review. Available in

API version 29.0 and later.

The color scheme, header, and footer used in the community.

Email template used when notifying community members when a case comment has been modified or added to a case.

Email template used when notifying a user that their password has been reset.

Description of the community.

Email address from which community emails are sent.

Name from which community emails are sent.

Specifies whether guest users can access public Chatter groups in the community without logging in.

Determines whether users can invite others to the community.

Determines if community members can see who’s knowledgeable on topics and endorse people for their knowledge on a topic. Available in API version 30.0 and later.

Network

468

Metadata Types

Field

enableNicknameDisplay enablePrivateMessages enableReputation enableSiteAsContainer forgotPasswordTemplate maxFileSizeKb navigationLinkSet networkMemberGroups newSenderAddress

Field Type

boolean boolean boolean boolean string int

NavigationLinkSet

NetworkMemberGroups

string

Description

Determines if user nicknames display instead of their first and last names in most places in the community. Set to false

by default. Available in API version 32.0 and later.

Determines if community members can send and receive private messages. Available in API version 30.0 and later.

Determines if reputation is calculated and displayed for community members. Available in API version 31.0 and later.

If enabled, reputationLevels

and reputationPointsRules

are used. If no reputationLevels

or reputationPointsRules

are not defined in the data file, the default values are used.

Determines whether the community uses Site.com pages instead of tabs.

The email template used when a user forgets their password.

Specifies the maximum file size (in KBs) that members can upload in your community. Available in API version 36.0

and later. Enter a number between 3072 KB and your org’s maximum file size. To use the default limit of 2 GB, leave this field empty.

Represents the navigation menu in a community. A navigation menu consists of items that users can click to go to other parts of the community. This field is available in API version 37.0 and later.

The profiles and permission sets that have access to the community. Users with these profiles or permission sets are members of the community.

Note: If a Chatter customer (from a customer group) is assigned a permission set that is also associated with a community, the Chatter customer isn’t added to the community.

Email address that has been entered as the new value for

EmailSenderAddress

but has not been verified yet. After a user has requested to change the sender email address and has successfully responded to the verification email, the

NewSenderAddress

value overwrites the value in

EmailSenderAddress

. This becomes the email address from which community emails are sent.

Network

469

Metadata Types

Field

picassoSite reputationLevels reputationPointsRules selfRegProfile selfRegistration sendWelcomeEmail site status tabs urlPathPrefix welcomeTemplate

Field Type

string

ReputationLevelDefinitions

ReputationPointsRules

string boolean boolean string

NetworkStatus[]

Description

Name of the Site.com site linked to the community.

The reputation levels assigned to members when they accrue points by performing certain actions.

The points members accrue when they perform certain defined actions.

The profile assigned to users who self register. This value is used only if selfRegistration

is enabled for the community. Available in API version 29.0 and later.

Determines whether self-registration is available for the community.

Determines whether a welcome email is sent when a new user is added to the community.

The CustomSite associated with the community.

Status of the community. Available values are:

•

Live—The community is online and members can access it.

•

DownForMaintenance—The community was previously published, but was taken offline. Members with “Create and Set Up Communities” can still access the setup for offline communities regardless of profile or membership. Members are not able to access offline communities, but they still appear in the user interface drop-down as

CommunityName (Offline)

.

•

UnderConstruction—The community has not yet been published. Users with “Create and Set Up

Communities” can access communities in this status if their profile is associated with the community.

Once a community is published, it can never be in this status again.

NetworkTabSet

string string

The tabs that are available in the community. The user that created the community selected these tabs.

The first part of the path on the site's URL that distinguishes this site from other sites. For example, if your site URL is mycompany.force.com/partners

, then partners

is the urlPathPrefix

.

The email template used when sending welcome emails to new community members.

Network

470

Metadata Types

Branding

Represents the branding and color scheme applied to the community.

Field

loginFooterText

Field Type

string loginLogo pageFooter pageHeader string string string primaryColor primaryComplementColor quaternaryColor string string string quaternaryComplementColor string secondaryColor tertiaryColor tertiaryComplementColor zeronaryColor zeronaryComplementColor string string string string string

Description

The text that appears in the footer of the community login page.

The logo that appears on the community login page for external users.

An image that appears on the footer of the community pages. Must be an .html file.

An image that appears on the header of the community pages. Can be an .html, .gif, .jpg, or .png file.

The color used for the active tab.

Font color used with primaryColor

.

The background color for pages in the community.

Font color used with quaternaryColor

.

The color used for the top borders of lists and tables.

The background color for section headers on edit and detail pages.

Font color used with tertiaryColor

.

The background color for the header.

Font color used with zeronaryColor

.

NavigationLinkSet

Represents the navigation menu in a community. A navigation menu consists of items that users can click to go to other parts of the community.

Field

navigationMenuItem

Field Type

NavigationMenuItem []

Description

A list of menu items in a NavigationLinkSet.

Use this object to create, delete, or update menu items in your community’s navigation menu.

Network

471

Metadata Types

NavigationMenuItem

Represents a single menu item in a NavigationLinkSet. Use this object to create, delete, or update menu items in your community’s navigation menu.

Field

defaultListViewId label position publiclyAvailable subMenu target targetPreference type

Field Type

string string int boolean

NavigationSubMenu

string string string

Description

If the value of the type

field is

SalesforceObject

, the value is the

ID of the default list view for the object.

Required. The text that appears in the navigation menu for this item.

Required. The location of the menu item in the navigation menu.

When set to true

, gives access to guest users.

A list of child menu items. This field is available in API 39.0 and later.

Required if type

is

ExternalLink

,

InternalLink

, or

SalesforceObject

. If type

is

ExternalLink

or

InternalLink

, the target is the URL that the link points to.

For

ExternalLink

, your entry looks like this:

http://www.salesforce.com

.

For

InternalLink

, use a relative URL, such as

/contactsupport

. If type is

MenuLabel

or

NavigationalTopic

, target

is not used.

Backed by a picklist that includes preferences for the target field. Valid values are:

•

None

•

OpenInExternalTab

—Used for external links to determine whether to open in an external tab.

Required. The type of navigation menu item.

Valid values are:

•

SalesforceObject

—Available objects include accounts, cases, contacts, and custom objects.

•

ExternalLink

—Links to a URL outside of your community. For

Network

472

Metadata Types

Field Field Type Description

example,

http://www.salesforce.com

.

•

InternalLink

—Links to a relative

URL inside your community. For example,

/contactsupport

.

•

MenuLabel

—A parent heading for your navigation menu. See

NavigationSubMenu for how to nest

items underneath the menu label. This value is available in API 39.0 and later.

•

NavigationalTopic

—A drop-down list with links to the navigational topics in your community.

You cannot nest other items of type

MenuLabel

or items of type

NavigationalTopic

under

MenuLabel

.

Network

NavigationSubMenu

A list of child menu items. Only NavigationMenuItem items of type

MenuLabel

can have items in a NavigationSubMenu. Available in API 39.0 and later.

Field

navigationMenuItem

Field Type

NavigationMenuItem []

Description

A list of menu items in a

NavigationSubMenu. Use navigationMenuItem

to create, delete, or update child items under a parent heading.

NetworkMemberGroup

Represents the profiles and permission sets that are assigned to the community. Users with one of the profiles or permission sets are members of the community, unless the user is a Chatter customer (from a customer group).

Field

permissionSet

Field Type

string

Description

A permission set that is assigned to the community.

Note: If a Chatter customer (from a customer group) is assigned a permission set that is also associated with a community, the Chatter

473

Metadata Types

Field

profile

Field Type

string

Description

customer isn’t added to the community.

A profile that is part of the community.

ReputationBranding

Branding for the reputation level.

Field

smallImage

Field Type

string

Description

Custom image associated with a reputation level. Use files with these extensions: .jpeg,

.png, or .gif. Images are stored as documents. If not specified, the default reputation level image is used. Available in

API version 32.0 and later.

ReputationLevelDefinitions

Represents reputation levels members can achieve by performing certain defined actions in a community.

Field

level

Field Type

ReputationLevel []

Description

Represents reputation levels.

ReputationLevel

Represents the name and lower value of the reputation level. The upper value is calculated by the application.

Field

branding label

Field Type

ReputationBranding []

string

Description

Represents any branding associated with the reputation level, specifically, the custom image for the reputation level.

This field is optional. If not specified, the default reputation level image is used.

Available in API version 32.0 and later.

Name of the reputation level.

This field is optional. If not specified, one of the 10 defaults are used.

•

Level 1

•

Level 2

Network

474

Metadata Types

Field

lowerThreshold

Field Type

double

Description

•

Level 3

•

Level 4

•

Level 5

•

Level 6

•

Level 7

•

Level 8

•

Level 9

•

Level 10

Required. The lower value in the range for this reputation level. For example, if this reputation level is for points 1–50, 1 is the lowerThreshold

.

ReputationPointsRules

Represents points rules in a community’s point system.

Field

pointsRule

Field Type

ReputationPointsRule []

Description

Represents events and their associated points.

ReputationPointsRule

Represents the event and associated point value for a points rule. When a user acts, they accrue the associated points.

Field

eventType

Field Type

string

Description

Required. The type of event a member has to perform to get points.

The available values are:

•

FeedItemWriteAPost

•

FeedItemWriteAComment

•

FeedItemReceiveAComment

•

FeedItemLikeSomething

•

FeedItemReceiveALike

•

FeedItemMentionSomeone

•

FeedItemSomeoneMentionsYou

•

FeedItemShareAPost

•

FeedItemSomeoneSharesYourPost

•

FeedItemPostAQuestion

•

FeedItemAnswerAQuestion

Network

475

Metadata Types

Field

points

Field Type

int

NetworkTabSet

Field

customTab defaultTab standardTab

Field Type

string string string

Description

•

FeedItemReceiveAnAnswer

•

FeedItemMarkAnswerAsBest

•

FeedItemYourAnswerMarkedBest

•

FeedItemEndorseSomeoneForKnowledgeOnATopic

•

FeedItemEndorsedForKnowledgeOnATopic

Required. The number of points a member gets for performing the event. The default number of points per event is:

•

FeedItemWriteAPost +1

•

FeedItemWriteAComment: +1

•

FeedItemReceiveAComment: +5

•

FeedItemLikeSomething: +1

•

FeedItemReceiveALike: +5

•

FeedItemMentionSomeone: +1

•

FeedItemSomeoneMentionsYou: +5

•

FeedItemShareAPost: +1

•

FeedItemSomeoneSharesYourPost: +5

•

FeedItemPostAQuestion: +1

•

FeedItemAnswerAQuestion: +5

•

FeedItemReceiveAnAnswer: +5

•

FeedItemMarkAnswerAsBest: +5

•

FeedItemYourAnswerMarkedBest: +20

•

FeedItemEndorseSomeoneForKnowledgeOnATopic: +5

•

FeedItemEndorsedForKnowledgeOnATopic: +20

Network

Description

Custom tab that is part of the community.

The Home tab for the community. When members log in, this tab is the first page they see.

Standard tab that is part of the community.

476

Metadata Types

Declarative Metadata Sample Definition

A sample XML definition of a network.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Network xmlns= "http://soap.sforce.com/2006/04/metadata">

<allowMembersToFlag >true </allowMembersToFlag >

<branding >

<loginFooterText >salesforce.com

</loginFooterText >

<loginLogo >Communities_Shared_Document_Folder/header2_png.png

</loginLogo >

<pageFooter >Branding/footer_html.html

</pageFooter >

<pageHeader >Branding/header_Image.jpg

</pageHeader >

<primaryColor >#AF5800 </primaryColor >

<primaryComplementColor >#FFFFFF </primaryComplementColor >

<quaternaryColor >#286FB8 </quaternaryColor >

<quaternaryComplementColor >#FFFFFF </quaternaryComplementColor >

<secondaryColor >#000000 </secondaryColor >

<tertiaryColor >#FFFFFF </tertiaryColor >

<tertiaryComplementColor >#222222 </tertiaryComplementColor >

<zeronaryColor >#0A3764 </zeronaryColor >

<zeronaryComplementColor >#FFFFFF </zeronaryComplementColor >

</branding >

<changePasswordTemplate >unfiled$public/CommunityChangePasswordEmailTemplate </changePasswordTemplate >

<description >Metadata Community </description >

<emailSenderAddress >[email protected]

</emailSenderAddress >

<emailSenderName >Admin User </emailSenderName >

<enableInvitation >false </enableInvitation >

<enableKnowledgeable >true </enableKnowledgeable >

<enableNicknameDisplay >false </enableNicknameDisplay >

<enablePrivateMessages >true </enablePrivateMessages >

<enableReputation >true </enableReputation >

<forgotPasswordTemplate >unfiled$public/CommunityForgotPasswordEmailTemplate </forgotPasswordTemplate >

<networkMemberGroups >

<permissionSet >Admin </permissionSet >

<permissionSet >Standard </permissionSet >

<permissionSet >ReadOnly </permissionSet >

<profile >Admin </profile >

<profile >Standard </profile >

<profile >ReadOnly </profile >

</networkMemberGroups >

<reputationLevels >

<level >

<branding >

<smallImage >communities_shared

_document_folder/replevel_beginner.png

</smallImage >

</branding >

<label >Beginner </label >

<lowerThreshold >0 </lowerThreshold >

</level >

<level >

<branding >

Network

477

Metadata Types

<smallImage >communities_shared

_document_folder/replevel_apprentice.png

</smallImage >

</branding >

<label >Apprentice </label >

<lowerThreshold >51 </lowerThreshold >

</level >

<level >

<branding >

<smallImage >communities_shared

_document_folder/replevel_gettingthere.png

</smallImage >

</branding >

<label >Getting There </label >

<lowerThreshold >101 </lowerThreshold >

</level >

<level >

<branding >

<smallImage >communities_shared

_document_folder/replevel_skilled.png

</smallImage >

</branding >

<label >Skilled </label >

<lowerThreshold >151 </lowerThreshold >

</level >

<level >

<branding >

<smallImage >communities_shared

_document_folder/replevel_expert.png

</smallImage >

</branding >

<label >Expert </label >

<lowerThreshold >201 </lowerThreshold >

</level >

<level >

<branding >

<smallImage >communities_shared

_document_folder/replevel_mentor.png

</smallImage >

</branding >

<label >Mentor </label >

<lowerThreshold >251 </lowerThreshold >

</level >

<level >

<branding >

<smallImage >communities_shared

_document_folder/replevel_guru.png

</smallImage >

</branding >

<label >Guru </label >

<lowerThreshold >301 </lowerThreshold >

</level >

</reputationLevels >

<reputationPointsRules >

<pointsRule >

<eventType >FeedItemWriteAPost </eventType >

<points >5 </points >

</pointsRule >

<pointsRule >

<eventType >FeedItemWriteAComment </eventType >

478

Network

Metadata Types

<points >3 </points >

</pointsRule >

<pointsRule >

<eventType >FeedItemReceiveAComment </eventType >

<points >10 </points >

</pointsRule >

<pointsRule >

<eventType >FeedItemLikeSomething </eventType >

<points >3 </points >

</pointsRule >

<pointsRule >

<eventType >FeedItemReceiveALike </eventType >

<points >5 </points >

</pointsRule >

<pointsRule >

<eventType >FeedItemMentionSomeone </eventType >

<points >5 </points >

</pointsRule >

<pointsRule >

<eventType >FeedItemSomeoneMentionsYou </eventType >

<points >10 </points >

</pointsRule >

<pointsRule >

<eventType >FeedItemShareAPost </eventType >

<points >5 </points >

</pointsRule >

<pointsRule >

<eventType >FeedItemSomeoneSharesYourPost </eventType >

<points >10 </points >

</pointsRule >

</reputationPointsRules >

<selfRegistration >false </selfRegistration >

<sendWelcomeEmail >true </sendWelcomeEmail >

<site >Network_11 </site >

<status >UnderConstruction </status >

<tabs >

<defaultTab >Chatter </defaultTab >

<standardTab >Chatter </standardTab >

<standardTab >Account </standardTab >

<standardTab >Campaign </standardTab >

<standardTab >Case </standardTab >

<standardTab >Console </standardTab >

<standardTab >Contact </standardTab >

<standardTab >Contract </standardTab >

<standardTab >Dashboard </standardTab >

<standardTab >JigsawSearch </standardTab >

<standardTab >File </standardTab >

<standardTab >CollaborationGroup </standardTab >

<standardTab >home </standardTab >

<standardTab >Idea </standardTab >

<standardTab >Lead </standardTab >

<standardTab >Opportunity </standardTab >

<standardTab >Product2 </standardTab >

<standardTab >UserProfile </standardTab >

479

Network

Metadata Types

<standardTab >report </standardTab >

<standardTab >Solution </standardTab >

</tabs >

<urlPathPrefix >network1 </urlPathPrefix >

<welcomeTemplate >unfiled$public/CommunityWelcomeEmailTemplate </welcomeTemplate >

</Network >

SEE ALSO:

Community (Zone)

Package

Specifies which metadata components to retrieve as part of a retrieve()

call or defines a package of components.

Name

apiAccessLevel description fullName namespacePrefix objectPermissions packageType

Type

APIAccessLevel ( enumeration

of type string) string string string

ProfileObjectPermissions

string

[]

Description

Package components have access via dynamic Apex and the

API to standard and custom objects in the organization where they are installed. Administrators who install packages may wish to restrict this access after installation for improved security. The valid values are:

•

Unrestricted—Package components have the same API access to standard objects as the user who is logged in when the component sends a request to the API.

•

Restricted—The administrator can select which standard objects the components can access. Further, the components in restricted packages can only access custom objects in the current package if the user's permissions allow access to them.

For more information, see “About API and Dynamic Apex Access in Packages” in the Salesforce online help.

A short description of the package.

The package 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. This field is inherited

from the Metadata

component.

The namespace of the developer organization where the package was created.

Indicates which objects are accessible to the package, and the kind of access available (create, read, update, delete).

Reserved for future use.

Package

480

Metadata Types

Name

postInstallClass setupWeblink types uninstallClass version

Type

string string

PackageTypeMembers[] string string

Description

The name of the Apex class that specifies the actions to execute after the package has been installed or upgraded. The Apex class must be a member of the package and must implement the Apex

InstallHandler

interface. In patch upgrades, you can't change the class name in this field but you can change the contents of the Apex class. The class name can be changed in major upgrades.

This field is available in API version 24.0 and later.

The weblink used to describe package installation.

The type of component being retrieved.

The name of the Apex class that specifies the actions to execute after the package has been uninstalled. The Apex class must be a member of the package and must implement the Apex

UninstallHandler

interface. In patch upgrades, you can't change the class name in this field but you can change the contents of the Apex class. The class name can be changed in major upgrades.

This field is available in API version 25.0 and later.

Required. The version of the component type.

PackageTypeMembers

Use to specify the name and type of components to be retrieved in a package.

Name

members

Type

string

Description

One or more named components, or the wildcard character

(

*

) to retrieve all metadata components of the type specified in the

<name >

element. To retrieve a standard object, specify it by name. For example,

<members >Account </members >

retrieves the standard

Account object.

name string

The type of metadata component to be retrieved. For example,

<name >CustomObject </name >

retrieves one or more custom objects as specified in the

<members >

element.

Package

SEE ALSO:

Sample package.xml Manifest Files

481

Metadata Types PathAssistant

PathAssistant

Represents Path records.This type extends the Metadata

metadata type and inherits its fullName

field.

Note the following when working with PathAssistant:

•

Only one path can be created per record type for each object, including __Master__ record type.

•

Rich text guidance information cannot be retrieved or deployed from or to translation workbench.

•

The preference does not need to be on to retrieve or deploy PathAssistant.

File Suffix and Directory Location

PathAssistant components have the suffix

.pathAssistant

and are stored in the pathAssistants

folder.

Version

PathAssistant components are available in API version 34.0 and later.

Fields

Field Name

active entityName fieldName masterLabel pathAssistantSteps recordTypeName

Field Type

boolean string string

Description

Indicates whether the path is active ( true

) or not ( false

).

Required. The entity name. This is hard coded for Opportunity, Lead, and

Quote. For a custom object, this field must be specified and should be the name of the custom object. This field is not updateable.

Required. The field name. This is hard coded for StageName and Status.

For a custom object, this field must be specified and should be the name of the picklist field that determines the steps in the path. This field is not updateable.

string Required. The master label of the path.

PathAssistantStep[]

on page 482

List of all the steps that have been configured with fields and guidance information. Note that a missing step in the .xml file means it has not been configured, not that it doesn’t exist.

string Required. The name of the record type associated with the path. This field is not updateable.

PathAssistantStep

Represents the steps or stages in a Path.

Field Name

fieldNames

Field Type

string

Description

All the fields in entityName

that will display in this step.

482

Metadata Types

Field Name

info picklistValueName

Field Type

string string

Description

The guidance information displayed in this step.

Required. The picklist value associated with the step.

Declarative Metadata Sample Definition

The following is an example of a PathAssistant component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<PathAssistant xmlns= "http://soap.sforce.com/2006/04/metadata">

<active >true </active >

<entityName >Opportunity </entityName >

<fieldName >StageName </fieldName >

<masterLabel >Test Path </masterLabel >

<pathAssistantSteps >

<fieldNames >Amount </fieldNames >

<fieldNames >CloseDate </fieldNames >

<info >Some Text </info >

<picklistValueName >Id. Decision Makers </picklistValueName >

</pathAssistantSteps >

<pathAssistantSteps >

<fieldNames >Amount </fieldNames >

<fieldNames >CloseDate </fieldNames >

<info >Some Text </info >

<picklistValueName >Proposal/Price Quote </picklistValueName >

</pathAssistantSteps >

<recordTypeName >Test_Record_Type </recordTypeName >

</PathAssistant >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Opportunity.Test_Busines_Process

</members >

<name >BusinessProcess </name >

</types >

<types >

<members >Opportunity.StageName

</members >

<members >Lead.LeadSource

</members >

<members >Opportunity.Type

</members >

<name >CustomField </name >

</types >

<types >

<members >Test_Path </members >

<name >PathAssistant </name >

</types >

<types >

<members >Opportunity.Test_Record_Type

</members >

<name >RecordType </name >

</types >

<types >

483

PathAssistant

Metadata Types PermissionSet

<members >PathAssistant </members >

<name >Settings </name >

</types >

<version >39.0

</version >

</Package >

PermissionSet

Represents a set of permissions that's used to grant additional access to one or more users without changing their profile or reassigning

profiles. You can use permission sets to grant access, but not to deny access. This type extends the Metadata

metadata type and inherits its fullName

field.

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

For more information, see Managed Component Access in Sample package.xml

Manifest Files

on page 22.

Declarative Metadata File Suffix and Directory Location

Permission sets are stored in the permissionsets

directory. The file name matches the permission set API name and the extension is

.permissionset

. For example, a permission set with the name User_Management_Perms is stored in permissionsets/User_Management_Perms.permissionset

.

Version

Permission sets are available in API version 22.0 and later.

Fields

Field Field Type

applicationVisibilities

PermissionSetApplicationVisibility

[]

Description

Indicates which apps are visible to users assigned to this permission set. Available in API version 29.0 and later. In

API version 29.0, this field supports custom apps only. In

API version 30.0 and later, this field supports both standard and custom apps.

484

Metadata Types PermissionSet

Field

classAccesses customPermissions

Field Type

PermissionSetApexClassAccess []

Description

Indicates which top-level Apex classes have methods that users assigned to this permission set can execute.

Available in API version 23.0 and later.

PermissionSetCustomPermissions []

Indicates which custom permissions are available to users assigned to this permission set. Available in API version

31.0 and later.

description externalDataSourceAccesses fieldPermissions hasActivationRequired label objectPermissions pageAccesses recordTypeVisibilities tabSettings license userLicense string

PermissionSetExternal

DataSourceAccess []

PermissionSetFieldPermissions

boolean

[]

The permission set description. Limit: 255 characters.

Indicates which data sources with identity type of

Per

User

are available to users assigned to this permission set. Available in API version 27.0 and later.

Indicates which fields are accessible to a user assigned to this permission set, and the kind of access available

(readable or editable). Available in API version 23.0 and later.

Indicates whether the permission set requires an associated active session ( true

) or not ( false

).

Available in API version 37.0 and later.

Required. The permission set label. Limit: 80 characters.

string

PermissionSetObjectPermissions

[] Indicates the objects that are accessible to a user assigned to this permission set, and the kind of access available

(create, read, edit, delete, and so on). Available in API version 23.0 and later.

PermissionSetApexPageAccess []

PermissionSetRecordTypeVisibility []

Indicates which record types are visible to users assigned to this permission set. Available in API version 29.0 and later. This field is never retrieved or deployed for inactive record types.

PermissionSetTabSetting []

Indicates which Visualforce pages that users assigned to this permission set can execute. Available in API version

23.0 and later.

string string

Indicates the tab visibility settings for this permission set.

Available in API version 26.0 and later.

Either the related permission set license or the user license associated with this permission set. Available in

API version 38.0 and later. Use this field instead of userLicense

, which is deprecated and only available up to API Version 37.0.

Deprecated. The user license for the permission set. A user license determines the baseline of features that the user can access. Every user must have exactly one user

485

Metadata Types PermissionSet

Field

userPermissions

Field Type

PermissionSetUserPermission

[]

Description

license. Available up to API version 37.0. In API version

38.0 and later, use license

.

Specifies an app or system permission (such as “API

Enabled”) and whether it's enabled for this permission set. In API version 28.0 and earlier, this field retrieves all user permissions, enabled or disabled. In API version 29.0

and later, this field retrieves only enabled user permissions.

PermissionSetApplicationVisibility

PermissionSetApplicationVisibility determines whether an app is visible to a user assigned to this permission set.

Field Name

application visible

Field Type

string boolean

Description

Required. The app name.

Required. Indicates whether this app is visible to users assigned to this permission set ( true

) or not ( false

).

PermissionSetApexClassAccess

PermissionSetApexClassAccess represents the Apex class access for users assigned to a permission set.

Field

apexClass enabled

Field Type

string boolean

Description

Required. The Apex class name.

Required. Indicates whether users assigned to this permission set can execute methods in the top-level class ( true

) or not ( false

).

PermissionSetCustomPermissions

PermissionSetCustomPermissions represents the custom permissions access for users assigned to a permission set. Only enabled custom permissions are retrieved.

Field Name

enabled name

Field Type

boolean string

Description

Required. Indicates whether the custom permission is enabled ( true

) or not ( false

).

Required. The custom permission name.

486

Metadata Types PermissionSet

PermissionSetExternalDataSourceAccess

PermissionSetExternalDataSourceAccess represents the data source access for users with identity type of

Per User

. Available in API version 27.0 and later.

Field

enabled externalDataSource

Field Type

boolean string

Description

Required. Indicates whether the data source is enabled ( true

) or not ( false

).

The name of the external data source.

PermissionSetFieldPermissions

PermissionSetFieldPermissions represents the field permissions for users assigned to a permission set. In API version 30.0 and later, permissions for required fields can’t be retrieved or deployed.

Note: As of API version 38.0, you can change field permissions to make a field editable using the Metadata API for fields that you can't change through the user interface. For example, you can deploy

Asset.ProductCode

as an editable field even though you can't through the user interface.

Field

editable field readable

Field Type

boolean string boolean

Description

Required. Indicates whether the field can be edited by the users assigned to this permission set ( true

) or not ( false

).

Required. The API name of the field (such as

Warehouse__c.Description__c

).

Indicates whether the field can be read by the users assigned to this permission set ( true

) or not ( false

).

PermissionSetObjectPermissions

PermissionSetObjectPermissions represents the object permissions for a permission set. Use one of these elements for each permission.

Field

allowCreate allowDelete allowEdit

Field Type

boolean boolean boolean

Description

Required. Indicates whether the object referenced by the object

field can be created by the users assigned to this permission set

( true

) or not ( false

).

Required. Indicates whether the object referenced by the object

field can be deleted by the users assigned to this permission set

( true

) or not ( false

).

Required. Indicates whether the object referenced by the object

field can be edited by the users assigned to this permission set

( true

) or not ( false

).

487

Metadata Types PermissionSet

Field

allowRead modifyAllRecords boolean object viewAllRecords

Field Type

boolean string boolean

Description

Required. Indicates whether the object referenced by the object

field can be viewed by the users assigned to this permission set

( true

) or not ( false

).

Required. Indicates whether the object referenced by the object

field can be viewed, edited, or deleted by the users assigned to this permission set ( true

) or not ( false

), regardless of the sharing settings for the object. This includes private records (records with no parent object). This is similar to the “Modify All Data” user permission, but limited to the individual object level.

Required. The API name of the object (such as

Warehouse__c

).

Required. Indicates whether the object referenced by the object

field can be viewed by the users assigned to this permission set

( true

) or not ( false

), regardless of the sharing settings for the object. This includes private records (records with no parent object).

This is similar to the “View All Data” user permission, but limited to the individual object level.

PermissionSetApexPageAccess

PermissionSetApexPageAccess represents the Visualforce page access for users assigned to a permission set.

Field

apexPage enabled

Field Type

string boolean

Description

Required. The Visualforce page name.

Required. Indicates whether users assigned to this permission set can execute the Visualforce page ( true

) or not ( false

).

PermissionSetRecordTypeVisibility

PermissionSetRecordTypeVisibility represents the visibility of record types for this permission set.

Field

recordType visible

Field Type

string boolean

Description

Required. The record type name, for example

Account.MyRecordType

.

Required. Indicates whether the record type is visible to users assigned to this permission set ( true

) or not ( false

).

PermissionSetTabSetting

PermissionSetTabSetting represents the tab settings for a permission set.

488

Metadata Types

Field

tab visibility

PermissionSet

Field Type

string

PermissionSetTabVisibility

( enumeration of type string)

Description

Required. The tab name.

Required. Indicates the visibility settings for the tab. Valid values are:

•

Available

—The tab is available on the All Tabs page.

Individual users can customize their display to make the tab visible in any app.

•

None

—The tab isn’t available on the All Tabs page or visible in any apps.

•

Visible

—The tab is available on the All Tabs page and appears in the visible tabs for its associated app. Individual users can customize their display to hide the tab or make it visible in other apps.

PermissionSetUserPermission

PermissionSetUserPermission represents an app or system permission for a permission set. Use one of these elements for each permission.

Field

enabled name

Field Type

boolean string

Description

Required. Indicates whether the permission is enabled ( true

) or disabled ( false

).

Required. The name of the permission.

Declarative Metadata Sample Definition

When adding or changing a permission set, you don't need to include all permissions—you only need to include the permissions you're adding or changing.

<?xml

version= "1.0" encoding= "UTF-8"?>

<PermissionSet xmlns= "http://soap.sforce.com/2006/04/metadata">

<description >Grants all rights needed for an HR administrator to manage employees.

</description >

<label >HR Administration </label >

<userLicense >Salesforce </userLicense >

<applicationVisibilities >

<application >JobApps__Recruiting </application >

<visible >true </visible >

</applicationVisibilities >

<userPermissions >

<enabled >true </enabled >

<name >APIEnabled </name >

</userPermissions >

<objectPermissions >

<allowCreate >true </allowCreate >

<allowDelete >true </allowDelete >

489

Metadata Types PermissionSet

<allowEdit >true </allowEdit >

<allowRead >true </allowRead >

<viewAllRecords >true </viewAllRecords >

<modifyAllRecords >true </modifyAllRecords >

<object >Job_Request__c </object >

</objectPermissions >

<fieldPermissions >

<editable >true </editable >

<field >Job_Request__c.Salary__c

</field >

<readable >true </readable >

</fieldPermissions >

<pageAccesses >

<apexPage >Job_Request_Web_Form </apexPage >

<enabled >true </enabled >

</pageAccesses >

<classAccesses >

<apexClass >Send_Email_Confirmation </apexClass >

<enabled >true </enabled >

</classAccesses >

<tabSettings >

<tab >Job_Request__c </tab >

<visibility >Available </visibility >

</tabSettings >

<recordTypeVisibilities >

<recordType >Recruiting.DevManager

</recordType >

<visible >true </visible >

</recordTypeVisibilities >

</PermissionSet >

The following is an example package.xml manifest used to retrieve the PermissionSet metadata for an organization. When you retrieve permission sets, you should also retrieve the related components with assigned permissions. For example, to retrieve objectPermissions

and fieldPermissions

for a custom object, you must also retrieve the CustomObject component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Job_Request__c </members >

<name >CustomTab </name >

</types >

<types >

<members >Job_Request__c </members >

<name >CustomObject </name >

</types >

<types >

<members >JobApps__Recruiting </members >

<name >CustomApplication </name >

</types >

<types >

<members >Recruiting.DevManager

</members >

<name >RecordType </name >

</types >

<types >

<members >* </members >

<name >PermissionSet </name >

</types >

490

Metadata Types PlatformCachePartition

<version >39.0

</version >

</Package >

PlatformCachePartition

Represents a partition in the Platform Cache. This type extends the Metadata

metadata type and inherits its fullName

field.

File Suffix and Directory Location

PlatformCachePartition components have the suffix

.cachePartition

and are stored in the cachePartitions

folder.

Version

PlatformCachePartition components are available in API version 35.0 and later.

Special Access Rules

The “Author Apex” permission is required to deploy and retrieve PlatformCachePartition components.

Fields

Field Name

description isDefaultPartition masterLabel

Field Type

string boolean string

Description

Describes the cache partition.

Required. Indicates whether this cache partition is the default partition in your organization ( true

) or not ( false

).

Required. The label of the cache partition that appears in the

Salesforce user interface.

platformCachePartitionTypes

PlatformCachePartitionType []

An array of cache types that the partition can store.

PlatformCachePartitionType

Contains information about a partition type, including its minimum and allocated capacity.

Field Name

allocatedCapacity

Field Type

int allocatedPurchasedCapacity int

Description

Required. The total storage capacity, in MB, that is allocated for the cache type, including free, purchased, and trial cache. Purchased capacity includes organization-wide cache, which can be used in any partition, and namespace-specific cache, which can be used only in partitions associated with a namespace.

Required. The amount of namespace-specific purchased storage capacity, in MB, that is allocated for the cache type.

491

Metadata Types PlatformCachePartition

Field Name

allocatedTrialCapacity cacheType

Field Type

int

Description

Required. The amount of trial cache space, in MB, that is allocated for the cache type.

PlatformCacheType

( enumeration

of type string)

The type of cache. Valid values are:

•

Session

—Session cache

•

Organization

—Org cache

Declarative Metadata Sample Definition

The following is an example of a PlatformCachePartition component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<PlatformCachePartition xmlns= "http://soap.sforce.com/2006/04/metadata">

<description >Custom partition and marked as default.

</description >

<isDefaultPartition >true </isDefaultPartition >

<masterLabel >myPartition </masterLabel >

<platformCachePartitionTypes >

<allocatedCapacity>10</allocatedCapacity>

<allocatedPurchasedCapacity>5</allocatedPurchasedCapacity>

<cacheType >Session </cacheType >

</platformCachePartitionTypes >

<platformCachePartitionTypes >

<allocatedCapacity>5</allocatedCapacity>

<allocatedPurchasedCapacity>5</allocatedPurchasedCapacity>

<cacheType >Organization </cacheType >

</platformCachePartitionTypes >

</PlatformCachePartition >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >myPartition </members >

<name >PlatformCachePartition </name >

</types >

<version >39.0

</version >

</Package >

If a namespace is defined in your organization, add the namespace prefix to your partition name. For example:

<members >Namespace.myPartition

</members >

To retrieve all cache partitions from your organization, use the wildcard character (*) as follows.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >PlatformCachePartition </name >

</types >

492

Metadata Types

<version >39.0

</version >

</Package >

Portal

The Portal metadata type represents a partner portal or Customer Portal. It extends Metadata

and inherits its fullName

field. To use this metadata type, you must have a partner portal or Customer Portal enabled for your organization. For more information, see “Partner

Portal Overview” and “Enabling Your Customer Portal” in the Salesforce online help.

Declarative Metadata File Suffix and Directory Location

Force.com Portal components are stored in the portals

directory of the corresponding package directory. The file name matches the portal name, and the extension is

.portal

.

Version

Force.com Portal components are available in API version 15.0 and later.

Fields

Field

active admin defaultLanguage

Field Type

boolean string string description emailSenderAddress emailSenderName enableSelfCloseCase footerDocument forgotPassTemplate string string string boolean string string

Description

Required. Denotes whether this portal is active.

The full name of the user designated to administer the portal.

The default language for HTML messages for the portal. Use the abbreviation for the language, for example, en_US for United

States English.

The portal description.

Required. The email address used when sending emails using templates configured from the portal (for example, for resetting the password).

Required. The name to display when sending emails using templates configured from the portal (for example, for resetting the password).

For the Customer Portal, allows portal users to close their own cases.

The file to be used as the footer for this portal.

The email template to use when a user clicks the Forgot

Password link.

Portal

493

Metadata Types

Field

fullName

Field Type

string

Description

Required. The name of the portal.

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.

headerDocument loginHeaderDocument logoDocument logoutUrl newCommentTemplate string isSelfRegistrationActivated boolean newPassTemplate newUserTemplate ownerNotifyTemplate selfRegNewUserUrl string string string string string string string string selfRegUserDefaultProfile string selfRegUserDefaultRole

PortalRoles (

enumeration of

type string)

The file to be used as the header for this portal.

Determines whether self-registration is active or not for this portal.

The file to be used as the header for this portal's login page.

The file to be used as the logo for this portal.

The URL that the user should be redirected to on logout.

The email template to be used for auto-notifications on new case comments.

The email template to be used for auto-notifications on password reset.

The email template to be used for auto-notifications on new user creation.

The email template to be used for auto-notifications on owner change.

The URL of the self-registration page.

The default profile for self-registered users.

The default role for self-registered users. The valid values are:

•

Executive

•

Manager

•

User

•

PersonAccount selfRegUserTemplate showActionConfirmation stylesheetDocument type string boolean

The email template to be used for auto-notifications on self-registration.

Determines whether or not confirmation messages are displayed for actions in the portal.

string The Document object to be used as the CSS stylesheet for this portal.

PortalType (

enumeration of type

string)

Required. The type for this portal. The valid values are:

•

CustomerSuccess

•

Partner

Portal

494

Metadata Types PostTemplate

Declarative Metadata Sample Definition

A sample XML definition of a portal is shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Portal xmlns= "http://soap.sforce.com/2006/04/metadata">

<active >true </active >

<description >Customer Portal </description >

<emailSenderName >[email protected]

</emailSenderName >

<enableSelfCloseCase >false </enableSelfCloseCase >

<forgotPassTemplate >unfiled$public/ChangePwdEmail </forgotPassTemplate >

<isSelfRegistrationActivated >false </isSelfRegistrationActivated >

<newPassTemplate >unfiled$public/ChangePwdEmail </newPassTemplate >

<newUserTemplate >unfiled$public/NewUserEmail </newUserTemplate >

<selfRegUserTemplate >unfiled$public/SelfRegUserEmail </selfRegUserTemplate >

<showActionConfirmation >false </showActionConfirmation >

<type >CustomerSuccess </type >

</Portal >

SEE ALSO:

CustomSite

PostTemplate

Represents the metadata associated with an approval post template for Approvals in Chatter. With approval post templates, you can

customize the information included in approval request posts that appear in Chatter feeds. This type extends the Metadata

metadata type and inherits its fullName

field.

Note: Review Chatter Post Templates for Approval Requests in the Salesforce Help before you create a post template.

File Suffix and Directory Location

PostTemplate components have the suffix

.postTemplate

and are stored in the postTemplates

folder.

Version

PostTemplate components are available in API version 29.0 and later.

Fields

Field Name

default

Field Type

boolean

Description

Required. Specifies whether this is the default post template for the given object.

When set to true

, this post template is used by approval processes that are associated with the same object and don’t specify a post template.

495

Metadata Types

Field Name

description fields label

Field Type

string string[] string

Description

When an object has no default post template, each of its approval processes uses the system default post template, unless the approval process specifies its own post template.

Optional description of the post template.

Required. An array of up to four fields to include in approval request posts.

If the approval object is a detail object in a master-detail relationship,

Owner isn’t available for approval page layouts or approval post templates.

Required. Name of the post template. This non-unique label is different from the unique name of the post template.

Declarative Metadata Sample Definition

The following is an example of a PostTemplate component:

<PostTemplate xmlns= "http://soap.sforce.com/2006/04/metadata">

<default >false </default >

<fields >NumberOfEmployees </fields >

<fields >NumberofLocations__c </fields >

<fields >PartnerAccount </fields >

<fields >LeadCustomFieldNumber__c </fields >

<label >My Lead Post Template </label >

</PostTemplate >

The following is an example package manifest that references the previous PostTemplate component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Lead.leadtemplate

</members >

<name >PostTemplate </name >

</types >

<version >29.0

</version >

</Package >

Profile

Represents a user profile. A profile defines a user’s permission to perform different functions within Salesforce. This type extends the

Metadata

metadata type and inherits its fullName

field.

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

Profile

496

Metadata Types

•

Custom tab settings

•

External data sources

•

Record types

•

Visualforce pages

For more information, see Managed Component Access in Sample package.xml

Manifest Files

on page 22.

Declarative Metadata File Suffix and Directory Location

The file suffix is

.profile

. There is one file for each profile, stored in the profiles

folder in the corresponding package directory.

Version

Profiles are available in API version 10.0 and later.

Fields

The content of a profile returned by Metadata API depends on the content requested in the

RetrieveRequest message. For example,

profiles only include field-level security for fields included in custom objects returned in the same RetrieveRequest as the profiles.

Note: As of API version 38.0, you can change field permissions to make a field editable using the Metadata API for fields that you can't change through the user interface. For example, you can deploy

Asset.ProductCode

as an editable field even though you can't through the user interface.

The profile definition contains the following fields:

Field Name

applicationVisibilities classAccesses custom customPermissions description

Field Type

ProfileApplicationVisibility []

ProfileApexClassAccess

boolean string

[]

ProfileCustomPermissions

[] externalDataSourceAccesses

ProfileExternalDataSourceAccess []

Description

Indicates which apps are visible to users assigned to this profile. In API version 29.0 and earlier, this field supports custom apps only. In API version 30.0 and later, this field supports both standard and custom apps.

Indicates which top-level Apex classes have methods that users assigned to this profile can execute.

Indicates whether the profile is a custom ( true

) or standard ( false

) profile. Available in API version 30.0

and later.

Indicates which custom permissions are available to users assigned to this profile. Available in API version 31.0 and later.

The profile description. Limit: 255 characters. Available in API version 30.0 and later.

Indicates which data sources with identity type of

Per

User

are available to users assigned to this profile.

Available in API version 27.0 and later.

Profile

497

Metadata Types

Field Name

fieldLevelSecurities

Field Type

ProfileFieldLevelSecurity

[] fieldPermissions fullName layoutAssignments loginHours loginIpRanges objectPermissions pageAccesses profileActionOverrides

ProfileFieldLevelSecurity

string

ProfileLayoutAssignments []

ProfileLoginHours

[]

ProfileLoginIpRange

[]

ProfileObjectPermissions

ProfileApexPageAccess

ProfileActionOverride []

[]

[]

[]

Description

Indicates which fields are visible to a user assigned to this profile, and the kind of access available (editable or hidden). This field is available in API version 22.0 and earlier.

Indicates which fields are visible to a user assigned to this profile, and the kind of access available (editable or readable). This field is available in API version 23.0 and later.

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.

Inherited from the Metadata

component, this field is not defined in the WSDL for this component. It must be specified when creating, updating, or deleting. See

create()

to see an example of this field specified for

a call.

Indicates which layout to use for this profile.

Indicates the hours within which a user with this profile may log in. If not specified, the profile doesn’t restrict a user’s login hours.

This field is available in API version 25.0 and later.

The list of IP address ranges from which users with a particular profile can log in.

This field is available in API version 17.0 and later.

Indicates which objects are accessible to a user assigned to this profile, and the kind of access available (create, read, edit, delete, and so on). In API version 28.0 and later, this field is only retrieved when allowRead

is true

.

Indicates which Visualforce pages that users assigned to this profile can execute.

A list of the Lightning Experience Home page action overrides that are assigned to this profile. When a user logs in with a profile, a matching ProfileActionOverride assignment takes precedence over existing overrides for the Home tab specified in

ActionOverride

.

This field is available in API version 37.0 and later.

Profile

498

Metadata Types

Field Name

recordTypeVisibilities

Field Type

ProfileRecordTypeVisibility []

tabVisibilities userLicense userPermissions

ProfileTabVisibility

[] string

ProfileUserPermission

[]

Description

Indicates the visibility of record types for users assigned to this profile. In API version 29.0 and later, this field is not retrieved or deployed for inactive record types.

Indicates which record types are visible to a user assigned to this profile, and therefore which tabs within an app are visible.

The

User License

for the profile. A user license determines the baseline of features that the user can access. Every user must have exactly one user license.

This field is available in API version 17.0 and later.

Specifies a user permission (such as “API Enabled”) and whether it’s enabled for this profile. This field retrieves only enabled user permissions. Available in API version

29.0 and later.

ProfileActionOverride

ProfileActionOverride represents a user profile-based override of an

ActionOverride

on a standard Home tab in Lightning Experience.

Field Name

actionName content

Field Type

string string

Description

Required. The possible values are the same as the actions you can override:

•

accept

•

clone

•

delete

•

edit

•

list

•

new

•

tab

•

view

Set this field if type

is set to flexipage

, scontrol

, or visualforce

. It refers to the name of the Lightning Page, s-control, or Visualforce page to use as the override. To reference installed components, use the format of

Component_namespace__Component_name

.

Profile

499

Metadata Types

Field Name

formFactor pageOrSobjectType recordType type

Field Type

FormFactor

(

enumeration

of type string)

Description

The size of the page being overridden. Only the

Large

value is supported. The other values,

Small

and

Medium

, are reserved for future use.

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

.

string string

ActionOverrideType

(

enumeration

of type string)

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

and custom

.

The record type assigned to the ProfileActionOverride. If the

PageOrSobjectType

is standard-home

, this field is null.

Required. Represents the type of action override. Valid values are described in

ActionOverrideType .

ProfileApplicationVisibility

ProfileApplicationVisibility determines whether an app is visible to a user assigned to this profile.

Field Name

application default visible

Field Type

string boolean boolean

Description

Required. The name of the app.

Required. Indicates whether the app is the default app ( true

) or not

( false

). Only one app per profile can be set to true

.

Required. Indicates whether this app is visible to users assigned to this profile ( true

) or not ( false

).

ProfileApexClassAccess

ProfileApexClassAccess determines which top-level Apex classes have methods that users assigned to this profile can execute.

Field Name

apexClass enabled

Field Type

string boolean

Description

Required. The Apex class name.

Required. Indicates whether users assigned to this profile can execute methods in the top-level class ( true

) or not ( false

).

ProfileCustomPermissions

ProfileCustomPermissions represents the custom permissions access for users assigned to a profile. Only enabled custom permissions are retrieved.

Profile

500

Metadata Types

Field Name

enabled name

Field Type

boolean string

Description

Required. Indicates whether the custom permission is enabled ( true

) or not ( false

).

Required. The custom permission name.

ProfileExternalDataSourceAccess

ProfileExternalDataSourceAccess represents the data source access for users with identity type of

Per User

. Available in API version

27.0 and later.

Field Name

enabled externalDataSource

Field Type

boolean string

Description

Required. Indicates whether the data source is enabled ( true

) or not

( false

).

The name of the external data source.

ProfileFieldLevelSecurity

ProfileFieldLevelSecurity represents the field level security for users assigned to a profile. In API version 30.0 and later, permissions for required fields can’t be retrieved or deployed.

Field Name

editable field hidden readable

Field Type

boolean string boolean boolean

Description

Required. Indicates whether this field is editable ( true

) or not ( false

).

In API version 30.0 and later, when deploying a new custom field, this field is false

by default.

Required. Indicates the name of the field.

Indicates whether this field is hidden ( true

) or not ( false

). This field is available in API version 22.0 and earlier.

For portal profiles, this is set to true

by default in API version 19.0 and later.

Indicates whether this field is readable ( true

) or not ( false

). This field is available in API version 23.0 and later. It replaces the hidden

field.

In API version 30.0 and later, when deploying a new custom field, this field is false

by default.

For portal profiles, this is set to false

by default.

Profile

ProfileLayoutAssignments

ProfileLayoutAssignments determines which layout to use for a profile and a given entity.

501

Metadata Types

Field Name

layout recordType

Field Type

string string

Description

Required. Indicates the layout for this particular entity.

This field is optional. If the recordType

of the record matches a layout assignment rule, it will use the specified layout.

ProfileLoginHours

ProfileLoginHours restricts the days and times within which users with a particular profile can log in.

Field Name

weekdayStart

weekdayEnd

Field Type

string

Description

Specifies the earliest time on that day that a user with this profile may log in. If a start time for a particular day is specified, an end time for that day must be specified as well. Start can’t be greater than end for a particular day.

•

Valid values for weekday

: monday

, tuesday

, wednesday

, thursday

, friday

, saturday

, or sunday

. For example, mondayStart

indicates the beginning of the login period for

Monday.

•

Valid values for Start: the number of minutes since midnight. Must be evenly divisible by 60 (full hours). For example,

300

is 5:00 a.m.

string Specifies the time on that day by which a user with this profile must log out.

•

Valid values for weekday

: monday

, tuesday

, wednesday

, thursday

, friday

, saturday

, or sunday

. For example, mondayEnd

indicates the close of the login period for Monday.

•

Valid values for End: the number of minutes since midnight. Must be evenly divisible by 60 (full hours). For example,

1020

is 5:00 p.m.

Profile

To delete login hour restrictions from a profile that previously had them, you must explicitly include an empty loginHours tag without any start or end times.

ProfileLoginIpRange

ProfileLoginIpRange IP defines an IP address ranges from which users with a particular profile can log in.

Field Name

description endAddress startAddress

Field Type

string string string

Description

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.

Required. The end IP address for the range.

Required. The start IP address for the range.

502

Metadata Types

ProfileObjectPermissions

ProfileObjectPermissions represents a user's access to objects.

Note: In API version 18.0 and later, these permissions are disabled in new custom objects for any profiles in which “View All Data” or “Modify All Data” is disabled.

Field Name

allowCreate

Field Type

boolean allowDelete allowEdit allowRead modifyAllRecords boolean boolean boolean boolean

Description

Indicates whether the object referenced by the object

field can be created by the users assigned to this profile ( true

) or not ( false

).

This field is named revokeCreate

before version 14.0 and the logic is reversed. The field name change and the update from true

to false

and vice versa is automatically handled between versions and does not require any manual editing of existing XML component files.

The field name change and the update from true

to false

and vice versa is automatically handled between versions and does not require any manual editing of existing XML component files.

Indicates whether the object referenced by the object

field can be deleted by the users assigned to this profile ( true

) or not ( false

).

This field is named revokeDelete

before version 14.0 and the logic is reversed. The field name change and the update from true

to false

and vice versa is automatically handled between versions and does not require any manual editing of existing XML component files.

Indicates whether the object referenced by the object

field can be edited by the users assigned to this profile ( true

) or not ( false

).

This field is named revokeEdit

before version 14.0 and the logic is reversed. The field name change and the update from true

to false and vice versa is automatically handled between versions and does not require any manual editing of existing XML component files.

Indicates whether the object referenced by the object

field can be seen by the users assigned to this profile ( true

) or not ( false

).

This field is named revokeRead

before version 14.0 and the logic is reversed. The field name change and the update from true

to false and vice versa is automatically handled between versions and does not require any manual editing of existing XML component files.

Indicates whether the object referenced by the object

field can be read, edited, or deleted by the users assigned to this profile ( true

) or not ( false

), regardless of the sharing settings for the object. This is equivalent to the “Modify All Data” user permission limited to the individual object level. This is a new field in API version 15.0.

Note: This field is not available for all objects. Refer to the profile in the user interface to determine which objects currently support these permissions. Profiles with "Modify All Data" ignore

Profile

503

Metadata Types

Field Name

object viewAllRecords

Field Type

string boolean

Description

modifyAllRecords

entries in Metadata API and don't return an error if "Modify All Data" is enabled on the profile.

Required. The name of the object whose permissions are altered by this profile, for example,

MyCustomObject__c

.

Indicates whether the object referenced by the object

field can be read by the users assigned to this profile ( true

) or not ( false

), regardless of the sharing settings for the object. This includes private records (records with no parent object). This is equivalent to the “View

All Data” user permission limited to the individual object level. This is a new field in API version 15.0.

Note: This field is not available for all objects. Refer to the profile in the user interface to determine which objects currently support these permissions. Profiles with "View All Data" ignore viewAllRecords

entries in the Metadata API and don't return an error if "View All Data" is enabled on the profile.

ProfileApexPageAccess

ProfileApexPageAccess determines which Visualforce pages that users assigned to this profile can execute.

Field Name

apexPage enabled

Field Type

string boolean

Description

Required. The Visualforce page name.

Required. Indicates whether users assigned to this profile can execute the Visualforce page ( true

) or not ( false

).

ProfileRecordTypeVisibility

ProfileRecordTypeVisibility represents the visibility of record types for this profile. Record types let you offer different business processes, picklist values, and page layouts to different users.

Field Name

default personAccountDefault

Field Type

boolean boolean

Description

Required. Indicates whether the record type is the default for this pair of profile and object ( true

) or not ( false

). Only one default is allowed per object.

Indicates whether the record type is the default person account record type for this pair of profile and object ( true

) or not ( false

). Only one person account record type default is allowed per object. This field is only relevant for record types for account or contact objects.

Profile

504

Metadata Types

Field Name

recordType visible

Field Type

string boolean

Description

For more information about person accounts, see “What Is a Person

Account?” in the Salesforce online help. Person accounts are not enabled by default in Salesforce. To request person accounts, contact Salesforce.

Required. The record type name, for example

Account.MyRecordType

.

Required. Indicates whether this record type is visible to users assigned to this profile ( true

) or not ( false

).

ProfileTabVisibility

ProfileTabVisibility represents the visibility of tabs for this profile. For version 17.0 and later, ProfileTabVisibility supports visibility of tabs for standard objects. The manifest file must include the standard object corresponding to a standard tab to retrieve the tab visibility in a profile.

Field Name

tab visibility

Field Type

string

TabVisibility

(

enumeration

of type string)

Description

Required. The name of the tab.

Required. Indicates the visibility of the tab. Valid values are:

•

DefaultOff

—The tab is available on the All Tabs page. Users can individually customize their display to make the tab visible in any app.

•

DefaultOn

—The tab is available on the All Tabs page and appears in the visible tabs for its associated app. Users can individually customize their display to hide the tab or make it visible in other apps.

•

Hidden

—The tab isn’t available on the All Tabs page or visible in any apps.

Note: In version 36.0 and earlier,

Hidden

is returned only if visibility

was set using the API. If it was set to

Hidden from the profile in Salesforce, the API doesn’t return a visibility value. For version 37.0 and later, when tab visibility is set to hidden, the API returns

Hidden

, regardless of how the value was set.

Profile

ProfileUserPermission

ProfileUserPermission represents an app or system permission for a profile. Use one of these elements for each permission.

Field

enabled name

Field Type

boolean string

Description

Required. Indicates whether the permission is enabled ( true

) or disabled ( false

).

Required. The permission name.

505

Metadata Types

Java Sample

The following sample uses picklists, profiles, record types, and a custom app: public void profileSample() { try {

// Create an expense report record, tab and app...

CustomObject expenseRecord = new CustomObject(); expenseRecord.setFullName( "ExpenseReport__c" ); expenseRecord.setLabel( "Expense Report" ); expenseRecord.setPluralLabel( "Expense Reports" ); expenseRecord.setDeploymentStatus(DeploymentStatus.Deployed); expenseRecord.setSharingModel(SharingModel.ReadWrite);

CustomField nameField = new CustomField(); nameField.setType(FieldType.AutoNumber); nameField.setLabel( "Expense Report Number" ); nameField.setDisplayFormat( "ER-{0000}" ); expenseRecord.setNameField(nameField);

AsyncResult[] arsExpenseRecord = metadataConnection.create( new Metadata[] {expenseRecord});

Picklist expenseStatus = new Picklist();

PicklistValue unsubmitted = new PicklistValue(); unsubmitted.setFullName( "Unsubmitted" );

PicklistValue submitted = new PicklistValue(); submitted.setFullName( "Submitted" );

PicklistValue approved = new PicklistValue(); approved.setFullName( "Approved" );

PicklistValue rejected = new PicklistValue(); rejected.setFullName( "Rejected" ); expenseStatus.setPicklistValues( new PicklistValue[] { unsubmitted, submitted, approved, rejected}

);

CustomField expenseStatusField = new CustomField(); expenseStatusField.setFullName(

"ExpenseReport__c.ExpenseStatus__c"

); expenseStatusField.setLabel( "Expense Report Status" ); expenseStatusField.setType(FieldType.Picklist); expenseStatusField.setPicklist(expenseStatus);

AsyncResult[] arsStatusField = metadataConnection.create( new Metadata[]

{expenseStatusField});

CustomTab expenseTab = new CustomTab(); expenseTab.setFullName( "ExpenseReport__c" ); expenseTab.setMotif( "Custom70: Handsaw" ); expenseTab.setCustomObject(true);

AsyncResult[] arsTab = metadataConnection.create( new Metadata[] {expenseTab});

506

Profile

Metadata Types

CustomApplication application = new CustomApplication(); application.setFullName( "ExpenseForce" ); application.setTab( new String[] {expenseTab.getFullName()});

AsyncResult[] arsApp = metadataConnection.create( new Metadata[] {application});

// Employees and managers have the same app visibility...

ProfileApplicationVisibility appVisibility = new ProfileApplicationVisibility(); appVisibility.setApplication( "ExpenseForce" ); appVisibility.setVisible(true);

Profile employee = new Profile(); employee.setFullName( "Employee" ); employee.setApplicationVisibilities( new ProfileApplicationVisibility[] {appVisibility}

);

AsyncResult[] arsProfileEmp = metadataConnection.create( new Metadata[] {employee});

Profile manager = new Profile(); manager.setFullName( "Manager" ); manager.setApplicationVisibilities( new ProfileApplicationVisibility[] {appVisibility}

);

AsyncResult[] arsProfileMgr = metadataConnection.create( new Metadata[] {manager});

// But employees and managers have different access

// to the state of the expense sheet

RecordType edit = new RecordType(); edit.setFullName( "ExpenseReport__c.Edit" );

RecordTypePicklistValue editStatuses = new RecordTypePicklistValue(); editStatuses.setPicklist( "ExpenseStatus__c" ); editStatuses.setValues( new PicklistValue[]

{unsubmitted, submitted}); edit.setPicklistValues( new RecordTypePicklistValue[]

{editStatuses});

AsyncResult[] arsRecTypeEdit = metadataConnection.create( new Metadata[] {edit});

RecordType approve = new RecordType(); approve.setFullName( "ExpenseReport__c.Approve" );

RecordTypePicklistValue approveStatuses = new RecordTypePicklistValue(); approveStatuses.setPicklist( "ExpenseStatus__c" ); approveStatuses.setValues( new PicklistValue[]

{approved, rejected}); approve.setPicklistValues( new RecordTypePicklistValue[]

{approveStatuses});

AsyncResult[] arsRecTypeApp = metadataConnection.create( new Metadata[] {approve});

} catch (ConnectionException ce) {

507

Profile

Metadata Types

}

} ce.printStackTrace();

Declarative Metadata Sample Definition

The following is the definition of a profile in an organization with a custom app, custom object, record type, tab, and user permission:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Profile xmlns= "http://soap.sforce.com/2006/04/metadata">

<applicationVisibilities >

<application >PubApps__Myriad_Publishing </application >

<default >false </default >

<visible >true </visible >

</applicationVisibilities >

<custom >true </custom >

<objectPermissions >

<object >TestWeblinks__c </object >

</objectPermissions >

<recordTypeVisibilities >

<default >true </default >

<recordType >TestWeblinks__c.My First Recordtype </recordType >

<visible >true </visible >

</recordTypeVisibilities >

<tabVisibilities >

<tab >Myriad Publications </tab >

<visibility >DefaultOn </visibility >

</tabVisibilities >

<userPermissions >

<enabled >true </enabled >

<name >APIEnabled </name >

</userpermissions >

</Profile >

Usage

When you use the retrieve()

call to get information about profiles in your organization, the returned

.profile

files only include security settings for the other metadata types referenced in the retrieve request (with the exception of user permissions, IP address ranges, and login hours, which are always retrieved). For example, the package.xml

file below contains a types

element that matches all custom objects, so the returned profiles contain object and field permissions for all custom objects in your organization, but do not include permissions for standard objects, such as Account, and standard fields.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >CustomObject </name >

</types >

<types >

<members >* </members >

<name >Profile </name >

</types >

Profile

508

Metadata Types ProfileActionOverride

<version >39.0

</version >

</Package >

The wildcard “*” on CustomObject does not match standard objects and this helps to avoid making unintended, high-impact profile changes. If you create a few custom objects in a Developer Edition organization,

retrieve()

the information, and subsequently

deploy()

the custom objects to your production organization, the profile and field-level security for all your standard objects, such

as Account, and standard fields are not overwritten unless you explicitly create separate types

elements for the standard objects or fields.

Metadata API intentionally makes it somewhat difficult to include standard fields in retrieve()

calls in order to prevent unexpected

profile changes. However, you can still retrieve and deploy profile permissions for custom and standard fields in standard objects, such as Account.

The next package.xml

file allows you to return profile permissions for Account standard and custom fields. Note how the standard

Account object is defined in a types

element by specifying it as a member of a CustomObject type.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Account </members >

<name >CustomObject </name >

</types >

<types >

<members >* </members >

<name >Profile </name >

</types >

<version >39.0

</version >

</Package >

The final package.xml

file allows you to return profile permissions for the

MyCustomField__c

custom field in the Account object.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Account.MyCustomField__c

</members >

<name >CustomField </name >

</types >

<types >

<members >* </members >

<name >Profile </name >

</types >

<version >39.0

</version >

</Package >

ProfileActionOverride

Represents an override of an ActionOverride by a user profile. You can use it to override an ActionOverride on a standard Home tab or object record page in Lightning Experience. When a user logs in with a profile, a matching ProfileActionOverride assignment takes precedence over existing overrides for the Home tab or record page specified in ActionOverride. You can only access ProfileActionOverride by accessing its encompassing CustomApplication or Profile. Available in API version 39.0 and later.

509

Metadata Types ProfileActionOverride

File Suffix and Directory Location

Profile-based action overrides are defined as part of a custom application or profile.

Version

ProfileActionOverrides are available in API version 39.0 and later.

Fields

Field Name

actionName content formFactor pageOrSobjectType recordType type

Field Type

string

Description

The name of the action. The only valid values are

Tab

.and

View

.

If pageOrSobjectType

is standard-home

, this field must be

Tab

. The

Tab

action is supported only when ProfileActionOverride is being specified as part of a Profile.

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.

string

FormFactor

(

enumeration of

type string) string string

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

The size of the page being overridden. Only the

Large

value is supported. The other values,

Small

and

Medium

, are reserved for future use. The

Large

value represents the Lightning Experience desktop environment.

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

and standard-home

.

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

.

ActionOverrideType

(

enumeration of

type string)

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

.

Declarative Metadata Sample Definition

You can define a ProfileActionOverride like this.

<CustomApplication xmlns= "http://soap.sforce.com/2006/04/metadata">

<profileActionOverrides >

<actionName >View </actionName >

<content >CustomObjectFlexiPage </content >

<formFactor >Large </formFactor >

<pageOrSobjectType >TestObj__c </pageOrSobjectType >

510

Metadata Types

<type >Flexipage </type >

<profile >standard </profile >

<recordType >TestObj__c.TestRecordType

</recordType >

</profileActionOverrides >

<defaultLandingTab >standard-home </defaultLandingTab >

<formFactors >Large </formFactors >

<label >My Custom App </label >

<tab >standard-Account </tab >

<tab >standard-Opportunity </tab >

<uiType >Lightning </uiType >

<navType >Standard </navType >

</CustomApplication >

Here is an example package.xml

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >MyCustomApp </members >

<name >CustomApplication </name >

</types >

<version >39.0

</version >

</Package >

Queue

Represents a holding area for items before they are processed.

Declarative Metadata File Suffix and Directory Location

The file suffix for queue components is

.queue

and components are stored in the queues

directory of the corresponding package directory. This component supports cases, leads, service contracts (if Entitlements are enabled), and custom objects.

Version

Queue components are available in API version 24.0 and later.

Fields

This metadata type represents the valid values that define a queue:

Field Name Field Type

doesSendEmailToMembers boolean email fullName string string

Description

Indicates whether emails are sent to queue members ( true

) or not

( false

) when a new record is added to the queue.

The email address of the queue owner.

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

Queue

511

Metadata Types QuickAction

Field Name

name queueSobject

Field Type

string

QueueSobject[]

Description

two consecutive underscores. This field is inherited from the Metadata

component. Corresponds to Queue Name in the user interface.

Required. The name of the queue. Corresponds to Label in the user interface.

Indicates the supported entity types.

QueueSobject

QueueSobject represents an entity type that the queue supports.

Field Name

sobjectType

Field Type

string

Description

Valid values are:

•

Case

•

Lead

•

ServiceContract

•

Custom objects (e.g.

ObjA_c

)

Declarative Metadata Sample Definition

The following is the definition of a queue, which supports Case, Lead, and a custom object named ObjA.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Queue xmlns= "http://soap.sforce.com/2006/04/metadata">

<doesSendEmailToMembers >true </doesSendEmailToMembers >

<email >[email protected]

</email >

<fullName >Your Name </fullName >

<name >memberQueue </name >

<queueSobject >

<sobjectType >Case </sobjectType >

</queueSobject >

<queueSobject >

<sobjectType >Lead </sobjectType >

</queueSobject >

<queueSobject >

<sobjectType >ObjA_c </sobjectType >

</queueSobject >

</Queue >

QuickAction

Represents a specified create or update quick action for an object that then becomes available in the Chatter publisher. For example, you can create an action that, on the detail page of an account, allows a user to create a contact related to that account from the Chatter feed on that page. QuickAction can be created on objects that allow custom fields. The parent objects supported include:

512

Metadata Types QuickAction

•

Account

•

Campaign

•

Case

•

Contact

•

Custom objects

•

Group

•

Lead

•

Opportunity

File Suffix and Directory Location

QuickAction components have the suffix quickAction

and are stored in the quickActions

folder.

Version

QuickAction components are available in API version 28.0 and later.

Fields

Field Name

canvas description fieldOverrides height icon isProtected label

Field Type

string string

FieldOverride on

page 515[] int

Description

If the custom action invokes a canvas app, the app name. Returns the fully qualified name of the canvas app in the format

<namespace>__<dev_name>

, if the quick action type is

Canvas

; otherwise, returns null

.

This field is available in API version 29.0 and later.

The description of the action.

The specific field that may be overridden within a QuickAction.

string boolean string

If a custom action is created, this field represents the height in pixels of the action pane.

The icon used to identify the action.

API version 32.0 and later returns different icons than in earlier API versions.

Indicates whether this component is protected ( true

) or not ( false

).

Protected components cannot be linked to or referenced by components created in the installing organization.

Identifies the action and displays to users. This is also the default identifier used for the API and managed packages.

513

Metadata Types QuickAction

Field Name

lightningComponent optionsCreateFeedItem page quickActionLayout standardLabel successMessage targetObject targetParentField

Field Type

string boolean

Description

If the custom action invokes a Lightning component, this field represents the fully qualified name of the component. Otherwise, this field is null

.

Available in API version 38.0 and later.

Required. Indicates whether successful completion of the action creates a feed item ( true

) or not ( false

). Applies only to Create Record,

Update Record, and Log a Call quick action types.

Available in API version 36.0 and later.

string If the custom action invokes a Visualforce page, this field identifies the page.

QuickActionLayout

The layout of fields on the action.

QuickActionLabel

(

enumeration of

type string)

Specifies the standard label to use for the action. The valid values are:

•

LogACall

•

LogANote

•

New

(A new record)

•

NewRecordType

(For example, a label with something like “New

Idea”)

•

Update

•

UpdateRecordType

•

NewChild

(A new child record)

•

NewChildRecordType

•

CreateNew

•

CreateNewRecordType

(For example, a label with something like “Create New Idea”)

•

SendEmail

(This value is available in API version 31.0 and later.)

•

QuickRecordType

•

Quick

(A quick record) string string string

The message that displays to the user upon successful completion of the action.

Available in API version 36.0 and later.

The object for which the action is created and performed.

For example, you can create an action that, on the detail page of an account, allows a user to create a contact related to that account from the Chatter feed on that page. In this case, Contact is the targetObject

.

The parent object type of the action. Links the target object to the parent object. For example, use Account if the target object is Contact and the parent object is Account.

514

Metadata Types QuickAction

Field Name

targetRecordType type width

Field Type

string

QuickActionType

(

enumeration of

type string) int

Description

Specifies which record type to create. Valid values are:

•

Business Account

•

Person Account

•

Master

Required. The type of quick action. Valid values are:

•

Canvas

•

Create

•

LightningComponent

(This value is available in API version

38.0 and later.)

•

LogACall

•

Post

•

SendEmail

(This value is available in API version 31.0 and later.)

•

SocialPost

•

Update

•

VisualforcePage

If a custom action is created, this field represents the width in pixels of the action pane.

FieldOverride

Represents the field names and their respective formulas and literal values that comprise overrides in a QuickAction.

Field Name

field formula literalValue

Field Type

string string string

Description

The name of the specific field to allow overrides on.

Specifies the formula to use when overriding a field.

The value of the field without overrides.

QuickActionLayout

The layout of fields on the action. There is no hard limit to the number of fields you can add to an action layout. However, for optimum usability, we recommend a maximum of eight fields. Adding more than 20 fields can severely affect user efficiency.

Field Name

layoutSectionStyle

Field Type

LayoutSectionStyle

(

enumeration

of type string)

Description

The type of layout structure used. The valid values are:

•

TwoColumnsTopToBottom

•

TwoColumnsLeftToRight

•

OneColumn

515

Metadata Types QuickAction

Field Name Field Type Description

•

CustomLinks quickActionLayoutColumns

QuickActionLayoutColumn[] Specifies columns in a QuickActionLayout.

QuickActionLayoutColumn

A column defined for a QuickActionLayout.

Field Name Field Type Description

quickActionLayoutItems

QuickActionLayoutItem

[]

Specifies row items in a QuickActionLayoutColumn.

QuickActionLayoutItem

A row item comprised of fields and defined for a QuickActionLayoutColumn.

Field Name

emptySpace field uiBehavior

Field Type

boolean string

UiBehavior

(

enumeration

of type string)

Description

Controls if this layout item is a blank space ( true

) or not ( false

).

Represents a specific field in QuickActionLayoutItem. There is no hard limit to the number of fields you can add to an action layout. However, for optimum usability, we recommend a maximum of eight fields. Adding more than 20 fields can severely affect user efficiency.

Specifies user input behavior for specific fields in QuickActionLayoutItem.

The valid values are:

•

Edit

•

Required

•

Readonly

Declarative Metadata Sample Definition

The following is an example of a QuickAction component:

<?xml

version= "1.0" encoding= "UTF-8"?>

<QuickAction xmlns= "http://soap.sforce.com/2006/04/metadata">

<description >testActionDefinitionTypesCreateTask </description >

<label >testActionDefinitionTypesCreateTask </label >

<optionsCreateFeedItem >true </optionsCreateFeedItem >

<quickActionLayout >

<layoutSectionStyle >TwoColumnsLeftToRight </layoutSectionStyle >

<quickActionLayoutColumns >

<quickActionLayoutItems >

516

Metadata Types RemoteSiteSetting

<emptySpace >false </emptySpace >

<field >OwnerId </field >

<uiBehavior >Required </uiBehavior >

</quickActionLayoutItems >

<quickActionLayoutItems >

<emptySpace >false </emptySpace >

<field >WhoId </field >

<uiBehavior >Edit </uiBehavior >

</quickActionLayoutItems >

<quickActionLayoutItems >

<emptySpace >false </emptySpace >

<field >WhatId </field >

<uiBehavior >Edit </uiBehavior >

</quickActionLayoutItems >

<quickActionLayoutItems >

<emptySpace >false </emptySpace >

<field >ActivityDate </field >

<uiBehavior >Edit </uiBehavior >

</quickActionLayoutItems >

<quickActionLayoutItems >

<emptySpace >false </emptySpace >

<field >Subject </field >

<uiBehavior >Edit </uiBehavior >

</quickActionLayoutItems >

<quickActionLayoutItems >

<emptySpace >false </emptySpace >

<field >Status </field >

<uiBehavior >Required </uiBehavior >

</quickActionLayoutItems >

<quickActionLayoutItems >

<emptySpace >false </emptySpace >

<field >Priority </field >

<uiBehavior >Required </uiBehavior >

</quickActionLayoutItems >

</quickActionLayoutColumns >

<quickActionLayoutColumns/ >

</quickActionLayout >

<successMessage >This is a success message </successMessage >

<targetObject >Task </targetObject >

<targetParentField >What </targetParentField >

<type >Create </type >

</QuickAction >

RemoteSiteSetting

Represents a remote site setting. Before any Visualforce page, Apex callout, or JavaScript code using XmlHttpRequest in an s-control or custom button can call an external site, that site must be registered in the Remote Site Settings page, or the call fails. RemoteSiteSetting extends the

Metadata metadata type and inherits its

fullName

field.

517

Metadata Types RemoteSiteSetting

Declarative Metadata File Suffix and Directory Location

RemoteSiteSetting components are stored in the remoteSiteSettings

directory of the corresponding package directory. The file name matches the unique name of the remote site setting, and the extension is

.remoteSite

.

Version

RemoteSiteSetting components are available in API version 19.0 and later.

Fields

Field

description

Field Type

string disableProtocolSecurity boolean fullName isActive url string boolean string

Description

The description explaining what this remote site setting is used for.

Required. Indicates whether code within Salesforce can access the remote site regardless of whether the user's connection is over HTTP or HTTPS ( true

) or not ( false

). When true

, code within Salesforce can pass data from an HTTPS session to an

HTTP session, and vice versa.

Warning: Only set to true

if you understand the security implications.

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.

Inherited from the

Metadata component, this field is not defined

in the WSDL for this component. It must be specified when

creating, updating, or deleting. See create()

to see an

example of this field specified for a call.

Required. Indicates if the remote site setting is active ( true

) or not ( false

).

Required. The URL for the remote site.

Declarative Metadata Sample Definition

A sample XML definition of a remote site setting is shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<RemoteSiteSetting xmlns= "http://soap.sforce.com/2006/04/metadata">

<description >Used for Apex callout to mapping web service </description >

<disableProtocolSecurity >false </disableProtocolSecurity >

<isActive >true </isActive >

518

Metadata Types

<url >https://www.maptestsite.net/mapping1 </url >

</RemoteSiteSetting >

Report

Represents a custom report. This type extends the

Metadata metadata type and inherits its

fullName

field. This metadata type only supports custom reports; standard reports are not supported.

Declarative Metadata File Suffix and Directory Location

Reports are stored in the reports

directory of the corresponding package directory. The file name matches the report title and the extension is

.report

.

Retrieving Reports

You can’t use the wildcard (*) symbol with reports in package.xml

. To retrieve the list of reports for populating package.xml

with explicit names, call listMetadata()

and pass in

ReportFolder

as the type. Note that ReportFolder is not returned as a type in describeMetadata()

. Report is returned from describeMetadata()

with an associated attribute of inFolder set to true. If that attribute is set to true, you can construct the type by using the component name with the word Folder, such as

ReportFolder.

The following example shows folders in package.xml

:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >MyDBFolder/MyDBName </members >

<name >Dashboard </name >

</types >

<types >

<members >MyDocumentFolder/MyDocumentName </members >

<name >Document </name >

</types >

<types >

<members >unfiled$public/MarketingProductInquiryResponse </members >

<members >unfiled$public/SalesNewCustomerEmail </members >

<name >EmailTemplate </name >

</types >

<types >

<members >MyReportFolder/MyReportName </members >

<name >Report </name >

</types >

<version >39.0

</version >

</Package >

Version

Report components are available in API version 14.0 and later.

Report

519

Metadata Types

Fields

The following information assumes that you are familiar with creating and running reports. For more information on these fields, see

“Create a Report” in the Salesforce online help.

Field

aggregates block blockInfo buckets chart colorRanges columns crossFilters currency description division

Field Type

ReportAggregate

Report

ReportBlockInfo

ReportBucketField

ReportChart

string string

[]

[]

ReportColorRange

ReportColumn

[]

ReportCrossFilter []

[]

[]

CurrencyIsoCode

( enumeration

of type string)

Description

List that defines custom summary formulas for summary, matrix, and joined reports.

Represents each block in a joined report where every block can be of a different report type.

Defines attributes for each block in a joined report.

Defines a bucket field to be used in the report.

This field is available in API version 24.0 and later.

.

Defines a chart for summary and matrix reports

List that specifies conditional highlighting for report summary data.

List that specifies the fields displayed in the report. Fields appear in the report in the same order as they appear in the Metadata API file.

Defines a cross filter's object, related object, and condition (WITH or WITHOUT). This field is available in API version 39.0 and later.

When using multiple currencies, some reports allow you to display converted amounts by selecting the appropriate column to display. For example, in opportunity reports, you can include the Amount (converted) column on the report.

This field is an enumeration of type string that defines the currency in which to display converted amounts. Valid values: Must be one of the valid alphabetic, three-letter currency ISO codes defined by the ISO 4217 standard, such as

USD

,

GBP

, or

JPY

.

Specifies a general description, which is displayed with the report name. Maximum characters: 255 characters.

If your organization uses divisions to segment data and you have the “Affected by Divisions” permission, records in the report must match this division.

This field is available in API version 17.0 and later.

Report

520

Metadata Types

Field

filter folderName format fullName groupingsAcross groupingsDown

Field Type

ReportFilter

string

ReportFormat

(

enumeration

of type string) string

ReportGrouping

ReportGrouping

[]

[]

Description

Limits report results to records with specific data.

For example, you can limit report results to opportunities for which the amount is greater than $1,000:

<filter >

<criteriaItems >

<column >AMOUNT </column >

<operator >greaterThan </operator >

<value >1000 </value >

</criteriaItems >

</filter >

For more information, see “Enter Filter Criteria” in the Salesforce online help.

Name of the folder that houses the report.

This field is available in API version 35.0 and later.

Defines the report format. For example,

Tabular

for a simple data list without subtotals.

The report unique developer name used as an 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.

List that defines the fields by which you want to group and subtotal data across a matrix report

(row headings). When grouping by a date field, you can further group the data by a specific time period such as days, weeks, or months.

Maximum: 2 fields.

For Summary and Matrix reports: List that defines the fields by which you want to group and subtotal. For summary reports, choosing more than one sort field allows you to subsort your data. For matrix reports, specifies summary fields for column headings. When grouping by a date field, you can further group the data by a specific time period such as days, weeks, or months.

Report

521

Metadata Types

Field Field Type

historicalSelector

ReportHistoricalSelector

name numSubscriptions string int params

ReportParam

[] reportType string roleHierarchyFilter string rowLimit scope int string

Description

Maximum for matrix reports: 2. Maximum for summary reports: 3

Defines a date range for which historical trend reporting data is to be captured. Default is “Any

Historical Date.”

Available in API version 29.0 and later.

Required. The report name. For example,

Opportunity Pipeline

Indicates whether a user has subscribed to this report Lightning Experience (1) or not (0). Tied to user context.

This field is available in API version 38.0 and later.

List that specifies settings specific to each report type, in particular options that let you filter a report to obtain useful subsets. For example, the

Activities report type lets you specify whether you want to see open or closed activities or both and whether you want to see tasks or events or both. Valid values depend on the report type.

Required. Defines the type of data in the report.

For example,

Opportunity

to create a report of opportunities data.

The role name for a report drill down. Some reports, such as opportunity and activity reports, display Hierarchy links that allow you to drill down to different data sets based on the role hierarchy.

This field is available in API version 17.0 and later.

Defines the maximum number of rows that can be returned for the report.

Defines the scope of data on which you run the report. For example, whether you want to run the report against all opportunities, opportunities you own, or opportunities your team owns. Valid values depend on the

reportType

. For example, for Accounts reports:

•

MyAccounts

•

MyTeamsAccounts

•

AllAccounts

Report

522

Metadata Types

Field

showCurrentDate showDetails sortColumn timeFrameFilter userFilter

Field Type

boolean boolean string sortOrder

SortOrder

(

enumeration of type string)

territoryHierarchyFilter string

ReportTimeFrameFilter

string

Description

Can be set to true

for historical trending reports in matrix format.

Available in API version 29.0 and later.

false

shows a collapsed view of the report with only the headings, subtotals, and total.

Default: true

Specifies the field on which to sort data in the report. Use

sortOrder

to specify the sort

order.

Specifies the sort order. Use

sortColumn

to specify the field on which to sort.

The territory name for a report drill down. If your organization uses territory management, some reports display Hierarchy links that allow you to drill down to different data sets based on the territory hierarchy.

This field is available in API version 17.0 and later.

Limits report results to records within a specified time frame.

The user name for a report drill down. Some reports, such as opportunity and activity reports, display Hierarchy links that allow you to drill down to different data sets based on the user hierarchy.

This field is available in API version 17.0 and later.

ReportAggregate

ReportAggregate defines custom summary formulas on summary, matrix, and joined reports. For more information on these fields, see

“Build a Custom Summary Formula” in the Salesforce online help.

Field

acrossGroupingContext

Field Type

string calculatedFormula datatype string

ReportAggregateDatatype

( enumeration

of type string)

Description

Defines the row grouping level at which you want your custom summary formula to be displayed. This is a new field in API version 15.0.

Required. The custom summary formula. For example,

AMOUNT:SUM + OPP_QUANTITY:SUM

Required. Specifies the data type for formatting and display of the custom summary formula results.

Report

523

Metadata Types

Field

description developerName isActive isCrossBlock masterLabel reportType scale

Field Type

string string downGroupingContext string booleanblo boolean string string int

Description

The custom summary formula description. Maximum: 255 characters.

Required. The internal development name of the custom summary formula, for example,

FORMULA1

. This is used to reference custom summary formulas from other report components, including conditional highlighting.

Defines the column grouping level at which you want your custom summary formula to be displayed. This field is available in API version 15.0 and later.

Required. true

displays the formula result in the report.

false

does not display the result in the report.

Determines whether the custom summary formula is a cross-block formula, which is available with joined reports.

true

indicates a cross-block custom summary formula.

false

indicates a standard custom summary formula.

This field is available in API version 25.0 and later.

Required. The custom summary formula label (name).

Required for joined reports. Specifies the

reportType

of the

blocks to which the aggregate

can be added.

The formula result is calculated to the specified number of decimal places. Valid values

0

through

18

.

ReportBlockInfo

ReportBlockInfo defines blocks in a joined report.

Field

aggregateReferences blockId joinTable

Field Type

ReportAggregateReference []

string string

Description

Lists the aggregates

that represent the custom summary formulas used in a joined report block.

Required. blockId

is used in cross-block custom summary formulas and joined report charts to identify the block containing each summary field. blockId

is assigned automatically. Valid values are B1 through B5.

This field is available in API version 25.0 and later.

Required. Refers to the entity used to join blocks in a joined report. The entity provides a list of fields that are available for globally grouping across the blocks.

Report

524

Metadata Types

ReportAggregateReference

ReportAggregateReference defines the developer name used for custom summary formulas in joined reports.

Field

aggregate

Field Type

string

Description

Required. The developerName

of the ReportAggregate, which specifies the custom summary formula used in a block of a joined report.

Report

ReportBucketField

ReportBucketField defines a bucket to be used in the report.

Field

bucketType developerName masterLabel nullTreatment otherBucketLabel sourceColumnName values

Field Type

ReportBucketFieldType

( enumeration

of type string)

Description

Required. Specifies the type of bucket. Valid values:

•

text

•

number

•

picklist string string

Required. A unique name used as the

<field >

value to display a bucket field in the column list and other report components, including sort, filter, list, group, and chart. Must be of the format

BucketField_

name

. For example,

BucketField_BusinessSize

.

Required. The bucket field label. Maximum 40 characters. Any line breaks, tabs, or multiple spaces at the beginning or end of the label are removed. Any of these characters within the label are reduced to a single space.

ReportBucketFieldNullTreatment

( enumeration

of type string)

For numeric bucket fields only. Specifies whether empty values are treated as zeros ( z

) or not ( n

).

string string

ReportBucketFieldValue

( enumeration

of type string)

The label of the container for unbucketed values.

Required. The source field that the bucket is applied to. For example,

SALES

or

INDUSTRY

.

Defines one bucket value used in the bucket field.

Note: While this name is plural, it represents a single bucket. In typical use, a bucket field contains multiple buckets.

ReportBucketFieldValue

ReportBucketFieldValue defines a bucket value used in the bucket field.

525

Metadata Types

Field

sourceValues value

Field Type Description

ReportBucketFieldSourceValue

( enumeration

of type string)

The value of a bucket in the bucket field. Valid values:

•

sourceValue

—Used for picklist and text bucket fields.

For picklists, describes the picklist item in the bucket. For example, the sourceValue of a bucket on

TYPE

could be

Customer

. For text, the full string for the item in the bucket. For example, the sourceValue of a bucket on

ADDRESS_STATE1

could be

NY

.

•

from

—Used only on numeric bucket fields. A non-inclusive lower bound for a numeric bucket range. This value must be a number.

•

to

—Used only on numeric bucket fields. The inclusive upper bound for a numeric bucket range. This value must be a number.

In numeric buckets, the first value must only have to

and last value must only have from

. All other values must have both to

and from

.

string Required. The name of a specific bucket value within the bucket field.

ReportGrouping

ReportGrouping defines how to group, subtotal, and sort data for summary, matrix, and joined reports.

Field

aggregateType dateGranularity field sortByName sortOrder

Field Type Description

ReportAggrType (

enumeration

of type string)

The type of aggregate value to sort by. Valid values are:

•

Sum

•

Average

•

Maximum

•

Minimum

•

RowCount

UserDateGranularity

( enumeration

of type string) string string

SortOrder

When grouping by a date field, the time period by which to group.

Required. The field by which you want to summarize data. For example,

CAMPAIGN_SOURCE

The API name of the column, aggregate or custom summary field used to order the grouping.

Required. Whether to sort data in ascending or descending alphabetical and numerical order.

Report

526

Metadata Types

Field

sortType

Field Type

ReportSortType (

enumeration

of type string)

Description

Indicates if the grouping is sorted by a column, aggregate or custom summary field. Valid values are:

•

Column

•

Aggregate

•

CustomSummaryFormula

ReportHistoricalSelector

ReportHistoricalSelector defines a date range for historical data.

Field

snapshot

Field Type

string

Description

Represents the date value to apply a historical filter, either relative (in the format

N_DAYS_AGO:2

) or absolute (in the format yyyy-MM-dd

). If unspecified, it’s assumed that the filter will be applied to all the columns the user sees.

Available in API version 29.0 and later.

SortOrder

An enumeration of type string that defines the order in which data is sorted in the report fields. Valid values:

Field

Asc

Desc

Description

Sorts data in ascending alphabetical and numerical order.

Sorts data in descending alphabetical and numerical order.

UserDateGranularity

An enumeration of type string that defines the time period by which to group data. Valid values:

Enumeration Value

None

Day

Week

Month

Quarter

Year

Description

No grouping by date

By day

By week

By month

By quarter

By year

Report

527

Metadata Types

Enumeration Value

FiscalQuarter

FiscalYear

MonthInYear

DayInMonth

FiscalPeriod

FiscalWeek

Description

By fiscal quarter. You can set the fiscal year for your organization. See “Set the Fiscal Year” in the

Salesforce online help.

By fiscal year

By calendar month in year

By calendar day in month

When custom fiscal years are enabled: By fiscal period

When custom fiscal years are enabled: By fiscal week

ReportSummaryType

An enumeration of type string that defines how report fields are summarized. Valid values:

Enumeration Value

Sum

Average

Maximum

Minimum

None

Description

Total

Average

Largest value

Smallest value

The field is not summarized.

ReportColorRange

ReportColorRange defines conditional highlighting for report summary data.

Field

aggregate columnName highBreakpoint highColor lowBreakpoint

Field Type

ReportSummaryType

( enumeration

of type string) string double string double

Description

Required. Defines how the field specified in columnName

is summarized. For example,

Sum

.

Required. Specifies the field whose value ranges are represented by colors.

Required. Specifies the number that separates the mid color from the high color.

Required. Specifies the color (in HTML format) to represent data that falls into the high number range. This color spans from the highBreakpoint

value.

Required. Specifies the number that separates the low color from the mid color.

Report

528

Metadata Types

Field

lowColor midColor

Field Type

string string

Description

Required. Specifies a color (in HTML format) to represent data that falls into the low value range, below the lowBreakpoint

value.

Required. Specifies a color (in HTML format) to represent data that falls into the mid value range.

ReportColumn

ReportColumn defines how fields (columns) are displayed in the report.

Field

aggregateTypes field

Field Type

ReportSummaryType []

( enumeration

of type string) string

Description

List that defines if and how each report field is summarized.

reverseColors showChanges boolean boolean

Required. The field name. For example,

AGE

or

OPPORTUNITY_NAME

In historical trend reports, displays greater Date values as green and greater Amount values as red, reversing the default colors.

Available in API version 29.0 and later.

In historical trend reports, adds a column displaying the difference between current and historical Date and Amount values.

Available in API version 29.0 and later.

Report

ReportFilter

ReportFilter limits the report results by filtering data on specified fields.

Field

booleanFilter

Field Type

string criteriaItems

ReportFilterItem

Description

Specifies filter logic conditions. For more information on filter logic, see “Getting the Most Out of Filter Logic” in the Salesforce online help.

The criteria by which you want to filter report data, either by comparing historical values or by applying a date range.

<criteriaItems > criteriaItems ReportFilterItem

<column >Opportunity.Opportunity__hd$Amount__hst </column >

<columnToColumn >false </columnToColumn >

529

Metadata Types

Field

language

Field Type Description

<operator >equals </operator >

<snapshot >N_DAYS_AGO:90 </snapshot >

<value >100 </value >

</criteriaItems >

Language

(

enumeration of type

string)

The language used when a report filters against a picklist value using the operators contains

or startsWith

. For a list of valid language values, see

Language .

ReportFilterItem

ReportFilterItem limits the report results by filtering data on specified fields.

Field

column columnToColumn isUnlocked operator snapshot value

Field Type

string boolean

Description

Required. The field on which you want to filter data. For example,

AMOUNT

Indicates that the field contains data from a historical snapshot.

Available in API version 29.0 and later.

boolean Optional. Indicates whether the report filter is unlocked ( true

) or locked ( false

). You can edit unlocked filters on the report run page in Lightning Experience. If unspecified, the default value is false

.

Available in API version 38.0 and later.

FilterOperation

( enumeration

of type string)

Required. An enumeration of type string that defines the operator used to filter the data, for example, greaterThan

.

For valid values, see

FilterOperation .

string Represents the date value, either relative (in the format

N_DAYS_AGO:2

) or absolute (in the format yyyy-MM-dd

).

Available in API version 29.0 and later.

string The value by which you want to filter the data, for example,

1000

. Note that the Metadata API filter condition values do not always match those that you enter in the report wizard. For example, in the Metadata API dates are always converted to the

US date format and values entered in a non-US English language may be converted to a standard US English equivalent.

ReportFormat

An enumeration of type string that defines the report format. Valid values:

Report

530

Metadata Types

Enumeration Value

Matrix

Summary

Tabular

Joined

Description

Summarizes data in a grid. Use to compare related totals.

Lists, sorts, and subtotals data.

Lists data with no sorting or subtotals.

Joins data from different report types storing each report’s data in its own block.

ReportParam

ReportParam represents settings specific to a report type, especially options that let you filter a report to certain useful subsets.

Field

name value

Field Type

string string

Description

Required. Specifies a specific

reportType

setting.

Required. The setting value.

Report

ReportAggregateDatatype

An enumeration of type string that specifies the data type for formatting and display of custom summary formula results. Valid values:

Enumeration Value

currency number percent

ReportChart

ReportChart represents charts on summary, matrix, and joined reports.

Field

backgroundColor1

Field Type

string backgroundColor2 backgroundFadeDir string

ChartBackgroundDirection

( enumeration

of type string)

Description

Specifies the beginning color (in HTML format) for a gradient color background.

Specifies the end color (in HTML format) for a gradient color background.

Specifies the direction for a gradient color background. Use with

backgroundColor1

to specify the beginning color and backgroundColor2

to specify the end color for the gradient

design. Use white for both if you do not want a background design. Valid values:

•

diagonal

531

Metadata Types

Field

chartSummaries chartType enableHoverLabels expandOthers groupingColumn legendPosition

Field Type Description

•

leftToRight

•

topToBottom

(

ChartSummary

[]

ChartType

(

enumeration

of type string)

Required. Specifies the chart type. Available chart types depend on the

report type .

boolean

Specifies the summaries you want to use for the chart. Invalid summaries are ignored without notification. If there are no valid summaries, RowCount is used by default for the axis value. This field is available in API version 17.0 and later.

boolean

Specifies whether to display values, labels, and percentages when hovering over charts. Hover details depend on chart type.

Percentages apply to pie, donut, and funnel charts only. This field is available in API version 17.0 and later.

Specifies whether to combine all groups less than or equal to

3% of the total into a single 'Others' wedge or segment. This only applies to pie, donut, and funnel charts. Set to true

to show all values individually on the chart; set to false

to combine small groups into 'Others.' This field is available in API version 17.0 and later.

string

ChartLegendPosition

enumeration

of type string)

Specifies the field by which to group data. This data is displayed on the X-axis for vertical column charts and on the Y-axis for horizontal bar charts.

Required.

The location of the legend with respect to the chart. The valid values are:

•

Bottom

•

OnChart

•

Right location

ChartPosition

(

enumeration

of type string)

Required. Specifies whether the chart is displayed at the top or bottom of the report.

secondaryGroupingColumn string showAxisLabels boolean

For grouped chart types: Specifies the field by which to group the data.

For bar and line charts: Specifies whether the chart displays names for each axis.

showPercentage showTotal boolean boolean

Indicates if percentages are displayed for wedges and segments of pie, donut, and funnel charts, as well as for gauges ( true

), or not ( false

).

Indicates if the total is displayed for donut charts and gauges

( true

), or not ( false

).

Report

532

Metadata Types

Field

showValues size summaryAggregate

Field Type

boolean

Description

Indicates if the values of individual records or groups are displayed for charts ( true

), or not ( false

).

ReportChartSize

(

enumeration

of type string)

Required. Specifies the chart size.

ReportSummaryType

( enumeration

of type string)

Defines how to summarize the chart data. For example,

Sum

.

No longer supported in version API 17.0 and later. See

chartSummaries

.

summaryAxisManualRangeEnd summaryAxisManualRangeStart summaryAxisRange summaryColumn textColor textSize double double

When specifying the axis range manually: Defines the ending value.

When specifying the axis range manually: Defines the starting value.

ChartRangeType

(

enumeration

of type string)

Required. For bar, line, and column charts: Defines whether to specify the axis range manually or automatically.

string string int

Required. Specifies the field by which to summarize the chart data. Typically this field is displayed on the Y-axis. No longer supported in version API 17.0 and later. See

chartSummaries

.

The color (in HTML format) of the chart text and labels.

The size of the chart text and labels. Valid values:

•

8

•

9

•

10

•

12

•

14

•

18

•

24

•

36

The maximum size is 18. Larger values are shown at 18 points.

title titleColor titleSize string string int

The chart title. Max 255 characters.

The color (in HTML format) of the title text.

The size of the title text. Valid values:

•

8

•

9

•

10

•

12

•

14

•

18

533

Report

Metadata Types

Field Field Type Description

•

24

•

36

The maximum size is 18. Larger values are shown at 18 points.

ChartType

An enumeration of type string that defines the chart type. For information on each of these chart types, see “Chart Types” in the Salesforce online help. Valid values:

Enumeration Value

None

HorizontalBar

HorizontalBarGrouped

HorizontalBarStacked

HorizontalBarStackedTo100

VerticalColumn

VerticalColumnGrouped

VerticalColumnStacked

VerticalColumnStackedTo100

Line

LineGrouped

LineCumulative

LineCumulativeGrouped

Pie

Donut

Funnel

Scatter

ScatterGrouped

VerticalColumnLine

VerticalColumnGroupedLine

VerticalColumnStackedLine

Plugin

Report

534

Metadata Types

Enumeration Value

Reserved for future use. This value is available in API version 31.0 and later.

ChartPosition

An enumeration of type string that specifies the position of the chart in the report. Valid values:

Enumeration Value

CHART_TOP

CHART_BOTTOM

ChartSummary

ChartSummary defines how data in the chart is summarized. Valid values:

Field

aggregate axisBinding column

Field Type

ReportSummaryType

ChartAxis

string

Description

Specifies the aggregation method—such as

Sum

,

Average

,

Min

, and

Max

—for the summary value. Use the

column

field

to specify the summary value to use for the aggregation. You don't need to specify this field for RowCount or custom summary formulas.

Specifies the axis or axes to use on the chart. Use the

column

field to specify the summary value to use for the axis.

Required. Specifies the summary field for the chart data. If all columns are invalid, RowCount is used by default for the axis value. For vertical column and horizontal bar combination charts, you can specify up to four values.

ChartAxis

An enumeration of type string that specifies the axis or axes to be used in charts. Valid values:

Enumeration Value

x y y2

Description

The summary value to use for the X-axis of a scatter chart.

The Y-axis for the chart.

The secondary Y-axis for vertical column combination charts with a line added.

ReportChartSize

An enumeration of type string that specifies the chart size. Valid values:

535

Report

Metadata Types

Enumeration Value

Tiny

Small

Medium

Large

Huge

ChartRangeType

An enumeration of type string that defines the report format. Valid values:

Enumeration Value

Auto

Manual

ReportTimeFrameFilter

ReportTimeFrameFilter represents the report time period.

Field

dateColumn endDate interval startDate

Field Type

string

Description

Required. The date field on which to filter data. For example,

CLOSE_DATE date

UserDateInterval

(

enumeration

of type string)

Required. Specifies the period of time.

date

When

interval

is

INTERVAL_CUSTOM

, specifies the end

of the custom time period.

When interval

is

INTERVAL_CUSTOM

, specifies the start of the custom time period.

ReportCrossFilter

ReportCrossFilter represents the cross filter functionality in reports.

Field

criteriaItems

Field Type

ReportFilterItem

Description

Represents the subfilters of a cross filter. There can be up to five subfilters. This field requires the following attributes.

•

Column

•

Operator

Report

536

Metadata Types

Field Field Type

operation primaryTableColumn relatedTable

ObjectFilterOperator.

Enumeration of type string string string relatedTableJoinColumn string

Description

•

Value

The action indicating whether to include or exclude an object.

Valid values: with

and without

.

The parent object used for the cross filter.

The child object used for the cross filter.

The field from the child object that is used to join the parent.

Declarative Metadata Sample Definition

A sample XML snippet using cross filters to build an Accounts report for cases where case status is not closed:

<crossFilters >

<criteriaItems >

<column >Status </column >

<operator >notequal </operator >

<value >Closed </value >

</criteriaItems >

<operation >with </operation >

<primaryTableColumn >ACCOUNT_ID </primaryTableColumn >

<relatedTable >Case </relatedTable >

<relatedTableJoinColumn >Account </relatedTableJoinColumn >

</crossFilters >

Note:

This sample was generated using the API version 23.0.

UserDateInterval

An enumeration of type string that defines the period of time. Valid values:

Enumeration Value

INTERVAL_CURRENT

INTERVAL_CURNEXT1

INTERVAL_CURPREV1

INTERVAL_NEXT1

INTERVAL_PREV1

INTERVAL_CURNEXT3

INTERVAL_CURFY

INTERVAL_PREVFY

INTERVAL_PREV2FY

Description

Current fiscal quarter

Current and next fiscal quarters

Current and previous fiscal quarters

Next fiscal quarter

Previous fiscal quarter

Current and next three fiscal quarters

Current fiscal year

Previous fiscal year

Previous two fiscal years

Report

537

Metadata Types

Enumeration Value

INTERVAL_AGO2FY

INTERVAL_NEXTFY

INTERVAL_PREVCURFY

INTERVAL_PREVCUR2FY

INTERVAL_CURNEXTFY

INTERVAL_CUSTOM

INTERVAL_YESTERDAY

INTERVAL_TODAY

INTERVAL_TOMORROW

INTERVAL_LASTWEEK

INTERVAL_THISWEEK

INTERVAL_NEXTWEEK

INTERVAL_LASTMONTH

INTERVAL_THISMONTH

INTERVAL_NEXTMONTH

INTERVAL_LASTTHISMONTH

INTERVAL_THISNEXTMONTH

INTERVAL_CURRENTQ

INTERVAL_CURNEXTQ

INTERVAL_CURPREVQ

INTERVAL_NEXTQ

INTERVAL_PREVQ

INTERVAL_CURNEXT3Q

INTERVAL_CURY

INTERVAL_PREVY

INTERVAL_PREV2Y

INTERVAL_AGO2Y

INTERVAL_NEXTY

INTERVAL_PREVCURY

INTERVAL_PREVCUR2Y

Description

Two fiscal years ago

Next fiscal year

Current and previous fiscal years

Current and previous two fiscal years

Current and next fiscal year

A custom time period. Use

startDate

and endDate

fields to specify the

time period's start date and end date.

Yesterday

Today

Tomorrow

Last calendar week

This calendar week

Next calendar week

Last calendar month

This calendar month

Next calendar month

Current and previous calendar months

Current and next calendar months

Current calendar quarter

Current and next calendar quarters

Current and previous calendar quarters

Next calendar quarter

Previous calendar quarter

Current and next three calendar quarters

Current calendar year

Previous calendar year

Previous two calendar years

Two calendar years ago

Next calendar year

Current and previous calendar years

Current and previous two calendar years

538

Report

Metadata Types

Enumeration Value

INTERVAL_CURNEXTY

INTERVAL_LAST7

INTERVAL_LAST30

INTERVAL_LAST60

INTERVAL_LAST90

INTERVAL_LAST120

INTERVAL_NEXT7

INTERVAL_NEXT30

INTERVAL_NEXT60

INTERVAL_NEXT90

INTERVAL_NEXT120

LAST_FISCALWEEK

THIS_FISCALWEEK

NEXT_FISCALWEEK

Description

Current and next calendar years

Last 7 days

Last 30 days

Last 60 days

Last 90 days

Last 120 days

Next 7 days

Next 30 days

Next 60 days

Next 90 days

Next 120 days

When custom fiscal years are enabled: Last fiscal week

When custom fiscal years are enabled: This fiscal week

When custom fiscal years are enabled: Next fiscal week

LAST_FISCALPERIOD

THIS_FISCALPERIOD

NEXT_FISCALPERIOD

LASTTHIS_FISCALPERIOD

When custom fiscal years are enabled: Last fiscal period

When custom fiscal years are enabled: This fiscal period

When custom fiscal years are enabled: Next fiscal period

When custom fiscal years are enabled: This fiscal period and last fiscal period

THISNEXT_FISCALPERIOD

CURRENT_ENTITLEMENT_PERIOD

PREVIOUS_ENTITLEMENT_PERIOD

PREVIOUS_TWO_ENTITLEMENT_PERIODS

TWO_ENTITLEMENT_PERIODS_AGO

When custom fiscal years are enabled: This fiscal period and next fiscal period

Current entitlement period

Previous entitlement period

Previous two entitlement periods

Two entitlement periods ago

CURRENT_AND_PREVIOUS_ENTITLEMENT_PERIOD

Current and previous entitlement period

CURRENT_AND_PREVIOUS_TWO_ENTITLEMENT_PERIODS

Current and previous two entitlement periods

Declarative Metadata Sample Definition

A sample XML report definition:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Report xmlns= "http://soap.sforce.com/2006/04/metadata">

<aggregates >

Report

539

Metadata Types

*

<acrossGroupingContext >CRT_Object__c$Id </acrossGroupingContext >

<calculatedFormula >PREVGROUPVAL(CRT_Object__c.Currency__c:AVG, CRT_Object__c.Id)

PARENTGROUPVAL(CRT_Object__c.Number__c:MAX, CRT_Object__c.CreatedBy.Name,

COLUMN_GRAND_SUMMARY)/RowCount </calculatedFormula >

<datatype >number </datatype >

<developerName >FORMULA1 </developerName >

<downGroupingContext >CRT_Object__c$CreatedBy </downGroupingContext >

<isActive >true </isActive >

<masterLabel >CurrCSF </masterLabel >

<scale >2 </scale >

</aggregates >

<aggregates >

<acrossGroupingContext >CRT_Object__c$LastModifiedDate </acrossGroupingContext >

<calculatedFormula >IF(RowCount&gt;10,

BLANKVALUE(ROUND(PREVGROUPVAL(CRT_Object__c.Currency__c:SUM,

CRT_Object__c.LastModifiedDate),3),

PARENTGROUPVAL(CRT_Object__c.Number__c:SUM, ROW_GRAND_SUMMARY,

CRT_Object__c.Id)) , 1000) </calculatedFormula >

<datatype >number </datatype >

<developerName >FORMULA2 </developerName >

<downGroupingContext >GRAND_SUMMARY </downGroupingContext >

<isActive >true </isActive >

<masterLabel >numCSF </masterLabel >

<scale >2 </scale >

</aggregates >

<buckets >

<bucketType >number </bucketType >

<developerName >BucketField_BusinessSize </developerName >

<masterLabel >NumericBucket </masterLabel >

<nullTreatment >z </nullTreatment >

<sourceColumnName >SALES </sourceColumnName >

<values >

<sourceValues >

<to >10000 </to >

</sourceValues >

<value >low </value >

</values >

<values >

<sourceValues >

<from >10000 </from >

<to >25000 </to >

</sourceValues >

<value >mid </value >

</values >

<values >

<sourceValues >

<from >25000 </from >

</sourceValues >

<value >high </value >

</values >

</buckets >

<buckets >

Report

540

Metadata Types

<bucketType >text </bucketType >

<developerName >BucketField_Region </developerName >

<masterLabel >TextBucket </masterLabel >

<nullTreatment >n </nullTreatment >

<otherBucketLabel >Other </otherBucketLabel >

<sourceColumnName >ADDRESS1_STATE </sourceColumnName >

<values >

<sourceValues >

<sourceValue >CA </sourceValue >

</sourceValues >

<value >west </value >

</values >

<values >

<sourceValues >

<sourceValue >NY </sourceValue >

</sourceValues >

<sourceValues >

<sourceValue >Ontario </sourceValue >

</sourceValues >

<value >east </value >

</values >

</buckets >

<chart >

<backgroundColor1 >#FFFFFF </backgroundColor1 >

<backgroundColor2 >#FFFFFF </backgroundColor2 >

<backgroundFadeDir >Diagonal </backgroundFadeDir >

<chartSummaries >

<axisBinding >y </axisBinding >

<column >FORMULA1 </column >

</chartSummaries >

<chartSummaries >

<axisBinding >y </axisBinding >

<column >FORMULA2 </column >

</chartSummaries >

<chartSummaries >

<aggregate >Maximum </aggregate >

<axisBinding >y </axisBinding >

<column >CRT_Object__c$Number__c </column >

</chartSummaries >

<chartSummaries >

<axisBinding >y </axisBinding >

<column >RowCount </column >

</chartSummaries >

<chartType >VerticalColumn </chartType >

<groupingColumn >CRT_Object__c$LastModifiedDate </groupingColumn >

<legendPosition >Right </legendPosition >

<location >CHART_TOP </location >

<size >Medium </size >

<summaryAxisRange >Auto </summaryAxisRange >

<textColor >#000000 </textColor >

<textSize >12 </textSize >

<titleColor >#000000 </titleColor >

<titleSize >18 </titleSize >

</chart >

541

Report

Metadata Types

<columns >

<field >CRT_Object__c$Name </field >

</columns >

<columns >

<aggregateTypes >Average </aggregateTypes >

<field >CRT_Object__c$Currency__c </field >

</columns >

<columns >

<aggregateTypes >Maximum </aggregateTypes >

<field >CRT_Object__c$Number__c </field >

</columns >

<columns >

<field >BucketField__Region </field >

</columns >

<format >Matrix </format >

<groupingsAcross >

<dateGranularity >Day </dateGranularity >

<field >CRT_Object__c$Id </field >

<sortOrder >Asc </sortOrder >

</groupingsAcross >

<groupingsAcross >

<dateGranularity >Year </dateGranularity >

<field >CRT_Object__c$LastModifiedDate </field >

<sortOrder >Asc </sortOrder >

</groupingsAcross >

<groupingsDown >

<dateGranularity >Day </dateGranularity >

<field >CRT_Object__c$CreatedBy </field >

<sortOrder >Asc </sortOrder >

</groupingsDown >

<groupingsDown >

<dateGranularity >Day </dateGranularity >

<field >CRT_Object__c$Currency__c </field >

<sortOrder >Desc </sortOrder >

</groupingsDown >

<name >CrtMMVC </name >

<reportType >CRT1__c </reportType >

<scope >organization </scope >

<showDetails >false </showDetails >

<timeFrameFilter >

<dateColumn >CRT_Object__c$CreatedDate </dateColumn >

<interval >INTERVAL_CUSTOM </interval >

</timeFrameFilter >

</Report >

Declarative Metadata Sample Definition for a Joined Report

A sample XML report definition:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Report xmlns= "http://soap.sforce.com/2006/04/metadata">

<!-- This is a cross-block custom summary formula. Note that the calculated formula reference for a blocks reference uses the BlockId#Aggregate. -->

<aggregates >

542

Report

Metadata Types

<calculatedFormula >B1#AMOUNT:SUM+B2#EMPLOYEES:SUM </calculatedFormula >

<datatype >number </datatype >

<developerName >FORMULA </developerName >

<isActive >true </isActive >

<isCrossBlock >true </isCrossBlock >

<masterLabel >Cross-Block CSF Example </masterLabel >

<scale >2 </scale >

</aggregates >

<!-- This is a standard custom summary formula. Note that the calculated formula reference does not have block reference but just the aggregate name of the report type associated

(Opportunity).-->

<aggregates >

<calculatedFormula >AMOUNT:SUM </calculatedFormula >

<developerName >FORMULA2 </developerName >

<isActive >true </isActive >

<isCrossBlock >false </isCrossBlock >

<masterLabel >Standard CSF Example </masterLabel >

<reportType >Opportunity </reportType >

<scale >2 </scale >

</aggregates >

<block >

<blockInfo >

<!-- This is how the block defines that the custom summary formula should be referenced.

In this example, it’s the in standard FORMULA 2 defined above. This block report has blockID

B1.-->

<aggregateReferences >

<aggregate >FORMULA2 </aggregate >

</aggregateReference >

<blockId >B1 </blockId >

<joinTable >a </joinTable >

</blockInfo >

<columns >

<field >TYPE </field >

</columns >

<format >Summary </format >

<name >Opportunities BLock 3 </name >

<params >

<name >role_territory </name >

<value >role </value >

</params >

<params >

<name >terr </name >

<value >all </value >

</params >

<params >

<name >open </name >

<value >all </value >

</params >

<params >

<name >probability </name >

<value >0 </value >

</params >

<params >

<name >co </name >

Report

543

Metadata Types

<value >1 </value >

</params >

<reportType >Opportunity </reportType >

<scope >organization </scope >

<timeFrameFilter >

<dateColumn >CLOSE_DATE </dateColumn >

<interval >INTERVAL_CUSTOM </interval >

</timeFrameFilter >

</block >

<block >

<blockInfo >

<!-- This is how the block defines that the custom summary formula should be referenced.

In this example, it’s the cross-block custom summary formula FORMULA 1 defined above. This block report has blockId B2.-->

<aggregateReferences >

<aggregate >FORMULA1 </aggregate >

</aggregateReferences >

<blockId >B2 </blockId >

<joinTable >a </joinTable >

</blockInfo >

<columns >

<field >USERS.NAME

</field >

</columns >

<columns >

<field >TYPE </field >

</columns >

<columns >

<field >DUE_DATE </field >

</columns >

<columns >

<field >LAST_UPDATE </field >

</columns >

<columns >

<field >ADDRESS1_STATE </field >

</columns >

<format >Summary </format

<name >Accounts block 5 </name >

<params >

<name >terr </name >

<value >all </value >

</params >

<params >

<name >co </name >

<value >1 </value >

</params >

<reportType >AccountList </reportType >

<scope >organization </scope >

<timeFrameFilter >

<dateColumn >CREATED_DATE </dateColumn >

<interval >INTERVAL_CUSTOM </interval >

</timeFrameFilter >

</block >

<blockInfo >

<blockId xsi:nil= "true"/>

Report

544

Metadata Types ReportType

<joinTable >a </joinTable >

</blockInfo >

<chart >

<backgroundColor1 >#FFFFFF </backgroundColor1 >

<backgroundColor2 >#FFFFFF </backgroundColor2 >

<backgroundFadeDir >Diagonal </backgroundFadeDir >

<chartSummaries >

<axisBinding >y </axisBinding >

<!-- This is how chart aggregates are designed in multiblock. We're using RowCount from

Block 1.-->

<column >B1#RowCount </column >

</chartSummaries >

<chartType >HorizontalBar </chartType >

<enableHoverLabels >false </enableHoverLabels >

<expandOthers >true </expandOthers >

<groupingColumn >ACCOUNT_NAME </groupingColumn >

<location >CHART_TOP </location >

<showAxisLabels >true </showAxisLabels >

<showPercentage >false </showPercentage >

<showTotal >false </showTotal >

<showValues >false </showValues >

<size >Medium </size >

<summaryAxisRange >Auto </summaryAxisRange >

<textColor >#000000 </textColor >

<textSize >12 </textSize >

<titleColor >#000000 </titleColor >

<titleSize >18 </titleSize >

</chart >

<format >MultiBlock </format >

<groupingsDown >

<dateGranularity >Day </dateGranularity >

<field >ACCOUNT_NAME </field >

<sortOrder >Asc </sortOrder >

</groupingsDown >

<name >mb_mbapi </name >

<reportType >Opportunity </reportType >

<showDetails >true </showDetails >

</Report >

SEE ALSO:

Dashboard

ReportType

Represents the metadata associated with a custom report type. This type extends the Metadata

metadata type and inherits its fullName field. Custom report types allow you to build a framework from which users can create and customize reports. For more information, see “Set Up a Custom Report Type” in the Salesforce online help.

545

Metadata Types ReportType

Declarative Metadata File Suffix and Directory Location

The file suffix is

.reportType

for the custom report type definition. There is one file per custom report type. Report types are stored in the reportTypes

directory of the corresponding package directory.

Version

Custom report types are available in API version 14.0 and later.

Fields

Field Name

autogenerated baseObject category deployed

Field Type

boolean string

ReportTypeCategory

(

enumeration

of type string) boolean

Description

Indicates that the report type was automatically generated when historical trending was enabled for an entity.

Available in API version 29 and later.

Required. The primary object for the custom report type, for example,

Account. All objects, including custom and external objects, are supported.

You cannot edit this field after initial creation.

Support for external objects is available in API version 38.0 and later.

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

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

description fullName join label sections

Field Type

string string

ObjectRelationship

string

ReportLayoutSection []

Description

The description of the custom report type.

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.

The object joined to the baseObject

. For example, Contacts may be

joined to the primary Accounts object.

Required. The report type label.

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

join outerJoin relationship

Field Type

ObjectRelationship

boolean string

Description

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.

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.

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

columns masterLabel

Field Type

ReportTypeColumn []

string

Description

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

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

checkedByDefault boolean displayNameOverride string field table string string

Description

Required. Indicates whether this column is selected be default ( true

) or not

( false

).

A customized column name, if desired.

Required. The field name associated with the report column.

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<ReportType xmlns= "http://soap.sforce.com/2006/04/metadata">

<baseObject >Account </baseObject >

<category >accounts </category >

<deployed >true </deployed >

<description >Account linked to Contacts and Assets </description >

<join >

<join >

<outerJoin >false </outerJoin >

<relationship >Assets </relationship >

</join >

<outerJoin >false </outerJoin >

<relationship >Contacts </relationship >

</join >

<label >Account Contacts and Assets </label >

<sections >

<columns >

<checkedByDefault >true </checkedByDefault >

<field >obj_lookup__c.Id

</field >

<table >Account </table >

</columns >

<columns >

<checkedByDefault >false </checkedByDefault >

<field >obj_lookup__c.Name

</field >

<table >Account </table >

</columns >

<columns >

<checkedByDefault >false </checkedByDefault >

<field >Opportunity__c.Amount

</field >

<table >Account </table >

</columns >

<columns >

<checkedByDefault >false </checkedByDefault >

<field >Owner.IsActive

</field >

<table >Account </table >

548

Metadata Types

</columns >

<masterLabel >Accounts </masterLabel >

</sections >

<sections >

<columns >

<checkedByDefault >false </checkedByDefault >

<field >Owner.Email

</field >

<table >Account.Contacts

</table >

</columns >

<columns >

<checkedByDefault >false </checkedByDefault >

<field >byr__c </field >

<table >Account.Contacts

</table >

</columns >

<columns >

<checkedByDefault >true </checkedByDefault >

<field >ReportsTo.CreatedBy.Contact.Owner.MobilePhone

</field >

<table >Account.Contacts

</table >

</columns >

<masterLabel >Contacts </masterLabel >

</sections >

</ReportType >

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

.

<sections >

<columns >

<checkedByDefault >false </checkedByDefault >

<field >Field2__c_hst </field >

<table >CustomTrendedObject__c.CustomTrendedObject__c_hst

</table >

</columns >

<masterLabel >History </masterLabel >

</sections >

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

Role

Metadata Types RoleOrTerritory

Fields

This metadata type extends to subtype RoleOrTerritory on page 550.

Field Name

fullName parentRole

Field Type

string string

Description

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. Corresponds to Role Name in the user interface.

The role above this role in the hierarchy.

Declarative Metadata Sample Definition

The following is the definition of a role.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Role xmlns= "http://soap.sforce.com/2006/04/metadata">

<caseAccessLevel >Edit </caseAccessLevel >

<contactAccessLevel >Edit </contactAccessLevel >

<description >Sample Role </description >

<mayForecastManagerShare >false </mayForecastManagerShare >

<name >R22 </name >

<opportunityAccessLevel >Read </opportunityAccessLevel >

</Role >

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

caseAccessLevel

Field Type

string

Description

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

contactAccessLevel string description fullName

Field Type

string string mayForecastManagerShare boolean name string opportunityAccessLevel string

RoleOrTerritory

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.

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.

The description of the role or territory.

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.

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Role xmlns= "http://soap.sforce.com/2006/04/metadata">

<caseAccessLevel >Edit </caseAccessLevel >

551

Metadata Types SamlSsoConfig

<contactAccessLevel >Edit </contactAccessLevel >

<description >Sample Role </description >

<mayForecastManagerShare >false </mayForecastManagerShare >

<name >R22 </name >

<opportunityAccessLevel >Read </opportunityAccessLevel >

</Role >

The following is the definition of a territory.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Territory xmlns= "http://soap.sforce.com/2006/04/metadata">

<accountAccessLevel >Edit </accountAccessLevel >

<caseAccessLevel >Edit </caseAccessLevel >

<contactAccessLevel >Edit </contactAccessLevel >

<description >Sample Territory </description >

<mayForecastManagerShare >false </mayForecastManagerShare >

<name >T22name </name >

<opportunityAccessLevel >Read </opportunityAccessLevel >

</Territory >

SEE ALSO:

Role

Territory

SamlSsoConfig

Represents a SAML Single Sign-On configuration. This type extends the

Metadata

metadata type and inherits its fullName

field.

Single sign-on (SSO) lets users access authorized network resources with one login. You validate usernames and passwords against your corporate user database or other client app rather than Salesforce managing separate passwords for each resource.

File Suffix and Directory Location

SamlSsoConfig components have the suffix

.samlssoconfig

and are stored in the samlssoconfigs

folder.

Version

SamlSsoConfig components are available in API version 28.0 and later.

Fields

Field Name

attributeName

Field Type

string attributeNameIdFormat string

Description

The name of the identity provider’s application. Get this from your identity provider.

For SAML 2.0 only and when identityLocation

is set to

Attribute

. Possible values include unspecified

, emailAddress

or persistent

. All legal values can be found in

552

Metadata Types SamlSsoConfig

Field Name

decryptionCertificate errorUrl executionUserId identityLocation

Field Type

string string

Description

the “Name Identifier Format Identifiers” section of the Assertions and

Protocols SAML 2.0 specification .

The name of the certificate to use for decrypting incoming SAML assertions. This certificate is saved in the organization’s Certificate and

Key Management list. Available in API version 30.0 and later.

The URL of the page users should be directed to if there’s an error during

SAML login. It must be a publicly accessible page, such as a public site

Visualforce page. The URL can be absolute or relative.

string The user that runs the Apex handler class. The user must have the

“Manage Users” permission. A user is required if you specify a SAML JIT handler class.

SamlIdentityLocationType

(enumeration of type string)

The location in the assertion where a user should be identified. Valid values are:

•

SubjectNameId

— The identity is in the

<Subject> statement of the assertion.

•

Attribute

— The identity is specified in an

<AttributeValue>

, located in the

<Attribute>

of the assertion.

identityMapping

SamlIdentityType

(enumeration of type string)

The identifier the service provider uses for the user during

Just-in-Time user provisioning

. Valid values are:

•

Username

— The user’s Salesforce username.

•

FederationId

— The federation ID from the user object; the identifier used by the service provider for the user.

•

UserId

— The user ID from the user’s Salesforce organization.

issuer loginUrl logoutUrl name oauthTokenEndpoint redirectBinding string string string string string boolean

The identification string for the Identity Provider.

For SAML 2.0 only: The URL where Salesforce sends a SAML request to start the login sequence.

For SAML 2.0 only: The URL to direct the user to when they click the

Logout link. The default is http://www.salesforce.com

.

The unique name used by the API and managed packages. The name must begin with a letter and use only alphanumeric characters and underscores. The name cannot end with an underscore or have two consecutive underscores.

For SAML 2.0 only: The ACS URL used with enabling Salesforce as an identity provider in the Web single sign-on OAuth assertion flow.

If you’re using My Domain, chose the binding mechanism your identity provider requests for your SAML messages. Values are:

•

HTTP POST

— HTTP POST binding sends SAML messages using base64-encoded HTML forms.

553

Metadata Types SamlSsoConfig

Field Name Field Type Description

•

HTTP Redirect

— HTTP Redirect binding sends base64-encoded and URL-encoded SAML messages within URL parameters.

requestSignatureMethod salesforceLoginUrl samlEntityId samlJitHandlerId samlVersion string The method that’s used to sign the SAML request. Valid values are

RSA-SHA1

and

RSA-SHA256

.

The URL associated with login for the Web single sign-on flow.

string string string

The issuer in SAML requests generated by Salesforce, and is also the expected audience of any inbound SAML Responses. If you don’t have domains deployed, this value is always https://saml.salesforce.com

. If you have domains deployed,

Salesforce recommends that you use your custom domain name.

The name of an existing Apex class that implements the

Auth.SamlJitHandler

interface.

SamlType (enumeration of type string)

The SAML version in use. Valid values are:

•

SAML1_1

— SAML 1.1

•

SAML2_0

— SAML 2.0

userProvisioning validationCert boolean string

If true

, Just-in-Time user provisioning is enabled, which creates users on the fly the first time they try to log in. Specify

Federation ID for the identityMapping

value to use this feature.

The certificate used to validate the request. Get this from your identity provider.

Declarative Metadata Sample Definition

The following is an example of a SamlSsoConfig component. The validation certificate string has been truncated for readability.

<?xml

version= "1.0" encoding= "UTF-8"?>

<SamlSsoConfig xmlns= "http://soap.sforce.com/2006/04/metadata">

<identityLocation >SubjectNameId </identityLocation >

<identityMapping >FederationId </identityMapping >

<issuer >https://my-idp.my.salesforce.com

</issuer >

<loginUrl > https://my-idp.my.salesforce.com/idp/endpoint/HttpRedirect

</loginUrl >

<logoutUrl >https://www.salesforce.com

</logoutUrl >

<name >SomeCompany </name >

<oauthTokenEndpoint > https://login.salesforce.com/services/oauth2/token?so= 00DD0000000JxeI

</oauthTokenEndpoint >

<redirectBinding >true </redirectBinding >

<requestSignatureMethod >RSA-SHA1 </requestSignatureMethod >

<salesforceLoginUrl > https://login.salesforce.com?so= 00DD0000000JxeI

</salesforceLoginUrl >

554

Metadata Types

<samlEntityId > https://saml.salesforce.com/customPath

</samlEntityId >

<samlVersion >SAML2_0 </samlVersion >

<userProvisioning >false </userProvisioning >

<validationCert >

MIIEojCCA4qgAwIBAgIOATtxsoBFAAAAAD4...

</validationCert >

</SamlSsoConfig >

Scontrol

Important: Visualforce pages supersede s-controls. Organizations that haven’t previously used s-controls can’t create them.

Existing s-controls are unaffected, and can still be edited.

Deprecated. Represents an Scontrol component, corresponding to an s-control in the Salesforce user interface. For more information,

see “About S-Controls” in the Salesforce online help. This type extends the MetadataWithContent

metadata type and inherits its content and fullName

fields.

Declarative Metadata File Suffix and Directory Location

The file suffix is

.scf

for the s-control file. The accompanying metadata file is named

ScontrolName-meta.xml

.

Scontrol components are stored in the scontrols

folder in the corresponding package directory.

Version

Scontrols are available in API version 10.0 and later.

Fields

This metadata type contains the following fields:

Field Name

content

Field Type

base64Binary

Description

Content of the s-control. 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. This field is inherited from the

MetadataWithContent

component.

contentSource

SControlContentSource (

enumeration

of type string)

Required. Determines how you plan to use the s-control:

•

HTML

: Select this option if you want to enter the content for your

s-control in content

.

•

URL

: Select this option if you want to enter the link or URL of an

external website in content

.

Scontrol

555

Metadata Types

Field Name Field Type Description

•

Snippet

: Snippets are s-controls that are designed to be included in other s-controls. Select this option if you want to enter the content for your s-control snippet in

content

.

description encodingKey fileContent fileName fullName name supportsCaching string Optional text that describes the s-control. This only displays to users with “View All Data” permission (administrator).

Encoding (

enumeration of type string)

Required. The default encoding setting is Unicode:

UTF-8

. Change it if you are passing information to a URL that requires data in a different format. This option is available when you select

URL

as the value for

contentSource

.

base64 string

File contents displayed if you add this s-control to a custom link. The file can contain a Java applet, Active-X control, or any other type of content you want. This option only applies to s-controls with a value of

HTML

for contentSource

.

The unique name for the s-control. This name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. This field cannot be changed for components installed by a managed

package. It is only relevant if the fileContent

field also has a value.

This is a new field in API version 14.0.

string string boolean

The s-control 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. If this field contained characters before version 14.0 that are no longer allowed, the characters were stripped out of this field,

and the previous value of the field was saved in the name

field. This

field is inherited from the

Metadata component.

Required. The unique name for the s-control. It must contain alphanumeric characters only and begin with a letter. For example example_s_control

.

Required. Indicates whether the s-control supports caching ( true

) or not ( false

). Caching optimizes the page so that it remembers which s-controls are on the page when it reloads. This option only applies to HTML s-controls.

Declarative Metadata Sample Definition

The following sample creates the

Myriad_Publishing.scf

s-control, which creates a link to the website specified in the s-control.

The corresponding

Myriad_Publishing.scf-meta.xml

metadata file follows the s-control file.

Scontrol

556

Metadata Types

Myriad_Publishing.scf

file: http://www.myriadpubs.com

Myriad_Publishing.scf-meta.xml

:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Scontrol xmlns= "http://soap.sforce.com/2006/04/metadata">

<contentSource >URL </contentSource >

<description >s-control to open Myriad Publishing website.

</description >

<encodingKey >UTF-8 </encodingKey >

<name >Myriad Publishing </name >

<supportsCaching >true </supportsCaching >

</Scontrol >

Settings

Represents the organization settings related to a feature. For example, your password policies, session settings and network access controls are all available in the SecuritySettings component type. Not all feature settings are available in the Metadata API. See

Unsupported

Metadata Types on page 118 for information on which feature settings are not available.

Settings can be accessed using the specific component member or via wildcard. For example, in the package manifest file you would use the following section to access SecuritySettings:

<types >

<members >Security </members >

<name >Settings </name >

</types >

The member format when used in the package manifest is the component metadata type name without the “Settings” suffix, so in the preceding example “Security” is used instead of “SecuritySettings”.

File Suffix and Directory Location

Each settings component gets stored in a single file in the settings

directory of the corresponding package directory. The filename uses the format

Setting feature.settings

. For example, the SecuritySettings file would be

Security.settings

. See

“File Suffix and Directory Location” information for the individual settings components to determine the exact filename.

Version

Settings is available in API version 27.0 and later. See the version information for the individual setting component to determine which

API version the settings component became available.

Declarative Metadata Sample Definition

The following is an example package manifest used to deploy or retrieve only the MobileSettings for an organization:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Mobile </members >

<name >Settings </name >

Settings

557

Metadata Types AccountSettings

</types >

<version >27.0

</version >

</Package >

The following is an example package manifest used to deploy or retrieve all the available settings metadata for an organization, using a wildcard:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >Settings </name >

</types >

<version >27.0

</version >

</Package >

SEE ALSO:

AccountSettings

ActivitiesSettings

AddressSettings

CaseSettings

ChatterAnswersSettings

CompanySettings

ContractSettings

EntitlementSettings

ForecastingSettings

IdeasSettings

KnowledgeSettings

MobileSettings

SecuritySettings

AccountSettings

Represents an organization’s account settings for account teams, account owner report, and the View Hierarchy link. 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

AccountSettings values are stored in the

Account.settings

file 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

AccountSettings is available in API versions 29.0 and later.

558

Metadata Types

Fields

Field Name Field Type

enableAccountOwnerReport boolean enableAccountTeams boolean showViewHierarchyLink boolean

ActivitiesSettings

Description

Indicates whether Account Owner Report may ( true

) or may not

( false

) be run by all users.

Indicates whether Account Teams are enabled ( true

) or not ( false

).

The Metadata API cant’ be used to disable Account Teams.

Indicates whether the default View Hierarchy link on all business account detail pages is visible ( true

) or hidden ( false

).

Declarative Metadata Sample Definition

The following is an example of the Account.settings file:

<?xml

version= "1.0" encoding= "UTF-8"?>

<AccountSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<enableAccountOwnerReport >true </enableAccountOwnerReport >

<enableAccountTeams >true </enableAccountTeams >

<showViewHierarchyLink >true </showViewHierarchyLink >

</AccountSettings >

Example Package Manifest

The following is an example package manifest used to deploy or retrieve the Account settings metadata for an organization:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Account </members >

<name >Settings </name >

</types >

<version >29.0

</version >

</Package >

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 enableActivityReminders boolean enableClickCreateEvents boolean enableDragAndDropScheduling 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.

Enables popup activity reminders for an organization.

Administrators control this field on the Activity settings page.

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.

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

enableEmailTracking enableGroupTasks

Field Type

boolean enableListViewScheduling boolean enableMultidayEvents enableRecurringEvents enableRecurringTasks enableSidebarCalendarShortcut enableSimpleTaskCreateUI enableUNSTaskDelegatedToNotifications meetingRequestsLogo showCustomLogoMeetingRequests boolean boolean boolean boolean boolean boolean boolean string boolean

ActivitiesSettings

Description

Administrators control this field on the User Interface settings page.

Enables tracking of outbound HTML emails if an organization uses HTML email templates.

Administrators control this field on the Activity settings page.

Lets users assign independent copies of a new task to multiple users.

Administrators control this field on the Activity settings page.

Extends the functionality of enableDragAndDropScheduling and enableClickCreateEvents

to list view calendars.

Administrators control this field on the User Interface settings page.

Enables creation of events that end more than 24 hours after they start.

Administrators control this field on the Activity settings page.

Enables creation of events that repeat at specified intervals.

Administrators control this field on the Activity settings page.

Enables creation of tasks that repeat at specified intervals.

Administrators control this field on the Activity settings page.

In the sidebar, displays a shortcut link to a user’s last-used calendar view.

Administrators control this field on the Activity settings page.

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.

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.

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 Field Type

showEventDetailsMultiUserCalendar boolean showHomePageHoverLinksForEvents boolean showMyTasksHoverLinks showRequestedMeetingsOnHomePage boolean boolean

ActivitiesSettings

Description

Displays event details on-screen rather than in hover text.

Administrators control this field on the Activity settings page.

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.

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.

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:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Activities </members >

<name >Settings </name >

</types >

<version >28.0

</version >

</Package >

562

Metadata Types AddressSettings

Declarative Metadata Sample Definition

The following is an example of an activity settings file:

<?xml

version= "1.0" encoding= "UTF-8"?>

<ActivitiesSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<enableActivityReminders >true </enableActivityReminders >

<enableClickCreateEvents >true </enableClickCreateEvents >

<enableDragAndDropScheduling >true </enableDragAndDropScheduling >

<enableEmailTracking >true </enableEmailTracking >

<enableGroupTasks >true </enableGroupTasks >

<enableListViewScheduling >true </enableListViewScheduling >

<enableMultidayEvents >true </enableMultidayEvents >

<enableRecurringEvents >true </enableRecurringEvents >

<enableRecurringTasks >true </enableRecurringTasks >

<enableSidebarCalendarShortcut >true </enableSidebarCalendarShortcut >

<meetingRequestsLogo >Folder02/logo03.png

</meetingRequestsLogo >

<showCustomLogoMeetingRequests >true </showCustomLogoMeetingRequests >

<showEventDetailsMultiUserCalendar >true </showEventDetailsMultiUserCalendar >

<showHomePageHoverLinksForEvents >true </showHomePageHoverLinksForEvents >

<showMyTasksHoverLinks >true </showMyTasksHoverLinks >

<showRequestedMeetingsOnHomePage >true </showRequestedMeetingsOnHomePage >

</ActivitiesSettings >

SEE ALSO:

Document

AddressSettings

Represents the configuration of country and state picklists. Use the AddressSettings component type to configure state and country data in your organization so that you can convert text-based values into standard picklist values. To convert your state and country values, from Setup, enter

State and Country Picklists

in the

Quick Find

box, then select State and Country Picklists

. For more information, see “Let Users Select State and Country from Picklists” in the Salesforce online help.

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.

Declarative Metadata File Suffix and Directory Location

AddressSettings values are stored in a single file named

Address.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

AddressSettings is available in API versions 27.0 and later.

CountriesAndStates

This complex metadata type represents valid definitions of states and countries in picklists.

563

Metadata Types AddressSettings

Field

Note: You can use the Metadata API to edit existing states and countries in state and country picklists. You can’t use the Metadata

API to create or delete new states or countries.

countries

Field Type

Country

[]

Description

The countries available in picklists.

Country

This metadata type provides the definition for a country in a picklist.

Field

active

Field Type

boolean

Description

Determines whether the value is available in the API.

Important: After you enable state and country picklists in your Salesforce organization, you can’t set the active

status to

false

.

integrationValue string isoCode label orgDefault standard states visible string string boolean boolean

State

[] boolean

A customizable text value that is linked to a state or country code. Integration values for standard states and countries default to the full ISO-standard state and country names. Integration values function similarly to the API names of custom fields and objects. Configuring integration values allows integrations that you set up before enabling state and country picklists to continue to work.

Important: If you don’t specify integration values before enabling state and country picklists in your organization, records use the default value provided by Salesforce. If you change integration values later, records created or updated from that point on use your edited values.

The ISO-standard code populates this field when you issue a retrieve()

call. This field is read only in the API but you can edit the label in Setup. You can’t edit the isoCode

of standard

states and countries.

The label is what users see in picklists in Salesforce. This field is read only in the API but you can edit the label in Setup.

Sets a country as the default value for new records in the

Salesforce organization.

Standard states and countries are states and countries that are included with Salesforce. You can’t edit the standard attribute.

The states or provinces that are part of the country.

Makes the state or country available to users in Salesforce. States or countries that are visible

must also be active

.

564

Metadata Types AddressSettings

State

This metadata type provides the definition for a state in a picklist.

Field

active

Field Type

boolean integrationValue isoCode label standard visible string string string boolean boolean

Description

Determines whether the value is available in the API.

Important:

After you enable state and country picklists in your Salesforce organization, you can’t set the active

status to

false

.

A customizable text value that is linked to a state or country code. Integration values for standard states and countries default to the full ISO-standard state and country names. Integration values function similarly to the API names of custom fields and objects. Configuring integration values allows integrations that you set up before enabling state and country picklists to continue to work.

Important: If you don’t specify integration values before enabling state and country picklists in your organization, records use the default value provided by Salesforce. If you change integration values later, records created or updated from that point on use your edited values.

The ISO-standard code populates this field when you issue a retrieve()

call. This field is read only in the API but you can edit the label in Setup.

The label is what users see in picklists in Salesforce. This field is read only in the API but you can edit the label in Setup.

Standard states and countries are states and countries that are included with Salesforce. You can’t edit the standard attribute.

Makes the state or country available to users in Salesforce. States or countries that are visible

must also be active

.

Declarative Metadata Sample Definition

The following is sample XML that configures state and country picklists for the United States and Canada for use in an organization. It also makes the country of Greenland available only in the API. This example is supported in API version 39.0.

<?xml

version= "1.0" encoding= "UTF-8"?>

<AddressSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<countriesAndStates >

<countries >

<country >

<active >true </active >

<integrationValue >United States </integrationValue >

565

Metadata Types

<isoCode >US </isoCode >

<label >United States </label >

<orgDefault >true </orgDefault >

<standard >true </standard >

<states >

<state >

<active >true </active >

<integrationValue >Alabama </integrationValue >

<isoCode >AL </isoCode >

<label >Alabama </label >

<standard >true </standard >

<visible >true </visible >

</state >

<state >

<active >true </active >

<integrationValue >Alaska </integrationValue >

<isoCode >AK </isoCode >

<label >Alaska </label >

<standard >true </standard >

<visible >true </visible >

</state >

</states >

<visible >true </visible >

</country >

<country >

<active >true </active >

<integrationValue >Canada </integrationValue >

<isoCode >CA </isoCode >

<label >Canada </label >

<orgDefault >false </orgDefault >

<states >

<state >

<active >true </active >

<integrationValue >Alberta </integrationValue >

<isoCode >AB </isoCode >

<label >Alberta </label >

<standard >true </standard >

<visible >true </visible >

</state >

<state >

<active >true </active >

<integrationValue >British Columbia </integrationValue >

<isoCode >BC </isoCode >

<label >British Columbia </label >

<standard >true </standard >

<visible >true </visible >

</state >

</states >

<visible >true </visible >

</country >

<country >

<active >true </active >

<integrationValue >Greenland </integrationValue >

<isoCode >GL </isoCode >

566

AddressSettings

Metadata Types BusinessHoursSettings

<label >Greenland </label >

<standard >true </standard >

<visible >false </visible >

</country >

</countries >

</countriesAndStates >

</AddressSettings >

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

businessHours

Field Type

BusinessHoursEntry []

holidays

Holidays []

Description

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

Represents a holiday and its usage in businessHours

.

BusinessHoursEntry

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

Field Name

timeZoneId name active default

Field Type

string string string string

Description

The time zone for the time that defines business hours.

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

Indicates whether the business hours are active.

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

567

Metadata Types

Field Name

mondayStartTime mondayEndTime tuesdayStartTime tuesdayEndTime wednesdayStartTime wednesdayEndTime thursdayStartTime thursdayEndTime fridayStartTime fridayEndTime saturdayStartTime saturdayEndTime sundayStartTime sundayEndTime

Field Type

string string string string string string string string string string string string string string

BusinessHoursSettings

Description

Start time for the business hours on Monday. Uses the format

HH:mm:ss.SSSZ

.

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.

Start time for the business hours on Tuesday. Uses the format

HH:mm:ss.SSSZ

.

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.

Start time for the business hours on Wednesday. Uses the format

HH:mm:ss.SSSZ

.

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.

Start time for the business hours on Thursday. Uses the format

HH:mm:ss.SSSZ

.

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.

Start time for the business hours on Friday. Uses the format

HH:mm:ss.SSSZ

.

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.

Start time for the business hours on Saturday. Uses the format

HH:mm:ss.SSSZ

.

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.

Start time for the business hours on Sunday. Uses the format

HH:mm:ss.SSSZ

.

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

name description isRecurring activityDate recurrenceStartDate recurrenceEndDate startTime endTime recurrenceType recurrenceInterval recurrenceDayOfWeek recurrenceDayOfMonth recurrenceInstance string string string string

Field Type

string string string string string string string string string recurrenceMonthOfYear businessHours string string

Description

Name of the holiday. This name does not have to be unique.

The description of the holiday.

Indicates whether the holiday is recurring.

The date of the holiday. Use for non-recurring holidays. Uses the format

HH:mm:ss.SSSZ

.

The date the holiday starts recurring. Uses the format yyyy-mm-dd

.

The date the holiday stops recurring. Uses the format yyyy-mm-dd

.

Optional.

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.

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.

The recurrence type of the holiday. Valid values are: RecursDaily,

RecursEveryWeekday, RecursMonthly, RecursMonthlyNth, RecursWeekly,

RecursYearly, RecursYealyNth.

The interval of weeks, months, or years the holiday recurs.

The day of week the holiday recurs. Valid values: Monday, Tuesday,

Wednesday, Thursday, Friday, Saturday, Sunday.

The day of month the holiday recurs. Valid values: integers 1-31.

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.

Valid values: January, February, March, April, May, June, July, August,

September, October, November, December.

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:

<?xml

version= "1.0" encoding= "UTF-8"?>

<BusinessHoursSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<businessHours >

<active >true </active >

<default >true </default >

<fridayEndTime >00:00:00.000Z

</fridayEndTime >

569

Metadata Types

<fridayStartTime >00:00:00.000Z

</fridayStartTime >

<mondayEndTime >00:00:00.000Z

</mondayEndTime >

<mondayStartTime >00:00:00.000Z

</mondayStartTime >

<name >Default </name >

<saturdayEndTime >00:00:00.000Z

</saturdayEndTime >

<saturdayStartTime >00:00:00.000Z

</saturdayStartTime >

<sundayEndTime >00:00:00.000Z

</sundayEndTime >

<sundayStartTime >00:00:00.000Z

</sundayStartTime >

<thursdayEndTime >00:00:00.000Z

</thursdayEndTime >

<thursdayStartTime >00:00:00.000Z

</thursdayStartTime >

<timeZoneId >America/Los_Angeles </timeZoneId >

<tuesdayEndTime >00:00:00.000Z

</tuesdayEndTime >

<tuesdayStartTime >00:00:00.000Z

</tuesdayStartTime >

<wednesdayEndTime >00:00:00.000Z

</wednesdayEndTime >

<wednesdayStartTime >00:00:00.000Z

</wednesdayStartTime >

</businessHours >

<businessHours >

<active >true </active >

<default >false </default >

<fridayEndTime >00:00:00.000Z

</fridayEndTime >

<fridayStartTime >00:00:00.000Z

</fridayStartTime >

<mondayEndTime >15:00:00.000Z

</mondayEndTime >

<mondayStartTime >09:00:00.000Z

</mondayStartTime >

<name >bh1 </name >

<saturdayEndTime >00:00:00.000Z

</saturdayEndTime >

<saturdayStartTime >00:00:00.000Z

</saturdayStartTime >

<sundayEndTime >00:00:00.000Z

</sundayEndTime >

<sundayStartTime >00:00:00.000Z

</sundayStartTime >

<thursdayEndTime >17:00:00.000Z

</thursdayEndTime >

<thursdayStartTime >10:50:00.000Z

</thursdayStartTime >

<timeZoneId >America/Los_Angeles </timeZoneId >

<tuesdayEndTime >13:00:00.000Z

</tuesdayEndTime >

<tuesdayStartTime >09:00:00.000Z

</tuesdayStartTime >

<wednesdayEndTime >15:00:00.000Z

</wednesdayEndTime >

<wednesdayStartTime >09:00:00.000Z

</wednesdayStartTime >

</businessHours >

<holidays >

<activityDate >2013-09-02 </activityDate >

<businessHours >Default </businessHours >

<businessHours >bh1 </businessHours >

<isRecurring >false </isRecurring >

<name >Labor Day </name >

</holidays >

<holidays >

<businessHours >bh1 </businessHours >

<isRecurring >true </isRecurring >

<name >Thanksgiving </name >

<recurrenceDayOfMonth >21 </recurrenceDayOfMonth >

<recurrenceMonthOfYear >November </recurrenceMonthOfYear >

<recurrenceStartDate >2013-11-21 </recurrenceStartDate >

<recurrenceType >RecursYearly </recurrenceType >

</holidays >

</BusinessHoursSettings >

570

BusinessHoursSettings

Metadata Types CaseSettings

The following is an example package.xml

manifest that references the BusinessHoursSettings definitions:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >BusinessHours </members >

<name >Settings </name >

</types >

<version >29.0

</version >

</Package >

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

caseAssignNotificationTemplate string caseCloseNotificationTemplate string caseCommentNotificationTemplate string caseCreateNotificationTemplate string caseFeedItemSettings

FeedItemSettings

[] closeCaseThroughStatusChange boolean

Description

Specifies the email template used for case assignment notifications. The format must be folderName

/ emailTemplateName

.

Specifies the email template used for case close notifications.

The format must be folderName

/ emailTemplateName

.

Specifies the email template used for case comment notifications. The format must be folderName

/ emailTemplateName

.

Specifies the email template used for case create notifications. The format must be folderName

/ emailTemplateName

.

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

defaultCaseOwner defaultCaseOwnerType defaultCaseUser

Field Type

string string string

Description

Specifies the default owner of a case when assignment rules fail to locate an owner.

Specifies whether the default case owner is a user or a queue.

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 enableCaseFeed enableDraftEmails enableEarlyEscalationRuleTriggers enableNewEmailDefaultTemplate enableSuggestedArticlesApplication enableSuggestedArticlesCustomerPortal enableSuggestedArticlesPartnerPortal enableSuggestedSolutions keepRecordTypeOnAssignmentRule

EmailToCaseSettings

boolean boolean boolean boolean boolean boolean boolean boolean boolean

The organization’s Email-to-Case settings.

Indicates whether Case Feed is enabled ( true

) or not

( false

).

Indicates whether draft emails are enabled ( true

) or not

( false

). Enabling email drafts requires that Case Feed and

Email-to-Case are also enabled.

Indicates whether early triggers on escalation rules are enabled ( true

) or not ( false

).

Indicates whether default email templates are enabled

( true

) or not ( false

). Default email templates are available only if draft emails are enabled.

Indicates whether the Suggested Articles list appears on case pages.( true

) or not ( false

). Is only valid if enableSuggestedSolutions

= false

.

Indicates whether the Suggested Articles list appears on customer portal pages ( true

) or not ( false

). Is only valid if enableSuggestedSolutions

= false

.

Indicates whether the Suggested Articles list appears on partner portal pages ( true

) or not ( false

). Is only valid if enableSuggestedSolutions

= false

.

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

.

Indicates whether, when applying assignment rules to manually created records, to keep the existing record type

572

Metadata Types CaseSettings

Field Name

newEmailDefaultTemplateClass notifyContactOnCaseComment notifyDefaultCaseOwner notifyOwnerOnCaseComment systemUserEmail useSystemEmailAddress boolean boolean notifyOwnerOnCaseOwnerChange boolean showFewerCloseActions useSystemUserAsDefaultCaseUser webToCase

Field Type

string boolean boolean string boolean boolean

WebToCaseSettings

Description

( true

) or to override the existing record type with the assignee’s default record type ( false

).

Specifies the Apex class that defines the default email template for new email messages in Case Feed. This field appears only when enableNewEmailDefaultTemplate=true

.

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

).

Indicates whether the default case owner is notified when assigned a new case ( true

) or not ( false

).

Indicates whether the case owner is notified when a comment is added to a case ( true

) or not ( false

).

Indicates whether the

Send Notification Email checkbox on cases is automatically selected when users change a case owner to another user ( true

).

Indicates whether the Save & Close button on case edit pages and the Cls link on Cases related lists are hidden

( true

) or shown ( false

).

Specifies the email address used when the default case user is the system user.

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

).

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.

The organization’s Web-to-Case settings.

EmailToCaseSettings

Represents an organization’s Email-to-Case settings.

573

Metadata Types CaseSettings

Fields

Field Name

enableEmailToCase enableHtmlEmail enableOnDemandEmailToCase enableThreadIDInBody enableThreadIDInSubject

Field Type

boolean boolean boolean boolean boolean

Description

Indicates whether Email-to-Case is enabled ( true

) or not

( false

). Note: once Email-to-Case is enabled, it can’t be disabled.

Indicates whether HTML email is enabled ( true

) or not

( false

).

Indicates whether On-Demand Email-to-Case is enabled

( true

) or not ( false

).

Indicates whether the Thread ID for a case is inserted in the body of an email ( true

) or not ( false

).

Indicates whether the Thread ID for a case is inserted in the subject line of an email ( true

) or not ( false

).

notifyOwnerOnNewCaseEmail overEmailLimitAction 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

).

EmailToCaseOnFailureActionType

(

enumeration of type string)

Specifies what happens to email messages received after an 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

).

The organization’s Email-to-Case routing address settings.

routingAddresses

EmailToCaseRoutingAddress []

unauthorizedSenderAction

EmailToCaseOnFailureActionType

(

enumeration of type string)

Specifies what happens to email messages received from invalid senders. Valid values are:

•

Bounce

•

Discard

EmailToCaseRoutingAddress

Represents an organization’s Email-to-Case routing address.

574

Metadata Types CaseSettings

Fields

Field Name

addressType authorizedSenders caseOrigin caseOwner caseOwnerType casePriority createTask emailAddress emailServicesAddress isVerified routingName saveEmailHeaders taskStatus

Field Type Description

EmailToCaseRoutingAddressType

( enumeration of type string)

Specifies the type of Email-to-Case routing address. Valid 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.

string 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.

Specifies the default case origin for cases created through this routing address.

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.

string string boolean string string boolean string boolean string

Specifies whether the default case owner is a user or a queue.

Specifies the default case priority for cases created through this routing address.

Indicates whether a task is automatically assigned to the case owner when a case is created through an email ( true

) or not ( false

).

Specifies the email address used to route email messages that are submitted as cases.

Reserved for future use.

Reserved for future use.

Specifies the name of the Email-to-Case routing address.

Indicates whether email routing and envelope information are saved ( true

) or not ( false

).

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

characterLimit collapseThread displayFormat feedItemType

(

Field Type

int boolean

FeedItemDisplayFormat

enumeration

of type string)

Description

Specifies the maximum number of characters displayed for each feed item.

Indicates whether earlier messages in an email thread are removed from email feed items( true

) or not ( false

).

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 (

enumeration

of type string)

The type of feed item to which the settings apply. For

FeedItemSettings

, the only valid feedItemType value is

EmailMessageEvent

.

WebToCaseSettings

Represents an organization’s Web-to-Case settings.

Fields

Field Name

caseOrigin

Field Type

string defaultResponseTemplate string enableWebToCase boolean

Description

Specifies the default case origin for cases created through this web form.

Only applies if enableWebToCase

is set to true

.

Specifies the default template used for email responses to cases submitted through a Self-Service portal. Only applies if enableWebToCase

is set to true

.

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CaseSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<caseAssignNotificationTemplate > unfiled$public/SupportCaseAssignmentNotification

</caseAssignNotificationTemplate >

<caseCloseNotificationTemplate > unfiled$public/SupportCaseCloseNotification

</caseCloseNotificationTemplate >

576

Metadata Types CaseSettings

<caseCommentNotificationTemplate > unfiled$public/SupportCaseCommentNotification

</caseCommentNotificationTemplate >

<caseCreateNotificationTemplate > unfiled$public/SupportCaseCreateNotification

</caseCreateNotificationTemplate >

<closeCaseThroughStatusChange >true </closeCaseThroughStatusChange >

<defaultCaseOwner >[email protected]

</defaultCaseOwner >

<defaultCaseOwnerType >User </defaultCaseOwnerType >

<defaultCaseUser >[email protected]

</defaultCaseUser >

<emailToCase >

<enableEmailToCase >true </enableEmailToCase >

<enableHtmlEmail >false </enableHtmlEmail >

<enableOnDemandEmailToCase >true </enableOnDemandEmailToCase >

<enableThreadIDInBody >true </enableThreadIDInBody >

<enableThreadIDInSubject >true </enableThreadIDInSubject >

<notifyOwnerOnNewCaseEmail >false </notifyOwnerOnNewCaseEmail >

<overEmailLimitAction >Bounce </overEmailLimitAction >

<preQuoteSignature >true </preQuoteSignature >

<routingAddresses >

<addressType >EmailToCase </addressType >

<authorizedSenders >[email protected]

</authorizedSenders >

<caseOrigin >Email </caseOrigin >

<casePriority >Medium </casePriority >

<createTask >true </createTask >

<emailAddress >[email protected]

</emailAddress >

<routingName >EmailToCaseRoutingAddress1 </routingName >

<saveEmailHeaders >true </saveEmailHeaders >

<taskStatus >Not Started </taskStatus >

</routingAddresses >

<routingAddresses >

<addressType >Outlook </addressType >

<authorizedSenders >[email protected]

</authorizedSenders >

<caseOrigin >Email </caseOrigin >

<caseOwner >[email protected]

</caseOwner >

<caseOwnerType >User </caseOwnerType >

<casePriority >High </casePriority >

<routingName >OutlookRoutingAddress1 </routingName >

</routingAddresses >

<unauthorizedSenderAction >Discard </unauthorizedSenderAction >

</emailToCase >

<enableCaseFeed >true </enableCaseFeed >

<enableDraftEmails >true </enableDraftEmails >

<enableEarlyEscalationRuleTriggers >true </enableEarlyEscalationRuleTriggers >

<enableNewEmailDefaultTemplate >true </enableNewEmailDefaultTemplate >

<enableSuggestedArticlesApplication >true </enableSuggestedArticlesApplication >

<enableSuggestedArticlesCustomerPortal >true </enableSuggestedArticlesCustomerPortal >

<enableSuggestedArticlesPartnerPortal >false </enableSuggestedArticlesPartnerPortal >

<enableSuggestedSolutions >false </enableSuggestedSolutions >

<keepRecordTypeOnAssignmentRule >true </keepRecordTypeOnAssignmentRule >

<newEmailDefaultTemplateClass >CaseTemplateController </newEmailDefaultTemplateClass >

<notifyContactOnCaseComment >true </notifyContactOnCaseComment >

<notifyDefaultCaseOwner >true </notifyDefaultCaseOwner >

<notifyOwnerOnCaseComment >true </notifyOwnerOnCaseComment >

577

Metadata Types ChatterAnswersSettings

<notifyOwnerOnCaseOwnerChange >false </notifyOwnerOnCaseOwnerChange >

<showFewerCloseActions >false </showFewerCloseActions >

<useSystemEmailAddress >true </useSystemEmailAddress >

<webToCase >

<caseOrigin >Web </caseOrigin >

<defaultResponseTemplate >unfiled$public/SupportCaseResponse </defaultResponseTemplate >

<enableWebToCase >true </enableWebToCase >

</webToCase >

</CaseSettings >

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

emailFollowersOnBestAnswer boolean emailFollowersOnReply emailOwnerOnPrivateReply boolean emailOwnerOnReply enableAnswerViaEmail enableChatterAnswers boolean boolean boolean boolean

Description

Indicates whether users are notified when a best answer is selected for a question that they’re following ( true

) or not ( false

).

Indicates whether users are notified when other users reply to questions they’re following ( true

) or not ( false

).

Indicates whether users are notified when customer support responds to their questions privately ( true

) or not ( false

).

Indicates whether users are notified when other users reply to their questions ( true

) or not ( false

).

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.

Indicates whether Chatter Answers is enabled in the organization ( true

) or not ( false

).

578

Metadata Types ChatterAnswersSettings

Field Name

enableFacebookSSO enableInlinePublisher boolean enableReputation enableRichTextEditor facebookAuthProvider showInPortals

Field Type

boolean boolean boolean string boolean

Description

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.

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.

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.

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.

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.

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:

<?xml

version= "1.0" encoding= "UTF-8"?>

<ChatterAnswersSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<emailFollowersOnBestAnswer >true </emailFollowersOnBestAnswer >

<emailFollowersOnReply >true </emailFollowersOnReply >

<emailOwnerOnPrivateReply >true </emailOwnerOnPrivateReply >

<emailOwnerOnReply >true </emailOwnerOnReply >

<enableChatterAnswers >true </enableChatterAnswers >

<enableFacebookSSO >true </enableFacebookSSO >

<enableInlinePublisher >true </enableInlinePublisher >

<enableReputation >true </enableReputation >

<enableRichTextEditor >true </enableRichTextEditor >

<facebookAuthProvider >FacebookAuthProvider </facebookAuthProvider >

<showInPortals >true </showInPortals >

</ChatterAnswersSettings >

The following is an example package.xml

manifest that references the ChatterAnswersSettings definitions:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

579

Metadata Types CompanySettings

<types >

<members >ChatterAnswers </members >

<name >Settings </name >

</types >

<version >29.0

</version >

</Package >

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

fiscalYear

Field Type

FiscalYearSetting

Description

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

fiscalYearNameBasedOn

Field Type

string

Description

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 ContractSettings

Field

startMonth

Field Type

string

Description

•

startingMonth

, then 2012 is used for the fiscal year name.

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<CompanySettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<fiscalYear >

<fiscalYearNameBasedOn >endingMonth </fiscalYearNameBasedOn >

<startMonth >January </startMonth >

</fiscalYear >

</CompanySettings >

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

autoCalculateEndDate notifyOwnersOnContractExpiration

Field Type

boolean boolean

Description

Indicates whether the end date of a contract is automatically calculated

( true

) or not ( false

).

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<ContractSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<autoCalculateEndDate >true </autoCalculateEndDate >

<notifyOwnersOnContractExpiration >false </notifyOwnersOnContractExpiration >

</ContractSettings >

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

assetLookupLimitedToActiveEntitlementsOnAccount boolean assetLookupLimitedToActiveEntitlementsOnContact boolean assetLookupLimitedToSameAccount boolean assetLookupLimitedToSameContact boolean enableEntitlements boolean

Description

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

).

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

).

Indicates whether entitlements-related lookup filters on cases return only the assets related to the case’s account

( true

) or not ( false

).

Indicates whether entitlements-related lookup filters on cases return only the assets related to the case’s contact

( true

) or not ( false

).

Indicates whether entitlements are enabled ( true

) or not

( false

).

582

Metadata Types EntitlementSettings

Field Name

enableEntitlementVersioning

Field Type

boolean entitlementLookupLimitedToActiveStatus boolean entitlementLookupLimitedToSameAccount boolean entitlementLookupLimitedToSameAsset boolean entitlementLookupLimitedToSameContact boolean

Description

Indicates whether entitlement versioning is enabled

( true

) or not ( false

).

This field is available in API version 28.0 and later.

Indicates whether entitlements-related lookup filters on cases return only active entitlements ( true

) or not

( false

).

Indicates whether entitlements-related lookup filters on cases return only the entitlements related to the case’s account ( true

) or not ( false

).

Indicates whether entitlements-related lookup filters on cases return only the entitlements related to the case’s asset ( true

) or not ( false

).

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<EntitlementSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<assetLookupLimitedToActiveEntitlementsOnAccount > false

</assetLookupLimitedToActiveEntitlementsOnAccount >

<assetLookupLimitedToActiveEntitlementsOnContact > false

</assetLookupLimitedToActiveEntitlementsOnContact >

<assetLookupLimitedToSameAccount > false

</assetLookupLimitedToSameAccount >

<assetLookupLimitedToSameContact > false

</assetLookupLimitedToSameContact >

<enableEntitlements > true

</enableEntitlements >

<entitlementLookupLimitedToActiveStatus > false

</entitlementLookupLimitedToActiveStatus >

<entitlementLookupLimitedToSameAccount > false

</entitlementLookupLimitedToSameAccount >

<entitlementLookupLimitedToSameAsset > false

</entitlementLookupLimitedToSameAsset >

583

Metadata Types FileUploadAndDownloadSecuritySettings

<entitlementLookupLimitedToSameContact > false

</entitlementLookupLimitedToSameContact >

</EntitlementSettings >

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

dispositions

Field Type Description

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

behavior

Field Type

FileDownloadBehavior

( enumeration of type string)

Description

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 FileUploadAndDownloadSecuritySettings

Field Name

filetype securityRiskFileType

Field Type

FileType ( enumeration

of type string) boolean

Description

•

HTML

•

RFC822

•

SVG

•

TXML

•

UNKNOWN

•

WEBVIEW

•

XHTML

•

XML

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

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.

<FileUploadAndDownloadSecuritySettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<dispositions >

<behavior >HYBRID </behavior >

<fileType >AVI </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >HYBRID </behavior >

<fileType >WORD </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >HYBRID </behavior >

<fileType >WORD_X </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >DOWNLOAD </behavior >

<fileType >EXE </fileType >

<securityRiskFileType >true </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >DOWNLOAD </behavior >

<fileType >HTML </fileType >

<securityRiskFileType >true </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >DOWNLOAD </behavior >

<fileType >WEBVIEW </fileType >

<securityRiskFileType >true </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >DOWNLOAD </behavior >

<fileType >RFC822 </fileType >

<securityRiskFileType >true </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >HYBRID </behavior >

<fileType >MOV </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >HYBRID </behavior >

<fileType >MP3 </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >HYBRID </behavior >

<fileType >MP4 </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

586

Metadata Types

<dispositions >

<behavior >HYBRID </behavior >

<fileType >MPEG </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >HYBRID </behavior >

<fileType >PDF </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >HYBRID </behavior >

<fileType >POWER_POINT </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >HYBRID </behavior >

<fileType >POWER_POINT_X </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >DOWNLOAD </behavior >

<fileType >SVG </fileType >

<securityRiskFileType >true </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >DOWNLOAD </behavior >

<fileType >FLASH </fileType >

<securityRiskFileType >true </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >DOWNLOAD </behavior >

<fileType >TXML </fileType >

<securityRiskFileType >true </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >DOWNLOAD </behavior >

<fileType >UNKNOWN </fileType >

<securityRiskFileType >true </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >HYBRID </behavior >

<fileType >WAV </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >HYBRID </behavior >

<fileType >WMA </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >HYBRID </behavior >

<fileType >WMV </fileType >

<securityRiskFileType >false </securityRiskFileType >

FileUploadAndDownloadSecuritySettings

587

Metadata Types ForecastingSettings

</dispositions >

<dispositions >

<behavior >DOWNLOAD </behavior >

<fileType >XHTML </fileType >

<securityRiskFileType >true </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >HYBRID </behavior >

<fileType >EXCEL </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >HYBRID </behavior >

<fileType >EXCEL_X </fileType >

<securityRiskFileType >false </securityRiskFileType >

</dispositions >

<dispositions >

<behavior >DOWNLOAD </behavior >

<fileType >XML </fileType >

<securityRiskFileType >true </securityRiskFileType >

</dispositions >

<noHtmlUploadAsAttachment >false </noHtmlUploadAsAttachment >

</FileUploadAndDownloadSecuritySettings >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >FileUploadAndDownloadSecurity </members >

<name >Settings </name >

</types >

<version >39.0

</version >

</Package >

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

displayCurrency enableForecasts

Field Type

DisplayCurrency

(

enumeration of

type string) boolean

Description

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

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

active adjustmentsSettings forecastRangeSettings name

Field Type

boolean

Description

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 This enables or disables the Forecasts adjustments option in Forecasts.

ForecastRangeSettings The default periods and range selections in Collaborative Forecasts.

string The name of the forecast type. Each forecast type requires a specific string.

Valid values include:

589

Metadata Types ForecastingSettings

Field Name 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

SelectedSettings

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.

opportunityListFields

UnselectedSettings quotasSettings

OpportunityListFields

UnselectedSettings

The fields not selected to appear in the opportunity pane of the forecast page for the forecast type.

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

Field Name

isAmount isAvailable isQuantity displayedCategoryApiNames managerAdjustableCategoryApiNames

Field Type

boolean boolean boolean string string

ForecastingSettings

Description

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

.

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.

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

.

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

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

masterLabel ownerAdjustableCategoryApiNames

Field Type

string string

ForecastingSettings

Description

•

commitonly

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

enableAdjustments

Field Type

boolean enableOwnerAdjustments boolean

Description

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.

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

beginning displaying periodType

Field Type

int int

PeriodTypes (

enumeration of

type string)

Description

Indicates the beginning month or quarter to display by default.

Indicates the number of months or quarters to display by default.

The maximum number of months is 12 and quarters is 8.

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 label

Field Type

string string

Description

The API name of the Opportunity field.

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

Field Type

string

Description

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

Field Type

string

Description

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

showQuotas

Field Type

boolean

Description

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

forecastingItemCategoryApiName

Field Type

string

Description

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

sourceCategoryApiName

Field Type

string weight double

Description

Specifies the API name of a forecast category to include in the rollup type. The valid values are.

•

pipeline

•

best case

•

commit

•

closed

•

omitted

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:

<?xml

version= "1.0" encoding= "UTF-8"?>

<ForecastingSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<enableForecasts >true </enableForecasts >

<forecastingTypeSettings >

<active >true </active >

<adjustmentsSettings >

<enableAdjustments >true </enableAdjustments >

</adjustmentsSettings >

<name >OpportunityRevenue </name >

<forecastRangeSettings >

<beginning >0 </beginning >

<displaying >6 </displaying >

<periodType >Month </periodType >

</forecastRangeSettings >

<opportunityListFieldsSelectedSettings >

<field >OPPORTUNITY.NAME

</field >

</opportunityListFieldsSelectedSettings >

<quotasSettings >

<showQuotas >true </showQuotas >

</quotasSettings >

</forecastingTypeSettings >

<forecastingTypeSettings >

<active >false </active >

<adjustmentsSettings >

595

Metadata Types ForecastingSettings

<enableAdjustments >true </enableAdjustments >

</adjustmentsSettings >

<name >OpportunityLineItemQuantity </name >

<forecastRangeSettings >

<beginning >0 </beginning >

<displaying >6 </displaying >

<periodType >Month </periodType >

</forecastRangeSettings >

<opportunityListFieldsSelectedSettings >

<field >OPPORTUNITY.NAME

</field >

</opportunityListFieldsSelectedSettings >

<quotasSettings >

<showQuotas >true </showQuotas >

</quotasSettings >

<displayedCategoryApiNames >pipelineonly </displayedCategoryApiNames >

<displayedCategoryApiNames >bestcaseonly </displayedCategoryApiNames >

<displayedCategoryApiNames >commitonly </displayedCategoryApiNames >

<displayedCategoryApiNames >closedonly </displayedCategoryApiNames >

<forecastedCategoryApiNames >commitonly </forecastedCategoryApiNames >

<forecastedCategoryApiNames >closedonly </forecastedCategoryApiNames >

<forecastedCategoryApiNames >bestcaseonly </forecastedCategoryApiNames >

<forecastedCategoryApiNames >pipelineonly </forecastedCategoryApiNames >

<managerAdjustableCategoryApiNames >commitonly </managerAdjustableCategoryApiNames >

<managerAdjustableCategoryApiNames >bestcaseonly </managerAdjustableCategoryApiNames >

<ownerAdjustableCategoryApiNames >commitonly </ownerAdjustableCategoryApiNames >

<ownerAdjustableCategoryApiNames >bestcaseonly </ownerAdjustableCategoryApiNames >

</forecastingTypeSettings >

<forecastingCategoryMappings >

<forecastingItemCategoryApiName >commitonly </forecastingItemCategoryApiName >

<weightedSourceCategories >

<sourceCategoryApiName >commit </sourceCategoryApiName >

<weight >1.0

</weight >

</weightedSourceCategories >

</forecastingCategoryMappings >

<forecastingCategoryMappings >

<forecastingItemCategoryApiName >closedonly </forecastingItemCategoryApiName >

<weightedSourceCategories >

<sourceCategoryApiName >closed </sourceCategoryApiName >

<weight >1.0

</weight >

</weightedSourceCategories >

</forecastingCategoryMappings >

<forecastingCategoryMappings >

<forecastingItemCategoryApiName >bestcaseforecast </forecastingItemCategoryApiName >

<weightedSourceCategories >

<sourceCategoryApiName >commit </sourceCategoryApiName >

<weight >1.0

</weight >

</weightedSourceCategories >

<weightedSourceCategories >

<sourceCategoryApiName >best case </sourceCategoryApiName >

<weight >1.0

</weight >

</weightedSourceCategories >

596

Metadata Types ForecastingSettings

<weightedSourceCategories >

<sourceCategoryApiName >closed </sourceCategoryApiName >

<weight >1.0

</weight >

</weightedSourceCategories >

</forecastingCategoryMappings >

<forecastingCategoryMappings >

<forecastingItemCategoryApiName >omittedonly </forecastingItemCategoryApiName >

<weightedSourceCategories >

<sourceCategoryApiName >omitted </sourceCategoryApiName >

<weight >1.0

</weight >

</weightedSourceCategories >

</forecastingCategoryMappings >

<forecastingCategoryMappings >

<forecastingItemCategoryApiName >openpipeline </forecastingItemCategoryApiName >

<weightedSourceCategories >

<sourceCategoryApiName >commit </sourceCategoryApiName >

<weight >1.0

</weight >

</weightedSourceCategories >

<weightedSourceCategories >

<sourceCategoryApiName >best case </sourceCategoryApiName >

<weight >1.0

</weight >

</weightedSourceCategories >

<weightedSourceCategories >

<sourceCategoryApiName >pipeline </sourceCategoryApiName >

<weight >1.0

</weight >

</weightedSourceCategories >

</forecastingCategoryMappings >

<forecastingCategoryMappings >

<forecastingItemCategoryApiName >bestcaseonly </forecastingItemCategoryApiName >

<weightedSourceCategories >

<sourceCategoryApiName >best case </sourceCategoryApiName >

<weight >1.0

</weight >

</weightedSourceCategories >

</forecastingCategoryMappings >

<forecastingCategoryMappings >

<forecastingItemCategoryApiName >commitforecast </forecastingItemCategoryApiName >

<weightedSourceCategories >

<sourceCategoryApiName >closed </sourceCategoryApiName >

<weight >1.0

</weight >

</weightedSourceCategories >

<weightedSourceCategories >

<sourceCategoryApiName >commit </sourceCategoryApiName >

<weight >1.0

</weight >

</weightedSourceCategories >

</forecastingCategoryMappings >

<forecastingCategoryMappings >

<forecastingItemCategoryApiName >pipelineonly </forecastingItemCategoryApiName >

<weightedSourceCategories >

<sourceCategoryApiName >pipeline </sourceCategoryApiName >

<weight >1.0

</weight >

597

Metadata Types IdeasSettings

</weightedSourceCategories >

</forecastingCategoryMappings >

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

enableIdeaThemes enableIdeas enableIdeasReputation

Field Type

boolean boolean boolean enableChatterProfile ideasProfilePage boolean string

Description

Indicates whether Idea Themes is enabled ( true

) or not ( false

).

Indicates whether Ideas is enabled ( true

) or not ( false

).

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.

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.

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

halfLife

Field Type

double

Description

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:

<?xml

version= "1.0" encoding= "UTF-8"?>

<IdeasSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<enableIdeaThemes >true </enableIdeaThemes >

<enableIdeas >true </enableIdeas >

<enableIdeasReputation >true </enableIdeasReputation >

<enableChatterProfile >false </enableChatterProfile >

<ideasProfilePage >

name of Visualforce page

</ideasProfilePage >

<halfLife >2.6

</halfLife >

</IdeasSettings >

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

answers

Field Type

KnowledgeAnswerSettings

Description

Represents the metadata used to manage settings for Salesforce Knowledge and Answers.

599

Metadata Types KnowledgeSettings

Field Name

cases defaultLanguage languages enableChatterQuestionKBDeflection enableCreateEditOnArticlesTab enableExternalMediaContent

Field Type

KnowledgeCaseSettings

string

KnowledgeLanguageSettings

boolean boolean boolean

Description

Represents the metadata used to manage settings for Salesforce Knowledge and Cases.

Required. The default language for Salesforce

Knowledge. Use the abbreviation for the language, for example, en_US for United States

English.

A list of languages enabled for Salesforce

Knowledge.

Indicates whether tracking for case deflection via

Chatter is enabled ( true

) or not ( false

).

Indicates whether users can create and edit articles on the articles tab ( true

) or not

( false

).

Indicates whether connecting to external media is enabled ( true

) or not ( false

).

enableKnowledge showArticleSummariesCustomerPortal showArticleSummariesInternalApp boolean boolean boolean

Indicates whetherSalesforce Knowledge is enabled ( true

) or not ( false

).

Indicates whether article summaries appear in the Customer Portal ( true

) or not ( false

).

Indicates whether article summaries appear in the internal knowledge base ( true

) or not

( false

).

showArticleSummariesPartnerPortal showValidationStatusField suggestedArticles boolean boolean

Indicates whether article summaries appear in the partner portal ( true

) or not ( false

).

Indicates whether validation status appears on articles ( true

) or not ( false

).

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

assignTo defaultArticleType

Field Type

string string

Description

Specifies the username an article is assigned to from Answers.

The default article type for articles created from Answers. Uses the API name of the article type.

600

Metadata Types KnowledgeSettings

Field Name

enableArticleCreation

Field Type

boolean

Description

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

name

Field Type

string

Description

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

Field Type

KnowledgeCaseField

[]

Description

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

name

Field Type

string

Description

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

Field Type

KnowledgeWorkOrderField []

Description

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

name

Field Type

string

Description

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

Field Type

KnowledgeWorkOrderLineItemField []

Description

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

caseFields useSuggestedArticlesForCase workOrderFields

Field Type

KnowledgeCaseFieldsSettings

boolean

KnowledgeWorkOrderFieldsSettings

Description

Represents a list of the case fields used to suggest articles for the case.

Indicates whether case content is used to suggest articles for cases (true) or not (false).

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

articlePDFCreationProfile articlePublicSharingSites

Field Type

string

KnowledgeSitesSettings

articlePublicSharingCommunities

KnowledgeSitesSettings

articlePublicSharingSitesChatterAnswers

KnowledgeSitesSettings

Description

The profile used to create a PDF of an article from

Cases.

Represents the metadata used to manage settings for Salesforce Knowledge and Sites.

Represents the metadata used to manage settings for Salesforce Knowledge and Communities.

Represents the metadata used to manage settings for Salesforce Knowledge and Sites with Chatter

Answers.

602

Metadata Types KnowledgeSettings

Field Name

assignTo customizationClass defaultContributionArticleType editor

Field Type

string string string

KnowledgeCaseEditor

(

enumeration

of type string)

Description

Specifies the username an article is assigned to from

Cases.

Specifies the Apex class used for customization.

The default article type for articles created from

Cases.

Indicates the rich text editor type. Valid values are:

•

simple

•

standard enableArticleCreation enableArticlePublicSharingSites useProfileForPDFCreation boolean boolean boolean

Indicates whether users can create articles from

Cases ( true

) or not ( false

). Controls whether other fields on KnowledgeCaseSettings can be set.

Indicates whether articles can be shared via a public site (URL) from Cases ( true

) or not ( false

).

Indicates whether a profile is used to create a PDF of an article from Cases ( true

) or not ( false

).

KnowledgeSitesSettings

Represents the metadata used to manage settings for Salesforce Knowledge and Sites.

Field Name

site

Field Type

string[]

Description

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

language

Field Type

KnowledgeLanguage

Description

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

active

Field Type

boolean

Description

Indicates whether the language is enabled ( true

) or not ( false

).

603

Metadata Types

Field Name

defaultAssignee defaultAssigneeType defaultReviewer defaultReviewerType name

Field Type

string

KnowledgeLanguageLookupValueType

(

enumeration

of type string)

Description

The default assignee for articles in the language.

Indicates the default assignee type. Valid values are:

•

user

•

queue string

KnowledgeLanguageLookupValueType

(

enumeration

of type string)

The default reviewer for articles in the language.

Indicates the default reviewer type. Valid values are:

•

user

•

queue 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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<KnowledgeSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<answers >

<enableArticleCreation >false </enableArticleCreation >

</answers >

<cases >

<articlePDFCreationProfile >partner portal knowledge profile </articlePDFCreationProfile >

<articlePublicSharingSites >

<site >KnowledgeSite </site >

<site >PKB2Site </site >

<site >ChatterAnswersSite </site >

</articlePublicSharingSites >

<articlePublicSharingSitesChatterAnswers >

<site >ChatterAnswersSite </site >

</articlePublicSharingSitesChatterAnswers >

<assignTo >[email protected]

</assignTo >

<defaultContributionArticleType >Support </defaultContributionArticleType >

<editor >simple </editor >

<enableArticleCreation >true </enableArticleCreation >

<enableArticlePublicSharingSites >true </enableArticlePublicSharingSites >

<useProfileForPDFCreation >true </useProfileForPDFCreation >

</cases >

<defaultLanguage >ja </defaultLanguage >

<enableCreateEditOnArticlesTab >true </enableCreateEditOnArticlesTab >

<enableExternalMediaContent >true </enableExternalMediaContent >

<enableKnowledge >true </enableKnowledge >

<showArticleSummariesCustomerPortal >true </showArticleSummariesCustomerPortal >

<showArticleSummariesInternalApp >true </showArticleSummariesInternalApp >

604

KnowledgeSettings

Metadata Types LeadConvertSettings

<showArticleSummariesPartnerPortal >true </showArticleSummariesPartnerPortal >

<showValidationStatusField >true </showValidationStatusField >

<suggestedArticles >

<caseFields >

<field >

<name >Subject </name >

</field >

<field >

<name >SuppliedEmail </name >

</field >

</caseFields >

<useSuggestedArticlesForCase >true </useSuggestedArticlesForCase >

</suggestedArticles >

</KnowledgeSettings >

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

allowOwnerChange

Field Type

boolean objectMapping inputObject mappingFields inputField outputField metadata type string metadata type string string

Description

Indicates whether to include the RecordOwner field in the Convert Lead dialog box ( true

) or not ( false

).

A set of inputObject

, mappingFields

, and outputObject entries. Up to three objectMapping

types can be declared—one each for Account, Contact, and Opportunity.

The name of the object type containing the source fields for mapping.

The value will always be

Lead

.

A set of inputField

and outputField

entries.

The name of a custom lead field supplying source data during lead conversion.

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

Field Name

outputObject

Field Type

string opportunityCreationOptions string

LeadConvertSettings

Description

The name of the object type receiving data during lead conversion—

Account

,

Contact

, or

Opportunity

.

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:

<?xml

version= "1.0" encoding= "UTF-8"?>

<LeadConvertSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<allowOwnerChange >false </allowOwnerChange >

<objectMapping >

<inputObject >Lead </inputObject >

<mappingFields >

<inputField >custom_lead_field_1 </inputField >

<outputField >custom_account_field_1 </outputField >

</mappingFields >

<mappingFields >

<inputField >custom_lead_field_2 </inputField >

<outputField >custom_account_field_2 </outputField >

</mappingFields >

<mappingFields >

<inputField >custom_lead_field_3 </inputField >

<outputField >custom_account_field_3 </outputField >

</mappingFields >

<outputObject >Account </outputObject >

</objectMapping >

<objectMapping >

<inputObject >Lead </inputObject >

<mappingFields >

<inputField >custom_lead_field_4 </inputField >

<outputField >custom_opportunity_field_1 </outputField >

</mappingFields >

<outputObject >Opportunity </outputObject >

</objectMapping >

<opportunityCreationOptions >VisibleOptional </opportunityCreationOptions >

</LeadConvertSettings >

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

enableLiveAgent

Field Type

boolean

Description

Indicates whether Live Agent is enabled ( true

) or not

( false

).

Declarative Metadata Sample Definition

This is a sample Live Agent settings file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<LiveAgentSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<enableLiveAgent >true </enableLiveAgent >

</LiveAgentSettings >

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

Fields

Field

chatterMobile

(Deprecated) dashboardMobile

(Deprecated) salesforceMobile touchMobile

(Deprecated)

Field Type

ChatterMobileSettings

DashboardMobileSettings

SFDCMobileSettings

TouchMobileSettings

MobileSettings

Description

The settings for devices running Chatter mobile.

The settings for devices running the mobile dashboards app.

The settings for devices running Salesforce

Classic Mobile.

The settings for devices running Salesforce

Touch.

ChatterMobileSettings

These fields are deprecated. Represents your organization’s Chatter Mobile settings.

Field

IPadAuthorized

Field Type

boolean

IPhoneAuthorized boolean androidAuthorized blackBerryAuthorized enableChatterMobile enablePushNotifications boolean boolean boolean boolean

Description

Indicates whether iPad devices are enabled for Chatter Mobile ( true

) or not ( false

).

Indicates whether iPhone devices are enabled for Chatter Mobile ( true

) or not

( false

).

Indicates whether Android devices are enabled for Chatter Mobile ( true

) or not

( false

).

Indicates whether Blackberry devices are enabled for Chatter Mobile ( true

) or not

( false

).

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.

Indicates whether Chatter push notifications have been enabled for your organization

( true

) or not ( false

)

608

Metadata Types

Field

sessionTimeout

MobileSettings

Field Type Description

MobileSessionTimeout (

enumeration

of type string)

The length of time after which users without 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

enableDashboardIPadApp

Field Type

boolean

Description

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

enableUserToDeviceLinking

Field Type

boolean enableMobileLite boolean

Description

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..

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

enableTouchBrowserIPad enableTouchAppIPad

Field Type

boolean boolean

Description

Indicates whether your organization has the

Salesforce Touch mobile browser app enabled ( true

) or not ( false

).

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<MobileSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<chatterMobile >

<IPadAuthorized >true </IPadAuthorized >

<IPhoneAuthorized >true </IPhoneAuthorized >

<androidAuthorized >true </androidAuthorized >

<blackBerryAuthorized >true </blackBerryAuthorized >

<enableChatterMobile >true </enableChatterMobile >

<enablePushNotifications >true </enablePushNotifications >

<sessionTimeout >Never </sessionTimeout >

</chatterMobile >

<dashboardMobile >

<enableDashboardIPadApp >true </enableDashboardIPadApp >

</dashboardMobile >

<salesforceMobile >

<enableUserToDeviceLinking >false </enableUserToDeviceLinking >

<enableMobileLite >false </enableMobileLite >

</salesforceMobile >

<touchMobile >

<enableTouchBrowserIPad >false </enableTouchBrowserIPad >

<enableTouchAppIPad >true </enableTouchAppIPad >

</touchMobile >

</MobileSettings >

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

enableMiddleName enableNameSuffix

Field Type

boolean boolean

Description

Indicates whether middle names are enabled ( true

) or disabled

( false

) for person objects.

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<NameSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<enableMiddleName >true </enableMiddleName >

<enableNameSuffix >false </enableNameSuffix >

</NameSettings >

The following is an example package.xml

manifest that references the NameSettings definitions.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Name </members >

<name >Settings </name >

</types >

<version >31.0

</version >

</Package >

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

Fields

Field Name

enableUpdateReminders

Field Type

boolean autoActivateNewReminders boolean enableFindSimilarOpportunities boolean findSimilarOppFilter enableOpportunityTeam promptToAddProducts multipicklist boolean boolean

OpportunitySettings

Description

Lets users enable automatic, scheduled updates on opportunities.

Automatically uses scheduled updates for new opportunities.

Lets users see related or similar existing opportunities.

Defines parameters for similar opportunities.

Lets users associate team members with opportunities.

Prompts users to add related products to an opportunity.

FindSimilarOppFilter

Defines whether to match by entire columns or fields.

Field Field Type

similarOpportunitiesDisplayColumns string similarOpportunitiesMatchFields string

Description

The columns to compare.

The fields to compare.

Declarative Metadata Sample Definition

The following is an example of the package file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Opportunity </members >

<name >Settings </name >

</types >

<version >28.0

</version >

</Package >

The package file references the following Opportunity.settings file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<OpportunitySettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<autoActivateNewReminders >true </autoActivateNewReminders >

<enableFindSimilarOpportunities >true </enableFindSimilarOpportunities >

<findSimilarOppFilter >

<similarOpportunitiesMatchFields >OPPORTUNITY.Account

</similarOpportunitiesMatchFields >

<similarOpportunitiesMatchFields >OPPORTUNITY.OpportunityCompetitors

</similarOpportunitiesMatchFields >

<similarOpportunitiesMatchFields >CustomField__c </similarOpportunitiesMatchFields >

612

Metadata Types OrderSettings

<similarOpportunitiesDisplayColumns >CustomField__c </similarOpportunitiesDisplayColumns >

</findSimilarOppFilter >

<enableOpportunityTeam >true </enableOpportunityTeam >

<enableUpdateReminders >true </enableUpdateReminders >

<promptToAddProducts >false </promptToAddProducts >

</OpportunitySettings >

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

enableNegativeQuantity

Field Type

boolean enableOrders enableReductionOrders boolean boolean

Description

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

.

Indicates whether orders are enabled for the organization ( true

) or not ( false

).

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<OrderSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<enableOrders >true </enableOrders >

<enableReductionOrders >false </enableReductionOrders >

613

Metadata Types OrgPreferenceSettings

<enableNegativeQuantity >true </enableNegativeQuantity >

</OrderSettings >

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Order </members >

<name >Settings </name >

</types >

<version >30.0

</version >

</Package >

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

preferences

Field Type Description

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

OrganizationSettingsDetail

Field Name

settingName setttingValue

Field Type

string boolean

OrgPreferenceSettings

Description

The name of the setting. For example,

“S1EncryptedStoragePref2.”

Indicates whether the setting is enabled

( true

) or not ( false

).

Declarative Metadata Sample Definition

The following is an example of a OrgPreferenceSettings component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<OrgPreferenceSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<preferences >

<settingName >EventLogWaveIntegEnabled </settingName >

<settingValue >true </settingValue >

</preferences >

<preferences >

<settingName >SendThroughGmailPref </settingName >

<settingValue >false </settingValue >

</preferences >

<preferences >

<settingName >LoginForensicsEnabled </settingName >

<settingValue >false </settingValue >

</preferences >

<preferences >

<settingName >EnhancedEmailEnabled </settingName >

<settingValue >true </settingValue >

</preferences >

<preferences >

<settingName >NotesReservedPref01 </settingName >

<settingValue >false </settingValue >

</preferences >

<preferences >

<settingName >S1OfflinePref </settingName >

<settingValue >true </settingValue >

</preferences >

<preferences >

<settingName >S1EncryptedStoragePref2 </settingName >

<settingValue >true </settingValue >

</preferences >

<preferences >

<settingName >OfflineDraftsEnabled </settingName >

<settingValue >false </settingValue >

</preferences >

<preferences >

<settingName >ChatterEnabled </settingName >

<settingValue >true </settingValue >

</preferences >

<preferences >

615

Metadata Types PathAssistantSettings

<settingName >SocialProfilesEnable </settingName >

<settingValue >true </settingValue >

</preferences >

<preferences >

<settingName >PathAssistantsEnabled </settingName >

<settingValue >false </settingValue >

</preferences >

<preferences >

<settingName >S1DesktopEnabled </settingName >

<settingValue >true </settingValue >

</preferences >

<preferences >

<settingName >VoiceEnabled </settingName >

<settingValue >false </settingValue >

</preferences >

</OrgPreferenceSettings >

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

pathAssistantForOpportunityEnabled boolean pathAssistantEnabled boolean

Description

Determines whether the preference is enabled for Path in Opportunity or not. Available in API version 34.0 only.

Determines whether the preference is enabled for Path or not. Available in API version 35.0 and later.

Declarative Metadata Sample Definition

The following is an example of a PathAssistantSettings component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<PathAssistantSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<pathAssistantEnabled >true </pathAssistantEnabled >

</PathAssistantSettings >

616

Metadata Types PersonalJourneySettings

The following is an example package.xml

that references the previous definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >PathAssistant </members >

<name >Settings </name >

</types >

<version >API </version >

</Package

PersonalJourneySettings

Represents an organization’s Adoption Manager setting, which enables or disables the Adoption Manager tool. 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 on page 557 for

more details.

File Suffix and Directory Location

PersonalJourneySettings values are stored in the

PersonalJourney.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

PersonalJourneySettings components are available in API version 39.0 and later.

Special Access Rules

Adoption Manager must be enabled in your organization.

Fields

Field Name Field Type

enableExactTargetForSalesforceApps boolean

Description

Enables use of Adoption Manager, a tool that helps drive adoption of the Salesforce1 mobile app and the Lightning Experience. For more information, see Salesforce Adoption Manager in the Salesforce help.

ProductSettings

Represents organization preferences for quantity schedules, revenue schedules, and active flag interaction with prices. This type extends the

Metadata

metadata type and inherits its fullName

field.

617

Metadata Types QuoteSettings

File Suffix and Directory Location

ProductSettings values are stored in a single file named

Product.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

ProductSettings is available in API version 28.0 and later.

Fields

Field Name Field Type

enableCascadeActivateToRelatedPrices boolean enableQuantitySchedule enableRevenueSchedule boolean boolean

Description

When changing active flag on a product record, automatically updates active flag on related prices.

Enables quantity schedules for products.

Enables revenue schedules for products.

Declarative Metadata Sample Definition

The following is an example of the package file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Product </members >

<name >Settings </name >

</types >

<version >28.0

</version >

</Package >

The package file references the following Product.settings file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<ProductSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<enableCascadeActivateToRelatedPrices >true </enableCascadeActivateToRelatedPrices >

<enableQuantitySchedule >false </enableQuantitySchedule >

<enableRevenueSchedule >false </enableRevenueSchedule >

</ProductSettings >

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

enableQuote

Field Type

boolean

Description

When set to true

, users can access Quotes.

Declarative Metadata Sample Definition

The following is an example of the package file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Quote </members >

<name >Settings </name >

</types >

<version >28.0

</version >

</Package >

The package file references the following Quote.settings file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<QuoteSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<enableQuote >true </enableQuote >

</QuoteSettings >

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

documentContentSearchEnabled optimizeSearchForCJKEnabled

Field Type

boolean boolean recentlyViewedUsersForBlankLookupEnabled searchSettingsByObject 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

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

Description

Indicates if a full-text document search is performed.

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.

sidebarLimitToItemsIOwnCheckboxEnabled singleSearchResultShortcutEnabled spellCorrectKnowledgeSearchEnabled boolean boolean 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.

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.

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.

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

searchSettingsByObject

Field Type Description

ObjectSearchSetting

Contains a list of search settings for each object.

ObjectSearchSetting

A list of search settings for each object.

Field Name

enhancedLookupEnabled

Field Type

boolean lookupAutoCompleteEnabled boolean name resultsPerPageCount string int

Description

Indicates if enhanced lookups is enabled for the object.

Indicates if autocomplete is enabled for lookup search. Autocomplete is when users edit the lookup field inline by choosing an autosuggestion.

The entity name of the object being configured.

The number of search results per page.

Declarative Metadata Sample Definition

The following is an example of the

Search.settings

file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<SearchSettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<documentContentSearchEnabled >true </documentContentSearchEnabled >

<optimizeSearchForCJKEnabled >true </optimizeSearchForCJKEnabled >

<recentlyViewedUsersForBlankLookupEnabled >true </recentlyViewedUsersForBlankLookupEnabled >

<searchSettingsByObject >

<searchSettingsByObject >

<enhancedLookupEnabled >false </enhancedLookupEnabled >

<lookupAutoCompleteEnabled >false </lookupAutoCompleteEnabled >

<name >Account </name >

<resultsPerPageCount >25 </resultsPerPageCount >

</searchSettingsByObject >

<searchSettingsByObject >

<enhancedLookupEnabled >false </enhancedLookupEnabled >

<lookupAutoCompleteEnabled >false </lookupAutoCompleteEnabled >

<name >Activity </name >

<resultsPerPageCount >25 </resultsPerPageCount >

</searchSettingsByObject >

<searchSettingsByObject >

<enhancedLookupEnabled >false </enhancedLookupEnabled >

<lookupAutoCompleteEnabled >false </lookupAutoCompleteEnabled >

<name >Asset </name >

<resultsPerPageCount >25 </resultsPerPageCount >

</searchSettingsByObject >

</searchSettingsByObject >

<sidebarAutoCompleteEnabled >true </sidebarAutoCompleteEnabled >

<sidebarDropDownListEnabled >true </sidebarDropDownListEnabled >

<sidebarLimitToItemsIOwnCheckboxEnabled >true </sidebarLimitToItemsIOwnCheckboxEnabled >

621

Metadata Types

<singleSearchResultShortcutEnabled >true </singleSearchResultShortcutEnabled >

<spellCorrectKnowledgeSearchEnabled >true </spellCorrectKnowledgeSearchEnabled >

</SearchSettings >

SecuritySettings

Example Package Manifest

The following is an example package manifest used to deploy or retrieve the Account settings metadata for an organization.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Search </members >

<name >Settings </name >

</types >

<version >37.0

</version >

</Package >

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

networkAccess

Field Type

NetworkAccess

passwordPolicies sessionSettings

PasswordPolicies

SessionSettings

Description

The trusted IP address ranges from which users can always log in without requiring computer activation.

The requirements for passwords and logins, and assistance with retrieving forgotten passwords.

The settings for session expiration and security.

622

Metadata Types SecuritySettings

NetworkAccess

Represents your organization’s trusted IP address ranges for network access.

Field

ipRanges

Field Type

IpRange

[]

Description

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

(<networkAccess></networkAccess>).

IpRange

Defines a range of trusted IP addresses for network access.

Field

description end start

Field Type

string string string

Description

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.

The IP address that defines the high end of a range of trusted addresses.

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

apiOnlyUserHomePageURL string complexity

Complexity ( enumeration

of type string)

Description

The URL to which users with the “API Only User” permission are redirected instead of the login page.

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 SecuritySettings

Field 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 maxLoginAttempts

Expiration (

enumeration of type

string)

Required. The length of time until user passwords expire and must be changed. Valid values are:

•

Never

•

ThirtyDays

•

SixtyDays

•

NinetyDays

. This value is the default value.

•

SixMonths

•

OneYear minimumPasswordLifetime passwordAssistanceURL string passwordAssistanceMessage string historyRestriction lockoutInterval boolean string

LockoutInterval (

enumeration

of type string)

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.

The URL that users can click to retrieve forgotten passwords.

The text that appears in the Account Lockout email and at the bottom of the Confirm Identity screen for users resetting their passwords.

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

.

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

( 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 SecuritySettings

Field Field Type Description

•

TenAttempts

. This value is the default value.

minimumPasswordLength obscureSecretAnswer questionRestriction string boolean

QuestionRestriction

( enumeration

of type 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).

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.

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

disableTimeoutWarning

Field Type

boolean enableCSPOnEmail enableCSRFOnGet boolean boolean

Description

Indicates whether the session timeout warning popup is disabled ( true

) or enabled ( false

).

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.

Indicates whether Cross-Site Request Forgery (CSRF) protection on GET requests on non-setup pages is enabled ( true

) or disabled ( false

).

625

Metadata Types

Field

enableCSRFOnPost

Field Type

boolean enableCacheAndAutocomplete boolean enableClickjackNonsetupSFDC boolean enableClickjackNonsetupUser boolean enableClickjackNonsetupUserHeaderless boolean enableClickjackSetup boolean enablePostForSessions boolean enableSMSIdentity enforceIpRangesEveryRequest boolean forceLogoutOnSessionTimeout forceRelogin boolean boolean boolean lockSessionsToDomain boolean

626

SecuritySettings

Description

Indicates whether Cross-Site Request Forgery (CSRF) protection on POST requests on non-setup pages is enabled ( true

) or disabled ( false

).

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

).

Indicates whether clickjack protection for non-setup Salesforce pages is enabled ( true

) or disabled ( false

).

Indicates whether clickjack protection for customer Visualforce pages with standard headers turned on is enabled ( true

) or disabled ( false

).

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.

Indicates whether clickjack protection for setup pages is enabled

( true

) or disabled ( false

).

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.

Indicates whether users can receive a one-time PIN delivered via SMS ( true

) or not ( false

).

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.

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.

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.

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

Metadata Types

Field

lockSessionsToIp logoutURL sessionTimeout

SecuritySettings

Field Type

boolean string

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.

Indicates whether user sessions are locked to the IP address from which the user logged in ( true

) or not ( false

).

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 ( 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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<SecuritySettings xmlns= "http://soap.sforce.com/2006/04/metadata">

<networkAccess >

<ipRanges >

<end >127.0.0.1

</end >

<start >127.0.0.1

</start >

</ipRanges >

</networkAccess >

<passwordPolicies >

<apiOnlyUserHomePageURL >http://www.altPage.com

</apiOnlyUserHomePageURL >

<complexity >SpecialCharacters </complexity >

<expiration >OneYear </expiration >

<passwordAssistanceURL >http://www.acme.com/forgotpassword </passwordAssistanceURL >

<passwordAssistanceMessage >Forgot your password? Reset it here.

</passwordAssistanceMessage >

<historyRestriction >3 </historyRestriction >

<lockoutInterval >ThirtyMinutes </lockoutInterval >

<maxLoginAttempts >ThreeAttempts </maxLoginAttempts >

<minimumPasswordLength >10 </minPasswordLength >

627

Metadata Types Territory2Settings

<questionRestriction >None </questionRestriction >

</passwordPolicies >

<sessionSettings >

<disableTimeoutWarning >true </disableTimeoutWarning >

<enableCSRFOnGet >false </enableCSRFOnGet >

<enableCSRFOnPost >false </enableCSRFOnPost >

<enableCacheAndAutocomplete >false </enableCacheAndAutocomplete >

<enableClickjackNonsetupSFDC >true </enableClickjackNonsetupSFDC >

<enableClickjackNonsetupUser >true </enableClickjackNonsetupUser >

<enableClickjackSetup >true </enableClickjackSetup >

<enableSMSIdentity >true </enableSMSIdentity >

<forceRelogin >true </forceRelogin >

<lockSessionsToIp >true </lockSessionsToIp >

<sessionTimeout >TwelveHours </sessionTimeout >

</sessionSettings >

</SecuritySettings >

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

Fields

Field Name Field Type

defaultAccountAccessLevel string defaultCaseAccessLevel string defaultContactAccessLevel string defaultOpportunityAccessLevel string

SharedTo

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.

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.

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Territory2Settings xmlns= "http://soap.sforce.com/2006/04/metadata">

<defaultAccountAccessLevel >Owner </defaultAccountAccessLevel >

<defaultOpportunityAccessLevel >Read </defaultOpportunityAccessLevel >

<defaultCaseAccessLevel >None </defaultCaseAccessLevel >

<defaultContactAccessLevel >Edit </defaultContactAccessLevel >

</Territory2Settings >

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

Fields

Field Field Type

allCustomerPortalUsers string allInternalUsers allPartnerUsers group string string string[] groups string[] managerSubordinates managers portalRole string[] string[] string[] portalRoleandSubordinates string[] role string[] roleAndSubordinates string[]

630

SharedTo

Description

A group containing all customer portal users.

This field is available in API version 24.0 and later.

A group containing all internal and nonportal users.

This field is available in API version 24.0 and later.

A group containing all partner users.

This field is available in API version 24.0 and later.

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.

A list of groups with sharing access.

Use the group

field instead for API version 22.0 and later.

A list of users whose direct and indirect subordinates receive sharing access. This field is available in API version 24.0 and later.

A list of users whose direct and indirect managers receive sharing access. This field is available in API version 24.0 and later.

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.

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.

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.

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.

Metadata Types

Field Field Type

roleAndSubordinatesInternal string[] roles string[] rolesAndSubordinates string[] territories territoriesAndSubordinates string[] territory territoryAndSubordinates string[] queue string[] string[] string[]

SharingBaseRule

Description

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.

A list of roles with sharing access.

Use the role

field instead for API version 22.0 and later.

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.

A list of territories with sharing access.

Use the territory

field instead for API version 22.0 and later.

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.

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.

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.

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

accessLevel

Field Type

string accountSettings description label sharedTo

AccountSharingRuleSettings []

string string

SharedTo

Description

Required. The access level that the sharing rule grants.

The access level for the account’s children (case, contact, and opportunity).

Describes the sharing rule. Maximum of 1000 characters.

Required. Label for the sharing rule.

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

caseAccessLevel

Field Type

string contactAccessLevel string

Description

Required. The access level that the user or group has to cases associated with the account.

Possible values are:

•

None

•

Read

•

Edit

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 Field Type

opportunityAccessLevel string

SharingRules

Description

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 SharingRules

Field Field Type

sharingCriteriaRules

SharingCriteriaRule []

sharingOwnerRules

SharingOwnerRule

[] sharingTerritoryRules

SharingTerritoryRule []

Description

An array of criteria-based sharing rules. Available in API version 33.0 and later.

An array of ownership-based sharing rules. Available in

API version 33.0 and later.

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

booleanFilter criteriaItems

Field Type

string

FilterItem []

Description

Advanced filter conditions that are specified for the sharing rule.

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

sharedFrom

Field Type

SharedTo

Description

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

criteriaBasedRules ownerRules

Field Type

AccountCriteriaBasedSharingRule []

AccountOwnerSharingRule []

Description

List that defines user criteria-based rules.

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

criteriaBasedRules ownerRules

Field Type

CampaignCriteriaBasedSharingRule

[]

CampaignOwnerSharingRule

[]

Description

List that defines user criteria-based rules.

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

criteriaBasedRules ownerRules

Field Type

CaseCriteriaBasedSharingRule

[]

CaseOwnerSharingRule

[]

Description

List that defines user criteria-based rules.

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

criteriaBasedRules ownerRules

Field Type

ContactCriteriaBasedSharingRule

[]

ContactOwnerSharingRule

[]

Description

List that defines user criteria-based rules.

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

criteriaBasedRules ownerRules

Field Type

LeadCriteriaBasedSharingRule

[]

LeadOwnerSharingRule

[]

Description

List that defines user criteria-based rules.

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

criteriaBasedRules ownerRules

Field Type

OpportunityCriteriaBasedSharingRule []

OpportunityOwnerSharingRule []

Description

List that defines user criteria-based rules.

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

rules

Field Type

AccountTerritorySharingRule []

Description

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

criteriaBasedRules ownerRules

Field Type

CustomObjectOwnerSharingRule []

Description

CustomObjectCriteriaBasedSharingRule []

List that defines user criteria-based rules.

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

criteriaBasedRules membershipRules

Field Type

UserCriteriaBasedSharingRule

[]

UserMembershipSharingRule []

Description

List that defines user criteria-based rules.

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<SharingRules xmlns= "http://soap.sforce.com/2006/04/metadata">

636

Metadata Types

<sharingCriteriaRules >

<fullName >AccountCriteriaShareWithCEO </fullName >

<accessLevel >Edit </accessLevel >

<accountSettings >

<caseAccessLevel >Read </caseAccessLevel >

<contactAccessLevel >Edit </contactAccessLevel >

<opportunityAccessLevel >Edit </opportunityAccessLevel >

</accountSettings >

<criteriaItems >

<field >Name </field >

<operation >startsWith </operation >

<value >Test </value >

</criteriaItems >

<description >my account criteria rule description </description >

<label >AccountCriteriaShareWithCEO </label >

<sharedTo >

<role >CEO </role >

</sharedTo >

</sharingCriteriaRules >

</SharingRules >

The following sample XML definition represents an ownership-based sharing rule in API version 33.0.

<?xml

version= "1.0" encoding= "UTF-8"?>

<SharingRules xmlns= "http://soap.sforce.com/2006/04/metadata">

<sharingOwnerRules >

<fullName >MyCase </fullName >

<accessLevel >Edit </accessLevel >

<description >my case test owner sharing rule desc </description >

<label >MyCase </label >

<sharedFrom >

<role >COO </role >

</sharedFrom >

<sharedTo >

<role >CEO </role >

</sharedTo >

</sharingOwnerRules >

</SharingRules >

The following sample XML definition represents a territory-based sharing rule in API version 33.0.

<?xml

version= "1.0" encoding= "UTF-8"?>

<SharingRules xmlns= "http://soap.sforce.com/2006/04/metadata">

<sharingTerritoryRules >

<fullName >MyAccountTerritoryRule </fullName >

<accessLevel >Read </accessLevel >

<accountSettings >

<caseAccessLevel >None </caseAccessLevel >

<contactAccessLevel >Read </contactAccessLevel >

<opportunityAccessLevel >None </opportunityAccessLevel >

</accountSettings >

<description >MyAccountTerritoryRule desc </description >

<label >MyAccountTerritoryRule </label >

<sharedFrom >

<territory >My_territory </territory >

637

SharingRules

Metadata Types SharingRules

</sharedFrom >

<sharedTo >

<role >CEO </role >

</sharedTo >

</sharingTerritoryRules >

</SharingRules >

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 .

<?xml

version= "1.0" encoding= "UTF-8"?>

<AccountSharingRules xmlns= "http://soap.sforce.com/2006/04/metadata">

<ownerRules >

<fullName >G1Dev_G2New </fullName >

<sharedFrom >

<group >G1Dev </group >

</sharedFrom >

<sharedTo >

<group >G2New </group >

</sharedTo >

<accountAccessLevel >Read </caseAccessLevel >

<caseAccessLevel >None </caseAccessLevel >

<contactAccessLevel >Read </contactAccessLevel >

<name >G1Dev_G2New </name >

<opportunityAccessLevel >Edit </opportunityAccessLevel >

</ownerRules >

<ownerRules >

<fullName >G2New_R1New </fullName >

<sharedFrom >

<group >G2New </group >

</sharedFrom >

<sharedTo >

<roleAndSubordinates >R1New </roleAndSubordinates >

</sharedTo >

<accountAccessLevel >Edit </accountAccessLevel >

<caseAccessLevel >Read </caseAccessLevel >

<contactAccessLevel >Edit </contactAccessLevel >

<name >G2New_R1New </name >

<opportunityAccessLevel >None </opportunityAccessLevel >

</ownerRules >

</AccountSharingRules >

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<UserSharingRules xmlns= "http://soap.sforce.com/2006/04/metadata">

<criteriaBasedRules >

<fullName >shareUsers2 </fullName >

<sharedTo >

<group >Asia_Division </group >

</sharedTo >

<criteriaItems >

<field >FirstName </field >

638

Metadata Types BaseSharingRule

<operation >equals </operation >

<value >John </value >

</criteriaItems >

<name >shareUsers2 </name >

<userAccessLevel >Read </userAccessLevel >

</criteriaBasedRules >

<membershipRules >

<fullName >shareUsers1 </fullName >

<sharedTo >

<group >South_America_Division </group >

</sharedTo >

<sharedFrom >

<group >Asia_Division </group >

</sharedFrom >

<name >shareUsers1 </name >

<userAccessLevel >Read </userAccessLevel >

</membershipRules >

</UserSharingRules >

The following shows a sample package.xml

file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >ObjA__c.* </members >

<name >SharingCriteriaRule </name >

</types >

<types >

<members >ObjA__c.* </members >

<name >SharingOwnerRule </name >

</types >

<version >39.0

</version >

</Package >

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

sharedTo fullName

Field Type

SharedTo

string

Description

Required. Specifies who the record should be shared with.

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.

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.

Field

criteriaItems

Field Type

FilterItem[]

Description

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

accountAccessLevel booleanFilter caseAccessLevel

Field Type Description

ShareAccessLevelNoNone

( enumeration

of type string)

Required. A value that represents the level of access that the user or group has to the account. The possible values are:

•

Read

•

Edit

•

All string Represents the filter logic of the sharing rule.

ShareAccessLevelNoAll

( enumeration

of type string)

Required. A value that represents the level of access that the user or group has to cases associated with the account. The possible values are:

•

None

•

Read

•

Edit contactAccessLevel description

ShareAccessLevelNoAll

( enumeration

of type string)

Required. A value that represents the level of access that the user or group has to contacts associated with the account. The possible values are:

•

None

•

Read

•

Edit 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

( enumeration

of type string)

Required. A value that represents the level of access that a target 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

booleanFilter description campaignAccessLevel name

Field Type

string string

Description

Represents the filter logic of the sharing rule.

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

ShareAccessLevelNoNone

( enumeration

of type string)

Required. A value that represents the level of access that a target group is granted for a campaign. The possible values are:

•

Read

•

Edit

•

All 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

booleanFilter description caseAccessLevel name

Field Type

string string

Description

Represents the filter logic of the sharing rule.

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

ShareAccessLevelReadEdit

( enumeration

of type string)

Required. A value that represents the level of access being granted for a case. The possible values are:

•

Read

•

Edit 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

booleanFilter description contactAccessLevel name

Field Type

string string

Description

Represents the filter logic of the sharing rule.

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

ShareAccessLevelReadEdit

( enumeration

of type string)

Required. A value that represents the level of access being granted to the target group, role, or user for a contact. The possible values are:

•

Read

•

Edit 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

booleanFilter description leadAccessLevel name

Field Type

string string

Description

Represents the filter logic of the sharing rule.

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

ShareAccessLevelReadEdit

( enumeration

of type string)

Required. A value that represents the level of allowed access.

The possible values are:

•

Read

•

Edit 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

booleanFilter description

Field Type

string string

Description

Represents the filter logic of the sharing rule.

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

opportunityAccessLevel ShareAccessLevelReadEdit

( enumeration

of type string)

Required. A value that represents the level of allowed access.

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

accessLevel

Field Type

string booleanFilter description name string string string

Description

Required. A value that represents the type of allowed sharing.

The possible values are:

•

Read

•

Edit

•

All

Represents the filter logic of the sharing rule.

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

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

Field

booleanFilter description name userAccessLevel

CriteriaBasedSharingRule

Field Type

string string

Description

Represents the filter logic of the sharing rule.

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

string Required. Name for the sharing rule. Corresponds to Label in the user interface.

ShareAccessLevelReadEdit

(

enumeration of type string)

Required. A value that represents the type of allowed sharing.

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<AccountSharingRules xmlns= "http://soap.sforce.com/2006/04/metadata">

<ownerRules >

<fullName >G1Dev_G2New </fullName >

<sharedTo >

<group >G2New </group >

</sharedTo >

<sharedFrom >

<group >G1Dev </group >

</sharedFrom >

<accountAccessLevel >Read </accountAccessLevel >

<caseAccessLevel >None </caseAccessLevel >

<contactAccessLevel >Read </contactAccessLevel >

</ownerRules >

<fullName >G2New_R1New </fullName >

<sharedTo >

<roleAndSubordinates >R1New </roleAndSubordinates >

</sharedTo >

<sharedFrom >

<group >G2New </group >

</sharedFrom >

<accountAccessLevel >Edit </accountAccessLevel >

<caseAccessLevel >Read </caseAccessLevel >

<contactAccessLevel >Edit </contactAccessLevel >

<name >G2New_R1New </name >

<opportunityAccessLevel >None </opportunityAccessLevel >

</ownerRules >

<criteriaBasedRules >

<fullName >AccountCriteria </fullName >

<sharedTo >

<group >G1 </group >

645

Metadata Types OwnerSharingRule

</sharedTo >

<criteriaItems >

<field >BillingCity </field >

<operation >equals </operation >

<value >San Francisco </value >

</criteriaItems >

<criteriaItems >

<field >MyChkBox__c </field >

<operation >notEqual </operation >

<value >False </value >

</criteriaItems >

<accountAccessLevel >Read </accountAccessLevel >

<booleanFilter >1 OR 2 </booleanFilter >

<caseAccessLevel >None </caseAccessLevel >

<contactAccessLevel >Read </contactAccessLevel >

<name >AccountCriteria </name >

<opportunityAccessLevel >None </opportunityAccessLevel >

</criteriaBasedRules >

</AccountSharingRules >

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.

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.

Field

sharedFrom sharedTo fullName

Field Type

SharedTo

SharedTo

string

Description

Required. Specifies the record owners.

Required. Specifies who the record should be shared with.

The unique identifier for API access. The fullName

can contain only underscores and

646

Metadata Types OwnerSharingRule

Field 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

accountAccessLevel caseAccessLevel contactAccessLevel description name

Field Type Description

ShareAccessLevelNoNone

( enumeration

of type string)

Required. A value that represents the level of access that a group or role has to the account. The possible values are:

•

Read

•

Edit

•

All

ShareAccessLevelNoAll

( enumeration

of type string)

Required. A value that represents the level of access that a group or role has to cases associated with the account. The possible values are:

•

None

•

Read

•

Edit

ShareAccessLevelNoAll

( enumeration

of type string)

Required. A value that represents the level of access that a group or role has to contacts associated with the account. The possible values are:

•

None

•

Read

•

Edit string string

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

Required. Name for the sharing rule. Corresponds to Label in the user interface.

647

Metadata Types OwnerSharingRule

Field Field Type Description

opportunityAccessLevel ShareAccessLevelNoAll

( enumeration

of type string)

Required. A value that represents the level of access that a group 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

campaignAccessLevel description name

Field Type Description

ShareAccessLevelNoNone

( enumeration

of type string)

A value that represents the level of access that a group or role is granted for a campaign. The possible values are:

•

Read

•

Edit

•

All string string

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

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

caseAccessLevel

Field Type Description

ShareAccessLevelReadEdit

( enumeration

of type string)

Required. A value that represents the level of access that a group or role is granted for a case. The possible values are:

•

Read

•

Edit

648

Metadata Types OwnerSharingRule

Field

description name

Field Type

string string

Description

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

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

contactAccessLevel description name

Field Type Description

ShareAccessLevelReadEdit

( enumeration

of type string)

Required. A value that represents the level of access that a group or role is granted for a contact. The possible values are:

•

Read

•

Edit string string

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

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

leadAccessLevel description

Field Type Description

ShareAccessLevelReadEdit

( enumeration

of type string)

Required. A value that represents the level of access that a group or role is granted for a lead. The possible values are:

•

Read

•

Edit 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

name

Field Type

string

Description

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

name description

Field Type

string string

Description

Required. Name for the sharing rule. Corresponds to Label in the user interface.

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

opportunityAccessLevel ShareAccessLevelReadEdit

( enumeration

of type string)

Required. A value that represents the level of access that a group 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

accountAccessLevel caseAccessLevel

Field Type Description

ShareAccessLevelNoNone

( enumeration

of type string)

Required. A value that represents the level of access that a

Territory or TerritoryAndSubordinates group is granted for an account territory. The possible values are:

•

Read

•

Edit

•

All

ShareAccessLevelNoAll

( enumeration

of type string)

Required. A value that represents the level of access that a

Territory or TerritoryAndSubordinates group is granted for all child cases to an account. The possible values are:

•

None

•

Read

650

Metadata Types OwnerSharingRule

Field Field Type Description

•

Edit contactAccessLevel description

ShareAccessLevelNoAll

( enumeration

of type string)

Required. A value that represents the level of access that a

Territory or TerritoryAndSubordinates group is granted for all related contacts on an account. The possible values are:

•

None

•

Read

•

Edit 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

( enumeration

of type string)

Required. A value that represents the level of access that a

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

accessLevel

Field Type

string description name string string

Description

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

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

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

description name userAccessLevel

Field Type

string

Description

Represents the description of the sharing rule. Maximum of 1000 characters.

This field is available in API version 29.0 and later.

string Required. Name for the sharing rule. Corresponds to Label in the user interface.

ShareAccessLevelReadEdit

( enumeration

of type string)

Required. A value that represents the level of access that a group 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

accessMappings description name

Field Type

AccessMapping

[] string string

Description

A list of access mappings on a sharing set.

The sharing set description. Limit: 255 characters.

Required. The unique identifier for API access. Corresponds to Sharing

Set Name on the user interface.

652

Metadata Types

Field Name

profiles

Field Type

string[]

SharingSet

Description

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

accessLevel

Field Type

string objectField object userField string string string

Description

The target object access level granted to the portal user. Valid values are:

•

Read

•

Edit

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

.

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.

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 Field Type

SharingSet

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<SharingSet xmlns= "http://soap.sforce.com/2006/04/metadata">

<accessMappings >

<accessLevel >Read </accessLevel >

<objectField >ReportsTo </objectField >

<object >Contact </object >

<userField >Contact </userField >

</accessMappings >

<description >User Access Mapping </description >

<name >User </name >

<profiles >customer community user </profiles >

</SharingSet >

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<SharingSet xmlns= "http://soap.sforce.com/2006/04/metadata">

<name >Case </name >

<accessMappings >

<accessLevel >Edit </accessLevel >

<objectField >Entitlement.Account

</objectField >

<object >Case </object >

<userField >Account </userField >

</accessMappings >

</SharingSet >

The following is an example of a SharingSet component with a list of access mappings.

<?xml

version= "1.0" encoding= "UTF-8"?>

<SharingSet xmlns= "http://soap.sforce.com/2006/04/metadata">

<description >This is a basic sharing set with several access mappings.

</description >

<name >Basic </name >

<profiles >customer community user </profiles >

<accessMappings >

<accessLevel >Read </accessLevel >

<objectField >Id </objectField >

<object >Account </object >

<userField >Account </userField >

654

Metadata Types SiteDotCom

</accessMappings >

<accessMappings >

<accessLevel >Edit </accessLevel >

<objectField >Account </objectField >

<object >Contact </object >

<userField >Account </userField >

</accessMappings >

<accessMappings >

<accessLevel >Edit </accessLevel >

<objectField >Contact </objectField >

<object >Case </object >

<userField >Contact </userField >

</accessMappings >

<accessMappings >

<accessLevel >Read </accessLevel >

<objectField >AccountLookup__c </objectField >

<object >HVPUAccessible__c </object >

<userField >Account </userField >

</accessMappings >

</SharingSet >

The following is an example package.xml

that references the previous definition.

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<fullName >SharingSetBasic </fullName >

<types >

<members >HVPUAccessible__c.AccountLookup__c

</members >

<members >HVPUAccessible__c.ContactLookup__c

</members >

<name >CustomField </name >

</types >

<types >

<members >HVPUAccessible__c </members >

<name >CustomObject </name >

</types >

<types >

<members >Basic </members >

<name >SharingSet </name >

<types >

<version >30.0

</version >

</Package >

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

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

label siteType

Field Type

string

(

enumeration of type

string)

Description

The name of the site you are deploying.

Required. Identifies whether the site is a

ChatterNetworkPicasso

site for Salesforce

Communities sites, or a

Siteforce

site for

Site.com sites.

Skill

Declarative Metadata Sample Definition

Sample XML definitions for SiteDotCom are shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<SiteDotCom xmlns= "http://soap.sforce.com/2006/04/metadata">

<label >testsite </label >

<siteType >Siteforce </siteType >

</SiteDotCom >

<?xml

version= "1.0" encoding= "UTF-8"?>

<SiteDotCom xmlns= "http://soap.sforce.com/2006/04/metadata">

<label >testCommunity </label >

<siteType >ChatterNetworkPicasso </siteType >

</SiteDotCom >

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

<developer_name>.skill

file in the skills

directory.

656

Metadata Types

Version

Skill is available in API version 28.0 and later.

Fields

Field Name

assignments

Field Type

SkillAssignments

description label string string

SkillProfileAssignments

Represents the profiles that are associated with a specific skill.

Fields

Field Name

profile

Field Type

string

Description

Specifies how skills are assigned to Live Agent users. Skills can be assigned to sets of users or sets of profiles.

Specifies the description of the skill. This field is available in

API version 38.0 and later.

Specifies the name of the skill.

SkillAssignments

Represents which users and user profiles to whom specific skills are assigned.

Fields

Field Name

profiles users

Field Type

SkillProfileAssignments

SkillUserAssignments

Description

Specifies the profiles that are associated with a specific skill.

Specifies the users that are associated with a specific skill.

Description

Specifies the custom name of the profile associated with a specific skill.

Skill

SkillUserAssignments

Represents the users that are associated with a specific skill.

657

Metadata Types

Fields

Field Name

user

StandardValueSet

Field Type

string

Description

Specifies the username of the user associated with a specific skill.

Declarative Metadata Sample Definition

This is a sample of a skill

file.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Skill xmlns= "http://soap.sforce.com/2006/04/metadata">

<label >My Skill 1 </label >

<assignments >

<profiles >

<profile >LiveAgentOperator </profile >

<profile >LiveAgentSupervisor </profile >

</profiles >

<users >

<user >[email protected]

</user >

</users >

</assignments >

</Skill >

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

sorted standardValue

Field Type

boolean

StandardValue[]

Description

Required. Indicates whether a global value set is sorted in alphabetical order. By default, this value is false

.

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.

<?xml version="1.0" encoding="UTF-8"?>

<StandardValueSet xmlns="http://soap.sforce.com/2006/04/metadata">

<fullName>OpportunityStage</fullName> <!-- Enum name -->

<standardValue>

<fullName>Closed Abandoned</fullName>

</standardValue>

<standardValue>

<fullName>Closed Won</fullName>

</standardValue>

<standardValue>

<fullName>Closed Lost</fullName>

</standardValue>

</StandardValueSet>

<CustomObject>

<fullName>Opportunity</fullName>

<fields>

<fullName>StageName</fullName> <!-- field name -->

<label>Stage</label>

<type>Picklist</type>

</fields>

<label>ObjectWithValueSet</label>

<pluralLabel>ObjectWithValueSet</pluralLabel>

<sharingModel>ReadWrite</sharingModel>

</CustomObject>

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

Fields

Field

valueTranslation

StaticResource

Field Type

ValueTranslation[]

Description

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.

<?xml

version= "1.0" encoding= "UTF-8"?>

<StandardValueSetTranslation xmlns= "http://soap.sforce.com/2006/04/metadata">

<valueTranslation >

<masterLabel >Cold </masterLabel >

<translation ><!-- Cold --> </translation >

</valueTranslation >

<valueTranslation >

<masterLabel >Hot </masterLabel >

<translation ><!-- Hot --> </translation >

</valueTranslation >

<valueTranslation >

<masterLabel >Warm </masterLabel >

<translation ><!-- Warm --> </translation >

</valueTranslation >

</StandardValueSetTranslation >

The following is an example package.xml

that references the StandardValueSetTranslation definition.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >AccountRating-fr </members >

<name >StandardValueSetTranslation </name >

</types >

<version >38.0

</version >

</Package >

SEE ALSO:

Translations

StaticResource

Represents a static resource file, often a code library in a ZIP file. This type extends the MetadataWithContent

metadata type and inherits its content

and fullName

fields.

Static resources allow you to upload content that you can reference in a Visualforce page, including archives (such as .zip and .jar files), images, style sheets, JavaScript, and other files.

660

Metadata Types StaticResource

File Suffix and Directory Location

The file suffix is

.resource

for the template file. The accompanying metadata file is named

resource-meta.xml

.

Static resource components are stored in the staticresources

folder in the corresponding package directory.

Version

Static resources are available in API version 12.0 and later.

Fields

This metadata type contains the following fields:

Field Name Field Type

cacheControl

StaticResourceCacheControl

( enumeration of type string)

content base64Binary contentType string description string fullName string

Description

Required. Indicates whether the static resource is marked with a public caching tag so that a third-party delivery client can cache the content. This is a new field in API version 14.0. The valid values are:

•

Private

•

Public

The static resource content. 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. This field is inherited from the

MetadataWithContent

component.

Required. The content type of the file, for example text/plain.

The description of the static resource.

The static resource name. 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.

Inherited from the Metadata component, this field is not defined in the WSDL

for this component. It must be specified when creating, updating, or deleting.

See create()

to see an example of this field specified for a call.

Declarative Metadata Sample Definition

<?xml

version= "1.0" encoding= "UTF-8"?>

<StaticResource xmlns= "http://soap.sforce.com/2006/04/metadata">

<contentType >text/plain </contentType >

<description >Test Resource </description >

</StaticResource >

661

Metadata Types SynonymDictionary

SynonymDictionary

Represents a set of synonym groups, which are groups of words or phrases that are treated as equivalent in users’ searches. You can define synonym groups to optimize search results for acronyms, variations of product names, and other terminology unique to your organization.

Synonyms are available in Service Cloud features such as Salesforce Knowledge. This type extends the Metadata

metadata type and inherits its fullName

field.

File Suffix and Directory Location

SynonymDictionary components have the suffix

.synonymDictionary

and are stored in the synonymDictionaries

folder.

Version

SynonymDictionary components are available in API version 29.0 and later.

Special Access Rules

Synonyms must be enabled in your organization. Only users with the “Manage Synonyms” permission can access this object.

Fields

Field Name

groups isProtected label

Field Type

SynonymGroup

boolean string

Description

The synonym groups defined in this dictionary.

Indicates whether this component is protected ( true

) or not ( false

).

Protected components cannot be linked to or referenced by components created in the installing organization.

Required. Specifies the display name of the synonym dictionary.

SynonymGroup

Represents a group of synonymous words or phrases.

Field Name

languages

Field Type

Language

Description

Required. Specifies the languages the synonym group applies to. If synonyms are specific to a single language, specify only that language. If the synonyms apply to multiple languages, specify multiple languages for one synonym group.

662

Metadata Types

Field Name

terms

Field Type

string

SynonymDictionary

Description

Required. A word or phrase synonymous with other terms in the group.

Maximum of 50 characters. Minimum of two terms

per group.

Synonym groups are symmetric, which means that if oranges and apples are defined in a synonym group, a search for

oranges

will return a match for

apples

, and vice versa for a search for

apples

.

Declarative Metadata Sample Definition

The following is an example of a SynonymDictionary component:

<?xml

version= "1.0" encoding= "UTF-8"?>

<SynonymDictionary xmlns= "http://soap.sforce.com/2006/04/metadata">

<groups >

<languages >en_US </languages >

<terms >Salesforce </terms >

<terms >salesforce.com

</terms >

<terms >The Customer Company </terms >

<terms >SFDC </terms >

</groups >

<groups >

<languages >fr </languages >

<terms >renault </terms >

<terms >clio </terms >

</groups >

<label >Sample Dictionary </label >

</SynonymDictionary >

The following is an example package.xml

that references the SynonymDictionary component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >Sample Dictionary </members >

<name >SynonymDictionary </name >

</types >

<version >39.0

</version >

</Package >

Usage

If you have existing synonym groups defined before API version 29.0, your existing groups are associated with a default dictionary called

_Default

.

If you have a set of synonyms that require frequent updates, we recommend assigning the synonym group or groups to a dedicated dictionary with a small number of groups. Each time you deploy an existing dictionary, all of its synonym groups are overwritten. We don’t support deploying updates to only a single synonym group within a dictionary.

663

Metadata Types

Territory

Represents a territory in your organization.

Declarative Metadata File Suffix and Directory Location

The file suffix for territory components is

.territory

and components are stored in the territories

directory of the corresponding package directory.

Version

Territory components are available in API version 24.0 and later.

Fields

This metadata type extends to subtype RoleOrTerritory .

Field Name

accountAccessLevel

Field Type

string fullName parentTerritory string string

Description

Specifies whether users in this territory can access accounts that are assigned to this territory and are otherwise inaccessible. Valid values are:

•

Read

•

Edit

•

All

If your organization’s sharing model for accounts is Public Read/Write, valid values are only

Edit

and

All

.

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.

This field is available in API version 31.0 and later.

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. Corresponds to Territory Name in the user interface.

The territory above this territory in the territory hierarchy.

Territory

Declarative Metadata Sample Definition

The following is the definition of a territory.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Territory xmlns= "http://soap.sforce.com/2006/04/metadata">

<accountAccessLevel >Edit </accountAccessLevel >

<caseAccessLevel >Edit </caseAccessLevel >

664

Metadata Types Territory2

<contactAccessLevel >Edit </contactAccessLevel >

<description >Sample Territory </description >

<mayForecastManagerShare >false </mayForecastManagerShare >

<name >T22name </name >

<opportunityAccessLevel >Read </opportunityAccessLevel >

</Territory >

Territory2

Represents the metadata associated with a sales territory in Territory Management 2.0. This type extends the Metadata

metadata type and inherits its fullName

field.Available only if Territory Management 2.0 has been enabled for your organization.

File Suffix and Directory Location

Territory2 components have the suffix territory2

and are stored in the territories

folder under the folder for the corresponding

Territory2Model.

Version

Territory2 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.

Fields

Field Name

accountAccessLevel

Field Type

string

Description

Specifies whether users in this territory can access accounts that are assigned to this territory and are otherwise inaccessible. Valid values are:

•

Read

•

Edit

•

All

If your organization’s sharing model for accounts is Public Read/Write, valid values are only

Edit

and

All

. If no value is set for this field, this field value uses the default access level that is specified in

Territory2Settings as permitted by the organization’s sharing settings.

665

Metadata Types

Field Name

caseAccessLevel contactAccessLevel customFields description name opportunityAccessLevel

Field Type

string string

FieldValue

string string string

Description

Specifies whether users in this territory can access cases that are assigned to this territory and are otherwise inaccessible. Valid values are:

•

None

•

Read

•

Edit

No value should be specified if your organization’s sharing model for cases/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

Territory2Settings as permitted by the organization’s sharing settings.

Specifies whether users in this territory can access contacts that are assigned to this territory and are otherwise inaccessible. Valid values are:

•

None

•

Read

•

Edit

No value should be specified if your organization’s sharing model for contacts is Public Read/Write or Controlled By Parent,

Values for custom fields defined on the Territory2 object and used by this territory. Their metadata is captured separately in

CustomObject

on page 233. Note the following:

•

Territory2 and Territory2Model objects do not handle values for

Text Area (Long), Text Area (Rich), and text-encrypted custom fields.

•

Fields are referenced using their API names. Compound field types like Geolocation will appear as their constituent column fields. For example, nnn_Latitude__s

, nnn_Longitude__s

where

“nnn” is the field name and the suffixes are the Geolocation components.

•

Values of required custom fields are enforced during the deploy()

operation.

A description of the territory.

Required. The user interface label for the territory.

Specifies whether users in this territory can access opportunities that are assigned to this territory and are otherwise inaccessible. Valid values are:

•

None

•

Read

•

Edit

No value should be specified if your organization’s sharing model for cases/opportunities is Public Read/Write,If no value is set for this field,

666

Territory2

Metadata Types Territory2

Field Name

parentTerritory ruleAssociations territory2Type

Field Type Description

this field value uses the default access level that is specified in

Territory2Settings as permitted by the organization’s sharing settings.

string The name of the territory’s parent. When you specify the parent territory, use the developer name. Do not use the “fully qualified” name. Custom fields with no values are retrieved with values of type:

<value xsi:nil="true"/>

. You can also use

<value xsi:nil="true"/>

syntax to remove existing values in custom fields.

Territory2RuleAssociation

Represents an object assignment rule and its association to a territory.

Use the developer name of the rule.

string Required. The territory type that the territory belongs to.

FieldValue

Represents the values of custom fields on the Territory2 object. Available in API version 32.0 and later.

Field Name

name value

Field Type

string any type

Description

Required. The user interface label for the territory.

The value of the field, which can also be null

. The field type is specified in the XML and depends on the field value.

Territory2RuleAssociation

Represents the association of an object assignment rule to a territory. Available in API version 32.0 and later.

Field Name

inherited ruleName

Field Type

boolean string

Description

Required. Indicates whether the rule is inherited from a parent territory ( true

) or local to the current territory ( false

).

Rule inheritance flows from the parent territory where the rule is created to the rule’s descendent territories (if any) in the territory model hierarchy. A local rule is created within a single territory and affects that territory only.

Required. The name of a rule associated with the territory. ruleName

doesn’t need to be fully qualified because Metadata API assumes that the rule belongs to the same model as the territory.

667

Metadata Types Territory2

Declarative Metadata Sample Definition

The following example shows the definition of a Territory2 component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Territory2 xmlns= "http://soap.sforce.com/2006/04/metadata" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd= "http://www.w3.org/2001/XMLSchema">

<name >USA </name >

<description >United States sales </description >

<accountAccessLevel >Edit </accountAccessLevel >

<opportunityAccessLevel >Read </opportunityAccessLevel >

<caseAccessLevel >Edit </caseAccessLevel >

<contactAccessLevel >Edit </contactAccessLevel >

<parentTerritory >Worldwide_Sales </parentTerritory >

<territory2Type >Geo </territory2Type >

<ruleAssociations >

<ruleName >AccRule1 </name >

<inherited >True </inherited >

</ruleAssociations >

<ruleAssociations >

<ruleName >AccRule2 </name >

<inherited >False </inherited >

</ruleAssociations >

<customFields >

<name >Activation_DateTime__c </name >

<value xsi:type= "xsd:dateTime">2014-07-16T05:05:00.000Z

</value >

</customFields >

<customFields >

<name >AutoNumber__c </name >

<value xsi:type= "xsd:string">T# 000001 </value >

</customFields >

<customFields >

<name >DeactivationDate__c </name >

<value xsi:type= "xsd:date">2016-07-12 </value >

</customFields >

<customFields >

<name >External_Id__c </name >

<value xsi:type= "xsd:string">AB2345 </value >

</customFields >

<customFields >

<name >ManagersPhone__c </name >

<value xsi:nil= "true"/>

</customFields >

</Territory2 >

The following is a package.xml

sample.

FY13

and

FY14

represent the names of territory models and demonstrate that rules can have identical developer names within different models. A wildcard character (*) in place of the model name can be used to retrieve all rules in all models in an organization.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >FY13 </members >

668

Metadata Types Territory2Model

<members >FY14 </members >

<name >Territory2Model </name >

</types >

<types >

<members >FY13.USA

</members >

<members >FY13.Worldwide_Sales

</members >

<members >FY14.APAC

</members >

<members >FY14.USA

</members >

<name >Territory2 </name >

</types >

<version >39.0

</version >

</Package >

Usage

•

Triggers defined on Territory2 will not fire during a deploy()

operation.

•

Territory Management 2.0 components don’t support packaging or change sets and aren’t supported in

CRUD calls

.

Territory2Model

Represents the metadata associated with a territory model in Territory Management 2.0. This type extends the

Metadata metadata type

and inherits its fullName

field.Available only if Territory Management 2.0 has been enabled for your Salesforce org.

File Suffix and Directory Location

Territory2Model components have the suffix territory2Model

and are stored in the territory2Models

folder.

Version

Territory2Model 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 models 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.

669

Metadata Types

Fields

Field Name

customFields

Territory2Model description name

Field Type

FieldValue

string string

Description

Custom fields defined on the Territory2Model object and used by this model. Their metadata is captured separately.

•

Territory2 and Territory2Model objects do not handle values for Text

Area (Long), Text Area (Rich), and text-encrypted custom fields.

•

Fields are referenced using their API names. Compound field types like Geolocation will appear as their constituent column fields. For example, nnn_Latitude__s

, nnn_Longitude__s

where

“nnn” is the field name and the suffixes are the Geolocation components.

•

Values of required custom fields are enforced during the deploy()

operation.

A description for the territory model.

Required. The user interface label for the territory model..

Declarative Metadata Sample Definition

The following example shows the definition of a Territory2Model component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Territory2Model xmlns= "http://soap.sforce.com/2006/04/metadata" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd= "http://www.w3.org/2001/XMLSchema">

<name >FY13 </name >

<description >Geographic allocation </description >

<customFields >

<name >Activation_DateTime__c </name >

<value xsi:type= "xsd:dateTime">2014-07-16T05:05:00.000Z

</value >

</customFields >

<customFields >

<name >AutoNumber__c </name >

<value xsi:type= "xsd:string">M# 000001 </value >

</customFields >

<customFields >

<name >DeactivationDate__c </name >

<value xsi:type= "xsd:date">2016-07-12 </value >

</customFields >

<customFields >

<name >External_Id__c </name >

<value xsi:nil= "true"/>

</customFields >

</Territory2Model >

670

Metadata Types Territory2Rule

Usage

•

The retrieve()

call will not return models in these four states:

Cloning

,

Cloning Failed

,

Deleting

, and

Deletion

Failed

.

•

Whenever a model is created, its initial state is

Planning

. You can only do a deploy()

operation for models in

Planning or

Active

state. The same requirement applies to territories and rules associated with those models. For example, you might have a model in

Planning

state on a sandbox org, and a model with the same developer name in

Archived

state on your production org. The deploy()

operation on production will fail because that model’s state is

Archived

and that state prevents changes to the model.

•

Because of the state restrictions, if you have territory models in different orgs with identical developer names and you attempt a deploy()

operation, Metadata API will attempt to create new models, but that operation will fail because of the developer name conflict. For example, you might have a model in

Planning

state on a sandbox org, and a model with the same developer name in

Archived

state on your production org. The deploy()

operation on production will fail because that model’s state is

Archived

and that state prevents changes to the model.

•

If you try to delete a model that has territories, then the delete()

call will change the model’s state to

Deleting

and cascade delete all territories, rules, and user associations in the model. Deleting may take some time depending on the number of territries in the model.

•

Whenever a model is created, its initial state is

Planning

. If a model with the same developer name already exists, it will already have a state, so we do not include the

State

field in Territory2.

•

Territory Management 2.0 components don’t support packaging or change sets and aren’t supported in

CRUD calls

.

Territory2Rule

Represents the metadata associated with a territory assignment rule associated with an object, such as Account, in Territory Management

2.0. This type extends the Metadata

metadata type and inherits its fullName

field.Available only if Territory Management 2.0 has been enabled for your Salesforce org.

File Suffix and Directory Location

Territory2Rule components have the suffix territory2Rule

and are stored in the rules

folder under the folder for the corresponding Territory2Model.

Version

Territory2Rule components are available in API version 32.0 and later.

Special Access

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 rules 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.The SOAP API and the user interface require that a user attempting to create or edit a rules has field-level security access to the fields referenced in the rule item.

671

Metadata Types Territory2Rule

This restriction is relaxed for Metadata API deploy()

operations, as those require “Modify All Data” and “Manage Territories” permissions.

“Modify All Data” is the base permission requirement for all Metadata API operations.

Fields

Field Name

active booleanFilter name objectType ruleItems

Field Type

boolean string string string

Description

Required. Indicates whether the rule is active ( true

) or inactive

( false

). Via the API, active rules run automatically when object records are created and edited. The exception is when the value of the

IsExcludedFromRealign

field on an object record is true

, which prevents record assignment rules from evaluating that record.

An advanced filter condition. For example:

(1 AND 2) OR 3

.

Numbering must start at 1 and must be contiguous.

Required. The user interface label for the rule.

Required. The object that the rule is defined for. For API version 32.0, the only available object is Account.

Territory2RuleItem

on page 672

The items that define a rule’s the selection criteria, such as

Billing

State equals California

.

Territory2RuleItem

Represents the association of a rule item to a rule. Available in API version 32.0 and later.

Field Name

field operation value

Field Type

string

Description

The standard or custom object field that the rule item operates on.

FilterOperation

( enumeration of type

string)

The criterion to apply for the rule item. For example:

equals

or

starts with

.

string The field value or values to evaluate. For example: if the field is

Billing

ZIP/Postal Code

, a value might be

94105

.

Declarative Metadata Sample Definition

The following example shows the definition of a Territory2RuleItem component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Territory2Rule xmlns= "http://soap.sforce.com/2006/04/metadata">

<label >Northern CA </label >

<description >To capture northern CA based accounts </description >

<objectType >Account </objectType >

<active >True </active >

<ruleItems >

672

Metadata Types Territory2Type

<field >BillingZip </field >

<operation >contains </operation >

<value ><94105,94404,94536/value>

</ruleItems >

<ruleItems >

<field >Industry </field >

<operation >equals </operation >

<value >IT </value >

</ruleItems >

<ruleItems >

<field >someCustomField__c </field >

<operation >greater_than </operation >

<value >50000 </value >

</ruleItems >

<booleanFilter >(1 OR 2) AND 3 </booleanFilter >

</Territory2Rule >

The following is a package.xml

sample.

FY13

and

FY14

represent names of territory models and demonstrate that rules can have identical developer names within different models. A wildcard character (*) in place of the model name can be used to retrieve all rules in all models in an org.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >FY13 </members >

<members >FY14 </members >

<name >Territory2Model </name >

</types >

<types >

<members >FY13.AccRule1

</members >

<members >FY14.AccRule1

</members >

<name >Territory2Rule </name >

</types >

<version >39.0

</version >

</Package >

Usage

•

A territory rule can have up to 10 rule items.

•

The sort order of rule items is implicitly derived from the position of the rule items in the XML

•

Rules can’t be run via Metadata API.

•

Territory Management 2.0 components don’t support packaging or change sets and aren’t supported in

CRUD calls

.

Territory2Type

Represents the metadata for a category of territories in Territory Management 2.0. Every Territory2 must have a Territory2Type. This type extends the

Metadata metadata type and inherits its

fullName

field.Available only if Enterprise Territory Management has been enabled for your Salesforce org.

673

Metadata Types Territory2Type

File Suffix and Directory Location

Territory2Type components have the suffix territory2Type

and are stored in the territory2Types

folder.

Version

Territory2Type components are available in API version 32.0 and later.

Special Access Rules

Users without the “Manage Territories” permission will be able to retrieve all the Territory2Types in the org. “Manage Territories” permission is required for the deploy()

operation, in addition to the “Modify All Data” permission required by the Metadata API.

Fields

Field Name

description name priority

Field Type

string string int

Description

A description of the territory type.

Required. The user interface label for the territory type.

Required. Used for Filter-Based Opportunity Territory Assignment

(Pilot in Spring ’15 / Metadata API version 33). Lets you specify a priority for a territory type. For opportunity assignments, the filter examines all territories assigned to the account that the opportunity is assigned to. The account-assigned territory whose territory type priority is highest is then assigned to the opportunity. The priority

field value on each territory type must be unique.

Further, if there are multiple territories with the same territory type

(and therefore the same priority) assigned to the account, no territory is not assigned to the opportunity.

Declarative Metadata Sample Definition

The following example shows the definition of a Territory2Type component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Territory2Type xmlns= "http://soap.sforce.com/2006/04/metadata">

<name >Geo </name >

<description >Geographic allocation </description >

</Territory2Type >

Usage

Territory Management 2.0 components don’t support packaging or change sets and aren’t supported in CRUD calls

.

674

Metadata Types TransactionSecurityPolicy

TransactionSecurityPolicy

Represents a transaction security policy definition. Transaction Security policies give you a way to look through events in your organization and specify actions to take when certain combinations occur.

This type extends the

Metadata metadata type and inherits its

fullName

field.

File Suffix and Directory Location

TransactionSecurityPolicy components have the suffix

.transactionSecurityPolicy

and are stored in the transactionSecurityPolicies

folder.

Version

TransactionSecurityPolicy components are available in API version 35.0 and later.

Fields

Field Name

action active apexClass description developerName eventType

Field Type

TransactionSecurityAction

boolean string

Description

Required. Describes the action to take when the matching

Transaction Security policy is triggered.

Required. If true

, the policy is enabled and is actively monitoring its event.

Required. The name of the class that implements the

TxnSecurity.PolicyCondition

interface for this policy.

string string

Optional. A description of the policy.

Optional. This unique name prevents conflicts with other policies that have the same masterLabel

. This name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.

MonitoredEvents ( enumeration

of type string)

Indicates which type of event is being monitored. Valid values are:

•

AccessResource

—Notifies you when the selected resource has been accessed.

•

AuditTrail

—Reserved for future use.

•

DataExport

—Notifies you when the selected object type has been exported using the Data Loader API client.

•

Entity

—Notifies you on use of an object type such as an authentication provider or client browser.

•

Login

—Notifies you when a user logs in.

675

Metadata Types

Field Name

executionUser masterLabel resourceName

Field Type

string string string

TransactionSecurityPolicy

Description

Required. The name of the user to notify when the policy is triggered, if any notifications have been selected. This user must have the System Administrator profile.

Optional. The master label for this object. This display value is the internal label that is not translated.

Required. A resource used to narrow down the conditions under which the policy triggers. For example, with a

Login

event, you can add a resource to specify that only a specific login URL triggers the policy. The resources available depend on the

Event Type

field. Valid resources are grouped below by event type.

•

AccessResource—EventTimestamp, SessionLevel, SourceIp

•

DataExport—EventTimestamp, SessionLevel, SourceIp

•

Entity—AuthorizeUrl, ConsumerKey, ConsumerSecret,

DefaultScopes, DeveloperName, ErrorUrl, FriendlyName,

IconUrl, IdTokenIssuer, LogoutUrl, TokenUrl, UserInfoUrl

•

Login—ApiType, ApiVersion, Application, Browser,

ClientVersion, LoginUrl, Platform, Status

TransactionSecurityAction

Describes the action to take when the matching Transaction Security policy is triggered.

Field Name

block endSession

Field Type

boolean boolean

Description

Required. If true

, the requested operation is blocked. This action only applies to Login and AccessResource events.

Required. If true

, a current session must be closed before a new session can be started. This action only applies to Login events.

notifications

TransactionSecurityNotification

[] Specifies how to notify the ystem administrator when the action is triggered. There can be none, one, or multiple notifications.

twoFactorAuthentication boolean Required. If true

, two-factor authentication is required for a higher level of access before the requested operation can continue.

This action only applies to Login and AccessResource events.

TransactionSecurityNotification

Describes who to notify and how to notify them when the matching Transaction Security policy is triggered.

Field Name

inApp

Field Type

boolean

Description

True if an in-app notification is selected.

676

Metadata Types Translations

Field Name

sendEmail user

Field Type

boolean string

Description

True if an email notification is selected.

The administrator to receive the notification. This user must belong to the System Administrator profile.

Declarative Metadata Sample Definition

The following is an example of a TransactionSecurityPolicy component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<TransactionSecurityPolicy xmlns= "http://soap.sforce.com/2006/04/metadata">

<action >

<block >true </block >

<endSession >false </endSession >

<notifications >

<inApp >false </inApp >

<sendEmail >true </sendEmail >

<user >[email protected]

</user >

</notifications >

<twoFactorAuthentication >false </twoFactorAuthentication >

</action >

<active >true </active >

<apexClass >TxnSecurityMdApiPolicy </apexClass >

<eventType >Login </eventType >

<executionUser >[email protected]

</executionUser >

<resourceName >LoginHistory </resourceName >

</TransactionSecurityPolicy >

The following is an example package manifest used to deploy or retrieve the transaction security metadata for an organization.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >MySecurityPolicy </members >

<name >TransactionSecurityPolicy </name >

</types >

<version >35.0

</version >

</Package >

Translations

This metadata type allows you to work with translations for various supported languages. This type extends the Metadata

metadata type and inherits its fullName

field. The ability to translate component labels is part of the Translation Workbench. For more information, see “Enable and Disable the Translation Workbench” in the Salesforce online help.

Language

A two-character language code identifies each language, such as en

, or a five-character locale code, such as en_AU.

677

Metadata Types Translations

Note: Setting a default locale is different from setting a default language.

Salesforce offers full support for the following languages.

•

Chinese (Simplified): zh_CN

•

Chinese (Traditional): zh_TW

•

Danish: da

•

Dutch: nl_NL

•

English: en_US

•

Finnish: fi

•

French: fr

•

German: de

•

Italian: it

•

Japanese: ja

•

Korean: ko

•

Norwegian: no

•

Portuguese (Brazil): pt_BR

•

Russian: ru

•

Spanish: es

•

Spanish (Mexico): es_MX

•

Swedish: sv

•

Thai: th

End-user languages are useful if you have a multilingual organization or partners who speak languages other than your company’s default language. For end-user languages, Salesforce provides translated labels for all standard objects and pages, except administrative pages, Setup, and Help. When you specify an end-user language, labels and Help that aren’t translated appear in English. End-user languages are intended only for personal use by end users. Don’t use end-user languages as corporate languages. Salesforce doesn’t provide customer support in end-user languages.

End-user languages include:

•

Arabic: ar

•

Bulgarian: bg

•

Croatian: hr

•

Czech: cs

•

English (UK): en_GB

•

Greek: el

•

Hebrew: iw

•

Hungarian: hu

•

Indonesian: in

•

Polish: pl

•

Portuguese (Portugal): pt_PT

•

Romanian: ro

•

Slovak: sk

•

Slovenian: sl

678

Metadata Types Translations

•

Turkish: tr

•

Ukrainian: uk

•

Vietnamese: vi

Note: Salesforce provides limited support for right-to-left languages—Arabic and Hebrew—for the following features.

•

Live Agent

•

Cases

•

Accounts

These features are not supported in Lightning Experience, the Salesforce1 mobile app, any other mobile app or mobile browser, or any user interface except Salesforce Classic. There is no guarantee that right-to-left languages function correctly with any other

Salesforce features. There are no plans to expand the list of supported features.

Features that aren’t supported for right-to-left languages include, but are not limited to, the following.

•

Report Builder

•

Generating quote PDFs

•

Customizable forecasting

•

Emails

•

Salesforce Knowledge

•

Feeds

•

Communities

The absence of a feature from this list does not imply support. Only Live Agent, Cases, and Accounts are supported with right-to-left languages.

In situations where Salesforce doesn’t provide default translations, use platform-only languages to localize apps and custom functionality that you’ve built on the Salesforce App Cloud. You can translate items such as custom labels, custom objects, and field names. You can also rename most standard objects, labels, and fields. Informative text and non-field label text aren’t translatable.

Platform-only languages are available in all places where you can select a language in the application. However, when you select a platform-only language, all standard Salesforce labels default to English or, in select cases, to an end-user or fully supported language.

•

Albanian: sq

•

Arabic (Algeria): ar_DZ

•

Arabic (Bahrain): ar_BH

•

Arabic (Egypt): ar_EG

•

Arabic (Iraq): ar_IQ

•

Arabic (Jordan): ar_JO

•

Arabic (Kuwait): ar_KW

•

Arabic (Lebanon): ar_LB

•

Arabic (Libya): ar_LY

•

Arabic (Morocco): ar_MA

•

Arabic (Oman): ar_OM

•

Arabic (Qatar): ar_QA

•

Arabic (Saudi Arabia): ar_SA

•

Arabic (Sudan): ar_SD

•

Arabic (Syria): ar_SY

679

Metadata Types

•

Arabic (Tunisia): ar_TN

•

Arabic (United Arab Emirates): ar_AE

•

Arabic (Yemen): ar_YE

•

Armenian: hy

•

Basque: eu

•

Bosnian: bs

•

Bengali: bn

•

Chinese (Simplified—Singapore): zh_SG

•

Chinese (Traditional—Hong Kong): zh_HK

•

English (Australia): en_AU

•

English (Canada): en_CA

•

English (Hong Kong): en_HK

•

English (India): en_IN

•

English (Ireland): en_IE

•

English (Malaysia): en_MY

•

English (Philippines): en_PH

•

English (Singapore): en_SG

•

English (South Africa): en_ZA

•

Estonian: et

•

French (Belgium): fr_BE

•

French (Canada): fr_CA

•

French (Luxembourg): fr_LU

•

French (Switzerland): fr_CH

•

Georgian: ka

•

German (Austria): de_AT

•

German (Luxembourg): de_LU

•

German (Switzerland): de_CH

•

Hindi: hi

•

Icelandic: is

•

Irish: ga

•

Italian (Switzerland): it_CH

•

Latvian: lv

•

Lithuanian: lt

•

Luxembourgish: lb

•

Macedonian: mk

•

Malay: ms

•

Maltese: mt

•

Romanian (Moldova): ro_MD

•

Montenegrin: sh_ME

•

Romansh: rm

680

Translations

Metadata Types Translations

•

Serbian (Cyrillic): sr

•

Serbian (Latin): sh

•

Spanish (Argentina): es_AR

•

Spanish (Bolivia): es_BO

•

Spanish (Chile): es_CL

•

Spanish (Colombia): es_CO

•

Spanish (Costa Rica): es_CR

•

Spanish (Dominican Republic): es_DO

•

Spanish (Ecuador): es_EC

•

Spanish (El Salvador): es_SV

•

Spanish (Guatemala): es_GT

•

Spanish (Honduras): es_HN

•

Spanish (Nicaragua): es_NI

•

Spanish (Panama): es_PA

•

Spanish (Paraguay): es_PY

•

Spanish (Peru): es_PE

•

Spanish (Puerto Rico): es_PR

•

Spanish (United States): es_US

•

Spanish (Uruguay): es_UY

•

Spanish (Venezuela): es_VE

•

Tagalog: tl

•

Tamil: ta

•

Urdu: ur

•

Welsh: cy

Declarative Metadata File Suffix and Directory Location

Translations are stored in a file with a format of

localeCode.translation

, where

localeCode

is the locale code of the translation language. For example, the file name for German translations is de.translation

. The supported locale codes are listed in

Language

.

Custom object translations are stored in the translations

folder in the corresponding package directory.

Version

Translations components are available in API version 14.0 and later.

Fields

Field

customApplications

Field Type

CustomApplicationTranslation []

Description

A list of custom application translations.

681

Metadata Types Translations

Field

customLabels customPageWebLinks customTabs fullName

Field Type

CustomLabelTranslation

[]

CustomPageWebLinkTranslation []

CustomTabTranslation []

string globalPicklists quickActions reportTypes scontrols

GlobalPicklistTranslation

[]

GlobalQuickActionTranslation

ReportTypeTranslation

ScontrolTranslation []

[]

[]

Description

A list of custom label translations.

A list of translations for web links defined in a home page component.

A list of custom tab translations.

Required. The language code; for example, de

for

German.

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.

A list of global picklist translations. A global picklist’s value set is inherited by all the custom picklist fields that are based on it.

This field is available in API version 37.0 only and is removed from later versions.

A list of global (rather than object-specific) quick actions.

A list of report type translations.

A list of s-control translations.

CustomApplicationTranslation

CustomApplicationTranslation contains details for a custom application translation. For more details, see

CustomApplication .

Field

label name

Field Type

string string

Description

Required. The translated custom application name. Maximum of 765 characters.

Required. The name of the custom application.

CustomLabelTranslation

CustomLabelTranslation contains details for a custom label translation. For more details, see

CustomLabels .

Field

label name

Field Type

string string

Description

Required. The translated custom label name. Maximum of 765 characters.

Required. The custom label name.

682

Metadata Types Translations

CustomPageWebLinkTranslation

CustomPageWebLinkTranslation contains details for a translation of a web link defined in a home page component. For more details, see

CustomPageWebLink

.

Field

label name

Field Type

string string

Description

Required. The translated web link.

Required. The name of the web link.

CustomTabTranslation

CustomTabTranslation contains details for a translation of a custom tab. For more details, see CustomTab .

Field

label name

Field Type

string string

Description

Required. The translated custom tab name.

Required. The custom tab name.

GlobalPicklistTranslation

Note: GlobalPicklistTranslation is available in API version 37.0 only and is removed from later versions.

GlobalPicklistTranslation contains details for a global picklist translation.

Translations are stored in a file with a format of

globalPicklistName__e-lang.objectTranslation

, where

globalPicklistName__e

is the global picklist name, and

lang

is the translation language. To reference a global picklist translation value, use

globalPicklistName__e.value1

, where

value1

is the translated value for the user interface.

Here’s what translations look like for a global picklist.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Translations xmlns= "http://soap.sforce.com/2006/04/metadata">

<globalPicklists >

<name >transpicklist </name >

<picklistValues >

<masterLabel >Three </masterLabel >

<translation >Trois </translation >

</picklistValues >

<picklistValues >

<masterLabel >Four </masterLabel >

<translation >Quatre </translation >

</picklistValues >

</globalPicklists >

</Translations >

Field

name

Field Type

string

Description

Required. Represents the name of a global picklist to be translated.

683

Metadata Types

Field

picklistValues

Translations

Field Type

PicklistValueTranslation []

Description

A list of picklist values from global picklists to be translated.

GlobalQuickActionTranslation

GlobalQuickActionTranslation contains details for the translation of a quick action, globally. For more information, see QuickAction .

Field

label name

Field Type

string string

Description

Required. The translated quick action name, globally.

Required. The quick action name.

ReportTypeTranslation

ReportTypeTranslation contains details for a translation of a custom report type. For more details, see ReportType

.

Field

description label name sections

Field Type

string string string

ReportTypeSectionTranslation

[]

Description

The translated report type description.

The translated report type name.

Required. The name of the report type.

A list of report type section translations.

ReportTypeSectionTranslation

ReportTypeSectionTranslation contains details for a report type section translation.

Field

columns label name

Field Type

ReportTypeColumnTranslation []

string string

Description

A list of report type column translations.

The translated report type section name.

Required. The name of the report type section.

ReportTypeColumnTranslation

ReportTypeColumnTranslation contains details for a report type column translation.

Field

label name

Field Type

string string

Description

Required. The translated report type column name.

Required. The report type column name.

684

Metadata Types Translations

ScontrolTranslation

Important: Visualforce pages supersede s-controls. Organizations that haven’t previously used s-controls can’t create them.

Existing s-controls are unaffected, and can still be edited.

ScontrolTranslation contains details for a translation of an s-control. For more information, see “About S-Controls” in the Salesforce online help.

Field

label name

Field Type

string string

Description

Required. The translated s-control name.

Required. The name of the s-control.

Declarative Metadata Sample Definition

A sample XML definition of a translations component is shown below.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Translations xmlns= "http://soap.sforce.com/2006/04/metadata">

<customApplications >

<label >Angebot-Manager </label >

<name >Quote Manager </name >

</customApplications >

<customLabels >

<label >Dieses ist ein manuelles Angebot </label >

<name >quoteManual </name >

</customLabels >

</Translations >

Usage

When you use the

retrieve()

call to get translations in your organization, the files returned in the

.translations

folder only include translations for the other metadata types referenced in package.xml

. For example, the following package.xml

file contains types

elements that match all custom applications, custom labels, Web links defined in home page components, custom tabs, report types, and s-controls. Translations for all these metadata types are returned because each metadata type is explicitly listed in package.xml

.

<?xml

version= "1.0" encoding= "UTF-8"?>

<Package xmlns= "http://soap.sforce.com/2006/04/metadata">

<types >

<members >* </members >

<name >CustomApplication </name >

</types >

<types >

<members >* </members >

<name >CustomLabels </name >

</types >

<types >

<members >* </members >

<name >CustomPageWebLink </name >

</types >

685

Metadata Types UserCriteria

<types >

<members >* </members >

<name >CustomTab </name >

</types >

<types >

<members >* </members >

<name >ReportType </name >

</types >

<types >

<members >* </members >

<name >Scontrol </name >

</types >

<types >

<members >* </members >

<name >Translations </name >

</types >

<version >39.0

</version >

</Package >

SEE ALSO:

CustomLabels

UserCriteria

Represents the member criteria to use in community moderation rules. This type extends the

Metadata

metadata type and inherits its fullName

field..

File Suffix and Directory Location

UserCriteria components have the suffix community_name.user_criteria_developer_name.userCriteria

and are stored in the

UserCriteria

folder.

Version

UserCriteria components are available in API version 39.0 and later.

Special Access Rules

To view, create, edit, and delete moderation rules, you need the Manage Communities or Create and Set Up Communities permission.

Fields

Field Name

creationAgeInSeconds description

Field Type

int string

Description

If specified, includes only users that were created within a specific time frame.

The description of the user criteria.

686

Metadata Types WaveApplication

Field Name

lastChatterActivityAgeInSeconds masterLabel userTypes

Field Type

int string

NetworkUserType

(

enumeration of

type string)

Description

If specified, includes only members that have posted or commented in the community within a specific time frame.

Name of the user criteria.

The member type to use in moderation rules. Valid values are:

•

Internal

•

Customer

•

Partner

Declarative Metadata Sample Definition

The following is an example of a UserCriteria component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<UserCriteria xmlns= "http://soap.sforce.com/2006/04/metadata">

<masterLabel >Customer and Partner Members </masterLabel >

<description >Member criteria matches customer and partner member </description >

<userTypes >Partner </userTypes >

<userTypes >Customer </userTypes >

</UserCriteria >

WaveApplication

Represents the Wave Analytics application. This type extends the

Metadata

metadata type and inherits its fullName

field.

File Suffix and Directory Location

WaveApplication components have the suffix

.wapp

and are stored in the wave

folder.

Version

WaveApplication components are available in API version 37.0 and later.

Fields

Field Name

assetIcon description folder masterLabel

Field Type

string string string string

Description

The icon that represents the Wave application.

The description that appears in the user interface.

The internal api name of the folder or application.

The user interface label name of the folder or application.

687

Metadata Types WaveDataflow

Field Name

shares templateOrigin templateVersion

Field Type

FolderShare

string string

Description

The folder sharing rules.

The internal (unique) name of the template used to create the application. This field is blank if the application was not created from a template.

The version assigned to the application template by the template's creator. This field is blank if the application was not created from a template.

Declarative Metadata Sample Definition

The following is an example of a WaveApplication component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<WaveApplication xmlns= "http://soap.sforce.com/2006/04/metadata">

<assetIcon >/analytics/wave/web/proto/images/app/icons/11.png

</assetIcon >

<description >Application that shows my sales </description >

<folder >edit </folder >

<masterLabel >Sales Application </masterLabel >

<shares >

<accessLevel >EditAllContents </accessLevel >

<sharedTo >[email protected]

</sharedTo >

<sharedToType >User </sharedToType >

</shares >

</WaveApplication >

WaveDataflow

Represents the WaveDataflow object in the Wave Analytics application. This type extends the MetadataWithContent metadata type and

inherits its content

and fullName

fields.

File Suffix and Directory Location

WaveDataflow components have the suffix

.wdf

and are stored in the wave

folder.

Version

WaveDataflow components are available in API version 37.0 and later.

Fields

Field Name

description masterLabel

Field Type

string string

Description

The dataflow description that appears in the user interface.

Required. The dataflow name that appears in the user interface.

688

Metadata Types WaveDashboard

Declarative Metadata Sample Definition

The following is an example of a WaveDataflow component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<WaveDataflow xmlns= "http://soap.sforce.com/2006/04/metadata" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance">

<description >flow1 </description >

<content xsi:nil= "true"/>

<masterLabel >flow1 </masterLabel >

</WaveDataflow >

WaveDashboard

Represents the WaveDashboard object in the Wave Analytics application. This type extends the MetadataWithContent metadata type

and inherits its content

and fullName

fields.

File Suffix and Directory Location

WaveDashboard components have the suffix

.wdash

and are stored in the wave

folder.

Version

WaveDashboard components are available in API version 37.0 and later.

Fields

Field Name

application description masterLabel templateAssetSourceName

Field Type

string string string string

Description

Required. The internal name of the application.

The dashboard description that appears in the user interface.

Required. The dashboard name that appears in the user interface.

Links the dashboard to the template used to create it. Null for assets not created from a template.

Declarative Metadata Sample Definition

The following is an example of a WaveDashboard component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<WaveDashboard xmlns= "http://soap.sforce.com/2006/04/metadata" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance">

<content xsi:nil= "true"/>

<application >dev__app </application >

<masterLabel >Dashboard1 </masterLabel >

<description >somedesc </description >

</WaveDashboard >

689

Metadata Types WaveDataset

WaveDataset

Represents the WaveDataset object in the Wave Analytics application. This type extends the Metadata metadata type and inherits its

fullName

field.

File Suffix and Directory Location

WaveDataset components have the suffix

.wds

and are stored in the wave

folder.

Version

WaveDataset components are available in API version 37.0 and later.

Fields

Field Name

application description masterLabel templateAssetSourceName

Field Type

string string string string

Description

Required. The internal name of the application.

The dataset description that appears in the user interface.

Required. The user interface label name of the Dataset.

Links the dataset to the template used to create it. Null for assets not created from a template.

Declarative Metadata Sample Definition

The following is an example of a WaveDataset component.

<WaveDataset >

<application >SharedApp </application >

<description >description </description >

<masterLabel >datasetl </masterLabel >

</WaveDataset >

WaveLens

Represents the WaveLens object in the Wave Analytics application. This type extends the

MetadataWithContent

metadata type and inherits its content

and fullName

fields.

File Suffix and Directory Location

WaveLens components have the suffix

.wlens

and are stored in the wave

folder.

690

Metadata Types WaveLens

Version

WaveLens components are available in API version 37.0 and later.

Fields

Field Name

application datasets description masterLabel templateAssetSourceName

Field Type

string string string string string visualizationType string

Description

Required. The internal name of the application.

A reference to the dataset used to create this lens.

The dashboard description that appears in the user interface.

Required. The user interface label name of the dashboard.

Links the lens to the template used to create it. Null for assets not created from a template.

Required. The visualization type to be used for this lens. Valid values are:

•

calheatmap

—Calendar heat map

•

comparisontable

—Comparison table

•

heatmap

—Heat map

•

hbar

—Horizontal bar

•

hbarhdot

—Horizontal dot plot

•

matrix

—Matrix

•

parallelcoords

—Parallel coordinates

•

pie

—Donut

•

pivottable

—Pivot table

•

scatter

—Scatter plot

•

stackhbar

—Stacked horizontal bar

•

stackvbar

—Stacked vertical bar

•

time

—Time line

•

valuestable

—Values table

•

vbar

—Vertical bar

•

vdot

—Vertical dot plot

Declarative Metadata Sample Definition

The following is an example of a WaveLens component.

<?xml

version= "1.0" encoding= "UTF-8"?>

<WaveLens xmlns= "http://soap.sforce.com/2006/04/metadata" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance">

<content xsi:nil= "true"/>

<application >dev__app </application >

691

Metadata Types WaveTemplateBundle

<datasets >dev__abc </datasets >

<masterLabel >lens1 </masterLabel >

<description >lens in shared app </description >

<visualizationType >hbar </visualizationType >

</WaveLens >

WaveTemplateBundle

Represents a Wave Analytics template bundle, which can be used to create Wave apps. A bundle contains a Wave template definition and all its related resources.This type extends the

Metadata

metadata type and inherits its fullName

field.

Note: We provide this feature to selected customers through a pilot program that requires agreement to specific terms and conditions. To be nominated to participate in the program, contact Salesforce. Because pilot programs are subject to change, we can’t guarantee acceptance. This pilot feature isn’t generally available, as referenced in this document or in press releases or public statements. We can’t guarantee that it will become generally available within any particular time frame or at all. Make your purchase decisions only on the basis of generally available features. Services provided by the Wave REST API are subject to change. Support is not provided.

File Suffix and Directory Location

A Wave template bundle is a folder that contains definition files for a template. Unlike other metadata components, a WaveTemplateBundle component isn’t represented by a single component file, but instead by a collection of JSON and CSV definition files. Each definition file represents a resource in a template, such as lenses, dashboards, dataflows, and comma-separated values. For example, this directory structure shows the hierarchy of the folders and files for one Wave Template definition, template1.

waveTemplates template1 template-info.json

variables.json

ui.json

extFiles

PostalCodes.csv

Wave template bundles must be under a top-level folder that’s named waveTemplates

. Each bundle must have its own subfolder under the waveTemplates

folder and be named with the template's fully qualified API name. The bundle folder must contain a template-info.json file to specify the metadata about the template and the references to other definition files. An entire bundle doesn’t have a suffix and definition files can have one of the following suffixes.

Suffix

.json

.csv

Component Type

JavaScript Object Notation

Comma-Separated Values

Version

WaveTemplateBundle components are available in API version 35.0 and later.

692

Metadata Types Wavexmd

Special Access Rules

Definitions can be created in both managed and unmanaged packages.

Fields

Field Name

assetIcon

Field Type

string description label templateType string string string

Description

The icon to use by default for new Wave apps based on this template.

Valid values are

1.png

through

20.png

.

The specification of the template.

Required. The label of the template.

Required. The type of the template. Valid values are:

•

App

•

Dashboard

•

Lens

Wavexmd

Represents the WaveXmd object in the Wave Analytics application. This type extends the

Metadata metadata type and inherits its

fullName

field.

File Suffix and Directory Location

WaveXmd components have the suffix

.xmd

and are stored in the wave

folder.

Version

WaveXmd components are available in API version 39.0 and later.

Fields

Field Name

dataset datasetConnector

Field Type

string string

Description

Specifies the dataset associated with this Xmd.

The name of the connector source for the dataset.

datasetFullyQualifiedName dates dimensions string

WaveXmdDate

Specifies the fully qualified name of the dataset version associated with this Xmd.

List of dates, with formatting information.

WaveXmdDimension

List of dimensions, with formatting information.

693

Metadata Types

Field Name

measures organizations origin

Field Type Description

WaveXmdMeasure

List of measures, with formatting information.

WaveXmdOrganization

List of organizations, for multi-organization support.

string The origin of the dataset version.

WaveXmdDate

WaveXmdDate represents a date in Wave Xmd.

Field

alias compact dateFieldDay dateFieldEpochDay dateFieldEpochSecond dateFieldFiscalMonth string dateFieldFiscalQuarter string dateFieldFiscalWeek string dateFieldFiscalYear dateFieldFullYear dateFieldHour dateFieldMinute string string string string

Field Type

string boolean string string string dateFieldMonth dateFieldQuarter dateFieldSecond dateFieldWeek dateFieldYear description firstDayOfWeek fiscalMonthOffset string string int int string string string string isYearEndFiscalYear label boolean string

Description

Alias of the Date column.

Whether the date should be displayed in compact form.

The day field.

The epoch day field.

The epoch second field.

The fiscal month field.

The fiscal quarter field.

The fiscal week field.

The fiscal year field.

The full year field.

The hour field.

The minute field.

The month field.

The quarter field.

The second field.

The week field.

The year field.

The description of the date column.

Represents the first day of the week.

Offset number of months for the fiscal year in relation to the calendar year.

Whether the year end is the fiscal year.

The label of the date column.

Wavexmd

694

Metadata Types Wavexmd

Field

showInExplorer sortIndex

Field Type

boolean int

Description

Whether or not the date should be shown in the explorer.

Whether or not to sort.

WaveXmdDimension

WaveXmdDimension represents a dimension in Wave Xmd.

Field

customActions customActionsEnabled dateFormat description field fullyQualifiedName imageTemplate isDerived isMultiValue label linkTemplate linkTemplateEnabled linkTooltip

Field Type Description

WaveXmdDimensionCustomAction

Custom actions linked to this dimension.

boolean string string string string

Indicates whether the dimension has custom actions enabled.

The format used for a date that is a dimension.

The description of the dimension.

The field name of the dimension (used in queries).

The fully qualified name of the dimension.

string boolean boolean string string boolean string

The image template.

Whether this is a derived dimension.

Indicates whether the dimension is multi-value.

The label for the dimension.

The template for formatting a link.

Indicates whether the dimension has link templates enabled.

The tooltip to be displayed for links.

members origin

WaveXmdDimensionMember

string

The member overrides for a dimension.

The origin of this dimension.

recordDisplayFields recordIdField recordOrganizationIdField

WaveXmdRecordDisplayLookup

Ordered list of dimensions. The list defines the default order in which to display the dimensions in the user interface.

string string

The record ID for this dimension.

The record organization ID for this dimension.

salesforceActions showInExplorer

WaveXmdDimensionSalesforceAction

Salesforce actions linked to this dimension.

salesforceActionsEnabled boolean showDetailsDefaultFieldIndex int boolean

Indicates whether the dimension has Salesforce actions enabled.

Default order in which to show the dimensions in the user interface.

Indicates whether the dimension is displayed in the explorer.

695

Metadata Types

Field

sortIndex

Field Type

int

Description

Whether or not to sort.

Wavexmd

WaveXmdDimensionCustomAction

WaveXmdDimensionCustomAction represents a custom action in a dimension in Wave Xmd.

Field

customActionName enabled icon method sortIndex target tooltip url

Field Type

string boolean string string int string string string

Description

The name of this custom action.

Indicates whether the action is enabled for a specific dimension.

The icon for the action.

The method for the action.

Whether or not to sort.

The target for the action.

The tooltip for the action.

The URL for the action.

WaveXmdDimensionMember

WaveXmdDimensionMember represents a dimension in Wave Xmd.

Field

color label member sortIndex

Field Type

string string string int

Description

The color for the member.

The label for the member.

The member value.

Whether or not to sort.

WaveXmdRecordDisplayLookup

WaveXmdDimensionRecordDisplayLookup represents a record display field in Wave Xmd.

Field

recordDisplayField

Field Type

string

Description

The field to display.

WaveXmdDimensionSalesforceAction

WaveXmdDimensionSalesforceAction represents an action in a dimension in Wave Xmd.

696

Metadata Types Wavexmd

Field

enabled salesforceActionName sortIndex

Field Type

boolean string int

Description

Indicates whether the action is enabled for a specific dimension.

The name of the action.

Whether or not to sort.

WaveXmdMeasure

WaveXmdMeasure represents a measure in Wave Xmd.

Field

dateFormat description field

Field Type

string string string formatCustomFormat formatDecimalDigits string int formatIsNegativeParens boolean formatPrefix formatSuffix formatUnit formatUnitMultiplier fullyQualifiedName isDerived label string string string double string boolean string origin string showDetailsDefaultFieldIndex int showInExplorer sortIndex boolean int

Description

The format used for a date that is a measure.

The description of the measure.

The field name of the measure (used in queries).

The original (XMD 1.1) format array as a single string.

The number of digits displayed after the decimal place.

Indicates whether to display negative numbers with parentheses, rather than a minus sign.

The prefix placed before the field value.

The suffix placed after the field value.

The unit string for the measure. For example, 'cm'.

The multiplier for the unit.

The fully qualified name of the measure.

Whether this is a derived measure.

The label for the measure.

The origin of the measure.

Default order in which to show the measures in the user interface.

Indicates whether the measure is displayed in the explorer.

Whether or not to sort.

WaveXmdOrganization

WaveXmdOrganization represents a Salesforce organization in Wave Xmd.

697

Metadata Types Workflow

Field

instanceUrl

Field Type

string label sortIndex string organizationIdentifier string int

Description

The instance URL for the organization.

The label for the organization.

The ID of the organization.

Whether or not to sort.

Workflow

Represents the metadata associated with a 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. For more information, see “Workflow” in the Salesforce

Help. This type extends the

Metadata metadata type and inherits its

fullName

field. Use this metadata type to create, update, or delete workflow rule definitions.

When using a manifest file, retrieve all workflow components using the following code:

<types >

<members >* </members >

<name >Workflow </name >

</types >

Declarative Metadata File Suffix and Directory Location

Workflow files have the suffix

.workflow

. There is one file per standard or custom object that has workflow. These files are stored in the workflows

directory of the corresponding package.

Version

Workflow rules are available in API version 13.0 and later.

Workflow

This metadata type represents the valid types of workflow rules and actions associated with a standard or custom object.

Field Name

alerts fieldUpdates flowActions

Field Type

WorkflowAlert []

WorkflowFieldUpdate

[]

WorkflowFlowAction []

Description

An array of all alerts for the object associated with the workflow.

An array of all field updates for the object associated with the workflow.

An array of flow triggers for the object associated with the workflow. Available in API version 30.0 and later.

The pilot program for flow trigger workflow actions is closed. If you've already enabled the pilot in your org, you can continue to create and edit flow trigger workflow actions. If you didn't

698

Metadata Types Workflow

Field Name

fullName knowledgePublishes outboundMessages rules tasks

Field Type Description

enable the pilot in your org, use the Flows action in Process

Builder instead.

string

WorkflowKnowledgePublish []

The 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. This field is inherited from the

Metadata

component.

An array of Salesforce Knowledge Workflow Publishes associated with the workflow. Available in API version 27.0 and later.

WorkflowOutboundMessage []

An array of all of the outbound messages for the object associated with the workflow.

WorkflowRule []

WorkflowTask

[]

An array of all the objects associated with the workflow.

An array of all the tasks for the object associated with the workflow.

WorkflowActionReference

WorkflowActionReference represents one of the workflow actions.

Field Name

name type

Field Type

string

Description

Required. The name of the workflow action.

WorkflowActionType

( enumeration

of type string)

Required. Available types of workflow actions:

•

Alert

•

FieldUpdate

•

FlowAction

—Available in API version 30.0 and later

•

OutboundMessage

•

Task

The pilot program for flow trigger workflow actions is closed. If you've already enabled the pilot in your org, you can continue to create and edit flow trigger workflow actions. If you didn't enable the pilot in your org, use the Flows action in Process Builder instead.

WorkflowAlert

WorkflowAlert represents an email alert associated with a workflow rule.

699

Metadata Types

Field Name

ccEmails description fullName protected recipients senderAddress senderType

Workflow

Field Type

string[] string string boolean

WorkflowEmailRecipient

string

[]

ActionEmailSenderType

( enumeration

of type string)

Description

Additional email addresses. This field is similar to the CC field in email clients.

For the email to be sent successfully, set a value for ccEmails

or recipients

. You can set values for both fields. The value of ccEmails

can include up to five different email addresses.

Required. A description of the email alert. Available in API version 16.0 and later.

Required. The 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. This field is inherited from the

Metadata

component.

Required. Indicates whether this component is protected

( true

) or not ( false

). Protected components cannot be linked to or referenced by components created in the installing organization.

The recipients for the email.

For the email to be sent successfully, set a value for ccEmails

or recipients

. You can set values for both fields.

The address in the From field for the email alert. This allows you to use a standard global email address for your organization (such as [email protected]

) instead of the default From field, which is the email address of the person who updates the record. You can only specify a value in this field if the senderType

is set to

OrgWideEmailAddress

. See “Organization-Wide

Addresses: Let Users Send Email from Salesforce Using a

Common

From

Address” in the Salesforce Help.

The email used as the sender's From and Reply-To addresses.

The following values are valid:

•

CurrentUser

—The email address of the person updating the record. This is the default setting.

•

DefaultWorkflowUser

—The email address of the default workflow user.

•

OrgWideEmailAddress

—A verified global email address for your organization, such as [email protected]

.

700

Metadata Types Workflow

Field Name

template

Field Type

string

Description

Required. Named reference to an EmailTemplate. This email template does not have to exist in the zip file, but it must exist in Metadata API.

WorkflowEmailRecipient

WorkflowEmailRecipient represents a recipient for an email alert associated with a workflow rule.

Field Name

field recipient type

Field Type

string string

ActionEmailRecipientTypes

( enumeration

of type string)

Description

Name of the field referenced in type

. The field named should be of the type specified in type

.

The recipients for the email. Depending on the type selected, this may be required.

Named reference to an EmailTemplate component. Valid values are:

•

accountOwner

- The email is sent to the record's account owner (for example, the Account owner for an

Opportunity).

•

accountTeam

- Only applicable on the Account object.

The email is sent to everyone on that Account's account team.

•

campaignMemberDerivedOwner

- Emails are sent to lead and contact owners when contacts are added to a campaign or in response to a campaign.

•

contactLookup

- The email is sent to a contact whose value is looked up from a field on the record. For this value, the field

field must reference a Contact.

•

creator

- The email is sent to the record's creator.

•

customerPortalOwner

- The email is sent to a specific self-service portal user. For this value, the recipient field must reference a User (by username), only self-service portal users.

•

email

- The email is sent to an email address whose value is looked up from a field on the record. For this value, the field

field must reference an email field.

•

group

- The email is sent to all users in a group. For this value, the recipient field must reference a group (by group name).

•

opportunityTeam

- Only applicable on the

Opportunity object. The email is sent to everyone on that

Opportunity's opportunity team.

•

owner

- The email is sent to the record's owner.

701

Metadata Types

Field Name Field Type

Workflow

Description

•

partnerUser

- The email is sent to a specific partner user. For this value, the recipient field must reference a User

(by username), only partner users.

•

portalRole

- Like role

, but for portal roles only.

•

portalRoleSubordinates

- Like roleSubordinates

, but for portal roles only.

•

role

- The email is sent to all users in a role. For this value, the recipient field must reference a Role (in the role hierarchy, by role name).

•

roleSubordinates

- The email is sent to all users in a role subordinates. For this value, the recipient field must reference a Role.

•

roleSubordinatesInternal

- Like roleSubordinates

, but for internal portal roles only.

•

user

- The email is sent to a specific user. For this value, the recipient field must reference a User (by username).

•

userLookup

- The email is sent to a user whose value is looked up from a field on the record. For this value, the field

field must reference a user foreign key field.

WorkflowFieldUpdate

WorkflowFieldUpdate represents a workflow field update. Field updates allow you to automatically update a field value to one that you specify when a workflow rule is triggered.

Field Name

description field formula fullName literalValue lookupValue

Field Type

string string string string string string

Description

The description of the field update. This information is useful to track the reasoning for initially configuring the field update.

Required. The field (on the object for the workflow) to be updated.

If the operation

field value is

Formula

, this is set to a formula used to compute the new field value.

Required. The 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. This field is inherited from the

Metadata component.

If the

operation

field value is

Literal

, this is the literal value for the field.

If the

operation

field value is

lookupValue

, this is the lookup value that is referenced.

702

Metadata Types Workflow

Field Name

lookupValueType name notifyAssignee operation protected reevaluateOnChange targetObject

Field Type

LookupValueType

( enumeration

of type string)

Description

The type of object that the

lookupValue

field value is

referencing. The valid values are:

•

Queue

•

RecordType

•

User string boolean

FieldUpdateOperation

( enumeration

of type string)

Required. A name for the component. Available in version API

16.0 and later.

Required. Notify the assignee when the field is updated.

Required. The operation that computes the value with which to update the field. Valid values are:

•

Formula

- Indicates the field will be set to a formula. If set, the formula must be a valid formula.

•

Literal

- Indicates the field will be set to a literal value. If set, the literalValue must be a valid literal value for this field.

•

LookupValue

- Similar to Literal, but for an object reference, such as a contact, user, account, etc. If set, the lookupValue

element must be set. Only User is supported in the current API.

•

NextValue

- Indicates that the field will be set to its next value; this is only allowed when the field update references a picklist.

•

Null

- Indicates the field will be set to null.

•

PreviousValue

- Indicates that the field will be set to its previous value; this is only allowed when the field update references a picklist.

boolean boolean

Required. Indicates whether this component is protected ( true

) or not ( false

). Protected components cannot be linked to or referenced by components created in the installing organization.

When set to true, if the field update changes the field’s value, all workflow rules on the associated object are re-evaluated. Any workflow rules whose criteria are met as a result of the field value change will be triggered.

If any of the triggered workflow rules result in another field update that’s also enabled for workflow rule re-evaluation, a domino effect occurs, and more workflow rules can be re-evaluated as a result of the newly-triggered field update. This cascade of workflow rule re-evaluation and triggering can happen up to five times after the initial field update that started it.

string This is set if the change is detected on a child record. If this is set, it points to the foreign key reference on the child object (for

703

Metadata Types Workflow

Field Name Field Type Description

example,

EmailMessage.ParentId

) pointing to the parent

(for example, Case). When set, the formula is based on the child object (for example,

EmailMessage

). This field is named sourceField

before version 14.0. The field name change is automatically handled between versions and does not require any manual editing of existing XML component files.

WorkflowFlowAction

Represents a flow trigger, which is a workflow action that launches a flow. Available in API version 30.0 and later. For more information, see the following topics in the Salesforce Help.

•

Define a Flow Trigger for Workflow (Pilot)

•

Flow Trigger Considerations (Pilot)

Note:

•

The pilot program for flow trigger workflow actions is closed. If you've already enabled the pilot in your org, you can continue to create and edit flow trigger workflow actions. If you didn't enable the pilot in your org, use the Flows action in Process

Builder instead.

•

Test mode for flow triggers isn’t supported in the Metadata API. If you want a flow trigger to run the latest flow version when an administrator causes the workflow rule to fire, enable test mode via the user interface after deployment.

Field Name

description flow flowInputs label language protected

Field Type

string string

WorkflowFlowActionParameter

[] string string boolean

Description

Describes the flow trigger.

Required. Unique name of the flow that this workflow action launches.

An array of values to pass into flow variables and sObject variables when launching the flow.

Required. Name of the flow trigger.

Reserved for future use.

Reserved for future use.

WorkflowFlowActionParameter

Represents a value specified in the flow trigger that is passed into a flow variable or sObject variable when launching the flow.

Note: The pilot program for flow trigger workflow actions is closed. If you've already enabled the pilot in your org, you can continue to create and edit flow trigger workflow actions. If you didn't enable the pilot in your org, use the Flows action in Process Builder instead.

704

Metadata Types Workflow

Field Name

name value

Field Type Description

string Required. Unique name of the variable or sObject variable in the flow.

The flow variable must have isInput

set to

True

.

string Required. Value to assign to the flow variable or sObject variable when launching the flow.

Unlike an sObject variable, which represents an entire Salesforce record in the flow, a flow variable represents a single field. Therefore, the allowed value

depends on whether the name

identifies a flow variable or an sObject variable.

For an sObject variable, the value

must be a merge field that identifies a record—or a lookup relationship field that references a record—of the same object type as the sObject variable. For example:

•

{!this}

—identifies the record that fired the workflow rule.

•

{!Contact}

—identifies the contact associated with the record that fired the workflow rule.

•

{!Asset.Account}

—identifies the account associated with the asset that is associated with the record that fired the workflow rule.

•

{!SomeObject__r}

—uses a lookup relationship field to identify a custom object record associated with the record that fired the workflow rule.

For a flow variable, you can enter a merge field or a literal value. Manually enter a literal value when the variable should have the same value every time the flow is launched, regardless of which record fired the workflow rule. For example, you can enter

true

or

false

for a variable of type Boolean.

For a flow variable, supported merge fields identify a global variable or a field of the same data type as the flow variable. For example:

•

{!Id}

—ID of the record that fired the workflow rule.

•

{!Account.Owner.Email}

—email address of the account owner for the account associated with the record that fired the workflow rule.

•

{!$Organization.Country}

—country of the organization.

WorkflowKnowledgePublish

WorkflowKnowledgePublish represents Salesforce Knowledge article publishing actions and information. Available in API version 27.0

and later.

Field Name

action description label

Field Type

KnowledgeWorkflowAction

( enumeration of type string)

string string

Description

The article publishing actions available when this rule fires.

Valid values are:

•

PublishAsNew

: Publishes the article as a new article.

•

Publish

: Publishes the article as a version of a previously published article.

A brief article description.

Label that represents the article throughout the Salesforce user interface.

705

Metadata Types Workflow

Field Name

language protected

Field Type

string boolean

Description

The language of the article.

Required. Indicates whether this component is protected

( true

) or not ( false

). Protected components cannot be linked to or referenced by components created in the installing organization.

WorkflowOutboundMessage

WorkflowOutboundMessage represents an outbound message associated with a workflow rule. Outbound messages are workflow and approval actions that send the information you specify to an endpoint you designate, such as an external service. An outbound message sends the data in the specified fields in the form of a SOAP message to the endpoint. For more information, see “Outbound Message

Actions” in the Salesforce Help.

Field Name

apiVersion

Field Type

double description endpointUrl fields fullName includeSessionId string string string[] string boolean

Description

Required. The API version of the outbound message. This is automatically set to the current API version when the outbound message is created.

Valid API versions for outbound messages are 8.0 and 18.0 or later.

This API version is used in API calls back to Salesforce using the enterprise or partner WSDLs. The

API Version

can only be modified by using the Metadata API. It can't be modified using the Salesforce user interface.

This field is available in API version 18.0 and later.

Warning: If you change the apiVersion

to a version that doesn't support one of the fields

configured for the outbound message, messages will fail until you update your outbound message listener to consume the updated WSDL. You can monitor the status of outbound messages from Setup by entering

Outbound Messages

in the

Quick Find

box, then selecting Outbound Messages in Salesforce.

Describes the outbound message.

Required. The endpoint URL to which the outbound message is sent.

The named references to the fields that are to be sent.

Required. The 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.

This field is inherited from the

Metadata component.

Required. Set if you want the Salesforce session ID included in the outbound message. Useful if you intend to make API calls and you do not want to include a username and password.

706

Metadata Types Workflow

Field Name

integrationUser name protected

Field Type

string string boolean useDeadLetterQueue boolean

Description

Required. The named reference to the user under which this message is sent.

Required. A name for the component. Available in version API 16.0 and later.

Required. Indicates whether this component is protected ( true

) or not

( false

). Protected components cannot be linked to or referenced by components created in the installing organization.

This field is only available for organizations with dead letter queue permissions turned on. If set, this outbound message will use the dead letter queue if normal delivery fails.

WorkflowRule

This metadata type represents a workflow rule. This type extends the

Metadata

metadata type and inherits its fullName

field.

Field Name

actions active booleanFilter boolean string criteriaItems

FilterItem []

description formula fullName

Field Type

WorkflowActionReference

[] string string string

Description

An array of references for the actions that should happen when this rule fires.

Required. Determines if this rule is active.

For advanced criteria filter, the boolean formula, for example,

(1 AND 2) OR

3

.

An array of the boolean criteria (conditions) under which this rule fires. Note that either this or formula

must be set.

The description of the workflow rule

The formula condition under which this rule first (either this or criteriaItems

) must be set

The 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.

This field is inherited from the

Metadata

component.

707

Metadata Types

Field Name

triggerType

Field Type

WorkflowTriggerTypes ( enumeration

of type string) workflowTimeTriggers

WorkflowTimeTrigger

Workflow

Description

Under what conditions the trigger fires.

Valid values are:

•

onAllChanges

- The workflow rule is considered on all changes.

•

onCreateOnly

- The workflow rule is considered only on create.

•

onCreateOrTriggeringUpdate

- The workflow rule is considered on create and triggering updates.

Represents a set of Workflow actions (Field

Updates, Email Alerts, Outbound Messages, and Tasks) that should execute before or after a specified interval of time.

WorkflowTask

This metadata type references an assigned workflow task.

Field Name

assignedTo assignedToType

Field Type

string

ActionTaskAssignedToTypes

( enumeration

of type string)

Description

Specifies the user, role, or team to which the workflow rule or action is assigned. The field corresponding to the value specified here must be the same as the specified assignedToType

.

Valid string values for this type are:

•

accountCreator

- When set, the task is assigned to the record's account's creator.

•

accountOwner

- When set, the task is assigned to the record's account's owner (Opportunity).

•

accountTeam

- Same as WorkflowAlert type

•

creator

- When set, the task is assigned to the record's creator.

•

opportunityTeam

- Same as WorkflowAlert type

•

owner

- When set, the task is assigned to the record's owner.

•

partnerUser

- When set, the assignedTo

field references a User (by username), a partner user.

•

portalRole

- When set, the assignedTo

field references a Role (by role name), a portal role.

•

role

- When set, the assignedTo

field references a Role (by role name)

708

Metadata Types Workflow

Field Name

description dueDateOffset fullName notifyAssignee offsetFromField priority protected status subject

Field Type

string int string boolean string string boolean string string

Description

•

user

- When set, the assignedTo

field references a User (by username)

The description of this workflow task.

Required. The offset, in days, from either the trigger date, or the date specified in the (optional) offsetFromField

. This can be a negative number.

Required. The 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. This field is inherited from the Metadata

component.

Required. Set to send an email notification when the task is assigned.

Optional field reference of the date field from which the dueDate

should be computed.

Required. The priority to assign the created task.

Required. Indicates whether this component is protected

( true

) or not ( false

). Protected components cannot be linked to or referenced by components created in the installing organization.

Required. The status to assign the created task.

Required. A subject for the workflow task. It is used if an email notification is sent when the task is assigned. Available in API version 16.0 and later.

WorkflowTimeTrigger

Represents a set of Workflow actions (Field Updates, Email Alerts, Outbound Messages, and Tasks) that should execute before or after a specified interval of time.

Field Name

actions offsetFromField

Field Type Description

WorkflowActionReference []

An array of references for the actions that should happen when this trigger fires.

string The date type field name that the time-based workflow triggers off of, i.e.

Created Date

,

Last Modified Date

,

Rule

Trigger Date

or a custom date field on the object for which the workflow rule is defined.

709

Metadata Types Workflow

Field Name

timeLength

Field Type

string

Description

The numeric value of the time after/before the workflow triggers.

A negative value represents the time length before the trigger will fire. The timeLength

is measured in either hours or days, as specified by workflowTimeTriggerUnit

.

workflowTimeTriggerUnit

WorkflowTimeUnits

( enumeration

of type string)

The unit of time before or after which the time-based workflow will trigger. Valid string values are:

•

Hours

•

Days

Declarative Metadata Sample Definition

The following is the definition of a workflow rule:

<?xml

version= "1.0" encoding= "UTF-8"?>

<Workflow xmlns= "http://soap.sforce.com/2006/04/metadata">

<alerts >

<fullName >Another_alert </fullName >

<description >Another alert </description >

<protected >false </protected >

<recipients >

<type >accountOwner </type >

</recipients >

<recipients >

<field >Contact__c </field >

<type >contactLookup </type >

</recipients >

<recipients >

<field >Email__c </field >

<type >email </type >

</recipients >

<template >TestEmail/Email Test </template >

</alerts >

<fieldUpdates >

<fullName >Enum_Field_Update </fullName >

<description >Blah </description >

<field >EnumField__c </field >

<name >Enum Field Update </name >

<notifyAssignee >true </notifyAssignee >

<operation >NextValue </operation >

<protected >false </protected >

</fieldUpdates >

<fieldUpdates >

<fullName >Enum_Field_Update2 </fullName >

<description >Blah </description >

<field >EnumField__c </field >

<literalValue >PLX2 </literalValue >

<name >Enum Field Update2 </name >

<notifyAssignee >true </notifyAssignee >

<operation >Literal </operation >

710

Metadata Types

<protected >false </protected >

</fieldUpdates >

<fieldUpdates >

<fullName >Field_Update </fullName >

<description >TestField update desc </description >

<field >Name </field >

<formula >Name &amp; &quot;Updated&quot; </formula >

<name >Field Update </name >

<notifyAssignee >false </notifyAssignee >

<operation >Formula </operation >

<protected >false </protected >

</fieldUpdates >

<fieldUpdates >

<fullName >Lookup_On_Contact </fullName >

<field >RealOwner__c </field >

<lookupValue >[email protected]

</lookupValue >

<name >Lookup On Contact </name >

<notifyAssignee >false </notifyAssignee >

<operation >LookupValue </operation >

<protected >false </protected >

</fieldUpdates >

<outboundMessages >

<fullName >Another_Outbound_message </fullName >

<description >Another Random outbound.

</description >

<endpointUrl >http://www.test.com

</endpointUrl >

<fields >Email__c </fields >

<fields >Id </fields >

<fields >Name </fields >

<includeSessionId >true </includeSessionId >

<integrationUser >[email protected]

</integrationUser >

<name >Another Outbound message </name >

<protected >false </protected >

</outboundMessages >

<rules >

<fullName >BooleanFilter </fullName >

<active >false </active >

<booleanFilter >1 AND 2 OR 3 </booleanFilter >

<criteriaItems >

<field >CustomObjectForWorkflow__c.CreatedById

</field >

<operation >notEqual </operation >

</criteriaItems >

<criteriaItems >

<field >CustomObjectForWorkflow__c.CreatedById

</field >

<operation >notEqual </operation >

<value >abc </value >

</criteriaItems >

<criteriaItems >

<field >CustomObjectForWorkflow__c.CreatedById

</field >

<operation >equals </operation >

<value >xyz </value >

</criteriaItems >

<triggerType >onCreateOrTriggeringUpdate </triggerType >

</rules >

<rules >

711

Workflow

Metadata Types

<fullName >Custom Rule1 </fullName >

<actions >

<name >Another_alert </name >

<type >Alert </type >

</actions >

<actions >

<name >Enum_Field_Update2 </name >

<type >FieldUpdate </type >

</actions >

<actions >

<fullName >Field_Update </name >

<type >FieldUpdate </type >

</actions >

<actions >

<name >Another_Outbound_message </name >

<type >OutboundMessage </type >

</actions >

<actions >

<name >Role_task_was_completed </name >

<type >Task </type >

</actions >

<active >true </active >

<criteriaItems >

<field >CustomObjectForWorkflow__c.Name

</field >

<operation >startsWith </operation >

<value >ABC </value >

</criteriaItems >

<description >Custom Rule1 desc </description >

<triggerType >onCreateOrTriggeringUpdate </triggerType >

</rules >

<rules >

<fullName >IsChangedFunctionRule </fullName >

<active >true </active >

<description >IsChangedDesc </description >

<formula >ISCHANGED(Name) </formula >

<triggerType >onAllChanges </triggerType >

</rules >

<tasks >

<fullName >Another_task_was_completed </fullName >

<assignedToType >owner </assignedToType >

<description >Random Comment </description >

<dueDateOffset >20 </dueDateOffset >

<notifyAssignee >true </notifyAssignee >

<priority >High </priority >

<protected >false </protected >

<status >Completed </status >

<subject >Another task was completed </subject >

</tasks >

<tasks >

<fullName >Role_task_was_completed </fullName >

<assignedTo >R11 </assignedTo >

<assignedToType >role </assignedToType >

<dueDateOffset >-2 </dueDateOffset >

<notifyAssignee >true </notifyAssignee >

712

Workflow

Metadata Types

<offsetFromField >CustomObjectForWorkflow__c.CreatedDate

</offsetFromField >

<priority >High </priority >

<protected >false </protected >

<status >Completed </status >

<subject >Role task was completed </subject >

</tasks >

<tasks >

<fullName >User_task_was_completed </fullName >

<assignedTo >[email protected]

</assignedTo >

<assignedToType >user </assignedToType >

<dueDateOffset >-2 </dueDateOffset >

<notifyAssignee >true </notifyAssignee >

<offsetFromField >User.CreatedDate

</offsetFromField >

<priority >High </priority >

<protected >false </protected >

<status >Completed </status >

<subject >User task was completed </subject >

</tasks >

</Workflow >

Workflow

713

CHAPTER 11 Headers

Use headers in Metadata API calls to set options for each call.

IN THIS SECTION:

AllOrNoneHeader

Indicates whether to roll back all metadata changes when some of the records in a call result in failures.

CallOptions

Specifies the API client identifier.

DebuggingHeader

Specifies that the deployment result will contain the debug log output, and specifies the level of detail included in the log. The debug log contains the output of Apex tests that are executed as part of a deployment.

SessionHeader

Specifies the session ID that the login call returns. This session ID is used to authenticate all subsequent Metadata API calls.

AllOrNoneHeader

Indicates whether to roll back all metadata changes when some of the records in a call result in failures.

Version

This header is available in API version 34.0 and later.

Supported Calls

createMetadata() ,

updateMetadata()

,

upsertMetadata()

,

deleteMetadata()

Usage

If this header isn’t used in API version 34.0 and later, by default a call can save a partial set of records (equivalent to

AllOrNoneHeader=false

)—the records that are processed successfully are saved and records that have failures aren’t saved.

714

Headers

Fields

Field Name

allOrNone

AllOrNoneHeader

Type

boolean

Description

Set to true

to cause all metadata changes to be rolled back if any records in the call cause failures. Set to false

to enable saving only the records that are processed successfully when other records in the call cause failures.

Sample Code—Java

Add the

AllOrNoneHeader

to the metadata connection before you perform a call as follows: metadataConnection.setAllOrNoneHeader(true);

This next example shows how to use the

AllOrNoneHeader

when creating two custom objects. Because the second custom object doesn’t have the required

Name

field, the create()

call can’t create this custom object and rolls back the first custom object. The output is shown after this code sample.

import com.sforce.soap.metadata.*; import com.sforce.soap.metadata.Error; import com.sforce.ws.ConnectionException; public class CallWithHeader {

MetadataConnection metadataConnection = null; public static void main(String[] args) throws ConnectionException {

CallWithHeader samples = new CallWithHeader(); samples.createWithHeader();

} public CallWithHeader() throws ConnectionException { metadataConnection = MetadataLoginUtil.login();

} public void createWithHeader() throws ConnectionException {

// Define two custom objects to be inserted.

CustomObject co1 = new CustomObject();

String name1 = "MyCustomObject1" ; co1.setFullName(name1 + "__c" ); co1.setDeploymentStatus(DeploymentStatus.Deployed); co1.setDescription( "Created by the Metadata API" ); co1.setEnableActivities(true); co1.setLabel(name1 + " Object" ); co1.setPluralLabel(co1.getLabel() + "s" ); co1.setSharingModel(SharingModel.ReadWrite);

CustomField nf = new CustomField(); nf.setType(FieldType.Text); nf.setLabel(co1.getFullName() + " Name" ); co1.setNameField(nf);

715

Headers CallOptions

// The second custom object doesn't have a Name field

CustomObject co2 = new CustomObject();

String name2 = "MyCustomObject2" ; co2.setFullName(name2 + "__c" ); co2.setDeploymentStatus(DeploymentStatus.Deployed); co2.setDescription( "Created by the Metadata API" ); co2.setEnableActivities(true); co2.setLabel(name2 + " Object" ); co2.setPluralLabel(co2.getLabel() + "s" ); co2.setSharingModel(SharingModel.ReadWrite);

// Setting the allOrNone header to true to cause

// the call to not commit any record if one or more

// records in this call have failures.

metadataConnection.setAllOrNoneHeader(true);

// Now that the header has been set, make the create call.

SaveResult[] results = metadataConnection

.createMetadata( new Metadata[] { co1, co2 });

// Iterate through the call results 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());

}

}

}

}

}

This is the output that the sample returns. The first record is rolled back and the second has a failure.

Errors were encountered while creating MyCustomObject1__c

Error message: Record rolled back because not all records were valid and the request was using AllOrNone header

Status code: ALL_OR_NONE_OPERATION_ROLLED_BACK

Errors were encountered while creating MyCustomObject2__c

Error message: Must specify a nameField of type Text or AutoNumber

Status code: FIELD_INTEGRITY_EXCEPTION

CallOptions

Specifies the API client identifier.

716

Headers

Version

This call is available in all API versions.

Supported Calls

All Metadata API calls.

Fields

Field Name

client

Type

string

Description

A value that identifies an API client.

DebuggingHeader

Sample Code—Java

To change the API client ID, add the

CallOptions

header to the metadata connection before you perform a call as follows: metadataConnection.setCallOptions( "client ID" );

DebuggingHeader

Specifies that the deployment result will contain the debug log output, and specifies the level of detail included in the log. The debug log contains the output of Apex tests that are executed as part of a deployment.

Version

This header is available in all API versions.

Supported Calls

deploy()

Fields

Field Name

categories debugLevel

Type

LogInfo

[]

Description

A list of log categories with their associated log levels.

LogType (

enumeration of type string)

Deprecated. This field is provided only for backward compatibility.

If you provide values for both debugLevel

and categories

, the categories

value is used.

The debugLevel

field specifies the type of information returned in the debug log. The values are listed from the least amount of

717

Headers

Field Name Type

DebuggingHeader

Description

information returned to the most information returned. Valid values include:

•

None

•

Debugonly

•

Db

•

Profiling

•

Callout

•

Detail

LogInfo

Specifies the type and amount of information to be returned in the debug log. The categories

field takes a list of these objects.

LogInfo is a mapping of category

to level

.

Element Name

category level

Type

LogCategory

LogCategoryLevel

Description

Specify the type of information returned in the debug log. Valid values are:

•

Db

•

Workflow

•

Validation

•

Callout

•

Apex_code

•

Apex_profiling

•

Visualforce

•

System

•

All

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

sessionId

Type

string

Description

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( "<session_ID>" );

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

AccountContactRole

AccountContactRelation.Roles

AccountContactRole.Role

AccountOwnership

AccountRating

Account.Ownership

Account.Rating

Lead.Rating

AccountType

AddressCountryCode

AddressStateCode

AssetStatus

CampaignMemberStatus

CampaignStatus

CampaignType

CaseContactRole

CaseOrigin

CasePriority

CaseReason

CaseStatus

CaseType

ContactRole

Account.Type

Country picklist

State picklist

Asset.Status

CampaignMember.Status

Campaign.Status

Campaign.Type

CaseContactRole.Role

Case.Origin

Case.Priority

Case.Reason

Case.Status

Case.Type

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

EntitlementType

EventSubject

EventType

FiscalYearPeriodName

Contract.Status

Entitlement.Type

Event.Subject

Event.Type

Period.PeriodLabel

FiscalYearPeriodPrefix

FiscalYearQuarterName

FiscalYearQuarterPrefix

IdeaCategory

1

IdeaMultiCategory

IdeaStatus

IdeaThemeStatus

Industry

FiscalYearSettings.PeriodPrefix

Period.QuarterLabel

FiscalYearSettings.QuarterPrefix

IdeaTheme.Categories

Idea.Categories

Idea.Status

IdeaTheme.Status

Account.Industry

Lead.Industry

1

InvoiceStatus

LeadSource

LeadStatus

OpportunityCompetitor

OpportunityStage

OpportunityType

OrderStatus

1

OrderType

PartnerRole

Product2Family

QuestionOrigin

1

QuickTextCategory

QuickTextChannel

Invoice.Status

Account.AccountSource

Lead.LeadSource

Opportunity.Source

Lead.Status

Opportunity.Competitors

Opportunity.StageName

Opportunity.Type

Order.Status

1

Order.Type

Account.PartnerRole

Product2.Family

Question.Origin

1

QuickText.Category

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

SocialPostClassification

SocialPostEngagementLevel

SocialPostReviewedStatus

SolutionStatus

TaskPriority

TaskStatus

TaskSubject

TaskType

WorkOrderLineItemStatus

WorkOrderPriority

WorkOrderStatus

ServiceContract.ApprovalStatus

SocialPost.Classification

SocialPost.EngagementLevel

SocialPost.ReviewedStatus

Solution.Status

Task.Priority

Task.Status

Task.Subject

Task.Type

WorkOrderLineItem.Status

WorkOrder.Priority

WorkOrder.Status

1

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,

<apex:detail >

. 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

<new object name> 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

750

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

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

751

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

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

752

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

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

754

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

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

W

WaveApplication component

687

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

755