On this page:
- Migrating rich filters
- Migrating rich filter gadgets
Before migrating Rich Filters for Jira Dashboards app data from Jira Server or Data Center to Jira Cloud, please first check the Feature Parity – Server/Data Center vs Cloud comparison documentation page.
The Rich Filters for Jira Dashboards app uses two different types of data that need to be migrated:
- The configuration of the rich filters defined on your Jira instance
- The configuration of the rich filter gadgets used in dashboards on your Jira instance
2. Migrating rich filters
For the migration of the rich filters, you have two possible options:
- migrate your rich filters automatically using the Jira Cloud Migration Assistant (JCMA); the next documentation section describes this migration path in detail;
- migrate your rich filters manually; this means that you need to recreate manually the rich filters from the Server/Data Center instance on your Cloud instance.
2.a. Migrating rich filters configuration automatically using JCMA
The Jira Cloud Migration Assistant (JCMA) allows you to automate the migration of your rich filters from Jira Server/Data Center to Jira Cloud. More precisely, JCMA migrates your Jira data and orchestrates the migration process for 3rd party apps which have added specific support for JCMA.
Migrating your data from Jira Server/Data Center to Jira Cloud using JCMA requires detailed planning and a number of configuration steps – for more details see Use the Jira Cloud Migration Assistant to migrate. Below, we refer only to the configuration steps that are relevant for the migration of the rich filters.
I) Before launching the JCMA migration
Step #1 - Make sure you have the appropriate software installed on you Jira instances
On your source Jira Server/Data Center instance, make sure you have installed:
- Rich Filters for Jira Dashboards version 1.23.0 or above
- Jira Cloud Migration Assistant (JCMA) latest version
On your destination Jira Cloud instance, make sure you have installed and licensed the Rich Filters for Jira Dashboards Cloud app.
Step #2 - Assess your apps
The first step in configuring JCMA before launching a migration is "1. ASSESS YOUR APPS" on the Migration Assistant home screen – more information available here. As part of this step, you need to chose which apps you wish to migrate to Cloud.
- You need to mark Rich Filters for Jira Dashboards as Needed in cloud. Note that all the rich filters will be migrated.
- If you also use any rich filters extensions apps, then you must mark all of them as Not needed in cloud.
On Cloud, the functionality provided by Rich Filters::Service Management Dashboards is available as part of the make Rich Filters for Jira Dashboards app. Hence, when migrating the main rich filters app, the data provided by the rich filters extension is also migrated.
II) After completing the JCMA migration
The following steps need to be completed on the destination Jira Cloud instance, after the JCMA migration is finished.
Step #3 - Check and migrate the saved base Jira filters
Rich filters are based on saved Jira filters. Unfortunately, as of version 1.16.8 (the last version we have tested), JCMA migrates only those Jira filters which are associated with boards that are migrated (see the What gets migrated with the Jira Cloud Migration Assistant documentation page).
If your rich filters are based on saved Jira filters which are not migrated by JCMA, then your rich filters will be migrated but their Jira filters will not be set (because the saved Jira filters don't exist on the destination Jira Cloud instance). As part of the post-migration steps, you will have to manually migrate the relevant Jira filters and set them manually in the rich filters.
As far as we know, Atlassian currently works on enhancing JCMA so that all saved Jira Filters are migrated. Please watch and vote for MIG-269 – Add support to migrate global filters.
Meanwhile, 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 (so that you can migrate manually the base Jira filters), then you can run the following SELECT SQL query on Jira's database:
The SQL query above will return the list of rich filters (id and name) together with the Jira filters they are based on (id and name), the author of those filters, and their JQL.
The rich filters migrated on the Cloud instance for which the base Jira filters were not migrated will display their Jira filters as NOT SET. You'll need to go through the list of migrated rich filters and for each rich filter, if its base Jira filter was not already migrated as part of the JCMA migration, to manually create the corresponding Jira filter and set it as base filter in the configuration of the rich filter. We remind you that only administrators can edit rich filters (for more details, see the Rights and Permissions documentation page).
Step #4 - Review and update JQL clauses in the configuration of your rich filters
Update user references in JQL
On Cloud, Atlassian has removed the userkey and username from JQL (it is no longer possible to identify a user based on their username or userkey). On Cloud instances, when writing JQL, users should be identified using account ids instead.
On Server/Data Center, JQL clauses filtering on user fields (eg: reporter, assignee, custom user fields) can use userkey, username, user's name and/or user's email address to identify a user. JQL clauses used in the configuration of your rich filters (static filters, smart filters, etc.) are migrated as-is from Server/Data Center to Cloud. As a consequence, the same JQL clause that was working fine on Jira Server/Data Center, might not work anymore on Jira Cloud.
You should review all the JQL clauses used in the configuration of your rich filters and replace any reference to a user with the user's account id. For example, any JQL clause such as
assignee = jdoe,
assignee = "John Doe", or
assignee = "email@example.com" needs to be updated to use the account id on Cloud:
assignee = 611298aeeb7aef00694d7520.
Update custom field id references in JQL
Moreover, if in any of your JQL clauses were referring to a custom field using its
cf[id] form, that reference is not automatically updated either. 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 on Cloud. The JQL clause is migrated as-is but the id of the migrated custom field 10100 might be different on Cloud. Hence, if you used any such custom field references in your JQL, you will have to 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.
Migration best practice
JCMA allows you to run migrations from the same Jira Server/DC instance to the same Jira Cloud instance multiple times (for instance, to migrate your projects gradually if this is useful to you). We recommend you migrate your Rich Filters for Jira Dashboards app data only one time after you have migrated all your Jira data. If you migrate your rich filters data before you have migrated all your Jira data, then references to missing Jira data will not be migrated and your rich filters might not be completely migrated.
If you migrate the rich filters data multiple times, the rich filters that are already migrated will not be migrated a second time. Nevertheless, if you migrate a rich filter to Cloud and if then you delete that rich filter, if you migrate the rich filters again, then the deleted rich filters will be migrated again. We don't recommend migrating rich filters multiple times unless it's absolutely necessary.
2.b. Migrating rich filters configuration manually
Alternatively, instead of using JCMA, you also have the option to migrate your rich filters manually – i.e. recreate the same rich filters configurations on your Cloud instance. One advantage that this approach brings is that you can decide to not migrate rich filters which are not used anymore.
The SELECT SQL query provided in the Step #3 above can be useful in order to obtain a flat list of rich filters on your Jira Server/Data Center instance.
3. Migrating rich filter gadgets
Unfortunately, Atlassian does not currently provide support for the automatic migration of 3rd party gadgets from Jira Server/Data Center to Jira Cloud. It is for this reason that at least for now, the migration of your dashboards and rich filter gadgets can be done only manually. You need to recreate the same dashboards as on the Jira Server/Data Center instance, using the rich filters already migrated as described above.
We hope Atlassian will soon provide the necessary technical framework so that we can automatically migrate the dashboards/rich filter gadgets too. Please watch and vote for MIG-164 – Support Migration of Dashboards.
Meanwhile, if you wish to obtain a flat list of dashboards which use rich filters gadgets on the source Jira Server/Data Center instance, then you can run the following SELECT SQL query on Jira's database:
The SQL query above will return the list of dashboard which use at least one rich filter gadget. For each dashboard, the query returns the dashboard id, dashboard name, dashboard owner, 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.