Self-serve migration guide

Migrating your subscription program over to Ordergroove can be done using Ordergroove’s migration tool.

---

Overview

The migration process is broken up into three high-level steps:

1. Preparation — getting your migration ready
2. Test migration — doing a test migration to ensure your preparations were set up correctly
3. Final migration — officially moving all of your active subscriber data over

This guide is meant to help you get through migration in the “happy path scenario” where everything is working as it should. When things are configured correctly, the process can take a few hours with more than 70% of your data importing successfully. In the event you experience errors or some data not successfully migrating, don’t worry — we are here to help. For any questions regarding errors, data issues, or anything else, open a ticket and someone from the Ordergroove migrations team will help you.

---

Preparations

To get your migration started, you’ll need to complete a few steps to prepare for it:

1. Create a test customer/subscription
2. Confirm your checkout requirements
3. Learn how to build an Ordergroove migration file

1. Create a test customer/subscription

Takes about 5 to 10 minutes to complete

A test customer/subscription is a subscription in your subscription program associated with you or one of your employees. Create a customer in your program using your (or another employee’s) information.

This creates a litmus test of the migration from beginning to end:

1. Extract data from your subscription program
2. Import the test customer/subscription into Ordergroove
3. Place an order through Ordergroove into your eCommerce system
4. Confirm payment processed correctly

If you’d like to create more than one to test, feel free to do so. Make sure to keep the email address for each handy as you will need to reference them later.

2. Confirm your checkout requirements

Takes about 5 minutes to complete

Let your solutions contact know which fields should be required for payment, customer, billing address, and shipping address. This will need to match the data you’re importing, based on your eCommerce data requirements for checkout.

3. Learn how to build an Ordergroove migration file

Takes more than 1 hour to complete

At this point you’re ready to take on one of the most important steps of the migration: extracting the data from your current subscription program and transforming it into the Ordergroove migration file structure. You can find all the information you need about the file and object structures in the Knowledge Center.

While this section is deceptively short, this can take quite a bit of time. One recommendation would be to start small and generate a file with a single customer. You can then use our tools in the Testing data integrity step of the Test Migration section below to see how you’re coming along.

---

Test Migration

Now that the preparations are complete, you will want to do a test run of the migration. The time this takes depends on the size of data you are migrating over. A more established subscription program means more data and therefore longer migration times. This can range from a few minutes to several hours — but keep in mind, this is a one-time thing.

A test migration requires the following:

1. Build the data set
2. Test the data integrity
3. Resolve errors

By doing a test migration, you will also get familiar with the migration tool so when the time comes for the final migration, you’ll fly through it.

1. Build the data set

Takes 10 minutes to more than 1 hour to complete, depending on data size

You’ll more than likely have set up some automation in order to build the migration file after having tested a handful of records. You’ll now want to pull all of your subscription program data for a test run of the migration and see how the data integrity holds up.

The time it takes to extract your data and build the migration file depends solely on the size of your subscription program.

2. Testing the data integrity

Takes 10 minutes to 1 hour to complete, depending on data size

Now that we’ve downloaded and transformed the data, it’s time to test the data integrity.

1. Go to the Migrations page in Ordergroove.
2. Make sure you’re on the Test Run tab.

3. Click the Upload button and select the transform file from the previous step.

A new row will appear in the table below indicating that the Test Run process has begun.

Periodically check back on this page. We’re waiting for the Processing Status column to move from “In Progress…” to “Completed,” at which point you can download the Unprocessed, Errors, and Successful files.

If you run into any issues here, please open a ticket with us.

3. Resolve Errors

Takes 10 minutes to more than 1 hour to complete, depending on data size

You’ll know the data integrity checks have completed when the Processing Status column shows Completed for the file you uploaded.

If instead you see the status as Cancelled, retry uploading and testing your file.

You’ll notice three columns:

• Successful — a file consisting of all the customers and their respective subscription information that passed initial validations. This file would represent something you could attempt to import in the Migration tab — but we’re not ready for that yet.
• Errors — similar in structure to the Successful file, except we found some data integrity issues that you’ll need to resolve.
• Unprocessed — more for debugging purposes. This represents data we simply could not put together or understand. Examples include subscriptions referencing a customer that does not exist in the migration file, or invalid JSON.

Error remediation can be by and large the most time-consuming (and frustrating) part of a migration process. This is why we’re in a preparatory phase — if you get ahead of it now, you won’t feel bad taking a break and coming back to it later.

Here are some resources to help:

• You can get a better understanding of the types of errors you might encounter in the Knowledge Center.
• We have a script/utility you can use to parse the error file and provide a summarized view, showing the errors that manifested for each specific customer.

At the end of the day, you’ll have to look in that file to determine which customers are having which problem.

Because we’re still in the preparation stages, you’ll want to make any data modifications in your subscription provider or eCommerce platform. After you’ve done so, go back to step 2 and repeat the subsequent steps until you feel comfortable with the data extraction, transformation, and validation.

---

Migration Day

At this point, you should already have your program with Ordergroove live.

Now that we’ve done some practice runs, we should be ready for the real migration. This requires the following:

1. Generate and validate the data
2. Set up the test customer file
3. Import the test customer/subscription
4. Place a test order
5. Validate payment processing
6. Import the full data set
7. Resolve any errors

1. Generating and validating the data

Takes 10 minutes to more than 1 hour to complete, depending on data size

Please refer to steps 1 and 2 in the Test Migration section above for details on how to test the migration file you’ve built.

2. Setting up the test customer file

Takes about 10 minutes

In the Successful file, locate the test customer:

1. Open the success file.
2. Search for the email address of the test customer.
3. Cut the entire contents of the row corresponding to the test customer.
4. Open a new file.
5. Paste the test customer data into the new file.
6. Make sure you don’t leave a blank line in the success file.

Give the file a representative name, for example: test_customer_for_og_migration.json

If the test customer is in the error file, extract it the same way — but because there were errors, you’ll need to make some modifications to the data.

3. Importing the test customer/subscription

Takes about 10 minutes to complete

1. Click the Migration tab on the Migrations page in Ordergroove.

2. Use the Upload button to select the test customer file created in the previous step.

3. A new row will be added to the table and the file you provided will be listed as “In Progress…”

When the process is over, download all three file types. If everything worked correctly, both the Errors and Unprocessed files should be empty and the Successful file should contain your test customer. If that’s the case, move on to Placing a test order below. Otherwise, keep reading.

Test Customer Import Error

Sometimes, even after all the preparation, the test customer can still result in an error. Remediate as you see fit and retry importing the test customer:

1. Modify the error file.
2. Save your modifications.
3. Go back to step 3, Importing the test customer/subscription.
4. Be very careful to make sure you pick the correct file.

4. Placing a test order

Takes about 15 to 20 minutes to complete

Now that the test customer has been successfully imported, the most important question can be answered: Can a customer be charged when an order is placed?

To test this, you’ll use some of Ordergroove’s tools to facilitate and verify this.

1. Navigate to the customer search screen by selecting the Customers link under the Data section of the navbar.

2. Search for the test customer’s email address.
3. Click on the customer row to be brought to a more detailed view. Take a moment to verify that all the test customer information is as you expected.
4. Click View All on the left side of the Orders section in this view.

5. Click on the upcoming order of the test customer so it expands.
6. Click the Send Now button on the top left.
7. Click Save.

At this point, wait for the Order Placement system to run — it will fetch the order and attempt to push it into your eCommerce system. Feel free to occasionally reload the page. After a little bit, you should see the order update. If it shows a “Success” state, move on to the next step. Otherwise, see the notes below.

If You See a Placement Failure

1. To find out why an order was not successfully placed, check the order placement section under the Data section of the navbar.

2. In the Filter section, set the search filter to Email.
3. In the Value section, provide the test customer email address.

You should see two rows — click the Response button to gain insight as to why the order was rejected.

If the system had a timeout communicating with your eCommerce system, that’s OK — we’ll retry.

If there’s a data issue, you can make the appropriate updates to the customer in our system. However, it is recommended to go through another test customer to ensure there’s no systematic issue with how the data is migrating from your subscription provider to Ordergroove.

If you need to re-import the test customer, that requires some help from us — we’ll need to move the test customer “out of the way.”

It’s worth noting, this situation is exactly why the test customer is so valuable: it’s much easier to resolve one single customer than an entire program.

If all else fails, open a ticket with us.

5. Validating payment processing

Takes about 5 to 10 minutes to complete

If the order is being reported as “Successful” in both Ordergroove and your eCommerce system, verify that the card was indeed charged successfully:

1. Log in to your eCommerce system.
2. Find the test customer.
3. Find the order that was placed.
4. Confirm the charge was successfully captured by your payment processor.

It may also be worth waiting for the charge to appear on the test customer’s credit card statement.

6. Importing the full data set

Takes 10 minutes to more than 1 hour to complete, depending on data size

1. Click the Migration tab on the Migrations page in Ordergroove.

2. Click the Upload button and select the Successful file downloaded from step 1 (Generating and validating the data).
3. A new row will appear in the table below indicating that the import process has begun.
4. Periodically check back. We’re waiting for the Processing Status column to move from “In Progress…” to “Completed,” at which point you can download the Unprocessed, Errors, and Successful files.

If you’ve followed all the steps, you should have been able to successfully import a good amount — if not all — of your data into the Ordergroove platform.

7. Resolving any errors

Takes 10 minutes to more than 1 hour to complete, depending on data size

Now comes the trickiest part of the migration process: error remediation. Because it’s migration day, any changes you make to remediate errors will have to be done directly in the Errors file.

• Each row represents all the data of a customer.
• If any data for a customer has an error, they will appear in this file.

Pay special attention to the last bullet: if a customer has multiple subscriptions and only one has an error, all of the good data will be imported. The error file includes all of this data as well as the error data. Take great care when modifying these files.

1. Errors in Test Run tab — If you have an Errors file in the Test Run tab, it is recommended to make updates to that file and then execute the Test Run tab again. This may produce another Errors file, but any data in the Successful file should be good to go in the Migration tab.
2. Errors in the Migration tab — If you have an Errors file from the Migration tab, modify this file and retry importing it.

It’s up to you which one you prefer to tackle first and how much time you want to dedicate.

For your own peace of mind, we take many precautions to ensure the migration is an idempotent process. Think of re-running errors like a relay race: the previous error file passes the baton to the next runner until there are hopefully no errors left.

Here are some resources to help:

• Get a better understanding of the types of errors you might encounter in this Knowledge Center article.
• Use our script/utility to parse the error file and get a summarized view, showing the errors that manifested for each specific customer.