Skip to main content

Jira Component

Manage Jira issues, comments, projects and users

Component key: atlassian-jira

Description

Jira is a proprietary issue tracking product developed by Atlassian that allows bug tracking and agile project management. This component allows you to create, update, comment on, and delete issues in a Jira project.

API Documentation: JIRA API Documentation

Connections

Jira Basic Connection

If you select Basic Auth and you are using Jira Cloud, you will need to supply your Jira email and an API token to the connection. If you are on a locally hosted instance of Jira, you will need to supply your Jira email and password to the connection. For information on generating an API token from Jira Cloud, refer to the Atlassian docs.

Jira OAuth 2.0 Connection

While Jira's Cloud API has support for legacy OAuth 1.0, Prismatic only offers support for Jira's OAuth 2.0 (3LO) flows. If you select OAuth 2.0, you need to enable it for your app using the Atlassian developer console.

Create a new "Oauth 2.0 integration" and give it a name. Under the app details section, take note of your client Id and client secret values that were generated. After you have saved those values, find the Authorization section and click configure on Oauth 2.0 (3LO). There you will be prompted to enter your redirect URL, which you can find under the credentials tab in the Prismatic settings. - https://oauth2.prismatic.io/callback - as a Redirect URL. Next navigate to the permissions. It is important that you remain consistent with the scopes you supply in both Jira, and your Prismatic connection. The default scopes on a new connection in Prismatic will be as follows: read:project:jira read:user:jira write:issue:jira read:issue:jira read:issue-link:jira write:issue-link:jira read:issue-link-type:jira write:issue-link-type:jira read:issue.transition:jira delete:issue:jira These scopes will provide access to the most of the actions in the Jira component, but you may have to modify the scopes in both locations (Prismatic and Atlassian Console) to meet your needs.

For more information on developing Jira applications, follow the guide here.

Next, you can configure an OAuth 2.0 connection within Prismatic. Add a Jira step to your integration. This will automatically create a Jira connection config variable. Ensure the connection is of type Jira OAuth 2.0 Connection and enter the following details:

  • For Client ID and Client Secret enter the values that you got from the Atlassian Developer Console
  • As stated previously Scopes will default to the following: read:project:jiraread:user:jirawrite:issue:jiraread:issue:jiraread:issue-link:jirawrite:issue-link:jiraread:issue-link-type:jirawrite:issue-link-type:jiraread:issue.transition:jiradelete:issue:jira. with the addition of offline_access on the connection side to obtain a refresh token. From here you can do any additional configuration to match your use case. For example, you might assign the scopes manage:jira-project read:jira-user if you plan to work with Users and Projects. You will need to enable these scopes on the Atlassian Developer Console page for your OAuth 2.0 Jira app. It is important to include offline_access in your scopes, or you will not be given a refresh token.
  • For Version enter the version of Jira you use (you likely use version 2).

Jira API: manage:jira-configuration, manage:jira-project, write:jira-work, read:jira-work.

Data Sources

Issue Fields

A map of a list of fields to Jira Issue Fields. | key: issueFields | type: picklist


Select Issue Type

Select an issue type | key: selectIssueType | type: picklist


Select Issue Types

Select one or many Issue Types | key: selectIssueTypes | type: objectSelection


Select Project

Select a project | key: selectProject | type: picklist


Select Projects

Select one or many projects | key: selectProjects | type: objectSelection


Actions

Add Comment

Add a comment to an existing issue | key: addComment


Add Issue Attachment

Add a file attachment to an issue | key: addIssueAttachment


Create Issue

Create an issue within a given project | key: createIssue


Create User

Create a new user record | key: createUser


Create Version

Create a new version | key: createVersion

Output Example Payload

{
"data": {
"self": "https://your-domain.atlassian.net/rest/api/3/version/10000",
"id": "10000",
"description": "An excellent version",
"name": "New Version 1",
"archived": false,
"released": true,
"releaseDate": "2010-07-06",
"userReleaseDate": "6/Jul/2010",
"project": "PXA",
"projectId": 10000
}
}

Create Webhook

Create a webhook to send data from Jira to an instance URL | key: createWebhook

Registering a Dynamic Webhook requires supplying a highly configurable payload called "Webhook Details". It's important to configure this for all use cases as each Jira app is only permitted to create and manage one endpoint.

Output Example Payload

{
"data": {
"webhookRegistrationResult": [
{
"createdWebhookId": 7
}
]
}
}

Delete Comment

Delete a comment from an issue | key: deleteComment


Delete Issue

Delete an issue by id | key: deleteIssue


Delete Webhook

Delete a webhook by ID | key: deleteWebhook

Output Example Payload

{
"data": null
}

Download Issue Attachment

Download the attachment data connected to an issue | key: downloadAttachment


Find Issue

Find Issue by attribute | key: findIssue


Find Project

Find Project by attribute | key: findProject


Find User

Find User by attribute | key: findUser


Get Board

Get information and metadata of a board by Id | key: getBoard

Output Example Payload

{
"data": {
"id": 84,
"self": "https://your-domain.atlassian.net/rest/agile/1.0/board/84",
"name": "scrum board",
"type": "scrum",
"location": {
"projectId": 10040,
"userId": 10040,
"userAccountId": "5b10a2844c20165700ede21g",
"displayName": "Example Project",
"projectName": "Example Project",
"projectKey": "Example Project Key",
"projectTypeKey": "KEY",
"name": "Example Project"
}
}
}

Get Comments

Get all the comments on a given issue | key: getComments

Output Example Payload

{
"data": {
"data": {
"startAt": 0,
"maxResults": 1,
"total": 1,
"comments": [
{
"self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000",
"id": "10000",
"author": {
"self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
"accountId": "5b10a2844c20165700ede21g",
"displayName": "Mia Krystof",
"active": false
},
"body": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper."
}
]
}
]
},
"updateAuthor": {
"self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
"accountId": "5b10a2844c20165700ede21g",
"displayName": "Mia Krystof",
"active": false
},
"created": "2021-01-17T12:34:00.000+0000",
"updated": "2021-01-18T23:45:00.000+0000",
"visibility": {
"type": "role",
"value": "Administrators",
"identifier": "Administrators"
}
}
]
}
}
}

Get Current User

Get the information and metadata of the current user | key: getCurrentUser


Get Issue

Get the information and metadata of an issue | key: getIssue


Get Project

Get the information and metadata of a project | key: getProject


Get Status List

Returns a status list | key: getStatusList


Get User

Get information and metadata about an user by id | key: getUser


Get Version

Get the information and metadata of an existing version | key: getVersion


List Assignable Users

Returns a list of users assignable to projects & issues | key: listAssignableUsers

Output Example Payload

{
"data": [
{
"displayName": "exampleUser",
"accountId": "example-483204",
"accountType": "atlassian",
"emailAddress": "someone@example.com",
"active": true
},
{
"displayName": "exampleUser",
"accountId": "example-483204",
"accountType": "atlassian",
"emailAddress": "someone@example.com",
"active": true
}
]
}

List Board Sprints

List all sprints within a board | key: listBoardsSprints

Output Example Payload

{
"data": {
"maxResults": 2,
"startAt": 1,
"total": 5,
"isLast": false,
"values": [
{
"id": 37,
"self": "https://your-domain.atlassian.net/rest/agile/1.0/sprint/23",
"state": "closed",
"name": "sprint 1",
"startDate": "2015-04-11T15:22:00.000+10:00",
"endDate": "2015-04-20T01:22:00.000+10:00",
"completeDate": "2015-04-20T11:04:00.000+10:00",
"originBoardId": 5,
"goal": "sprint 1 goal"
},
{
"id": 72,
"self": "https://your-domain.atlassian.net/rest/agile/1.0/sprint/73",
"state": "future",
"name": "sprint 2",
"goal": "sprint 2 goal"
}
]
}
}

List Boards

Retrieve a list of existing boards | key: listBoards

Output Example Payload

{
"data": {
"maxResults": 2,
"startAt": 1,
"total": 5,
"isLast": false,
"values": [
{
"id": 84,
"self": "https://your-domain.atlassian.net/rest/agile/1.0/board/84",
"name": "scrum board",
"type": "scrum"
},
{
"id": 92,
"self": "https://your-domain.atlassian.net/rest/agile/1.0/board/92",
"name": "kanban board",
"type": "kanban"
}
]
}
}

List Issue Custom Fields

List all configured issue fields | key: listIssueCustomFields

Output Example Payload

{
"data": [
{
"clauseNames": [],
"custom": true,
"id": "statuscategorychangedate",
"key": "statuscategorychangedate",
"name": "Status Category Changed",
"navigable": true,
"orderable": false,
"schema": {
"type": "datetime",
"system": "statuscategorychangedate"
},
"searchable": true
}
]
}

List Issue Fields

List all non-custom issue fields | key: listIssueFields

Output Example Payload

{
"data": [
{
"id": "description",
"name": "Description",
"custom": false,
"orderable": true,
"navigable": true,
"searchable": true,
"clauseNames": [
"description"
],
"schema": {
"type": "string",
"system": "description"
}
},
{
"id": "summary",
"key": "summary",
"name": "Summary",
"custom": false,
"orderable": true,
"navigable": true,
"searchable": true,
"clauseNames": [
"summary"
],
"schema": {
"type": "string",
"system": "summary"
}
}
]
}

List all available issue link types | key: listIssueLinkTypes


List Issue Transitions

Returns a list of issue transitions | key: listIssueTransitions


List Issue Types

Returns a list of issue types | key: listIssueTypes


List Issue Worklogs

Returns a list of issue worklogs | key: listIssueWorklogs


List Issues

Returns a list of issues | key: listIssues


List Priorities

Returns a list of all priorities | key: listPriorities


List Projects

Retrieve a list of all projects | key: listProjects


List Versions

Returns a list of all versions | key: listVersions

Output Example Payload

{
"data": {
"self": "https://your-domain.atlassian.net/rest/api/3/project/PR/version?startAt=0&maxResults=2",
"nextPage": "https://your-domain.atlassian.net/rest/api/3/project/PR/version?startAt=2&maxResults=2",
"maxResults": 2,
"startAt": 0,
"total": 7,
"isLast": false,
"values": [
{
"self": "https://your-domain.atlassian.net/rest/api/3/version/10000",
"id": "10000",
"description": "An excellent version",
"name": "New Version 1",
"archived": false,
"released": true,
"releaseDate": "2010-07-06",
"overdue": true,
"userReleaseDate": "6/Jul/2010",
"projectId": 10000
},
{
"self": "https://your-domain.atlassian.net/rest/api/3/version/10010",
"id": "10010",
"description": "Minor Bugfix version",
"name": "Next Version",
"archived": false,
"released": false,
"overdue": false,
"projectId": 10000,
"issuesStatusForFixVersion": {
"unmapped": 0,
"toDo": 10,
"inProgress": 20,
"done": 100
}
}
]
}
}

List Webhooks

List all webhooks configured, including those for other integrations | key: listWebhooks

Output Example Payload

{
"data": {
"isLast": true,
"maxResults": 100,
"startAt": 0,
"total": 1,
"values": [
{
"events": [
"jira:issue_created"
],
"expirationDate": "2022-12-18T15:22:13.418-0900",
"id": 1,
"jqlFilter": "project = EXAMPLE"
}
]
}
}

Query

Search your entire Jira site using a JQL query | key: query


Raw Request

Send raw HTTP request to Jira | key: rawRequest


Refresh Webhook

Refresh webhook expiration by ID | key: refreshWebhook

Output Example Payload

{
"data": {
"expirationDate": "2022-12-21T09:20:20.388-0900"
}
}

Search Issues

Returns a list of issues that match the given string of text | key: searchIssues


Search Projects

Returns a list of projects that match the given string of text | key: searchProjects


Search Users

Returns a single user that matches the given string of text | key: searchUsers


Transition Issue

Transition an existing issue by Id | key: transitionIssue


Update Comment

Update the contents and metadata of an existing comment. | key: updateComment


Update Issue

Update an existing issue within a given project | key: updateIssue


Update Version

Update an existing version by Id | key: updateVersion

Output Example Payload

{
"data": {
"self": "https://your-domain.atlassian.net/rest/api/3/version/10000",
"id": "10000",
"description": "An excellent version",
"name": "New Version 1",
"archived": false,
"released": true,
"releaseDate": "2010-07-06",
"userReleaseDate": "6/Jul/2010",
"project": "PXA",
"projectId": 10000
}
}