How-to migrate

This document shows how to migrate a system from one IoT Enterprise environment to another.

PREREQUISITES:
Before migrating, make sure -

1. Both platforms are on the same version.

2. The user performing the migration is an Administrator on both environments.

KNOWN ISSUES:

1. If there is a custom column in the Edges table, the migration will fail. To overcome this issue:

   1. Delete the custom column from the source system before migration.

   2. Perform the migration (i.e. without the custom column).

   3. Add the custom column to both systems after the migration is done.

STEPS:
Let's say you want to migrate system S1 from environment E1 (source) to environment E2 (destination).

1. Go to S1 On E1.

2. Go to the Messages page and subscribe to the following topics:

   1. $notification/migration/status - Gives you migration status updates

   2. $notification/migration/error - Gives you migration status errors

3. Send a GET request to /admin/systemmigration/generatecredentials on E1 to generate a temporary username and password.
   
   This is an ADMIN endpoint so it requires a ClearBlade-DevToken header set to the token of a Developer on E1.

4. Once you get a temporary username and password, send a POST request to /admin/systemmigration/migrate on E2 to start the migration process. The POST body is as follows:

   CODE

   Username string `json:"username"` // generated from the step 3b 
   Password string `json:"password"` // generated from the step 3b 
   SystemKey string `json:"system_key"` // system key to be migrated 
   RemotePlatformURL string `json:"remote_platform_url"` // url of E1 without the 'https://'' prefix (e.g. community.clearblade.com) 
   RemotePlatformPort string `json:"remote_platform_port"` // can skip this

   This is an ADMIN endpoint so it requires a ClearBlade-DevToken header set to the token of a Developer on E2.
   
   Sending the request causes the migration to start.
   

5. Note that the new system on E2 will be initially disabled. It will need to be re-enabled from the Admin tab.