Jira Integration Documentation

Overview

The Jira Integration for Vantage provides seamless connectivity with Jira's REST API v3, enabling users to manage and manipulate Jira issues, projects, and user authentication easily. This integration leverages OAuth 2.0 for secure authentication and allows for operations such as fetching accessible projects, creating and updating issues, and executing complex searches using Jira Query Language (JQL).

Settings

The Jira Integration comes with a variety of settings to configure its behavior and interactions with the Jira API. Each setting is explained in detail below.

1. encryptedRecord

• Input Type: Object
• Description: Contains encrypted user credentials and configuration information necessary for authenticating with the Jira API.
• Default Value: Not applicable; this setting must be provided during instantiation.

2. serviceId

• Input Type: String
• Description: This identifier is tied to the specific instance of the integration. It is used to track the service in the Vantage system.
• Default Value: Not applicable; this setting must be provided during instantiation.

3. clientId

• Input Type: String
• Description: The client identifier for OAuth 2.0 authentication required to access the Jira resources.
• Default Value: Not applicable; this setting must be provided during instantiation.

4. credentialId

• Input Type: String
• Description: A unique identifier used to reference user credentials stored in the database. This ID is crucial for updating and retrieving user-specific access tokens.
• Default Value: Not applicable; this setting must be provided during instantiation.

5. accessToken

• Input Type: String
• Description: The current OAuth access token used to authenticate requests to the Jira API. This token expires after a defined period and can be refreshed as needed.
• Default Value: null (initialized upon authentication).

6. tokenExpiry

• Input Type: Date
• Description: A timestamp indicating when the current access token will expire. This allows the integration to preemptively refresh the token before it is used.
• Default Value: null (initialized upon authentication).

7. cloudId

• Input Type: String
• Description: A unique identifier for the Jira Cloud instance being accessed. It is required for constructing API URLs for requests to that specific instance.
• Default Value: null (resolved after the first API request for accessible resources).

8. retryAfter

• Input Type: Numeric
• Description: This indicates how long (in seconds) the system should wait before making another request after receiving a rate limit error (HTTP status 429) from the API.
• Default Value: 60 seconds.

How It Works

The Jira Integration processes interactions with Jira through the following main functions:

1. Authentication: It uses OAuth 2.0 for authentication, managing access and refresh tokens as required.
2. Cloud ID Resolution: It resolves the Jira Cloud ID needed to construct subsequent API requests by querying the "accessible-resources" endpoint after obtaining the access token.
3. API Requests: All requests are authorized with the current access token. If the token is expired or not valid, the system will attempt to refresh it.
4. Error Handling: The integration implements error handling for various HTTP statuses, including retries on rate limiting (HTTP 429) and token expiration (HTTP 401) using appropriate fallback processes.

Data Expectations

The Jira Integration expects various data formats depending on the API endpoints being interacted with:

• Projects: Requests for projects expect string query parameters for pagination (e.g., maxResults and startAt).
• Issues: When creating or updating issues, the following fields must be supplied:
  • projectKey: (Required) The identifier for the Jira project.
  • issueType: Type of the issue (e.g., Bug, Task, Story).
  • summary: (Required) A concise title of the issue.
  • description: The detailed description formatted as Atlassian Document Format (ADF).
  • priority, labels, and assigneeAccountId: Additional attributes for richer issue detail.

Use Cases & Examples

Use Cases

1. Automated Bug Tracking: An organization can automate the creation and updating of bug tickets in Jira based on the results of automated testing or continuous integration.
2. Project Management: Users can integrate their project management tools with Jira to keep track of task assignments and overall project statuses.
3. Data Visualization: Data professionals can pull issue data from Jira into Vantage for analysis, enabling visualization of issue trends and project timelines.

Example Configuration

Use Case: Automated Bug Reporting

Imaging a software development team utilizes Vantage to automatically report bugs discovered during automated testing. Here’s how the integration might be configured:

{
  "encryptedRecord": {
    "accessToken": "sample_access_token",
    "refreshToken": "sample_refresh_token",
    "cloudId": null,
    "tokenExpiry": null
  },
  "serviceId": "jira_service_001",
  "clientId": "your_client_id_here",
  "credentialId": "credential_123456"
}

In this scenario, the integration initializes with the necessary credentials and sets up the environment to make API calls. When a bug is discovered, a function calling createIssue would transform the test results into a Jira issue like this:

await jiraIntegration.createIssue({
    projectKey: 'DEV',
    issueType: 'Bug',
    summary: 'Automated Test Failure in Feature X',
    description: 'Automated tests for Feature X failed due to ...',
    priority: 'High',
    labels: ['automation', 'bug', 'testing'],
    assigneeAccountId: 'jira_account_id_of_dev'
});

This configuration allows the team to dynamically report issues as they arise, integrating seamlessly with their existing Jira setup.

AI Integrations

Currently, the Jira Integration does not have direct AI functionalities; however, it can be extended to interact with AI models for predictive maintenance, trend analysis, and ticket classification if required in the future.

Billing Impacts

The use of the Jira Integration may result in API request costs depending on your Jira subscription plan. Organizations should review their plan with Atlassian to understand API limits and associated costs, especially if a high volume of requests is anticipated. Additionally, performance impacts related to token management may affect system resource utilization, which could have billing implications in the context of usage within Vantage.