Jira Ticketing Plugin

The Jira ticketing plugin creates Jira issues in response to Horizon alarms.

Setup

The Jira ticketer requires the opennms-plugin-ticketer-jira package to be installed before use.

To install the opennms-plugin-ticketer-jira package, use one of the following commands:

  • For RPM-based distributions:

    • yum install opennms-plugin-ticketer-jira

  • For Debian-based distributions:

    • apt-get install opennms-plugin-ticketer-jira

  1. Once the package has been installed, set the ticketer plugin property in ${OPENNMS_HOME}/etc/opennms.properties.d/ticketer.properties to enable the plugin:

    opennms.ticketer.plugin=org.opennms.netmgt.ticketd.OSGiBasedTicketerPlugin

    If the ticketer properties file does not exist, create it manually.

  2. Configure the plugin by enabling and disabling options in ${OPENNMS_HOME}/etc/jira.properties.

    Name Description

    jira.host

    Jira server URL.

    jira.username

    Username.

    jira.password

    An authentication token. Must be configured in the Jira Cloud user settings.

    jira.project

    The Jira project’s key. Use the jira:list-projects Karaf command to see a list of project keys.

    jira.type

    The issue type ID to use when opening new issues. Use the jira:list-issue-types Karaf command to see a list of issue type IDs (see Finding the ID for issue types in Atlassian’s knowledge base for more information).

    jira.resolve

    Name of the transition to use when resolving issues. The transition name is typically found on a button when looking at the ticket in Jira.

    jira.reopen

    Name of the transition to use when reopening issues. The transition name is typically found on a button when looking at the ticket in Jira.

    jira.status.open

    A comma-separated list of Jira status names that classify a ticket as "Open."

    jira.status.closed

    A comma-separated list of Jira status names that classify a ticket as "Closed."

    jira.status.cancelled

    A comma-separated list of Jira status names that classify a ticket as "Canceled."

    jira.cache.reloadTime

    The amount of time, in milliseconds, it takes to reload the fields cache. This is required to prevent the plugin from reading the issue type’s metadata every time an issue is created. A value of 0 disables the cache.
    The default value is 300000 (5 minutes).

  3. To ensure the ticketer system starts automatically when the service starts, add jira-troubleticketer to the ${OPENNMS_HOME}/etc/featuresBoot.d/ticketer.boot file. If the file does not exist, create it manually.

  4. To start the ticketer system manually, run the following Karaf command:

    feature:install jira-troubleticketer

The plugin should now be ready to use. Open the Karaf shell and run the opennms:jira-verify command to check your configuration.

The jira.verify command will not work until the jira.properties file has been configured.
Metadata expressions can also be used in the fields of the jira.properties configuration file. This lets the user to also reference credentials stored in the secure credentials.

Jira commands

The Jira ticketing plugin includes Karaf commands for setting up the plugin on the Karaf shell. There are commands to list all available projects, versions, components, groups, issue types, and more.

To list all available commands, type help | grep jira in the Karaf shell.

Include --help after a command to see that command’s documentation.

Custom fields

Besides the common fields (creator, create date, description, and subject), you also may need to set custom fields. The Jira ticketing plugin provides the opportunity to define those in the Horizon ticket attributes, which can be overwritten with Drools rules.

To enable the Drools ticketing integration, set the ticketer service layer property in ${OPENNMS_HOME}/etc/opennms.properties.d/ticketer.properties:

opennms.ticketer.servicelayer=org.opennms.netmgt.ticketd.DroolsTicketerServiceLayer

If the ticketer properties file does not exist, create it manually.

In addition, the Drools ticketer rules property in ${OPENNMS_HOME}/etc/drools-ticketer.properties must point to a drools-ticketer-rules.drl file:

drools-ticketer.rules-file=$OPENNMS_HOME/etc/drools-ticketer-rules.drl

Finally, you must place a Drools rule file named drools-ticketer-rules.drl in the ${OPENNMS_HOME}/etc directory.

There is an example file in ${OPENNMS_HOME}/etc/examples that you can use as a template.

The following Drools example defines attributes to set custom fields:

// Set ticket defaults
rule "TicketDefaults"
salience 100
 when
  $alarm : OnmsAlarm()
 then
  ticket.setSummary($alarm.logMsg);
  ticket.setDetails($alarm.description);
  ticket.addAttribute("customfield_10111", "custom-value");
  ticket.addAttribute("customfield_10112", "my-location");
  ticket.addAttribute("customfield_10113", "some classification");
end
Fields must be referenced by their field IDs. Use the opennms:jira-list-fields Karaf command to determine a field’s ID. By default, only custom fields are shown. You can show all fields by appending the -s option to the command.

You may also need to set default values (for example, the component, reporter, or assignee). You can also redefine the project key and issue types in the jira.properties file.

The Horizon ticketer attribute model only lets you set a String value. The Jira model, however, is slightly different, and each Horizon attribute value must be converted to a Jira field type.

This table describes valid values for Horizon attributes:

Type Description

any

Any String.

date

Any date in YYYY-MM-DD format.

datetime

Any date-time value in the ISO 8601 format (YYYY-MM-DDThh:mm:ss.sTZD).

group

A group’s name.

user

A user’s name.

project

A project’s key (for example, NMS).

version

The version name. To list all available versions, use the jira:list-versions command.

string

Any String.

option

An option’s name.

issuetype

An issue type (for example, Bug). To list all issue types, use the jira:list-issue-types command.

priority

A priority level (for example, Major). To list all priorities, use the jira:list-priorities command.

option-with-child

An option’s name, or a comma-separated list of a parent option and its applicable children (for example, parent,child).

number

Any valid number (for example, 1000).

array

If the type is array, the value must be of the containing type. For example, to set a custom field that defines multiple groups, the value jira-users,jira-administrators is mapped properly. The same is valid for versions: 18.0.3,19.0.0.

Values are usually identified by their names instead of their IDs, and projects are identified by their keys. This makes properties files easier to read, but may break the mapping code if the name of a component changes in the future.

To change the mapping from name or key to id, add the following entry in ${OPENNMS_HOME}/etc/jira.properties:

jira.attributes.customfield_10113.resolution=id

See the following articles to learn more about the Jira REST API:

The following Jira (custom) fields have been tested with Jira version 6.3.15:

  • Checkboxes

  • Date Picker

  • Date Time Picker

  • Group Picker (multiple groups)

  • Group Picker (single group)

  • Labels

  • Number Field

  • Project Picker (single project)

  • Radio Buttons

  • Select List (cascading)

  • Select List (multiple choices)

  • Select List (single choice)

  • Text Field (multi-line)

  • Text Field (read only)

  • Text Field (single line)

  • URL Field

  • User Picker (multiple user)

  • User Picker (single user)

  • Version Picker (multiple versions)

  • Version Picker (single version)

All other field types are mapped as-is, and therefore may not work.

Examples

The following output is the result of the command opennms:jira-list-fields -h http://localhost:8080 -u admin -p testtest -k DUM -i Bug -s. It lists all available fields for project with key DUM and issue type Bug:

Name                           Id                   Custom     Type
Affects Version/s              versions             false      array
Assignee                       assignee             false      user
Attachment                     attachment           false      array
Component/s                    components           false      array  (1)
Description                    description          false      string
Environment                    environment          false      string
Epic Link                      customfield_10002    true       any
Fix Version/s                  fixVersions          false      array (2)
Issue Type                     issuetype            false      issuetype (3)
Labels                         labels               false      array
Linked Issues                  issuelinks           false      array
Priority                       priority             false      priority (4)
Project                        project              false      project (5)
Reporter                       reporter             false      user
Sprint                         customfield_10001    true       array
Summary                        summary              false      string
custom checkbox                customfield_10100    true       array (6)
custom datepicker              customfield_10101    true       date

The following snippet shows how to set the custom fields in your Drools script:

ticket.addAttribute("components", "core,web"); (1)
ticket.addAttribute("assignee", "ulf"); (2)
ticket.addAttribute("fixVersions", "1.0.1"); (3)
ticket.addAttribte("issueType", "Task"); (4)
ticket.addAttribute("priority", "Minor"); (5)
ticket.addAttribute("project", "HZN"); (6)
ticket.addAttribute("summary", "Custom Summary"); (7)
ticket.addAttribute("customfield_10100", "yes,no"); (8)
ticket.addAttribute("customfield_10101", "2021-12-06"); (9)

  1. Sets the issue’s components to core and web.

  2. Sets the issue’s assignee to the user with login ulf.

  3. Sets the issue’s fix version to 1.0.1.

  4. Sets the issue type to Task, overwriting the value of jira.type.

  5. Sets the issue’s priority to Minor.

  6. Sets the project to HZN, overwriting the value of jira.project.

  7. Sets the summary to Custom Summary, overwriting any previous summary.

  8. Checks the checkboxes yes and no.

  9. Sets the value to 2021-12-06.

Troubleshooting

When troubleshooting, consult the following log files:

  • ${OPENNMS_HOME}/data/log/karaf.log

  • ${OPENNMS_HOME}/logs/trouble-ticketer.log