What file structure is required when setting deployOptions.singlePackage to False

Question

In using the metadata API to delete validation rules today, I ran into the issue described in this post, where i needed to set deployOptions.singlePackage to true, in order for the rules to get deleted.

I understand that this setting indicates the structure of the zip file, as per the docs on the deploy method.

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

However, it seems like all of the samples in the documentation use the structure where singlePackage = true. I have not been able to find an example of deploying with singlePackage = false.

Given that the default value (at least in workbench) is false, I would like to understand what file structure is expected in order to successfully deploy using singlePackage = false.

Answer 1

I thought I'd try this, but in reverse.

Using my new found knowledge that you can pull a changeset with the Metadata API I used two random unmanaged packages as samples for a retrieve operation via Workbench.

Note that SinglePackage is unchecked and both changeset names are defined.

After Retrieve:

The fileProperties above do a pretty good job of indicating the zip structure. At the top level are folders with each of the unmanaged package names.

For fun I:

• extracted the Zip
• updated the description field in the package.xml files with a "- Updated" suffix
• zipped the top level folders back up into a single zip again.
• deployed the result with workbench (with Single Package unchecked).

Workbench multiple packages:

Deploy result:

The unmanaged package descriptions were updated with my "- Updated" suffix.

---

Do keep and eye on Salesforce DX and the packaging 2.0 changes. I wouldn't be surprised to see more utilization or changes in this area going forward.

Answer 2

Similarly for retrieving, if you try to retrieve multiple packages on with a single request,

./retrievePagkage.txt

<?xml version="1.0" encoding="utf-8" ?><env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
    <env:Header>
        <n1:SessionHeader xmlns:n1="http://soap.sforce.com/2006/04/metadata">
            <n1:sessionId><sessionid></n1:sessionId>
        </n1:SessionHeader>
    </env:Header>
    <env:Body>
        <n1:retrieve xmlns:n1="http://soap.sforce.com/2006/04/metadata">
            <n1:retrieveRequest type="tns:RetrieveRequest">
                <n1:apiVersion type="xsd:double">38.0</n1:apiVersion>
                <n1:singlePackage type="xsd:boolean">TRUE</n1:singlePackage>
                <n1:unpackaged type="tns:Package">
                    <types> 
                        <members>*</members>
                        <name>ApexClass</name>
                    </types>
                    <version>38.0</version>
                </n1:unpackaged>
                <n1:packageNames type="xsd:String">MyManagedPackage</n1:packageNames>
                <n1:packageNames type="xsd:String">MyPkg</n1:packageNames>
            </n1:retrieveRequest>
        </n1:retrieve>
    </env:Body>
</env:Envelope>

.

$ curl https://<instance>.salesforce.com/services/Soap/m/35.0/<orgid> -d @retrievePackage.txt -H 'Content-Type: text/xml' -H "SOAPAction: ''" -v

with singlePackage set to true, you will get an error message:

INVALID_CROSS_REFERENCE_KEY: More than 1 package retrieved with single package flag

Setting singlePackage to true will successfully retrieve your packages: