Migration to Cloud

Automatic migration of rich filter gadgets using the Jira Cloud Migration Assistant (JCMA) is supported by Rich Filters for Jira Dashboards starting with Data Center version 2.1.0.

We strongly recommend using the latest Data Center app version when performing a migration. This documentation applies to the latest DC version. Migrations executed with earlier DC versions are supported on a best-effort basis and may behave differently from what is described here.

1. Introduction

Before migrating the app data to Jira Cloud, please check out the Feature parity – Cloud vs Data Center comparison.

The Rich Filters for Jira Dashboards app uses two different types of data that need to be migrated:

The configuration of the rich filters;
The configuration of the rich filter gadgets used in dashboards.

It is, of course, possible to migrate the app data manually, by recreating in the target Cloud instance the same configuration as in the source Data Center instance. Consider this approach if you have a few rich filters and rich filter gadgets to migrate, especially if you intend to use the migration as an opportunity to change some of your Jira and/or app configuration. There are no specific instructions for the manual migration of the app data, since it is a straightforward process. The rest of this page concerns the automatic migration of the app data.

Starting with the version 2.1.0 of the app, both the rich filters and the rich filter gadgets can be automatically migrated using the Jira Cloud Migration Assistant (JCMA). More precisely, during a migration run, JCMA first migrates your Jira data (including the saved Jira filters and the dashboards if they are selected in the migration run), and then orchestrates the migration process for the Rich Filters app.

2. Automatic migration of the app data

Migrating your data using JCMA requires detailed planning and several configuration steps. For details, see Use the Jira Cloud Migration Assistant to migrate. Below, we refer only to the configuration steps that are related to the migration of the Rich Filters for Jira Dashboards app data.

Step #1 - Install required software.

On your source Jira Data Center instance, ensure you have installed the following:

Rich Filters for Jira Dashboards version 2.1.0 or above, preferably the latest DC version;
Jira Cloud Migration Assistant (JCMA) latest version.

On your target Jira Cloud instance, ensure you have installed and licensed the Rich Filters for the Jira Dashboards Cloud app.

Step #2 - Assess your apps

The first step in preparing a JCMA migration is Assess your apps on the Migration Assistant home screen—more information is available here. In this step, you must choose which apps to migrate to the Cloud.

You need to mark Rich Filters for Jira Dashboards as Needed in cloud.
If you also use rich filter extension apps, you must mark them all as Not needed in cloud.

On Cloud, the functionality provided by Rich Filters::Service Management Dashboards is available as part of the main Rich Filters for the Jira Dashboards app. Hence, when migrating the main rich filters app, the data provided by this rich filters extension is also migrated. Currently, the functionality provided by Rich Filters::Time Tracking Dashboards is not supported on Cloud.

Migration best practices

JCMA lets you run migrations from the same source Jira Data Center instance to the same target Jira Cloud instance multiple times (for example, in order to migrate your projects gradually, if this is useful to you). Whenever possible, we recommend you migrate your Jira data and your app data only once, that is, in one migration run.

If you need to migrate your Jira data in several migration runs, we recommend you enable the migration of the Rich Filters app only once, in the last migration run or in a separate app-data-only run executed after the last migration run for Jira data. This is because, if the app data migration happens before all Jira data is migrated, any references to Jira objects (such as Jira filters, custom fields or dashboards) that are missing on Cloud will be broken, so your rich filters and/or rich filter gadgets might not be correctly migrated.

In the explanations below, we assume you are following the recommended path described above.

Step #3 - Check permissions

To be able to migrate rich filter gadgets, the app must have the System / Global Permissions / Share dashboards and filters permission on the target Cloud instance. If you need to migrate dashboards with rich filter gadgets, make sure that the group atlassian-addons-admin is granted this permission. (atlassian-addons-admin is a technical group added automatically by Jira to manage permissions for the apps.)

Step #4 - Configure JCMA to migrate filters and dashboards

Rich filters are based on (have a reference to) saved Jira filters. In order for this reference to be preserved during the migration, it is important that all the Jira filters that are referenced in rich filters are already migrated when the rich filters are migrated (see the section Migration best practices above).

JCMA supports Jira dashboard migration. The migration of dashboards with rich filter gadgets happens in two steps. In the first step, JCMA creates the dashboards on the target Cloud instance and migrates the native Jira gadgets (but not third-party gadgets). In the second step, the app migrates the rich filter gadgets on these dashboards. It is therefore important that all dashboards containing rich filter gadgets be created by JCMA before the app data is migrated (see the section Migration best practices above).

Therefore, you should configure JCMA to migrate all Jira filters and all dashboards. To do this, in the JCMA migration configuration step Select dashboards, boards and filters you need to select the options Dashboards/All dashboards and Boards and filters/All filters and cross-project boards. For details, see What gets migrated with the Jira Cloud Migration Assistant and How dashboards, boards, and filters are migrated.

If you don’t migrate all Jira filters and all dashboards but only some of them, then only the corresponding rich filters and rich filter gadgets will be migrated by the app. This behavior is expected:

The app cannot create or configure gadgets on dashboards that are not present in Cloud.
Rich filters whose base Jira filters are not migrated will not be migrated.

For guidance on partial and incremental migrations, see the section 4. Partial and incremental migrations below.

Step #5 - Enable app migration

To enable the migration of the app data, in the JCMA migration configuration step Select apps you need to select the option All - marked as Needed in cloud with a migration path. If you have other apps marked as “Needed in cloud”, make sure you consult the migration documentation of those apps as well.

Step #6 - Start the migration

Once you start the migration, JCMA first migrates your Jira data and then orchestrates the migration process for the Rich Filters app. When the app has finished the migration, your migration details screen will show a status and a progress percentage for the app. If all the rich filters and all the rich filter gadgets are migrated successfully, the status will be COMPLETE and the progress will be 100%.

3. Verification and adjustments

After the JCMA migration, the following steps must be completed on the destination Jira Cloud instance.

Step #1 - Check the base Jira filters

In this step, you need to check that all the migrated rich filters have a base Jira filter.

If any migrated rich filter doesn’t have a base Jira filter (i.e. the base Jira filter is NOT SET), you need to find out whether the corresponding Jira filter has been migrated in the same migration run as the rich filter (or in a previous but recent migration run—see the section Migration best practices above). If these conditions are met, yet the reference is broken, please create a support ticket so that our team can investigate the issue. If these conditions are not met, you will need either a) to identify the cause and fix the problem, and then run the migration again from scratch, or b) to manually create the missing Jira filter and/or set it as a base filter in the migrated rich filter. We remind you that rich filters can only be edited by their administrators (for more details, see Rights and Permissions).

If you wish to obtain a flat list of rich filters together with their base Jira filters on the source Jira Data Center instance, you can run the following SELECT SQL query on Jira's database:

SELECT rf.ID as rich_filter_id, rf.NAME as rich_filter_name, 
	   jf.id as jira_filter_id, jf.filtername as jira_filter_name, 
       jf.authorname as jira_filter_owner, jf.reqcontent as jira_filter_jql
FROM AO_24D977_QRFRFE0 rf INNER JOIN searchrequest jf ON rf.JIRA_FILTER_ID=jf.ID 
ORDER BY jira_filter_id, rich_filter_id;

If your database server is PostgreSQL, then you might need to add double quotes around the upper-case identifiers – see below:

PostgreSQL

SELECT rf."ID" as rich_filter_id, rf."NAME" as rich_filter_name, 
	   jf.id as jira_filter_id, jf.filtername as jira_filter_name, 
       jf.authorname as jira_filter_owner, jf.reqcontent as jira_filter_jql
FROM "AO_24D977_QRFRFE0" rf INNER JOIN searchrequest jf ON rf."JIRA_FILTER_ID"=jf.id
ORDER BY jira_filter_id, rich_filter_id;

The SQL query above will return the list of rich filters (id and name) and the Jira filters they are based on (id and name), the author of those filters, and their JQL.

Step #2 - Check the rich filter gadgets

In this step, you need to check that all the rich filters gadgets have been correctly migrated.

It is expected that Data Center app features that are not supported on Cloud will result in misconfigured gadgets.

For example, gadgets configured with features from the Rich Filters::Time Tracking Dashboards app extension will show an error in the migrated dashboard. The misconfigured gadgets will need to be manually reconfigured or deleted in the Cloud instance.

If you wish to obtain a flat list of dashboards that use rich filter gadgets on the source Jira Data Center instance, you can run the following SELECT SQL query on Jira's database:

SELECT distinct d.id as dashboard_id, d.pagename as dashboard_name, d.username as dashboard_owner_username, 
       p.userprefvalue as rf_id, rf.NAME as rf_name
FROM portalpage d, portletconfiguration g, gadgetuserpreference p, AO_24D977_QRFRFE0 rf
WHERE d.id = g.portalpage
	AND g.id = p.portletconfiguration
	AND p.userprefkey = 'rf'
	AND p.userprefvalue = rf.ID
ORDER BY dashboard_id;

If your database server is PostgreSQL, you might need to add double quotes around the upper-case identifiers and match the types of ID columns – see below:

PostgreSQL

SELECT distinct d.id as dashboard_id, d.pagename as dashboard_name, d.username as dashboard_owner_username,
       p.userprefvalue as rf_id, rf."NAME" as rf_name
FROM portalpage d, portletconfiguration g, gadgetuserpreference p, "AO_24D977_QRFRFE0" rf
WHERE d.id = g.portalpage
    AND g.id = p.portletconfiguration
    AND p.userprefkey = 'rf'
    AND p.userprefvalue = cast(rf."ID" as varchar)
ORDER BY dashboard_id;

The SQL query above will return a list of dashboards that use at least one rich filter gadget. For each dashboard, the query returns the dashboard ID, dashboard name, dashboard owner, and the ID and name of the rich filter used in that dashboard. The same rich filter can be used in multiple dashboards, and each dashboard can use multiple rich filters. There is an n-to-n relationship between dashboards and rich filters.

Step #3 - Check the JQL clauses

Update custom field ID references in JQL

If any of your JQL clauses in the configuration of rich filters or rich filter gadgets refers to a custom field using the cf[id] form, that reference is not automatically updated during the migration. For example, if on your Jira Data Center you used the JQL query cf[...] is not empty, then the reference to the custom field ID is not translated when migrating to the Cloud. The JQL clause is migrated as-is, but the ID of the migrated custom field might be different on Cloud. Hence, if you used any such custom field references in your JQL, you must manually update them on Cloud.

If you wish to obtain a flat list of rich filters (and their sub-objects) that have JQL clauses that reference custom fields by ID, you can run the following SELECT SQL queries on the source Jira Data Center database:

-- static filters:
SELECT 
  rf.ID AS "Rich filter ID",
  rf.NAME AS "Rich filter name",
  sf.ID AS "Static filter ID",
  sf.LABEL AS "Static filter name",
  sf.JQL
FROM AO_24D977_QRFRFE0 rf
JOIN AO_24D977_QRFSTFE0 sf ON rf.ID = sf.RICH_FILTER_ID
WHERE sf.JQL LIKE '%cf[%';

-- smart filters:
SELECT 
  rf.ID AS "Rich filter ID",
  rf.NAME AS "Rich filter name",
  sf.ID AS "Smart filter ID",
  sf.NAME AS "Smart filter name",
  cl.LABEL AS "Clause label",
  cl.JQL
FROM AO_24D977_QRFRFE0 rf
JOIN AO_24D977_QRFSMFE0 sf ON rf.ID = sf.RICH_FILTER_ID
JOIN AO_24D977_QRFSMFCE0 cl ON sf.ID = cl.SMART_FILTER_ID
WHERE cl.JQL LIKE '%cf[%';

-- custom values:
SELECT 
  rf.ID AS "Rich filter ID",
  rf.NAME AS "Rich filter name",
  sf.ID AS "Custom value ID",
  sf.LABEL AS "Custom value name",
  sf.JQL
FROM AO_24D977_QRFRFE0 rf
JOIN AO_24D977_QRFCVE0 sf ON rf.ID = sf.RICH_FILTER_ID
WHERE sf.JQL LIKE '%cf[%';

-- custom ratios:
SELECT 
  rf.ID AS "Rich filter ID",
  rf.NAME AS "Rich filter name",
  sf.ID AS "Custom ration ID",
  sf.LABEL AS "Custom ration name",
  sf.JQL
FROM AO_24D977_QRFRFE0 rf
JOIN AO_24D977_QRFCRE0 sf ON rf.ID = sf.RICH_FILTER_ID
WHERE sf.JQL LIKE '%cf[%';

-- time series:
SELECT 
  rf.ID AS "Rich filter ID",
  rf.NAME AS "Rich filter name",
  sf.ID AS "Time series ID",
  sf.LABEL AS "Time series name",
  sf.JQL
FROM AO_24D977_QRFRFE0 rf
JOIN AO_24D977_QRFTSE0 sf ON rf.ID = sf.RICH_FILTER_ID
WHERE sf.JQL LIKE '%cf[%';

-- queues:
SELECT 
  rf.ID AS "Rich filter ID",
  rf.NAME AS "Rich filter name",
  sf.ID AS "Rich queue ID",
  sf.NAME AS "Rich queue name",
  sf.JQL
FROM AO_24D977_QRFRFE0 rf
JOIN AO_24D977_QRFRQE0 sf ON rf.ID = sf.RICH_FILTER_ID
WHERE sf.JQL LIKE '%cf[%';

If your database server is PostgreSQL, you might need to add double quotes around the upper-case identifiers and match the types of ID columns – see below:

PostgreSQL

-- static filters:
SELECT 
  rf."ID" AS "Rich filter ID",
  rf."NAME" AS "Rich filter name",
  sf."ID" AS "Static filter ID",
  sf."LABEL" AS "Static filter name",
  sf."JQL"
FROM "AO_24D977_QRFRFE0" rf
JOIN "AO_24D977_QRFSTFE0" sf ON rf."ID" = sf."RICH_FILTER_ID"
WHERE sf."JQL" LIKE '%cf[%';

-- smart filters:
SELECT 
  rf."ID" AS "Rich filter ID",
  rf."NAME" AS "Rich filter name",
  sf."ID" AS "Smart filter ID",
  sf."NAME" AS "Smart filter name",
  cl."LABEL" AS "Clause label",
  cl."JQL"
FROM "AO_24D977_QRFRFE0" rf
JOIN "AO_24D977_QRFSMFE0" sf ON rf."ID" = sf."RICH_FILTER_ID"
JOIN "AO_24D977_QRFSMFCE0" cl ON sf."ID" = cl."SMART_FILTER_ID"
WHERE cl."JQL" LIKE '%cf[%';

-- custom values:
SELECT 
  rf."ID" AS "Rich filter ID",
  rf."NAME" AS "Rich filter name",
  sf."ID" AS "Custom value ID",
  sf."LABEL" AS "Custom value name",
  sf."JQL"
FROM "AO_24D977_QRFRFE0" rf
JOIN "AO_24D977_QRFCVE0" sf ON rf."ID" = sf."RICH_FILTER_ID"
WHERE sf."JQL" LIKE '%cf[%';

-- custom ratios:
SELECT 
  rf."ID" AS "Rich filter ID",
  rf."NAME" AS "Rich filter name",
  sf."ID" AS "Custom ration ID",
  sf."LABEL" AS "Custom ration name",
  sf."JQL"
FROM "AO_24D977_QRFRFE0" rf
JOIN "AO_24D977_QRFCRE0" sf ON rf."ID" = sf."RICH_FILTER_ID"
WHERE sf."JQL" LIKE '%cf[%';

-- time series:
SELECT 
  rf."ID" AS "Rich filter ID",
  rf."NAME" AS "Rich filter name",
  sf."ID" AS "Time series ID",
  sf."LABEL" AS "Time series name",
  sf."JQL"
FROM "AO_24D977_QRFRFE0" rf
JOIN "AO_24D977_QRFTSE0" sf ON rf."ID" = sf."RICH_FILTER_ID"
WHERE sf."JQL" LIKE '%cf[%';

-- queues:
SELECT 
  rf.ID AS "Rich filter ID",
  rf.NAME AS "Rich filter name",
  sf.ID AS "Rich queue ID",
  sf.NAME AS "Rich queue name",
  sf.JQL
FROM AO_24D977_QRFRFE0 rf
JOIN AO_24D977_QRFRQE0 sf ON rf.ID = sf.RICH_FILTER_ID
WHERE sf.JQL LIKE '%cf[%'

The SQL queries above will return the list of rich filters (id and name) and their sub-objects (id and name), along with their JQL, when this JQL contains a reference to a custom field using the cf[id] form.

4. Partial and incremental migrations

The app supports partial and incremental migrations. When planning such non-standard migrations, it is critical to pay attention to the coherence of the migration scope.

In a partial migration—when only some projects, filters, and dashboards are migrated—the app migrates only the corresponding rich filters and rich filter gadgets. This behavior is expected:

The app cannot create or configure gadgets on dashboards that are not present in Cloud.
Rich filters whose base Jira filters are not migrated will not be migrated.

However, partial migrations introduce additional considerations for other Jira objects that are referenced by the migrated rich filters and gadgets, including:

Users and groups
Custom fields

4.1 Migration risks

Partial migrations present two levels of risk:

High risk – objects directly referenced in app configuration

Objects that are referenced directly in the app configuration (e.g., a custom field used in a dynamic filter) are critical.
If these objects are not present in Cloud prior to the app migration, the corresponding rich filter or gadget configuration will be broken and require manual repair.
High-risk objects for the app include: users, groups and custom fields.

Medium risk – objects referenced only in JQL clauses

Any Jira object that appears only in JQL queries—whether a status, priority, issue type, custom field, resolution, or issue link type—can cause incorrect runtime behavior if missing in Cloud.
The configuration itself remains valid, but the JQL can return incomplete or incorrect results until the missing objects are migrated.

4.2 Recommendations

To minimize migration risk in partial and incremental scenarios:

Plan your Jira object migration scope carefully
- Ensure that all users, groups, custom fields, and issue link types referenced in the migrated rich filters and gadgets are included in the Cloud migration.
Prioritize high-risk objects
- Objects directly referenced in the app configuration are critical. Missing objects will break the app configuration and should be migrated first.
Consider medium-risk objects
- Any Jira object used in JQL queries should be migrated to prevent runtime inconsistencies, even if they are not directly referenced in app configuration.
Test incrementally
- After migrating a subset of projects, dashboards, and filters, validate the integrity of the app configuration and the runtime behavior of the gadgets before proceeding with additional migrations.

By following these guidelines, you can safely perform partial or incremental migrations while maintaining both the integrity of the app configuration and the correctness of its behavior.

Navigate to Jira Administration ().
Go to Manage apps.
Under RICH FILTERS, select Cloud migration (JCMA).

For Inclusion mode, select how you want to include rich filters in the cloud migration:
- Migrate all rich filters - Migrates all rich filters (default)
- Migrate only the rich filters below - Migrates only the specified rich filter IDs
  - Rich filters to include - Enter a comma-separated list of rich filter IDs (for example, 131, 82) you want to include
- Migrate all rich filters except the ones below - Migrates all rich filters except the specified IDs
  - Rich filters to exclude - Enter a comma-separated list of rich filter IDs (for example, 11, 22) you want to exclude
- Don't migrate any rich filters - Skips rich filter migration entirely
For Inclusion mode, select how you want to include dashboards in the cloud migration:
- Migrate all dashboards - Migrates all dashboards (default for JCMA migrations with mapped dashboards)
- Migrate only the dashboards below - Migrates only the specified dashboard IDs
  - Dashboards to include - Enter a comma-separated list of dashboard IDs you want to include.
- Migrate all dashboards except the ones below - Migrates all dashboards except the specified IDs
  - Dashboards to exclude - Enter a comma-separated list of dashboard IDs you want to exclude
- Don't migrate any dashboards - Skips dashboard migration entirely
Click Submit.