# Connecting to Jira Cloud
Jira Cloud is a platform developed by Atlassian. The platform includes issue tracking products that help teams plan and track their Agile projects. As a Jira Cloud user, your account contains data about your projects, such as issues, workflows, and events. You can use AWS Glue to transfer your Jira Cloud data to certain AWS services or other supported applications.
**Topics**
+ [AWS Glue support for Jira Cloud](jira-cloud-support.md)
+ [Policies containing the API operations for creating and using connections](jira-cloud-configuring-iam-permissions.md)
+ [Configuring Jira Cloud](jira-cloud-configuring.md)
+ [Configuring Jira Cloud connections](jira-cloud-configuring-connections.md)
+ [Reading from Jira Cloud entities](jira-cloud-reading-from-entities.md)
+ [Jira Cloud connection options](jira-cloud-connection-options.md)
+ [Limitations and notes for Jira Cloud connector](jira-cloud-connector-limitations.md)
# AWS Glue support for Jira Cloud
AWS Glue supports Jira Cloud as follows:
**Supported as a source?**
Yes. You can use AWS Glue ETL jobs to query data from Jira Cloud.
**Supported as a target?**
No.
**Supported Jira Cloud API versions**
The following Jira Cloud API versions are supported:
+ v3
For entity support per version specific, see [Reading from Jira Cloud entities](jira-cloud-reading-from-entities.md).
# Policies containing the API operations for creating and using connections
The following sample policy describes the required AWS IAM permissions for creating and using connections. If you are creating a new role, create a policy that contains the following:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:ListConnectionTypes",
"glue:DescribeConnectionType",
"glue:RefreshOAuth2Tokens",
"glue:ListEntities",
"glue:DescribeEntity"
],
"Resource": "*"
}
]
}
```
------
If you don't want to use the above method, alternatively use the following managed IAM policies:
+ [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – Grants access to resources that various AWS Glue processes require to run on your behalf. These resources include AWS Glue, Amazon S3, IAM, CloudWatch Logs, and Amazon EC2. If you follow the naming convention for resources specified in this policy, AWS Glue processes have the required permissions. This policy is typically attached to roles specified when defining crawlers, jobs, and development endpoints.
+ [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) – Grants full access to AWS Glue resources when an identity that the policy is attached to uses the AWS Management Console. If you follow the naming convention for resources specified in this policy, users have full console capabilities. This policy is typically attached to users of the AWS Glue console.
# Configuring Jira Cloud
Before you can use AWS Glue to transfer data from Jira Cloud to supported destinations, you must meet these requirements:
## Minimum requirements
The following are minimum requirements:
+ You have an Atlassian account where you use the Jira software product in Jira Cloud. For more information, see [Creating a Jira Cloud account](#jira-cloud-configuring-creating-jira-cloud-account).
+ You must have an AWS account created with the service access to AWS Glue.
+ This app provides the client credentials that AWS Glue uses to access your data securely when it makes authenticated calls to your account. For more information, see [Enabling OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#enabling-oauth-2-0--3lo-) in the Atlassian Developer documentation.
If you meet these requirements, you’re ready to connect AWS Glue to your Jira Cloud account.
## Creating a Jira Cloud account
To create a Jira Cloud account:
1. Navigate to the [Atlassian sign up URL](https://id.atlassian.com/signup).
1. Enter your work email and name and choose **Agree**. You receive a verification email.
1. After verifying your email, you can create a password and choose **Sign up**.
1. Enter name and password, and choose **Sign up**.
1. You are redirected to a page where you need to enter your site. Enter a site name and choose **Agree**.
Once your Atlassian Cloud site starts up, you can set up your Jira by answering a few questions as per your project type preferences.
To log in to an existing account:
1. Navigate to the [Atlassian login URL](https://id.atlassian.com/login) and enter credentials.
1. Enter email and password and click **Log in**. You are redirected to the Jira dashboard.
## Creating an app in your Jira Cloud
To create an app in Jira Cloud and obtain the Client ID and Client Secret from the managed client app:
1. Navigate to the [Jira Cloud URL](https://id.atlassian.com/login) and enter credentials.
1. Choose **Create** and select the **OAuth 2.0 integration** option.
1. Enter the app name, check **T&C** and choose **Create**.
1. Navigate to the **Distribution** section in the left menu and choose **Edit**.
1. In the **Edit distribution controls** section:
1. Select **DISTRIBUTION STATUS** as **Sharing**.
1. Enter the vendor name.
1. Enter the URL for your **Privacy policy**. For example, https://docs.aws.amazon.com/glue/latest/dg/security-iam-awsmanpol.html
1. Enter the URL for your **Terms of service** (optional).
1. Enter the URL for your **Customer support contact** (optional).
1. Select Yes/No from the **PERSONAL DATA DECLARATION** and choose **Save changes**.
1. Navigate to **Permissions** in the left menu for the respective app.
1. For **Jira API**, choose **Add**. Once added, choose the **Configuration** option.
1. Under the **Classic scopes** > **Jira platform REST API** section choose **Edit Scopes**. and check all scopes. Click **Save**.
1. Under **Granular Scopes** choose **Edit Scopes** and select the following scopes:
1. Scroll down and find scopes. There are two kinds of scopes you must select under headings "CRM" and "Standard".
1. Add the following scopes:
```
read:application-role:jira
read:audit-log:jira
read:avatar:jira
read:field:jira
read:group:jira
read:instance-configuration:jira
read:issue-details:jira
read:issue-event:jira
read:issue-link-type:jira
read:issue-meta:jira
read:issue-security-level:jira
read:issue-security-scheme:jira
read:issue-type-scheme:jira
read:issue-type-screen-scheme:jira
read:issue-type:jira
read:issue.time-tracking:jira
read:label:jira
read:notification-scheme:jira
read:permission:jira
read:priority:jira
read:project:jira
read:project-category:jira
read:project-role:jira
read:project-type:jira
read:project-version:jira
read:project.component:jir
read:project.property:jira
read:resolution:jira
read:screen:jira
read:status:jira
read:user:jira
read:workflow-scheme:jira
read:workflow:jira
read:field-configuration:jira
read:issue-type-hierarchy:jira
read:webhook:jira
```
1. Navigate to **Authentication** in the left menu and choose **Add**.
1. Enter a **Callback URL** such as https://us-east-1.console.aws.amazon.com/gluestudio/oauth
1. Navigate to **Settings** in the left menu and scroll down for **Authentication** details. Note the Client ID and Secret.
# Configuring Jira Cloud connections
Jira Cloud supports the AUTHORIZATION\$1CODE grant type for OAuth2.
+ This grant type is considered "three-legged" OAuth as it relies on redirecting users to a third-party authorization server to authenticate the user. It is used when creating connections via the AWS Glue console. The AWS Glue console will redirect the user to Jira Cloud where the user must login and allow AWS Glue the requested permissions to access their Jira Cloud instance.
+ Users may still opt to create their own connected app in Jira Cloud and provide their own client ID and client secret when creating connections through the AWS Glue console. In this scenario, they will still be redirected to Jira Cloud to login and authorize AWS Glue to access their resources.
+ This grant type results in a refresh token and access token. The access token is short lived, and may be refreshed automatically without user interaction using the refresh token.
+ For public Jira Cloud documentation on creating a connected app for Authorization Code OAuth flow, see [Enabling OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#enabling-oauth-2-0--3lo-).
To configure a Jira Cloud connection:
1. In AWS Secrets Manager, create a secret with the following details:
1. For the customer managed connected app, the Secret should contain the connected app Consumer Secret with `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` as key.
1. Note: You must create a secret for the connection in AWS Glue.
1. In AWS Glue Glue Studio, create a connection under **Data Connections** by following the steps below:
1. When selecting a **Connection type**, select Jira Cloud.
1. Provide the Jira Cloud environment.
1. Select the AWS IAM role which AWS Glue can assume and has permissions for following actions:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
------
1. Select the `secretName` which you want to use for this connection in AWS Glue to put the tokens.
1. Select the network options if you want to use your network.
1. Grant the IAM role associated with your AWS Glue job permission to read `secretName`.
# Reading from Jira Cloud entities
**Prerequisite**
A Jira Cloud object you would like to read from. You will need the object name such as Audit Record or Issue. The following table shows the supported entities.
**Supported entities for source**:
| Entity | Can be filtered | Supports limit | Supports Order by | Supports Select \$1 | Supports partitioning |
| --- | --- | --- | --- | --- | --- |
| Audit Record | Yes | Yes | No | Yes | Yes |
| Issue | Yes | Yes | No | Yes | Yes |
| Issue Field | No | No | No | Yes | No |
| Issue Field Configuration | Yes | Yes | No | Yes | Yes |
| Issue Link Type | No | No | No | Yes | No |
| Issue Notification Scheme | Yes | Yes | No | Yes | Yes |
| Issue Security Scheme | No | No | No | Yes | No |
| Issue Type Scheme | Yes | Yes | Yes | Yes | Yes |
| Issue Type Screen Scheme | Yes | Yes | Yes | Yes | Yes |
| Issue Type | No | No | No | Yes | No |
| Jira Setting | Yes | No | No | Yes | No |
| Jira Setting Advanced | No | No | No | Yes | No |
| Jira Setting Global | No | No | No | Yes | No |
| Label | No | No | No | Yes | Yes |
| Myself | Yes | No | No | Yes | No |
| Permission | No | No | No | Yes | No. |
| Project | Yes | Yes | Yes | Yes | Yes |
| Project Category | No | No | No | Yes | No |
| Project Type | No | No | No | Yes | No |
| Server Info | No | No | No | Yes | No |
| Users | No | No | No. | Yes | No |
| Workflow | Yes | Yes | Yes | Yes | Yes |
| Workflow Scheme | No | Yes | No | Yes | Yes |
| Workflow Scheme Project Association | Yes | No | No | Yes | No |
| Workflow Status | No | No | No | Yes | No |
| Workflow Status Category | No | No | No | Yes | No |
**Example**:
```
jiracloud_read = glueContext.create_dynamic_frame.from_options(
connection_type="JiraCloud",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "audit-record",
"API_VERSION": "v3"
}
```
**Jira Cloud entity and field details**:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/glue/latest/dg/jira-cloud-reading-from-entities.html)
## Partitioning queries
You can provide the additional Spark option `NUM_PARTITIONS` if you want to utilize concurrency in Spark. With this parameter, the original query would be split into `NUM_PARTITIONS` number of sub-queries that can be executed by Spark tasks concurrently.
+ `NUM_PARTITIONS`: the number of partitions.
Example:
```
jiraCloud_read = glueContext.create_dynamic_frame.from_options(
connection_type="JiraCloud",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "issue",
"API_VERSION": "v3",
"NUM_PARTITIONS": "10"
}
```
# Jira Cloud connection options
The following are connection options for Jira Cloud:
+ `ENTITY_NAME`(String) - (Required) Used for Read. The name of your object in Jira Cloud.
+ `API_VERSION`(String) - (Required) Used for Read. Jira Cloud Rest API version you want to use. For example: v3.
+ `DOMAIN_URL`(String) - (Required) The Jira Cloud ID you want to use.
+ `SELECTED_FIELDS`(List) - Default: empty(SELECT \$1). Used for Read. Columns you want to select for the object.
+ `FILTER_PREDICATE`(String) - Default: empty. Used for Read. It should be in the Spark SQL format.
+ `QUERY`(String) - Default: empty. Used for Read. Full Spark SQL query.
+ `NUM_PARTITIONS`(Integer) - Default: 1. Used for Read. Number of partitions for read.
# Limitations and notes for Jira Cloud connector
The following are limitations or notes for the Jira Cloud connector:
+ The `Contains` operator does not work with the `resourceName` field, which is of `String` data type.
+ By default, if no explicit filter is applied, only issues from the past 30 days will be crawled. Users have the option to override this default filter by specifying a custom filter.