
[[ref-ticketing-jira]]
= Jira Ticketing Plugin
:description: Learn how to set up and use the Jira Ticketing Plugin to create Jira issues in response to {page-component-title} alarms.

The Jira ticketing plugin creates Jira issues in response to {page-component-title} alarms.

[[ref-ticketing-jira-setup]]
== Setup

IMPORTANT: The Jira ticketer requires the `{package-prefix}-plugin-ticketer-jira` package to be installed before use.

****
To install the `{package-prefix}-plugin-ticketer-jira` package, use one of the following commands:

* For RPM-based distributions:
** `yum install {package-prefix}-plugin-ticketer-jira`
* For Debian-based distributions:
** `apt-get install {package-prefix}-plugin-ticketer-jira`
****

. Configure the plugin by enabling and disabling options in `$\{OPENNMS_HOME}/etc/jira.properties`.
+
[options="header"]
[cols="1,3"]
|===
| 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 https://confluence.atlassian.com/display/JIRA050/Finding+the+Id+for+Issue+Types[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).
|===

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

NOTE: The `jira.verify` command will not work until the `jira.properties` file has been configured.

NOTE: 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 {page-component-title} ticket attributes, which can be overwritten with https://www.drools.org/[Drools] rules.

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

[source, 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:

[source, properties]
----
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.

TIP: 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:

[source, drools]
----
// 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
----

NOTE: 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 {page-component-title} ticketer attribute model only lets you set a String value.
The Jira model, however, is slightly different, and each {page-component-title} attribute value must be converted to a Jira field type.

This table describes valid values for {page-component-title} attributes:

[options="header"]
[cols="1,3"]
|===
| 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:

* https://developer.atlassian.com/jiradev/jira-apis/jira-rest-apis/jira-rest-api-tutorials/jira-rest-api-example-create-issue#JIRARESTAPIExample-CreateIssue-MultiSelect[Jira REST API examples]
* https://docs.atlassian.com/jira/REST/cloud/[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)

NOTE: 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`:

[source, table]
----
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:

[source, drools]
----
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>
----

. Sets the issue's components to `core` and `web`.
. Sets the issue's assignee to the user with login `ulf`.
. Sets the issue's fix version to `1.0.1`.
. Sets the issue type to `Task`, overwriting the value of `jira.type`.
. Sets the issue's priority to `Minor`.
. Sets the project to `HZN`, overwriting the value of `jira.project`.
. Sets the summary to `Custom Summary`, overwriting any previous summary.
. Checks the checkboxes `yes` and `no`.
. Sets the value to `2021-12-06`.

[[ref-ticketing-jira-troubleshooting]]
== Troubleshooting

When troubleshooting, consult the following log files:

* `$\{OPENNMS_HOME}/data/log/karaf.log`
* `$\{OPENNMS_HOME}/logs/trouble-ticketer.log`
