I’ve been writing a bit about using Redmine’s issue filters to create and save a query recently and noticed that there is very little documentation on how it works. This post attempts to document how to pass parameters to Redmine’s issues list using the url. All of these options can be used directly in a web browser or also as part of the REST API.
[box type=”note” style=”rounded” border=”full”]All of the urls should be url-encoded.[/box]
Required: Enable the url filtering
The first thing you need to do is to add
set_filter=1. This tells Redmine to run the filters from the url. If you don’t set this, Redmine will use your last query that is stored in your session.
[box type="download" style="rounded" border="full"]/issues?set_filter=1[/box]
Sorting is done using the
sort key which takes a comma separated list of fields and a direction. So to sort by the assigned user and then subject you would add:
[box type="download" style="rounded" border="full"]/issues?set_filter=1&sort=assigned_to,subject:asc[/box]
A list of all of the sortable columns are below.
Grouping the issues uses the
group_by key and the name of the field, like priority.
[box type="download" style="rounded" border="full"]/issues?set_filter=1&group_by=priority[/box]
A list of all of the columns for grouping are below.
Results per page
The number of results per page is controlled by the
per_page option. You have to use a value that has been configured in the Administration panel (Admin > Settings > General > “Objects per page options”).
[box type="download" style="rounded" border="full"]/issues?set_filter=1&per_page=100[/box]
Controlling the columns is done using the
c key (shorthand for “column names”). There can be multiple values used. So if you only want to show the id, status, and subject columns you would use this:
[box type="download" style="rounded" border="full"]/issues?set_filter=1&c=status&c=subject[/box]
(The id and bulk editing columns are always shown)
Filtering is where things get complex. Redmine requires 3 components for a filter:
- field name –
- field operator –
- field value –
So to show issues with the status id equal 2 you would need to set:
- field name – statusid (note that this uses statusid instead of just status)
- field operator – ‘=’ for equal
- field value – 2
Which would become:
[box type="download" style="rounded" border="full"]/issues?set_filter=1&f=status_id&v[status_id]=2&op[status_id]==[/box]
You can sort by these column names.
These columns can be used in the group_by option
- = – equal
- ! – not equal
- * – all
- !* – none
- >= – greater than or equal
- <= – less than or equal
- ~ – contains
- !~ – does not contain
- t – today
- w – this week
- t+ – in (used with dates, e.g. in exactly 5 days)
- t- – ago
- >t+ – in more than (used with dates, e.g. in more than 5 days)
- >t- – in more than ago (used with dates, e.g. in more than 5 days ago)
- o – open (only used on status)
- c – closed (only used on status)
This should give you enough information to start crafting custom queries for your issues list. Some ideas for this are create urls and embed them into reports or even to bookmark.