Page tree
Skip to end of metadata
Go to start of metadata

GoodData platform provides you with several tools to migrate selected objects between projects. For example, you can quickly migrate dashboards or other metadata from your development project into one or more production projects using one of the methods described in this article.

GoodData platform also supports the cloning of complete projects using export and import APIs. For more information, see Clone a Project.

Contents:

Overview and Prerequisites

You must be logged into the GoodData platform using the same account for both the export and the import. That account must have administrator privileges in each project.

Before you begin, you should acquire the project identifiers of the target and destination project, which are easily retrieved from the URL when you first select each project in the GoodData Portal.

Migration of objects between projects has the following criteria:

  • Every object has its unique URI.
  • Projects must have the same logical data model if you want to migrate objects between them.
  • Migration works for metrics, reports and dashboards.

For example, suppose that you have two Human Resources projects, each of which uses an identical logical data model.

  • Project 1: The sandbox project where you perform your development work.
  • Project 2: The production project where your finished development work is published.
  • For more information on this basic example, see HR data analysis.

In this workflow, you prepare your new object(s) in Project 1. In this case, the new object is the Total Payment by Quarter report.

Project 1: Development Project

Project 2: Production Project

As you can see below, the HR Demo Copy is empty.

The rest of this page describes how to perform these types of migrations through one of the available interfaces: Gray Pages, CL Tool, or direct interaction with the GoodData APIs.

Acquiring Object Identifiers

An easy way to acquire is to select the object in the source project. The hashed value at the end of the URL is the internal identifier. For example, in the following project URL, an object is selected:

https://secure.gooddata.com/#s=/gdc/projects/njy3r40rc9s4jvrm0y9cqyfghxlo1osu|analysisPage|head|/gdc/md/njy3r40rc9s4jvrm0y9cqyfghxlo1osu/obj/351

In the above example, the object identifier is the URI value after |head|:

/gdc/md/njy3r40rc9s4jvrm0y9cqyfghxlo1osu/obj/351

For metrics, attributes, and facts, this method works if you select them using the Manage page in the GoodData Portal

Migrating Objects via Gray Pages

The following sections describe the required steps to migrate objects between projects through the gray pages.

Retrieving object identifiers from the gray pages

Steps:

  1. Go to the Query screen:

    https://secure.gooddata.com/gdc/md/{project-id}/query

  2. Navigate the object hierarchy to locate and select the object by its title.
  3. The object identifier is the value for the URI:

Partial metadata export via gray pages

Steps:

  1. Go to the Maintenance screen:

    https://secure.gooddata.com/gdc/md/{project-id}/maintenance
  2. Click partial-md-export.
  3. The PartialMDExport screen is displayed:
  4. In the text box, enter the object identifier value. Click submit.
  5. In the response, retrieve the value for token:

Partial metadata import via gray pages

Steps:

  1. Retrieve the project identifier for the destination project.
  2. Go to the Maintenance screen for the destination project: 

    https://secure.gooddata.com/gdc/md/{project-id}/maintenance
  3. Click partial-md-import.
  4. The PartialMDImport screen is displayed:

    It is possible to allow overwriting of the logical data model in cases where the imported object forces changes to it. However, making changes to the LDM can have cascading effects throughout the project, including the unexpected deletion of project data. It is recommended that you do not select this option unless you have thoroughly tested the impacts of this overwrite first.

  5. Select the checkbox to enable overwriting of any newer objects already in the project.
  6. In the text box, enter the value for the token that was generated. Click submit.
  7. If a status link is displayed, click it until you receive an OK status:
  8. The object has been imported.

Migrating Objects via APIs

To migrate project objects via API, you must execute the following calls using the partial metadata export and import APIs:

This method is typically used for migrating an object from a single source project to multiple target projects.

  1. Acquire object identifiers of the object to export. For more information, see Acquiring Object Identifiers.
  2. Generate URI identifier for the object to export, which is in the following form:
    /gdc/md/{project-id}/obj/{object-id}
    where:
    {project-id} is the internal identifier for the source project.
    {object-id} is the internal identifier for the object within the source project.
  3. Object export: Partial Metadata Export API:  POST -/gdc/md/{project-id}/maintenance/partialmdexport
  4. Object import: Partial Metadata Import API:  POST -/gdc/md/{project-id}/maintenance/partialmdimport

Migrating Objects via CL Tool

This section describes how to perform object migrations between projects using the CL Tool.

The CL Tool is a legacy interface and may be deprecated in a future release. Instead of using the CL Tool, you may want to switch to migrating via API or via gray pages.

Exporting objects

Before you begin, acquire the object identifiers for the source project, destination project, and object to export. For more information, see Acquiring Object Identifiers.

To export a report through CL Tool, execute the following script:

UseProject(fileName="..."); 

ExportMetadataObjects(tokenFile="...", objectIDs="...");

This functionality is available in the CL Tool 1.2.40 or higher.

Before executing ExportMetadataObjects you must use the UseProject or the OpenProject command to open the target project.

This command exports metadata objects with all dependencies. The tokenFile is a file where the import token is stored. In objectIDs, you paste the comma-separated list of the metadata object IDs. The Object ID is a numerical value located on the end of the URL when the object is selected.

When you use CL Tool for migration, you have to specify the numeric value for the {object-id}. When you want to do the same via gray pages, you must specify the URI, which is the part of the URL.

In this example, the report metadata contains the author, title, URI etc. When the script is executed, the generated token is written to the tokenFile file.

Importing objects

To import an exported object, you must apply the tokenFile containing the generated token to the following script. Before executing ImportMetadataObjects you must use the UseProject or the OpenProject command to open the target project.

Use the ImportMetadataObjects command:

UseProject(fileName="...");

ImportMetadataObjects(tokenFile="...", overwrite="<1|0>", updateLDM="<1|0>");

The command imports metadata objects from the token. The import command has two options:

  • updateLDM - If set to 1, the attributes, facts names and descriptions are updated.
    It is possible to allow overwriting of the logical data model in cases where the imported object forces changes to it. However, making changes to the LDM can have cascading effects throughout the project, including the unexpected deletion of project data. We recommend that you do not select this option unless you first test the impacts of this overwrite.
  • overwrite - If set to 1, the existing metadata are overwritten.
    Only overwrite=1 is currently supported.

If the import was successful, you can log into the target project. Click Reports and verify that the report is there:


The report was successfully migrated from one project to another.