Special Behavior in Deployments

Approval Processes

• If the approval page fields include any custom fields on standard objects, manually add those custom fields to outbound change sets. The View/Add Dependencies option for selecting change set components doesn’t include these fields.
• If the approval process references any post templates that contain custom fields, resave those post templates in the originating organization before adding them to the change set. From Setup, in the Quick Find box, enter Post Templates, then select Post Templates. For each post template, click Edit and then Save.
• Change sets don’t include the order of active approval processes from the source. Sometimes it’s necessary to reorder the approval processes in the destination after deployment.
• If you change the Unique Name of an approval process that previously was included in a change set and deployed in another organization, and you resend the approval process via a change set, a new approval process is created upon deployment in the other organization. The previously deployed approval process isn’t modified.

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, take one of these steps.

• 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.

If a record is created in an Apex test, the test record isn’t marked as viewed. Therefore, Apex tests with queries that filter by LastViewedDate fail during deployment and can cause code coverage failures. To mark a record as viewed in an Apex test, first use the FOR VIEW clause, and then filter by LastViewedDate.

This example Apex test uses the FOR VIEW clause before filtering by LastViewedDate.

@isTest
public class AccountViewTest {

    @testSetup
    static void myTestSetup() {
        Account a = new Account();
        a.Name = 'Test Account';
        insert a;
    }

    @isTest
    static void testMethod1() {
        List<Account> aForView = [Select Id, Name from Account LIMIT 1 FOR VIEW];
        List<Account> a = [Select Id, Name from Account where LastViewedDate = TODAY LIMIT 1];
        System.assertEquals(1, a.size());
    }

}

Custom Fields

• To change the data type of a custom field, you can use change sets. But the deployment is sometimes delayed as many records are updated. Consider changing the target through the user interface instead.

Custom Objects

• You can 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 overall default.
• Simultaneously inserting a custom object, updating the sharingModel field for an object, and adding a new owner-based sharing rule isn’t supported. Instead, three separate deployments are required. First deploy the custom object, then deploy the updated sharingModel for the object, and then deploy the new owner-based sharing rule. You can update the sharingModel field and add a criteria-based or guest user sharing rule in one deployment.

Flows

• If you plan to deploy a flow with change sets, consider limitations in migration support. Make sure that your flows reference only fields and components that are available in change sets.
• You can include only one version of a flow in a change set.
• If the flow has no active version when you upload the outbound change set, the latest inactive version is used.
• When you view the dependent components for the change set, the Component Dependencies page lists the dependencies for <i>all</i> versions of the flow. Add all interdependent components for the relevant flow version to the outbound change set.
• An active flow in a change set is deployed to its destination as inactive. Activate the flow manually after deployment.
• Deploying or redeploying a flow with change sets creates a version of the flow in the destination.
• In production orgs, you can enable the setting to deploy a new active version of a process or flow via change sets or Metadata API. The setting doesn't appear in non-production orgs (such as scratch, sandbox, and developer orgs), because you can always deploy a new active version.

Permissions

See Permission Sets and Profile Settings in Change Sets

Page Layout

A deployment containing a profile and record type, but not the assigned page layout for that record type, removes the existing layout assignment from the profile for that record type. Always include all page layouts for all required record types in the change set.

Picklist Values

Values for a picklist field in a target that aren’t included in the change set are set to inactive.

For example, if the target’s picklist includes an active value of 1, and the change set’s picklist doesn’t include 1 as a value, 1 changes from active to inactive in the target.

Sharing

Simultaneously updating the sharingModel field for an object and adding a new owner-based sharing rule isn’t supported. You can add an owner-based sharing rule when the overall default is public, and then update the sharingModel, which results in a single sharing recalculation. You can deploy a criteria-based or guest user sharing rule and changes to the sharingModel field together using change set components.

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, take one of these steps.

• 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.

If a record is created in an Apex test, the test record isn’t marked as viewed. Therefore, Apex tests with queries that filter by LastViewedDate fail during deployment and can cause code coverage failures. To mark a record as viewed in an Apex test, first use the FOR VIEW clause, and then filter by LastViewedDate.

This example Apex test uses the FOR VIEW clause before filtering by LastViewedDate.

@isTest
public class AccountViewTest {

    @testSetup
    static void myTestSetup() {
        Account a = new Account();
        a.Name = 'Test Account';
        insert a;
    }

    @isTest
    static void testMethod1() {
        List<Account> aForView = [Select Id, Name from Account LIMIT 1 FOR VIEW];
        List<Account> a = [Select Id, Name from Account where LastViewedDate = TODAY LIMIT 1];
        System.assertEquals(1, a.size());
    }

}

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, resave those post templates in the originating organization before adding them to the change set. From Setup, in the Quick Find box, enter Post Templates, and then select Post Templates. For each post template, click Edit and then Save.
• The metadata doesn’t include the order of active approval processes. It can be necessary to reorder the approval processes in the destination after deployment.
• If you change the Unique Name of an approval process that previously was included in a change set and deployed in another organization, and you resend the approval process via a change set, a new approval process is created upon deployment in the other organization. The previously deployed approval process isn’t modified.

Authentication Providers

Beginning in November 2022, if a change set includes an authentication provider with a consumer secret defined, the consumer secret is changed to a placeholder value. You must insert the consumer secret manually during change set deployment.

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

Simultaneously inserting a custom object, updating the sharingModel field for an object, and adding a new owner-based sharing rule isn’t supported. Instead, three separate deployments are required. First deploy the custom object, then deploy the updated sharingModel for the object, and then deploy the new owner-based sharing rule. You can update the sharingModel field and add a criteria-based or guest user sharing rule in one deployment.

Connected App

• You can’t set the consumerKey in Metadata API. It’s 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 is generated in the destination.
• Mobile settings of connected apps aren’t supported in change sets and must be manually migrated.

Groups

Members of the public group aren’t 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 these 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 can’t 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. But 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 the assignments 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 aren’t 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 doesn’t include a picklist value of 1, 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, 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.

Custom fields on the ContentVersion object are available to all profile users. When you export profile metadata, all custom fields are exposed.

Sharing

• Using API version 29.0, you can’t change the sharingModel of an object using Metadata API. Manually change the target 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.
• Simultaneously updating the sharingModel field for an object and adding a new owner-based sharing rule isn’t supported in Metadata API. You can add an owner-based sharing rule when the overall default is public, and then update the sharingModel, which would result in a single sharing recalculation. You can deploy a criteria-based or guest user sharing rule and changes to the sharingModel field together using the Metadata API.

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.