> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keephq.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira Cloud Provider

> Jira Cloud provider is a provider used to query data and creating issues in Jira

## Authentication

This provider requires authentication.

* **email**: Atlassian Jira Email (required: True, sensitive: False)
* **api\_token**: Atlassian Jira API Token (required: True, sensitive: True)
* **host**: Atlassian Jira Host (required: True, sensitive: False)
* **ticket\_creation\_url**: URL for creating new tickets (optional, will use default if not provided) (required: False, sensitive: False)

Certain scopes may be required to perform specific actions or queries via the provider. Below is a summary of relevant scopes and their use cases:

* **BROWSE\_PROJECTS**: Browse Jira Projects (mandatory)
* **CREATE\_ISSUES**: Create Jira Issues (mandatory)
* **CLOSE\_ISSUES**: Close Jira Issues
* **EDIT\_ISSUES**: Edit Jira Issues
* **DELETE\_ISSUES**: Delete Jira Issues
* **MODIFY\_REPORTER**: Modify Jira Issue Reporter
* **TRANSITION\_ISSUES**: Transition Jira Issues

## In workflows

This provider can be used in workflows.

As "step" to query data, example:

```yaml theme={null}
steps:
    - name: Query jira
      provider: jira
      config: "{{ provider.my_provider_name }}"
      with:
        ticket_id: {value}  # The ticket id of the issue, optional.
        board_id: {value}  # The board id of the issue.
```

As "action" to make changes or update data, example:

```yaml theme={null}
actions:
    - name: Query jira
      provider: jira
      config: "{{ provider.my_provider_name }}"
      with:
        summary: {value}  # The summary of the issue.
        description: {value}  # The description of the issue.
        issue_type: {value}  # The type of the issue.
        project_key: {value}  # The project key of the issue.
        board_name: {value}  # The board name of the issue.
        issue_id: {value}  # The issue id of the issue.
        labels: {value}  # The labels of the issue.
        components: {value}  # The components of the issue.
        custom_fields: {value}  # The custom fields of the issue.
        transition_to: {value}  # Optional transition name (e.g., "Done", "Resolved") to apply after update/create.
```

Check the following workflow examples:

* [create\_jira\_ticket\_upon\_alerts.yml](https://github.com/keephq/keep/blob/main/examples/workflows/create_jira_ticket_upon_alerts.yml)
* [incident-enrich.yaml](https://github.com/keephq/keep/blob/main/examples/workflows/incident-enrich.yaml)
* [jira-create-ticket-on-alert.yml](https://github.com/keephq/keep/blob/main/examples/workflows/jira-create-ticket-on-alert.yml)
* [jira-transition-on-resolved.yml](https://github.com/keephq/keep/blob/main/examples/workflows/jira-transition-on-resolved.yml)
* [jira\_on\_prem.yml](https://github.com/keephq/keep/blob/main/examples/workflows/jira_on_prem.yml)
* [test\_jira\_create\_with\_custom\_fields.yml](https://github.com/keephq/keep/blob/main/examples/workflows/test_jira_create_with_custom_fields.yml)
* [test\_jira\_custom\_fields\_fix.yml](https://github.com/keephq/keep/blob/main/examples/workflows/test_jira_custom_fields_fix.yml)
* [update\_jira\_ticket.yml](https://github.com/keephq/keep/blob/main/examples/workflows/update_jira_ticket.yml)

## Connecting with the Provider

1. Go to [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) to Create API token and generated token should be passed to jira authentication.
2. Get `host` and `board_id` from your respective board from its URL.
3. Get `project_key` from your project > settings > details.
4. `email` would be same as of your account email.

## Auto-Transition Workflows

The Jira provider supports automatically transitioning tickets when alerts change status. This is useful for keeping your Jira board synchronized with alert states - for example, automatically closing tickets when alerts are resolved.

### Prerequisites

1. Configure a Jira Cloud provider in Keep
2. Ensure your Jira user has the `TRANSITION_ISSUES` permission
3. Know your Jira board name and desired transition status names

### Workflow 1: Create Jira Ticket on Alert

This workflow creates a Jira ticket when an alert fires, but only if no ticket has been created yet.

```yaml theme={null}
workflow:
  id: jira-create-ticket-on-alert
  name: Create Jira Ticket on Alert
  description: Create Jira ticket when alert fires
  disabled: false
  triggers:
    - type: alert
      cel: status == "firing"
  actions:
    - name: jira-action
      if: "not '{{ alert.ticket_id }}'"
      provider:
        type: jira
        config: "{{ providers.JiraCloud }}"
        with:
          board_name: YOUR_BOARD_NAME  # Change this to your board name
          issue_type: Task  # Or Bug, Story, etc.
          summary: "{{ alert.name }} - {{ alert.description }}"
          description: |
            "This ticket was created automatically by Keep.

            Alert Details:
            {code:json}
            {{ alert }}
            {code}"
          enrich_alert:
            - key: ticket_type
              value: jira
            - key: ticket_id
              value: results.issue.key
            - key: ticket_url
              value: results.ticket_url
```

**Key Points:**

* `if: "not '{{ alert.ticket_id }}'"` - Only creates a ticket if one doesn't exist yet
* `enrich_alert` - Stores the ticket ID, type, and URL in the alert for later use
* The ticket is created in the default status (usually "To Do" or "Open")

### Workflow 2: Transition Ticket to Done on Alert Resolved

This workflow updates the existing Jira ticket and transitions it to "Done" when the alert is resolved.

```yaml theme={null}
workflow:
  id: jira-transition-on-resolved
  name: Transition Jira Ticket to Done
  description: Close Jira ticket when alert is resolved
  disabled: false
  triggers:
    - type: alert
      cel: status == "resolved"
  actions:
    - name: jira-action
      provider:
        type: jira
        config: "{{ providers.JiraCloud }}"
        with:
          issue_id: "{{ alert.ticket_id }}"
          summary: "{{ alert.name }} - {{ alert.description }} (resolved)"
          description: |
            "Alert has been resolved automatically by Keep.

            Resolved at: {{ alert.lastReceived }}

            Original Alert Details:
            {code:json}
            {{ alert }}
            {code}"
          transition_to: Done  # Change to your workflow's status name
```

**Key Points:**

* Uses `issue_id: "{{ alert.ticket_id }}"` from the enriched alert data
* `transition_to: Done` - Transitions the ticket to the specified status
* No `if` condition needed - if the alert has no `ticket_id`, the action will simply fail gracefully

### Available Transition Names

Common Jira transition names (varies by workflow):

* `Done`
* `Resolved`
* `Closed`
* `In Progress`
* `To Do`
* `Canceled`

**How to find your transition names:**

1. Go to your Jira project settings
2. Navigate to Workflows
3. Check the available statuses in your workflow
4. Use the exact status name in the `transition_to` parameter (case-insensitive)

### Error Handling

If you specify an invalid transition name, the Jira provider will return a helpful error message listing all available transitions for that ticket:

```
Transition 'Invalid' not found. Available transitions: To Do, In Progress, Done, Closed
```

### Example: Three-State Workflow

You can also create intermediate transitions:

```yaml theme={null}
# Workflow 3: Move to In Progress when acknowledged
workflow:
  id: jira-transition-in-progress
  name: Transition to In Progress
  description: Move ticket to In Progress when alert is acknowledged
  disabled: false
  triggers:
    - type: alert
      cel: status == "acknowledged"
  actions:
    - name: jira-action
      provider:
        type: jira
        config: "{{ providers.JiraCloud }}"
        with:
          issue_id: "{{ alert.ticket_id }}"
          summary: "{{ alert.name }} - In Progress"
          description: "Alert acknowledged and being worked on."
          transition_to: In Progress
```

### Testing

1. **Create an alert** that triggers the first workflow

* Verify a Jira ticket is created
* Check that the alert has `ticket_id`, `ticket_type`, and `ticket_url` fields

2. **Resolve the alert** to trigger the second workflow

* Verify the existing ticket is updated (no new ticket created)
* Check that the ticket status changed to "Done"

3. **Check the logs** in Keep UI for any errors or debugging info

### Troubleshooting

#### Issue: Workflow creates a new ticket instead of updating

**Cause:** The `issue_id` parameter is missing or the alert doesn't have a `ticket_id`.

**Solution:** Ensure the first workflow enriches the alert with `ticket_id` and the second workflow uses it via `issue_id: "{{ alert.ticket_id }}"`.

#### Issue: Transition fails with "Transition 'X' not found"

**Cause:** The transition name doesn't match your Jira workflow.

**Solution:** Check the error message for available transitions and update the `transition_to` parameter accordingly.

#### Issue: Permission denied when transitioning

**Cause:** Your Jira user doesn't have the `TRANSITION_ISSUES` permission.

**Solution:** Grant the necessary permissions in Jira project settings.

### Advanced Features

#### Configuration Variables

You can use Keep's configuration variables to make the workflows more flexible:

```yaml theme={null}
consts:
  JIRA_BOARD: "ALERTS"
  JIRA_DONE_STATUS: "Done"
  JIRA_ISSUE_TYPE: "Task"

# Then use in workflows:
board_name: "{{ consts.JIRA_BOARD }}"
transition_to: "{{ consts.JIRA_DONE_STATUS }}"
issue_type: "{{ consts.JIRA_ISSUE_TYPE }}"
```

#### Custom Fields

You can also set custom fields when creating or updating tickets:

```yaml theme={null}
with:
  issue_id: "{{ alert.ticket_id }}"
  summary: "Alert resolved"
  custom_fields:
    customfield_10001: "High"
    customfield_10002: "Production"
  transition_to: Done
```

#### Labels and Components

```yaml theme={null}
with:
  board_name: YOUR_BOARD_NAME
  summary: "{{ alert.name }}"
  description: "{{ alert.description }}"
  labels:
    - alert
    - automated
    - critical
  components:
    - Monitoring
    - Infrastructure
```

## Notes

## Useful Links

* [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
* [https://developer.atlassian.com/cloud/jira/software/rest/api-group-board/#api-rest-agile-1-0-board-boardid-issue-get](https://developer.atlassian.com/cloud/jira/software/rest/api-group-board/#api-rest-agile-1-0-board-boardid-issue-get)
* [https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-post](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-post)
* [https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-transitions-get](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-transitions-get) (Transitions API)