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.
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
Go to the Atlassian Developer Console.
Click on Create and select OAuth 2.0 integration
Enter the name of the integration and click Create.
-
Go to the Permissions menu in the left sidebar.
-
Click on Add in the Jira API. Then click Configure.
- Under Jira platform REST API click on Edit Scopes.
- 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.
-
Click Save.
-
Go to Authorization in the left sidebar and click on Add next to OAuth 2.0 (3LO)
- Enter a placeholder callback URL and click Save Changes. We will replace this later by the correct callback URL from the action.
- 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
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
-
Copy the redirect URL from the OAuth section in the action.
-
Go to your Jira app
-
Navigate back to the Authorization section in the left sidebar.
-
Next to OAuth 2.0 (3LO) click on Configure and replace the placeholder from before with the correct callback URL.
