My client has always preferred reading an email at the start of his day that summarizes all the work his dev team was up to the night before. We call it the status mail. It usually contains the list of tasks we have worked on, containing its full description along with our comments/status on that day. Such reports are favorites among clients who are non-technical or who cannot afford to spend time in JIRA, as they get all updates in one go. But, of course, this is beneficial only for a team size of 5-20 members. Any more than that, the mail itself becomes too long to read.
We adopted JIRA only recently, slightly more than a year ago. During the pre-JIRA dark ages, my predecessors had to perform a laborious task of compiling status mails from tasks, bugs and feature requests sent by the clients over emails. It used to easily take up 30-60 mins on a rainy day, copy pasting updates provided by the team, then mix-matching the formats to make it look good, etc. Moreover, it was too much manual labor to love this part of the job.
Then came JIRA, and life became much more efficient.
Creating Status Mail from JIRA
So, let us get down to the core part of this post. The steps to create a status mail are pretty straightforward. But before we proceed further, go through the checklist below that you may need (to know).
The Secret Ingredients List
- JQL (JIRA Query Language) to build your query
- JIRA API to fetch the query results programmatically
- An application+ to fetch your results using JIRA API
- JQuery templates+ to build your email content (HTML) from your processed final JSON.
First and foremost, you need to fetch only relevant issues that have been updated that day to be processed and put into the status mail. JQL (JIRA Query Language) is the best way to get that done. A typical example of the query I use is as follows.
project in ("My Project") AND comment ~ "\\[statuscomment\\]" AND updated > startOfDay() AND updated < endOfDay() ORDER BY key DESC
- In our implementation, a comment that needs to go into the status mail must be prefixed with
[statuscomment], so that only the relevant comments are grabbed when processing results (later below).
- Of course, you can use any other keyword instead – just change it in the processing function. If you don’t want any “keyword processing” at all, such that all comments from today should show up, that’s fine by me. Just, again, make sure to change the processing function accordingly.
- You may save the JQL query as a JIRA Filter, so that you can reuse or reference it later.
- The JQL above is not perfect, because it may fetch issues that have not been actually updated with a
statuscommenton that day. A typical example is, if you added a status comment for an issue yesterday (and not today), but you did update it today (like marked it to done or edited some fields), the task still qualifies for the JQL above. This is because JQL does not support querying individual comments’
updateddates. However, this should not be an issue for us, as we will be filtering out such comments, as you will see later.
To fetch issues from JIRA in to your application, you need to use
/search API. You can use either
POST method to do so. The JIRA documentation explains all necessary steps clearly, so I’m not covering that. However, here are the key parameters that you should add to fetch all necessary details in one go.
Sample JQL result-set provided at the bottom. (See gist
There are a few key things to note in this result set:
- It brought only the fields mentioned in
maxResultsproperties are used for pagination. By default, JIRA API brings only 50 items per query. So, if you have more than 50 issues to process daily, you should tweak your API call accordingly.
- There is a
renderedFieldsproperty which contains the actual rendered HTML of the description fields, and not the JIRA wiki syntax as in descriptions in the original
fields. The JIRA wiki syntax is useless for us.
processStatus(data) function in below
01-jira-task-status-processor.js gist is our public API to building the status HTML. What it essentially does is:
- Process result set per issue-item per comment
- Check that the comment must begin with
[statuscomment]– else do not process
- Check that date of comment must be after
checkDatedefaults to today) – else do not process
- Strip out
[statuscomment]tag from comment, as not required anymore
- Prepare an object containing issue title, description, filtered comments content, user details of comments, etc.
- (Freebie) Encode comments so that we can put it into email replies automatically when Repy >button is clicked. (See further sections below to understand what I’m talking about)
- Pass object to JQuery Templates (see
02-jira-status-template.htmlgist) that builds the final status mail HTML.
jiraAPIResponseProcessor()is just a wrapper function.
- You may need to modify these gists for your use.
- I will try to create an API/library for you in the near future, so that you do not have to deal with these boiler plate codes.
Combined together with the JIRA API result-set, you may generate an HTML which finally looks like the following image. Of course, this is a very crude representation below without any styling whatsoever. So, please do stylize the output as you like, before sending it to your boss. 😉
Here is the gist