Working with the Zip File

The deploy() and retrieve() calls are used to deploy and retrieve a .zip file. Within the .zip file is a project manifest (package.xml) that lists what to retrieve or deploy, and one or more XML components organized into folders.

The files retrieved or deployed in a .zip file may be unpackaged components that reside in your organization (such as standard objects), or packaged components that reside within named packages.

Every .zip file contains a project manifest, a file named package.xml, and a set of directories that contain the components. The manifest file defines the components that you’re trying to retrieve or deploy in the .zip file and the API version that’s used for the deployment or retrieval.

The following is a sample package.xml file. Note that you can retrieve an individual component for a metadata type by specifying its fullName field value in a members element, or you can also retrieve all components of a metadata type, by using <members>*</members>.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>MyCustomObject__c</members>
5        <name>CustomObject</name>
6    </types>
7    <types>
8        <members>*</members>
9        <name>CustomTab</name>
10    </types>
11    <types>
12        <members>Standard</members>
13        <name>Profile</name>
14    </types>
15    <version>32.0</version>
16</Package>

The following elements might be defined in package.xml:

• <fullName> contains the name of the server-side package. If no <fullName> exists, this is a client-side unpackaged package.
• <types> contains the name of the metadata type (for example, CustomObject) and the named members (for example, myCustomObject__c), to be retrieved or deployed. There can be multiple <types> elements in a manifest file and there is one entry for each named component, and one entry for each individual member.
• <members> contains the fullName of the component, for example MyCustomObject__c. The listMetadata() call is useful to find out the fullName for components of a particular metadata type, if you want to retrieve an individual component. For many metadata types, you can replace the value in members with the wildcard character * (asterisk) instead of listing each member separately. For a list of metadata types that allow the wildcard character, see the “Allows Wildcard (*)?” column in Metadata Types.

  You specify Security in the <members> element and Settings in the name element when retrieving the SecuritySettings component type.

  Note

• <name> contains the metadata type, for example CustomObject or Profile. There is one name defined for each metadata type in the directory. Any metadata type that extends Metadata is a valid value. The name entered must match a metadata type defined in the Metadata API WSDL. See Metadata Types for a list.
• <version> is the API version number used when deploying or retrieving the .zip file. Currently the valid value is 32.0.

For more sample package.xml manifest files that show you how to work with different subsets of metadata, see Sample package.xml Manifest Files.

To delete items, use the same procedure, but also include a delete manifest file named destructiveChanges.xml. To bypass the Recycle Bin, see purgeOnDelete.

The format of destructiveChanges.xml is the same as package.xml, except that wildcards are not supported.

The following is a sample destructiveChanges.xml file that names a single custom object to be deleted:

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>MyCustomObject__c</members>
5        <name>CustomObject</name>
6    </types>
7</Package>

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

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <version>32.0</version>
4</Package>