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 have Apex jobs pending or in
progress can’t be deployed. To deploy these changes, do one of the following.
- Cancel Apex jobs before deploying changes to Apex code. Reschedule the jobs after the deployment.
- Enable deployments with Apex jobs in the Salesforce user interface in the Deployment Settings page.
- Approval Processes
-
- To use approval processes on Salesforce Knowledge articles with the Metadata API, the article type must be deployed. For article version (_kav) in approval processes, the supported action types are: Knowledge Action, Email Alert, Field Update, and Outbound Message.
- If the approval process references any post templates that contain custom fields, then you need to resave those post templates in the originating organization before adding them to the change set. From Setup, enter Post Templates in the Quick Find box, then select Post Templates. For each post template, click Edit and then Save.
- The metadata doesn’t include the order of active approval processes. You might need to reorder the approval processes in the destination org after deployment.
- If you change the Unique Name of an approval process that was previously included in a change set and deployed in another organization, and you resend the approval process via a change set, a new approval process will be created upon deployment in the other organization. The previously deployed approval process will not be modified.
- Custom Fields
- Starting in API version 30.0, when deploying a new custom field, the default values for the editable and readable fields in profile field permissions are false. To override the default values, include field permissions for the new field in your profiles.
- Custom Objects
- Using API version 29.0, you
can’t change the sharingModel of an object using the Metadata API. You must manually make this change
to the target org through the user interface.
Starting with API version 30.0, you can change the sharingModel of an object for internal users using the Metadata API and the user interface.
- Connected App
-
- You cannot set the consumerKey in the Metadata API. It is included in a retrieve operation for informational purposes. If you try to move the connected app to another org, you must remove the consumerKey from the .zip file before the deployment to an org. A new key will be generated in the destination org.
- Mobile settings of connected apps are not supported in change sets and must be manually migrated.
- Named Credentials
-
The following callout options for named credentials can be set only via the user interface. If the default values aren’t appropriate in the destination org, the admin for that org must manually configure the named credential after deployment.
- Generate Authorization Header—Default: Enabled
- Allow Merge Fields in HTTP Header—Default: Disabled
- Allow Merge Fields in HTTP Body—Default: Disabled
- Page Layout
- A deployment containing page layout assignments replaces all existing page layout assignments in the destination org with those specified in the .zip file. Existing page layouts in the org disappear if they’re not included in the .zip file. Always include all page layouts for all required record types in the .zip file.
- Profiles
- If a package includes a profile with a name that doesn’t exist in the target org, a new profile is created with that name. If the deployed profile doesn’t specify any permissions or settings, the resulting profile consists of all the permissions and settings in the Standard Profile.
- Sharing
-
- Simultaneously updating the sharingModel field for an object and adding a new sharing rule isn’t supported in the Metadata API, regardless of which object you’re updating. For example, you can add a sharing rule when the org-wide default is public, and subsequently update the sharingModel. This would result in a single sharing recalculation.
- You might encounter an error if you’re deploying a change set with a custom object that has a parent-child relationship without the master/detail field in the same change set. To resolve this error, include the master/detail custom field in the change set, even if you haven’t changed the org-wide default.
- Workflow
- Test mode for flow triggers isn’t supported in the Metadata API. If you want a flow trigger to run the latest flow version when an administrator causes the workflow rule to fire, enable test mode via the user interface after deployment.