# Jira Service Desk Connector

## Overview

This document provides comprehensive instructions on setting up the integration and configuring data sources for seamless integration with Jira Service Desk.

## Prepare

### Authentication

The Jira Service Desk supports two forms of authentication. **OAuth 2.0** and **Basic**. 

#### OAuth 2.0

The Jira Service Desk connector supports **OAuth 2.0** as an authentication type. You will need to create an application on the Atlassian platform. The credentials obtained from this application will be used for authenticating with and connecting the Aisera platform to your Jira Service Desk.

To create an application on the Atlassian platform, follow the Atlassian documentation on [Enabling OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#enabling-oauth-2-0--3lo-).

When setting the callback URL, use your Aisera vanity URL for OAuth 2.0 authentication. This will look like `https://<tenant>.login.aisera.<top_level_domain>/?id=aisera.oauth.oauthCommand`.

You will also need to give the following permissions to the application for the Jira Service Desk connector to function:

* `read:jira-work`
* `write:jira-work`
* `read:servicedesk-request`
* `write:servicedesk-request`

Take note of the **Client Id** and **Client** **Secret** provided by the new application.

You will need to construct the endpoint for your Jira Service Desk by [getting the cloud id for your site](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#3-1-get-the-cloudid-for-your-site). Once you have acquired your **Cloud Id**, the endpoint URL will look like: `https://api.atlassian.com/ex/jira/<cloud_id>`.

An authorization URL containing the necessary scopes for each API call will need to be provided for the connector. The standard URL for this is:

{% code overflow="wrap" %}

```url
https://auth.atlassian.com/authorize?audience=api.atlassian.com&scope=offline_access%20read%3Ajira-user%20read%3Ajira-work%20manage%3Ajira-project%20manage%3Ajira-configuration%20write%3Ajira-work%20read%3Aservicedesk-request%20write%3Aservicedesk-request&prompt=consent
```

{% endcode %}

The required information for this form of authentication is:

<table><thead><tr><th width="207.5999755859375">Field</th><th>Description</th></tr></thead><tbody><tr><td>Access Token URL</td><td><code>https://auth.atlassian.com/oauth/token</code></td></tr><tr><td>Authorization URL</td><td>An authorization URL containing the necessary scopes for each API call the connector will make. This URL is provided above.</td></tr><tr><td>Client Id</td><td>The <strong>Client Id</strong> for the application created on the Atlassian Platform</td></tr><tr><td>Client Secret</td><td>The <strong>Client Secret</strong> for the application created on the Atlassian Platform</td></tr><tr><td>Endpoint</td><td>The endpoint constructed using your Atlassian <strong>Cloud Id</strong>. This will look like <code>https://api.atlassian.com/ex/jira/&#x3C;cloud_id></code></td></tr></tbody></table>

#### Basic

The Basic Authentication method uses an account username and API key for authentication. You will need to generate an API key. Go to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) to create an API token. To learn more about these tokens, go to the [Manage API tokens for your Atlassian account](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) page.

The required information for this form of authentication is:

<table><thead><tr><th width="207.5999755859375">Field</th><th>Description</th></tr></thead><tbody><tr><td>Username</td><td>The Username of the account used to generate the API token</td></tr><tr><td>Password</td><td>The API token generated on the Atlassian platform</td></tr><tr><td>Endpoint</td><td>The base URL for your Atlassian site. This will look like <code>https://&#x3C;your_company>.atlassian.net</code></td></tr></tbody></table>

{% hint style="danger" %}
Be sure to keep your API token secure as it provides access to your Jira Service Desk data.
{% endhint %}

### Service Desk Id

You will need the **Service Desk Id** for your Jira Service Desk Project. To locate this information follow the instructions on [Atlassian Support](https://support.atlassian.com/jira/kb/find-the-service-desk-id-for-your-jira-service-management-cloud-project/).

## Integration Setup

1. In the Aisera Admin UI navigate to **Settings > Integrations**

2. Click on **+ New Integration**

3. In the menu, select **Jira Service Desk** and click **Next**

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FXrFseCLQEnRkgzAmVvpY%2Fimage.png?alt=media&#x26;token=e1f127b4-1df0-4e98-8118-d5d3626e328c" alt=""><figcaption></figcaption></figure></div>

4. Enter the configuration details and select **Next**

   <table><thead><tr><th width="140">Field</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>The name used to identify the integration</td></tr><tr><td>Description</td><td>A description of the integration and it's purpose</td></tr><tr><td>Endpoint</td><td>The <strong>Endpoint</strong> used for the Authentication type selected during the Prepare step.</td></tr></tbody></table>

5. On the **Step 3: Authentication** screen, select the prepared **Auth Type** from the dropdown and enter the credentials gathered during the Prepare step

6. Select **Ok** to save the integration

## Data Source Setup

1. In the Aisera Admin UI navigate to **Settings > Data Sources**
2. Click **+ New Data Source** in the upper right corner
3. Select **Jira Service Desk** and click **Next**
4. The required fields will vary based on the selected functions. Enter the general details and select **Next**

   <table><thead><tr><th width="200">Field</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>The name used to identify your Data Source</td></tr><tr><td>Functions</td><td>Functions dictate how a data source behaves and what data is ingested into the Aisera platform</td></tr><tr><td>Integration</td><td>The integration with the necessary authentication information for data retrieval</td></tr><tr><td>Schedule</td><td>This determines how often the Data Source will request new data</td></tr><tr><td>Description</td><td>A description of the integration and it's purpose</td></tr></tbody></table>
5. Choose the projects to be ingested in the **Projects** field.

   <div data-gb-custom-block data-tag="hint" data-style="danger" class="hint hint-danger"><p>If a list under <strong>Projects</strong> does not automatically populate, it means that the <strong>Integration</strong> step has failed or has not been configured properly.</p><ul><li>Check that your integration has been properly set up, and that the credentials are correct.</li><li>Because each user environment is different, you may need to increase the permissions for the Aisera Platform to properly detect the spaces.</li><li>If trouble persists, contact your Aisera representative for further help.</li></ul></div>
6. Enter the **Service Desk Id** you obtained during the prepare step.
7. All remaining configurations are optional. See the **Optional Configurations** section below for more information. Click **Next** until the window closes to complete the creation of the **Data Source**

## Optional Configurations

### Remote Executor

This indicates whether or not a Remote Executor will be used with this data source. The Remote Executor is used to execute commands on and ingest data from On Premises installations of your enterprise software. Refer to documentation on the [Remote Executor](https://docs.aisera.com/aisera-platform/adding-data-to-your-tenant/integrations-and-data-sources/remote-executor) for more information.

### Custom Script

This configuration allows for the transformation of data as it is being ingesting into the Aisera Platform. This includes, adding, editing, or removing fields from the ingested content. For use of this feature, reach out to Aisera for help creating, testing, and implementing these scripts.

### Bypass Test Connection

Disable if you want to bypass the test connection. This is not recommended.

### Use Deprecated JQL Search

If you prefer to use the deprecated Jira JQL Search to retrieve **Ticket** data from a Jira data source, you can enable the **Use Deprecated JQL Search** option.

### Custom Query

This field allows for the entry of a custom query to Jira. This is written using Jira Query Language (JQL). This field overrides all parts of the default Jira query except for the project.

## Post Setup Actions

### Data Ingestion

After you've successfully set up your connector, your data will automatically sync according to the schedule settings or on demand, as specified during the Data Source Configuration step. However, you should perform a manual sync immediately. This initial run will serve two key purposes:

After setting up your connector, your data will sync automatically based on your schedule parameters, or you can choose the "on demand" configuration to sync data only when requested.

1. It confirms the connector is working properly.
2. It provides an immediate view of the information being ingested into the Aisera Application, allowing you to validate and begin working with the data.

To manually ingest data:

1. In the Aisera Admin UI navigate to **Settings > Data Sources.**<br>

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FUIsDFUfemqsV7ML86iHS%2FDataIngestion-DataSourceWindow.png?alt=media&#x26;token=c41635bd-16b9-4b13-b35b-84705fa26309" alt=""><figcaption><p>Data Sources Window</p></figcaption></figure></div>
2. **Click** on the **Data Source** you wish to manually ingest data from.
3. At the top right of the **Data Source Details** page, click the **Play** button to manually ingest data.<br>

   <figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FWOAAURoDxlvnQcfI7gws%2FDataIngestion-DataSourceDetailsWindow.png?alt=media&#x26;token=41069e6a-e0be-4924-a9b2-41aae8fb5d43" alt=""><figcaption><p>Data Source Window</p></figcaption></figure>

All the ingested tickets are available under the **Tickets** tab. Click on the **SOR > Tickets** to view the ingested Tickets.