Progress will discontinue Telerik Platform on May 10th, 2018. Learn more

Migration Guide

This article is targeted at Telerik Backend Services customers who are exploring the steps to migrate their existing Telerik Backend Services apps to Kinvey.

It is intended to give a general idea of what the migration to Kinvey means. It lists aspects you need to consider before starting actual migration and also gives a recommended migration flow for migrating a single Telerik Backend Services app.

Content at a glance:

Considerations

Pricing and Licensing

There are differences in the way Telerik Platform and Kinvey are licensed. One such difference is that in Kinvey the pricing is per app, while in Telerik Platform it is based on seats and a data plan. Also, Kinvey comes in different editions which include different features.

Before you start migrating your apps, make sure to choose the best licensing option for you. You can read more about Kinvey licensing here.

Feature Parity

Although Telerik Backend Services and Kinvey are built to solve the same problem, there are differences in what is supported and how.

Before you start migrating your apps, make sure to check that the features you use in Telerik Backend Services are also available in Kinvey. Most of the features are supported and for the unsupported there is often a workaround.

Also, it is a good idea to check for Kinvey features that are not supported in Telerik Backend Services. It might turn out that something you do manually or using a workaround for in Telerik Backend Services is readily available in Kinvey.

You can find more information about feature parity in the Feature Comparison article.

If you are unsure about how to start, contact the Telerik Platform support engineers to figure out the best possible migration path.

Migration Process Overview

This section outlines the migration process for a single Telerik Platform application. You need to repeat the process for each application that you want to migrate.

You might need to consider a more complex approach if you have multiple related apps and want to migrate them at once.

You can find the recommended migration path for a single app below. Some of the steps are automated but the rest you must complete manually.

Migration process for a single app:

  1. Plan the app migration and prepare (manual).
  2. Migrate backend configuration to Kinvey (partially automated).
  3. Rework your app to work with Kinvey (manual).
  4. Migrate data from Telerik Backend Services to Kinvey (automated).
  5. Publish the updated mobile app to your customers (manual).

You will find detailed explanation of each step in the sections below.

Step 1: Plan the App Migration and Prepare

Depending on the complexity and usage of your app, its migration might be a complex process. Spare plenty of time to plan before you start migrating.

First you need to think about how you are going to introduce the migrated app to your users. At best, the transition will be transparent to them. At worst, you will have downtime and will need to notify your customers in advance to provide a smooth user experience.

There are several things you need to think about:

  • Decide on the transition process
  • Plan data migration and downtime
  • Prepare your app
  • Notify your customers early

Decide on Transition Process

After you ensure that your code works well with Kinvey as a backend, you need to distribute the new/updated app to your users. Unfortunately, you cannot always force them to update to a newer version. This means that some customers will start using the app version that writes to the Kinvey backend while the rest will continue using the old versions of the app that connect to the Telerik Platform backend.

Think carefully if the above is acceptable to you. If your app is writing data to the cloud, having parallel versions and backends will probably not work. Every app will write data to its respective backend and you might never be able to consolidate the data.

On the other hand, if you mostly use external data sources through Data Connectors, then it might be acceptable to have both versions working at the same time. It is up to you to decide.

There are two ways to prevent two active backends at the same time:

  • Flag for minimum version—you can add a facility (a cloud function, a content type with one document, etc.) on the backend that returns the minimum required client version. You can then version the app and implement a version check on startup. If the minimum version returned by the backend is higher than the current app version—require app update. Still, you might run into issues if you have different apps with different versions for the different platforms.
  • Disable the old backend—another option is to disable the Telerik Backend Services backend. You can read more about this in the Additional Information section.

Both options give you reliable control over data access that effectively prevents old app versions from working. When you are ready with the migration and have published the new app, you just set the flag in the backend.

Note that you will probably need to prepare your app to work seamlessly with the server-side flag—error handling and so on.

Plan Data Migration and Downtime

The term "data" comprises all your content types, users, and files. You need to plan when the data migration is going to happen and how.

We provide an automated tool for migrating the data, but you still need to think about how and when to use it. Ideally, you should start migrating the data after you have disabled the old app/backend and before you enable the new.

If you start migrating before you disable the old app, there will be users who still write data to the old backend, meaning the migration will not envelop all data. On the other hand, if you start migrating after you release the new app, customers will be able to install it, but their data will not be available in it because it will have not been migrated yet.

All that said, proceeding with the data migration in between means downtime. You need to stop the old app, run the migration, then release/enable the new app.

It is up to you to decide what is the best approach for your particular app.

Prepare Your App

After building a plan for data migration and downtime as discussed in the previous section, you might need to prepare your app accordingly.

If that is the case, try and make the changes to the app as early as possible and publish it. This way your customers will have time to update and get those changes.

Even if you release the prepared version of your app immediately, you might still have users who will not install the update.

Notify Your Customers Early

In the best-case scenario your customers won’t notice that you transitioned to a different backend.

But if the transition is not transparent and you expect downtime or some other kind of user-visible problems, it is important to inform your customers about the migration.

To do this you could use the email templating functionality in Telerik Backend Services. You could also use push notifications if they are enabled for your app.

Step 2: Migrate Backend Configuration to Kinvey

The first step in the actual migration process is to migrate the app backend configuration. During this process you will need to consider all the server-side differences between the two BaaS solutions.

Note that this section contains only information on what you need to migrate. It does not give detailed explanation on how different features translate to Kinvey. To see detailed comparison and migration guidance for each feature, please see the Feature Comparison article.

All the configuration options that you have in place in Telerik Backend Services need to be applied in Kinvey. Below you will find is a list of what you might need to migrate:

  • Roles—the user roles that you have defined
  • Data connectors—the definitions of the data connectors that you use
  • Content type definitions—the custom content type definitions you have created
  • User management settings—all the settings and authentication providers that you have defined
  • Push notification settings—all the push providers you have configured
  • Business logic—all the Cloud Functions and Cloud Code for Data you have created

To make the migration easier, we have created a tool that can partially migrate configuration from Telerik Backend Services to Kinvey.

Automated Migration

The automated migration is done using the provided backend migration tool. You can use it to migrate the following:

  • Roles—the tool will re-create in Kinvey all the roles you have defined in Telerik Backend Services
  • Content type definitions—instead of you having to create each type, the tool can create those for you
  • Business logic code transfer (not actual migration)—the automated tool can create all your Cloud Functions and Cloud Code for Data triggers in Kinvey and put your current Telerik Backend Services code there. Note that the code will not work in this state, you will need to adjust it.

You can find more information on how to use the tool in the Additional Information section.

Manual Migration

Below you will find all the settings you need to do to migrate manually. Note that you need to do them even if you used the automated migration tool.

Roles

After migrating the roles of your app to Kinvey with the automated tool, you need to set each role’s permissions for the various collections. Find more information on role-based access control here.

Note that Kinvey does not offer the "Anonymous" role due to the way security is implemented. For more information about the differences in role-based access control in Kinvey and Telerik Platform Backend Services, refer to the Feature Comparison article.

Data Connectors

Data connectors have an equivalent in Kinvey called RAPID. While the concept is very similar, the actual configuration is a bit different.

You need to create all your data connectors as RAPID services in Kinvey. Then you need to create collections in Kinvey that correspond to the content types from Data Connectors in Telerik Backend Services. After you have those collections in place, you need to set their permissions.

Content Type Definitions

Content types in Telerik Backend Services are the feature that allows you to store data in the cloud. In Kinvey, content types are known as "collections".

In Kinvey, you do not need to define fields for the collections because they are automatically created based on the inserted data. Still, you need to create the collections themselves and set the proper permissions.

You can define the collections automatically using the migration tool. Still, you will need to manually set permissions.

Cloud Files

There is no configuration that you need to migrate for cloud files. Permissions for files are not supported in Kinvey.

User Management

You need to transfer your configuration from Telerik Backend Services to be able to use User Management in Kinvey. The configuration includes:

  • Linked social and enterprise authentication providers
  • Customized email templates for user-related emails
  • Permissions for user management

Push Notifications

You need to manually transfer your push notifications settings from Backend Services to Kinvey. This means entering the Android server key and the iOS server push certificates that you are currently using with Backend Services.

Note that in Kinvey you can import only one iOS push server certificate—either for production or development.

Existing push notification entries in Backend Services cannot be migrated to Kinvey. You may consider backing up this information for your archives.

Business Logic

Your business logic are all the Cloud Functions and Cloud Code for Data logic that you created in Telerik Backend Services.

In Kinvey, both of those concepts are available, although under a different name. Cloud Functions are called "Custom endpoints" and Cloud Code for Data is known as "Collection hooks".

Although in both products the business logic is implemented using JavaScript code, simply copying and pasting the code will not work, as the available API is different. You will find more information on how to migrate your code in the Feature Comparison article.

Step 3: Rework Your App to Work with Kinvey

After migrating the background configuration, the next step is to migrate your current mobile app to work with Kinvey. This is done by replacing the Telerik Backend Services SDK with the Kinvey SDK and making the necessary adjustments to your code.

Remember that the current version of your app that works with Telerik Backend Services will still be live and your customers will continue to use it until you publish the updated mobile app (not until Step 5).

The sections below help you understand what Kinvey SDK you can switch to, based on the type of app you have.

Cordova, NativeScript, Web, and Node.js

If you used the Telerik Backend Services JavaScript SDK, you can switch to using the Kinvey JavaScript SDK.

Similar to Telerik Backend Services, there are several flavors for the Kinvey JavaScript SDK:

Android Native

If you have a native Android app using Telerik Backend Services, you can start using the Kinvey Android SDK. Head to the Getting Started Android article to find more information.

iOS Native

For iOS native apps you can use the Kinvey iOS SDK. Head to the Getting Started iOS article to find more information and download the SDK.

Windows or Windows Phone

While there is no dedicated Windows Phone or UWP SDK for Kinvey, you can use the Kinvey .NET SDK for your Windows-based apps.

Note that there is a dedicated Xamarin SDK for Kinvey, in case you are using that platform.

REST API

If you used the REST API of Telerik Backend Services, you can switch to using the Kinvey REST API.

Note that Kinvey provides native SDKs for more platforms than Telerik Backend Services. If you used the REST API of Telerik Backend Services because there was no native SDK for your platform, we suggest checking if Kinvey supports it. More information on supported SDKs is available in the Feature Comparison article.

Step 4: Migrate Cloud Data to Kinvey

After you have your Kinvey backend configured and your mobile app ready, you need to transfer your Telerik Backend Services data to it.

The data consists of:

  • Cloud data (content types)
  • Files
  • Users
  • Devices registered for push notifications

We are providing an automated tool to help you with the transfer of data. (Note: Coming soon.)

Step 5: Switch to Using the New App

The final part of the migration is to publish your updated app that works with the Kinvey backend to your customers.

Note that unless you have a way to force the installation of the new version, a large number of your customers will not update immediately. This means that they will continue to work with Telerik Backend Services. Depending on your app, this might not be acceptable.

There is an option in Telerik Backend Services that allows you to disable the backend for an app. You can use that option to force your customers to update to the Kinvey-based version of your app.

Additional Information

Automated Migration Tool

To ease the migration to Kinvey, we are providing an automated migration tool. This tool can help you with the following:

  • Partially migrating backend configuration
  • Migrating data

How to get the tool

Coming soon.

Disabling Your Telerik Backend

Once you have migrated your app to Kinvey, you can make sure that no new requests are handled by Telerik Backend Services. There are two options:

  • Partially disabled—only disable writing new data
  • Fully disabled—disable all requests

You can use this as a way to force your customers to update to the new version of the app that is using Kinvey. Also, it is the only way to make sure your customers with older versions of the app will not continue to write new data to Telerik Backend Services.

A good way to handle this is to first disable only the write operations and then after some time disable all requests. When you disable the write operations, your customers will still be able to read all the data and files you have, but not be able to insert or update data.

Note that even with the soft disable your app might stop working, depending on how it uses the backend and how it handles errors. Below you can find a table that explains what is working and what not in both modes.

Operation/Mode Partially Disabled Fully Disabled
from API from portal from API from portal
CRUD on external data only read enabled disabled only read
CRUD on cloud data only read enabled disabled only read
CRUD on users only read enabled disabled only read
User login/logout enabled n/a disabled n/a
CRUD on files only read enabled disabled only read
Upload files disabled enabled disabled disabled
Download files enabled enabled disabled enabled
Execute cloud functions enabled enabled disabled disabled
Execute stored procedures enabled enabled disabled disabled
CRUD on push notifications enabled enabled disabled only read
CRUD on push devices only read enabled disabled only read

To disable the backend, go to your app’s Settings page in the Telerik Platform Portal and then use the Disable Backend drop-down box to set the setting you want.

When you disable an app backend, all requests to disabled functionality return the following error:

{
    "errorCode": 1200,
    “message”: “This app is disabled.”
}

Getting Help with Migration

In case you encounter technical, development-related, or licensing issues when migrating your app’s backend to Kinvey, you can use the Telerik Platform support system to find a solution or report the problems.

Start by searching the Telerik Platform Backend Services documentation for a solution and continue your work without submitting a support request. For Kinvey-specific questions, you can refer to the Kinvey DevCenter resources.

If you cannot find a solution to your problem in the support resources, you need to submit a support request using your Progress Telerik account or ask for assistance in the forums. The level of support you can receive may be a subject to your subscription plan.

Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.