Migrate from Rich Filters Server/Data Center to Cloud

The automatic migration of rich filter gadgets with JCMA is supported by Rich Filters for the Jira Dashboards starting with version 2.1.0. We recommend you use the latest Data Center app version to perform your migration.

Contents:

1 1. Introduction
2 2. Automatic migration of the app data
3 3. Verification and adjustments

1. Introduction

Before migrating the app data from Jira Server or Data Center to Jira Cloud, please check out the Feature parity – Cloud vs Server/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 Server/Data Center instance. Consider this approach if you have 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 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 Server/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 - Prepare your dashboards for the migration

This preparatory step is necessary to prevent some rich filter dashboards from failing to migrate due to insufficient permissions.

Currently, Atlassian doesn’t provide specific support for the migration of third-party gadgets with JCMA (see MIG-1937). The Rich Filters app uses the existing Jira Cloud APIs to implement the rich filter gadget migration. One of these APIs has a bug that, for particular dashboard share configurations, makes it impossible for the app to give itself the permission to edit the Cloud dashboards (see JRACLOUD-84000), resulting in dashboards that fail to migrate.

The proper solution for this issue is for Atlassian to fix JRACLOUD-84000. We encourage you to do whatever you can to increase the chances of this happening (comment and vote on the issue, contact Atlassian directly etc.).

Until Atlassian fixes this bug (or provides specific support for the migration of third-party gadgets), you need to implement the following workaround in the source Jira Server/Data Center instance:

Identify the rich filter dashboards that are shared with at least one project with an explicit project role selected (in Edit and Share Dashboard / Viewers or Editors) => For these dashboards you need to remove all the project role shares (from both Viewers and Editors). If you wish, you can also share these dashboards with logged-in users (Viewers).
Identify the rich filter dashboards that are shared with at least one group (in Edit and Share Dashboard / Viewers or Editors, including among those treated in step 1 above) and are not shared with logged-in users => You need to share these dashboards with logged-in users (Viewers).

These steps will allow the Rich Filters app to work around the Jira API bug and give itself the permission to edit the Cloud dashboards during the migration. After the dashboard migration is completed and verified, you can restore the appropriate permissions of the Cloud dashboards.

Step #3 - 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 allows you to run migrations from the same source Jira Server/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). We recommend you migrate your Jira data and your app data only once, i.e. in one migration run. If you need to migrate your Jira data in several migration runs, you must enable the migration of the Rich Filters app only once, in the last migration run. 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 not be migrated, 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 #4 - Configure JCMA to migrate all 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 be already migrated when the rich filters are migrated (see the section Migration best practices above).

The latest versions of JCMA provide support for 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 the dashboards that contain rich filter gadgets be already created by JCMA when 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.

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 Server/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.

Reminder: The preparatory step Step #2 - Prepare your dashboards for the migration is necessary to prevent some rich filter dashboards from failing to migrate due to insufficient permissions.

It is expected that Server/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 Server/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 Server/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.

We have asked Atlassian to help us automate this step. Please watch and vote for MIG-1021 – Provide API to convert all JQL from Server to Cloud.