JQL, or Jira Query Language, is a powerful and flexible way to search for your issues in Jira and can also help you filter important issues right into your roadmap.
When to use JQL
When setting up your Jira integration in Roadmunk, there are two ways to filter down which issues from a project should be pulled into your roadmap.
Basic mode allows you to filter issues by Type (Task, Story, Bug, Epic) and by Status (To Do, In Progress, Done) by simply multi-selecting the appropriate values. If you need to use other fields as criteria, then you’ll need to use JQL.
JQL mode allows you to specify the JQL query that Roadmunk should use to filter incoming issues from your Jira project.
Configuring Roadmunk to use JQL
- Select the Jira Project you want to bring into Roadmunk from the Project dropdown.
- Toggle the Configuration Mode from Basic to JQL.
- Input your query in the Custom JQL text field.
- Click the Validate button to ensure that your query is correct.
- If "Everything looks good!" then press Next.
The most common causes of errors in Custom JQL are:
An invalid query
This could be anything from a typo to trying to access a field or value by the wrong name. Before entering JQL into Roadmunk, we recommend using the Advanced Search feature in Jira to build the exact JQL query you'd like to use. Then, simply copy and paste your query into the Custom JQL field in Roadmunk.
Your query specifies a project or has an "order by" clause
Roadmunk will always prepend your project ID and append an order by clause so you’ll need to exclude these from your JQL when you copy it over from Jira.
Example Roadmunk generated JQL:
project = <your project id> AND (<your JQL query>) ORDER BY created ASC