Saved filters and subscriptions
A saved filter is a named JQL query. Boards, plans, dashboards and searches use filters as their scope, so a good filter is reused many times. A filter subscription mails you the result on a schedule. This page is for members who keep filters and for project administrators who share them.
Create a saved filter
Section titled “Create a saved filter”-
Write the query on the search page. The JQL must compile. An empty query is valid and means all work you may read.
-
Save it with a name and an optional description.
-
Choose who can use it: only you (the default), the members of a project, or everyone on the site.
A filter shows each person only the work that person may read. Sharing a filter never shares work.
Work with filters
Section titled “Work with filters”| Action | Who can do it |
|---|---|
| Open and use | Anyone who can read the filter. A filter you may not read answers 403. |
| Copy | Any reader. The copy is private and yours. |
| Star | Any reader. Stars are personal, and nobody sees who starred a filter. |
| Rename, change the query or sharing, delete | The owner or a site administrator. A project administrator can also manage a project filter that has no owner. |
| Transfer to a new owner | An administrator, to an active account that can see the filter |
Stars keep a filter in your quick lists, together with your starred projects. Filter links also open directly, for example /filters/<id>.
Subscribe to a filter
Section titled “Subscribe to a filter”A subscription e-mails you the work a filter finds. You choose the schedule:
- Frequency. Daily, on weekdays, weekly on a day you pick, or monthly on a day from 1 to 28.
- Hour and time zone. The hour from 0 to 23, in an IANA time zone. The default is your profile’s time zone.
- Empty results. Off by default, so an empty result sends nothing. You can switch it on.
- Recipient. You, or a group you belong to. Only site administrators can subscribe other people, or groups they are not in.
You can subscribe to a filter you can read. A filter holds up to 50 subscriptions, and each person up to 100. Going over answers 409 quota_exceeded.
Each recipient sees only their own work
Section titled “Each recipient sees only their own work”When a subscription is due, Orbit runs the filter’s query as each recipient, with their own visibility, time zone and custom fields. For a group it runs once for each active member, up to 500 people. Two people can receive different lists from the same filter.
Orbit records one result for each person:
| Result | Meaning |
|---|---|
| Mailed | An e-mail went to the delivery log, with up to 50 work items, the total and a link to the search |
| Empty | Nothing matched and empty results are off |
| No access | The person may no longer read the filter |
| Mail off | The person turned work e-mail off |
| No address | The person has no e-mail address |
| Query failed | The query could not run |
Before every send or retry, Orbit checks that the subscription, the recipient, the filter and the person’s access are still valid. It then runs the query again and rebuilds the subject, count and body from the work the person can read now. A removed subscription or lost access cancels queued mail, and a failed query retries without sending stale text.
Subscription mail goes through the same delivery log as other work mail. See Notifications and e-mail.
Run now and read the history
Section titled “Run now and read the history”The owner of a subscription, the owner of the filter or a site administrator can run a subscription at once. This does not move the next scheduled run. Running again within a minute answers 429 subscription_ran_recently. The history shows the latest 50 runs. A recipient sees only their own rows.
Creating and removing subscriptions is audited. Deleting a filter removes its subscriptions and their history.