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.

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.7.0 (Forge 6.0.0)

Version 1.7.0 (Forge 6.0.0) ships nine modules. Seven of them keep functional parity with the Data Center add-on. The Attachment Field and the Workflow Expression Condition are Cloud-only in this release.

Upgrade to 1.7.0 — action required

This release introduces Forge Object Store (a major Forge version change). The site administrator must update the installation in Apps → Manage apps and re-consent to the app permissions; otherwise the new modules will not be operational. See the Installation Guide.

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.

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

Attachment Field

• New custom field type to attach files directly to a specific work item field (for example, Invoices, Evidence Photos, PQR Documents).
• Files live inside the field, independently of the work item's native attachments panel.
• Per-context configuration: maximum file count, allowed types (images, spreadsheets, documents, videos, compressed archives), custom extensions, and maximum file size.
• Upload, preview, download, and delete files with their original filename.
• JQL: is EMPTY / is not EMPTY per field.

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

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 have no 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.