[[actions-jira]]
=== Jira Action

Use the `jira` action to create issues in  https://www.atlassian.com/software/jira[Atlassian's Jira Software].
To create issues you need to <<configuring-jira, configure at least one Jira account>> in `elasticsearch.yml`.

[[configuring-jira-actions]]
==== Configuring Jira Actions

You configure Jira actions in the `actions` array. Action-specific attributes
are specified using the `jira` keyword.

The following snippet shows a simple jira action definition:

[source,js]
--------------------------------------------------
"actions" : {
  "create-jira-issue" : {
    "transform" : { ... },
    "throttle_period" : "5m",
    "jira" : {
      "account" : "integration-account", <1>
      "fields" : {
        "issue" : {
          "project" : {
            "key": "PROJ" <2>
          },
          "issuetype" : {
            "name": "Bug" <3>
          },
          "summary" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes", <4>
          "description" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)", <5>
          "labels" : ["auto"], <6>
          "priority" : {
            "name" : "High" <7>
          }
        }
      }
    }
  }
}
--------------------------------------------------
<1> The name of a Jira account configured in `elasticsearch.yml`.
<2> The key of the Jira project in which the issue will be created.
<3> The name of the issue type.
<4> The summary of the Jira issue.
<5> The description of the Jira issue.
<6> The labels to apply to the Jira issue.
<7> The priority of the Jira issue.

[[jira-action-attributes]]
==== Jira Action Attributes

Depending of how Jira projects are configured, the issues can have many different fields and values. Therefore
the `jira` action can accept any type of sub fields within its `issue` field. These fields will be directly used
when calling Jira's https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-createIssue[Create Issue API], allowing
 any type of custom fields to be used.

NOTE: The `project.key` (or `project.id`), the `issuetype.name` (or `issuetype.id`) and `issue.summary` are
always required to create an issue in Jira.

[cols=",^,", options="header"]
|======
| Name                     |Required | Description

| `account`                 | no      | The Jira account to use to send the message.

| `proxy.host`              | no      | The proxy host to use (only in combination with `proxy.port`)

| `proxy.port`              | no      | The proxy port to use (only in combination with `proxy.host`)

| `fields.project.key`      | yes     | The key of the Jira project in which the issue will be created.
                                       It can be replaced by `issue.project.id` if the identifier of the
                                       project is known.

| `fields.issuetype.name`   | yes     | A name that identifies the type of the issue. Jira provides default
                                       issue types like `Bug`, `Task`, `Story`, `New Feature` etc. It can
                                       be replaced by `issue.issuetype.id` if the identifier of the type
                                       is known.

| `fields.summary`          | yes     | The summary (or title) of the issue.

| `fields.description`      | no      | The description of the issue.

| `fields.labels`           | no      | The labels to apply to the Jira issue.

| `fields.priority.name`    | no      | The priority of the Jira issue. Jira provides default `High`,
                                       `Medium` and `Low` priority levels.

| `fields.assignee.name`    | no      | Name of the user to assign the issue to.

| `fields.reporter.name`    | no      | Name of the user identified as the reporter of the issue.
                                      Defaults to the user account.

| `fields.environment`      | no      | Name of the environment related to the issue.

| `fields.customfield_XXX`  | no      | Custom field XXX of the issue (ex: "customfield_10000": "09/Jun/81")


|======

[[configuring-jira]]
==== Configuring Jira Accounts

You configure the accounts {watcher} can use to communicate with Jira in the
`xpack.notification.jira` namespace in `elasticsearch.yml`.

{watcher} supports Basic Authentication for Jira Software. To configure a
Jira account you need to specify:

[source,yaml]
--------------------------------------------------
xpack.notification.jira:
  account:
    monitoring:
      url: https://internal-jira.elastic.co:443
      user: B0A6D1PRD
      password: mslNSCnJR
--------------------------------------------------

To avoid credentials that transit in clear text over the network, {watcher} will
reject `url` settings like `http://internal-jira.elastic.co` that are based on
plain text HTTP protocol. This default behavior can be disabled with the explicit
 `allow_http setting`:

[source,yaml]
--------------------------------------------------
xpack.notification.jira:
  account:
    monitoring:
      url: http://unsecure-jira.elastic.co/
      allow_http: true
      user: B0A6D1PRD
      password: mslNSCnJR
--------------------------------------------------

WARNING: It is strongly advised to use Basic Authentication with secured HTTPS
 protocol only.

You can also specify defaults for the <<jira-account-attributes, Jira issues>>:

[source,yaml]
--------------------------------------------------
xpack.notification.jira:
  account:
    monitoring:
      url: https://internal-jira.elastic.co:443
      user: B0A6D1PRD
      password: mslNSCnJR
      issue_defaults:
        project:
          key: proj
        issuetype:
          name: Bug
        summary: "X-Pack Issue"
        labels: ["auto"]
--------------------------------------------------

If you configure multiple Jira accounts, you either need to configure a default
account or specify which account the notification should be sent with in the
<<actions-jira, jira>> action.

[source,yaml]
--------------------------------------------------
xpack.notification.jira:
  default_account: team1
  account:
    team1:
      ...
    team2:
      ...
--------------------------------------------------