Skip to main content

Jira Component

Jira

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": ""
}

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 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
  }
}