Redmine Issue Query Reference

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[] or f[] key
  • field operator – operators[] or op[] key
  • field value – values[] or v[] 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.

4 comments

  1. Sinharajesh says:

    just curious to know how do you handle custom fields allocated against specific trackers in issues APIs or URLs in the above scenarios.

  2. John says:

    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…

Comments are closed.