Be you a beginner in JIRA or a professional, one of the features used often is creating and managing filters. The fact that we can save the searches, share them, and subscribe to them adds a lot of value to JIRA. So, how do we programmatically create and manage filters?
In this recipe, we will learn how to manage filters programmatically.
We will see the various aspects of managing the filters one-by-one.
Most of the operations on managing filters are done using SearchRequestService. For creating a filter, the following are the steps:
- Create the query to be saved as a filter. The query can be created using
JqlQueryBuilder, as we have seen in the previous recipes. - Create a
SearchRequestobject from the query, using the appropriate name, description, and so on:SearchRequest searchRequest = new SearchRequest(query, loggedInUser, "Test Filter", "Test Description"); - Create a JIRA Service Context. If you are in an action class, you can get the service context by calling
getJiraServiceContext()and if not, an instance can be created as follows:JiraServiceContext ctx = new JiraServiceContextImpl(user);
Here,
useris the user for whom the filter should be created. - Get an instance of
SearchRequestService. It can be either injected in the constructor or as follows:SearchRequestService searchRequestService = ComponentAccessor.getComponent(SearchRequestService.class); - Create the filter:
final SearchRequest newSearchRequest = searchRequestService.createFilter(ctx, searchRequest, favorite);Here,
favoriteis a Boolean, which can be set to true if you want the filter to be made a favorite.
Updating a filter is very similar to creating a filter. Here we have to retrieve the SearchRequest using its ID and then update the attributes such as name, description, and so on, using the setter methods.
Once the SearchRequest is modified, we can use SearchRequestService to update the filter:
SearchRequest updatedFilter = searchRequestService.updateFilter(ctx, newSearchRequest, favorite);
JIRA takes the filter ID as the input for deleting a filter. Before we actually delete the filter, we need to validate the deletion as follows:
searchRequestService.validateForDelete(ctx, filterId);
If there are any errors, it will be added into the action's error collection. We can then check for the errors, and delete the filter if there are no errors:
if(!ctx.getErrorCollection().hasAnyErrors()))
{
searchRequestService.deleteFilter(ctx, filterId);
}We can also delete all the filters of a user by using the following:
deleteAllFiltersForUser(JiraServiceContextserviceCtx, ApplicationUser user);
The SearchRequestService also has a few methods to retrieve favorite filters, filters owned by a user, non-private filters, and so on. Key methods are listed as follows:
Collection<SearchRequest> getFavouriteFilters(ApplicationUser user); Collection<SearchRequest> getOwnedFilters(ApplicationUser user); Collection<SearchRequest> getNonPrivateFilters(ApplicationUser user); Collection<SearchRequest> getFiltersFavouritedByOthers(ApplicationUser user);
The method names are self-explanatory.
In order to share a filter, we need to retrieve the relevant filter and set the permissions on it using the following:
searchRequest.setPermissions(permissions);
Here, permissions is a set of SharePermission objects. The SharePermission objects can be created from a JSONArray using the SharePermissionUtils utility class. The JSONObject can have three keys - Type, Param1, and Param2.
The Type can have the following values: global, group, or project:
- When
Typeisglobal,Param1andParam2are not required - When it is
group,Param1is populated with thegroupname - When it is
project,Param1is the ID of the project andParam2is the ID of the project role
An example of JSON arrays is as follows:
[{"type":"global"}]
[{"type":"group","param1":"jira-administrators"},{"type":"project","param1":"10000","param2":"10010"}]If you want to share a filter with everyone, permissions can be set as follows:
newSearchRequest.setPermissions(SharePermissionUtils.fromJsonArrayString("[{"type":"global"}]"));