0% found this document useful (0 votes)
674 views47 pages

Salesforce Migration Guide

Salesforce.com is a registered trademark of salesforce.com, inc. Other marks appearing herein may be trademarks of their respective owners.

Uploaded by

Pratip Dutta
Copyright
© Attribution Non-Commercial (BY-NC)
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
674 views47 pages

Salesforce Migration Guide

Salesforce.com is a registered trademark of salesforce.com, inc. Other marks appearing herein may be trademarks of their respective owners.

Uploaded by

Pratip Dutta
Copyright
© Attribution Non-Commercial (BY-NC)
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd

Version 25.

0: Summer '12

[Link] Migration Tool Guide

Last updated: June 1 2012


Copyright 20002012 [Link], inc. All rights reserved. [Link] is a registered trademark of [Link], inc., as are other

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

Table of Contents

Table of Contents
Chapter 1: Development as a Service (DaaS).........................................................................................3
[Link] Migration Tool........................................................................................................................................................3 Understanding Package and Directory Structure......................................................................................................................3

Chapter 2: Installing the [Link] Migration Tool..............................................................................5


Prerequisites for Using the [Link] Migration Tool.............................................................................................................5 Verifying Java Installation..............................................................................................................................................5 Installing Java................................................................................................................................................................5 Verifying Ant Installation..............................................................................................................................................5 Installing and Configuring Ant.....................................................................................................................................6 Installing the [Link] Migration Tool..................................................................................................................................6 About the Contents of the [Link] Migration Tool.................................................................................................6

Chapter 3: Using the [Link] Migration Tool....................................................................................8


Entering Salesforce Connection Information............................................................................................................................8 Constructing a Project Manifest...............................................................................................................................................9 Specifying Named Components..................................................................................................................................14 Specifying all Components of a Type..........................................................................................................................15 Specifying Standard Objects........................................................................................................................................15 Getting Information About Metadata Types..............................................................................................................15 Describing Metadata Types.........................................................................................................................................16 Listing Components for a Metadata Type..................................................................................................................16 Creating Retrieve Targets.......................................................................................................................................................18 Retrieving Unpackaged Components..........................................................................................................................19 Retrieving Managed or Unmanaged Packages............................................................................................................19 Retrieving Components in Bulk..................................................................................................................................19 Retrieving Metadata from a Salesforce Organization..............................................................................................................20 Editing Metadata....................................................................................................................................................................21 Deleting Files from an Organization.......................................................................................................................................21 Deploying Changes to a Salesforce Organization...................................................................................................................21 Deploying Components...............................................................................................................................................23 Deploying Code..........................................................................................................................................................24 Running Tests in a Deployment..................................................................................................................................24 Checking the Status of a Task.................................................................................................................................................25

Chapter 4: Common Migration Issues.................................................................................................26


Common Metadata Issues.......................................................................................................................................................26 Connection Problems..............................................................................................................................................................27 Testing in Apex.......................................................................................................................................................................28

Glossary.............................................................................................................................................29

Table of Contents

Index.................................................................................................................................................44

ii

Chapter 1
Development as a Service (DaaS)
[Link] Development as a Service (DaaS) is a suite of features that enables you to use traditional development practices for creating on-demand applications. With the point-and-click tools in the Salesforce Web application, you can create or modify the setup information of your organization including custom objects and fields, workflow rules, Apex classes and triggers, and many other [Link] components. DaaS expands the development process to include external tools, such as code editors, source control systems, and batch scripts to facilitate development and deployment. An important use of DaaS features is when migrating metadata components from one organization to another, for example, when making setup changes in a sandbox organization and then promoting those changes to a production environment.

[Link] Migration Tool


The [Link] Migration Tool is a Java/Ant-based command-line utility for moving metadata between a local directory and a Salesforce organization. The [Link] Migration Tool is especially useful in the following scenarios: Development projects where you need to populate a test environment with large amounts of setup changes Making these changes using a Web interface could take a long time. Multistage release processes A typical development process requires iterative building, testing, and staging before releasing to a production environment. Scripted retrieval and deployment of components can make this process much more efficient. Repetitive deployment using the same parameters You can retrieve all the metadata in your organization, make changes, and deploy a subset of components. If you need to repeat this process, it's as simple as calling the same deployment target again. When migrating from stage to production is done by IT Anyone that prefers deploying in a scripting environment will find the [Link] Migration Tool a familiar process.

For more information, see Using the [Link] Migration Tool on page 8.

Understanding Package and Directory Structure


The Metadata API functions in a package-centric manner. Components may be in one or more packages, or in no package at all. Packages may be local (created in your Salesforce organization) or installed from [Link] AppExchange. Whenever the [Link] Migration Tool retrieves a set of components, that set will be limited to whats in a single package or whats in no package at all. There are three kinds of packages: UnpackagedComponents that live natively in your organization, such as standard objects, go in the unpackaged package.

Development as a Service (DaaS)

Understanding Package and Directory Structure

Unmanaged packageUnmanaged packages are typically used to distribute open-source projects or application templates to provide developers with the basic building blocks for an application. Once the components are installed from an unmanaged package, the components can be edited in the organization they are installed in. The developer who created and uploaded the unmanaged package has no control over the installed components, and can't change or upgrade them. Unmanaged packages should not be used to migrate components from a sandbox to production organization. Instead, see Change Sets in the online help. Managed packageA 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.

Chapter 2
Installing the [Link] Migration Tool
Before you install the [Link] Migration Tool you will need Java and Ant installed on your local machine. Then you can download the [Link] Migration Tool from a Salesforce organization. 1. Install Java and Ant, as described in Prerequisites for Using the [Link] Migration Tool. 2. Log into a Salesforce organization and download the [Link] Migration Tool, as described in Installing the [Link] Migration Tool.

Prerequisites for Using the [Link] Migration Tool


Before you can use the [Link] Migration Tool you must have Java and Ant installed and configured correctly. You may not need to install Java and Ant if you already have them on your computer, so first verify the installation from a command prompt.

Verifying Java Installation


To see if you have Java installed: 1. Open a command prompt. 2. At the prompt, type java -version and press Enter. The output should look something like the following:
java version "1.5.0_01" Java(TM) SE Runtime Environment (build 1.5.0_01-b06) Java HotSpot(TM) Client VM (build 1.5.0_01-b06, mixed mode)

The [Link] Migration Tool works with Java version 1.5.x or later. If you have an earlier version, you will need to install Java 1.5.x or later.

Installing Java
In a Web browser, navigate to [Link] and install the latest version of the Java JDK on the deployment machine. When you are finished with the installation, verify the installation by typing java -version at a command prompt.

Verifying Ant Installation


To see if you have Ant installed:

Installing the [Link] Migration Tool

Installing and Configuring Ant

1. Open a command prompt. 2. At the prompt, type ant -version and press Enter. The output should look something like the following:
Apache Ant version 1.7.0 compiled on December 13 2006

If the Ant version is 1.5.x or earlier, you will need to download the latest version of Ant. Note: Even if you have Ant installed, you may still need to put the bin directory on your path. On a Windows operation system, you may also need to set the ANT_HOME and JAVA_HOME environment variables. For details, see Installing and Configuring Ant.

Installing and Configuring Ant


To install Ant: 1. Download Apache Ant version 1.6 or newer to a directory of your choice: [Link] This directory will be known as ANT_HOME. Once the files are on your computer, there is no further installation required. 2. Add the bin directory to your path. (Only the bin and lib directories are required to run Ant.) 3. If you are using a Windows operation system, create an ANT_HOME environment variable and set the value to where you have installed Ant. Also create a JAVA_HOME environment variable and set the value to the location of your JDK. For additional information, see [Link]

Installing the [Link] Migration Tool


To download and install the [Link] Migration Tool: 1. 2. 3. 4. Log into a Salesforce organization on your deployment machine. Click Your Name > Setup > Develop > Tools, and then click [Link] Migration Tool. Save the .zip file locally and extract the contents to the directory of your choice. Copy [Link] and paste into your Ant installation's lib directory. The lib directory is located in the root folder of your Ant installation. Note: If you do not have Ant installed, see Prerequisites for Using the [Link] Migration Tool.

About the Contents of the [Link] Migration Tool


When you extract the [Link] Migration Tool zip files, the following folders and files are written to the location you specified: A [Link] file that explains how to use the tools A Jar file containing the ant task: [Link] A sample folder containing:

Installing the [Link] Migration Tool

About the Contents of the [Link] Migration Tool

A codepkg\classes folder that contains [Link] and [Link] A codepkg\triggers folder that contains [Link] A mypkg\objects folder that contains the custom objects used in the examples A removecodepkg folder that contains XML files for removing the examples from your organization A sample [Link] file that you must edit, specifying your credentials, in order to run the sample ant tasks in [Link] A sample [Link] file, that exercises the deploy and retrieve API calls

Chapter 3
Using the [Link] Migration Tool
The [Link] Migration Tool is a Java/Ant-based command-line utility for moving metadata between a local directory and a Salesforce organization. You can use the [Link] Migration Tool to retrieve components, create scripted deployment, and repeat deployment patterns. The general procedure you will follow when using the [Link] Migration Tool to copy metadata from one Salesforce organization to another is: 1. 2. 3. 4. 5. 6. Enter credentials and connection information for source Salesforce organization in [Link] Create retrieve targets in [Link] Construct a project manifest in [Link] Run the [Link] Migration Tool to retrieve metadata files from Salesforce Enter credentials and connection information for destination Salesforce organization in [Link] Run the [Link] Migration Tool to deploy metadata files or deletions to Salesforce

Entering Salesforce Connection Information


In order to retrieve or deploy metadata components, you need to edit [Link] to point to a Salesforce organization: 1. Go to the location where you extracted the [Link] Migration Tool files and open the sample subdirectory. 2. Open [Link] in a text editor and substitute a valid Salesforce username and password. If you are using a security token, paste the 25-digit token value to the end of your password. Parameter
[Link]

Value The [Link] username for login. The username associated with this connection must have the Modify All Data permission. Typically, this is only enabled for System Administrator users. When connecting to a sandbox instance your sandbox name is appended to your username. For example, if your production username is foo@[Link], and one of your sandboxes is called bar, then your sandbox username is foo@[Link]. The password you use to log into the organization associated with this project. If you are using a security token, paste the 25-digit token value to the end of your password. The salesforce server URL. Use [Link] to connect to a production or Developer Edition organization. To connect to a sandbox instance, change this to [Link]

[Link]

[Link]

Using the [Link] Migration Tool

Constructing a Project Manifest

Constructing a Project Manifest


The [Link] file is a project manifest that lists all the components you want to retrieve or deploy in a single request. You can retrieve or deploy only a single package at a time. The following elements may be defined in [Link]: Name
<fullName>

Description The name of the server-side package to deploy into. If the <fullName> field is omitted, components will not be assigned to a package when deployed, and will be in the unpackaged package. This field is not used for retrieve. This element contains one or more <members> tags and one <name> tag, and is used to list the metadata components of a certain type to retrieve or deploy. The full name of a component. There is one <members> element defined for each component in the directory. You can replace the value in this member with the wildcard character * (asterisk) instead of listing each member separately. This is a child element of <types>. Contains the type of the component, for example CustomObject or Profile. There is one name defined for each component type in the directory. This is a child element of <types>. The Metadata API version number of the files being retrieved or deployed. When deploying, all the files must conform to the same version of the Metadata API.

<types>

<members>

<name>

<version>

Component Types The following table lists the component types that can be defined by the <name> element in [Link]: Component XML <name> Metadata Folder Type
accountSharingRules

Uses Notes * yes AccountCriteriaBasedSharingRule is represented as criteriaBasedRules, contained in the AccountSharingRules component. yes AccountOwnerSharingRule is represented as ownerRules, contained in the AccountSharingRules component. no This type is retrieved or deployed as part of a custom object file. You must dot-qualify the object name before the component name.

Account Criteria criteriaBasedRules Based Sharing Rule Account Owner ownerRules Sharing Rule

accountSharingRules

Action Override ActionOverride

objects

Using the [Link] Migration Tool

Constructing a Project Manifest

Component

XML <name> Metadata Folder Type

Uses Notes * AccountTerritorySharingRule is represented as rules, contained in the AccountTerritorySharingRules component.

Account rules Territory Sharing Rule Analytic Snapshot Apex class Article Type Visualforce component
AnalyticSnapshot

accountTerritorySharingRules yes

analyticsnapshots

no yes yes yes yes yes no This type is retrieved or deployed as part of a custom object file. You must dot-qualify the object name before the component name.

ApexClass ArticleType ApexComponent

classes objects components

Visualforce page ApexPage Apex trigger


ApexTrigger

pages triggers objects

Business process BusinessProcess

Campaign Criteria Based Sharing Rule Campaign Owner Sharing Rule Case Criteria Based Sharing Rule Case Owner Sharing Rule

criteriaBasedRules

campaignSharingRules

yes CampaignCriteriaBasedSharingRule is represented as criteriaBasedRules, contained in the CampaignSharingRules component. yes CampaignOwnerSharingRule is represented as ownerRules, contained in the CampaignSharingRules component. yes CaseCriteriaBasedSharingRule is represented as criteriaBasedRules, contained in the CaseSharingRules component. yes CaseOwnerSharingRule is represented as ownerRules, contained in the CaseSharingRules component. yes ContactCriteriaBasedSharingRule is represented as criteriaBasedRules, contained in the ContactSharingRules component. yes ContactOwnerSharingRule is represented as ownerRules, contained in the ContactSharingRules component.

ownerRules

campaignSharingRules

criteriaBasedRules

caseSharingRules

ownerRules

caseSharingRules

Contact Criteria criteriaBasedRules Based Sharing Rule Contact Owner Sharing Rule
ownerRules

contactSharingRules

contactSharingRules

10

Using the [Link] Migration Tool

Constructing a Project Manifest

Component Custom Object Criteria Based Sharing Rule

XML <name> Metadata Folder Type


criteriaBasedRules

Uses Notes * CustomObjectCriteriaBasedSharingRule is represented as criteriaBasedRules, contained in the CustomObjectSharingRules component. CustomObjectOwnerSharingRule is represented as ownerRules, contained in the CustomObjectSharingRules component.

customObjectSharingRules no

Custom Object Owner Sharing Rule Custom application Custom field

ownerRules

customObjectSharingRules no

CustomApplication

applications

yes no Custom fields are retrieved or deployed as part of a custom object file. You must dot-qualify the object name before the component name. Individual custom fields cannot be retrieved with the wildcard (*) symbol, but must be explicitly named in [Link], unless their object is named in the CustomObject section.

CustomField

objects

Custom label

CustomLabels

labels

yes Custom labels that can be localized for use in different languages, countries, and currencies. yes Standard objects cannot be retrieved with the wildcard (*) symbol, but must be explicitly named in [Link], and only custom fields and standard picklist fields are included. yes yes Web links are defined in a home page component. yes yes no yes Includes a category group and its categories. no no

Custom object or CustomObject standard object

objects

Custom object translation Custom page web link Custom site Custom tab Dashboard

CustomObjectTranslation objectTranslations

CustomPageWebLink

weblinks

CustomSite CustomTab Dashboard

sites tabs dashboards datacategorygroups

Data Categories DataCategoryGroup Document Email template


Document EmailTemplate

document email

11

Using the [Link] Migration Tool

Constructing a Project Manifest

Component Entitlement Template Field set Flow Folder Group Home page component Home page layout Page layout Letterhead List view

XML <name> Metadata Folder Type


EntitlementTemplate entitlementTemplates

Uses Notes * yes yes yes A .flow file is an XML representation of a flow definition. no yes yes yes yes no no This type is retrieved or deployed as part of a custom object file. You must dot-qualify the object name before the component name. This type is retrieved or deployed as part of a custom object file. You must dot-qualify the object name before the component name. A folder may contain email templates, documents, reports, or dashboards.

FieldSet Flow

objects flows

Folder

document

Group HomePageComponent

groups homePageComponents

HomePageLayout

homePageLayouts

Layout Letterhead ListView

layouts letterhead objects

Lookup filter

NamedFilter

objects

no

Lead Criteria Based Sharing Rule Lead Owner Sharing Rule Opportunity Criteria Based Sharing Rule

criteriaBasedRules

leadSharingRules

yes LeadCriteriaBasedSharingRule is represented as criteriaBasedRules, contained in the LeadSharingRules component. yes LeadOwnerSharingRule is represented as ownerRules, contained in the LeadSharingRules component. OpportunityCriteriaBasedSharingRule is represented as criteriaBasedRules, contained in the OpportunitySharingRules component. OpportunityOwnerSharingRule is represented as ownerRules, contained in the OpportunitySharingRules component.

ownerRules

leadSharingRules

criteriaBasedRules

opportunitySharingRules yes

Opportunity Owner Sharing Rule

ownerRules

opportunitySharingRules yes

12

Using the [Link] Migration Tool

Constructing a Project Manifest

Component Permission set

XML <name> Metadata Folder Type


PermissionSet permissionsets

Uses Notes * yes The contents of a permission set retrieved depends on the contents of the organization. For example, permission sets only include field-level security for fields included in custom objects returned at the same time as the permission sets. yes yes The contents of a profile retrieved depends on the contents of the organization. For example, profiles will only include field-level security for fields included in custom objects returned at the same time as the profiles. yes yes This type is retrieved or deployed as part of a custom object file. You must dot-qualify the object name before the component name. yes no yes Custom report types allow you to build a framework from which users can create and customize reports. yes yes Deprecated. Use Visualforce pages. yes This metadata type is not supported by the deploy(), create(), delete(), or update() calls. no This type is retrieved or deployed as part of a custom object file. You must dot-qualify the object name before the component name. This type is retrieved or deployed as part of a custom object file. You must dot-qualify the object name before the component name.

Portal Profile

Portal Profile

portals profiles

Queue Record type

Queue RecordType

queues objects

Remote site setting Report Report type

RemoteSiteSetting

remoteSiteSettings

Report ReportType

reports reportTypes

Role Scontrol

Role Scontrol

roles scontrols orgSettings

Security settings SecuritySettings

Sharing reason

SharingReason

objects

Sharing recalculation

SharingRecalculation objects

no

Static resource

StaticResource

staticResources

yes

13

Using the [Link] Migration Tool

Specifying Named Components

Component Territory Translation Workbench Validation rule

XML <name> Metadata Folder Type


Territory Translations territories translations

Uses Notes * yes yes no This type is retrieved or deployed as part of a custom object file. You must dot-qualify the object name before the component name. This type is retrieved or deployed as part of a custom object file. You must dot-qualify the object name before the component name.

ValidationRule

objects

Web link

Weblink

objects

no

Workflow

Workflow

workflows

yes A .workflow file is a container for the individual workflow components associated with an object.

Specifying Named Components


To retrieve a component, specify the type of component in the <name> element and declare each component to be retrieved or deployed in the <members> element. The following is a sample [Link] project manifest that names two custom objects to be retrieved or deployed:
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="[Link] <types> <members>MyCustomObject__c</members> <members>MyHelloWorldObject__c</members> <name>CustomObject</name> </types> <version>25.0</version> </Package>

Some metadata components are sub-components of another component. This means you must dot-qualify the sub-component with the parent component name. The following metadata components are defined as part of an object:
CustomField Picklist RecordType Weblink ValidationRule

For example, the following code retrieves a validation rule called ValidationRuleName on the Opportunity object:
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="[Link]

14

Using the [Link] Migration Tool

Specifying all Components of a Type

<types> <members>[Link]</members> <name>ValidationRule</name> </types> <version>25.0</version> </Package>

Specifying all Components of a Type


To retrieve all components of a particular type, use the wildcard symbol (*). For example, to retrieve all custom objects:
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="[Link] <types> <members>*</members> <name>CustomObject</name> </types> <version>25.0</version> </Package>

The wildcard symbol does not apply to all metadata types. For example, using the wildcard with the CustomObject type name will not retrieve standard objects. To retrieve a standard object, you must explicitly name the object in [Link]. Likewise, if you want to retrieve custom fields defined on standard objects, you must name the object and field.

Specifying Standard Objects


To retrieve standard objects and/or custom fields on standard objects, you must name the component in [Link]. The following [Link] file will retrieve a single field EngineeringReqNumber__c, on the Case object, as well as the entire Account object.
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="[Link] <types> <members>Case.EngineeringReqNumber__c</members> <name>CustomField</name> </types> <types> <members>Account</members> <name>CustomObject</name> </types> <version>25.0</version> </Package>

Note: Custom objects and standard objects should be specified in the same <types> section, the one containing <name>CustomObject</name>.

Getting Information About Metadata Types


You sometimes need to experiment with the composition of your [Link] manifest file before you settle on the final version that retrieves or deploys the metadata that you want. There are a couple of helper targets, <sf:describeMetadata> and <sf:listMetadata>, that are useful for gathering the relevant information during this experimentation period. The [Link] file specifies a series of commands to be executed by Ant. Within the [Link] file are named targets that process a series of commands when you run Ant with a target name.

15

Using the [Link] Migration Tool

Describing Metadata Types

Describing Metadata Types


The describeMetadata target returns a list of metadata types that are enabled for your organization. This target is useful when you want to identify the syntax needed for a metadata type in a <name> element in [Link]; for example, CustomObject for custom objects or Layout for page layouts. The following parameters may be set for each <sf:describeMetadata> target: Field
username

Description Required. The Salesforce username for login. The username associated with this connection must have the Modify All Data permission. Typically, this is only enabled for System Administrator users. Required. The password you use to log into the organization associated with this project. If you are using a security token, paste the 25-digit token value to the end of your password. Optional. The Salesforce server URL (if blank, defaults to [Link]). To connect to a sandbox instance, change this to [Link]. Optional. The API version to use for the metadata. The default is 25.0. Optional. The path of the output file where results are stored. The default output is the console. Directing the output to a file makes it easier to extract the relevant information for your [Link] manifest file. Optional. Defaults to false. Prints the SOAP requests and responses to the console. Note that this will show the user's password in plain text during login.

password

serverurl

apiVersion resultFilePath

trace

To get the list of metadata types enabled for your organization, specify a target in the [Link] file using <sf:describeMetadata>.
<target name="describeMetadata"> <sf:describeRetrieve username="${[Link]}" password="${[Link]}" serverurl="${[Link]}" resultFilePath="describeMetadata/[Link]"/> </target>

Listing Components for a Metadata Type


The listMetadata target retrieves property information about metadata components in your organization. This target is useful when you want to identify individual components in [Link] for a retrieval or if you want a high-level view of particular metadata types in your organization. For example, you could use this target to return a list of names of all the CustomObject or Layout components in your organization, and use this information to make a subsequent retrieval to return a subset of these components. The following parameters may be set for each <sf:listMetadata> target:

16

Using the [Link] Migration Tool

Listing Components for a Metadata Type

Field
username

Description Required. The Salesforce username for login. The username associated with this connection must have the Modify All Data permission. Typically, this is only enabled for System Administrator users. Required. The password you use to log into the organization associated with this project. If you are using a security token, paste the 25-digit token value to the end of your password. Optional. The Salesforce server URL (if blank, defaults to [Link]). To connect to a sandbox instance, change this to [Link]. Required. The name of the metadata type for which you are retrieving property information; for example, CustomObject for custom objects, or Report for custom reports. For a full list of allowed values, see Component Types on page 9. The folder associated with the component. This field is required for components that use folders, such as Dashboard, Document, EmailTemplate, or Report. Optional. The API version to use for the metadata. The default is 25.0. Optional. The path of the output file where results are stored. The default output is the console. Directing the output to a file makes it easier to extract the relevant information for your [Link] manifest file. Optional. Defaults to false. Prints the SOAP requests and responses to the console. Note that this will show the user's password in plain text during login.

password

serverurl

metadataType

folder

apiVersion resultFilePath

trace

To get property information for components of one metadata type, such as CustomObject, specify a target in the [Link] file using <sf:listMetadata>.
<target name="listMetadata"> <sf:listMetadata username="${[Link]}" password="${[Link]}" serverurl="${[Link]}" metadataType="CustomObject" resultFilePath="listMetadata/[Link]"/> </target>

The following example uses a component that resides in a folder.


<target name="listMetadata"> <sf:listMetadata username="${[Link]}" password="${[Link]}" serverurl="${[Link]}" metadataType="Report" folder="Marketing_Reports" resultFilePath="listMetadata/[Link]"/> </target>

17

Using the [Link] Migration Tool

Creating Retrieve Targets

Creating Retrieve Targets


The [Link] file specifies a series of commands to be executed by Ant. Within the [Link] file are named targets that process a series of commands when you run Ant with a target name. The following parameters may be set for each <sf:retrieve> target: Field
username

Description Required. The Salesforce username for login. The username associated with this connection must have the Modify All Data permission. Typically, this is only enabled for System Administrator users. Required. The password you use to log into the organization associated with this project. If you are using a security token, paste the 25-digit token value to the end of your password. Optional. The Salesforce server URL (if blank, defaults to [Link]). To connect to a sandbox instance, change this to [Link]. Required. The root of the directory structure into which the metadata files are retrieved. Required if unpackaged is not specified. A comma-separated list of the names of the packages to retrieve. You must specify either packageNames or unpackaged, but not both. Optional. The Metadata API version to use for the retrieved metadata files. The default is 25.0. Optional. Defaults to 10000. The number of milliseconds to wait between attempts when polling for results of the retrieve request. The client continues to poll the server up to the limit defined by maxPoll. Optional. Defaults to 20. The number of times to poll the server for the results of the retrieve request. The wait time between successive poll attempts is defined by pollWaitMillis. Optional. Defaults to true. This must be set to false if you are retrieving multiple packages. If set to false, the retrieved zip file includes an extra top-level directory containing a subdirectory for each package. Optional. Defaults to false. Prints the SOAP requests and responses to the console. Note that this will show the user's password in plain text during login. Required if packageNames is not specified. The path and name of a file manifest that specifies the components to retrieve. You must specify either unpackaged or packageNames, but not both. Optional. Defaults to true. If set to true, the retrieved components are unzipped. If set to false, the retrieved components are saved as a zip file in the retrieveTarget directory.

password

serverurl

retrieveTarget

packageNames

apiVersion

pollWaitMillis

maxPoll

singlePackage

trace

unpackaged

unzip

18

Using the [Link] Migration Tool

Retrieving Unpackaged Components

Retrieving Unpackaged Components


The unpackaged package contains all of the standard objects, custom objects, Apex classes and other metadata components that exist natively in your organization, and not within a package. To retrieve unpackaged components, use a [Link] target that contains the unpackaged attribute that points to a [Link] file. For example:
<target name="retrieveUnpackaged"> <mkdir dir="projectFolder"/> <sf:retrieve username="${[Link]}" password="${[Link]}" serverurl="${[Link]}" retrieveTarget="projectFolder" unpackaged="unpackaged/[Link]"/> </target>

The [Link] file contains Ant tasks for accessing the Metadata API. In the code above, sf:retrieve is an Ant task. The full list of metadata Ant tasks are described in the Metadata API Developer's Guide.

Retrieving Managed or Unmanaged Packages


Packages are useful for distributing related bundles of metadata across multiple instances or organizations, via [Link] AppExchange. However, you can use the [Link] Migration Tool to freely retrieve and deploy packaged metadata without using AppExchange. You retrieve both managed and unmanaged packages in the same way. To retrieve a package, specify a packageNames parameter in the [Link] file. For example:
<target name="retrieveNamedPackage"> <sf:retrieve username="${[Link]}" password="${[Link]}" serverurl="${[Link]}" retrieveTarget="projectFolder" packageNames="mySourcePackage"/> </target>

Retrieving Components in Bulk


This target is the optimal way to download a large number of components of a single metadata type, such as custom reports, into a set of local files. The following parameters may be set for each <sf:bulkRetrieve> target: Field
username

Description Required. The Salesforce username for login. The username associated with this connection must have the Modify All Data permission. Typically, this is only enabled for System Administrator users. Required. The password you use to log into the organization associated with this project. If you are using a security token, paste the 25-digit token value to the end of your password.

password

19

Using the [Link] Migration Tool

Retrieving Metadata from a Salesforce Organization

Field
serverurl

Description Optional. The Salesforce server URL (if blank, defaults to [Link]). To connect to a sandbox instance, change this to [Link]. Required. The root of the directory structure into which the metadata files are retrieved. Required. The name of the metadata type to be retrieved; for example, CustomObject for custom objects, or Report for custom reports. For a full list of allowed values, see Component Types on page 9. Optional. If the metadata is contained in a folder, this parameter should be the name of the folder from which the contents are retrieved. Optional, defaults to 10. The number of items to retrieve while doing multi-part retrieve. Optional. The Metadata API version to use for the retrieved metadata files. The default is 25.0. Optional. Defaults to 20. The number of times to poll the server for the results of the retrieve request. The clients waits for two seconds after the first poll attempt. The wait time is doubled for each successive poll attempt up to maximum of 30 seconds between poll attempts. Optional. Defaults to true. If set to true, the retrieved components are unzipped. If set to false, the retrieved components are saved as a zip file in the retrieveTarget directory.

retrieveTarget

metadataType

containingFolder

batchSize

apiVersion

maxPoll

unzip

To retrieve custom report components in bulk, specify a target in the [Link] file using <sf:bulkRetrieve>.
<target name="bulkRetrieve"> <sf:bulkRetrieve username="${[Link]}" password="${[Link]}" serverurl="${[Link]}" metadataType="Report" retrieveTarget="retrieveUnpackaged"/> </target>

Retrieving Metadata from a Salesforce Organization


To retrieve [Link] components: 1. Open a command prompt. 2. Run Ant by specifying a target name in [Link]. If this is the first time you are running Ant, use ant retrieveUnpackaged to retrieve unpackaged components specified in [Link].

20

Using the [Link] Migration Tool

Editing Metadata

Note: The sample [Link] contains a number of useful targets for various retrieve() and deploy() options that you can modify or use as is. To see a list of all of your named targets in [Link], enter ant -p at the command line. The Metadata API can deploy up to 50 MB, and retrieve up to 2,500 files or 400 MB at one time. If you are working with a large number of components, you should use the listMetadata target to identify the subset of files that you want to retrieve, or you should retrieve batches of components using the bulkRetrieve target.

Editing Metadata
You can use any UTF-8 text editor to make changes to the files you retrieve. Caution: Text editors that do not natively support UTF-8 may insert a byte order mark (BOM) at the top of the file, which can cause problems in the XML metadata.

Deleting Files from an Organization


The [Link] file is a project manifest that lists all the components you want to retrieve or deploy. While you can use [Link] to add components, you cannot use it to delete them. To delete files, you must create a delete manifest called [Link]. The format of the delete manifest is the same as [Link], except that wildcards are not supported. Note: If you try to delete components that do not exist in the organization, the rest of the deletions will be attempted.

The following is a sample [Link] file that names a single custom object to be deleted:
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="[Link] <types> <members>MyCustomObject__c</members> <name>CustomObject</name> </types> <version>25.0</version> </Package>

Deploying Changes to a Salesforce Organization


The [Link] file specifies targets to retrieve and deploy. The following parameters may be set for each deploy target:

21

Using the [Link] Migration Tool

Deploying Changes to a Salesforce Organization

Field
username

Description Required. The Salesforce username for login. The username associated with this connection must have the Modify All Data permission. Typically, this is only enabled for System Administrator users. Required. The password you use to log into the organization associated with this project. If you are using a security token, paste the 25-digit token value to the end of your password. Optional. The Salesforce server URL (if blank, defaults to [Link]). To connect to a sandbox instance, change this to [Link]. Optional. Defaults to 10000. The number of milliseconds to wait when polling for results of the deployment. Note that deployment may succeed even if you stop waiting. Optional. Defaults to false. Set to true to check the validity of the deployed files without making any changes in the organization. This will not deploy any components or change the organization in any way. Optional. Defaults to 20. The number of times to poll the server for the results of the deploy request. Note that deployment may succeed even if you stop waiting. Required if zipFile is not specified. Specifies the root of the directory tree of files to deploy. You must define a value for either zipFile or deployRoot. Required if deployRoot is not specified.. Specifies the path of the metadata zip file to be deployed. You must define a value for either zipFile or deployRoot. Optional. Defaults to false. Declares that the zipFile or deployRoot parameter points to a directory structure with a single package, as opposed to a set of packages. Optional. Defaults to false. Specifies whether a deploy succeeds even if files that are specified in [Link] are not in the zip file. Do not use this parameter for deployment to production organizations. Optional. Defaults to false. Specifies whether a deploy should continue even if files present in the zip file are not specified in [Link]. Do not use this parameter for deployment to production organizations. Optional. Defaults to false. This setting indicates that a deployment should succeed even if there are warnings (true) or that one or more warnings will cause the deployment to fail and roll back (false). If there are errors, as opposed to warnings, the deployment will always fail and roll back. 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. Optional. Defaults to false. If set to true, all tests are run after deploy. For deployment to a production organization, all tests, except for those that originate from installed managed packages, are automatically run regardless of this argument. If any of these tests fail when the rollbackOnError parameter is set to true, the deployment is rolled back and no changes will be made to your organization.

password

serverurl

pollWaitMillis

checkOnly

maxPoll

deployRoot

zipFile

singlePackage

allowMissingFiles

autoUpdatePackage

ignoreWarnings

rollbackOnError

runAllTests

22

Using the [Link] Migration Tool

Deploying Components

Field
runTest

Description Optional child elements. A list of Apex classes containing tests run after deploy. If any of these tests fail when the rollbackOnError parameter is set to true, the deployment is rolled back and no changes will be made to your organization. Optional. Defaults to false. Prints the SOAP requests and responses to the console. Note that this will show the user's password in plain text during login. Optional. The debug logging level for running tests. The default is None. Valid options are: None Debugonly Db Profiling Callout Detail

trace

logType

Note: The [Link] Migration Tool ignores any files or folders with a name starting with a period (.) or ending with a tilde (~) when deploying files. Some source control systems, such as Subversion, create files or folders with names starting with a period. These files can cause issues during deployment to Salesforce, so the [Link] Migration Tool ignores them. The [Link] Migration Tool comes with a sample [Link] file that lists several deployment targets. You will want to create your own custom targets using the sample targets as starting points. A description of the sample targets follows:
deployUnpackaged deploys unpackaged components specified in the target. deployCode deploys the contents of the codepkg package specified in the target. undeployCode deletes classes and triggers in the removecodepkg directory specified by the [Link] manifest. This file is similar to [Link], but lists components to be deleted. For

more information, see Deleting Files from an Organization on page 21. deployCodeFailingTest deploys code that fails testing requirements, strictly for demonstration purposes. deployCodeCheckOnly verifies that deployment will work, but does not deploy any components.

Deploying Components
You can deploy any set of components as a package or into your organization directly in the unpackaged package. The package used is not determined by the [Link] target, but by the project manifest ([Link]). A sample deployment target follows:
<target name="deployUnpackaged"> <sf:deploy username="${[Link]}" password="${[Link]}" serverurl="${[Link]}" deployroot="projectFolder"/> </target>

23

Using the [Link] Migration Tool

Deploying Code

Deploying Code
You can deploy metadata components and Apex at the same time, but you may find it useful to create separate targets for deploying Apex, so that you can run tests as part of the deployment. A portion of a [Link] file is listed below, with a target named deployCode that deploys the contents of the codepkg package and runs the tests for one class.
<target name="deployCode"> <sf:deploy username="${[Link]}" password="${[Link]}" serverurl="${[Link]}" deployroot="codepkg"> <runTest>SampleDeployClass</runTest> </sf:deploy> </target>

Note: When deploying to a production organization, all Apex test methods are run automatically. You cannot specify which tests to run.

Running Tests in a Deployment


For deployment to a production organization, all the tests in your organization, except for those that originate from installed managed packages, are automatically run. If any of the tests fail, the entire deployment will roll back. There is an exception to this rule if you are deploying components for one or more of the following metadata types: ApexComponent ApexPage Dashboard EmailTemplate Report Scontrol StaticResource

If your deployment consists entirely of components for one or more of these metadata types, no tests are run. However, if the deployment includes components for any other metadata type, all the tests are automatically run. For example, no tests are run for the following deployments: One ApexComponent component 100 Report components and 40 Dashboard components

All tests are automatically run for the following deployments: One CustomField component One ApexComponent component and one ApexClass component Five CustomField components and one ApexPage component 100 Report components, 40 Dashboard components, and one CustomField component

24

Using the [Link] Migration Tool

Checking the Status of a Task

Checking the Status of a Task


When you run a target, the [Link] Migration Tool outputs the request ID for each deploy or retrieve task included in the target. You can use the request ID to check the status of a deploy or retrieve task. This is particularly useful if a client is running for a long time and there is a network issue that breaks the connectivity between the [Link] Migration Tool on your machine and Salesforce. To check the status of a run target, use the following command:
ant -[Link]=requestID targetName

Use the requestID that was printed out when you ran the target. For example, if you run the deployZip target, you can run the following command to check the status of the retrieval:
ant -[Link]=04sx00000002aGuAAI deployZip

Note: You should not use this command with targets that contain multiple retrieve or deploy tasks. You should not use this command with the bulkRetrieve task also as this task batches retrievals in multiple requests. To track the status of deployments from within Salesforce, you can also click Your Name > Setup > Deploy > Monitor Deployments.

25

Chapter 4
Common Migration Issues
There are a number of common issues you may run into when migrating metadata and deploying changes. These issues can be grouped into three categories: Metadata Special considerations for dealing with certain metadata components Connectivity Problems connecting to an organization or polling for results Testing and Code Coverage Testing Apex before deployment

Common Metadata Issues


The most common metadata issues are detailed below: Retrieving custom fields on standard objects When you use the wildcard symbol in [Link], to retrieve all objects, you will not retrieve standard objects, or custom fields on standard objects. To retrieve custom fields on standard objects, see Constructing a Project Manifest on page 9. Profiles or permission sets and field-level security The contents of a retrieved profile or permission set depend on the other contents of the retrieve request. For example, field-level security for fields included in custom objects are returned at the same time as profiles or permission sets. For more information, see Profile and PermissionSet in the [Link] Metadata API Developer's Guide. Understanding packages Packages are used to bundle related components so they can be shared with multiple organizations, or distributed on [Link] AppExchange. Managed packages are packages that can be upgraded in the installer's organization. They differ from unmanaged packages in that some components are locked, in order to permit upgrades. Metadata components that are not in any package can be accessed with the unpackaged attribute of sf:retrieve and sf:deploy. Workflow A .workflow file is a container for the individual workflow components associated with an object, including WorkflowAlert, WorkflowFieldUpdate, WorkflowOutboundMessage, WorkflowRule, and WorkflowTask. To retrieve all workflows, include the following XML in [Link]:
<types> <members>*</members> <name>Workflow</name> </types>

Retrieving or deploying components that depend on an object definition The following metadata components are dependent on a particular object for their definition: CustomField, Picklist, RecordType, Weblink, and ValidationRule. This means you must dot-qualify the component name with the object name in [Link], and may not use the wildcard symbol. For more information, see Constructing a Project Manifest on page 9. Personal folders Users' personal folders, for both reports and documents, are not exposed in the Metadata API. To migrate reports or documents you must move them to a public folder.

26

Common Migration Issues

Connection Problems

Connection Problems
The most common connection problems are detailed below: Request timed out When you retrieve or deploy metadata, the request is sent asynchronously, meaning that the response is not returned immediately. Because these calls are asynchronous, the server will process a deploy() to completion even if the [Link] Migration Tool times out. If the deploy succeeds, the changes will be committed to the server. If the deploy fails after timing out, there is no way to retrieve the error message from the server. For this reason, it is important to tune your pollWaitMillis and maxPoll parameters if you receive time-out errors: pollWaitMillis The number of milliseconds to wait between polls for retrieve/deploy results. The default value is 10000 milliseconds (ten seconds). For long-running processes, increase this number to reduce the total number of polling requests, which count against your daily API limits. maxPoll The number of polling attempts to be performed before aborting. The default value is 20. When combined with the default value of pollWaitMillis (10000), this means the [Link] Migration Tool will give the server process a total of 200 seconds (20 poll attempts, waiting 10 seconds between them) to complete before timing out. Note: Since these parameters have default values, they do not have to be specified, and may not exist on your named targets. To add these parameters, include them in the target definition. For example:
<sf:retrieve username="${[Link]}" password="${[Link]}" serverurl="${[Link]}" retrieveTarget="retrieveUnpackaged" . unpackaged="unpackaged/[Link]" pollWaitMillis="10000" maxPoll="100"/>

Invalid username, password, security token; or user locked out - This error indicates a problem with the credentials in [Link]: Username Verify that your username is correct on this account. When connecting to a sandbox instance your sandbox name is appended to your username. For example, if your production username is foo@[Link], and one of your sandboxes is called bar, then your sandbox username is foo@[Link]. Password Verify that your password is correct for this account. Note that you security token is appended to the end of your pasword. Security token The security token is a 25-digit string appended to your password. To reset your security token, click Your Name > Setup > My Personal Information > Reset Security Token, and click Reset Security Token. Locked out If you unsuccessfully attempt to log into an organization too many times, you may be temporarily locked out. The number of times you may fail to connect and the lockout duration depend on your organization settings. Either contact your administrator to have the lock removed, or wait until the lockout period expires. Connection mismatch between sandbox and production If all of your connection credentials in [Link] are correct, you may have a URL mismatch. The server URL is different for sandbox and production environments. In [Link], the [Link] value for production is [Link] For sandbox environments, the value is [Link]

Proxy settings If you connect through a proxy, you will need to follow the Ant Proxy Configuration instructions.

27

Common Migration Issues

Testing in Apex

Testing in Apex
When deploying to a production organization, every unit test in your organization namespace is executed. Before you deploy Apex, the following must be true: 75% of your Apex code must be covered by unit tests, and all of those tests must complete successfully. Note the following: When deploying to a production organization, every unit test in your organization namespace is executed. Calls to [Link] are not counted as part of Apex code coverage. Test methods and test classes are not counted as part of Apex code coverage. While only 75% of your Apex code must be covered by tests, your focus shouldn't be on the percentage of code that is covered. Instead, you should make sure that every use case of your application is covered, including positive and negative cases, as well as bulk and single record. This should lead to 75% or more of your code being covered by unit tests.

Every trigger has some test coverage. All classes and triggers compile successfully.

[Link] recommends that you write tests for the following: Single action Test to verify that a single record produces the correct, expected result. Bulk actions Any Apex code, whether a trigger, a class or an extension, may be invoked for 1 to 200 records. You must test not only the single record case, but the bulk cases as well. Positive behavior Test to verify that the expected behavior occurs through every expected permutation, that is, that the user filled out everything correctly and did not go past the limits. Negative behavior There are likely limits to your applications, such as not being able to add a future date, not being able to specify a negative amount, and so on. You must test for the negative case and verify that the error messages are correctly produced as well as for the positive, within the limits cases. Restricted user Test whether a user with restricted access to the sObjects used in your code sees the expected behavior. That is, whether they can run the code or receive error messages. Note: Conditional and ternary operators are not considered executed unless both the positive and negative branches are executed. For more information, see Understanding Testing in Apex in the [Link] Apex Code Developer's Guide.

28

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 [Link] platform server in conjunction with calls to the [Link] 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 applications 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 Call Center. 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 [Link] that allows you to browse and share apps and services for the [Link] 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.

29

Glossary

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.

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 [Link] 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 [Link] IDE or the [Link] 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 organizations needs.

30

Glossary

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.

D
Database An organized collection of information. The underlying architecture of the [Link] 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 from the [Link] platform database. 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 [Link] platform. Developer Edition accounts are available on [Link]. Developer Force The Developer Force website at [Link] provides a full range of resources for platform developers, including sample code, toolkits, an online developer community, and the ability to obtain limited [Link] platform environments.

31

Glossary

Document Library A place to store documents without attaching them to accounts, contacts, opportunities, or other records.

E
Email Alert Email alerts are workflow and approval actions that are generated using an email template by a workflow rule or approval process and sent to designated recipients, either Salesforce users or others. 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 [Link] platform) and define the relationships between them. ERD diagrams for key Salesforce objects are published in the SOAP API Developer's Guide. 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 Enterprise, Unlimited, and Developer Editions only. Filter Condition/Criteria Condition on particular fields that qualifies items to be included in a list view or report, such as State equals California. [Link] The [Link] platform for building applications in the cloud. [Link] combines a powerful user interface, operating system, and database to allow you to customize and deploy applications in the cloud for your entire enterprise. [Link] IDE An Eclipse plug-in that allows developers to manage, author, debug and deploy [Link] applications in the Eclipse development environment.

32

Glossary

[Link] Migration Tool A toolkit that allows you to write an Apache Ant build script for migrating [Link] 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 twelve 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.

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 [Link] platform runs on multiple instances, but data for any single organization is always consolidated 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.

33

Glossary

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, or Developer Edition organization as your license management organization. For more information, go to [Link] List View A list display of items (for example, accounts or contacts) based on specific criteria. Salesforce provides some predefined views. In the Console tab, 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 ([Link] 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, and Developer Edition organizations, a users individual Locale setting overrides the organizations 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.

34

Glossary

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 ([Link]) 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 [Link] IDE or the [Link] 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. [Link] uses XML to describe metadata. Metadata WSDL A WSDL for users who want to use the [Link] 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 [Link]. 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.

35

Glossary

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 is a workflow, approval, or milestone action that sends 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. Outbound messaging is configured in the Salesforce setup menu. Then you must configure the external endpoint. You can 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. Owner Individual user to which a record (for example, a contact or case) is assigned.

P
Package A group of [Link] 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.

36

Glossary

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

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

37

Glossary

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 Console tab'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). 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 SOA (Service-Oriented Architecture) A powerful capability of [Link] that allows you to make calls to external Web services from within Apex.

38

Glossary

Sandbox Organization A nearly identical copy of a Salesforce production organization. You can create multiple sandboxes in separate environments for a variety of purposes, such as testing and training, without compromising the data and applications in your production environment. 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 by clicking Your Name > Setup > 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 An administration area where you can customize and define [Link] applications. Access Setup through the Your Name > Setup link at the top of Salesforce pages. Sharing Allowing other users to view or edit information you own. There are different ways to share data: Sharing Modeldefines the default organization-wide access levels that users have to each others information and whether to use the hierarchies when determining access to data. Role Hierarchydefines 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 Rulesallow 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 Sharingallows individual users to share records with other users or groups. Apex-Managed Sharingenables developers to programmatically manipulate sharing to support their applications 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. Sites [Link] Sites enables you to create public websites and applications that are directly integrated with your Salesforce organizationwithout 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.

39

Glossary

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 [Link] database. SOSL (Salesforce Object Search Language) A query language that allows you to perform text-based searches using the [Link] API. Standard Object A built-in object included with the [Link] 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 [Link] IDE. Translation Workbench The Translation Workbench lets you specify languages you want to translate, assign translators to languages, create translations for customizations youve 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 modethat is, they process several records at once, rather than just one record at a time. Trigger Context Variable Default variables that provide access to information about the trigger and the records that caused it to fire.

40

Glossary

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 [Link]'s flagship solution for maximizing CRM success and extending that success across the entire enterprise through the [Link] 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, [Link] 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. 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.

41

Glossary

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 is an email alert, field update, outbound message, or task that 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 [Link] components that are retrieved or deployed through the Metadata API are represented by XML definitions.

Y
No Glossary items for this entry.

Z
Zip File A data compression and archive format.

42

Glossary

A collection of files retrieved or deployed by the Metadata API. See also Local Project.

43

Index

Index
A
[Link] file 6 ApexClass component 9 ApexComponent component 9 ApexPage component 9 ApexTrigger component 9

H
helper targets describeMetadata 16 listMetadata 16 HomePageComponent component 9 HomePageLayout component 9

B
[Link] file 8 [Link] 18

I
installation overview 5

C
checking status 25 code coverage 26 code, deploying 21 common deployment problems 26 connection problems 26 CustomApplication component 9 CustomField component 9 CustomObject component 9 CustomPageWebLink component 9 CustomTab component 9

L
Layout component 9 Letterhead component 9 listMetadata 1516

M
managed packages 3 manifest file 9 maxPoll parameter 26 metadata deploying 8, 26 editing 21 retrieving 20 metadata component types 9

D
DaaS 3 deleting components 21 deploy call running tests 24 deploy targets 18 deploying changes 21 deploying code 21 deploying metadata 26 describeMetadata 1516 [Link] file 21 Document component 9

N
named packages 3

P
[Link] constructing 1516 [Link] file 9, 21 Picklist component 9 pollWaitMillis parameter 26 prerequisites for [Link] Migration Tool 5 Profile component 9 project manifest 9 proxy settings 26

E
editing metadata 21 EmailTemplate component 9

F
Folder component 9 [Link] Migration Tool checking status 25 connecting 8 deploying 21 downloading 6 editing metadata 21 prerequisites 5 retrieving metadata 20 using 8

R
[Link] file 6 RecordType component 9 retrieve targets 18 retrieving metadata 20

S
Scontrol component 9 security token 26 [Link] 8 [Link] 8 [Link] 8 StaticResource component 9

44

T
targets for deploy and retrieve 18

V
ValidationRule component 9 Visualforce page component 9

Index

U
unpackaged package 3

W
WebLink component 9 wildcard symbol in [Link] 9 Workflow component 9

45

You might also like