# Oktul Work Item Macro for Confluence

Oktul Work Item Macro for Confluence puts a table of Jira work items on a Confluence page.
A page editor writes the JQL query and chooses the columns. Everyone who opens the page
sees the work items as they are in Jira at that moment, filtered by their own Jira
permissions.

## What it does

- **Any Jira field as a column.** The column picker lists every field on the site,
  including custom fields, Jira Service Management fields and fields added by other
  Forge apps. The same field can appear in several columns with different display
  options.
- **Display options per column.** Status as a lozenge or text, users as cards or names,
  dates as dates or relative time, numbers with decimals and a unit, and more, depending on
  the field type. See [columns and display options](./columns/).
- **Assets objects as chips.** A Jira Service Management Assets field shows each object
  with its object type icon, label and key, linked to the object. See
  [Assets and Work Item Selector fields](./assets-and-work-item-selector/).
- **Work Item Selector fields as cards.** A field of Oktul Work Item Selector for Jira is
  drawn as the same one-line work item cards that app shows in Jira.
- **Exports with the table in them.** PDF and Word exports, page history and notification
  emails carry the list as a Confluence table, up to 300 rows. See
  [export, page history and email](./export/).
- **Inline editing, in the Advanced edition.** Viewers can change fields in the table
  without leaving the page, as themselves, within their own Jira permissions. See
  [inline editing](./inline-editing/).

## How it works

Every request to Jira and Assets runs as the person viewing the page, from their browser.
Jira applies that person's permissions, so two people can see different rows on the same
page. Someone with no access to a project sees none of its work items.

The macro keeps nothing. Each time the page opens, it runs the JQL query again and reads
the fields fresh from Jira. The only thing saved is the macro's own configuration, which
Confluence stores in the page like any other macro's.

The application runs on Atlassian Forge. Its manifest declares no external permissions
and no remotes, so no data leaves your Atlassian site. See
[privacy and data handling](./privacy/).

## Editions

| Edition | What it includes |
|---|---|
| **Standard** | The table, every column and display option, paging and exports |
| **Advanced** | Everything in Standard, plus inline editing of the listed fields |

The edition follows your Marketplace subscription. Nothing is installed or configured
differently for either.

## What it does not do

- **It does not sort in the table.** Column headers are not sortable, because sorting one
  page of results in the browser would misrepresent the rest. Use `ORDER BY` in the JQL.
- **It does not jump to a page number.** Jira's search returns results one page after
  another, so the table has **Previous** and **Next**. The total in the pager comes from
  Jira's approximate count, which is exact for ordinary result sets.
- **It does not cache.** Every page view runs the search again. A large page size on a
  busy page means more requests to Jira.
- **It does not show images from outside the application.** Priority and work type icons
  are drawn from Atlassian's icon set, and Assets icons are copies of Atlassian's predefined
  icons bundled with the app. An icon an administrator uploaded is not shown: an Assets
  object gets a generic glyph instead, a priority its name only.
- **Exports stop at 300 rows** and show no icons.
- **It shows Jira data only.** The macro does not list Confluence content, and it does not
  create work items.

## Before you start

- Confluence Cloud and Jira Cloud on the same site. The app has to be installed in both:
  Confluence to show the macro, Jira to read the work items.
- A site administrator to install it. See [install the app](./install/).
- To add the macro, permission to edit the page.
- To see work items in it, permission to browse them in Jira. For Assets objects, the
  Object viewer role on their object schema.

## Next

- [Install the app](./install/)
- [Add the macro to a page](./add-the-macro/)
- [Columns and display options](./columns/)
- [Privacy and data handling](./privacy/)