Frequently Asked Questions (FAQ)
Below are some of the most common questions about configuring and using Admin Essentials for Jira.
Q: Which version do I have installed?
A: The verifiable version in Jira Cloud is the one shown in Apps → Manage apps (for example, 4.2.0). That is the Forge version.
On this documentation site, the version selector shows the Forge version for releases published to production. See the mapping table in the changelog to relate each MB Group release to its Forge version.
Q: What's the difference between the Cloud and Data Center versions of the add-on?
A: Both versions share the same feature set for the modules covered by this release (Email, Traffic Light KPI, Phone, Currency, Percentage, Fields Required and Field Dependency validators). The Cloud version is built on Atlassian Forge and distributed through the Atlassian Marketplace with Atlassian licensing, while the Data Center version is installed manually as a .jar plugin. The end-user experience is equivalent; the differences are concentrated in the installation, licensing, configuration, and update flows.
Q: How do I purchase or renew a license for Admin Essentials for Jira?
A: Licensing is managed through the Atlassian Marketplace and appears on your site's consolidated billing. A site administrator can buy or renew from Settings → Billing → Manage subscriptions, or from Apps → Manage apps → Admin Essentials for Jira. You can also start a 30-day free trial when installing from the Marketplace. See the Installation Guide and Marketplace Licensing.
Q: What happens if the license expires or is inactive?
A: Values already stored on issues remain visible in view mode, with an informational banner. Editing fields, configuring contexts (thresholds, currency, country, etc.), and creating or editing validators are blocked with a License required message. Users should contact their Jira administrator to renew the Marketplace license.
Q: Why does a workflow validator still block transitions after the license expired?
A: Rules saved inside a workflow validator cannot check license state when a transition runs. This is a Jira platform limitation. License protection applies when configuring validators, not when they run. To stop enforcement after expiry, the administrator must remove or disable the validator in the workflow. More detail in Marketplace Licensing.
Q: I installed via a direct Forge link before Marketplace listing — is that still valid?
A: Sites that installed through a direct Forge link move to the Marketplace licensing model when updating to version 4.0.0 or later. Manage the license from Atlassian's billing panel like any other Marketplace app. For commercial support, contact MB Group at support@mbgroup.pe.
Q: Why does Jira refuse to save the issue and show an error on the Email field?
A: The add-on validates the email format via a server-side Jira expression. The error appears when: 1) the text doesn't match a standard email shape (missing @, has spaces, or has multiple @), 2) the address exceeds the 254-character total limit, or 3) the part before the @ exceeds the 64-character local-part limit. Fix the address and try again.
Q: Does validation also run if I create or update issues through the REST API?
A: Yes. Validation runs on the server as part of the standard Forge custom field lifecycle, so it applies uniformly from Jira screens, the Jira Cloud REST API, and external integrations. This prevents invalid addresses from slipping in through alternative paths.
Q: Can I search issues by the Email field value in JQL?
A: Yes, using exact-match operators: =, !=, in, not in, is EMPTY, is not EMPTY. For example: "Field name" = "user@example.com". The partial-match operators (~, !~) are not compatible with Forge string custom fields; this is an Atlassian platform limitation, not an add-on issue.
Q: I created an Email field but users don't see it on the issue screen. What's missing?
A: In Jira, custom fields only appear on the screens they are explicitly associated with. Make sure the field is included in the relevant project's screen scheme (typically the create, edit, and view screens). On Jira Cloud this is managed under Project settings → Issues → Screens or in global screen administration.
Q: I created a Traffic Light KPI field, set a value on an issue, and the indicator shows gray. What's missing?
A: The Traffic Light field renders gray as long as the field's context has no thresholds (Low threshold and High threshold) configured. Go to Settings → Issues → Custom fields, open the field's actions menu (⋯) → Contexts and default value, pick the relevant context, and fill in the thresholds under Traffic Light thresholds. Once saved, issues in that context will start showing the resolved color.
Q: Can I have different thresholds per project on the same Traffic Light KPI field?
A: Yes. The field's thresholds are stored per context. Create one context per project or issue type you want to assign different rules to, and define independent thresholds in each from Contexts and default value.
Q: What exactly does "Lower value is better" do?
A: It inverts the color assignment without changing the threshold order. In the default mode, low values = red and high values = green. With "Lower value is better" enabled, low values = green and high values = red. It's useful for KPIs like resolution time, open defects, or delays, where a lower value indicates better performance. The legend and tooltip update automatically.
Q: Can the Traffic Light KPI field be used in JQL?
A: Yes. The field is registered in Forge with type: number, so it supports the standard numeric operators (=, !=, <, <=, >, >=, is EMPTY, is not EMPTY, in, not in). Queries operate on the stored numeric value, not on the resolved color.
Q: Is the add-on compatible with Jira Service Management (JSM)?
A: Yes. The add-on's field types declare the portal-view and portal-request experiences, so they render correctly on the agent view and the customer portal of JSM. Editing and validation work the same way as on Jira Software or Jira Work Management projects.
Q: Is the add-on compatible with Jira Cloud's dark mode?
A: Yes. The Traffic Light KPI indicator, its legend and tooltip, and the Email field are built with UI Kit 2 design tokens (color.text, color.text.subtlest, etc.). Colors adjust automatically to the active theme (light or dark) while keeping accessible contrast.
Q: The "Fields Required" validator skips a custom field even though I selected it. Why?
A: By default, the validator skips custom fields that are not configured for the project or issue type the transition runs against. This is intentional when the same workflow is reused across projects with different schemes. To enforce the field anyway, tick the Ignore context checkbox when editing the validator.
Q: Can the Cloud add-on coexist with the Data Center version of the same add-on?
A: Yes — they are independent products on different platforms. An organization can have the DC version on its Data Center instance and the Cloud version on its Atlassian Cloud site in parallel, with no conflict.
Q: Are the add-on's updates automatic?
A: Yes. Forge apps update automatically from Atlassian's infrastructure, with no manual administrator intervention. If a future version introduces new permissions (scopes), Atlassian will notify you and request explicit approval before applying the update.
Q: Which phone number formats does the Phone Number Field accept?
A: The field accepts E.164 (+51 999 888 777, +1 800 555 0100) and local formats with separators (999-888-777, (01) 234-5678), with total length between 7 and 25 characters. Only digits and the visual separators +, space, ., -, (, ) are accepted. If the value fails the rules, Jira shows "The value is not a valid phone number." and blocks the save.
Q: The Currency field shows the value without a symbol — why?
A: The currency symbol, its position and the decimals are configured per field context. As long as a context has no saved configuration, values render as a plain number (1,500.00) using the user's locale. Go to Settings → Issues → Custom fields, open the field's ⋯ menu → Contexts and default value, select the context and complete Currency symbol, Symbol position and Decimal places in the Currency display section.
Q: Can I have different currencies on the same Currency field, depending on the project?
A: Yes. Configuration (symbol, position, decimals) is stored per context of the custom field. Create a context for each project or issue type you want to assign a different currency to, and save the matching configuration in each one. There's no need to duplicate the field.
Q: The Percentage field's bar shows in a colour I didn't expect — why?
A: The bar colours depend on the thresholds defined for the field's context. When a context has no thresholds configured, the add-on applies defaults (red < 40, yellow 40–69, green ≥ 70). If you need different thresholds, go to the field's Contexts and default value page and set At-risk from and On-track from in the Percentage colour thresholds section.
Q: What's the difference between the Fields Required and Field Dependency validators?
A: Fields Required enforces one or more fields on every transition. Field Dependency enforces a field only when another field holds a specific value (e.g. "require Assignee only when Priority is Highest"). Both validators can coexist on the same transition: the first one covers always-required fields and the second one layers conditional rules on top.
Q: Can I use a text or numeric field as the trigger for the Field Dependency validator?
A: Yes, since version 3.1.0. In addition to fields with discrete values (Priority, Issue Type, Single-select List and Radio Buttons), the validator supports numeric fields (Currency, Percentage, Traffic Light KPI) with =, !=, <, <=, >, >= operators, and text fields (Email, Phone Number) with equals, does not equal, contains, is empty and is not empty operators.
Q: Why did the Cancel/Save buttons disappear from inside the add-on fields on the issue-create screen?
A: In version 3.0.0 we removed those internal buttons because they duplicated Jira's native Create / Cancel dialog buttons. The new integration feels more natural: the field stops behaving like a separate mini-form and validates alongside the rest of the dialog when the user clicks Create. Validation and save behaviour are unchanged: if the entered value is invalid, the field shows the error and blocks the dialog submission until it's fixed.