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.

Kind: global class

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

new Connect(args)

| Param | Type | Description | | --- | --- | --- | | args | Object | Arguments for the JIRA interface. | | args.log | Nexd | The logger to use. | | args.hostUrl | String | The user defined host URL. | | args.userEmail | Object | The client user email. | | args.userSettings | Object | JIRA integration user settings being used. | | args.oauthInstance | OAuth | OAuth instance to use. |

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)

| Param | Type | Description | | --- | --- | --- | | integration | Object | The integration details. | | log | Nexd | The logger to use. | | userEmail | Object | The current client user email. | | hostUrl | String | The host URL for JIRA. |

contentBuilder.issue(item) ⇒ Object

Content builder for issues.

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

| Param | Type | Description | | --- | --- | --- | | item | Object | The issue item. |

contentBuilder.component(item) ⇒ Object

Content builder for components.

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

| Param | Type | Description | | --- | --- | --- | | item | Object | The component item. |

Issue

JIRA Issue handler.

Kind: global class

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

new Issue(args)

| Param | Type | Description | | --- | --- | --- | | args | Object | Arguments for the class. | | args.userEmail | String | The user's email. | | args.maxResults | Integer | The maximum number of results per page. | | args.jiraInstance | JiraClient | The JIRA client instance. | | args.log | Nexd | The logger to use. |

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.

| Param | Type | Default | Description | | --- | --- | --- | --- | | projectId | String | | The project ID for the issues. | | startDate | String | | The farthest back date to retrieve. | | startAt | Integer | 0 | The count of which item in the pages to start at. |

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.

| Param | Type | Default | Description | | --- | --- | --- | --- | | startDate | String | | The farthest back date to retrieve. | | startAt | Integer | 0 | The count of which item in the pages to start at. |

Jira

Main interface to JIRA.

Kind: global class

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

new Jira(args)

| Param | Type | Description | | --- | --- | --- | | args | Object | Arguments for the JIRA interface. | | args.userEmail | Object | The client user email. | | args.serviceToken | String | Client's token for JIRA. | | args.integration | Object | JIRA integration being used. | | args.syncOptions | Object | Client sync options. | | args.log | Nexd | The logger to use. |

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)

| Param | Type | Description | | --- | --- | --- | | args | Object | Arguments for the class. | | args.userEmail | String | The user's email. | | args.jiraInstance | JiraClient | The JIRA client instance. | | args.log | Nexd | The logger to use. |

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.

| Param | Type | Description | | --- | --- | --- | | projectIdOrKey | String | The project to get components for. |

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)

| Param | Type | Description | | --- | --- | --- | | args | Object | Arguments for the JIRA interface. | | args.log | Nexd | The logger to use. | | args.hostUrl | String | The user defined host URL. | | args.userEmail | Object | The client user email. | | args.jiraInstance | Jira | JIRA library instance to use. | | args.integration | Object | JIRA integration being used. | | args.nexdClient | Nexd | Nexd SDK library instance to use. | | args.maxMonthsToSync | Integer | The maximum number to sync. | | args.maxResults | Integer | Maximum results per page. | | args.maxPages | Integer | Maximum number of pages to sync per type. |

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.

| Param | Type | Description | | --- | --- | --- | | items | Array | Items returned during sync. | | contentType | String | The content type of items to send. |

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.

| Param | Type | Description | | --- | --- | --- | | oldMostRecentDateTime | String | The previous high-watermark. |