Saved Filters - Best practice for preventing broken queries
Platform Notice: Cloud Only - This article only applies to Atlassian products on the cloud platform.
Problem
Existing Saved Filters can include JQL that becomes broken by external behaviour. Most often this will involve the JQL referring to a resource (e.g. Project, User or Custom Field, etc.) by name. Then if the resource's name is changed the JQL breaks. When viewing the Saved Filter that refers to the old name you may see a warning that says "The value 'Old Project Name CM JSW' does not exist for the field 'project'.":
Prevention
Your JQL queries will be less brittle and therefore less likely to break if you refer to a resource's ID rather than name. The following instructions show how to do so for some commonly used resources.
Projects
To find all your projects' IDs, go to https://<your site name>.atlassian.net/rest/api/3/project/search
There you will find a JSON object that contains all the projects from your site. Here is an example of a single Project object:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"expand": "description,lead,issueTypes,url,projectKeys,permissions,insight",
"self": "https://arutnam.atlassian.net/rest/api/3/project/10048",
"id": "10048",
"key": "TFWV",
"name": "Test for Workflow Validation",
"avatarUrls": {
"48x48": "https://arutnam.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10409",
"24x24": "https://arutnam.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10409?size=small",
"16x16": "https://arutnam.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10409?size=xsmall",
"32x32": "https://arutnam.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10409?size=medium"
},
"projectTypeKey": "software",
"simplified": false,
"style": "classic",
"isPrivate": false,
"properties": {}
}In your JQL you should refer to the ID rather than the name i.e. project = 10048
Users
To find a user's account ID go to https://<your site name>.atlassian.net/rest/api/3/user/search?query=<the user's email address>
Here is an example of a user object that would be returned:
1
2
3
4
5
6
7
8
9
10
11
{
"self": "https://arutnam.atlassian.net/rest/api/3/user?accountId=6220b40949c90000701fb7c1",
"accountId": "6220b40949c90000701fb7c1",
"accountType": "atlassian",
"emailAddress": "",
"avatarUrls": {
"48x48": "https://secure.gravatar.com/avatar/7d497631af97a6e026f00a5c6f0429e8?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FA-0.png",
"24x24": "https://secure.gravatar.com/avatar/7d497631af97a6e026f00a5c6f0429e8?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FA-0.png",
"16x16": "https://secure.gravatar.com/avatar/7d497631af97a6e026f00a5c6f0429e8?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FA-0.png",
"32x32": "https://secure.gravatar.com/avatar/7d497631af97a6e026f00a5c6f0429e8?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FA-0.png"
}In your JQL you should refer to the accountId's value rather than the user's name or email address i.e. assignee = 6220b40949c90000701fb7c1
Custom Fields
To find your site's custom field IDs go to https://<your site name>.atlassian.net/rest/api/3/field
Here is an example of a custom field object that would be returned:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"id": "customfield_10098",
"key": "customfield_10098",
"name": "Hooray name changed",
"untranslatedName": "Hooray name changed",
"custom": true,
"orderable": true,
"navigable": true,
"searchable": true,
"clauseNames": ["cf[10098]", "Hooray name changed", "Hooray name changed[Dropdown]"],
"schema": {
"type": "option",
"custom": "com.atlassian.jira.plugin.system.customfieldtypes:select",
"customId": 10098
}In your JQL you should refer to the customId's value rather than the custom field's name. You also need to add some text around that customId like so: "cf[<customId here>]". So the end JQL query would look like this: cf[10098] is not empty
Identifying existing saved filters that reference names rather than IDs
To return all your saved filters go to https://<your site name>.atlassian.net/rest/api/3/filter/search?expand=jql
Here is an example of two saved filter objects that would be returned:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"expand": "description,owner,jql,viewUrl,searchUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,subscriptions",
"self": "https://arutnam.atlassian.net/rest/api/3/filter/10045",
"id": "10045",
"name": "Filter for JSFSS board",
"jql": "project = JSFSS ORDER BY Rank ASC"
}, {
"expand": "description,owner,jql,viewUrl,searchUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,subscriptions",
"self": "https://arutnam.atlassian.net/rest/api/3/filter/10042",
"id": "10042",
"name": "Filter for JSW board",
"jql": "project = 10046 ORDER BY Rank ASC"
},
{
"expand": "description,owner,jql,viewUrl,searchUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,subscriptions",
"self": "https://arutnam.atlassian.net/rest/api/3/filter/10063",
"id": "10063",
"name": "Filter with custom field in JQL that is deleted",
"jql": "cf[10030] is not EMPTY"
}There is no single foolproof way to identify which JQL queries refer to an ID, but you can run some regex to identify those Saved Filters where the JQL doesn't contain a numeral. In those cases you can be assured that the filter is not referring to the resources ID.
Relevant feature requests
Was this helpful?