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.

How to get this add-on?

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 evaluation on your site.

License required (v4.0.0+)

From version 4.0.0, editing and configuration of fields and validators requires an active Marketplace license. Values already stored on issues 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 4.0.0

The current Cloud release ships seven modules with functional parity to the Data Center version of the add-on in the areas covered:

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 issue view.
• Inline editing from the issue 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 projects or issue 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.

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 project or issue 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).

"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).

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 from Atlassian
Dark mode	Classic CSS styling	Native via design tokens

Already using the Data Center version?

If you're already familiar with Admin Essentials for Jira Data Center, you'll find a functionally equivalent experience in the Cloud version for the modules included in this 4.0.0 release. Differences are concentrated in the installation (Marketplace), licensing, screen configuration, and field administration flows, which on Cloud follow the native patterns of Forge and Jira Cloud's admin UI.

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.