Introduction to Admin Essentials

Welcome to the official documentation for Admin Essentials for Jira! 🎉

Admin Essentials — advanced custom fields and workflow extensions for Jira Cloud on Forge.

The add-on is built on Atlassian Forge and distributed through the Atlassian Marketplace, which means it benefits from Atlassian's official platform for security, deployment, and updates.

Introductory video

Learn in just a few minutes what Admin Essentials for Jira is and how it can help you extend Jira Cloud with custom fields and workflow extensions.

Admin Essentials for Jira is available on the Atlassian Marketplace as a paid product with a free trial period. Follow the Installation Guide to install it or start a free trial on your site.

Install from Marketplace

v4.0.0+

From version 4.0.0, editing and configuration of fields and validators requires an active Marketplace license. Values already stored on work items remain visible without a license. See Atlassian Marketplace Licensing for surface-by-surface detail.

Who is this for?

Target audience

Admin Essentials is designed for Jira Cloud administrators, project leads, and operational teams (support, service desks, sales, operations) who need to extend Jira with cross-cutting utilities that cover everyday needs without adding more add-ons to the instance.

What's included in version 1.9.0 (Forge 7.0.0)

Version 1.9.0 (Forge 7.0.0) ships ten modules. Seven of them keep functional parity with the Data Center add-on. The Attachment Field, the Workflow Expression Condition, and the Attachment Count Validator are Cloud-only.

Upgrading from 1.8.0

This is a minor release on top of 1.8.0: it adds JQL search by colour for Traffic Light KPI and Percentage, the attachment count validator, and downloading from the Attachment Field preview. It also fixes saving several files in that field. It includes new permissions that the administrator must approve. See the Installation Guide for update details.

Previous version: 1.8.0 (Forge 6.1.0)

1.8.0 moved the Attachment Field storage to native Jira attachments and its view to cards (thumbnail or icon).

Email Custom Field

• Custom field type that stores a single email address per work item.
• Format validation on the client (while editing) and on the server (via a Jira expression).
• Automatic rendering as a clickable mailto: link on the work item view.
• Inline editing from the work item view, create / edit / transition screens, and the JSM portal.
• JQL search with exact-match string operators (=, !=, in, is EMPTY, etc.).

Traffic Light KPI Custom Field

• Numeric field type rendered as a three-color indicator (🔴 red / 🟡 yellow / 🟢 green).
• Per-context thresholds: different thresholds for different spaces or work types.
• "Lower value is better" mode to invert the color semantics for KPIs where a low value is desirable.
• Descriptive legend and tooltip explaining the active rule.
• Native dark-mode support through UI Kit 2 design tokens.
• JQL search by colour with the trafficLightBand function (for example, issue in trafficLightBand("red")), in addition to the numeric operators on the value.

Phone Number Custom Field

• Stores a single phone number per work item with a searchable country selector (~250 ISO countries) and an inline local number field.
• Default country configurable per context (contextConfig): administrators set the default country per space or work type.
• Consistent validation on client and server (E.164, local formats with separators); total length between 7 and 25 characters (including the dialling code).
• Rendered as 📱 PE +51 943 824 375 with a clickable tel: link.
• Inline editing and JQL search with exact-match operators.

Currency Custom Field

• Numeric field that stores a monetary amount and renders it with a symbol, position, and decimals configurable per context.
• JQL search operates on the stored numeric value, not the formatted string.

Percentage Custom Field

• Numeric field restricted to the 0–100 range, rendered as a progress bar with three colour bands.
• Per-context thresholds (At-risk from, On-track from).
• JQL search by colour with the percentageBand function (for example, issue in percentageBand("green")).

Attachment Field

• Custom field type to attach files directly to a specific work item field (for example, Invoices, Evidence Photos, PQR Documents), keeping each field independent from the others.
• Native Jira attachment storage: files uploaded from this version onward are stored as native attachments of the work item; the field only stores their identifiers and filters the view to the ones that belong to it.
• Card view: each file is shown as a card with a thumbnail (images) or type icon (PDF, Word, Excel…), name, type, and size, plus a preview or download icon. Available on the work item view, the JSM portal, and the agent view.
• Preview with download: images and text files open in a preview window with Download and Close buttons.
• Per-context configuration: maximum file count (1 to 7), allowed types (images, spreadsheets, documents, videos, compressed archives), custom extensions, and maximum file size.
• JQL: is EMPTY / is not EMPTY per field; the native panel query attachments is not EMPTY also detects the field's new files.

"Fields Required" Workflow Validator

• Transition validator that blocks transitions when selected fields are empty.
• Configuration through a dual list (available fields / required fields).
• Custom error message and Ignore context option to enforce validation even on contexts that don't apply.

"Field Dependency" Workflow Validator

• Conditional validator that blocks the transition when a trigger field meets a condition and a required field is empty.
• Multiple rules per validator, each with its own custom error message.
• List triggers (Priority, Issue Type, Single-select List, Radio Buttons), numeric triggers (Currency, Percentage, Traffic Light KPI) and text triggers (Email, Phone Number).
• Numeric operators (=, !=, <, <=, >, >=) and text operators (equals, does not equal, contains, is empty, is not empty).

"Attachment Count" Workflow Validator

• Transition validator that blocks transitions when an Attachment Field has fewer or more files than configured.
• Minimum, maximum, or both per field, for one or more Attachment Fields in the same validator.
• Optional custom error message; by default, the message names the field, the limit, and the current count.
• Files added on the transition screen are counted too.

Workflow Expression Condition

• New workflow condition that hides the transition button when the work item does not meet a Jira expression.
• Unlike validators, it acts before the attempt: if the work item does not meet the criterion, the button does not appear.
• Useful for simplifying the workflow view by removing options that do not apply.
• Available only in company-managed spaces.

Differences from the Data Center version

Aspect	Data Center	Cloud (Forge)
Platform	Traditional plugin (P2)	Atlassian Forge
Distribution	.jar / .obr file	Atlassian Marketplace
Licensing	Atlassian plugin license	Marketplace license (edit/config require active license from v4.0.0)
UI technology	Velocity / AUI	UI Kit 2 (@forge/react) + Custom UI
Compatibility	Jira Data Center 10.3.18+	Jira Cloud (any site)
Updates	Manual by the administrator	Automatic, except major Forge version upgrades (e.g. 1.7.0) that require Update and re-consent
Dark mode	Classic CSS styling	Native via design tokens

Cloud

If you're already familiar with Admin Essentials for Jira Data Center, you'll find an equivalent Cloud experience for Email, Traffic Light KPI, Phone, Currency, Percentage, and the Fields Required and Field Dependency validators. The Attachment Field and the Workflow Expression Condition were added in 1.7.0, and the Attachment Count Validator in 1.9.0. None of them has a Data Center equivalent. Platform differences are concentrated in installation (Marketplace), licensing, screen configuration, and field administration.

Compatibility

• Jira Cloud: Any Jira Cloud site (Free, Standard, Premium, Enterprise).
• Jira Service Management (JSM): Custom fields work on the agent view and the customer portal.
• Platform: Atlassian Forge, runtime nodejs24.x.

Welcome to Admin Essentials: the essentials so your Jira Cloud speaks the same language as your processes.