OpenSearch/x-pack/docs/en/watcher/actions/jira.asciidoc

[[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 (see {ref}/secure-settings.html[secure settings]):

[source,yaml]
--------------------------------------------------
bin/elasticsearch-keystore xpack.notification.jira.account.monitoring.secure_url
bin/elasticsearch-keystore xpack.notification.jira.account.monitoring.secure_user
bin/elasticsearch-keystore xpack.notification.jira.account.monitoring.secure_password
--------------------------------------------------

deprecated[The insecure way of storing sensitive data (`url`, `user` and `password`) in the configuration file or the cluster settings is deprecated]

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:

NOTE: The `url` field can also contain a path, that is used to create an issue. By
default this is `/rest/api/2/issue`. If you set this as well, make sure that this
path is the full path to the endpoint to create an issue.

[source,yaml]
--------------------------------------------------
xpack.notification.jira:
  account:
    monitoring:
      allow_http: true
--------------------------------------------------

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

You can also specify defaults for the
{ref}/notification-settings.html#jira-account-attributes[Jira issues]:

[source,yaml]
--------------------------------------------------
xpack.notification.jira:
  account:
    monitoring:
      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:
      ...
--------------------------------------------------