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 Email, Traffic Light KPI, Phone, Currency, Percentage, and the Fields Required and Field Dependency validators. The Cloud version is built on Atlassian Forge and distributed through the Atlassian Marketplace; the Data Center version is installed as a .jar plugin. The Attachment Field and the Workflow Expression Condition are Cloud-only (release 1.7.0) and have no Data Center equivalent. For the shared modules, the end-user experience is equivalent; differences are concentrated in installation, licensing, configuration, and updates.
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 work items 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 work item 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 work items 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 work items 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 work item 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 space's screen scheme (typically the create, edit, and view screens). On Jira Cloud this is managed under Space settings → Work items → Screens or in global screen administration.
Q: I created a Traffic Light KPI field, set a value on a work item, 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 → Work items → 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, work items in that context will start showing the resolved color.
Q: Can I have different thresholds per space on the same Traffic Light KPI field?
A: Yes. The field's thresholds are stored per context. Create one context per space or work 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 spaces.
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 space or work type the transition runs against. This is intentional when the same workflow is reused across spaces 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: In general, yes. Forge apps update automatically from Atlassian's infrastructure. If a version introduces new permissions (scopes) or a major Forge version change, Atlassian requests explicit approval before applying it.
Exception — 1.7.0 (Forge 6.0.0): this release incorporates Forge Object Store and requires the site administrator to go to Apps → Manage apps, click Update, and re-consent to the app permissions. Until then, the Attachment Field and the Workflow Condition are not operational. See the Installation Guide.
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 → Work items → 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 space?
A: Yes. Configuration (symbol, position, decimals) is stored per context of the custom field. Create a context for each space or work 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 work item-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.
Q: What do I need to do when upgrading to version 1.7.0?
A: Complete two steps: Update in Apps → Manage apps, then re-consent to the permissions Atlassian prompts for (Object Store / major Forge version). Without both, the new modules will not work. Field and validator configurations from 1.6.0 are preserved; the Attachment Field and the Workflow Condition are configured from scratch. Details are in the Installation Guide.
Q: What is the difference between the Attachment Field and Jira's native attachments panel?
A: They are independent storage mechanisms. Files uploaded to the Attachment Field live inside that specific field and do not appear in the work item's native Attachments panel. The JQL query attachments is not EMPTY does not detect files in the Attachment Field; to filter work items with files in the field, use "Field name" is not EMPTY. The Attachment Field is designed to categorise documents by type or stage (Invoices, Evidence Photos, PQR Documents) independently of the native panel and of attachments in other fields on the same work item.
Q: Can I search by filename or file type in the Attachment Field using JQL?
A: No. The Attachment Field only supports the is EMPTY and is not EMPTY operators in JQL, which allow filtering work items that do or do not have files in that field. Searching by filename, extension, or file type is not possible via JQL.
Q: What happens to the files in the Attachment Field if I delete the work item?
A: Deleting the work item does not automatically delete the files from the Forge Object Store. The objects remain in storage and are no longer accessible from Jira. To avoid orphaned objects, it is recommended to delete the files from the field (in edit) before deleting the work item. This is a current limitation of the Forge Object Store (Preview) platform.
Q: What is the difference between a workflow condition and a validator?
A: A condition acts before the transition attempt: if the work item does not meet the criterion, the transition button simply does not appear. A validator acts after: the button is always shown, but when the user confirms the transition, it is blocked with an error message if the rules are not met. Use the condition when you want to simplify the workflow view by hiding transitions that do not apply. Use the validator when you want the user to always see the transition, but with explicit verification on confirm.
Q: Does the Workflow Expression Condition use classic JQL?
A: No. The condition evaluates Jira expressions, which is Atlassian Forge's own expression language. It does not support history operators such as WAS or CHANGED, nor free JQL syntax. Queries must be written as boolean expressions on work item fields (for example, issue.priority != null && issue.priority.name == 'High'). See the Expression Condition Guide for examples.
Q: Is the Workflow Expression Condition available in team-managed spaces?
A: No. The condition is available only in company-managed spaces. Team-managed spaces do not support third-party workflow extensions. Additionally, the underlying module (jira:workflowCondition) is currently in Preview status on the Atlassian Forge platform, which means its capabilities and availability may change in future versions.