Frequently Asked Questions (FAQ)
Below are some of the most common questions about configuring and using Admin Essentials.
Q: Why won't Jira let me save the issue and shows an error on the Email field?
A: The add-on validates email format on the server. The error appears when: 1) the text does not match a standard email format (for example, missing @ or containing spaces), 2) the address exceeds the 254 characters allowed in total, or 3) the part before @ exceeds 64 characters. Correct the address and save again.
Q: Does validation also apply when I create or update issues through the REST API?
A: Yes. Validation runs on the server as part of Jira's standard custom field lifecycle, so it applies uniformly from Jira screens, the REST API, importers, and external integrations. This prevents invalid addresses from entering through alternate paths.
Q: Can I search for issues by Email field value from JQL?
A: Yes. The field is registered with a searcher integrated with Jira's engine. You can use queries such as "Field Name" = "client@example.com", replacing Field Name with the exact name assigned when creating the custom field.
Q: I created the field, but users don't see it on the issue screen. What's missing?
A: In Jira, custom fields only appear on screens they have been explicitly associated with. Verify that the Email field is included in the project's screen scheme (for example, on the default, create, and edit issue screens).
Q: Can I store more than one email address in the same field?
A: No. The Email field stores a single address per issue. If you need to capture multiple addresses (for example, a notification list), we recommend creating separate Email fields or using a free-text field with an internal convention.
Q: What happens if the field is not marked as required and a user leaves it blank?
A: An empty value is valid when the field is not required in the project configuration. No error will be shown and the issue can be saved normally.
Q: Why is the plugin now called "Admin Essentials"?
A: Starting with version 1.0.0, the add-on officially adopts the name Admin Essentials to reflect its nature as a multi-module suite of utilities for Jira administrators. The first release includes the Email field; future releases will add new modules under the same package.
Q: I created a Traffic Light field, assigned a value to an issue, and the indicator appears gray. What's missing?
A: The Traffic Light field renders in gray while the field context has no thresholds (Red max and Yellow max) configured. Go to Jira Administration > Issues > Custom fields, open the field configuration, locate the Thresholds row for the corresponding context, and click Edit to define the thresholds. Once saved, issues in that context will begin showing the resolved color.
Q: Can I have different thresholds per project on the same Traffic Light field?
A: Yes. Traffic Light thresholds are stored per context (FieldConfigContext). Create one context for each project or issue type you want to assign different rules to, and define each context's thresholds independently from the field configuration page.
Q: Can the Traffic Light field be used in JQL?
A: Yes. The field is registered with Jira's standard Number Range Searcher, so it supports the usual numeric operators (=, <, <=, >, >=). For example: "Compliance level" < 30. Remember that queries operate on the stored numeric value, not the resolved color.
Q: Can I filter "red", "yellow", or "green" Traffic Light issues in JQL?
A: Yes, but not with a color syntax such as "My Field" = "RED". In Jira, JQL queries the stored numeric value, so you must translate each zone into a numeric range using the relevant context thresholds (Red max and Yellow max). For example, in the default mode, the red zone is expressed as "My Field" <= <LOW>. For more detail, see the Filtering Traffic Light zones with JQL section in the Traffic Light KPI field guide.
Q: Does version 2.0.0 work on Jira 10?
A: No. Version 2.0.0 requires Jira Data Center 11.3 or later (Java 21) and is not compatible with Jira 10.x. If your site remains on Jira 10.x, continue using version 1.4.0.
Q: Do I need to reconfigure fields, thresholds, or workflow rules when upgrading to version 2.0.0?
A: No. Version 2.0.0 is a platform update: existing fields, thresholds, contexts, and workflow rules remain unchanged after the upgrade.
Q: What limits does the Attachment Field have, and who configures them?
A: The limits are defined by the Jira administrator in each field context: maximum number of files (a whole number between 1 and 100; default 5), allowed file types (Images, Sheets, Documents, Videos, and Archives, plus custom extensions), and maximum size per file in KB, MB, or GB (default 10 MB; if left empty, there is no size limit). If no type group is checked, any file is allowed.
Q: How is the Attachment Field different from Jira's native attachments panel?
A: The Attachment Field is stored as native Jira attachments, but it is a filtered view: it only shows the files uploaded through that specific field, while the issue's Attachments panel lists all attachments on the issue, no matter where they came from. The field also applies the quantity, type, and size restrictions configured by the administrator, which the native panel does not. Field files also appear in the native panel and are detected by attachments is not EMPTY, but the panel cannot tell you which field each file comes from.
Q: Can I search issues by file name or file type in the Attachment Field using JQL?
A: No. The field only supports the is EMPTY and is not EMPTY operators on the field name, which let you filter issues that have or do not have files in that field (for example, "Invoices" is not EMPTY). It is not possible to search by file name, extension, or type, neither on the field nor on the native attachments panel.
Q: Does the Attachment Field require Jira Service Management?
A: No. The add-on works as usual without JSM: the field is available on the issue view, create, edit, and transition screens. If your instance has Jira Service Management, the administrator can additionally enable the field on the customer portal, so customers can attach files when raising a request and see them in the request details. It is a per-context option and is disabled by default.
Q: What happens when I remove a file from the Attachment Field?
A: When you remove a file and save, the corresponding native attachment is permanently deleted from the issue; it cannot be recovered. Jira asks for confirmation first ("Remove {file}? It will be permanently deleted when you save.").
Q: What happens to Attachment Field files if I uninstall the add-on?
A: Files uploaded to the field are native Jira attachments and remain on the issue even if the add-on is uninstalled; only the custom field and its context configuration become unavailable.
Q: Can I have several Attachment Fields on the same issue?
A: Yes. Each field keeps its own list of files, independent of the others, with its own quantity, type, and size limits. An "Invoices" field and a "Photo evidence" field on the same issue do not mix their files, even though both also appear in the native attachments panel.
Q: Can I save the issue while a file is uploading?
A: No. While an upload is in progress, Jira blocks saving or creating the issue and shows the notice "Wait until the files finish uploading before saving or creating the issue.". Wait for the upload to finish and then save; the files will be associated with the field automatically.