Add the macro to a page

Each macro on a page has its own JQL query, page size and columns. A page can hold as many as it needs, and each one loads on its own.

Insert and configure it

Edit the page and type /oktul
Choose Oktul Work Item Macro for Confluence. It is also in the macro browser, under the + in the toolbar.
Select the macro, then the pencil icon on it
The Configure work item list dialog opens and loads the list of Jira fields.
Write the JQL query
Any JQL that Jira’s own search accepts. Put the sort order in it with ORDER BY.
Set the results per page
Between 1 and 100, 25 by default.
Choose the columns, then Save
A new macro starts with Key, Summary and Status. The page shows the new table as soon as the configuration closes.

The configuration

Setting	What it does
JQL query	Chooses the work items and their order. Column headers are not sortable, so `ORDER BY` in the query is the only sort.
Results per page	How many work items are fetched from Jira at a time, and shown per page. 1 to 100.
Allow inline editing	Advanced edition only, off by default. Lets readers edit fields in the table. See inline editing.
Columns	One row per column, shown left to right in the order of the rows.

Each column row has:

Field: any Jira field on the site, in a searchable list. Two fields with the same name show their field id in brackets, for example Status (customfield_10003).
Table header: the column’s heading. It fills in with the field name when you pick a field, and can be changed.
A drag handle, to move the column.
A bin, to remove it.
A gear, labelled Column options, for field types that have display options. See columns and display options.

The same field can be used in more than one column, each with its own options. One Assets field can show its label in one column and an attribute in the next, for example.

What is checked before saving

Save refuses a configuration with no JQL query, a page size outside 1 to 100, no columns, or a column without a field, and lists what to fix. The JQL itself is checked by Jira when the page loads, not when you save.

If the list of Jira fields cannot load, the configuration says Could not load Jira fields and Save stays disabled, so a failed load never replaces a stored configuration. That usually means the app is not connected to Jira. See install the app.

What readers see

The table shows the first page of results and, under it on the right, the pager: Page 1 of 3 · 62 work items, with Previous and Next. The total is Jira’s approximate count, which is exact for ordinary result sets; a tooltip on it says so. If the count cannot be read, the pager shows only the page number.

Each reader sees the work items their own Jira permissions allow. The page does not store the results, so two readers can see different rows, and a reader who opens the page later sees the work items as they are then.

Dates follow Confluence’s style, Sep 22, 2026 and Sep 22, 2026, 13:03, in the reader’s Atlassian profile language and time zone. A calendar date such as a due date is the same day in every time zone.

Messages on the page

Message	Meaning
Configure this macro	The macro has no JQL query or no usable column yet.
Jira rejected the JQL	Jira’s own error follows, as Jira words it. Fix the query in the configuration.
No work items match this JQL.	The query ran and found nothing this reader can see.
App not installed in Jira, Cannot reach Jira	The app is not connected to Jira on this site. See install the app.
Could not load work items	Any other failure, with Jira’s reason. Try again runs the search again without reloading the page.
App license is not active	The subscription has lapsed. See licensing.

A failed Assets or Work Item Selector lookup does not stop the table. The cell shows what it can and says why in a tooltip.

Something goes wrong only on the page

The table runs in the reader’s browser, so its errors are in the browser’s developer console, as Loading work items failed with a code, rather than in any server log. Include that line when you write to support.