e-Reminders App for JIRA Cloud

e-Reminders add-on allows JIRA Cloud administrators and users to run custom queries (JQL), on a regular base or on demand, and have results delivered by email.

Administrators can setup queries that will be executed for the whole JIRA user group and under user's identity so each users gets own view to JIRA issues.

If you have any question, please contact us at support@bugsio.com.

Global Settings

JIRA administrators can access global configuration page using Configure button on the JIRA's Add-ons page.

User Level Settings

Members of the ereminders-users JIRA group can setup their own reminders opening configuration page from the JIRA User Menu.

Report Settings

Query Options

Name: Name of the report, also used as default subject of report email.

JIRA Query: JQL expression - see Queries

Max Results: Maximal number of results for JQL

Issue Fields: Comma or white-space separated list of additional issue fields to include in report. (Issue key and summary are always included by default.) Field names are case sensitive.

To see all issue fields available in the result set, click "Test Query" button. As a result, you will get a list of fields with their content as coming from JIRA. In many cases issue field values coming from JIRA are complex objects and you'd probably want to include just a certain part of it in your report. To do this, extend the issue field name with a dot followed by an object field name of interest.

Examples: environment, description, duedate, reporter.displayName, project.name, status.name, priority.name, issuetype.name, versions.name, fixVersions.name, labels.name, assignee.displayName, votes.votes, created.formatted.rfc822.

Date fields allow additional formatting options.

Group By: Select this if you want issues grouped by selected criteriaGroup issues in report.

Schedule Options

Start Date/Time: When the report should run.

Repeats: Set frequency of the report. You can run it daily (on selected days), weekly or monthly.

Recipients Options

Send Report To: Who should receive the report. Send to your self or to any specified email address.

For system level reports, JIRA administrators have an option to send report to the selected JIRA user group.

Format Options

Message: Specifies text to include at the top of the report email. In the message text you may use $TOTAL and $COUNT placeholders for the total and included number of issues.

Data Template: Get report as a simple list, HTML table or CSV file attached to email.

Custom Email Template: See Email Template

note

All issue fields explicitly listed in email template (e.g. "assignee.displayName") must be specified in the "Issue Fields" list on the Query tab.

Queries

You can use any valid JIRA query with e-Reminders to setup a personal or group report.

If the query contains placeholder $USER and report is sent to a JIRA group/role, e-Reminders add-on will run query individually for each group/role member, replacing $USER with username of the member.

note

All Queries are run by JIRA user "e-Reminders" that is automatically created and associated with the add-on. Make sure this user has sufficient access rights to pull needed data.

For more details about the JIRA Query Language (JQL) see Atlassian's articles:

• Advanced Searching
• Advanced Searching Functions
• JIRA Query Language (JQL)

Examples

List of open issues with approaching due date

resolution = Unresolved AND due >= -3w AND due <= 20w AND assignee in ($USER) ORDER BY due ASC

Setup this one to run daily for JIRA users (or other group) using grouping by due date and recipients will get a nice email with an overview of approaching deadlines.

Find critical issues without due date set

priority >= Critical AND status = Open and duedate is NULL

Administrators or project managers could run this or similar report daily to make sure critical issues are not missed in planning.

Email Template

e-Reminders add-on allows complete customization of email formatting.

For template syntax details, see Go HTML template package documentation.

The following data objects are available in template:

• Name: Name of the report
• FieldIds: Top level field names
• IssueGroups: Issue groups
• Issues: Found list of issues
• TotalIssues: Number of issues found
• JiraFields: Issue fields metadata
• JiraUrl: Base URL to JIRA
• ContactUser: Report owner

Sample HTML template:

{{$self := .}}

<h2>Simple issues list:</h2>

<ul>

{{range .Issues}}

<li>

<a href="{{$self.JiraUrl}}/browse/{{.Key}}">{{.Key}}</a> ({{.FieldValue "issuetype.name"}})

assigned to {{.FieldValue "assignee.displayName"}}

<br/>Date formatting examples:

<br>* <em>updated.formatted.RFC1123</em>:

{{formatValueForReport .Fields "updated.formatted.RFC1123" $self.JiraFields}}

<br>* <em>updated.formatted with custom format</em>:

{{formatValueForReport .Fields "updated.formatted" $self.JiraFields "Jan _2 15:04:05 MST"}}

<br>* <em>updated.formatted with custom format and location</em>:

{{formatValueForReport .Fields "updated.formatted" $self.JiraFields "Jan _2 15:04:05 MST" "America/New_York"}}

</li>

{{end}}

</ul>

<h2>An example with grouping, showing all fields listed in UI:</h2>

{{range $sInd,$group := .IssuesGroups}}

{{if $group.Issues}}

<h4>{{$group.Name}}</h4>

<ul>

{{range $ind,$issue := $group.Issues}}

<li><a href="{{$self.Instance.BaseUrl}}/browse/{{$issue.Key}}">{{$issue.Key}}</a> {{$issue.Summary}}

{{range $key := $self.FieldIds}}

<br/>{{getFieldName $self.JiraFields $key}}:

{{formatValueForReport $issue.Fields $key $self.JiraFields}}

{{end}}

</li>

{{end}}

</ul>

{{end}}

{{end}}

note

Issue fields explicitly listed in email template (e.g. "assignee.displayName" above) must be specified in the "Issue Fields" list on the Query tab.

Formatting Dates

By default, date and datetime JIRA field values are printed as received from JIRA (e.g. "2006-01-02T15:04:05+0700"). You can customize date format adding ".formatted" suffix to field name, accompanied by format details as described below.

Formatting dates in predefined template

When using one of predefined email template formats (list, table or CSV), date fields can be formatted using one of following formats: RFC822, RFC822Z, RFC850, RFC1123, RFC1123Z, RFC3339, ANSIC, UnixDate.

To format date field, specify issue field (in the Query options) as <field_name>.formatted.<format>

For example: created.formatted.rfc822, updated.formatted.UnixDate

Formatting dates in custom template

In custom email templates you can format date/time using any valid time format layout, optionally converting time to IANA Time Zone specifying zone location (e.g. "America/New_York").

For example:

{{formatValueForReport $issue.Fields "updated.formatted" $self.JiraFields "Jan _2 15:04:05 MST" "America/New_York"}}

What happens here is that we invoke function formatValueForReport, passing to it:

• the current issue fields data,
• issue field name (where ".formatted" suffix means we want it formatted)
• JIRA fields metadata (so the function can check the type of field)
• date/time format layout
• time zone location (optional)

For more examples see the custom email template sample.

For details about time format layout see Golang time package.