Pickmark documentation

Get started

1. Install Pickmark from the Atlassian Marketplace (Confluence admin). Sites of up to 10 users pay a flat $5 a month, and every site gets a 30-day free trial.
2. Edit any page and type /Status, /Dropdown, /Checkbox or /Date, then pick the (Pickmark) macro.
3. The first time, the macro asks you to create a field, for example "Status" with Draft, In review, Approved and Rejected. Choose Create field, then Save, and publish the page.
4. On the published page, click the value and pick a new one. No edit mode needed.
5. On another page, insert the Pickmark report macro to list every page with a given value.

Fields are shared across the site: create "Status" once and use it on any page, then report on it across spaces. Confluence admins manage fields under Settings > Pickmark fields.

The value macros

Changing a value on the published page

Click the value to open a picker. Choose an option, tick options and Save for a multi-select, or pick a date. Clear value removes it. Checkboxes toggle with one click. The picker shows who changed the value last and when.

A value change does not edit the page. It is saved separately from the page body, so it creates no page version and never touches anyone's unpublished draft. If the same field appears more than once on a page, every copy updates together.

To change a value you need permission to edit the page. A field can be narrowed further to named people (see Admin settings). Hover over a value you can't change to see why.

Macro settings

When you insert or edit a value macro:

• Status field (or Dropdown, Checkbox, Date field): pick an existing field, or New status field to create one. Edit options changes the field's options if you are allowed to.
• How the value is set:
  • On the published page: anyone who can edit the page clicks it to change it.
  • Here, in the editor only: you set the Value in the macro settings and the page shows it as plain, read-only text. It is saved when you publish, so reports still see it.
• Show "Field name:" before the value: adds the field name as a prefix.

Fields and options

When you create or edit a field:

• Field name and Type (Status, Dropdown, Checkbox or Date).
• Allow more than one value (multi-select) for dropdowns. This can't be changed later.
• Options, each with a color (Grey, Blue, Green, Red, Yellow, Purple). Reorder with Up and Down, add with Add option, or Paste a list with one option per line ("Approved, green" sets the color). For checkboxes you can rename the Yes and No labels.
• Default for new pages: an option, or for dates The day the page is created. Pages created from a template get this value when they are published, so they show up in reports right away.
• Description (optional).

Renaming an option keeps every page's value, because pages store the option, not its text. Remove hides an option from pickers; pages that already use it still show it.

The Pickmark report

Insert Pickmark report on any page. In its settings:

• Heading (optional).
• Which pages: This space, These spaces or All spaces I can see, plus With label (optional) and Only pages below this page.
• Where: up to 6 filters with Add filter. Each one is a field, a condition and values:

With no filters, the report lists every page in scope that has at least one Pickmark value.

• Show: field columns, plus Space, Last updated, Who changed a value last and Let readers filter and search.
• Sort by (page title, last updated or any field), Order, Maximum rows (up to 1,000, default 200) and Chart (a donut chart of one status, dropdown or checkbox field).

On the published page:

• The table sorts by any column and shows 25 rows per page. Page titles link to the pages.
• People who can edit a page can change its values right in the table.
• With Let readers filter and search on, readers get Search titles and values, a filter for each field (dates offer Overdue, Due in the next 7 days and Due in the next 30 days), Apply and Reset. This narrows the view for them only and never edits the page.
• Click an entry in the chart legend to filter the table to that value.
• Copy as CSV shows the result as CSV text to copy into a spreadsheet or save as a .csv file.
• Show CQL shows the Confluence query behind the report, for Confluence advanced search or any macro that takes CQL.

Reports only list pages the reader is allowed to see.

Searching values in Confluence

Pickmark values are indexed by Confluence. In Confluence advanced search, the Pickmark values field finds pages by the text of any Pickmark value. Each field also has its own CQL field name (shown in Settings > Pickmark fields), for example gwpps_s1.

PDF and Word export

Value macros export as their text, and the report exports as a table, so Confluence's Export to PDF and Word include them. Pickmark values also work inside Confluence's own Page Properties tables.

Admin settings

Confluence admins open Settings > Pickmark fields. It has four tabs.

Fields: every field with its type, options and CQL field. New field, Edit and Delete. Deleting hides a field everywhere and makes its values read-only; Show deleted fields and Restore bring it back. When editing a field, Only these people can change values limits who can set it (leave empty for anyone who can edit the page).

Import values: set values on many pages at once, for example when moving from Data Center. Export your Page Properties Report, or your old dropdown app's report, to CSV, rename the columns to match field names, and paste it in.

• Identify pages with a Page ID (or page URL) column, or Space key plus Page title.
• Every other column named like a field is imported. Use option labels and separate multiple values with ;. Checkboxes: yes or no. Dates: YYYY-MM-DD. Empty cells leave a page alone; (clear) removes a value.
• Check CSV shows how columns map to fields, rows with problems (skipped), and values that are not options yet, with a button to add them. Then Import N rows. A progress bar shows updated, unchanged and failed rows with the line number of each failure.
• Each row is written as you, so your own edit permissions apply. Up to 1,000 rows per import.

Backup: Show backup gives the field definitions (names, options, colors, defaults) as JSON. Paste a backup and choose Merge into this site to restore it or copy fields to another site. Values stay on the pages.

Permissions:

• Anyone can create new fields from the macro settings (on by default). Turn it off so only admins create fields here.
• Anyone can change any field's options (off by default: only the field's creator and admins can).

Licensing and trials

Pickmark is paid through Atlassian: $5 a month for up to 10 users, billed per user above that, with a 30-day free trial. If the subscription is not active, a "Subscription not active" message appears and everything stays visible and readable, including reports. Changing values, creating or editing fields, Copy as CSV and imports pause until a site admin starts a trial or renews in Apps > Manage apps. Values are never deleted because of a lapsed subscription.

Permissions and data handling

Pickmark runs on Atlassian's Forge platform and is built for Runs on Atlassian. It makes no calls outside Atlassian.

• Values are stored on each page as a Confluence content property, not in the page body. Field definitions and settings are stored in Atlassian's Forge storage for your site.
• Reading and changing values runs as you, with your Confluence permissions. Reports are Confluence searches run as the reader.
• The app acts on its own only to apply a field's default, or a value set in the macro settings, to a page when it is published, and to refresh the searchable text after an option is renamed. It writes only Pickmark's own property.
• Each page keeps a log of its last 25 value changes (who and when).

Pickmark asks Confluence for permission to read and write pages (for its property), run searches (reports and imports), read spaces (the report's space picker) and receive page events (defaults on publish).

Limits and known gaps

• Pages only. Blog posts and live docs are not supported.
• Per site: 24 status, dropdown and checkbox fields, 8 date fields and 8 multi-select fields. Fields are shared by every page, so most sites use a handful.
• An unticked checkbox that nobody has set is "not set", not "No". Reports filter on what was set.
• CSV export is copy and paste from the report.
• Value changes don't appear in page history, because they don't create page versions. The last 25 changes per page are kept in Pickmark's own log.
• A report can show up to 1,000 rows. A new value can take a few seconds to appear in reports while Confluence indexes it.
• Defaults from a template can't be applied to a page that is restricted so the app can't edit it.

FAQ

Can I list every page that has a particular value? Yes. That is what the Pickmark report does, across one space, several spaces or all spaces, filtered by label, by parent page and by up to 6 conditions.

Can readers filter the report without editing the page? Yes, with Let readers filter and search turned on.

Will changing a value wipe out someone's unpublished draft? No. Pickmark never writes the page body, so drafts and page versions are untouched.

Do I need to refresh the page after changing a value? No. The value updates in place, along with any other copy of that field on the page.

Can a value be set in the editor and shown as plain text? Yes. Choose Here, in the editor only in the macro settings.

Can I bring my option lists and values over from Data Center? Yes. Paste option lists into a field with Paste a list, and import values from a Page Properties Report CSV in Import values. Backup copies field definitions between sites.

Do I need labels to make values searchable? No. Every value is searchable in Confluence and in reports.

What about Confluence's own page status? Confluence gives each page one status. Pickmark adds as many typed fields per page as you need, changed in view mode, with a report that filters and charts their values.

Uninstalling and your data

Copy your reports as CSV and use Show backup first if you want to keep a record. When the app is uninstalled, Atlassian deletes Pickmark's stored field definitions and settings for your site, and the macros stop rendering.

Support

Open a request in the Great Work support portal (linked from the Marketplace listing and from Help and support in Settings > Pickmark fields) or email hello@greatwork.company. We answer within one business day (US Central time). Security reports: within 4 hours.