How to Migrate to DX Format

Updated 1 month ago by Copado Solutions

Please note that DX format is a pilot project and there are some limitations with other features. There are currently no more places available for this pilot.

Introduction to DX Source Format

Salesforce DX source format provides a new project structure and source format that separates metadata into more granular folders. This can be very useful when working with version control systems  as source files are split up into smaller files, thus making it easier for you to find the piece of information you are looking for. 

Copado supports the creation of Git Repository records that can be configured to use the DX source format. All you need to do is select DX from the Source Format picklist field when setting up a new Git Repository record.

Benefits of DX Format

https://copado.helpdocs.io/app/settingsHere are some of the advantages of working with the DX format:

  • Merge conflicts will be reduced drastically. Since the nested components of objects are now stored in separate folders, conflicts will no longer occur if different users apply changes to the same object in different user stories. A semantic merge will no longer be required. Copado will still support the smart auto resolve functionality for the other metadata types and they will work as usual.
  • Finally, switching to DX format won’t pose a risk. Since you have to create a new repository, all the metadata before the migration will be stored in your old repository, so all your branches will be backed up.

Migration Process

Before switching to DX format, it is important to note that Copado doesn’t allow to work with hybrid repositories that contain branches both in metadata and DX format. Therefore, if you want to store your metadata in Git using the new format, you will need to create a new repository and recreate the different branches using Copado.

To create a new repository in DX format and then link it to your pipeline, follow the steps below:

  1. Create a new repository in your Git server.
  2. Create a new Git Repository record in Copado. For more information about how to do this, check out the article Git Repository Overview
    1. Add an authentication (HTTP or SSH).
    2. Make sure you select DX in the Source Format field.
  3. Create a Git Snapshot record for every environment in your pipeline. For more information about how to do this, check out the article Git Snapshot Overview.
    1. When providing the name of the branches, follow the same naming convention you had in the Metadata API repository.
  4. Take a snapshot of the master branch.
  5. Create all the environment branches from the master branch.
  6. Inform your company of this change as the feature branches and the promotion branches will need to be recreated.
  7. Update your pipeline Git Repository related record to the new one you created in step 2.
  8. Recreate the feature branches:
    1. Use the recommit files functionality to auto select the items that are contained in the user stories. 
  9. Recreate the promotion branches:
    1. Create a new deployment out of each Promotion record.

How to Go Back to the Metadata API Format

If you want to switch back to the Metadata API format, you can use the same strategy you used to change to DX format:

  1. Create a new Metadata API repository or use an existing repository in your Git server.
  2. Create a new Git Repository record in Copado*.
    1. Add an authentication (HTTP or SSH).
    2. Make sure you select Metadata in the Source Format field.
  3. Create a Git Snapshot record for every environment in your pipeline*.
    1. When providing the name of the branches, follow the same naming convention you had in the DX format repository.
  4. Take a snapshot of the master branch. This is to make sure all the latest changes in production are in a version control system.
  5. Create all the environment branches from the master branch.
  6. Inform your company of this change as the feature branches and the promotion branches will need to be recreated.
  7. Update your pipeline Git Repository related record to the new or existing one mentioned in Step 2.
  8. Recreate the feature branches:
    1. Use the recommit files functionality to auto select the items that are contained in the user stories. 
  9. Recreate the promotion branches:
    1. Create a new deployment out of each Promotion record.

*Steps 2 and 3 will not be required if you didn’t delete the records after migrating to DX.

If you need assistance with the setup and migration to the DX format, Copado’s Professional Services team can help you with this. Please bear in mind that the amount of time this will take will depend on how big your pipeline is as well as on the work in progress your team has. For more information, reach out to your customer success manager.


How did we do?