171 lines
6.4 KiB
Plaintext
171 lines
6.4 KiB
Plaintext
[[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:
|
|
...
|
|
--------------------------------------------------
|