Migrate from GoodData Legacy to GoodData Cloud
6 min read | Published
If your organization is still running on GoodData Legacy, the case for moving to GoodData Cloud is straightforward: a richer self-service experience, a robust analytics as code approach, workspace hierarchies with inherited content, Python and React SDKs, and a fast-growing set of AI-powered capabilities that simply don't exist in Legacy.
What has historically made the migration feel daunting is the technical complexity of moving years of analytics content — logical data models, metrics, dashboards, Pixel Perfect Reports — across two platforms with fundamentally different architectures. That complexity is now largely automated.
This article introduces the open-source gooddata-legacy2cloud toolkit: a Python package that handles the migration of your analytics content from GoodData Legacy to GoodData Cloud, step by step, at your own pace, without requiring GoodData Professional Services engagement.
Key Takeaways
- GoodData Cloud is architecturally different from GoodData Legacy — a direct copy-paste migration doesn't work. Object identifiers need remapping, relationships need preserving, and Pixel Perfect Reports need conversion.
- The open-source gooddata-legacy2cloud toolkit automates migration of LDMs, metrics, insights, dashboards, Pixel Perfect Reports, scheduled exports, permissions, and color palettes.
- No Professional Services required. The toolkit is designed for self-service migration with detailed log files and mapping CSVs at every step.
- Three migration scenarios are supported out of the box: single workspace, parent/child workspace hierarchies, and incremental migration.
- The built-in Web Comparison Tool generates a visual, side-by-side comparison of every migrated object — color-coded by outcome — so validation doesn't require digging through log files.
Why Migrate to GoodData Cloud?
GoodData Cloud is the modern evolution of the GoodData analytics platform, built for the cloud-native era.
Compared to GoodData Legacy, it offers a significantly richer self-service experience alongside a robust analytics as code approach — Git-based version control, CI/CD pipelines, and infrastructure-as-code deployment, while still offering the intuitive drag-and-drop UI for business users. Workspace hierarchies allow child workspaces to automatically inherit content from a parent, eliminating the manual rollout process that Legacy requires. Python SDK, React SDK, and a growing set of AI-powered capabilities complete the picture.
When helping customers migrate to GoodData Cloud, we treat migration as an opportunity to modernize: keep what works, remove what's no longer used, and upgrade analytics with new AI and BI capabilities. This mirrors the broader principle that BI modernization and platform migration should happen together, not sequentially — a point covered in depth in the refactor-first approach to BI platform migration.
If your organization is still on GoodData Legacy, it's time to move.
How Hard Is the Migration?
From a product architecture perspective, GoodData Legacy and GoodData Cloud are significantly different — and a direct copy-paste migration doesn't work.
In Legacy, every workspace holds its own local copies of all objects: metrics, insights, dashboards. In Cloud, workspace hierarchies allow child workspaces to inherit content from their parent, meaning a single metric defined at the parent level is available to all child workspaces without duplication. This is a more powerful model, but it means objects need to be transformed, identifiers remapped, and relationships between objects carefully preserved during migration.
On top of that, Legacy contains two distinct types of reporting: KPI Dashboards (responsive, modern-style dashboards supported natively in Cloud) and Pixel Perfect Reports (pixel-precise tabular reports built on an older rendering engine that requires intelligent conversion to Cloud visualizations).
Manually handling this across hundreds or thousands of workspaces, dashboards, insights, and metrics has traditionally required expert Professional Services engagement. The gooddata-legacy2cloud toolkit changes that.
Introducing the Migration Toolkit
The gooddata-legacy2cloud toolkit is an open-source Python package (Python 3.14.2 required) available on GitHub and installable directly from PyPI with a single command.
The toolkit handles all critical migration steps:
- Mapping object identifiers across platforms within the logical data model (datasets, attributes, facts, date dimensions) and the analytics model (metrics, insights, dashboards)
- Translating MAQL metric definitions
- Migrating metrics, insights, and dashboards including their filter contexts
- Converting Pixel Perfect Reports to Cloud visualizations
- Preserving dashboard drill-through relationships
- Translating Legacy data products and segments into correct parent/child workspace hierarchies in Cloud
Using a clean, unified CLI, you run a single gooddata-legacy2cloud command with subcommands for each migration step:
gooddata-legacy2cloud ldm
gooddata-legacy2cloud metrics
gooddata-legacy2cloud insights
gooddata-legacy2cloud dashboards
Every command produces detailed log files and mapping CSVs — so you know exactly what was migrated, what was skipped, and what needs manual review.
What the Toolkit Migrates
Logical Data Model (LDM)
The foundation of everything. The toolkit migrates your entire data model: dataset definitions, date dimensions, attribute and fact mappings, and data source connections. It generates an ldm_mappings.csv file that all subsequent commands depend on to correctly remap object references.
Metrics
All MAQL-based calculated measures are converted and migrated to Cloud with automatic identifier translation. Where conversion isn't fully possible — for example, due to missing attribute element values — migrated metrics are flagged with a [WARN] or [ERROR] prefix in their title so they're easy to find and manually review.
Insights (Visualizations)
Charts, tables, and other visualizations are migrated along with their filter context definitions and configurations. Any insight requiring attention is clearly flagged with a [WARN] or [ERROR] prefix.
Note on geo charts: Geo charts are always flagged with [ERROR] because the geo label structure differs between platforms. Legacy uses a single label for latitude and longitude combined; Cloud requires two separate labels. If your solution includes geo charts, you'll need to update the Cloud LDM and recreate those charts manually.
KPI Dashboards
Full dashboard structures including layout, filters, drill-to-dashboard links, and KPI widgets. The toolkit handles cross-dashboard drills carefully: it first creates all dashboards as empty shells, then populates them, ensuring drill targets already exist before they're referenced.
Pixel Perfect Reports
These don't have a direct equivalent in Cloud, so the toolkit performs a best-effort conversion to Cloud visualizations. The visual output may differ from the original, and features specific to Pixel Perfect that have no Cloud equivalent are noted in the object description.
Pixel Perfect Dashboards
Migrated one-to-one into Cloud KPI dashboards using native tabs — one Legacy tab becomes one Cloud tab.
Scheduled Exports
Scheduled email automations attached to Legacy dashboards can be migrated to Cloud automations, matching recipients by email address and translating attachment types and filter selections. The corresponding users must be provisioned to Cloud before running this step.
Dashboard Permissions
Dashboard ownership and sharing permissions can be synchronized from Legacy to Cloud, mapping Legacy users and user groups to their Cloud counterparts.
Color Palette
Your organization's custom color palette is migrated and set as the default at the Cloud organization level.
Common Migration Scenarios
Single Workspace Migration
The simplest case: one Legacy workspace migrated into one Cloud workspace. Configure your .env file with source and target workspace credentials, then run the migration commands in sequence — LDM first, then metrics, insights, and dashboards. Verify results in your Cloud workspace after each step.
gooddata-legacy2cloud ldm
gooddata-legacy2cloud metrics
gooddata-legacy2cloud insights
gooddata-legacy2cloud dashboards
Parent/Child Workspace Migration
Many GoodData Legacy customers run a multi-workspace setup where a master workspace holds shared content and individual client workspaces hold customizations. In Legacy, content from the master workspace must be manually released and rolled out to client workspaces. In Cloud, workspace hierarchies handle this natively — child workspaces automatically see all content defined in the parent.
Migrate the parent workspace first to establish the shared foundation, then migrate each client workspace using the --client-prefix parameter:
gooddata-legacy2cloud metrics \
--legacy-ws client1_legacy_id \
--cloud-ws client1_cloud_id \
--client-prefix client1_
gooddata-legacy2cloud insights \
--legacy-ws client1_legacy_id \
--cloud-ws client1_cloud_id \
--client-prefix client1_
gooddata-legacy2cloud dashboards \
--legacy-ws client1_legacy_id \
--cloud-ws client1_cloud_id \
--client-prefix client1_
The toolkit verifies that the target Cloud workspace is correctly set up as a child workspace and migrates only objects unique to that client — not content already present in the parent.
Incremental Migration
For phased migrations or environments where new content has been added to Legacy after an initial migration run, the --without-mapped-objects parameter migrates only objects not yet migrated. The toolkit tracks everything in its mapping CSV files, so incremental runs are clean and safe as long as the mapping files remain untouched.
gooddata-legacy2cloud metrics --without-mapped-objects
gooddata-legacy2cloud insights --without-mapped-objects
gooddata-legacy2cloud dashboards --without-mapped-objects
Migration Validation
One of the standout features of the toolkit is the built-in Web Comparison Tool. After running migration commands, a single additional command generates a set of static HTML pages giving you a visual, side-by-side comparison of every migrated object:
gooddata-legacy2cloud web-compare
The comparison view lets you:
- See the migration status of every object at a glance, color-coded by outcome (success, warning, or error)
- Filter and search across objects by title, ID, or migration status
- Click into any individual object to open a live split-view comparison directly in Legacy and Cloud
- Review warning and error details without digging through log files
The output is a self-contained folder of HTML files that works entirely offline and can be shared with your team or clients without any server setup.
AI-Assisted Migration with GoodData.AI's MCP Server
For teams that prefer an AI-guided experience, GoodData.AI's MCP Server supports Legacy-to-Cloud migrations. It provides built-in skills to install and run the gooddata-legacy2cloud CLI and guides you through the migration process conversationally — without manually executing each command and interpreting output yourself.
Beyond orchestrating commands, the MCP Server can analyze migration artifacts, summarize results, and help you understand errors or warnings encountered along the way. For a broader view of how AI agents are changing BI migration work at the platform level, see why most BI migrations fail — and how GenAI is fixing that.
Migration in Practice: Aklamio
For a concrete example of what this migration looks like end-to-end, Aklamio's migration from GoodData Platform to GoodData Cloud shows the process in practice. Aklamio — an incentive platform serving over 400 brands — completed the migration in early 2025, moving from internal reporting to partner-facing embedded dashboards. Live Snowflake querying replaced their previous hourly sync model, and analytics as code workflows significantly accelerated iteration cycles across the team.
Aklamio's VP of Engineering, Thomas Karbe, described the engineering approach as central to their adoption: the ability to manage analytics objects via API and version control — "just like an engineer would" — was a decisive factor in how quickly their team could iterate after migration.
Get Started
Download the gooddata-legacy2cloud toolkit from GitHub and follow the README.md for configuration and setup. If you run into issues or have questions, reach out via GoodData Community Slack or GoodData Support.
No. The toolkit is designed for self-service migration: it produces detailed log files and mapping CSVs at every step so your team has full visibility into what was migrated, what was skipped, and what needs manual review. Professional Services remains an option for large or complex programs, but it's not required.
Pixel Perfect Reports don't have a direct equivalent in GoodData Cloud. The toolkit performs a best-effort conversion to Cloud visualizations, but the visual output may differ from the original. Any feature specific to Pixel Perfect that has no Cloud equivalent is noted in the object description. Review flagged items after migration and decide whether to recreate them manually or retire them.
Yes. The --without-mapped-objects parameter lets you run incremental migrations safely — the toolkit tracks everything it has already migrated in mapping CSV files, so subsequent runs only process new or unmigrated objects. This is the recommended approach for phased migrations.
Objects that require attention are flagged with [WARN] or [ERROR] prefixes in their title — visible immediately in the GoodData Cloud UI and in the Web Comparison Tool output. This makes it straightforward to identify what needs manual review without searching through log files.
In GoodData Legacy, shared content must be manually released and rolled out from a master workspace to client workspaces. In GoodData Cloud, workspace hierarchies handle this natively: content defined at the parent level is automatically available to all child workspaces. The toolkit migrates this structure directly — parent first, then each client workspace with the --client-prefix parameter to ensure only client-specific objects are migrated.
