integration-jira v1.0.0
integration-jira
Integration for JIRA using OAuth 1.0a and REST API with the client.
Table of Contents
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
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
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
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. |
6 years ago