5.3 Field Configurations, Renderers, Hiding & Required Fields

Field Configurations, Renderers, Hiding & Required Fields

While Custom Fields define what data can be captured and Screens define where fields are visually arranged, Field Configurations define how fields behave. A Field Configuration acts as the behavioral engine for every field in Jira—whether system or custom—dictating whether a field is mandatory, whether it is visible, what help instructions are displayed beneath it, and which rendering engine processes its text.

On the ACP-120 exam, Field Configurations represent one of the most critical testing areas. Many complex troubleshooting scenarios hinge on understanding why an integration broke, why a user cannot submit an issue, or how hiding a field in a Field Configuration fundamentally differs from leaving it off a screen.

---

The Anatomy of a Field Configuration

Field Configurations are managed globally at Cog (Settings) > Issues > Field configurations. Every Jira Cloud instance includes a system-default configuration named Default Field Configuration.

Inside any Field Configuration, every system and custom field in the instance is listed alphabetically, exposing four administrative levers:

+-----------------------------------------------------------------------------------------+
|                                Field Configuration Levers                               |
+-----------------------------------------------------------------------------------------+
| 1. Required / Optional | Enforces whether the field must contain a value (Red asterisk) |
| 2. Hide / Show         | Toggles global visibility on/off for this configuration        |
| 3. Edit (Description)  | Sets contextual help text displayed immediately below field    |
| 4. Renderers           | Selects rendering engine for text fields (Default vs. Wiki)    |
+-----------------------------------------------------------------------------------------+

1. Required vs. Optional

• Required: The field cannot be empty. If a user attempts to create or transition an issue without supplying a value, Jira halts the operation and renders an error banner.
• Optional: The field may remain null/empty.

2. Hide vs. Show

• Hide: The field is completely suppressed from view across the entire project for issue types using this configuration.
• Show: The field is active and eligible to be displayed on screens.

3. Edit (Field Description / Help Text)

• Allows customizing the descriptive text that appears beneath the field input box. This is an enterprise best practice for guiding users on format requirements (e.g., "Enter the 8-digit SAP vendor ID starting with V-").
• Field descriptions configured in a Field Configuration override any global description set on the custom field itself.

4. Renderers

• Applicable to multi-line text (paragraph) and certain system fields (like Environment and Description).
• Toggles between the Default Text Renderer (plain, unformatted monospace or sans-serif text) and the Wiki Style Renderer (rich text rendering supporting bulleted lists, numbered lists, tables, colored text, hyperlinks, inline images, and user @mentions).

---

Field Configuration Schemes: Mapping to Issue Types

A single project often tracks diverse issue types with radically different data requirements. For example, a software project needs Steps to Reproduce to be mandatory on Bug issues, but Steps to Reproduce should not even appear on Story or Task issues.

A Field Configuration Scheme (Cog > Issues > Field configuration schemes) bridges this requirement by mapping specific issue types to distinct Field Configurations within a project.

+-------------------------------------------------------------------------+
|                  Software Field Configuration Scheme                    |
+-------------------------------------------------------------------------+
                                     |
         +---------------------------+---------------------------+
         |                                                       |
         v                                                       v
+---------------------------------+     +---------------------------------+
|        Bug Issue Type           |     |     Default (All other types)   |
|               |                 |     |               |                 |
|               v                 |     |               v                 |
|   "Bug Field Configuration"     |     |  "Standard Field Configuration" |
| - Steps to Reproduce: REQUIRED  |     | - Steps to Reproduce: HIDDEN    |
| - Environment: WIKI RENDERER    |     | - Story Points: OPTIONAL        |
| - Fix Version/s: OPTIONAL       |     | - Due Date: OPTIONAL            |
+---------------------------------+     +---------------------------------+

Unmapped Issue Types and the Default Entry

Every Field Configuration Scheme contains a mandatory entry labeled Default. Any issue type in the project that is not explicitly mapped to a specialized configuration automatically inherits the rules defined in the Default configuration. This ensures that even if a new issue type is later added to the project's Issue Type Scheme, it will always have a valid field configuration.

---

The Cardinal Rule of Required Fields and Creation Failures

One of the most frequent real-world disasters—and classic ACP-120 exam questions—involves breaking issue creation mechanisms by improperly configuring Required fields.

The Golden Rule

[!CAUTION] If a field is configured as Required in a Field Configuration, put it on the Create screen for that issue type (or give it a default value in its context). Automation rules run only after an issue exists, so they can't satisfy a field that's required at creation.

What Happens When This Rule Is Broken?

1. User Web Interface: A user clicks Create, selects the project and issue type, fills out all displayed fields, and clicks Create. Jira attempts to validate the issue against the Field Configuration. Because the required field is empty, validation fails. But because the field was omitted from the Create Screen, the user cannot see the field or enter a value. The UI displays an error: "Field '[Field Name]' is required and cannot be empty." The user is completely blocked from creating work.
2. REST API Integrations: Scripts or CI/CD pipelines calling POST /rest/api/3/issue fail with HTTP 400 Bad Request if they omit the required field. If they try to send it and the field isn't on the Create screen, Jira rejects that too: "Field '…' cannot be set. It is not on the appropriate screen, or unknown." The fix is to put the required field on the Create screen (or supply a default value).
3. Email-to-Issue Handlers: Incoming mail handlers can't ask senders for custom field values. If the project's field configuration makes a field required that the handler can't fill, issue creation from email fails. The handler's Forward Email option sends a status message to an address you choose, which is how admins spot these failures.
4. CSV & External Data Imports: Bulk imports fail on record validation unless the required field is mapped in the CSV import wizard.

---

Hiding via Field Configuration vs. Omitting from a Screen

Understanding the distinction between hiding a field in a Field Configuration versus leaving it off a Screen is a foundational competency tested extensively on the exam.

Scenario: "A 'Risk Score' field must be set only by our vulnerability scanner.
People must never type into it, but analysts must search and report on it."

WRONG: Hide the field in the field configuration.
- Result: The field disappears for those issue types, can't be bulk-edited,
  and can't be set by the scanner.

WRONG: Leave it off every screen and have the scanner call the REST API
with a normal API token.
- Result: The API rejects the update: the field isn't on the appropriate screen.

CORRECT: Keep the field visible (not hidden) in the field configuration, keep it
off the Create and Edit screens, and have the scanner call an automation rule
(for example, an incoming webhook trigger) whose Edit issue action sets it.
- Result: People can't edit it, automation updates it, and it stays searchable.

---

Text Renderers: Default Text vs. Wiki Style Renderer

When a multi-line text field is created, Jira Cloud assigns it the Default Text Renderer. In this mode, text is stored and rendered as raw, plain ASCII/Unicode text.

The Wiki Style Renderer

Switching a field to the Wiki Style Renderer (configured via Field configurations > [Configuration] > [Field] > Renderers) enables rich formatting powered by the Atlassian Document Format (ADF):

• Headings (h1., h2.), bold (*bold*), italics (_italics_), and strikethrough.
• Bulleted lists (*), numbered lists (#), and task checkboxes.
• Data tables with column headers and cell formatting.
• Code blocks with syntax highlighting ({code:java}...{code}).
• Inline macro support and media attachments.
• User mentions (@username) that trigger native Jira notification events.

Administrative Cautions When Changing Renderers

When an administrator switches a field's renderer from Default Text to Wiki Style (or vice versa) on an active instance, Jira displays a warning modal. Changing the renderer affects all existing issues using that Field Configuration. If users previously typed characters like brackets [ ], asterisks *, or braces { } expecting them to display literally, the Wiki Style Renderer may attempt to parse them as markup macros, altering the visual appearance of historical records.