From 3549a95aa60294fa90c8159986cc2553cd4413e7 Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Tue, 8 Apr 2025 10:08:32 +0200 Subject: [PATCH] [release-11.6.1] docs: create documentation for jira service management contact point (#103576) docs: create documentation for jira service management contact point (#100444) * docs: create documentation for jira service management contact point create documentation page for jira service management * Update configure-jira-service-management.md updates thanks to yuri and some subsequent edits * minor edits, weight minor edits, weight * links and tables links and references to jira added on other pages, bullets turned into a table. * edits * Update configure-jira.md link fix * Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-jira.md Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> * Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-jira.md Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> * Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-jira.md Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> * Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-jira.md Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> * Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-jira.md Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> * Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-jira.md Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> * Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-jira.md Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> * Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-jira.md Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> * pretty, prettier, prettiest * Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-jira.md Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> * Update configure-jira.md prettier --------- Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> (cherry picked from commit 671ba2ab024295b02929aaf2a08f4839c8bfe466) Co-authored-by: Johnny Kartheiser <140559259+JohnnyK-Grafana@users.noreply.github.com> --- .../manage-contact-points/_index.md | 6 ++ .../integrations/configure-jira.md | 74 +++++++++++++++++++ .../notifications/contact-points.md | 1 + 3 files changed, 81 insertions(+) create mode 100644 docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-jira.md diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/_index.md b/docs/sources/alerting/configure-notifications/manage-contact-points/_index.md index 215ed1926dc..3da03cef5b7 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/_index.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/_index.md @@ -96,6 +96,11 @@ refs: destination: /docs/grafana//alerting/configure-notifications/template-notifications/manage-notification-templates/ - pattern: /docs/grafana-cloud/ destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/template-notifications/manage-notification-templates/ + jira: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/manage-contact-points/integrations/configure-jira/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/manage-contact-points/integrations/configure-jira/ configure-grafana-alerts: - pattern: /docs/grafana/ destination: /docs/grafana//alerting/alerting-rules/create-grafana-managed-rule/ @@ -142,6 +147,7 @@ Each contact point integration has its own configuration options and setup proce - [Google Chat](ref:gchat) - [Grafana OnCall](ref:oncall) - Kafka REST Proxy +- [Jira](ref:jira) - Line - [Microsoft Teams](ref:teams) - [MQTT](ref:mqtt) diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-jira.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-jira.md new file mode 100644 index 00000000000..892529c87f5 --- /dev/null +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-jira.md @@ -0,0 +1,74 @@ +--- +canonical: https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/configure-jira/ +description: Configure the Jira integration to receive notifications when your alerts are firing +keywords: + - grafana + - alerting + - Jira + - integration +labels: + products: + - cloud + - enterprise + - oss +menuTitle: Jira +title: Configure Jira for Alerting +weight: 121 +refs: + configure-contact-points: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/manage-contact-points/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/manage-contact-points/ +--- + +# Configure Jira for Alerting + +Use the Jira integration in a contact point to create issues in your Jira instance when alerts fire. The integration supports both Jira Cloud and Jira Server/Data Center installations. + +## Before you begin + +Before you begin, ensure you have the following: + +- A Jira instance (Cloud, Server, or Data Center) +- API access credentials for Jira +- Appropriate permissions to create issues in your target Jira project + +## Configure Jira for a contact point + +To create a contact point with a Jira integration, complete the following steps: + +1. Navigate to **Alerts & IRM** -> **Alerting** -> **Contact points**. +2. Click **+ Add contact point**. +3. Enter a name for the contact point. +4. From the **Integration** list, select **Jira**. +5. Set up the required [settings](#required-settings) for your Jira configuration. +6. Click **Save contact point**. + +For more details on contact points, including how to test them and enable notifications, refer to [Configure contact points](/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/). + +### Required Settings + +| Key | Description | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| URL | The URL of the REST API of your Jira instance. Supported versions: `2` and `3` (e.g., `https://your-domain.atlassian.net/rest/api/3`). | +| Basic Auth User | Username for authentication. For Jira Cloud, use your email address. | +| Basic Auth Password | Password or personal token. For Jira Cloud, you need to obtain a personal token [here](https://id.atlassian.com/manage-profile/security/api-tokens) and use it as the password. | +| API Token | An alternative to basic authentication, a bearer token is used to authorize the API requests. See [Jira documentation](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) for more information. | +| Project Key | The project key identifying the project where issues will be created. Project keys are unique identifiers for a project. | +| Issue Type | The type of issue to create (e.g., `Task`, `Bug`, `Incident`). Make sure that you specify a type that is available in your project. | + +### Optional Settings + +| Key | Description | +| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Title | The issue title. Supports templating. Max length is 255 characters. | +| Description | The description of the issue. Depending on version of the API, it can be a text, Markdown, or JSON (v3 API only). Maximum size of the field is 32kb.
**Note:** JSON is not limited by the client, and if it exceeds the size, the API is likely to reject the request. | +| Labels | Custom labels can be added to organize and filter issues created in Jira. Supports templating, allowing dynamic label generation based on alert data. | +| Priority | The priority level of the issue (e.g., `Low`, `Medium`, `High`, `Critical`).
Ensure that the priority value matches the available options for your Jira instance. You can customize priority levels in Jira [here](https://support.atlassian.com/jira-cloud-administration/docs/configure-priorities/). | +| Resolve Transition | The transition name to move the issue to a resolved state when an alert is resolved. Ensure that the value matches a valid transition available in your Jira workflow for the specified issue type. If this field is empty, the issue will not be transitioned to Done. | +| Reopen Transition | The transition name to move the issue back to an open state when an alert reoccurs. Ensure that the value matches a valid transition available in your Jira workflow for the specified issue type. If this field is empty, the issue will not be reopened. | +| Reopen Duration | The time duration (in minutes) to control whether to reopen an issue that was closed within this duration or create a new one. If not specified, the most recent issue that matches the deduplication key will be updated and reopened (if reopen transition is specified). | +| Ignored Resolution | Specify a resolution status that should be ignored when searching for existing issues. For example, issues with this resolution will not be reopened or updated by subsequent alerts. | +| Deduplication Key Field | Custom field to store the deduplication key. Must be a text field.
If not specified, the deduplication key is added to labels in the format of `ALERT(hash sum)`. See [Jira documentation](https://support.atlassian.com/jira-cloud-administration/docs/create-a-custom-field/) for how to create custom fields. | +| Fields | Allows to configure custom fields of Jira issue. The field name should be of the format like `customfield_10001`. | diff --git a/docs/sources/alerting/fundamentals/notifications/contact-points.md b/docs/sources/alerting/fundamentals/notifications/contact-points.md index 702bed9cdce..18264d037d3 100644 --- a/docs/sources/alerting/fundamentals/notifications/contact-points.md +++ b/docs/sources/alerting/fundamentals/notifications/contact-points.md @@ -44,6 +44,7 @@ A contact point includes one or more contact point integrations for sending aler - Email - Google Chat - Grafana Oncall +- Jira - Kafka REST Proxy - Line - Microsoft Teams