How to Migrate Content from Amazon WorkDocs

Amazon WorkDocs provides two methods for migrating data out of a WorkDocs site. This post provides an overview of these methods and links to detailed steps to run, troubleshoot and optimize each migration method.

This method allows WorkDocs site administrators or AWS console users to initiate a migration job from the AWS WorkDocs console. The migration tool will zip and export all the data for a WorkDocs site to an Amazon S3 bucket in the same region and account.

The tool creates a zip file for each user of the WorkDocs site. Each user’s zip file will contain their folders, files, and versions. The comments and permissions for each file/folder in the zip will be added in a separate .csv file located at the root level of the zipped folder. The zip file will preserve the folder structure used within the WorkDocs service.

This method is ideal for migrating all data from the WorkDocs site in one action. This method is helpful to automate a migration job for a large WorkDocs site that has many users, folders, and files. Once the data has been exported to S3, additional tools or scripts can be used to further transfer or move the data from S3 to another location, for example a local drive.

Option A: WorkDocs Web Client

This method allows WorkDocs end-users to bulk download files and folders from the WorkDocs web client. Users must have the WorkDocs Companion App installed. Users can use the multi-select checkboxes to select all files and folders they wish to download. Once the download job has started, the WorkDocs Companion App will download all selected files and folders to the user’s desktop.

This method allows each end-user to migrate the files and folders they own and those shared with them. WorkDocs admins cannot migrate data on another user’s behalf and cannot download the entire site’s data using this method. This method will not download any prior versions, comments, or permissions – only the latest version of files and folders. For files larger than 5-GB please refer to Method 1 or Option B of Method 2.

This method is ideal for individual end users who wish to manually download only their files and folders from their WorkDocs site to their local desktop.

Option B: WorkDocs Drive Client on Windows

This method makes files in WorkDocs appear like a hard drive, with W: drive letter. You can use any desktop application to copy files from WorkDocs to other hard drives or removable drives. This method allows users to migrate the files and folders they own and those shared with them. This method will not download any prior versions, comments, or permissions – only the latest version of files and folders.

This method is ideal for individual end users who wish to manually download only their files and folders from their WorkDocs Drive location to another location on their local desktop. This method is ideal to download large sized files (> 5-GB).

Method 1: How to use the Data Migration Tool

Pre-requisites

You must have the following items to use the migration tool.

1. An Amazon S3 bucket in the same AWS account and region of your WorkDocs site. For information about creating an Amazon S3 bucket, see Creating a bucket, in the Amazon S3 User Guide. Your bucket must use the same IAM account and reside in the same Region as your WorkDocs site. Also, you must block public access to the bucket. For more information about doing that, see Blocking public access to your Amazon S3 storage, in the Amazon S3 User Guide.

To grant Amazon WorkDocs permission to upload your files, configure the bucket policy as follows:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowWorkDocsFileUpload",
            "Effect": "Allow",
            "Principal": {
                "Service": "workdocs.amazonaws.com"
            },
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::BUCKET-NAME/*",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "AWS-ACCOUNT-ID"
                },
                "ArnLike": {
                    "aws:SourceArn": "arn:aws:workdocs:REGION:AWS-ACCOUNT-ID:organization/WORKDOCS-DIRECTORY-ID"
                }
            }
        }
    ]
}

Notes:

2. An IAM policy. To start a migration on the WorkDocs console, the IAM calling principal must have the following policy attached to its permissions set:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowStartWorkDocsMigration",
            "Effect": "Allow",
            "Action": [
                "workdocs:StartInstanceExport"
            ],
            "Resource": [
               "arn:aws:workdocs:REGION:AWS-ACCOUNT-ID:organization/WORKDOCS-DIRECTORY-ID"
            ]
        },
        {
            "Sid": "AllowDescribeWorkDocsMigrations",
            "Effect": "Allow",
            "Action": [
                "workdocs:DescribeInstanceExports",
                "workdocs:DescribeInstances"
            ],
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AllowS3Validations",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketPublicAccessBlock"
            ],
            "Resource": [
                "arn:aws:s3:::BUCKET-NAME"
            ]
        },
        {
            "Sid": "AllowS3ListMyBuckets",
            "Effect": "Allow",
            "Action": [
                "s3:ListAllMyBuckets"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

3. Optionally, you can use an AWS KMS key to encrypt the at-rest data in your bucket. If you do not provide a key, the bucket’s standard encryption setting applies. For more information, see Creating keys, in the AWS Key Management Service Developer Guide. The key is required to be in the same region and account as your WorkDocs site. To use an AWS KMS key, add the following statement to the IAM policy:

{
    "Sid": "AllowKMSMigration",
     "Effect": "Allow",
     "Action": [
        "kms:CreateGrant", "kms:DescribeKey", "kms:ListAliases"
     ],
     "Resource": [
         "arn:aws:kms:REGION:AWS-ACCOUNT-ID:key/KEY-RESOURCE-ID"
     ]
}

Running the Migration

You can migrate multiple sites to an Amazon S3 bucket. You do not need to create one bucket per site. However, you must ensure that your IAM and bucket policies allow multiple sites. Each migration job will be placed at a new S3 prefix.

Note: The tool is limited to one successful migration per a site for each 24-hour period

Steps:

1. 1. 1. Open the Amazon WorkDocs console at https://console.aws.amazon.com/zocalo/.
      2. In the navigation pane, choose ‘My sites’, then select the checkbox next to the site that you want to migrate.
      3. Open the Actions list and choose Migrate Data.
      4. On the Migrate Data site-name page
         1. Enter the URI of your Amazon S3 bucket
         2. Or Choose Browse S3 and follow these steps:
            1. As needed, search for the bucket.
            2. Select the radio button next to the bucket name, then select Choose.
      5. (Optional) Under Notifications, input one or more email addresses and hit enter. The tool sends migration status emails to each recipient. The tool will accept up to 5 email addresses.
      6. (Optional) Under Advanced Settings, select a KMS key to encrypt your stored data.
      7. The following modal shows a completed migration form:

1. 1. 8. Enter migrate in the text box to confirm the migration, then choose Start Migration. An indicator appears and displays the status of the migration. Migration times vary, depending on the amount of data in a site.

When the Migration Finishes

• The tool sends “Success” emails to the addresses entered during setup, if any.
• Your Amazon S3 bucket contains a prefix for the migration job. In turn, that prefix contains a zipped folder for each user. Each user zip contains the user’s folders and files from the site.
• Documents with multiple versions have a _version_creation timestamp identifier. The timestamp uses epoch milliseconds. For example, a document named “HelloWorld.txt” with 2 versions appears as follows:
  • HelloWorld.txt (version 2 – latest version)
  • HelloWorld_version_1707437230000.txt

Using the Migrated Data

Once the migration job has completed, all of your WorkDocs data (files, folders, versions, comments, annotations, and permissions) for each user will be present in your S3 bucket.

For large sites, we recommend provisioning an EC2 instance using a compliant Linux- based Amazon Machine Image to download, unzip and transfer your data from Amazon S3 to your storage provider or destination of choice.

The following steps explain how to download a single user’s zip file at a time. For information about other ways to download files, see Downloading objects, in the Amazon S3 User Guide.

1. Open the Amazon S3 console at https://console.aws.amazon.com/s3/.
2. Select the target bucket and navigate to the site alias.
3. Select the checkbox next to the zipped folder OR Open the zipped folder and select the checkbox next to the file or folder for an individual user.
4. Choose Download.

Limitations

• Each zip file will be at most 50-GB. Users with more than 50-GB of data in WorkDocs will have multiple zip files exported into S3
• If a single file is larger than 50-GB it will not be exported. All files, for the entire site, that are larger than 50-GB will be listed in a CSV file in the same prefix as the zip files. For example, /workdocs/<site-alias>/<created-timestamp-UTC>/skippedFiles.csv. These files can then be downloaded directly from WorkDocs using the WorkDocs API.
• Each user’s zip file will only contain files/folders that they own. Any files and/or folders that have been shared with the user will be in the zip file of the user that owns the files/folders.
• If a folder is empty (contains no nested files/folders) in WorkDocs, it will not be exported
• It is not guaranteed that any data (files, folders, versions, comments, annotations) created after the migration job has been initiated, will be included in the exported data in S3.
• Migrating WorkDocs data to Amazon S3 will be subject to S3 pricing.

Viewing your Migration History

1. Open the Amazon WorkDocs console at https://console.aws.amazon.com/zocalo/.
2. Select the radio button next to the desired WorkDocs site.
3. Open the Actions list and choose Migrate Data.
4. On the Migrate Data site-name page, choose Ongoing Migrations and History.

The migration history appears under Migrations. The following image shows an example history:

Troubleshooting

You can also try these additional steps to ensure you have configured your environment correctly:

• If a migration fails, an error message will be listed in the migration history section. Review the error message in the migration history tab on the WorkDocs Console. If a migration fails, you may remove any partially migrated data that was placed within the prefix in your Amazon S3 bucket
• Check your Amazon S3 bucket settings
• Rerun the migration.

If an issue persists, please contact AWS Support. Please include the WorkDocs Site URL and the Migration Job ID (available in the migration history table)

Method 2: How to Bulk Download using Amazon WorkDocs Clients

Option A: WorkDocs Web Client

Pre-requisites

1. You must install Amazon WorkDocs Companion to complete the following steps. To install Amazon WorkDocs Companion:
   1. Start Amazon WorkDocs and choose Apps. The Apps page appears.
   2. Under Companion App, choose PC or Mac.
   3. The next step depends on your choice.
      1. If you chose PC, the Opening Amazon WorkDocs Companion.msi dialog box appears. Choose Save File.
      2. If you chose Mac, the Opening Amazon WorkDocs Companion.pkg dialog box appears. Choose OK.
   4. Either choice saves the file to your download folder.
   5. When the download finishes, open the file and follow the steps in the installation program.
2. When you use Amazon WorkDocs Companion to download files/folders, your directory structures, file names, and file content remain intact. File ownership, permissions, and versions are not retained.

Steps

Site users can download files/folders by following the steps listed below. You can also set up a shared folder in your WorkDocs site, have your users move the files to that folder, then download the folder using the steps below. You can also transfer ownership to yourself and perform the downloads. To download Microsoft Word documents with comments, see Downloading Word documents with feedback, in the Amazon WorkDocs User Guide.

1. Sign in to Amazon WorkDocs.
2. Use the multi-select checkboxes next to each file or folder or alternatively use the checkbox in the table header to select all files/folders.
3. Open the Actions menu and choose Download.
   1. On a PC, downloaded files land by default in Downloads/WorkDocsDownloads/folder name.
   2. On a Macintosh, files land by default in hard drive name/Users/user name/WorkDocsDownloads.

Option B: WorkDocs Drive Client on Windows

Pre-requisites

• You must install Amazon WorkDocs Drive on a Windows machine to complete the following steps. For more information, see Installing Amazon WorkDocs Drive.
• You can use Amazon WorkDocs Drive to download files larger than 5 GB.
• When you use Amazon WorkDocs Drive to download files and folders, your directory structures, file names, and file content remain intact. File ownership, permissions, and versions are not retained.

Steps

WorkDocs Drive makes files in WorkDocs appear as hard drive in Windows, making available drive letter W: to access the files. For example:

To move data, you can use “copy & paste”, “cut & paste”, or “drag & drop”, to paste selected files into the new location. You can also use any application of choice, such as robocopy, to copy files from W: to any other hard drive or removable drive.

To download from WorkDocs Drive using File Explorer

1. Start File Explorer and open your W: drive.
2. Select the folders or files that you want to download from WorkDocs.
3. Right-click on the selected items and choose Copy, then Paste the copied items into their new location OR Drag and drop the selected items to their new location using File Explorer.
4. Delete the original files from W: drive. This will remove files from WorkDocs cloud.

To download from WorkDocs Drive using robocopy

1. Start Windows PowerShell
2. Execute command: “robocopy W: C:destination-folder /E /MOVE /MT:1” (without quotes)

In conclusion, Amazon WorkDocs provides two robust methods for migrating data out of a WorkDocs site – the Data Migration Tool and Bulk Download using WorkDocs clients. The Data Migration Tool allows full migration of all data including versions, comments and permissions, ideal for administrators migrating an entire site’s content. The Bulk Download methods empower end users to manually select and migrate the files they own plus those shared with them, downloading to their local desktops. Both options ensure users have self-service access to extract their content from WorkDocs.