GoodData.CN: Migrating Objects Between Workspaces

Introduction

When working with your data in GoodData.CN, you may find that a measure or insight that you created in one workspace would also be useful in another workspace. The GoodData.CN API enables you to migrate copies of your objects to other workspaces.

Considerations

Before migrating objects, consider the logical data model (LDM) being used in each workspace. It is possible to migrate an object to a target workspace that uses a different LDM; however, the target workspace must include the same objects referenced by the object being migrated. 

If you are migrating a measure, for example, the target workspace should include the same facts and attributes used by the measure and they must have the exact same IDs in both workspaces. Similarly, you must also migrate any dependencies prior to the object you want to migrate. For example, say you built an insight in Analytical Designer that uses measures that you have created. Before you can migrate it to the target workspace, you first need to migrate the measures it uses, and then you can migrate the insight. 

One last thing to consider is the object IDs, which must be unique within each workspace. If you created an insight in the source workspace with the ID “my-revenue-chart” and you already have an insight in the target workspace with the ID “my-revenue-chart”, then the migration will not work unless you change the ID.

Migrating an object from one workspace to another

The process of migrating an object between workspaces is fairly straightforward: it involves exporting the object using the API endpoint for your source workspace and then importing it into the target workspace using the target’s API endpoint. Below, I will lay out a method for migrating a measure and an insight.

This tutorial will be using the GoodData.CN Community Edition installed locally, and will utilize objects from the "demolayout.json" layout provided in some of our other tutorials. 

Migrating a measure

Let’s say we have a measure called “Revenue” in one of our workspaces (the source workspace) that we want to reuse in another workspace (the target workspace).

We see that the Revenue measure contains a nested measure called “Order Amount”. So, first we’ll have to migrate the Order Amount measure.

Start by finding the ID of the Order Amount measure.

If you do not already know the ID of the measure, you can issue a GET request to the /metrics endpoint of the source workspace to return a list of all the measures you’ve already created:

curl http://localhost:3000/api/entities/workspaces/my-workspace/metrics \
  -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X GET \
  | jq > my_measures.json

This command will create a file called “my_measures.json” in the current directory with all the measures you have currently defined in the source workspace. (Remember to adjust the URL, and, if not using the GoodData.CN Community Edition, the authorization token as well.)

In “my_measures.json”, look for the ID of the measure you want to move. In this case, we see the “ID” field for the measure named “Order Amount” has the value “Test1”. This is our measure ID:

Next, we will issue a GET request to the /metrics endpoint of the source workspace to return only the measure with the ID of “Test1” and store it in a file called “measure1.json”:

curl http://localhost:3000/api/entities/workspaces/my-workspace/metrics/Test1 \
  -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X GET \
  | jq > measure1.json

Now, we can use this file to create the measure in the target workspace. Prior to doing so, ensure that there is not a measure with the exact same ID in the target workspace—in this case “Test1”. Use the curl command mentioned previously to get all the measures in the target workspace if you are unsure. If a measure does already exist in the target workspace with the ID “Test1”, then you can edit value of the “id” field in the “measure1.json” file to be an ID value that is not already in use.

Next, issue a POST request to the /metrics endpoint of the target workspace with measure1.json as the body of the request to create the measure:

curl http://localhost:3000/api/entities/workspaces/my-new-workspace/metrics \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -X POST \
  -d @measure1.json

Navigate to Analytical Designer in the target workspace in your browser to confirm that the measure was created:

We’ve just successfully migrated the “Order Amount” measure between workspaces. 

In our example, “Order Amount” was a nested measure for the “Revenue” measure that we ultimately wanted to migrate. Since it is the only dependency, we can now migrate Revenue. To do so, we will simply repeat the process used above. 

Referring back to our full list of measures from our source workspace in “my_measures.json”, we see that Revenue has the ID “Test5”. 

We can issue the following API call to the source workspace to get the Revenue measure and save it in a file called “measure2.json”:

curl http://localhost:3000/api/entities/workspaces/my-workspace/metrics/Test5 \
  -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X GET \
  | jq > measure2.json

Finally, issue a POST request to the /metrics endpoint of the target workspace to create the Revenue measure using measure2.json:

curl http://localhost:3000/api/entities/workspaces/my-new-workspace/metrics \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -X POST \
  -d @measure2.json

Navigate to the target workspace in your browser to confirm that the Revenue measure was successfully created:

We’ve just successfully migrated the Revenue measure to our target workspace. We also migrated a second measure, Order Amount, which was necessary as it was nested in our Revenue measure.

Migrating multiple measures at once

While the API does not directly allow creating multiple measures simultaneously, you can do so by using a simple script to iterate through a list and issue multiple API calls.

The following bash command is one such way of doing so. If you have all the measures from your source workspace saved in a file called “my_measures.json” as described above, then you can create all of them in the target workspace by running the following command. However, note that the measures in the file must be listed in order of their dependencies. That is, measures that reference nested measures must be listed in the json file after the nested measures they use (you can manually edit the json file to list them in the necessary order).

Run the following command against your target workspace’s /metrics endpoint:

for key in $(jq '.data | keys | .[]' my_measures.json);
do
  json=`jq '.data['$key']' my_measures.json`;
  curl http://localhost:3000/api/entities/workspaces/my-new-workspace/metrics \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -X POST \
  -d '{"data": '$json'}';
done | jq

If you had the measures listed in the file with dependencies listed first, then all of your measures should have been created successfully. You can confirm by navigating to the workspace in the browser.

You can also check the output of your command. If a measure contained a dependency which had not already been created, then you will see output like below describing that it failed to be created:

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Some of given referenced 'metrics' entities do not exist. Not existing IDs: StockId(apiId=Test5, scope=WorkspaceObjectScope(organization=default, space=addee8f07dcb426c8748b15caecf9428))",
  "traceId": "21a0f27267276a42"
}

Migrating Insight Objects

Migrating insights works the same way as migrating measures: we first migrate any dependencies, then we export the insight from the source workspace and finally import it to the target workspace. 

If we want to migrate an insight called “Revenue Trend”, shown below, we must first migrate the measure it uses, called “Revenue”. This is the measure we migrated in our previous example.

Issue the following GET request to the /visualizationObjects endpoint of our source workspace to create a file called “my_insights.json” with a list of all the insights we’ve created:

curl http://localhost:3000/api/entities/workspaces/my-workspace/visualizationObjects \
  -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X GET \
  | jq > my_insights.json

In that file, we can search for the insight called “Revenue Trend” to find its ID:

Alternatively, we can also find the ID of an insight by opening it in Analytical Designer and looking at the URL:

Next, we will issue a GET request to return only that insight and save it to a file called “insight1.json”:

curl http://localhost:3000/api/entities/workspaces/my-workspace/visualizationObjects/82ee02f5-da98-4783-9500-ed84d8900047 \
  -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X GET \
  | jq > insight1.json

And finally, issue a POST request to the target workspace to create the insight from the file we just created:

curl http://localhost:3000/api/entities/workspaces/4157dba4efa848acbc53a9e4f00a4c84/visualizationObjects \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -X POST \
  -d @insight1.json

We’ve just created the insight in our target workspace. We can now navigate to Analytical Designer in our target workspace in a browser to verify it was created:

Further considerations

This tutorial described how to migrate insights and measures, but you can also migrate dashboards or filters using the same process. Reference our API documentation for more details on the exposed resources available for GoodData.CN. 

If you want to create a copy of an entire workspace, refer to our tutorial on cloning workspaces. 

If you are interested in GoodData.CN, please contact us.

Alternatively, test a trial version of GoodData Cloud:

Start Your GoodData Analytics Trial — Commitment-Free