How to use Interactive Map Layers to migrate Data Hub spaces

In order for your applications to access your datasets on the HERE platform, you must update your applications currently using HERE Data Hub spaces to use Interactive Map Layers (IML) API endpoints. For more information on IML, see the Data API.  

In this blog, we will outline a complete guide to Migrate Data Hub Spaces using IML. 

Warning

Note: We are NOT copying data with this process. We are creating a configuration which creates an IML that points to the old data. Until Data Hub is finally ramped down, you can access the same data via the old Data Hub Space and also through the new IML. We offer this to support an easy migration of your clients. 

As such we highly recommend that you write to a dataset via one API only. Reading through both will work though you may see stale data via the other respective API.  You cannot create new Spaces or edit existing Spaces configuration after you have started the migration. 

Preparation

You will need two tokens to complete this workflow. One from Data Hub and one from HERE platform.

Data Hub Token 

To start, we will need a token with manageSpaces permission on all Spaces. To create one:

• Login to https://xyz.api.here.com/console (use Chrome or Edge, Firefox is not supported currently for this) 
• Go to Access Manager tab :

• Next, click Generate Token:

• Check manageSpaces in the ALL row:

• Next - Skip capabilities and Connectors
• Next
  • Select Permanent or Temporary. We recommend to run the migration close after this and choose a short living temporary token.
  • Add Description
  • Keep allowed origins/hosts empty
  • Select an app
  • Submit

The Token is displayed in the green top banner. You click "Copy Token" and save it for later. We will refer to this as yourDatahubToken from now on.

HERE platform Token

Now we need to log in to the HERE platform and open https://platform.in.here.com/api/portal/accessToken.

You will get a JSON file as a download. Formatted, it looks like this:

        {

  "accessToken": "<a long string>",

  "refreshTokenExpires": "2023-02-01T17:05:49.319Z",

  "accessTokenExpires": "2023-01-21T17:05:48.319Z"

}
  

• Copy the long string value of accessToken.

We will refer to this as yourPlatformToken from now on.

Note: You will have to execute some REST requests. You can do this with a REST tool or plain curl. In this example, we use curl in the command line.

Review your resources

Note: Before starting the migration you can list your resources. With this, we will also indicate if a certain Space can be migrated or not. Certain features are not supported on IML. Spaces using those won't be migrated. You will need to set up a new IML and copy manually in this scenario. Refer to previous steps.

        curl -X 'GET' \

  'https://conversion-service-eu-west-1.api-gateway.ls.hereapi.com/list/dh' \

  -H 'accept: application/json' \

  -H 'Authorization: Bearer <yourPlatformToken>' \

  -H 'Dh-Token: <yourDatahubToken>'
  

Run the migration

Note: You need to execute a POST request. You can do this with a REST tool or plain curl. In this example, we use curl on the command line:

        curl -X 'POST' \

  'https://conversion-service-eu-west-1.api-gateway.ls.hereapi.com/convert/dh' \

  -H 'accept: application/json' \

  -H 'Authorization: Bearer <yourPlatformToken>' \

  -H 'Dh-Token: <yourDatahubToken>'
  

In the JSON response you will find a jobId. You will need this jobId to query the status and result of the job or to restart it later on.

Review your new IMLs

• Login to HERE platform if not already
• Go to your Data Services under "Data" in the launcher
• You will find one Catalog with one Layer (IML) for each Data Hub Space. The Space Id is part of the ids.

Other API endpoints

Get jobs by the target user

You can also migrate Spaces of multiple source users to one destination user. One job is always related to the source user. If you want to lookup jobs based on the destination user, you can use this endpoint:

        curl -X 'GET' \

  'https://conversion-service-eu-west-1.api-gateway.ls.hereapi.com/convert/dh' \

  -H 'accept: application/json' \

  -H 'Authorization: Bearer <yourPlatformToken>'
  

Get the status of an already-started job

With this you can check if a job is done. For a typical use, a job should take only a few minutes. If the job is finished you will receive the result: Which space is migrated and which is not. For the migrated space, you will find ids for the new catalog and layer. For the space that isn't migrated, a reason why they are not migrated is provided.

        curl -X 'GET' \

  'https://conversion-service-eu-west-1.api-gateway.ls.hereapi.com/convert/dh/{jobId}' \

  -H 'accept: application/json' \

  -H 'Authorization: Bearer <yourPlatformToken>'
  

Restart a job

If something went wrong (or new resources have been created in the meantime), you can restart a job. You can't create a new job for the same source user:

        curl -X 'POST' \

  'https://conversion-service-eu-west-1.api-gateway.ls.hereapi.com/convert/dh/{jobId}' \

  -H 'accept: application/json' \

  -H 'Authorization: Bearer <yourPlatformToken>' \

  -H 'Dh-Token: <yourDatahubToken>'
  

This concludes the guide to migrating Data Hub Spaces using IML! We hope this guide was helpful to you.

For more information on IML and using them, please check out this blog on how to upload IML to HERE platform.