iSyncSFDocumentation

#File & Attachment Migration

iSyncSF supports migrating Salesforce files, attachments, and documents between orgs as part of a sync template. This guide covers how file migration works, size limits, and how to configure your templates to include files.

#Overview of File Sync in iSyncSF

Salesforce stores files using the ContentVersion object (the file body and metadata) and links them to records via ContentDocumentLink (the association between a file and a record). iSyncSF handles both objects during file migration, ensuring that files are transferred to the target org and linked to the correct records.

The file migration process works alongside the standard record sync. When you include file-related objects in your sync template, iSyncSF:

  1. Identifies all files associated with the records being synced.
  2. Transfers the file content (binary data) to the target org.
  3. Creates ContentDocumentLink records in the target to associate each file with the correct parent record.
  4. Remaps all IDs automatically — the source ContentDocument and ContentVersion IDs are mapped to their new target IDs.

#Supported File Types

iSyncSF can migrate any file type stored in Salesforce, including:

All standard file formats are supported — PDFs, images, Word documents, spreadsheets, CSVs, and any other format that Salesforce can store.

#File Size Limits and Transfer Behavior

iSyncSF uses a hybrid transfer approach based on file size:

File Size Transfer Method Details
Up to 5 MB Direct org-to-org transfer The file is encoded and sent directly from the source org to the target org as part of the standard sync callout. No additional setup is required.
Over 5 MB (up to 2 GB) External relay service Files exceeding 5 MB are routed through an external streaming relay service that transfers the file content without loading it entirely into memory. This bypasses Salesforce governor limits on heap size and callout body size.

Why the 5 MB Threshold?

Salesforce imposes strict governor limits that prevent large binary data from being processed in Apex: the heap size limit is 6 MB in synchronous context and 12 MB in asynchronous context, and the HTTP callout body limit is 12 MB. Base64-encoding a 5 MB file produces approximately 6.7 MB of data, which approaches these limits. Files under 5 MB transfer safely within these constraints; files over 5 MB require the streaming relay to avoid governor limit errors.

Setting Up Large File Migration

To enable migration of files larger than 5 MB:

  1. Navigate to the Setup Assistant in iSyncSF.
  2. Open the File Migration tab.
  3. Follow the guided setup to configure the external relay service, including creating Connected Apps on both orgs with the content and api scopes.
  4. Use Test Connection and Validate Both Orgs to verify the configuration.
  5. Click Enable File Migration to activate the feature.

Monitoring Large File Transfers

Large files in transit show status code 11 ("Sent to File Migration Service") in the DataSyncAuditLog. Once the relay completes the transfer, the status is updated to the final result (inserted or error). If a large file transfer fails, the error details are recorded in the audit log.

#How to Include Files in a Sync Template

To include files in your sync, you need to configure the template to process the file-related objects:

  1. Add the parent object first. Ensure the object that owns the files (for example, Account, Case, or Opportunity) is already in your template with the correct sequence number.
  2. Configure file relationships. In the template line for the parent object, enable the Include Relationships option and ensure ContentDocument-related relationships are included. iSyncSF will automatically discover and include associated files during the scan phase.
  3. Set the Migrate Content From option. On the template line, use the MigrateContentFrom setting to specify how file content should be sourced. This tells iSyncSF which content relationships to follow when discovering files.
  4. Run Preview/Scan. The scan phase will identify all files associated with the records matching your template line criteria and create audit log entries for them.
  5. Execute the sync. Files are transferred during the sync execution phase along with the parent records.

In Salesforce, the ContentDocumentLink object connects a file (ContentDocument) to a record. When iSyncSF migrates files, it automatically handles the creation of ContentDocumentLinks in the target org:

#Best Practices for File Migration

Plan for Storage

Files consume file storage in the target org. Before migrating, check the target org's available file storage to ensure there is enough capacity. Salesforce storage limits vary by edition and license count.

Sync Parent Records First

Files must be linked to records that already exist in the target org. Always ensure the parent objects (Account, Contact, Case, etc.) are synced before their associated files. Use the Sequence field on template lines to enforce the correct order.

Use Smaller Batch Sizes for File Objects

File transfers involve binary data, which is significantly larger than standard record data. Reduce the MaxBatchSize on the Object Settings for file-related objects to prevent callout size limit errors. A batch size of 10–25 is recommended for ContentVersion objects.

Monitor Large File Transfers

Large files (over 5 MB) are processed asynchronously via the relay service. The transfer happens in the background after the main sync batch completes. Check the DataSyncAuditLog for status code 11 records and wait for them to update to their final status before considering the sync complete.

Handle Existing Files

If a file already exists in the target org (from a previous sync run), iSyncSF can update the existing ContentDocument rather than creating a duplicate. This is handled automatically when the audit log contains a previous destination record ID for that file.

Security Considerations

File migration respects Salesforce security: