Reporter template syntax

This article addresses the specifics of a Reporter template.

For a general introduction to Liquid, refer to this article.

_Templates are edited in the template editor with live preview. To draw charts, see Charts in reports

Single vs Multiple issue report templates

While preparing a template, the only object you can directly access is either
  • issue (single issue template) or
  • issues (the array of issues included in the report when preparing a multi-issue template).

When preparing a multi-issue template, you can iterate through every issue in the list with:

{% for issue in issues %}
...
(Access contents of each issue)
...
{% endfor %}

Variables of a template

Template type Objects you can use
Single issue issue
List of issues issues
Time entries time_entries and issues
All types user (the current user), now (current time), today (current date) and template (the template itself, see custom fields of a template)

Objects and attributes

The syntax to read an attribute of an object is {{ object.attribute }}. Attributes that hold another object let you go further, for example {{ issue.project.users.size }}. An attribute that has no value prints nothing.

The types are String, Number, Boolean, Date, Time, Array and Hash, or the name of another object below.

issue

An issue. In a single issue template it is available as issue; in a list template take it from issues (see above).

Attribute Type Description
id Number Issue number
subject String Subject
description String Description, the raw text
link String HTML link to the issue with the subject as text
url String Path to the issue, without the host, for example /issues/42
tracker String Name of the tracker
status String Name of the status
priority String Name of the priority
category String Name of the category
version String Name of the target version
author user Who created the issue
assignee user The assignee
project project The project of the issue
project_name String Name of the project
parent issue The parent issue, empty for a top-level issue
subtasks issues Subtasks
start_date Date Start date
due_date Date Due date
created_on Time Creation time in the time zone of the current user
updated_on Time Last update time in the time zone of the current user
closed_on Time Closing time
done_ratio Number Percent done
estimated_hours Number Estimated time in hours
total_estimated_hours Number Estimated time with subtasks
spent_hours Number Spent time in hours
total_spent_hours Number Spent time with subtasks
closed? Boolean The issue is closed
overdue? Boolean The due date has passed
is_private? Boolean The issue is private
visible? Boolean The issue is visible to the current user
time_entries time_entries Time entries of the issue
journals journals Only the history entries that have a note
notes Array of String Texts of the notes, oldest first
attachments Array of attachment Attached files
images images Image attachments of the issue, for printing pictures
watchers users Watchers
relations_from relations Relations that start in this issue; only the visible issues
relations_to relations Relations that end in this issue; only the visible issues
time_in_status Array of Hash How long the issue stayed in each status: from_date, to_date, status, duration in minutes and author
total_time_in_status Hash Minutes per status name
total_spent_time_by_date Hash Spent hours per date, with subtasks
available_statuses Hash Status names by id
tags Array of String Tags (needs the Tags plugin)
story_points Number Story points (needs the Agile plugin)
color String Card color (needs the Agile plugin)
day_in_state Number Days in the current status (needs the Agile plugin)
checklists Array of Hash Checklist items, see below (needs the Checklists plugin)
helpdesk_ticket Object The helpdesk ticket of the issue (needs the Helpdesk plugin)

issues

A list of issues: the whole list of a list template, the subtasks of an issue or the issues of a project.

Attribute Type Description
all Array of issue All issues of the list
visible Array of issue Only the issues the current user may view
size Number Number of issues
spent_time_by_date Hash Spent hours per date for all issues of the list, for charts
issues[42] issue The issue with the id 42

time_entries

A list of time entries.

Attribute Type Description
all Array of time_entry All time entries
visible Array of time_entry Only the entries the current user may view
size Number Number of entries

time_entry

A time entry.

Attribute Type Description
id Number Id
hours Number Hours
comments String Comment
spent_on Date The date the time was spent on
tyear Number Year of the date
tmonth Number Month of the date
tweek Number Week of the date
activity String Name of the activity
user user Who spent the time
issue issue The issue
created_on Time Creation time
updated_on Time Last update time
visible? Boolean The entry is visible to the current user

journals

A list of the history entries of an issue.

Attribute Type Description
all Array of journal All entries
visible Array of journal Only the entries the current user may view
size Number Number of entries

journal

One entry of the issue history.

Attribute Type Description
id Number Id
notes String Text of the note, empty for an entry that only changes fields
created_on Time Time of the entry
private_notes Boolean The note is private
user user Who made the entry
issue issue The issue
attachments Array of attachment Files attached with the entry

project

A project.

Attribute Type Description
id Number Id
identifier String Identifier
name String Name
description String Description
short_description String Short description
link String HTML link to the project
url String Path to the project
is_public Boolean The project is public
active? Boolean The project is active
archived? Boolean The project is archived
visible? Boolean Visible to the current user
overdue? Boolean The due date has passed
start_date Date Start date
due_date Date Due date
completed_percent Number Percent of completion
issues issues Issues of the project
users users Users involved in the project
subprojects projects Subprojects

projects

A list of projects.

Attribute Type Description
all Array of project All projects
active Array of project Active projects
size Number Number of projects
projects[identifier] project The project with this identifier

user

A user. user is also the current user in every template.

Attribute Type Description
id Number Id
name String Name as shown in Redmine
firstname String First name
lastname String Last name
mail String E-mail address
language String Language code
active? Boolean The user is active
admin? Boolean The user is an administrator
logged? Boolean The user is signed in
avatar String HTML of the avatar
permissions Array of String Permissions the user has through the memberships
groups Array of String Names of the groups
projects projects Visible projects the user is a member of

users

A list of users.

Attribute Type Description
all Array of user All users of the list
current user The current user
size Number Number of users
users[login] user The user with this login

attachment

An attached file.

Attribute Type Description
id Number Id
filename String File name
title String Title
description String Description
filesize Number Size in bytes
content_type String MIME type
digest String Checksum of the file
downloads Number Number of downloads
created_on Time Upload time
author user Who uploaded the file
url String Path to download the file
link String HTML link to the file
image? Boolean The file is an image
thumbnailable? Boolean A thumbnail can be made
is_text? Boolean The file is a text file
visible? Boolean Visible to the current user
read String Content of a text file
to_base64_string String Content encoded in Base64, for embedding

images

The image attachments of an issue.

Attribute Type Description
all Array of image All images
size Number Number of images
images[42] image The image with the id 42

image

An image attachment.

Attribute Type Description
id Number Id
filename String File name
filesize Number Size in bytes
description String Description
created_on Time Upload time
author user Who uploaded the image
url String Public path of the image
full_url String Public address of the image with the host
link String HTML link to the image
asset_base64 String Image encoded in Base64, for embedding in a PDF

relations

Relations of an issue.

Attribute Type Description
all Array of relation All relations
size Number Number of relations

relation

One relation between two issues.

Attribute Type Description
relation_type String Type, for example relates or blocks
delay Number Delay in days for follows and precedes
issue_from issue The issue where the relation starts
issue_to issue The issue where the relation ends

Checklist item

An item of issue.checklists (needs the Checklists plugin).

Attribute Type Description
id_done Boolean The item is checked
subject String Text of the item
is_section Boolean The item is a section heading

FAQ: "How to get days?" Use time_entry.spent_on.

Examples

  • With {{issue.project.users}} you reference the array of all users involved in the project this issue belongs to.
  • To print a list of all issue notes you can use
    {% for journal in issue.journals.all %}
        {% if journal.notes != ''  %}
            <em>{{journal.created_on | date: "%a, %b %d, %y"}} - {{journal.user.name}}</em> {{journal.notes | textilize }}
        {% endif %}   
    {% endfor %}
    ... producing the following output:
    Sun, Dec 09, 18 - User One
    (Comment of User One...)
    Mon, Dec 10, 18 - User Two
    (Comment of User Two...)
    ...
    
    The {% if journal.notes != '' %} check is necessary to select only entries that actually represent a comment and to ignore entries that contain only changes to some issue field.
  • With {{issue.total_spent_hours | round: 2 }} you will display the total spent hours rounded to 2 decimal places.
  • With http://your.redmine.com{{issue.url}} you can print an URL to the issue.

Custom fields

To access the content of a custom field, use
{{issue | custom_field: "custom_field_name"}}.

You can also iterate through all custom fields with
{% assign custom_fields = issue | custom_fields%}
{% for field in custom_fields %}
<p><b>{{field}}:</b> {{issue | custom_field: field}}</p>
{% endfor %}

Note: 'issue' here is a an object of type issue. When preparing a multi-issue template there is no such object initially, rather the array 'issues'. You can use this loop to refer to each issue separately.

CSS styling

To add CSS styling direct into the template use the <style> tag as you would in an HTML document.

Import a template

Alternatively, you can a template. You cannot import a template that has the same name as an existing one unless you mark Rewrite existed. In that case, the existing one will be replaced by the import.

Note: You can try out our sample templates. Just download the .yml template file and import it into your Redmine.

Was this article helpful? Yes  No
3530 from 3576 found this helpful