# Migrating User Data to Parcel

In this tutorial we will learn about two data migration strategies and best practices for onboarding your users' data onto Parcel. We will assume that initially your company (let's call it Acme Inc.) stores documents of your users, and that the documents are accessible and managed through your in-house application. Since it is difficult for your company to keep up with ever stricter data retention policies and regulations, you decide to migrate sensitive data such as your users' documents to Parcel. By doing so, you pass the ownership of each created Parcel document to the appropriate user(s). Each user now has full control over all of their documents, and can decide which of your requested access policies they'd like to allow (possibly none of them). Any access they grant to you or any other parties, they can check the data access logs and more for full and transparent auditability. Of course, since your users can now access their data separately from your application, this moves some liability from your company to the user, and they need to accept additional terms.

This tutorial assumes you are familiar with the following topics:

  • how to securely store users' documents in Parcel (the Uploading Data chapter)
  • how to change the ownership and restrict access to users' documents (the Managing User Data chapter)
  • how to onboard new users to Parcel (the Login with Oasis chapter)

# Custodial Access to Documents

When a user wants to obtain the ownership of the documents through Parcel, they must first register with Oasis Steward and accept Parcel's General Terms of Service. In the meantime, your company can move their documents to Parcel and use it as a secure store. The data however, will still be owned by your company and at this point you'll retain custodial access to the documents.

Eventually, when the user registers at Parcel and the data migration is complete, they will gain full and exclusive ownership over their documents. The custodial access of your company to their documents will be revoked, so the only way your company can access their documents is by getting the user's consent.

# Migration Strategies

Good data migration must be as smooth and non-intrusive as possible, yet still compliant with the data protection laws and regulations. In essence, the data migration can be performed immediately (eagerly) or in two steps (the lazy approach).

# Eager Apporach

When your company initiates eager data migration, it will upload documents of all your users to Parcel at once and associating them on Parcel with your app's Parcel identity:

  1. Local copies of the documents are deleted and your application will only retain document references and their corresponding owners.
  2. All newly created documents will also be stored on Parcel and their document ID references stored in your database.
  3. At this point your company will still have custodial access to the users' documents.

Once you onboard the user to Parcel, you will:

  1. Obtain their Parcel identity.
  2. Associate it with your internal User ID.
  3. Change the ownership of their documents on Parcel to the user's Parcel identity.
  4. If your user decides to grant your app access to their documents, your app will have access to all the user documents with the corresponding app tag until they revoke it.

The sequence diagram below sketches the eager migration user journey, where the actions on the gray background represent a custodial access to your users' documents:


This strategy is appropriate for businesses with a smaller user base and applications with smaller and more maintainable codebases. The migration will typically require a short downtime to safely move all the documents to Parcel and to perform the necessary healthchecks. Since we are stopping the service and moving all documents at once, there is a risk of prolonged downtime in case of an error.

# Lazy Approach

In the lazy migration approach, your company will store all user documents in company storage until they decide to onboard to Parcel. Then, you will:

  1. Store their Parcel identity.
  2. Upload all their documents over to Parcel.
  3. Delete local copies.

The document's ownership will be set to the user's Parcel identity and you will regain access to the documents, if and only if the user consents via Steward. From that point on, newly created documents will be stored directly on Parcel with the aforementioned attributes. No custodial access is required at any time.

The sequence diagram below sketches the lazy migration user journey:


This approach is suitable for companies with larger user base and where the downtime costs are high. Since the migration is made per-client, you will resolve any errors case-by-case. On the other hand, your application will need to support storing documents both to your company-owned storage and to Parcel until the migration is complete, which increases the migration and maintenance cost.