Data Migration

This guide explains how to export and import gadget configurations, move setups between dashboards, back up your configurations, and understand what can and cannot be migrated.

---

Overview

The app stores gadget configurations (chart settings, column choices, filter fields, display options) in Atlassian Forge KVS - not in Jira issues or project data. When you "migrate" a dashboard setup, you are moving these gadget configurations, not Jira data.

Important: Uninstalling the app permanently deletes all stored gadget configurations. Back up important configurations before uninstalling.

---

How to Export a Gadget Configuration

Every gadget has a built-in JSON export that captures the complete configuration:

1. Open the gadget in edit mode
2. Click the Import/Export tab in the right settings panel
3. Click Export Configuration
4. The configuration JSON is shown in the text area - copy the entire JSON string
5. Save it to a file or document for safekeeping

What the Export JSON Contains

---

How to Import a Configuration

1. Add a new gadget of the same type to a dashboard
2. Open it in edit mode
3. Click the Import/Export tab
4. Paste the exported JSON into the import text area
5. Click Import - all settings are applied immediately
6. Check the Live Preview to confirm everything looks correct
7. Adjust the data source if needed (the import does not transfer data source selections - you must re-select the project or filter)
8. Click Save gadget

Note: You must re-select the data source after import. Project names and filter IDs are environment-specific and may differ between dashboards or Jira instances.

---

Moving Configurations Between Dashboards (Same Jira Instance)

Use Import/Export to copy a gadget from one dashboard to another within the same Jira site:

1. Export the configuration from the source gadget (steps above)
2. Open the destination dashboard in edit mode
3. Add a new gadget of the same type
4. Import the configuration into the new gadget
5. Re-select the data source (project, filter, or JQL)
6. Save

Dynamic Filter Controller - Special Consideration

When moving a Dynamic Filter Controller to a new dashboard:

• The controller gets a new Reference ID on the new dashboard
• All connected charts on the new dashboard must be re-connected to the new Reference ID
• Export and import the controller configuration, then re-link each connected gadget

---

Moving Configurations Between Jira Instances

Gadget configurations can be moved between different Jira Cloud sites using the same Import/Export process, but with additional manual steps:

Steps

1. Export the gadget configuration JSON from the source Jira instance
2. On the target Jira instance, add a new gadget of the same type
3. Import the JSON
4. Re-select the data source - project names and filter IDs do not transfer between instances
5. Verify that custom fields used in Chart By, Group By, or columns exist on the target instance (field names must match)
6. Verify that JQL segment conditions reference valid field names and values on the target instance
7. Save

What Transfers Cleanly

---

JSON Configuration Backup

Best practices for backing up your gadget configurations:

Before Major Changes

Always export configuration before making significant changes to a working gadget - this gives you a restore point.

Regular Backup Process

1. For each important gadget, open it in edit mode
2. Export the configuration JSON
3. Save to a shared document, wiki page, or version-controlled file

Backup Format Recommendation

Store backups as plain text files with a clear naming convention:

dashboard-name_gadget-type_chart-name_YYYY-MM-DD.json

Example:

sprint-dashboard_custom-charts_bug-by-priority_2026-05-19.json
team-dashboard_issue-list_workload-view_2026-05-19.json

What to Back Up Before Uninstalling

If you plan to uninstall and reinstall the app:

1. Export every gadget configuration you want to preserve
2. Note the Reference IDs of Dynamic Filter Controllers and which charts connect to each
3. Document your dashboard layouts (screenshot or notes)
4. After reinstalling, import configurations and re-establish controller connections

---

Limitations