# Inline editing

In the Advanced edition, readers can change fields directly in the table. Every change is
saved to Jira as the reader, so Jira applies their permissions, the field's screens and
its validation, exactly as if they had made the change in Jira. Watchers are notified as
for any other edit.

Inline editing is off in every macro until a page editor turns it on.

## Turn it on

<Steps
  items={[
    {
      title: 'Open the macro’s configuration',
      body: 'Edit the page, select the macro, then the pencil icon on it.',
    },
    {
      title: 'Switch on Allow inline editing',
      body: 'It appears under Results per page, in the Advanced edition only.',
    },
    {
      title: 'Leave out the columns that should stay read-only',
      body: 'Every column whose field can be edited gets an Editable switch in its Column options, on by default. Switch it off for a column readers should not change.',
    },
    {
      title: 'Save, then publish the page',
      body: 'Nothing is editable while the page is open in the editor.',
    },
  ]}
/>

## Who can edit

A reader gets editors when all of these are true:

- The subscription is the **Advanced** edition.
- The macro has **Allow inline editing** on, and the column has **Editable** on.
- The reader is signed in with a Confluence licence. Anonymous and unlicensed readers see the
  table only.
- The page is being viewed, not edited.
- **Jira allows this reader to edit this field on this work item.** The macro asks Jira each
  time a cell is opened, and never reuses the answer.

When Jira says no, the cell says **You can't edit this field on this work item.**, with a
link to open the work item in Jira.

<Aside type="note" title="What the edition check protects">
The edition check runs in the reader's browser. It protects the paid feature, not your data:
every change is made with the reader's own Jira permissions, so nobody can change anything
through the macro that they could not already change in Jira. The app never saves as itself
and never bypasses a screen or a field's editable flag.
</Aside>

## Edit a cell

Select the cell. The editor opens in place, and checks the value as you type where the field
has rules: a required field, a number, a URL, a time estimate, a label. Confirm to save.

Once Jira has saved the change, the row is redrawn from the value Jira stored, in every
column that shows that field. The page does not reload. A work item that no longer matches
the JQL query stays in the table until the page is loaded again.

When Jira refuses the change, the cell keeps its old value and shows Jira's reason after
**Jira did not save the change:**.

One cell is open at a time.

## What can be edited

| Field | Editor |
|---|---|
| Summary, Short text, Epic Name | Text |
| Number, Story points | Number |
| URL | Text, checked as an address |
| Due date, Date picker, Target start and end | Date |
| Date time picker | Date and time, in the reader's browser time zone |
| Priority, Single select, Radio buttons, Version picker | A list of the values Jira allows |
| Multi select, Checkboxes, Components, Fix and Affects versions, Multi version picker, Flagged | A list, several values |
| Cascading select | Two lists: the parent, then a child under it |
| Labels | Existing labels as you type, or a new one |
| Assignee, Reporter, User picker | A user picker |
| Multi user picker, People | A user picker, several users |
| Parent | A search of work items |
| Original estimate, Remaining estimate, Time tracking | A time such as `2h 30m` or `1d` |
| Status | The statuses the work item can move to |
| Assets objects | A search of Assets objects |
| Description, Environment, Paragraph | A rich text editor in place of the cell |

### Field by field

- **Status** lists the statuses the work item can move to from where it is. A transition
  whose screen needs a field without a default is left out, because the macro cannot show
  that screen; when nothing is left, the cell says to change the status in Jira. Only the
  status cell refreshes: fields the transition also sets show on the next page load.
- **People**: the picker lists the site's users, not only those assignable to the work item.
  Jira refuses someone who cannot be assigned, and the cell shows why.
- **Labels** cannot contain spaces or be longer than 255 characters.
- **Estimates** edit only the estimate chosen. An estimate cannot be cleared through Jira's
  REST API, so `0m` means none.
- **Parent** offers work items that are not subtasks. It does not filter by hierarchy level,
  so Jira refuses a parent at the wrong level, with its reason.
- **Cascading select**: changing the parent clears the child.
- **Rich text** opens a rich text editor in place of the cell, with its own **Save** and
  **Cancel**. It opens only when everything in the field is something that editor can
  keep: text formatting, headings, lists, text colour, links and code blocks. A field with a
  table, a mention, an image, a panel or anything else is edited in Jira, so a save never
  loses content. An empty field saves as empty.

### Assets fields

The editor searches objects by label, or by key when the text looks like one, and lists up to
25 at a time. Two column settings, shown only for editable Assets columns, shape it:

- **Objects offered when editing (AQL)**: an AQL query that limits the search, such as
  `objectType = Laptop`. Empty searches every object by label. Jira refuses an object the
  field does not allow when the change is saved, whatever this query offers.
- **Single object**: the editor picks one object instead of several. A field that already
  holds several keeps the multi-object editor, so nothing is dropped.

Jira does not let apps read an Assets field's own object filter or whether it takes several
objects, which is why the column repeats them.

The editor searches the Assets workspace of the objects already in the cell, or elsewhere on
the page. When the page shows no Assets object at all, it cannot tell which workspace to
search and says so. Add an object to a work item in Jira first.

<Aside type="caution" title="Assets and rich text start from Jira’s current value">
Saving either replaces the whole field, so the editor reads the field from Jira when it
opens rather than trusting the page. If someone else changed it after the page loaded, the
cell shows Jira's value and asks you to open it again. That keeps a save from undoing
another person's change.
</Aside>

## What is never edited

- **Set by Jira**: Key, Created, Updated, Resolved, Creator, Resolution (set by transitions),
  Status category changed, Last viewed, Work ratio, Rank.
- **A move, not an edit**: Project, Work type.
- **Managed elsewhere in Jira**: Votes, Watchers, Attachments, Comments, Work log, Subtasks,
  Linked work items, Time spent, Progress.
- **Jira Service Management**: Request type, SLA fields, Approvals, Satisfaction, Request
  language.
- **Fields of other apps**, including Work Item Selector: their own app controls how they
  are edited.
- **Not yet editable**: Group pickers, Team, Sprint, Organizations and Request participants.
  Each needs a search the app's current permissions do not include.

## Next

- [Export, page history and email](../export/)
- [Privacy and data handling](../privacy/)