Skip to main content

Jira query tutorial

Learn how to read and write data to Jira.

After setting up a Jira integration with Retool, your Jira resource is available to use in the query editor. Retool generates the available operations directly from Jira's OpenAPI specification, so you select an operation instead of writing a request from scratch.

Create a query​

Switch to the new app builder

Retool recommends using the new app builder so you can use natural language to build React-based apps using AI.

To create a Jira query in a Retool app:

  1. In the Retool app IDE, open the Code tab, then click + in the page or global scope.
  2. Select Resource query.
  3. Choose your Jira resource.
  4. Select an operation and configure its parameters.

Query configuration fields​

Jira queries don't use fixed Retool action types. Instead, the query editor reads Jira's OpenAPI specification and exposes its operations and parameters directly.

Operation​

Select the Jira API operation to call, such as searching for issues or creating an issue. Operations are grouped by the resource they act on (issues, projects, workflows, and so on). Refer to the Jira Cloud REST API reference for the full list of available operations and what each one does.

Parameters​

Once you select an operation, Retool displays the parameters that operation supports, grouped by where they belong in the request: path, query, or header. Required parameters are marked in the editor. Use embedded expressions to populate parameters dynamically.

Example: dynamic issue key
{{ table1.selectedRow.data.key }}

Request body​

For operations that create or update data (such as creating an issue), Retool displays a form generated from Jira's request schema. Fields marked required in the schema must be filled in before the query can run.

Example request body for creating an issue
{
  "fields": {
    "project": {
      "key": {{ projectSelect.value }}
    },
    "summary": {{ summaryInput.value }},
    "description": {{ descriptionInput.value }},
    "issuetype": {
      "name": {{ issueTypeSelect.value }}
    }
  }
}

Common use cases​

The following examples demonstrate typical Jira operations in Retool apps. For a complete reference of available operations and parameters, refer to the Jira Cloud REST API documentation.

search for issues with JQL

First, create a query and select the Search for issues using JQL (GET) operation.

Set the jql query parameter to a Jira Query Language expression.

Example
project = {{ projectSelect.value }} AND status = "In Progress" ORDER BY created DESC

Next, add a Table component to the app and set its Data property to {{ searchIssuesQuery.data.issues }}.

retrieve an issue

First, create a query and select the Get issue operation.

Set the issueIdOrKey path parameter to the issue you want to retrieve.

Example
{{ table1.selectedRow.data.key }}

Next, bind a Text or Form component to {{ getIssueQuery.data }} to display the issue's fields.

create a new issue

First, add a Form component (form1) with input fields for the issue's project, summary, description, and issue type.

Next, create a query and select the Create issue operation. Configure the request body:

Example request body
{
  "fields": {
    "project": {
      "key": {{ form1.data.project }}
    },
    "summary": {{ form1.data.summary }},
    "description": {{ form1.data.description }},
    "issuetype": {
      "name": {{ form1.data.issueType }}
    }
  }
}

Then, add an event handler to the form's Submit event that runs the create query and refreshes the search query.

update an issue's fields

First, add a Button component in your table's action column.

Next, create a query and select the Edit issue operation. Set the issueIdOrKey path parameter and configure the request body:

Example issueIdOrKey
{{ table1.selectedRow.data.key }}
Example request body
{
  "fields": {
    "summary": {{ summaryInput.value }},
    "priority": {
      "name": {{ prioritySelect.value }}
    }
  }
}

Then, add an event handler to the button's Click event that runs the update query and refreshes the search query.

transition an issue's status

First, add a Select component listing the available transitions for an issue.

Next, create a query and select the Get transitions operation with the issueIdOrKey path parameter set to {{ table1.selectedRow.data.key }} to populate the available transitions.

Then, create a second query and select the Do transition operation. Set the issueIdOrKey path parameter and configure the request body:

Example request body
{
  "transition": {
    "id": {{ transitionSelect.value }}
  }
}

Add an event handler to the select component's Change event that runs the transition query and refreshes the search query.

Best practices​

Follow these best practices to keep Jira queries fast, efficient, and safe.

Performance​

  • Cache responses: For data that doesn't change frequently, enable query caching to reduce API calls and improve response times.
  • Request only what you need: Use the fields query parameter Jira supports on issue search and retrieval operations to limit the fields returned instead of fetching full issue objects.
  • Paginate large result sets: Use the startAt and maxResults parameters on search operations to page through large result sets instead of requesting everything at once.
  • Set appropriate timeouts: Configure query timeouts based on expected API response times to prevent hung requests.

Data integrity​

  • Validate user input: Sanitize and validate all user input before including it in a JQL expression or request body to prevent malformed or unexpected data from reaching Jira.
  • Handle errors gracefully: Configure error notifications and fallback behavior for failed queries to improve user experience.
  • Verify responses: Check the response status and validate the response data structure before using it in your app.
  • Implement retry logic: For transient failures, use Retool's automatic retry settings or implement custom retry logic with exponential backoff.
  • Log query activity: Enable query logging to track requests and responses for debugging and auditing.