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.
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 ofoffline_accesson 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-userif 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_accessin 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": ""
}
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": {
"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 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
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"
}
]
}
}
Raw Request
Send a raw HTTP request to Jira API | 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
}
}