For add-on installation help, read this: https://confluence.atlassian.com/upm/installing-marketplace-apps-273875715.html
RSE runs as a JIRA service. Services are managed on the Administration > System > Advanced > Services page. (See https://confluence.atlassian.com/display/JIRA/Services for more details.)
To add a new RSE service:
com.e7solutions.jira.Rse
On the Edit Service screen, provide the requested parameters.
If you are including an issue comment upon escalation, the workflow transition must be associated with a screen that includes the comment field. Otherwise the escalation transition will occur without the comment being added to the issue. See the FAQ section for more details. |
Check for valid workflow transitions in your JQL. RSE doesn't check your work. If your JQL returns an issue for which the specified workflow transition is invalid, then there's a problem. It's up to you to provide a valid workflow transition id for any issue that might be returned by your JQL. (In case you haven't already guessed, that's why there is an option to specify a "Notify Upon Error" user. That's a really simple way to let you know if something went wrong - 99% of the time you'll get it right anyway.) For example, you probably don't want your JQL to be project = MYPRJCT and not updated >= -26w
, since you probably have a bunch of issues that haven't been touched in 6 months because they are legitimately resolved. You almost certainly don't want to escalate those (and your workflow almost certainly doesn't include an escalation transition for legitimately resolved issues anyway). Instead, you might use something like project = MYPRJCT and not updated >= -26w and status not in (Closed,
Rejected)
. (Note that embedding the escalation logic in your JQL in combination with your workflow can be made to go a pretty long way, allowing for things like multiple escalation levels, e.g. "Escalation Stage 1", "Escalation Stage 2", "ESCALATION CODE RED", etc.)
It should go without saying, but it's probably not a great idea to add functionality like this on a mission-critical production system without having first tested it on a development environment. |
Make the workflow and notification scheme do the hard work. RSE is intended to be as simple as possible, so the only thing it does is invoke a workflow transition. (Well, plus the optional comment. We debated long and hard as to whether that didn't undermine its simplicity, but in the end we think that 99% of the time, leaving a comment explaining why the escalation happened is morally the right thing to do.) If you want anything fancier than that to happen, put a post function on the escalation workflow transition, or use the project's notification scheme to send appropriate emails. See https://confluence.atlassian.com/display/JIRA/Advanced+workflow+configuration for help with post functions, and https://confluence.atlassian.com/display/JIRA/Creating+a+Notification+Scheme for help with notification schemes.
Here are a few examples to get you started...
For alerting the Issue Assignee if any of his/her issues haven't been touched in a week:
project = MYPRJCT and not updated >= -7d and status not in (Closed, Rejected)
If different priority levels require different escalation times, you can do something like this:
project = MYPRJCT and ((priority = Blocker and not updated >= -1h) or (priority = Critical and not updated >= -8h) or (priority = Major and not updated >= -2d)) and status not in (Closed, Rejected)
For closing out issues that have somehow managed to slip through the cracks (e.g. haven't been updated in 6 months):
project = MYPRJCT and not updated >= -26w and status not in (Closed, Rejected)
For gradually turning up the heat ("Escalation 1"..."Escalation 2"...etc.):
This can be accomplished by defining multiple escalation jobs:
project = MYPRJCT and not updated >= -7d and status not in (Closed, Rejected, "Escalation 1")
project = MYPRJCT and not updated >= -7d and status = "Escalation 1"
If you get a failure notification, don't panic. If this happens, it means that your escalation job couldn't be executed (for whatever reason). In any case, this was checked before the escalation was attempted. If there was an error, then absolutely nothing happened to the issue. (Note that this is on an issue-by-issue basis. When RSE encounters issues that it can invoke the workflow transition on, then it does so, but it completely skips any issues that are problematic.)
There are really only a handful of things that can go wrong. Here's how to handle them.
Failure Notification Message | Cause | Resolution |
---|---|---|
The escalation process encountered invalid issues | Either:
|
|
com.atlassian.jira.jql.parser.JqlParseException | Bad JQL syntax | Update the JQL query - one simple way to make sure your query is valid is to run it on the Issue Search screen (in Advanced mode) |
java.lang.Exception: Unknown Escalation User | The escalation user is not a valid JIRA user | Make sure the escalation user is a valid JIRA user id (make sure you select it from the type-ahead suggestions or from the user picker) |
To add comments upon escalation, the workflow transition must be associated with a screen that includes the comment field. Otherwise the escalation transition will occur without the comment being added to the issue.
One way to do this is by creating an "Escalation" transition screen specifically for this purpose, which is defined as having no fields. (This screen will then include a comment field, since every screen includes the comment field by default.)
(See https://confluence.atlassian.com/display/JIRA/Configuring+Workflow for help with associating a screen to a workflow transition.)
Mainly in order to stay Really Simple. RSE uses JIRA's Services user interface as a way of leaving a minimal footprint when installed (i.e., there are no RSE admin pages added!). However, the Services interface by design doesn't provide a means for validating input. (Note, for example, that when you add a "Run Jelly script" service from the "Built-in Services" list, you can set the input-file
and output-file
Service parameters to anything you like, without any validation that it actually points to a file, nor that it's a valid file path format for that matter). Anyway, that's why Services are under the "Advanced" System settings - if you're there, then presumably you know what you're doing. As a compromise, RSE can let you know if something went wrong after the fact. Given that no issue action is performed in such a case, this seems like a reasonable trade-off.
It's up to you - but make sure that the escalation user has sufficient permissions to invoke the specified workflow action on any issue that the JQL might return. We recommend creating a separate bot user in JIRA for this purpose, in order to keep any automatic actions on issues separate from the usual human activity in the Issue History.
Don't do that! You should make sure that any workflow transition that is used for an RSE service is one where the associated screen does not solicit any human input:
Generally speaking, it is strongly recommended that RSE is associated with workflow transitions which are explicitly intended for automatic invocation only (i.e, they are not intended to be invoked by human users). This can be achieved by the use of a Condition on the transition which restricts its availability to the escalation user (for example, using a "User Is In Group" Condition).
That being said, if RSE is asked to invoke a transition which is associated with an input screen, then it will try to invoke the transition if possible. This means that the default values for all fields on that screen will be submitted (which is very possibly not what you want).
Really Simple Escalation is released under the BSD 2-Clause License. Source code is available at https://bitbucket.org/e7solutions/e7-atlassian-rse.