Metadata API Developer Guide
jNewer Version Available
Special Behavior in Metadata API Deployments
Important considerations for specific types and contents
of a deployment.
When deploying changes to a Salesforce org, consider how individual components in your deployment behave so you’re including all the necessary changes. Use the following information to determine what to include in your deployment, and how the changes appear in the destination org.
- Apex Classes and Apex Triggers
- By default, changes to Apex code that has Apex jobs pending or in progress can’t be
deployed. To deploy these changes, do one of the following.
- Cancel Apex jobs before deploying changes to Apex code. Reschedule the jobs after the deployment.
- Enable deployments with Apex jobs in the Salesforce user interface in the Deployment Settings page.
- Approval Processes
-
- To use approval processes on Salesforce Knowledge articles with the Metadata API, the article type must be deployed. For article version (_kav) in approval processes, the supported action types are: Knowledge Action, Email Alert, Field Update, and Outbound Message.
- If the approval process references any post templates that contain custom fields, then you need to resave those post templates in the originating organization before adding them to the change set. From Setup, enter Post Templates in the Quick Find box, then select Post Templates. For each post template, click Edit and then Save.
- The metadata doesn’t include the order of active approval processes. You might need to reorder the approval processes in the destination org after deployment.
- If you change the Unique Name of an approval process that was previously included in a change set and deployed in another organization, and you resend the approval process via a change set, a new approval process will be created upon deployment in the other organization. The previously deployed approval process will not be modified.
- Custom Fields
- Starting in API version 30.0, when deploying a new custom field, the default values for the editable and readable fields in profile field permissions are false. To override the default values, include field permissions for the new field in your profiles.
- Custom Objects
- Using API version 29.0, you can’t change the sharingModel
of an object using Metadata API. You must manually make this change to the target org
through the user interface.
Starting with API version 30.0, you can change the sharingModel of an object for internal users using Metadata API and the user interface.
- Connected App
-
- You cannot set the consumerKey in Metadata API. It is included in a retrieve operation for informational purposes. If you try to move the connected app to another org, you must remove the consumerKey from the .zip file before the deployment to an org. A new key will be generated in the destination org.
- Mobile settings of connected apps are not supported in change sets and must be manually migrated.
- Groups
-
Members of the public group are not migrated when you deploy the group type.
- Master-Detail Relationships
- A Metadata API
deployment that includes Master-Detail relationships deletes all detail records in
the Recycle Bin in the following cases.
- For a deployment with a new Master-Detail field, soft delete (send to the Recycle Bin) all detail records before proceeding to deploy the Master-Detail field, or the deployment fails. During the deployment, detail records are permanently deleted from the Recycle Bin and cannot be recovered.
- For a deployment that converts a Lookup field relationship to a Master-Detail relationship, detail records must reference a master record or be soft-deleted (sent to the Recycle Bin) for the deployment to succeed. However, a successful deployment permanently deletes any detail records in the Recycle Bin.
- Page Layout
- A deployment containing page layout assignments replaces all existing page layout assignments in the destination org with those specified in the .zip file. Existing page layouts in the org disappear if they’re not included in the .zip file. Always include all page layouts for all required record types in the .zip file.
- Picklist Values
- Values for a picklist field in a target org that are not included in the metadata are set to inactive.
- For example, if the target org has a picklist that includes an active value of 1, and the metadata does not include 1 as a value for the picklist, 1 changes from active to inactive in the target org.
- Profiles
- If a package includes a profile with a name that doesn’t exist in the target org, a new profile is created with that name. If the deployed profile doesn’t specify any permissions or settings, the resulting profile consists of all the permissions and settings in the Standard Profile.
- Sharing
-
- Simultaneously updating the sharingModel field for an object and adding a new sharing rule isn’t supported in Metadata API, regardless of which object you’re updating. For example, you can add a sharing rule when the org-wide default is public, and subsequently update the sharingModel. This would result in a single sharing recalculation.
- You might encounter an error if you’re deploying a change set with a custom object that has a parent-child relationship without the master/detail field in the same change set. To resolve this error, include the master/detail custom field in the change set, even if you haven’t changed the org-wide default.
- Workflow
- Test mode for flow triggers isn’t supported in the Metadata API. If you want a flow trigger to run the latest flow version when an administrator causes the workflow rule to fire, enable test mode via the user interface after deployment.