Salesforce has two ways to attach files to records. Prior to the introduction of Lightning, there were simple attachments. These are stored in the Attachment object, which has a single ParentId field that specifies which record the attachment is for. With Lightning, Salesforce introduced Files as a replacement for the older attachment system. Instead of a single object, this new style of attachment uses a more complicated set of objects. The ContentVersion object stores the binary data,

ContentDocument is used to group multiple versions of a single file, and the new ContentDocumentLink junction object takes the place of the ParentId field, allowing a single file to be attached to many other records if needed.

Both types of attachments are supported for data deployment and backup restores in Gearset.

First, include the object type you want to deploy attachments for in the deployment. Many different objects support attachments. For the purposes of this example, we've chosen Account. If necessary, add filters to this object to deploy only the records that are needed.

To deploy the attachments for this Account: on the first page of the data deployment, add the type of attachment you want to deploy.

For attachments added before Lightning, choose the Attachment object. And for attachments added in Lightning, choose ContentDocumentLink. In both cases, enable the 'Filter using parent object' filter to tell Gearset to deploy the attachments associated with the other records that are included in the deployment.

For more complicated deployments, it may be necessary to use the dropdown to select the object whose attachments should be deployed.

There are a few things to check on the second page (related objects):

  • Binary objects can only be deployed by a 'create' step, so Attachment or ContentDocumentLink must be set to 'Create new records'.

  • When deploying Files, ContentDocumentLink will appear on the left-hand side of the page and ContentDocument and ContentVersion will appear as related objects on the right-hand side.

  • All three objects must be selected for deployment for the attachments to be successfully created on Salesforce.

  • ContentDocument is not deployed by Gearset, but instead created by Salesforce on the target organization, so it uses the special deployment type 'Read back created records', which looks up which records were created.

This is all that's needed to configure the deployment. It's possible to check that the attachments will be deployed by looking at the deployment plan. The fetch step will be filtered by the 'parent' object, and the attachment itself will be deployed using a 'create binary' step.

Restore from a backup

When restoring from a backup, it's common to make the mistake of choosing the wrong run to restore from.

Imagine you have run, X, where you back up the file, and a subsequent run, Y, where the file deletion is detected. You will need to go to Y to take the ID information of what you want to restore, but then go to X and click on Restore snapshot data to start the configuration.


If you're not the owner of the attachments you are trying to deploy, then you may encounter an error message like the following:

Documents in a user's private library must always be owned by that user

The solution to this is to exclude the User object from the deployment on the related objects page. This will ensure that the attachments are created with your deployment user (and not the original owner) set as the owner, meaning that we won't attempt to store the attachments in the original user's private library.

Did this answer your question?