# Setup guide

This guide walks through installing Field Rules and creating your first UI Modification.

***

## Installation

Install **Field Rules - UI Modifications for Jira** from the [Atlassian Marketplace](https://marketplace.atlassian.com/apps/1235577/field-rules-ui-modifications-for-jira?hosting=cloud\&tab=overview). Once installed, open Jira settings and navigate to **Apps > Field Rules - UI modifications**.

***

## Core concept

The central unit in Field Rules is the **UI Modification (UIM)**. Each UIM defines:

* **Where it applies** - a combination of projects, issue types, view types, and optionally JSM portals and request types
* **What it does** - an ordered list of rules that run when a user opens a matching screen

A UIM is matched against the user's current context when they open a screen. If the project, issue type, and view all match, the UIM's rules are evaluated.

***

## Supported view types

| View                    | Description                                                          |
| ----------------------- | -------------------------------------------------------------------- |
| **Global Issue Create** | The create issue dialog, available across all projects               |
| **Issue View**          | The issue detail page where users read and edit existing issues      |
| **Issue Transition**    | Screens shown when moving an issue through workflow statuses         |
| **JSM Request Create**  | The customer-facing request form on a Jira Service Management portal |

A single UIM can cover multiple view types at once - for example, Global Issue Create and Issue View together. Rules within the UIM that do not support a given view type are automatically skipped on that view.

***

## Creating a UI Modification

{% stepper %}
{% step %}

#### Click **Create UI modification**

Start the creation flow for a new UIM.
{% endstep %}

{% step %}

#### Enter a **name** and an optional **description**

Use something that makes the purpose clear - for example: "Bug fields - Software team" or "Onboarding project - create and view".
{% endstep %}

{% step %}

#### Configure the context

* On the **Jira** tab: select one or more Jira view types (Global Issue Create, Issue View, Issue Transition), then select the projects and issue types where this UIM should apply.
* On the **Jira Service Management** tab: select JSM Request Create, then select the portals and request types where this UIM should apply.
* You can configure both tabs in a single UIM if you need the same rules to apply on both Jira and JSM screens.
  {% endstep %}

{% step %}

#### Click **Save**

The UIM is now created with no rules. Open it to start adding rules.

New UIMs are **enabled** by default. You can toggle this at any time from the UIM settings.
{% endstep %}
{% endstepper %}

***

## Enabling and disabling a UIM

Each UIM has an **Enable** toggle, accessible both from the main configuration view and from within the UIM itself. When a UIM is disabled, it is completely inactive - its rules do not run, and none of its fields are registered for change tracking. Users see the screen exactly as they would without the app.

This is useful in several situations:

**Testing a new configuration** - build and configure a UIM while it is disabled, then enable it when you are ready for users to see it.

**Quick rollback** - if a UIM is causing unexpected behaviour, disable it immediately to restore the original screen while you investigate.

**Seasonal or temporary rules** - disable a UIM when the rules are not needed rather than deleting and recreating it.

***

## Adding rules

Inside a UIM, click **Add rule** and select a rule type.

| Rule                            | When to use it                                                       |
| ------------------------------- | -------------------------------------------------------------------- |
| **Show field**                  | Show or hide a field based on conditions                             |
| **Make field required**         | Enforce a field as required under specific conditions                |
| **Pre-fill field**              | Seed a field's value when the screen loads                           |
| **Change field value**          | Update a field automatically when the user changes another field     |
| **Lock field**                  | Prevent editing a field for specific users or situations             |
| **Hide field options**          | Filter the available options in a dropdown or selection field        |
| **Hide issue types**            | Restrict which issue types appear on the create or transition screen |
| **Enable self-assignment only** | Enforce that users can only assign issues to themselves              |
| **Use description**             | Show contextual hint text on a field                                 |

{% stepper %}
{% step %}

#### Choose the **target field**

The field the rule will act on.

Some rules - Enable self-assignment only and Hide issue types - always target a fixed field and skip this step.
{% endstep %}

{% step %}

#### Configure the rule-specific settings

Set up the behaviour for the selected rule type.
{% endstep %}

{% step %}

#### Optionally, add **preconditions**

Use preconditions to control when the rule applies.
{% endstep %}

{% step %}

#### Save the rule

Each rule documents which view types it supports. Rules that do not support the current view type are skipped automatically - no error is shown to the user.
{% endstep %}
{% endstepper %}

***

## Configuring preconditions

Preconditions are optional. When left empty, a rule always applies to every user who opens a matching screen. When configured, the rule only runs if the conditions are met at evaluation time.

There are two types of preconditions:

**Field conditions** check the current value of another field on the screen. For example: "Issue Type equals Bug" or "Priority is one of High, Critical". A wide range of operators is available, tailored to the type of field being checked.

**User conditions** check who the current user is, based on their account, group membership, or project role. For example: "User is in group Support Agents" or "Except users in role Project Manager".

Both types can be configured on the same rule. When both are present, both must pass for the rule to apply.

For a full reference of available operators, special variables, and view-type-specific limitations, see [Conditions](/field-rules/jira-administrator/conditions.md).

***

## Rule execution and ordering

Rules within a single UIM execute **in sequence**, from top to bottom. Each rule runs and applies its effect to the form's working state, then the next rule runs. A rule that comes later in the list sees the state of the form after all earlier rules have already applied their changes.

This enables chaining: pre-fill a field early in the list, then use its resulting value as a condition in a later rule, then show a third field based on what the second rule produced.

Rules can be reordered within a UIM using the rule actions menu.

When multiple UIMs match the same context, they all run - but in parallel, with no guaranteed order between them. Rules that must run in a specific sequence relative to each other need to be in the same UIM.

For a detailed explanation with worked examples, see [Execution order](/field-rules/jira-administrator/execution-order.md).

***

## Organising UIMs

There is no single right way to organise UIMs. Some approaches that work well:

**One UIM per concern** - a UIM for bug-specific field behaviour, another for priority restrictions, another for assignee rules. Clear names make it easy to find and edit the right one later.

**One UIM per project** - when a project has many behaviours that interact with each other, keeping them in one UIM ensures they run in the correct order.

**Separate UIMs by team** - if different teams manage different rules, separate UIMs give each team clear ownership without one team's changes affecting another's.

The key constraint: if rule B must run after rule A and read A's effects, both rules must be in the same UIM in the right order. Rules across separate UIMs do not have a guaranteed execution order relative to each other.

***

## Tips for common situations

**Making a field required conditionally** Add a "Make field required" rule with a field condition. The field becomes required only when the condition passes, and returns to optional when it does not.

**Hiding a field and making it required together** Use "Show field" to control visibility and "Make field required" for the requirement. Place "Show field" before "Make field required" in the UIM. The required rule automatically forces the field visible if needed - but having both in the right order avoids conflicting states.

**Controlling JSM portal fields** Create a UIM and configure the Jira Service Management tab with the portal and request types you want to target. Not all fields available on standard Jira screens are accessible on the portal. Check the rule documentation for JSM-specific limitations before designing your configuration.

**Applying rules to specific projects or issue types within a multi-project UIM** Use a "Project" or "Issue Type" field condition in the preconditions. Both are always available as condition targets, even without being on the screen. This lets one UIM cover multiple projects and issue types while applying specific rules to only some of them - without creating separate UIMs for each combination.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.forgappify.com/field-rules/jira-administrator/setup-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.