Data migration is the process of transferring your data from your old account management system to Pelcro. It is a meticulous process that requires the data to be transformed to fit the Pelcro structure. Our team has put together all the necessary tools at your disposal to help you migrate your data successfully into Pelcro.

Process

The migration team possesses extensive expertise in database systems, including proficient data mapping techniques, and has harnessed this knowledge to successfully transfer over 1,000,000 subscriptions across multiple businesses.

We have migrated businesses from several other systems including but not limited to CDS, Piano, PayPal, Braintree, TownNews, Pigeon, Pico, Salesforce, and Clickshare.

The analysis and preparation phase for data migration generally spans between one to three weeks, provided that the data supplied conforms to the Pelcro templates.

Any technical team would be able to successfully migrate data into Pelcro using the core APIs. You can learn more about the Pelcro CORE API here.

When Pelcro's migration team is assigned to migrate your data, it's essential for both parties to collaborate in following the procedure outlined in this section. This collaborative effort encompasses all the crucial measures required to ensure a successful migration.

1. Review and understand the scope of the data migration.
2. Request a data export from your current provider.
3. Populate Pelcro's migration templates found here, by using the data conversion tables.
4. Request Pelcro's migration scope sheet and SFTP server credentials from your account manager and upload your converted files and the approved migration scope sheet to Pelcro's SFTP server.
5. Pelcro's migration team will perform the necessary validations on the data files provided by your team and offer feedback if necessary.
6. Once the files are approved by Pelcro's migration team, we will perform a migration test run on our staging environment.
7. Our migration team will analyze the test data, provide the stats sheet, and furnish feedback regarding the results of the migrated data. More details about this step can be found here.
8. To ensure a seamless migration, Pelcro's QA team will conduct various tests related to the migrated data based on the scope of the migration and will provide the required feedback:
   a. Password migration
   b. User interface flows, such as customer login and subscription view
   c. Essential aspects related to the Pelcro platform like list and fulfillment generation, subscription view, etc.
9. Your account manager will provide you with test account credentials so that you can conduct your own tests and validate data accuracy. The suggested approach can be found here.
10. Once both teams approve the data accuracy, we will plan the production migration and agree on the GoLive date. The following steps will be required for production migration:
    a. Initiate the credit card migration process (if included in the scope of the data migration). More details can be found here.
    b. Prepare the production data files
    c. Initiate production data migration
    d. Validate production data

👍

Our support team is right there for you!

Contact us at [email protected] and we're happy to assist with any questions or concerns.

Understanding your data scope

Before performing any data migration, it is indispensable to understand and clean your data. During the migration kickoff meeting, your account manager will be asking you a set of questions that will be critical to understanding the data structure:

1. Number of authenticated users to be migrated.
2. Number of active subscriptions to be migrated.
3. How are the active subscriptions broken down?
4. How many of the active subscriptions are on auto-renew?
5. How many of the active subscriptions are set to be canceled at period end?
6. How many of these subscriptions are gift subscriptions?
7. How many of these subscriptions are membership subscriptions?
8. Does your business collect taxes?
9. Are there any subscriptions with an outstanding open invoice that must be charged upon import?

When requesting a data export from your current provider, the format likely will not match the data structure required by Pelcro. By providing the data in our predefined CSV files, our team will be able to process and deliver the data migration significantly faster than if you provide us with a data dump as-is from the current provider.

Building your migration files

First, download Pelcro's migration file templates that are linked below. Each file represents an object resource in Pelcro, and it is important to only download and build the migration files for the resource you will be migrating.
For example, if you will not be migrating group members subscriptions, do not build the 'Memberships' file.

The file templates contain field headers in a CSV format. Use the tables below to populate the file templates with the relevant data, according to the field description and mandate (required vs. optional).

Migration file templates

Customers
Subscriptions
Addresses
Plans
Products
Memberships

Customers

Customers are registered users to which we associate addresses, subscriptions, payments, invoices, etc.
You can migrate all of your users' profile information into Pelcro by either filling in the preset fields on the template (email address, phone number, etc.) or by adding your own custom fields which will get stored in the customer record's metadata table.

The table below contains the list of attributes that make up the Customers resource migration file template:

Here are some examples of customer records formatted into Pelcro's Customers migration file template:

Addresses

Addresses provide contact information related to customers and their subscriptions. That includes shipping and billing addresses.

If your Pelcro account checks any of the boxes below, the shipping address will be required to migrate your subscriptions into Pelcro. If you are unsure of whether there is an address requirement to create subscriptions, please contact [email protected] or your account manager.

1. Sales tax collection is enabled on your account.
2. The address is required on the subscription product. This is typically the case when a product needs to be shipped to the subscriber. In this case, the shipping address will only be required to migrate subscriptions on the given Product.
3. The payment gateway connected to your account requires an address to process charges.

The table below contains the list of attributes that make up the Address resource migration file template:

Here are some examples of addresses formatted into Pelcro's Addresses migration file template:

Products

Subscription Products describe the goods or services that your business offers to your customers. Each product can contain one or multiple pricing plans, which are often grouped together based on the nature of the component being offered. For example, a newspaper offers a digital access subscription, as well as a print copy subscription to their customers. One product would be created for each type, and pricing plans would be added to each product. The pricing plan carries the price and the duration/term of the good or service you are offering. More on this here.

The table below contains the list of attributes that make up the Products resource migration file template:

Here are some examples of products formatted into Pelcro's Product migration file template:

Plans

The pricing plan, also known as the rate, will dictate the price, the currency, the terms and the duration of the good or the service you are offering. You cannot create a subscription without a pricing plan, and you cannot create a pricing plan without a Product. This relationship has been surfaced on the migration templates, by allowing you to tie files together using common fields, namely 'plan_id' and 'product_id'. Learn more about the Plans resource and its associated properties.

The table below contains the list of attributes that make up the Plans resource migration file template:

Here are some examples of plans formatted into Pelcro's Plans migration file template:

Subscriptions

The subscription is the piece that connects the registered user, Customer, to the good or service you are offering, the pricing Plan. The subscription carries relevant information such as its end date, its auto-renewal status, the payment method used to purchase the subscription, as well as the number of shipments/issues remaining on a user's subscription.

Subscriptions can be tied to individual customers, as well as multiple. Pelcro supports migrating group/corporate subscriptions, and gift subscriptions (from one user to another).

If you will be migrating group subscriptions into Pelcro, the group admin and user subscriptions must be split into two files. The group admin subscription must be added to the Subscriptions file template and carry the type 'admin'. The group member subscription must be added to the Memberships file template. Learn more about the Subscriptions resource and its associated properties.

The table below contains the list of attributes that make up the Subscriptions resource migration file template:

Here are some examples of gift donor (1), open invoice (2), group owner (3) and gift recipient (4) subscription records, formatted into Pelcro's Subscription migration file template:

Memberships

The membership represents the group member subscription to the good or service you are offering. This template must only be filled out if you are intending on migrating group/school/corporate subscriptions into Pelcro.
The membership (group member) record will be tied to the group owner subscription record (any subscription tied to a plan with 'type = membership'). Learn more about the Memberships resource and its associated properties.

The table below contains the list of attributes that make up the Memberships resource migration file template:

Here are some examples of group member subscriptions formatted into Pelcro's Memberships migration file template:

Limitations

There are some important limitations to be aware of when migrating your data in Pelcro’s system. You cannot migrate the following data:

1. Expired subscriptions.
2. Canceled subscriptions.

There are also limitations with migrating open active subscriptions ('next_invoice_date = NULL'). On the day of migration, a charge equal to the plan price associated with the subscription will be attempted on the user account during the migration process. The different scenarios and expected behaviors have been outlined below:

1. Auto-renewing unpaid subscriptions:
   a. An open invoice is generated, with the amount fetched from the plan.amount field value.
   b. If the collection_method is set to send_invoice, the invoice will remain open until the automatic uncollectible (or write-off) period is reached.
   c. If the collection_method is set to charge_automatically and a valid payment method exists, a charge will be attempted on the invoice.
   d. If the collection_method is set to charge_automatically but there is no valid payment method on file, the collection_method will be changed to send_invoice (see point b.)

2. For non-auto-renewing, unpaid subscriptions:
   a. The collection_method will be forced to send_invoice.
   b. An open invoice is generated, with the amount fetched from the plan.amount field value.
   c. The invoice will remain open until the automatic uncollectible (or write-off) period is reached.

Gifts

You can migrate your gift subscriptions into Pelcro. It is important to note how gift subscriptions are structured in Pelcro prior to the migration, as it may be different than the way your gift subscriptions are built on your old provider's database. In Pelcro, a gift subscription is split into two subscriptions: the gift donor subscription and the gift recipient subscription records.

In order to migrate your gifts into Pelcro, you must have two subscription records per gift subscription. Both subscription records must contain the same subscription data, with the exception of:
a. old.provider_id (must be unique)
b. customer_id (since the gift donor and gift recipient are often not the same user).
c. address_id
d. is_gift_donor
e. gift_donor_subscription_id

The 'is_gift_donor' field is a flag that will indicate whether the subscription record in question is a gift donor subscription record. The 'gift_donor_subscription_id' field indicates that the subscription record in question is a gift recipient subscription, and will be tied to its donor record via the 'old_provider_id' value. This format must be adhered to in order to successfully import gift subscriptions into Pelcro.

Migrating passwords

The password migration component deals specifically with transferring the end-user passwords. The main consideration here is the customer’s previous encryption mechanism. Pelcro only supports the following:

1. Drupal_v8.2.x
2. Bcrypt (WordPress)
3. Bcrypt
4. MD5
5. Plain text

Note: Pelcro uses Bcrypt and its implementation on PHP.

Once you've reviewed the prerequisites, the next step is to provide Pelcro with a small sample of hashes with their respective passwords in plain text, against the hashing algorithm. This will allow Pelcro's migration engineers to analyze the sample and evaluate the feasibility of migrating user passwords into the database.

Items the customer must provide to migrate passwords into Pelcro:

1. A minimum of 5 password examples (hashes and their equivalent plain text).
2. Hash types:
   a. Built-in: Provide the name of the hashing mechanism (e.g. sha1, MD5, bcrypt).
   b. Custom implementation: Provide the code used to generate and validate passwords.
3. If the hashing requires a salt/pepper, that must be provided as well.

If Pelcro's migration engineers successfully reproduce the hashing output that matches the customers’, we deem that we are capable of moving forward with the password migration.
The final step is to provide the password hash in the customers file template, as part of the data dump; this must be provided under the customer.password field. Pelcro will then undertake the work of importing the user passwords upon GoLive.

Performing a data migration into a Staging environment

Once all the statistics have been reviewed and validated by the client, the migration team will begin the migration dry-run process:

1. The migration team will prepare the data files to perform the migration to staging.
2. The migration team will run the script to migrate the data into the staging environment.
3. The migration team will validate that all the data provided in the dry-run data dump has been successfully imported.

Generating a migration statistics report

Once the dry-run process has been completed, it will be critical for the migration team to review the data and generate a migration report that will illustrate the migration success rate of each Pelcro record object.
The sample statistics report below reflects the percentage of records with valid data that Pelcro was able to migrate from the legacy system into the Pelcro system.

Field definitions:

1. Attribute: Property of a given object type.
2. Pelcro Pre-Processed: number of records fed into Pelcro’s migration script.
3. Excel dump: number of records included in the customer data dump.
4. Accuracy: Measure of how many records were kept between the Excel dump and Pelcro's migration script.
5. Inaccuracy: Compliment of accuracy.
6. Dry-run (staging): number of valid records migrated into the staging server.
7. Production: number of valid records migrated into the production server.

Sample statistics reports will vary in size depending on the data points included. It is important to sanity-check the numbers in this report against the data in your system. For example, verify that you have 1848 customers subscribed to the 'Print & Digital 1-Year USA' plan.

Reviewing and analyzing the data migration

The report generated in the previous section will be critical to getting the client's approval to move forward with the production migration.
As part of this process, the client will be required to:

1. Review the report generated by the Pelcro migration team
2. Validate the numbers
3. Validate sample data in the Pelcro Dry-run environment.
4. Sign off on the report and Data validation

In order to assist you in validating the imported data, you can review Pelcro's best practices below:

1. Once logged into the Pelcro platform, use the Products tab in the left sidebar to validate the product and plan relations and plan amounts.
   a. Tip: Looking at shipments_per_interval and plan_intervals is a great way to begin your validations.
2. Navigate to Billing > Subscriptions and perform a data export to validate the subscription-related objects, such as:
   a. Auto_renew status
   b. Subscription expiry dates
   c. Shipments_remaining
   d. Validate the customer-subscription relations using the same CSV data export.

Going the extra mile: Navigate to Customers > Customers and perform a customer_object data export, where you can validate:

1. Billing and Shipping Addresses
2. Customer metadata.

Migrating Credit Cards to Production

Migrating credit card information is important to ensure your end users do not have to re-enter their payment details when you switch from your legacy payment processor to your new payment processor.

The key difference between migrating credit cards and your other data is the intervention of a third-party vendor. This may impact the timeframe of the data migration.

The steps required to migrate your end users' credit card information into the new payment processor are outlined below:

Get familiar with the requirements for credit card migration.
You need an ID for each customer in the old payment processor files, which will be mapped to new customer IDs.
Coordinate between your new payment processor and the previous one to request the data migration.
a. Your new payment processor will provide you with a file template for dumping the credit card information. Work with your old payment processor to prepare the data dump file.
The transitionary period: online payment freeze period, where the customer will be requested to freeze any online payment.
a. Redirecting all new subscriptions to the customer service operators, that will manually process the subscription and issue a bill-to invoice.
b. For smaller customers without customer service operators, they can even freeze all new subscriptions during this transitionary period.
The new payment processor will confirm the import by providing a mapping file (JSON) that contains their generated IDs (customers, payment methods, etc.) along with the old payment processor IDs.
Use the mapping file to overwrite Pelcro data (customer record info, subscriptions, ..).
Once the mapping is complete, you must validate the data across both providers and provide a stamp of approval.

📘

Check out these helpful articles for more information on our blog

• The Pelcro Blog
  • How to Migrate from Piano Go
  • Switching From Legacy Systems to a Modern Subscription Platform