Administration & Automation

1 Create an additional customfield
2 Various shapes are configurable for visualization
3 Optional settings for traffic-light options
4 Dynamic Rules for automation and flexibility

Create an additional customfield

Create a new custom field of type "Status as Traffic-Light" with global context for all issues. Name it for example "Criticality". A set of default options will be created automatically, but you can modify them like renaming, reordering or change coloring etc.

The syntax of an option looks like:

(color,color,color) label

having "color" a valid name of color or a hex representation like #CC0000. If a color is omitted, then an empty circle will be drawn as light off. The label is an optional name, which will be displayed on the right side of the traffic-light.

Using this syntax, you can configure any possible combination of lights and colors like "(,yellow,red) on the way back to green" to show a traffic-light switching from "red" via "yellow, red" to "green" in a lot of countries: limitations are only your brain and needs ...

Since Traffic-Light version 3.3.0 for Jira Server, you can use the following syntax to reduce the visualization of a traffic-light to just a square:

[color] label

having "color" a valid name of color or a hex representation like #CC0000. This will look like you can see on the sample screenshot:

Various shapes are configurable for visualization

Since version 3.3.1, the following shapes are configurable:

square by using the syntax "[color] optional label"
circle by using the syntax "(color) optional label"
diamond by using the syntax "<color> optional label"
star(s) by using the syntax "*color* optional label", using multiple stars counting the leading number of asterisks like "***color* label" to display 3 stars with a label
traffic-light by using the syntax "(color,color,color) optional label"
colorable trend arrows
harvey balls by using the syntax "{start angle in degree, segment angle in degree, segment color} optional label"

Since v4.2.0: support of harvey balls

Optional settings for traffic-light options

Available since Traffic-Light version 3.1.x:

Blinking Lights

Append ".blink" to any color (HTML color name or RGB hex value like #FFCC00) to force a blinking traffic-light to pay more attention by users.

Trend arrows instead of Traffic-Lights

Prepend "TREND" in uppercase to the option label name to indicate a trend arrow:

having set the left color, then the arrow will be drawn up using this color,
having set the middle color, then the arrow will be drawn sideways using this color,
having set the right color, then the arrow will be drawn down using this color.

Available since Traffic-Light version 4.2.0

Flexible Harvey Balls instead of or in addition to Traffic-Lights

A Harvey ball can be configured as simple as a normal traffic light: just create new options but use "{" and "}" instead of "(" and ")".

The first parameter is the start angle in degree (mostly = 0),
the second parameter is the angle in degree of the colored segment and
the third parameter is the color of the segment like shown within the sample below:

So, you are not limited to just the 4 quarters. You can configure any segment you need. If you have any questions, please do not hesitate to contact me per email at support@traffic-light.polscheit.de

Dynamic Rules for automation and flexibility

You can define complex statements taking all issue methods into account, from the current issue status until the issue's parent object or the status of children to determine what traffic-light status to set. In contrast to other solutions, there are almost no limits: program your rule in JavaScript syntax!

Update traffic-lights in real-time

Available Listeners

de.polscheit.jira.listener.DynamicRulesUpdateListener
de.polscheit.jira.listener.DynamicRulesCreationListener
de.polscheit.jira.listener.DynamicRulesWorkLoggingListener
de.polscheit.jira.listener.DynamicRulesEventListener (since v3.2.0)

In order to create a new listener, please switch into JIRA administration - system - listeners:

Having created an update-/create-/work-logging-Listener, you have to configure the code, which will be executed accordingly:

I recommend using any editor of your choice to write the snippet of JavaScript code and include it in the related documentation. The length of your source code must be less than 255 characters due to JIRA's limitations. So, use e.g. single letter variable names like "i" or "j" to shorten, although this looks like spaghetti-coding. Accessing any customfield content, please use my getter-function issue.getCF() as this is also shorter than using JIRA's native API via issue.getCustomfieldValue().

Then use copy & paste to transfer your source code into the listener. JIRA predefines the size of the text field and cannot be expanded by an add-on; however, as this copy and paste is a one-off, it is not a significant limitation.

Using Traffic-Light version 2.1.1 for JIRA 7, that limitation is no longer there: you can put in almost any code you want ...

Within the summary of all configured listeners, you will find the new (update-/create-/work-logged) listener together with JIRA's defaults and other listeners:

Sample for getting info of an added issue link: the JS variables "from" and "to" will contain the related issue keys, which will be prompted to System.out in the example below.
Using the issue keys, you can load the related issues via issueManager.getIssueByCurrentKey(from) and read fields as well as set customfield values like a traffic-light.

Available workflow function

Post function "Dynamic Rule(s) of Traffic-Light Status"

Important: Take care about the sequence/position of a workflow post function! - If a dynamic rule is executed as workflow post function before storing the issue's new values, the former values are retrieved within the rule, accessing the issue's data.

Using Javascript to code what you want

An expression is a set of javascript statements, each terminated by a semicolon.
All methods of the related issue can be accessed via issue.methodName(). Please have a look at Atlassian's documented JIRA Java-API for detailed information about available methods, such as issue.getKey() or issue.getStatus().getName().

Additionally, the following utility functions are available:

util.log(Object obj);
util.setCFstring(MutableIssue issue, String customfieldName, String value): sets the value of a Jira text customfield
util.setCFoption(MutableIssue issue, String customfieldName, String value): sets the value of a Jira customfield having options like all traffic-light fields
util.getCF(MutableIssue issue, String customfieldName): gets the value of a Jira customfield, which can be referenced by its name or its customfield_id (see samples below)
util.getCFms(MutableIssue issue, String customfieldName): gets the value of a Jira date/datetime customfield in milliseconds

Since version 4.0.6:
util.historyMetadataBuilder(String description): gets a metadata object containing the passed description to be used while performing a workflow transition (see sample below)

The following native Jira objects are available:

issue
issueLinkManager

Since version 4.0.6:
user: the currently logged in user
issueService

Using the "DynamicRulesEventListener", you also have access to the following native Jira objects in addition:
issueManager
changes: all ChangeItems of the related event

Samples

General usage of log output e.g. for debug infos

util.log(util.getCF(issue,'Criticality'));           // this will write the content of the custom field named "Criticality" into the output stream System.out to assist debugging of your own code.

Retrieve the current option value of a traffic-light customfield

var criticality = util.getCF(issue, 'Criticality');if (criticality != null) util.log(criticality);

Set the option of a traffic-light customfield

util.setCFoption(issue,'Criticality','(,#FFBF00,) amber');      // the new value for being set must be 100% identical to the related option's value as you have configured!

Set option values of traffic-lights of linked issues

// set linked issues' traffic-light field "Severity" to the content of this issue's traffic-light field "Criticality":
// just as a generic sample for the usage of issue links regardless if it makes sense from a business point of view, here
var criticality = util.getCF(issue, 'Criticality');
var links        = issueLinkManager.getOutwardLinks(issue.id);
if (criticality  != null) for (var i=0; i<links.size(); i++) {
    if (links.get(i).getIssueLinkType().getOutward().equals("blocks")) {
        util.setCFoption(links.get(i).getDestinationObject(),'Severity',criticality);
    }
}

A more complex sample illustrates the flexibility of what can be automized without any other third-party app using a traffic-light update listener.

Perform a workflow transition of a related epic if a story's traffic-light switches to RED

var epicLinkCF       = 'customfield_10001';  // your EPIC link (name may be translated into a different language, therefore use the customfield ID instead)
var myTrafficLight   = 'customfield_10013';  // your traffic-light customfield
var myOption         = '(,,red) Red';        // must be one of your traffic-light options as configured
var myTransitionId   = 21;                   // transition ID to be executed in case of myTrafficLight has been set to myOption

var value = util.getCF(issue, myTrafficLight);
if (value != null && value == myOption) {  
  var myEpicKey = ""+util.getCF(issue, epicLinkCF);
  if (myEpicKey != null && myEpicKey.length > 0) {
    var issueResult = issueService.getIssue(user, myEpicKey);
    if (issueResult.isValid()) {
      var epic = issueResult.getIssue();
      var issueInputParameters = issueService.newIssueInputParameters();
      issueInputParameters.setHistoryMetadata(util.historyMetadataBuilder("traffic light of " + issue.getKey() + " is RED"));
      var transitionValidationResult = issueService.validateTransition(user, epic.getId(), myTransitionId, issueInputParameters);
      if (transitionValidationResult.isValid()) {
        if (issueService.transition(user, transitionValidationResult).isValid() == false) {
          util.log("-> invalid transition (id " + myTransitionId + " for " + epic.getKey() + ")");
        }
      }
    }
  }
}

Help: If you have any questions, please do not hesitate to contact me at support@traffic-light.polscheit.de

WARNING:

Exceptions are put into the JIRA log file. There is no syntax or semantic checking upfront due to performance topics! So, be sure to enter the correct expression.
I highly recommend using a suitable test environment before modifying a productive system environment. In most cases, malfunctions are caused by humans.

Schedule the automatic setting of traffic-lights

Since Traffic-Light v3.0.5 and later versions, you can configure a scheduled service to automatically set the content of a configured traffic-light field to a specified option value for all issues being retrieved by a given JQL search command.

1. Switch into Jira Administration -> System

2. Scroll down and click on "Services" on the left side

3. Add Service as displayed below: name it like you want but use exactly the Class name "de.polscheit.jira.service.AutoExecuteForFilteredIssuesService" as displayed below

4. Enter a valid JQL for retrieving the issues you want to modify

5. Enter a valid customfield name of type "Traffic-Light"

6. Enter the new option value used for setting

7. Specify the interval of running, e.g., during your night, in order not to cause any performance impacts on your customers/clients/collegues

The JQL would be something like:

statusCategory != Done AND duedate < now()
statusCategory != Done AND "Planned End" < now()