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
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
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]
Columns
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)
Filters
Filtering is where things get complex. Redmine requires 3 components for a filter:
- field name –
fields[]
orf[]
key - field operator –
operators[]
orop[]
key - field value –
values[]
orv[]
key
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]
Sortable columns
You can sort by these column names.
- project
- tracker
- parent
- status
- priority
- subject
- assigned_to
- updated_on
- category
- fixed_version
- start_date
- due_date
- estimated_hours
- done_ratio
- created_on
Groupable columns
These columns can be used in the group_by option
- project
- tracker
- status
- priority
- assigned_to
- category
- fixed_version
- done_ratio
Operator Reference
- = – 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.
just curious to know how do you handle custom fields allocated against specific trackers in issues APIs or URLs in the above scenarios.
All custom fields are stored in the database and are named after the custom field id. So “cf_4” would be the Custom Field with the id of 4.
Quick question about the issue list itself…If I wanted to add a Filter for time spent, which is in another table, how would I go about patching Redmine to do this? Adding something to the Filter list isn’t difficult but I can’t seem to locate where to look to modify the SQL that is running on the Issue List page…
Thanks in advance…
Last time I had to do this I had to hack the Redmine internals. For a calculated column like time spent, it’s even harder.