Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Text updates: jira/jira-servicedesk-incidents #290

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Text updates: jira/jira-servicedesk-incidents #290

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bc38445
Text updates: jira/jira-servicedesk-incidents
hillaryfraley Aug 1, 2022
eeb71ef
Fix link typo
hillaryfraley Aug 3, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion integrations/jira/jira-servicedesk-incidents/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,13 @@ to [Semantic Versioning][semver].

## Unreleased

- N/A
- Add default values for base URL and project key in integration yaml
- Revise text labels and prompts in configuration modal
- Revise summary for success screen in integration yaml file
- Rename dashboard screenshot (use a more descriptive name) in README
- Remove explanation about filters and silencing in README
- Add and revise setup steps and options in README
- Update reference documentation list in README

## [ 20220421.0.0 ] - 2022-04-21

Expand Down
67 changes: 35 additions & 32 deletions integrations/jira/jira-servicedesk-incidents/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,69 +2,75 @@

<!-- Sensu Integration description; supports markdown -->

The Jira Service Management integration is a Sensu Event Pipeline that generates alerts in the Jira Service Management service.
The Jira Service Management integration provides a Sensu pipeline that creates Jira incidents based on the events that Sensu checks generate.

<!-- Provide a high level overview of the integration contents (e.g. checks, filters, mutators, handlers, assets, etc) -->

This integration provides the following resources:
This integration provides the following Sensu resources:

* `jira-servicedesk-pipeline` [pipeline]
* `jira-servicedesk-handler` [handler]
* `jira-servicedesk-incidents` [pipeline]
* `sensu/sensu-jira-handler:2.0.0` [asset]

## Dashboards

<!-- List of supported dashboards w/ screenshots (supports png, jpeg, and gif images; relative paths only; e.g. `![](img/dashboard-1.png)` )-->

This integration is compatible with the Jira Service Management dashboard. The Incidents dashboard will display the Sensu Event namespace, entity, and check details (including check status).
The Jira Service Management integration is compatible with the Jira Service Management dashboard. The incident page will display the Sensu event namespace, entity, and check details, including check status.

![](img/screenshot.png)
![](img/jira-service-mgmt-dashboard-screenshot.png)

## Setup

<!-- Sensu Integration setup instructions, including Sensu agent configuration and external component configuration -->
<!-- EXAMPLE: what configuration (if any) is required in a third-party service to enable monitoring? -->

1. **Get a Jira Service Management API Token**
1. Get the Jira Service Management [base URL], project key, [issue type], username, and [API token].

While the on-premise version of Jira uses basic HTTP authentication with only
a simple username and password the [cloud version requires the use of an API
token to authenticate][about-atlassian-api-tokens].
**Optional**: If you want to use Sensu [secrets] to represent the Jira username and API token, you will need the secret names when you install this integration.

To create the API token perform the following steps:
1. Add the `jira-servicedesk-incidents` [pipeline] to one or more [checks].

1. Navigate to [Atlassian's API Tokens Screen][atlassian-api-tokens]
1. Click on the `Create API Token` button
1. In the popup box enter `Sensu Jira Handler` or any label of your liking
1. Click on the `Create` button
1. Click on `Copy to clipboard` to copy your token
<details><summary><strong>Example: Check pipeline configuration</strong></summary>

## Plugins
```yaml
spec:
pipelines:
- api_version: core/v2
type: Pipeline
name: jira-servicedesk-incidents
```

<!-- Links to any Sensu Integration dependencies (i.e. Sensu Plugins) -->
</details>
<br>

- [sensu/sensu-jira-handler:2.0.0][jira-plugin-bonsai]
## Plugins

## Metrics & Events
<!-- Links to any Sensu Integration dependencies (i.e. Sensu Plugins) -->

<!-- List of all metrics or events collected by this integration. -->
The Jira Service Management integration uses the following Sensu [plugins]:

This integration does not produce any [metrics].
- [sensu/sensu-jira-handler:2.0.0][jira-plugin-bonsai]

## Alerts

<!-- List of all alerts generated by this integration. -->

This integration provides an alert & incident management processing pipeline for use with other monitoring integrations. By default this integration will process all events passing the [built-in `is_incident` filter][is_incident] (i.e. failing events and resolution events only). Event processing via this integration may be suppressed using [Sensu Silencing][silences] (see the [built-in `not_silenced` filter][not_silenced] for more details).
The Jira Service Management integration does not produce any events that should be processed by an alert or incident management [pipeline].

## Metrics

This integration does not produce any events that should be processed by an alert or incident management [handler].
<!-- List of all metrics or events collected by this integration. -->

The Jira Service Management integration does not produce any [metrics].

## Reference Documentation

<!-- Please provide links to any relevant reference documentation to help users learn more and/or troubleshoot this integration. -->

1. This integration uses [Handler Templating][handler-templating] for variable substitution
1. This integration uses Sensu's built-in [Secrets Management][secrets-mgmt]
* [Handler templating][handler-templating] (Sensu documentation): the Jira Service Management integration supports handler templating for variable substitution with data from Sensu events
* [Jira Service Management Cloud documentation] (Atlassian documentation)


<!-- Links -->
[check]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-schedule/checks/
Expand All @@ -79,11 +85,8 @@ This integration does not produce any events that should be processed by an aler
[handler-templating]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/handler-templates/
[pipeline]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/pipelines/
[secret]: https://docs.sensu.io/sensu-go/latest/operations/manage-secrets/secrets/
hillaryfraley marked this conversation as resolved.
Show resolved Hide resolved
[secrets-mgmt]: https://docs.sensu.io/sensu-go/latest/operations/manage-secrets/secrets-management/
[about-atlassian-api-tokens]: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
[atlassian-api-tokens]: https://id.atlassian.com/manage/api-tokens
[API token]: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
[jira-plugin-bonsai]: https://bonsai.sensu.io/assets/sensu/sensu-jira-handler
[is_incident]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-filter/filters/#built-in-filter-is_incident
[not_silenced]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-filter/filters/#built-in-filter-not_silenced
[silencing]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/silencing/
[silences]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/silencing/
[issue type]: https://confluence.atlassian.com/servicedeskcloud/issue-types-1097176086.html
[base URL]: https://confluence.atlassian.com/adminjiraserver/configuring-the-base-url-938847830.html
[Jira Service Management Cloud documentation]: https://support.atlassian.com/jira-service-management-cloud/resources/
0 ...-servicedesk-incidents/img/screenshot.png → ...ira-service-mgmt-dashboard-screenshot.png
View file
Open in desktop
File renamed without changes
79 changes: 37 additions & 42 deletions integrations/jira/jira-servicedesk-incidents/sensu-integration.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,49 +21,42 @@ spec:
title: Jira Service Management Configuration
- type: markdown
body: |
This integration requires a Jira account and [Jira Service Management] project.
Provide these Jira Service Management configuration parameters:

* [Jira URL] (e.g. `https://mycompany.atlassian.net`)
* [Jira Project Key] (e.g. `OPS`)
* [Jira Issue Type] (e.g. `[System] Incident`)

Please provide these Jira configuration parameters below.

[Jira Service Management]: https://www.atlassian.com/software/jira/service-management/features/service-desk
[Jira URL]: https://confluence.atlassian.com/adminjiraserver/configuring-the-base-url-938847830.html
[Jira Project Key]: https://support.atlassian.com/jira-cloud-administration/docs/edit-a-projects-details/
[Jira Issue Type]: https://support.atlassian.com/jira-cloud-administration/docs/what-are-issue-types/
* Jira base URL (e.g. `https://mycompany.atlassian.net`)
* Jira Service Management project key (e.g. `OPS`)
* Jira Service Management issue type (e.g. `[System] Incident`)
- type: question
name: jira_url
required: true
input:
type: string
title: Jira URL
description: Please provide the Jira site URL (e.g. https://yourcompany.atlassian.net)
title: Jira base URL
description: Enter the Jira site base URL
default: "https://mycompany.atlassian.net"
- type: question
name: jira_project_key
required: true
input:
type: string
title: Jira Project Key
description: Please provide the Jira Project Key (e.g. "OPS")
title: Jira project key
description: Enter the Jira Service Management project key
default: "OPS"
- type: question
name: jira_issue_type
required: true
input:
type: string
title: Jira Issue Type
description: Please provide the Jira Issue Type (e.g. "[System] Incident")
title: Jira issue type
description: Enter the Jira Service Management issue type
default: "[System] Incident"
- type: section
title: Jira Service Management Integration Authentication
title: Jira Service Management Authentication
- type: markdown
body: |
This integration requires a Jira Service Management API Token for Jira Service Management API Authentication.
Provide the Jira Service Management username and [API token].

Please visit the Jira Service Management knowledge base article ["Manage API Tokens for your Atlassian Account"] for more information.

["Manage API Tokens for your Atlassian Account"]: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
[API token]: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
- type: question
name: jira_username
required: true
Expand All @@ -77,17 +70,17 @@ spec:
properties:
option:
type: string
title: Jira Username
title: Jira username
const: secret
constLocale:
title: Secret
description: >-
Select this option to use Sensu Secrets Management
Use a Sensu secret to provide the Jira username
secret:
type: string
title: Jira Username (Sensu Secret)
title: Secret name
description: >-
Select the Jira Username (Sensu Secret)
Enter the secret name for the Jira username
ref: secrets/v1/secret/metadata/name
- type: object
required:
Expand All @@ -96,17 +89,17 @@ spec:
properties:
option:
type: string
title: Jira Username
title: Jira username
const: env_var
constLocale:
title: Environment Variable
title: Environment variable
description: >-
Select this option to store sensitive configuration as environment variables
Save the Jira username as a backend environment variable
env_var:
type: string
title: Jira Username
title: Jira username
description: >-
Provide the Jira Username (NOTE: this will be stored in the Sensu API as unencrypted plaintext).
Enter the Jira username (username will be stored in the Sensu API as unencrypted plaintext)
- type: question
name: jira_api_token
required: true
Expand All @@ -120,17 +113,17 @@ spec:
properties:
option:
type: string
title: Jira API Token
title: Jira API token
const: secret
constLocale:
title: Secret
description: >-
Select this option to use Sensu Secrets Management
Use a Sensu secret to provide the Jira API token
secret:
type: string
title: Jira API Token (Sensu Secret)
title: Secret name
description: >-
Select the Jira API Token (Sensu Secret)
Enter the secret name for the Jira API token
ref: secrets/v1/secret/metadata/name
- type: object
required:
Expand All @@ -139,17 +132,17 @@ spec:
properties:
option:
type: string
title: Jira API Token
title: Jira API token
const: env_var
constLocale:
title: Environment Variable
title: Environment variable
description: >-
Select this option to store sensitive configuration as environment variables
Save the Jira API token as a backend environment variable
env_var:
type: string
title: Jira API Token
title: Jira API token
description: >-
Provide the Jira API Token (NOTE: this will be stored in the Sensu API as unencrypted plaintext).
Enter the Jira API token (token will be stored in the Sensu API as unencrypted plaintext)
resource_patches:
- resource:
api_version: core/v2
Expand Down Expand Up @@ -186,9 +179,11 @@ spec:
title: Success
- type: markdown
body: |
You have successfully enabled the "jira-servicedesk-incidents" pipeline.
You enabled the Jira Service Management integration.

For events from checks that reference the `jira-servicedesk-incidents` pipeline, Sensu will create incidents in `[[jira_url]]` with project key [[jira_project_key]] and issue type [[jira_issue_type]].

Checks configured with the `elasticsearch` pipeline will send Sensu event and metric data to your Jira Service Management account.
Add the `jira-servicedesk-incidents` pipeline reference to one or more checks:

```yaml
spec:
Expand Down