​
Prerequisites

This guide helps you to set up an assistant action for Jira. Before proceeding, we recommend reading the following guide: Assistant actions.

Jira is a ticket and project management tool by Atlassian. You can search and read issues from Jira in Langdock or create and update issues, tasks and assign the to other users in your assistant.

Before you get started, make sure that you have access and permissions to create an application in the Atlassian Developer Console. Also, you need your Jira Domain: https://YOUR_SUBDOMAIN.atlassian.net/jira

You can find the Application API Documentation of Jira here and the Application OAuth 2.0 Documentation here.

​
Setup

​
1. Assistant instructions

Create a new assistant. If you are new to creating assistants, you can read more about how to create assistants and write instructions in our assistant guide and our prompt engineering guide. Paste the following instructions into the according field.

Persona: You are the Jira assistant and are specialized in creating and editing issues in Jira through API connections. 

Task: You can create, read and edit project issues based on the user’s instructions.

- When asked to perform a task, use the available actions via the api.atlassian.com API.
- When asked to create an issue, use the user's input to synthesize a summary and description and file the issue in JIRA.
- When asked to create a subtask, assume the project key and parent issue key of the currently discussed issue. Clarify with if this context is not available.
- When asked to assign an issue or task to the user, first use jql to query the current user's profile and use this account as the assignee. 
- Ask for clarification when needed to ensure accuracy and completeness in fulfilling user requests.

​
2. OpenAPI Schema

Scroll to the bottom of the assistant configuration and click on New Action. Here you can configure actions and API requests to other tools. Copy the text below into the field OpenAPI Schema. You can also try out action assistant to write the OpenAPI schema.

: Add your unique cloud ID in the URL. You can find the cloud id here: https://YOUR\_SUBDOMAIN.atlassian.net/\_edge/tenant\_info
openapi: 3.1.0
info:
  title: Jira API
  description: API for interacting with Jira issues and sub-tasks.
  version: 1.0.0
servers:
  - url: https://api.atlassian.com/ex/jira/{CLOUD_ID}/rest/api/3
    description: Jira Cloud API
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.atlassian.com/authorize
          tokenUrl: https://auth.atlassian.com/oauth/token
          scopes:
            read:jira-user: Read Jira user information
            read:jira-work: Read Jira work data
            write:jira-work: Write Jira work data
  schemas:
    Issue:
      type: object
      properties:
        id:
          type: string
        key:
          type: string
        fields:
          type: object
          properties:
            summary:
              type: string
            description:
              type: string
            issuetype:
              type: object
              properties:
                name:
                  type: string
    IssueUpdateDetails:
      additionalProperties: true
      description: Details of an issue update request.
      properties:
        fields:
          additionalProperties: {}
          description: List of issue screen fields to update, specifying the sub-field to update and its value for each field. This field provides a straightforward option when setting a sub-field. When multiple sub-fields or other operations are required, use `update`. Fields included in here cannot be included in `update`.
          type: object
        properties:
          description: Details of issue properties to be add or update.
          items:
            $ref: '#/components/schemas/EntityProperty'
          type: array
        update:
          additionalProperties:
            items:
              $ref: '#/components/schemas/FieldUpdateOperation'
            type: array
          description: A Map containing the field field name and a list of operations to perform on the issue screen field. Note that fields included in here cannot be included in `fields`.
          type: object
paths:
  /search:
    get:
      operationId: getIssues
      summary: Retrieve a list of issues
      parameters:
        - name: jql
          in: query
          schema:
            type: string
        - name: startAt
          in: query
          schema:
            type: integer
        - name: maxResults
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of issues
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      $ref: '#/components/schemas/Issue'
  /issue:
    post:
      operationId: createIssue
      summary: Create a new issue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type: object
                  properties:
                    project:
                      type: object
                      properties:
                        key:
                          type: string
                    summary:
                      type: string
                    description:
                      type: object
                      properties:
                        content:
                          type: array
                          items:
                            type: object
                            properties:
                              content:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    text:
                                      type: string
                                    type:
                                      type: string
                                      default: text
                                      enum: [text]
                              type:
                                type: string
                                default: paragraph
                                enum: [paragraph]
                        type:
                          type: string
                          enum: [doc]
                        version:
                          type: integer
                          enum: [1]
                      required:
                        - content
                        - type
                        - version
                    issuetype:
                      type: object
                      properties:
                        name:
                          type: string
      responses:
        '201':
          description: Issue created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'
  /issue/{issueIdOrKey}:
    get:
      operationId: getIssue
      summary: Retrieve a specific issue
      parameters:
        - name: issueIdOrKey
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Issue details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'
    put:
      operationId: updateIssue
      summary: Update an existing issue
      parameters:
        - name: issueIdOrKey
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type: object
                  properties:
                    summary:
                      type: string
                    description:
                      type: string
                    issuetype:
                      type: object
                      properties:
                        name:
                          type: string
      responses:
        '204':
          description: Issue updated successfully
  /issue/subtask:
    post:
      operationId: createSubTask
      summary: Create a sub-task for an issue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type: object
                  properties:
                    project:
                      type: object
                      properties:
                        key:
                          type: string
                    parent:
                      type: object
                      properties:
                        key:
                          type: string
                    summary:
                      type: string
                    description:
                      type: object
                      properties:
                        content:
                          type: array
                          items:
                            type: object
                            properties:
                              content:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    text:
                                      type: string
                                    type:
                                      type: string
                                      default: text
                                      enum: [text]
                              type:
                                type: string
                                default: paragraph
                                enum: [paragraph]
                        type:
                          type: string
                          enum: [doc]
                        version:
                          type: integer
                          enum: [1]
                    issuetype:
                      type: object
                      properties:
                        name:
                          type: string
      responses:
        '201':
          description: Sub-task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'
security:
  - OAuth2:
      - read:jira-user
      - read:jira-work
      - write:jira-work

​
Authentication

​
3. Create a Jira Application

  1. Go to the Atlassian Developer Console. Click on Create and select OAuth 2.0 integration

  2. Enter the name of the integration and click Create.

  3. Go to the Permissions menu in the left sidebar.

  4. Click on Add in the Jira API. Then click Configure.

  5. Under Jira platform REST API click on Edit Scopes.

  6. Grant the following scopes: read:jira-work write:jira-work read:jira-user

If you want to use other permissions than in our example, you need to set this here and in the OpenAPI Schema above.

  1. Click Save.

  2. Go to Authorization in the left sidebar and click on Add next to OAuth 2.0 (3LO)

  3. Enter a placeholder callback URL and click Save Changes. We will replace this later by the correct callback URL from the action.

  4. Go to Settings in the left sidebar and scroll down to Authentication Details. Save the Client ID and the Secret securely. We will need them to authenticate the access from Langdock.

​
4. OAuth Configuration in Langdock

  1. Go to the Authentication section at the top of the action settings. Select OAuth. Enter the according information from your Jira Application:

Specifying the scope offline_access allows us to automatically refresh access tokens for signed-in users.

​
5. Paste the redirect URL into Jira application

  1. Copy the redirect URL from the OAuth section in the action.

  2. Go to your Jira app

  3. Navigate back to the Authorization section in the left sidebar.

  4. Next to OAuth 2.0 (3LO) click on Configure and replace the placeholder from before with the correct callback URL.

Was this page helpful?

Google Drive ActionsFair Usage Policy