> For the complete documentation index, see [llms.txt](https://docs.forgappify.com/field-rules/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.forgappify.com/field-rules/rules/use-description.md).

# Use description: change a Jira field's hint text based on conditions

Change a Jira field's description (hint text) based on work type, user, group, role, or another field's value. Dynamic field guidance, no scripting.

Field Rules can override a Jira field's description - the hint text shown below it - based on conditions, so users get the right guidance at the right moment. Explain what a field should contain, warn about its current state, or adapt the hint by work type, user, group or role, or another field's value, with no code.

***

## How to set it up

1. Open the **UI Modification** for the context you want to control (space, work type, and view).
2. Add a **Use description** rule and choose the field under **Field name**.
3. Enter the **Description** text to show (up to 255 characters). Basic wiki markup - bold, links, color, and a few block styles - is supported; see [Formatting the description](#formatting-the-description) below.
4. Add **preconditions** - field values and/or user identity - that determine when the custom description appears. When conditions are not met, the field's original description is restored automatically.
5. Save. The description updates in real time as the user fills in the form, no reload required.

<figure><img src="https://1561395444-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOfQTst0rZQxXAZF84TB5%2Fuploads%2Fgit-blob-9f6f7ccee65fc03d415f09d55c5f48ba82bb8689%2Fuse-description-rule-summary-hint-for-bugs.png?alt=media" alt="Configuring a Use description rule that changes the Summary field&#x27;s hint text when Issue Type is Bug"><figcaption><p>Showing a bug-specific hint for Summary only when the Issue Type is Bug.</p></figcaption></figure>

| Option            | Description                                                                                                                                                 |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Field name**    | The field whose description will be overridden.                                                                                                             |
| **Description**   | The text to display as the field's description. Maximum 255 characters. Leave it empty to hide the field's description.                                     |
| **Preconditions** | Optional field and/or user conditions. When conditions are met the custom description is shown; when they are not met the original description is restored. |

***

## How it works

When the screen loads and the configured preconditions pass, the rule replaces the field's description with the configured text. If the preconditions later become false (for example, because the user changes a watched field), the description reverts to its original value automatically.

The description text is limited to 255 characters. Leave it empty to hide the field's description while the conditions are met.

***

## Formatting the description

Description text is not limited to plain text - it is rendered through Jira's wiki markup engine, the same one used for other field descriptions. Combine several styles at once, for example a titled panel with bold text, a line break, a link, and colored text:

<figure><img src="https://1561395444-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOfQTst0rZQxXAZF84TB5%2Fuploads%2Fgit-blob-ee3312c519a759ed02a0123e0644384f5fe53438%2Fuse-description-rule-summary-formatted-tips.png?alt=media" alt="A Summary field on the create screen with a rendered description panel titled Summary tips, showing bold text, a line break, a hyperlink to a reporting guide, and a red PII warning"><figcaption><p>A single description string rendered as a titled panel with bold text, a link, and a red warning.</p></figcaption></figure>

That result comes from one description string:

```
{panel:title=Summary tips}*Be specific* - describe the exact steps and expected result.\\See the [reporting guide|https://intranet.example.com/reporting-guide] for the full template. {color:red}Avoid pasting customer PII.{color}{panel}
```

The table below breaks down the individual markup used above, and a few more styles, next to how each one renders on its own.

**Inline styles**

| Markup                     | Renders as                               |
| -------------------------- | ---------------------------------------- |
| `*bold*`                   | **bold**                                 |
| `_italic_`                 | *italic*                                 |
| `-strikethrough-`          | ~~strikethrough~~                        |
| `{{monospace}}`            | `monospace`                              |
| `[link text\|https://...]` | [link text](#formatting-the-description) |
| `:)` `:(` `(y)`            | 🙂 🙁 👍                                 |

`{color:red}...{color}` is also supported (as well as `blue`, `green`, `yellow`, `purple`, and a few other named colors) - see the red warning text in the screenshot above for how it renders. `+underline+` is supported too, it just has no direct equivalent to preview in this documentation format.

**Block styles**

`{quote}...{quote}` renders as a blockquote:

> Select the reason for rejection - this will be visible to the reporter.

`{code}...{code}` and `{code:java}...{code}` render as a syntax-highlighted code block:

```
reason: "Cannot reproduce"
```

`{noformat}...{noformat}` renders as a plain monospace block, with any markup inside left un-interpreted.

`{panel:title=...}...{panel}` renders as a titled, colored panel - see the "Summary tips" screenshot above for a real example.

**Not supported** - these render as literal text with the markup characters visible: headings (`h1.`), bullet and numbered lists (`*`, `#`), tables (`\|\|Header\|\|`), horizontal rule (`----`), and superscript/subscript (`^text^`, `~text~`).

***

## Preconditions and rollback

When preconditions are configured, the description behaves dynamically:

* **Conditions met** - the custom description is displayed.
* **Conditions not met** - the field reverts to its original description.

This allows the description to change in real time as the user fills in the form, without requiring a page reload.

***

## Examples

**Explain a locked field**\
When a field is locked using the [Lock field](https://docs.forgappify.com/field-rules/rules/lock-field.md) rule, override its description to explain why editing is disabled, e.g. "This field is managed automatically and cannot be edited."

**Context-sensitive guidance**\
When the Issue Type is set to "Bug", override the Summary field description to "Briefly describe the problem, e.g. 'Login fails on Safari 17'." When the Issue Type is anything else, the original description is shown.

**Role-based hint**\
When the current user belongs to the "Support" group, override the Priority field description with "Set based on customer SLA, see the priority guide for reference."

**Transition warning**\
When a "Reject" transition screen loads, override the Resolution field description with "Select the reason for rejection. This will be visible to the reporter."

**Formatted hint with a link**\
Override the Priority field description with `*Set based on customer SLA* - see the [priority guide|https://intranet.example.com/priority-guide] for reference.` The bold phrase and the link render directly in the hint text below the field.

**Same hint across several request types**\
On the JSM portal, override a "Category" field's description with guidance that applies equally to "Report a bug" and "Request a feature" requests, using a Request Type condition set to "is one of" both. One rule reaches every matching request type, instead of repeating the text in each request type's own Request Form settings.

***

## When to use it

Use Use description whenever a field's meaning changes depending on context, and a static hint would be wrong some of the time:

* **Pair it with another rule** - explain why a field is [locked](https://docs.forgappify.com/field-rules/rules/lock-field.md) or [required](https://docs.forgappify.com/field-rules/rules/make-field-required.md) so the restriction doesn't feel arbitrary.
* **Work-type-specific guidance** - give the same field a different hint depending on what is being created.
* **Guide users on the JSM portal** - adjust request-form hints based on what the customer has already entered.
* **Add emphasis or a link** - bold a key phrase, link to an internal guide, or color a warning using wiki markup, so the hint itself carries more information. See [Formatting the description](#formatting-the-description).

***

## Doing this without Field Rules

To give a field a different description per work type without an app, Jira's traditional approach was the same detour as required fields: create a separate Field Configuration with the custom description, and map it to its work types through a Field Configuration Scheme. A one-field, one-work-type change meant creating and maintaining a whole extra configuration bundling every other field's required, optional, and hidden state along with it.

A Field Scheme's "Replace field description on work types" setting replaces that: pick the work types (or "All work types") directly on the field, in the scheme, and write the override in a rich text editor - no separate configuration objects needed. This is effectively the same idea as the Use description rule with an Issue Type condition - a field whose hint text changes depending on what's being created - except it's a static setting an admin writes ahead of time, not a rule.

The difference is what the description can react to, and when. A Field Scheme's override only varies by work type, and it's fixed the moment an admin saves it. Use description can react to work type too, but also to the value of any other field, or to who the user is - their group, role, or identity - and it updates live as the user fills in the form, not just when the screen first loads. Native Jira has no equivalent for those cases.

None of this applies on the JSM customer portal - neither the field's base description nor a Field Scheme's override is shown on the Create Request form. Portal help text is a separate mechanism: each request type's own Request Form settings, configured one request type at a time. Giving the same hint to several request types means repeating it in every request type's settings individually. Use description covers the portal too, and with one rule you can target several request types at once with a Request Type condition, instead of repeating the same text across each request type's settings.

Conditions beyond work type, and real-time reactivity, require a UI Modifications app like Field Rules or a scripting app. Field Rules closes this gap with a no-code, visually configured rule - no developer required.

See [Field Rules vs native Jira](https://docs.forgappify.com/field-rules/jira-administrator/field-rules-vs-native-jira.md) for the full comparison across every rule.

***

## Supported fields

The JSM Agent views behave like their standard equivalents.

| Field type        | Global Issue Create | Issue View | Issue Transition | JSM Request Create |
| ----------------- | ------------------- | ---------- | ---------------- | ------------------ |
| Assignee          | Yes                 | Yes        | Yes              | No                 |
| Affects versions  | Yes                 | Yes        | Yes              | No                 |
| Cascading select  | Yes                 | Yes        | Yes              | Yes                |
| Checkboxes        | Yes                 | Yes        | Yes              | No                 |
| Components        | Yes                 | Yes        | No               | No                 |
| Date picker       | Yes                 | Yes        | Yes              | Yes                |
| Date time         | Yes                 | Yes        | Yes              | Yes                |
| Description       | Yes                 | No         | Yes              | Yes                |
| Due date          | Yes                 | No         | No               | Yes                |
| Fix versions      | Yes                 | Yes        | Yes              | No                 |
| Labels            | Yes                 | Yes        | Yes              | Yes                |
| Multi select      | Yes                 | Yes        | Yes              | Yes                |
| Multi user picker | Yes                 | Yes        | Yes              | No                 |
| Number            | Yes                 | Yes        | Yes              | Yes                |
| Original estimate | No                  | Yes        | Yes              | No                 |
| Paragraph         | Yes                 | Yes        | Yes              | Yes                |
| Parent            | Yes                 | Yes        | Yes              | No                 |
| People            | Yes                 | Yes        | No               | No                 |
| Priority          | Yes                 | No         | Yes              | Yes                |
| Project picker    | Yes                 | Yes        | Yes              | No                 |
| Radio buttons     | Yes                 | Yes        | Yes              | No                 |
| Reporter          | Yes                 | Yes        | Yes              | No                 |
| Resolution        | No                  | No         | Yes              | No                 |
| Select            | Yes                 | Yes        | Yes              | Yes                |
| Summary           | Yes                 | No         | Yes              | Yes                |
| Target end        | Yes                 | No         | No               | No                 |
| Target start      | Yes                 | No         | No               | No                 |
| Text field        | Yes                 | Yes        | Yes              | Yes                |
| URL               | Yes                 | Yes        | Yes              | No                 |
| User picker       | Yes                 | Yes        | Yes              | Yes                |

***

## Limitations

* **Issue Type** does not support this rule on any view.
* Description text is capped at **255 characters**.
* Wiki markup is not rendered on the JSM Request Create (Portal) screen, it shows as literal text.

***

## Related rules

* [Lock field](https://docs.forgappify.com/field-rules/rules/lock-field.md) - explain why a field is locked.
* [Make field required](https://docs.forgappify.com/field-rules/rules/make-field-required.md) - explain why a field is required.
* [Show field](https://docs.forgappify.com/field-rules/rules/show-field.md) - show or hide a field based on conditions.
