# Assets and Work Item Selector fields

Two kinds of field hold references rather than values: an Assets field holds objects, and a
Work Item Selector field holds work items. Jira's search returns only the references, so the
macro looks up what they point at after the table is on screen. Those cells show a spinner
for a moment while everything else is already there.

## Assets fields

Each object in a Jira Service Management Assets field is a chip: the object type's icon, the
object's label linked to the object in Assets, and its key.

### Options

| Option | Values | Default |
|---|---|---|
| **Show** | Label, Object key, Label and key | Label and key |
| **Show icon** | on or off | on |
| **Attribute instead of label** | The name of an attribute of the object type, such as `Serial number` | none |

With an attribute set, the chip shows that attribute's value in place of the label, and the
label when the object has no value for it. To show several attributes, add the field as
several columns, one attribute each.

### Who sees what

The lookup runs as the reader, and Assets needs more than Jira permission for it: the reader
needs at least the **Object viewer** role on the object's schema. Without it, the chip shows
the object's key in a warning state, and its tooltip names the missing role. An object that
has been deleted, or that the reader cannot see at all, shows the same way with Assets' own
reason.

### Icons

The macro shows Atlassian's predefined Assets icons, such as Laptop, Server and Building,
from copies bundled with the application. It never loads an image from outside the app,
which is what keeps it on the *Runs on Atlassian* programme.

- **An icon an administrator uploaded** is not shown. The chip shows a generic glyph instead.
- **A predefined icon Atlassian adds or renames later** also shows the glyph until the
  application is updated with the new set.
- **Changing an object type's icon** in Assets shows on the next page view, with nothing to
  update.

### Exports

In PDF, Word, page history and email, each object is its label and key, with the label
linked to the object. Exports show no icons.

## Work Item Selector fields

The fields of [Oktul Work Item Selector for Jira](/apps/work-item-selector/), single select
and multi select, are recognised without any setting. Each selected work item is drawn as
the one-line card that app shows in Jira: work type, key and summary on the left, then
priority, status and assignee on the right.

### Options

- **Show as**: **Cards, as in Jira** (the default) or **Keys only**, which lists the keys as
  links and looks nothing up.
- **Card fields**: the fields each card shows, up to seven, chosen from every Jira field on
  the site. Work type, key and summary always sit on the left, and the rest on the right in
  the order chosen. Left empty, the cards show work type, key, summary, priority, status and
  assignee.

Work Item Selector keeps its own card fields in its field configuration in Jira, and Jira
does not let one app read another app's field settings. So the macro cannot copy them, and
the column states them instead.

### What a card shows

| Field on the card | Shown as |
|---|---|
| Work type, Priority | Jira's icon, with the name in a tooltip |
| Status | A small pill, cut at 16 characters |
| Assignee and other people | Initials avatars, at most three, then **+N** |
| Labels | Tags |
| Assets fields | "N Assets objects"; cards do not look objects up |
| Anything else | One line of text: dates and numbers formatted, rich text's first line |

A multi select field shows ten cards, then **+N more**.

A work item the reader cannot browse, or that has been deleted, shows as a muted card with
its key and **Not available**, as it does in Jira.

<Aside type="note" title="A moved work item shows as Not available">
When a work item moves to another project, its key changes. The field still holds the old
key, and the macro does not match the work item Jira returns under the new one, so the card
says **Not available** until the field is set again.
</Aside>

### Exports

Each work item is one line: its key, linked, then the card's fields joined with " · ", with
statuses as Confluence status lozenges. Exports show no icons or avatars.

## Next

- [Inline editing](../inline-editing/)
- [Export, page history and email](../export/)