Gridwell documentation (public KB source)
Get started
- Create a field. Jira settings > Work items > Fields > Create field > Gridwell table. Name it for what it holds ("Line items", "Test steps", "Contacts").
- Choose where it applies. In the field's Contexts and default value, pick projects and work types. Each context can have its own columns.
- Set the columns. Edit the context's configuration. Start from a template (Line items, Test steps, Effort breakdown, Checklist with owners, Contacts, Risks, or one you saved) or add columns yourself. Save.
- Put it on screens. Add the field to the create, edit and view screens of those work types. For Jira Service Management, add it to the request type's form so customers can fill it in.
Column types
| Type | Holds | Notes |
|---|---|---|
| Text | Up to 2,000 characters | Words are searchable with Text ~ |
| Number | Numbers | Decimals, prefix ($) and suffix (h, kg). Pasted values like 1.234,50, $1,200 and (40) are understood |
| Date | A date | Picker in the editor. Pasted ISO, month/day/year or day/month/year (set per context), or 3 Mar 2026 |
| Person | A Jira user | User picker; pasted names or emails are matched when exactly one person fits. People are searchable with Users |
| Select list | One of your options | Matching ignores case |
| Checkbox | Yes or no | Pasted yes/no, x, 1/0, true/false |
| Formula | A number computed from the row | See below. Never typed or imported |
Each column can be required and can have a default for new rows (today works for dates).
Formulas
Use column ids (shown on the configuration screen, like qty) or names in brackets
([Unit price]).
- Operators:
+ - * / % ^, comparisons= <> < > <= >=(1 when true, 0 when false), parentheses. - Functions:
ROUND(x, digits),ROUNDUP,ROUNDDOWN,ABS,MIN,MAX,SUM,AVG,IF(condition, then, else),AND,OR,NOT,DAYS(end, start),TODAY(). - Checkboxes count as 1 or 0, dates as day numbers (so
DAYS([Due], TODAY())is days left), empty cells as 0. Formulas can use other formula columns; loops are reported.
Examples: qty * unit_price, ROUND(hours * rate * (1 - discount / 100), 2),
IF(done, 0, estimate), likelihood * impact.
Totals
Each number or formula column can show a sum, average, minimum or maximum in the totals row; checkbox columns can count ticked boxes; any column can count filled cells.
Rules
- Required columns: every row needs a value.
- Minimum and maximum rows: for example "at least one line item".
- Saving is blocked while anything needs fixing, and the problems are listed under the table.
Jira re-checks this on the server (
value.problems == 0), so other clients can't save a broken table either.
Paste and import
- Paste rows: copy cells from Excel, Google Sheets, Numbers or a CSV file. Tabs, commas and semicolons all work. If the first line matches your column names (in any order, ignoring case and spacing), it's used as the header; otherwise values fill the columns left to right. Choose Add to the existing rows or Replace all rows.
- Import JSON: paste an array of row objects or a Table Grid export (
rowswithcolumnsmaps, plus the column list that maps internal names to titles). Keys are matched to column names. Unmatched keys are listed, and formula columns are always calculated. - Copy as CSV: on the issue view, under the table.
Search with JQL
Every Gridwell field can be searched by:
| Property | Example |
|---|---|
Rows (row count) | "Line items.Rows" > 3 |
Total, Total2, Total3 (the column totals chosen on the context) | "Line items.Total" >= 5000 |
Text (words in text and select cells, first 1,000 characters) | "Contacts.Text" ~ "acme" |
Users (people in person columns) | "Checklist.Users" = currentUser() |
Checked (ticked boxes) | "Test steps.Checked" < 3 |
Problems | "Line items.Problems" > 0 |
List view, filters, exports and history show the field's summary, such as "5 rows, Amount $3,554.90, Qty 18".
Starter rows and templates
- Starter rows: on the configuration screen, paste CSV rows that every new work item begins with (a standard checklist, the usual line items).
- Save as a template: Jira admins can save a context's columns as a template; every Gridwell field on the site can then start from it. Manage templates under Jira settings > Apps > Gridwell.
Large tables
Up to 2,000 rows and 30 columns. Tables over about 24 KB keep their rows in Gridwell's storage on Atlassian; the field keeps the first rows and the full summary, so search, list view and exports keep working, and the issue view loads every row for anyone who can see the work item.
Changing columns later
Renaming a column keeps its data. Removing a column that still holds data keeps it visible as "(removed column)" in the editor until its cells are cleared, so nothing is lost by accident.
Moving from Table Grid on Data Center
- Create a Gridwell field with the same column names as the grid.
- For each work item, export the grid's rows as JSON (Table Grid's REST API or export) and use Import JSON in the Gridwell editor.
- Person values with account ids are kept; names are matched to Jira users.
Subscription
If the subscription or trial ends, tables stay readable but can't be changed until it is renewed under Apps > Manage apps.