We have seen various methods of managing filters. While filters are a great way to save searches and access them quickly at a later point in time, filter subscriptions are even better! The subscriptions help us to see the issues of interest at regular intervals, without even logging in to JIRA.
How do we subscribe to a filter programmatically? In this recipe, we will focus on subscribing to a filter in our plugins.
For the subscription of filters, JIRA provides a manager class implementing the FilterSubscriptionService interface. This class provides the important methods needed for managing filter subscriptions.
There are three important parameters for filter subscriptions:
- Cron Expression: This is the most important part of a subscription. It tells us when the subscription has to run, or in other words, it defines the schedule of a subscription. Cron expressions consist of the following fields, separated by spaces:
Field
Allowed Values
Allowed Special Characters
Second
0-59
, - * /
Minute
0-59
, - * /
Hour
0-23
, - * /
Day-of-Month
1-31
, - * / ? L W C
Month
1-12 Or JAN-DEC
, - * /
Day-of-week
1-7 Or SUN-SAT
, - * / ? L C #
Year (Optional)
1970-2099
, - * /
The special characters denote the following:
Special Character
Usage
,
List of values. For example, "MON,WED,FRI" means "every Monday, Wednesday, and Friday".
-
Range of Values. For example, "MON-WED" means "every Monday, Tuesday, Wednesday".
*
All possible values. For example, * in the
Hourfield means "every hour of the day"./
Increments to the give value. For example, 1/3 in
Hourfield means "every three hours during the day, starting from 1.00 AM".?
No particular value. This is useful when you need to specify a value for only one of the two fields,
Day-of-monthorDay-of-week, but not the other.L
Last possible value. It has different meanings based on the context. For example:
- L in
Day-of-weekmeans "Last day of every week" - 7L means "last Saturday of the month"
- L in
Day-of-monthmeans "last day of the month" - LW means "last weekday of the month"
W
Weekday (MON-FRI) nearest to the given day of the month.
For example, 1W means "nearest working day to the 1st of the month" - useful when you want to get the first working day of the month!
It cannot be used with a range of days.
#
N'th occurance of a given day of the week.
For example, MON#3 means "3rd Monday of the month".
We need to create a valid Cron expression based on the subscription we want to set up. The following are some examples based on these rules:
0 7 30 * * ?- 7:30 AM Every Day0 0/15 15 * * ?- Every 15 minutes starting at 3.00PM and ending at 3:59 PM
You can find more examples in the Atlassian documentation for filter subscriptions at http://confluence.atlassian.com/display/JIRA/Receiving+Search+Results+via+Email.
- L in
- Group Name: This is the group that we want to subscribe the filter. If the value is null, it will be considered as a personal subscription and the user in the context will be used.
- Email On Empty: It is a Boolean value, which is true if you want the subscription to send an e-mail, even when it has no results.
Now let us see the steps to subscribe to a known filter:
- Get an instance of the
FilterSubscriptionService. You can either inject the class in the constructor, or get it using theComponentAccessorclass, as follows:FilterSubscriptionService filterSubscriptionService = ComponentAccessor.getComponent(FilterSubscriptionService.class); - Define the Cron expression based on the aforementioned rules:
String cronExpression = "0 0/15 * * * ? *"; // Denotes every 15 minutes - Define the group name. Use
nullif it is a personal subscription:String groupName = "jira-administrators";
- 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 is subscribed, in case it is a personal subscription. - Define whether an e-mail should be sent or not, even when the number of results is zero:
boolean mailOnEmpty = true;
- Validate the Cron expression:
filterSubscriptionService.validateCronExpression (ctx, cronExpression);If there are any errors, the Error Collection in
JiraServiceContextwill be populated with an error message. - If there are no errors, use the
FilterSubscriptionServiceclass to store the subscription:if (!ctx.getErrorCollection().hasAnyErrors()){ filterSubscriptionService.storeSubscription(ctx, filterId, groupName, cronExpression, emailOnEmpty); }Here,
filterIdis the ID of the filter we want to subscribe to, and can be obtained assearchRequest.getId().
The subscription should now be saved and the mails will be sent based on the schedule defined by the Cron expression.
We can also update an existing subscription using FilterSubscriptionService, using the following method:
filterSubscriptionService.updateSubscription(ctx, subId, groupName, cronExpression, emailOnEmpty);
Here, subId is the existing subscription ID.
Each subscription we create is stored as a scheduled job in the system, which run based on the Cron expression we have defined while storing the subscription.
If you want to use a web form like the one used in JIRA to create filter subscriptions, and you don't want to write the Cron expression, you can create a CronEditorBean using the parameters from the web form.
Note
The various attributes supported in the form can be found from the CronEditorBean class. The Java Docs can be found at http://docs.atlassian.com/software/jira/docs/api/latest/com/atlassian/jira/web/component/cron/CronEditorBean.html .
Once the CronEditorBean is created, it can be parsed into a Cron expression, as follows:
String cronExpression = new CronExpressionGenerator().getCronExpressionFromInput(cronEditorBean);