Background

If you have logged into your Parse Dashboard recently, you will have seen this.

Parse is shutting down

Parse will be shut down on January 28th 2017. If you have developed a mobile app that relies on Parse for backend data storage or push notifications, then you need to take action now to ensure the users of the app do not experience any interruption in service that could lead to bad reviews and unhappy clients. This guide outlines the steps you need to take to migrate from Parse to Kumulos, including:

Getting Started

Signing up for a free trial

First things first - you'll need a Kumulos account! Head over to www.kumulos.com and signup for a free trial. Kumulos features are free to use on up to 25 test devices for 30 days while you complete your app migration.

Creating a client

Kumulos groups your Apps under Clients, usually the name of the company you are building the app for. To add a new client click the primary action button.

Add a Client

Fill in the name of the client. If you are building an app for someone else, you can enable the Client Portal so they can get read-only access to the analytics and reports for their apps. You can also share files and links with them during the migration project. If you choose not to enable it now, you can edit the client enable the client portal for them at a later date. Click "Save" when done.

Add a Client

You will now be redirected to the client dashboard.

Adding an app

Now, you can add an app for that client by clicking primary action button. Fill in the name of the App, and optionally, add a brief description and upload an icon. Click "Save" when done.

Create an App

You will now be redirected to the dashboard for that app.

Migrating your data to Kumulos

Enabling App Build

The App Build feature in Kumulos provides cloud-based, relational database storage. If you used the Parse Core Backend-as-a-Service, then this is where you will migrate your parse data objects to. Click "Start" on the Build feature.

Enable Build

This will prompt you to choose your preferred data hosting option. Choose "New Managed Database".

Managed Data Hosting

Creating tables for Parse classes

Your data in Parse was stored in classes. Your data in Kumulos will be stored in tables. You will need to create a table for each Parse class used by your app. Login your Parse Dashboard, select the app you want to migrate and then select "Core". Under the browser you can see all of the classes used by your app. Click on a class to see the columns and their type for that class.

Parse Classes

In Kumulos, select "Build" and then "Tables" from the left menu and click on add button on the right to create a table for that class.

Screenshot

Give your table a title, which will automatically be pluralised by Kumulos as a matter of convention. Now, for each column in the Parse class, drag and drop a field of that type from the right hand column into the middle table editor pane as required:

  • For String columns, use the Text/String field type
  • For Number columns, use a Number field type (e.g. Float or Integer) as appropriate
  • For columns that contain Parse Files, use the Data field type
  • For Boolean columns, use the Boolean field type
  • For Date columns, use the Date/Time field type

Give the field the same name as in Parse, although note that Kumulos will convert field names to lowerCamelCase for consistency.

Screenshot

Kumulos will automatically add a primary key id field, a timeCreated and timeUpdated field for your table so you do not need to recreate the objectId, timeCreated or timeUpdated column in Parse.

When you're happy with the schema you've defined, click the "Save" button. Repeat this for each of your Parse classes. More information on modeling data in Kumulos can be found in our relational data modeling guide.

Importing parse data objects

If you have a lot of data object to migrate, our awesome technical support team are standing by to import this for you. First, export the objects for the class you want to migrate. In the Parse Browser, click "Edit" and, ensuring you have no filters applied, select "Export this data".

Export this data

Click "Export" when prompted to request an export by email.

Export email

Save the attachment and repeat this for each class you want to migrate.

Once you have exported all the data objects, contact technical support who will import the data for you. For smaller amounts of data, you can just attach the exports to the email. For larger amounts of data, our technical support team will arrange the transfer.

Accessing your data from your app

To access your data you can use the RESTful API from any HTTP client or use the drag-and-drop API editor to create RPC API Methods that you can access by integrating one of our SDKs. While the RESTful API may be more familiar to developers who are used to Parse, which approach you use for your app, will very much depend on when and how you access your data (and personal preference). The following video will give you an overview of each approach.


Accessing your data with the RESTful API

To access your data via the RESTful API, you first need to generate an API key. To do this, select "Build" and then "API" from the left menu. Now, click on the "REST" tab.

To add a new API key, click the primary action button on the right, you will then be shown the create API key form. Select the permissions you would like the key to have and click "Create".

Add API key form

You can now use the RESTful API to access your data as shown in the Integration Guide.

At present, the RESTful API only supports filtering results by id field. For more advanced filtering, sorting and joining on related data, use RPC API Methods

Accessing your data with RPC API Methods

You can also use the drag-and-drop API editor to create RPC API Methods that support filtering, sorting and joining on related data. Please see the API Methods section of our docs for full details on creating and testing RPC API Methods.

API Actions

Once created, in order to make your API available to your app, you need to deploy the API methods. This step is important and turns your methods into native server-side code and also native client bindings. When you build your API, all methods you've added or deleted since the last deployment are synchronized so the changes are live.

To deploy your API, select on "Deploy" from the left hand menu. Select each of the client SDKs you want to use in your app and click the "deploy" button.

Deploying API Methods

You can now download the SDK bundle(s) that have been generated from "Download" in the left hand menu.

Download SDKs

Please refer to the appropriate integration guide for each platform for details of how to integrate each SDK into your app project.

Enabling Production Mode

At the end of your 30 day trial, once you have migrated your data to Kumulos and updated your app to use the Kumulos RESTful API or integrated one of our SDKs to call RPC API Methods, you need to enable production mode for your app to ensure uninterrupted API service.

First of all, you need a valid payment subscription. Click on the drop-down menu by your login and select "Account Settings" and then "Billing". Enter your payment card details to create a new Kumulos subscription.

Add payment card details Subscription

Next, click on "Build" in the left hand menu and toggle the "Production Mode" switch to "On".

Production Mode

When not in production mode, use of Kumulos is limited to 30 days on 25 test installations.

Using Kumulos push notifications

If you used Parse to send Push Notifications to your app, you need to update your app to use the Kumulos Push Notifications instead.

Enabling Push Notifications

To enable push notifications for an app, click on that app and then from the app dashboard for that app, select "Push" in the left menu.

Push Dashboard

Click the primary action button to enable push notifications, clicking YES,PROCEED when prompted.

Enable Push Dialog

Configuring Push Notifications

In order to send push notifications to iOS and/or Android devices you must configure the Apple Push Notification Service (APNS) and/or Google Cloud Messaging (GCM) and upload your push certificate to Kumulos.

Configure Push Dashboard

Either click CONFIGURE NOW or the cog icon next to the platform you would like to configure. This will open the platform configuration dialog where you can enter the required information to send push notifications to iOS devices via APNS and/or Android devices via GCM.

Configure Push Dialog

GCM Configuration

In order to send push notifications to Android devices with Kumulos, you'll need to set up a GCM project and configure push for your app. These steps are shown in the following video guide.

Configuring GCM for Android with Kumulos

After configuring Kumulos and GCM, refer to the Android SDK integration guide for instructions for integrating Kumulos into your app project.

APNS Configuration

In order to send push notifications to iOS devices with Kumulos, you'll need to create certificates in the Apple Developer Member Center. The steps to complete this are shown in the video guide.

Configuring APNS for iOS with Kumulos

After configuring your project, you can refer to the Objective-C integration guide or Swift SDK integration guide as appropriate for details on integrating the notifications into your app.

Sending Push Notifications

Once configured, the dashboard will change to a summary view of trends in your subscribers and notifications history along with a summary of recent notifications that have been sent.

Configured Push Dashboard

To send a push notification, click the primary action button to display the Compose Push Notification dialog.

Compose Dialog

Fill in the title and message content for your notification and click "Send". Your clients can send notifications from their client portal in exactly the same way. Please refer to the Push Notifications section of our docs for more details.

Currently, you can send broadcast notifications to every installation that has registered to receive push notifications from your app. Soon you will also be able to segment your audience to target specific user groups based on platform, location and recent activity.

If you use the Kumulos Build feature, then you can send notifications programmatically from your app via Kscripts. Please refer to the API reference for KScript for more details.

In addition, you can send notifications by building an integration with the REST interface of the Kumulos Push API, allowing you complete flexibility when defining the business rules that generate notifications.

Migrating Cloud Code to KScripts

KScript allows you to use Kumulos to encapsulate business logic in custom server-side jobs, written in JavaScript. It will be deployed and accessed in the same way as your existing API methods but offers you much greater flexibility and control over what happens on the server-side of Kumulos. If you have deployed Cloud Code in Parse, you can migrate this to KScripts in Kumulos.

Enabling KScript

KScript is not enabled by default as the majority of use cases can be satisfied via API Methods. If you wish to add server-side jobs, please contact technical support who will be happy to enable KScripts for you.

Once you receive an email confirming that KScript has been enabled for your app, you can then create KScript methods by selecting "Build" and then "API" from the left hane menu. Underneath the "Create API" button, there will now be a "Create Some KScript" button once its enabled on your app.

Writing KScript Methods

In Parse Core, click on "Cloud Code" to see your methods.

Parse Cloud Code

As Kscript also uses Javascript, it should be straightforward to port your cloud code to Kscript methods. Please see the Kscript reference guide for more details and the cookbook section of our docs for example methods.

Social Authentication

If your application requires users to authenticate in order to access content, then you can either build your own authentication mechanism in Kumulos or you can use Kumulos to integrate Facebook Login or the Google Identity Platform to support social login for your users.

The following section of the migration guide will show you how you can write a KScript to allow your users to login with their Facebook credentials and then use the Facebook Graph API to retrieve details about them.

This assumes that you have a Facebook developer account and have registered your app.

Kscripts includes a Facebook SDK for use within your Kscript methods. It requires a valid Facebook access token in order to initialize for use.

The access token is retrieved by integrating a Facebook SDK into your app and then following the Facebook login guide.

Once initialized, you can then call the Facebook Graph API from your KScript methods to access the users profile. A sequence diagram illustrating an example integration is as follows:

Facebook Integration Sequence Diagram

Click the 'Create Some KScript' button and create a new KScript method called setFacebookAccessToken to upload the user access token and save this in the KScript session.

K.session.fbAccessToken = K.params.fbAccessToken;

Click the 'Create Some KScript' button and create a new KScript method called _facebook_ to encapsulate the initialization of the Facebook SDK.

var FB_APP_ID = '';
var FB_APP_SECRET = '';
// Assume session storage of access token set by setFacebookAccessToken
K.initFB(FB_APP_ID, FB_APP_SECRET, K.session.fbAccessToken);

Finally, click the 'Create Some KScript' button and create a new KScript method called getUserProfile to make an API call to the Facebook Graph API.

include('_facebook_');
var userProfile = K.FB.api('/me');
K.log(userProfile);
K.setResponse(userProfile);

A similar process can be implemented to integrate the Google Identity Platform]

A full reference guide to the Facebook Graph API can be found on the Facebook Developer Site. Some methods may require the Facebook User ID. This can be retrieved via the K.FB.getUser() method (for which further information can be found in the KScript Reference Guide).