The Telerik Platform product is retired.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:


Before you start planning a migration, you'll probably want to learn about the differences between Telerik Backend Services and Kinvey.

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 the feature parity between the two products in the Feature Comparison article. The Data Field Mapping Reference document contains valuable reference information that can help you plan your development efforts.

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 refer to 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. Important information about data field mapping is provided in Data Field Mapping Reference.

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.

Role-Based Access Control

One of the first things to do after migrating the backend configuration to Kinvey, or alternatively, you may consider doing so after the actual data migration, is to set the corresponding permissions for each role over a collection. This includes the Users, Files and custom data collections.

You can do so in Kinvey using the web-based interface or using the REST API as explained here.

More information on role-based access control in Kinvey is available here.

For more information about the differences in role-based access control in Kinvey and Telerik Platform Backend Services, please refer to the Feature Comparison document.

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 Structure

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 a content type structure for a collection. As in Telerik Platform Backend Services, no schema/type definitions will be enforced on the inserted data. You can enforce that using Business Logic.

Still, you need to manually set the collection permissions for the data migrated to Kinvey.

Cloud Files

The Files collection in Kinvey is also subject to Role-based access control. Refer to the above information for “Role-Based Access Control” for more information about how to do so.

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
  • Settings like automatic email verification, password reset, etc.
  • Role-based access control permissions

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.

Note that in Kinvey each app user can access a custom endpoint. If you need to deny access to some users or depending on the user role, for example, you need to programmatically control the execution of the logic in the custom endpoint from your business logic code.

Scheduled Jobs

You have to define your scheduled jobs in your Kinvey app environment from scratch.

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.


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

User accounts created from Microsoft Accounts, ADFS 2.0 and SAML 2.0 will not be migrated. To continue using these providers you will need to configure a Mobile Identity Connect service in Kinvey and re-create the user accounts.

We are providing an automated tool to help you with the transfer of data. You can read more about how to obtain and use the tool in the Additional Information section.

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.

Using the 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

Before starting the migration ensure you have reviewed the contents of the Data Field Mapping Reference.


The automated migration tool depends on the following software:

  • Node.js version 6.x.x or later
  • npm in any version that supports the required Node.js version
  • Git

Getting the Tool

The migration tool is a Node.js script. You can get the package through its GitHub repository from the following link:

Installing Dependencies

Before using the tool ensure you've installed the required dependencies by running:

npm install

Configuring the Migration Tool

Before you use the migration tool you need to configure it to work with your Kinvey and Telerik Platform accounts. The configuration is stored in the config.json file located in the directory where you installed the migration tool. Edit it to provide the following information:

  • Kinvey configuration

    • kinvey_api_host—Host to use when invoking requests to Kinvey. Leave this to the default, unless you have a dedicated Kinvey instance.
    • kinvey_manage_host—Host to use when invoking administration requests to Kinvey. Leave this to the default unless you have a dedicated Kinvey instance.
    • kinvey_kidMandatory Kinvey App Key for the app enviroment you would like to migrate to.
    • kinvey_app_secretMandatory Kinvey App Secret for the app enviroment you would like to migrate to.
    • kinvey_master_secretMandatory Kinvey Master Secret for the app enviroment you would like to migrate to. You can find your Kinvey API keys for a given app environment by navigating to the Settings > Environment Settings > API keys section from the navigation pane on the left in the Kinvey web console.
    • kinvey_token—Do not edit manually. This token will be set automatically after the tool initializes and creates a session in result of authentication.
  • Telerik Platform Backend Services configuration

    • bs_app_idMandatory Telerik Platform App Id of the app that you want to migrate. Learn how to find your App ID and API Master Key.
    • bs_master_keyMandatory Master key of the app that you want to migrate. You can find the master key in the Telerik Platform portal.

    The master keys and kinvey_token give unlimited access to the respective backend applications and to your Kinvey account. Keep them in a secure place and do not expose them to third parties.

Initializing the Migration Tool

After configuring the backend tokens and keys in the configuration file you need to initialize an administrator user session in Kinvey. At a command prompt, navigate to the directory where you installed the migration tool and invoke the following command:

$ node index.js --login

When prompted, enter the username (usually in the form of an email address) and the password for an administrator account belonging to the Kinvey environment you want to target with the migration.

The following message signals the successful creation of a session:

Successfully configured Migration tool.

Migrating Backend Configuration

As the next migration step you need to migrate the backend configuration from the source Telerik Platform app to the target Kinvey app environment.

You cannot migrate a custom content type named "User" or "user". If you have such a content type, the migration tool shows the error message "Collection name is already taken" during migration. Consider changing the source content type name before you start.

To start the backend configuration migration, navigate to the directory where you installed the migration tool and invoke the following command.

$ node index.js --migrate-config

The command will start the migration of the following backend configuration assets from Backend Services to their corresponding assets in Kinvey:

  • Content Types to Collections
  • Roles
  • Cloud Functions to Custom Endpoints
  • Cloud Code for Data to Business Logic Hooks

Content types from a Data Connector are not migrated.

Roles are migrated with their names but receive new random IDs in Kinvey. User accounts are migrated by assigning them to the roleId of the Kinvey role that matches the name of the original Backend Services user role. Before you start, ensure that you don't any roles with matching names in Kinvey because this may lead to an undesired behavior.

The code in the Backend Services beforeCreate and beforeUpdate event handlers is transferred as a onPreSave hook in Kinvey. Adjust your code to handle the different cases where the save operation is either an updateor create.

The code in the Backend Services afterCreate and afterUpdate event handlers is transferred as a onPostSave hook in Kinvey. Adjust your code to handle the different cases where the save operation is either an updateor create.

Migrating Backend Data

After you have migrated the backend configuration you can proceed with migrating actual data. Ensure that you have a steady internet connection, preferably over a cable connection.

If you have enabled the "Automatically send verification email" option in Kinvey for the purpose of verifying users over email, you may want to turn it off before migrating the user accounts from Telerik Platform Backend Services to Kinvey. Otherwise an email notification will be sent to each of the migrated accounts after they are created in Kinvey.

To start migrating data, navigate to the directory where you installed the migration tool and enter the following command:

$ node index.js --migrate-data

This command starts the migration of data items from the following Backend Services content types to the Kinvey collections:

  • Custom-defined content types
  • Users
  • Files

User accounts created from Microsoft Account social authentication are not migrated.

Troubleshooting the Migration Tool

The following section explains some common errors or unexpected behavior that you may encounter during the migration process and how to resolve them.

  • 422 - {"code":"ValidationError","description":"Validation failed.","errors":[{"field":"name","message":"Collection name is already taken."}]}If you receive an error for existing items you will need to (backup) and delete the item and restart the migration. Note that some other data may have already be migrated and will subsequently throw a similar error.
  • 422 - {"code":"ValidationError","description":"Validation failed.","errors":[{"field":"name","message":"Endpoint name is already taken."}]} - same as above.
  • 400 - {"code":"MalformedAuthorizationHeader","description":"The Authorization header must be: Kinvey realm=\"Kinvey authorization needed\""} - you need to login again using the —login command.

Additional Information

This section contains information and procedures that you might need to use during migration.

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
Copyright © 2016-2018, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.