integration-jira

Integration for JIRA using OAuth 1.0a and REST API with the client.

Table of Contents

• Commands
  • Run
  • Testing
  • Fix formatting
  • Linting
  • Building docs
• Developer Notes
  • Design Decisions
  • Production Setup
  • Development Setup
• API Reference

Commands

Run

Inject integration-jira into the client.

cd integration-jira
npm run start

Testing

Runs ESLint and Mocha tests.

cd integration-jira
npm run test

Linting

Lints all JavaScript using ESLint and Prettier.

cd integration-jira
npm run lint

Fix formatting

Autoformats all JavaScript ESLint/Prettier issues if possible.

cd integration-jira
npm run format

Building docs

This adds/updates this README with the API.

cd integration-jira
npm run docs

Developer Notes

Design Decisions

Syncing

Syncing works by fetching one page of 50 items, sending it to the server, and iterating for 15 iterations or until there aren't any more pages. The number 15 was chosen because it was benchmarked at around 750 ( 15 * 50 per step = ~750 items per type) items per type for a 10 minute sync when running in serial. However, currently it is running in parallel which brings down this sync time quite a bit. This will need to be adjusted in the future when new content types are added.

Production Setup

• Application Name: JIRA
• Icon URL: https://logo.clearbit.com/atlassian.net?s=128
• Integration Type: jira

Content Policies:

Policy 1

• Policy Name: JIRA
• URL Pattern: https://*.jira.com/*
• Content Type: ``
• Allowed Data Sources: Jira, Desktop, Web

Policy 2

• Policy Name: JIRA Issue
• URL Pattern: https://*.atlassian.net/browse/*
• Content Type: jiraIssue
• Allowed Data Sources: Jira

Policy 3

• Policy Name: JIRA Component
• URL Pattern: https://*.atlassian.net/rest/api/*/component/*
• Content Type: jiraComponent
• Allowed Data Sources: Jira

Development Setup

Make sure the following is in rest-server/data/global-apps.

{
    "_index": "app_v2",
    "_type": "App",
    "_id": "AVE7ktoVGz3n-jira",
    "_score": 4.01902,
    "_source": {
        "rootDomain": "atlassian.net",
        "name": "JIRA",
        "title": "JIRA",
        "teamId": "##GLOBAL##",
        "integrationType": "jira",
        "events": "team",
        "contentPolicies": [
            {
                "indexLevel": "team",
                "sources": ["jira"],
                "name": "jira::component",
                "contentType": "jiraComponent",
                "requiredContentActivity": 1,
                "urlPattern": "https://*.atlassian.net/rest/api/*/component/*",
                "title": "JIRA Component",
                "requiredUniqueUsers": 1
            },
            {
                "indexLevel": "team",
                "sources": ["jira"],
                "name": "jira::issue",
                "contentType": "jiraIssue",
                "requiredContentActivity": 1,
                "urlPattern": "https://*.atlassian.net/browse/*",
                "title": "JIRA Issue",
                "requiredUniqueUsers": 1
            },
            {
                "indexLevel": "disable",
                "name": "jira::jira",
                "requiredContentActivity": 1,
                "urlPattern": "https://*.atlassian.net/*",
                "contentType": "",
                "title": "JIRA",
                "requiredUniqueUsers": 1
            }
        ],
        "recommendations": "enable",
        "metrics": { "contentPinCount": 0, "contentHideCount": 0, "eventCount": 0, "contentViewCount": 0, "contentCount": 0 }
    }
}

API Reference

Classes

Connect

Main interface to JIRA connecting.

ContentBuilder

Content builder to map JIRA to the client.

Issue

JIRA Issue handler.

Jira

Main interface to JIRA.

Project

JIRA Project API handler.

Sync

Main interface to JIRA syncing.

Connect

Main interface to JIRA connecting.

Kind: global class

• Connect
  • new Connect(args)
  • .getRequestTokens() ⇒ Object
  • .getAuthorizationUrl() ⇒ Object
  • .updateAccessToken() ⇒ Object
  • .getAccessToken() ⇒ Object

new Connect(args)

connect.getRequestTokens() ⇒ Object

Get OAuth request token and token secret for JIRA.

Kind: instance method of Connect

connect.getAuthorizationUrl() ⇒ Object

Get the OAuth request tokens needed for retrieving the verifier code from JIRA.

Kind: instance method of Connect
Returns: Object - The authorization URL, nonce, and request tokens.

connect.updateAccessToken() ⇒ Object

Updates OAuth access token for JIRA.

A special method is needed because on requesting a new token, the paramter oauth_session_handle is required. The oauth.getOAuthAccessToken function does not allow extra parameters, so this method calls the private method of oauth which allows extra parameters.

Kind: instance method of Connect
Returns: Object - The updated access token metadata.

connect.getAccessToken() ⇒ Object

Gets OAuth access token for JIRA.

Kind: instance method of Connect
Returns: Object - The access token metadata.

ContentBuilder

Content builder to map JIRA to the client.

Kind: global class

• ContentBuilder
  • new ContentBuilder(integration, log, userEmail, hostUrl)
  • .issue(item) ⇒ Object
  • .component(item) ⇒ Object

new ContentBuilder(integration, log, userEmail, hostUrl)

contentBuilder.issue(item) ⇒ Object

Content builder for issues.

Kind: instance method of ContentBuilder
Returns: Object - Content ready for the client.

contentBuilder.component(item) ⇒ Object

Content builder for components.

Kind: instance method of ContentBuilder
Returns: Object - Content ready for the client.

Issue

JIRA Issue handler.

Kind: global class

• Issue
  • new Issue(args)
  • .getIssuesPageByProjectId(projectId, startDate, startAt) ⇒ Object
  • .getIssuesPage(startDate, startAt) ⇒ Object

new Issue(args)

issue.getIssuesPageByProjectId(projectId, startDate, startAt) ⇒ Object

Retrieve a page of issues for a project.

Kind: instance method of Issue
Returns: Object - The issues, pages left, and the end issue count.

issue.getIssuesPage(startDate, startAt) ⇒ Object

Retrieve a page of issues.

Kind: instance method of Issue
Returns: Object - The issues, pages left, and the end issue count.

Jira

Main interface to JIRA.

Kind: global class

• Jira
  • new Jira(args)
  • .connect() ⇒ Object
  • .sync() ⇒ Object

new Jira(args)

jira.connect() ⇒ Object

Handles the routing for the different OAuth cases.

Kind: instance method of Jira
Returns: Object - Error and result.

jira.sync() ⇒ Object

Sync handler for JIRA with the client.

Kind: instance method of Jira
Returns: Object - The new most recent sync timestamps.
Todo

• Add audit delta syncing for components

Project

JIRA Project API handler.

Kind: global class

• Project
  • new Project(args)
  • .getAllProjectIds() ⇒ Array
  • .getProjectComponents(projectIdOrKey) ⇒ Array

new Project(args)

project.getAllProjectIds() ⇒ Array

Retrieve all projects IDs.

Kind: instance method of Project
Returns: Array - Project IDs.

project.getProjectComponents(projectIdOrKey) ⇒ Array

Retrieve all components for a project.

Kind: instance method of Project
Returns: Array - All components for a project.

Sync

Main interface to JIRA syncing.

Kind: global class

• Sync
  • new Sync(args)
  • .sendItemsToServer(items, contentType) ⇒ Array
  • .syncComponents() ⇒ Object
  • .syncIssues(oldMostRecentDateTime) ⇒ Object

new Sync(args)

sync.sendItemsToServer(items, contentType) ⇒ Array

Sends data back to the rest-server.

Kind: instance method of Sync
Returns: Array - All errors while sending items to the server.

sync.syncComponents() ⇒ Object

Sync all components for all projects.

Kind: instance method of Sync
Returns: Object - Errors if any.

sync.syncIssues(oldMostRecentDateTime) ⇒ Object

Sync all issues based on most recent high-watermark.

Kind: instance method of Sync
Returns: Object - Either error or new high-watermark.