Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 29 ยท Projects

Project: A Small Issue Tracker with Search

Build a small issue tracker in JavaScript with workflow rules, then add a JQL-style query language: tokenizer, parser, filtering and sorting.

Jira feels like magic until you build a miniature version of it. In this project you will write the core of a small issue tracker: a store that creates issues with keys like SHOP-1 and enforces a workflow, and a search language inspired by JQL (Jira Query Language) that can answer questions such as "which high-priority bugs are not done and assigned to me?".

You will meet three classic programming ideas along the way: a tokenizer that splits text into pieces, a recursive-descent parser that turns those pieces into a tree, and an evaluator that walks the tree for each issue. They are the same steps real query languages use. The result is a stand-in that borrows JQL's look and a few of its rules; it is not Jira's engine and does not support most of real JQL. The real language is covered in JQL and Filters, and issue types and workflows in Issues, Issue Types and Workflows.

From text to results

Tokenize Split the query into words and symbols.
Parse Build a tree that respects AND, OR and brackets.
Evaluate Test every issue against the tree.
Sort Apply ORDER BY after filtering.

Four small steps turn a string into a result list.

1 / 2

Step 1: The issue store

A tracker needs to hold issues, give each one a unique key, and protect the workflow. In Jira, a key is the project key plus a counter (SHOP-1, SHOP-2), and you can only move an issue along the transitions that the workflow allows. The store below does the same with a Map, a counter and a table of allowed moves.

It also validates input (a summary must say something) and records a history of status changes, which later lessons use for cycle time. Errors are thrown as exceptions so the caller can show them.

JS An issue store with a workflow

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that the workflow lives in data (this.flow), not in if statements. That is also how Jira works: a workflow is configuration that an administrator edits, see Workflows, Permissions and Customization.

Step 2: The query language

Our language is a small subset of what JQL offers, with these rules:

  • A clause is field operator value, for example status = "In Progress". Quote values that contain spaces.
  • Operators: =, !=, ~ (contains, case-insensitive), >, <, >=, <=, IN (a, b), NOT IN (a, b), IS EMPTY, IS NOT EMPTY.
  • Combine clauses with AND, OR, NOT and parentheses. AND binds tighter than OR, as in most languages.
  • currentUser() is a function that returns whoever is running the search.
  • Dates compare as YYYY-MM-DD text, and -7d means seven days before the fixed "today" in the example.
  • ORDER BY field [ASC|DESC], ... sorts the result. Priority sorts by importance, not alphabetically.

A rule worth remembering about priority: the words Lowest, Low, Medium, High, Highest sort as a ranked list, so priority >= High finds High and Highest. Alphabetical comparison would give nonsense, so the evaluator maps names to ranks first.

How the parser works

The grammar is written from the loosest binding to the tightest, and each level has one function:

  1. parseOr handles a OR b OR c.
  2. parseAnd handles a AND b AND c and is called by parseOr, so AND binds tighter.
  3. parseNot handles NOT x and parenthesized groups, which call parseOr again.
  4. parseClause reads one comparison.

That is recursive descent: the call structure mirrors the grammar. The output is a tree such as or(and(a, b), c) that the evaluator can test against each issue.

JS Tokenizer, parser and evaluator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Study the last three queries. A good query language gives useful errors: it says what it expected and where, instead of silently returning nothing. Jira's own editor does the same by underlining the bad part of a query.

Two design details deserve a note. Sorting by several keys is done by sorting repeatedly from the last key to the first, which works because JavaScript's sort is stable (equal items keep their order). And fields that hold lists, like labels, make = mean "contains this value", which is how Jira treats label fields too.

Extending the project

  1. Add a reporter field and a resolved date, and support resolved >= -14d.
  2. Add was history queries by searching the history array (for example "was In Progress").
  3. Support a sprint in openSprints() function by giving issues a sprint and tracking which sprints are open.
  4. Return paged results (startAt, maxResults) and the total count, as the Jira REST API does; see Jira Automation and the REST API.
  5. Save queries by name as filters and let one filter reference another.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In the parser, why is parseAnd called from parseOr rather than the other way round?

    Functions that sit lower in the call chain bind tighter. parseOr calls parseAnd, so 'a OR b AND c' is read as 'a OR (b AND c)'.
  2. 2. Why does the evaluator map priority names to ranks before comparing?

    Alphabetically 'High' < 'Highest' < 'Low' < 'Lowest' < 'Medium', which has no relation to importance. Ranks make '>= High' mean High and Highest.
  3. 3. What does the tokenizer produce?

    Tokenizing is the first step: it splits text into tokens. The parser then arranges the tokens into a tree, and the evaluator uses the tree.
  4. 4. Why does the store keep the workflow in a data table?

    A workflow is configuration. Keeping it as data separates the rules from the code that enforces them, which is how Jira treats workflows.

Summary

  • An issue store needs unique keys, validation and a workflow table that decides which status changes are allowed.
  • A query language is processed in three steps: tokenize, parse into a tree, evaluate each item against the tree.
  • Recursive descent maps the grammar to functions; the order of calls decides operator precedence.
  • Ranked fields such as priority need explicit ordering, and stable sorting makes multi-key ORDER BY easy.
  • Helpful error messages are part of a query language's design.
  • The code is a teaching stand-in with a JQL-like syntax, not Jira's implementation.

Next, simulate flow with Project: Kanban Flow Simulator.