Overview

Some platforms keep snapshots of every change made to files. Version preservation determines how file versions are handled in the transfer. If version preservation is enabled for a job, the application will attempt to preserve all or the specified number of versions of the files if supported on both platforms.

Each Box account type is limited to the maximum number of file versions that can be accessed. This means that while the UI shows as many versions as you upload, you can only access a certain number of versions. In addition to the default version maximum, account administrators can set the maximum number of file versions to save and track for the account. Both the default file version maximum and any custom version settings added to the Box account affect version transfers. Please refer to Box’s version history documentation to understand the version limitations of your account.

Enabling Preservation

When creating a job through the user interface, version preservation is enabled on the Behaviors page. The Preserve file versioning between locations toggle indicates if the feature is enabled or disabled for the job. By default, version preservation is enabled (green toggle with a check mark). Select the toggle to disable it for the job (gray toggle with an x).The “preserve” options determine if DryvIQ will preserve versioning in the transfer. The default option is to preserve All versions.

If you want to preserve a limited number of versions, select the Limited versions option and specify the number of versions you want to preserve. The specified number of versions will be preserved on the source and destination. Note that this value is contingent on what each platform supports.

Enabling Version Preservation Through the REST API

When creating a job using the REST API, version preservation is defined in the job in the “versioning” block of the job JSON. Through this block, you can configure the preserve, select, from_source, and from_destination options.

Preserve

The preserve value indicates which items you want to preserve.

none: This option turns version detection off, and DryvIQ will not preserve versions in the transfer. Only the latest version of the file will be transferred on the initial job run. Version detection will not be used on subsequent job runs, so new versions added to the file after the initial run will not be identified or transferred.
native: This option turns version preservation on, and DryvIQ will preserve versions in the transfer. When this option is selected, use the “select” options to control which versions should transfer. This is the default “preserve” option.

Select

If you select “native” as the preserve option, use the "select" option to specify which versions should transfer.

all: DryvIQ will transfer all versions of the file. However, if the number of versions exceeds the version limit of the destination platform, DryvIQ will transfer the most recent file version and continue to transfer the versions in order until the version limit is reached. You can configure the number of versions you want to maintain on the source and/or destination. (See From Source and From Destination below for more information.)
latest: DryvIQ will only transfer the latest version of the file. If DryvIQ identifies a new version of the file has been added after the initial job run, DryvIQ will transfer the newest version on subsequent job runs, even if there are many versions on the source.
published: If a platform supports the concept of publishing files, DryvIQ will only transfer the “published” versions of the file. (This option can also be used for Dropbox connections to ensure transfer of true file versions. See Transferring Versions with Dropbox below for more information.)
unpublished: If a platform supports the concept of publishing files, DryvIQ will only transfer the “unpublished” versions of the file (a version that was removed from a previously published state).

From Source

This options allows you to set the default number of versions you want to maintain on the source platform. When set, DryvIQ will only keep the specified number of versions–deleting any versions over the set number.

From Destination

This option allows you to set the default number of versions to maintain on the destination platform. When set, DryvIQ will only transfer the set number of versions.

Not all platforms support version deletes. When a specific transfer value is set and the destination platform doesn’t support version deletes, DryvIQ will use the following logic to determine how it handles transferring the versions:

If the file doesn’t exist on destination, DryvIQ will respect the version limit set and only transfer the set number of versions during the initial copy/migration.

If the file exists on destination, DryvIQ will migrate all new versions of the file from the source to the destination, even if it results in exceeding the file version limit set on version count. This ensures all new content is transferred. DryvIQ will log a warning to inform the user that the transfer took place and resulted in the transfer count being exceeded.

Example JSON

Native Preservation and Latest Version

POST {{url}}v1/jobs

{
    "name":"Preserve Latest Versions",
    "kind": "transfer",
    "transfer": {
        "transfer_type": "copy",
        "batch_mode": "always",
    	"versioning": {
        	"preserve": "native",
        	"select": "latest"
    	},
        "source": {
            "connection": { "id": "{{cloud_connection_source}}" },
            "target": {
                "path": "/SourcePath"
            }
        },
        "destination": {
            "connection": { "id": "{{cloud_connection_destination}}" },
            "target": {
                "path": "/DestinationPath"
            }
        }
    },
    "schedule": {
        "mode": "manual"
    },
    "stop_policy": {
        "on_success": 2
    },
    "category": {
    	"name": "Preserve Latest Version Job Reports"
   }
}

Setting Version Limits

POST {{url}}v1/jobs

{
    "name":"Preserve set number of versions",
    "kind": "transfer",
    "transfer": {
        "transfer_type": "copy",
        "batch_mode": "always",
    	"versioning": {
        	"preserve": "native",
        	"select": "all",
			"from_source": "6",
			"from_destination": "6"
    	},
        "source": {
            "connection": { "id": "{{cloud_connection_source}}" },
            "target": {
                "path": "/SourcePath"
            }
        },
        "destination": {
            "connection": { "id": "{{cloud_connection_destination}}" },
            "target": {
                "path": "/DestinationPath"
            }
        }
    },
    "schedule": {
        "mode": "manual"
    },
    "stop_policy": {
        "on_success": 2
    },
    "category": {
    	"name": "Preserve Latest Version Job Reports"
   }
}

Transferring Versions with Dropbox

The Dropbox platform treats content version history differently than other cloud platforms, with each native move and rename tracked as a new version. In order to only transfer true version history, enable the advanced scripting option on step 6 during job creation and copy the following JSON:

{
"transfer": {
"versioning": {
            "preserve": "native",
            "select": "published"
        }
    }
}

DryvIQ Migrate

Version Preservation