# 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

<Steps
  items={[
    {
      title: 'Edit the page and type /oktul',
      body: 'Choose Oktul Work Item Macro for Confluence. It is also in the macro browser, under the + in the toolbar.',
    },
    {
      title: 'Select the macro, then the pencil icon on it',
      body: 'The Configure work item list dialog opens and loads the list of Jira fields.',
    },
    {
      title: 'Write the JQL query',
      body: 'Any JQL that Jira’s own search accepts. Put the sort order in it with ORDER BY.',
    },
    {
      title: 'Set the results per page',
      body: 'Between 1 and 100, 25 by default.',
    },
    {
      title: 'Choose the columns, then Save',
      body: '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](../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](../columns/).

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](../install/#if-it-did-not-work).

## 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](../install/#if-it-did-not-work). |
| **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](../install/#licensing-and-what-happens-when-it-lapses). |

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.

<Aside type="tip" title="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.
</Aside>

## Next

- [Columns and display options](../columns/)
- [Assets and Work Item Selector fields](../assets-and-work-item-selector/)
- [Export, page history and email](../export/)