> For the complete documentation index, see [llms.txt](https://docs.docontrol.io/docontrol-user-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.docontrol.io/docontrol-user-guide/integrations/jira-software.md).

# Jira Software

Jira Software is a proprietary Atlassian product that's used for issue tracking and agile project management by over 180,000 customers around the world. As an IT service management tool (ITSM), Jira Software manages a wide range of development data, including sensitive information, code and user credentials.

## Use cases

Integrating DoControl with Jira Software enables you to detect and prevent unnecessary exposure and address these use cases:

* **Get event visibility** - View all near real-time events for Jira issues and their entities, such as issue created/updated, and comment created/updated
* **Remediate future data exposure -** Leverage automated security workflows, such as notify if PII is detected in Jira issues and entities, delete encryption files from Jira issues, delete issues or entities

{% hint style="info" %}
**For example**: If a Jira user in your organization shares a password in the issue description or in a comment, you can receive notification in near real-time and take appropriate action.
{% endhint %}

## Prerequisites

Before integrating DoControl with Jira Software, make sure that:

* The integrator has one of these [Jira admin privileges](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro#permissions):
  * Administer the Cloud site OR
  * Administer Jira
* Verify that your Jira plan is approved to install OAuth applications.

## Jira permissions

The user who performs the DoControl-Jira integration, must have these Jira permissions:

* **Read** permission
* **Write** permission (required for remediations)
* **Delete** permission for issues, comments and attachments (required for remediations)

{% hint style="danger" %}
Think carefully about which groups or project administrators you assign **Delete** permission to; usually it's only given to administrators. 
{% endhint %}

## Delete permissions

You need to assign different Jira permissions to delete entire issues, comments or attachments. These permissions must be assigned to the person who performed the DoControl-Jira integration. 

<table><thead><tr><th width="203.66666666666666">Jira permission</th><th>Scope</th><th>Path in Jira</th></tr></thead><tbody><tr><td>Delete issues</td><td>Permission to delete an entire issue, including all its comments and attachments, even if the user does not have the Delete all comments or Delete all attachments permission</td><td>Jira settings > Issues > Permissions schema > Default permission schema > Delete issue > Update > Single user and enter the DoControl integration owner email</td></tr><tr><td>Delete all comments</td><td>Permission to delete any individual comments, regardless of who added them</td><td>Jira settings > Issues > Permissions schema > Default permission schema > Delete comment > Update > Single user and enter the DoControl integration owner email</td></tr><tr><td>Delete all attachments</td><td>Permission to delete any individual attachments, regardless of who added them<br></td><td>Jira settings > Issues > Permissions schema > Default permission schema > Delete attachment > Update > Single user and enter the DoControl integration owner email</td></tr></tbody></table>

{% hint style="info" %}
For more information, see [Jira support](https://support.atlassian.com/jira-cloud-administration/docs/permissions-for-company-managed-projects/) and [managing project permissions](https://confluence.atlassian.com/jira064/managing-project-permissions-720412504.html).
{% endhint %}

## DoControl application scopes

DoControl requires the following scopes to work with Jira. DoControl also leverages these API calls:&#x20;

<table><thead><tr><th>Scope</th><th width="235.33333333333331">Permission name and API</th><th>OAuth 2.0 scopes</th></tr></thead><tbody><tr><td>Returns the details for an issue </td><td><a href="https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get">Get issue</a></td><td><code>read:jira-work</code> </td></tr><tr><td>Deletes an issue</td><td><a href="https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-delete">Delete issue</a></td><td><code>write:jira-work</code> </td></tr><tr><td>Returns details of projects, issue types within projects, and, when requested, the create screen fields for each issue type for the user. Use the information to populate the requests in <a href="https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post">Create issue </a>and <a href="https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-bulk-post">Create bulk issues</a></td><td><a href="https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-createmeta-get">Get create issue metadata</a></td><td><code>read:jira-work</code> </td></tr><tr><td>Returns the contents of an attachment</td><td><a href="https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-attachments/#api-rest-api-3-attachment-content-id-get">Get attachment content</a></td><td><code>read:jira-work</code> </td></tr><tr><td>Deletes an attachment from an issue</td><td><a href="https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-attachments/#api-rest-api-3-attachment-id-delete">Delete attachment</a></td><td><code>write:jira-work</code></td></tr><tr><td>Returns a comment</td><td><a href="https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-comments/#api-rest-api-3-issue-issueidorkey-comment-id-get">Get comment</a></td><td><code>read:jira-work</code> </td></tr><tr><td>Deletes a comment</td><td><a href="https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-comments/#api-rest-api-3-issue-issueidorkey-comment-id-delete">Delete comment</a></td><td><code>write:jira-work</code></td></tr></tbody></table>

## **Webhook events**&#x20;

A webhook is a user-defined callback over HTTPS. You can use Jira webhooks to notify DoControl when certain [events](https://developer.atlassian.com/cloud/jira/platform/webhooks/#registering-a-webhook-using-the-rest-api--for-connect-and-oauth-2-0-apps-) occur in Jira.&#x20;

For example, you can alert DoControl when an issue has been created or updated. Using a webhook means that DoControl doesn't have to periodically poll Jira (via the REST APIs) to determine whether changes have occurred.

### Issue webhooks

created (`jira:issue_created`)

updated (`jira:issue_updated`)

deleted (`jira:issue_deleted`)

### Comment webhooks

created (`comment_created`)

updated (`comment_updated`)

## Integrate Jira Software with DoControl

To integrate Jira Software with DoControl, make sure you've fulfilled all the [prerequisites](#prerequisites).

<div align="left"><figure><img src="https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2FAAzYqbofgb5OpXXgHgw3%2FJIRA%20integrate.png?alt=media&amp;token=860077b4-e8ba-46a2-855e-32aaa5032779" alt=""><figcaption></figcaption></figure></div>

1. From the DoControl side menu, click **Integrations**.
2. Under the Jira icon, click **Connect**. The Connect to Jira wizard opens.
3. Click **Let's go**, and follow the instructions in the wizard.
4. Click **Allow** to grant DoControl access permissions.&#x20;
5. Select which Jira sites DoControl should retrieve information from. When finished, the wizard indicates that Jira is connected.

{% hint style="success" %}
To learn how DoControl can detect PII in Jira assets, see [Jira PII scan](/docontrol-user-guide/workflows/define-workflow-settings/action-settings/query/pii-scan.md#jira-pii-scan).
{% endhint %}

## Troubleshooting

Q. What happens if my Jira token expires?

A. Jira tokens are valid for a maximum of **1 year**. Your Jira token will expire after 1 year, or after the person who performed the integration leaves your organization. After your token expires, you need to reconnect to DoControl by performing the [integration procedure](#integrate-jira-software-with-docontrol) again.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.docontrol.io/docontrol-user-guide/integrations/jira-software.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.