Validic is in the process of migrating customers currently on the first version of our API platform (V1) to the second version of our API platform, Inform (V2). While the two platforms both send health and fitness data to customers, the method in which they send data and the format of this data varies between the two platforms. Major changes to the V2 platform include:
A Streaming API
Different call patterns to the REST API
And, an updated data model representing your users’ events
It is imperative that you read the V2 API documentation thoroughly before setting a migration date. For detailed information on V2 integrations, implementations, data, and more visit the V2 Support Portal. Please note: you can request a sandbox on V2 to develop and test changes to your application. Contact your Client Success Executive to request a sandbox and begin V2 development. Development against the V2 sandbox must be completed in order to migrate to V2.
What does “Migration” actually mean?
The migration from the Legacy V1 API to the Inform V2 API is a service that Validic offers to upgrade your Validic organization without the need for all of your connected users to have to re-connect via the Validic Marketplace.
What we will migrate from V1 to V2:
Validic user IDs and tokens
Data source developer credentials (i.e. Fitbit, Garmin, Withings)
What we will not migrate from V1 to V2:
User data, including historical data
It is important to note that once the actual user migration starts, there is no going back. Therefore we must ensure that you are 100% ready to move forward with the migration and the use of the Inform V2 API before we start.
Ready to Migrate? Ok, here we go!
Sandbox time! If you are reading this document, it means you have probably already spoken to a Validic team member about doing the migration. You might also already have access to a Sandbox Org in V2. If you don’t, that will be set up soon for you.
Testing, testing, development, more testing. Now that you have your sandbox, you should be focusing the majority of your effort on creating test users, connecting the test users to sources through the marketplace, generating data, and working with the Streaming API. Throughout this process, do not hesitate to reach out in your support case with any and all questions. This is very important because we cannot move forward with the migration until you are 100% ready to use the V2 Streaming API.
Mirroring V1 data. Testing in a sandbox is great for development, but it doesn’t really accurately show you what your actual user data will look like once migrated to V2. This is where “data mirroring” comes in. At least 30 days before your desired migration, Validic will create a duplicate of your V1 production org in V2. It will have the exact same Org ID, but a different Access Token. At the same time, we will start “mirroring” your incoming V1 data into this V2 org. Your V1 org is not affected in any way by this.The purpose for the mirroring is to allow you to see what a full load of customer data will look like in the streaming API to make sure you are prepared for the volume you will see after migrationImportant: You may use this data to load test, however, not all metrics or sources are covered in the mirrored stream. That said, you can use it to backfill data as long as you have noted the format of the data in the mirrored stream compared to what you see in your sandbox.
It’s a date! Once you have fully completed the above, we will schedule some time to talk through what you have completed and then confirm a date for the actual migration. If you are not yet ready to 100% use the streaming API for your production data, you are not ready to migrate and therefore a date may not be set until you are. Migrations are done on Tuesdays or Wednesdays during US business hours to ensure all resources are available.
Who does what and when do they do it?
While the majority of the work of migration falls on Validic, there are still some steps that we need you complete to ensure a smooth migration.
Client Tasks:
Inform your users that your Marketplace will be down for potentially several hours on the day of migration. This is the extent of any “outage” that they might experience.
Approximately 1 week before migration, you should complete user “housekeeping” by deleting users from your V1 org that you are confident are old/inactive/etc. No point migrating users that are no longer active
1-2 days before the migration date, you should stop all user management processes. For organizations with large numbers of users, Validic will start to replicate the user IDs over to V2 prior to migration day (with no effect on V1). We rely heavily on having accurate user counts during migration so if your system is adding or removing users during this time it can throw off our counts and result in a longer time to complete the migration.
Either the night before, or early on the day of migration, you should disable your V1 marketplace access for users and instead display your maintenance page. This will need to remain in place until the migration is complete later in the day on migration day.
On migration day, all you have to do is wait for Validic to let you know that you can turn the marketplace back on, only this time it will be the V2 marketplace
Process Summary
Day 1: CSE opens a support case and you receive the intake form to fill out. The first meeting is scheduled through the support case. All relevant client contacts are added to the support ticket for visibility.
First Meeting: Set expectations of customer requirements to migrate. Support creates sandbox org and turns on mirroring. Customers can now begin development to have the Streaming API working for the sandbox V2 organization.
Second Meeting: Verify that the customer has met the requirements for migration. Schedule migration if they have, and if they haven’t the client will supply a date to have this meeting again when they can accomplish their obligation to the process.
Third meeting: This occurs the week before migration. There will be a review of migration day requirements for the client. If anything has come up in prechecks that the client should be aware of this will be discussed.
Migration day: The client turns off marketplace access in V1 prior to migration start time and is patient while Validic completes migration. Customer is notified when they can turn on the V2 marketplace
Notes:
V2 Backfill Setting: Backfill for new users will initially be turned off in V2. This will ensure we do not run into constraints with data provider systems due to the volume of user event data. Once the performance has stabilized after the migration (about 24 hours on average), we will enable your backfill to your preferred setting.
Expanded Data: Expanded data fields are not supported in V2. If you are using any expanded data fields, please list all fields and the corresponding use case in the Customer Intake Form. Based on the demand for the field, your use case, alternative fields, and ease of implementation, we will determine if that field will be added to V2 prior to your migration. The results of this evaluation will be detailed in our response to your migration request.