Jira Component
Manage Jira issues, comments, projects and users
Component key: atlassian-jiraDescription
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
This component was built using the 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).
- You will now be prompted to enter your redirect URL as
https://oauth2.prismatic.io/callback
for US based integrations.- For integrations outside the US refer to this guide to find your region’s Callback 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, 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: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
.
- 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 scopesmanage: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 includeoffline_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
{
"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.
Registering a Webhook Notes
Please note that whenever trying to register a webhook, the request payload's structure is different depending on the authentication method:
- For Basic Auth, the payload should be structured as follows on this article: Basic Auth Webhook Payload Structure
{
"name": "my first webhook via rest",
"description": "description of my first webhook",
"events": ["jira:issue_created", "jira:issue_updated"],
"filters": {
"issue-related-events-section": "Project = JRA AND resolution = Fixed"
},
"excludeBody": false,
"secret": "G8j4166a5OkXRD4WbqV3"
}
- For OAuth, the payload should be structured as follows: OAuth Webhook Payload Structure
[
{
"events": ["jira:issue_created", "jira:issue_updated"],
"fieldIdsFilter": ["summary", "customfield_10029"],
"jqlFilter": "project = PROJ"
},
{
"events": ["jira:issue_deleted"],
"jqlFilter": "project IN (PROJ, EXP) AND status = done"
},
{
"events": ["issue_property_set"],
"issuePropertyKeysFilter": ["my-issue-property-key"],
"jqlFilter": "project = PROJ"
}
]
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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 Issue Link Types
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
{
"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
{
"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
{
"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
{
"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
}
}