RSE Release 1.0.0

Getting Started

Installation

For add-on installation help, read this: https://confluence.atlassian.com/upm/installing-marketplace-apps-273875715.html

Defining An Escalation Service

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:

1. Add a JIRA service with the following values:
   
   1. Name - Your choice. Something descriptive.
   2. Class - Set this to com.e7solutions.jira.Rse
   3. Delay - The delay (in minutes) between service runs.
       

   
   
   

2. On the Edit Service screen, provide the requested parameters.
   
   
   
   

3. All set! You'll see the RSE service you added in the list that appears on Administration > System > Advanced > Services. You can edit/delete it from there if you ever need to.

Tips

Ensuring Valid Workflow Transitions

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.)

Delegating Additional Escalation Actions

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.

Example Escalation Recipes

Here are a few examples to get you started...

Basic 7-Day Reminder

For alerting the Issue Assignee if any of his/her issues haven't been touched in a week:

• JQL - project = MYPRJCT and not updated >= -7d and status not in (Closed, Rejected)
• Workflow - use an "Escalate" transition that is applicable to all non-Closed/Rejected issues, and configure the Notification Scheme to notify the Issue Assignee
• Delay - 1440 (check once a day)

Priority-Based Escalation

If different priority levels require different escalation times, you can do something like this:

• JQL - 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)
  
• Workflow - use an "Escalate" transition that is applicable to all non-Closed/Rejected issues, and configure the Notification Scheme to notify the Issue Assignee (and maybe re-assign it to the Project Lead!)
• Delay - 15 (check every 15 minutes - this JQL checks for Blockers that haven't been updated within an hour!)


Spring Cleaning

For closing out issues that have somehow managed to slip through the cracks (e.g. haven't been updated in 6 months):

• JQL - project = MYPRJCT and not updated >= -26w and status not in (Closed, Rejected)
• Workflow - use a "Closed As Forgotten About" transition that is applicable to all non-Closed/Rejected issues, and configure the Notification Scheme to notify the Issue Reporter and Watchers
• Delay - 1440 (check once a day)

Multi-Tiered Escalation

For gradually turning up the heat ("Escalation 1"..."Escalation 2"...etc.):

This can be accomplished by defining multiple escalation jobs:

• Escalation job #1:
  • JQL - project = MYPRJCT and not updated >= -7d and status not in (Closed, Rejected, "Escalation 1")
  • Workflow - use an "Escalate Level 1" transition that is applicable to all non-Closed/Rejected issues, which sets the status to "Escalation 1"
  • Delay - 1440 (check once a day)
• Escalation job #2:
  • JQL - project = MYPRJCT and not updated >= -7d and status = "Escalation 1"
  • Workflow - use an "Escalate Level 2" transition that is applicable to issues in "Escalation 1" status, which sets the status to "Escalation 2"
  • Delay - 1440 (check once a day)
• Etc...

Failure Notifications

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.)

Troubleshooting Failure Notifications

There are really only a handful of things that can go wrong. Here's how to handle them.

FAQ

Why didn't my escalation comment show up?

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.)

Why doesn't RSE validate my input?

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.

Who should I use as the escalation user?

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.

What happens if I tell RSE to invoke a workflow transition that requires user input (other than a comment)?

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:

• If your escalation leaves a comment, then the transition should be associated with a screen that only includes a comment field
• If your escalation does not leave a comment, then the transition shouldn't be associated with any screen

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).

License and Source

Really Simple Escalation is released under the BSD 2-Clause License. Source code is available at https://bitbucket.org/e7solutions/e7-atlassian-rse.