Administration & Automation

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

Dynamic Rules for automation and flexibility

You can define complex statements taking all issue methods into account, from current issue status until issue's parent object or status of children to determine, what traffic-light status to set. In opposite to other solutions, there exsist almost no limits: just 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 to use any editor of you choice to write the snippet of javascript code and put that into a related documentation. The length of your source code must be less than 255 characters due to JIRA's limitations, here. 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. The size of the text field is predefined by JIRA and cannot be expanded by an add-on, but as this copy & paste is an one-off, it is not a huge 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 what

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, like issue.getKey() or issue.getStatus().getName().

Additionally, 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 have got also access to the following native Jira objects in addition:

• issueManager

• changes: all ChangeItems of the related event

Samples

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.

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

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 question, 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 syntex or semantic checking upfront due to performance topics! So, be sure to enter the correct expression.
I highly recommend to use a suitable test environment before modifying a productive system environment. In most cases, mal-functions are cause by humans.