Skip to main content

Common Pitfalls to Avoid

Learning from common mistakes saves time and prevents frustration. This guide highlights frequent errors when creating Dynamic Screen Rules and shows how to avoid them.

Understanding these pitfalls helps you design rules that work reliably from the start.

Hiding Native-Required Fields​

The Problem​

Mistake: Creating a "Hide Field" rule for a field that is already marked as required in the Jira screen configuration.

Example:

Jira Screen Configuration: Description field is REQUIRED
Dynamic Screen Rule: Hide Description when Priority = Low

What happens:

  • User opens Create issue dialog
  • Sets Priority = Low
  • Description field becomes hidden
  • User clicks "Create"
  • Error: "Description is required" (but field is hidden - user can't fill it!)
  • Form submission fails

Impact: Users cannot submit form. Creates confusion and frustration.

How to Avoid​

Solution 1: Don't hide native-required fields

  • Check Jira screen configuration before creating hide rules
  • If field is required on screen, don't hide it with rules

Solution 2: Make field optional on screen

  • Remove required status from Jira screen configuration
  • Use Dynamic Screen Rules "Make Field Required" action instead
  • Now you have full control over when field is required/visible

Verification checklist:

  • ☐ Check Project Settings → Screens → Field Configuration
  • ☐ Identify fields marked as required
  • ☐ Don't create hide rules for these fields
  • ☐ Or remove native required status and use rules instead

Circular Dependencies​

The Problem​

Mistake: Creating rules where field A's visibility depends on field B, and field B's visibility depends on field A.

Example:

Rule 1: Show Budget Code when Finance Approval = Yes
Rule 2: Show Finance Approval when Budget Code is not empty

What happens:

  • Both fields are hidden initially
  • User cannot make Budget Code "not empty" (it's hidden)
  • User cannot set Finance Approval = Yes (it's hidden)
  • Neither field ever appears
  • Circular dependency deadlock

Impact: Fields remain permanently hidden. Users confused about missing fields.

How to Avoid​

Solution: Break circular dependency

Option 1: Use independent condition

Rule 1: Show Budget Code when Estimated Cost > 10000
Rule 2: Show Finance Approval when Estimated Cost > 10000

Both rules depend on same independent field (Estimated Cost).

Option 2: Chain conditions hierarchically

Rule 1: Show Budget Code when Priority = High
Rule 2: Show Finance Approval when Budget Code is not empty

Priority → Budget Code → Finance Approval (one-way chain, no loop).

Detection:

  • Draw dependency diagram
  • If arrows form a loop, you have circular dependency
  • Redesign to eliminate loop

Overly Broad Conditions​

The Problem​

Mistake: Creating rules with conditions that match more contexts than intended.

Example:

Rule: Show Root Cause when Priority = High
Scope: All issue types

What happens:

  • Rule applies to ALL issue types (Bug, Story, Task, Epic, etc.)
  • Root Cause field appears on Stories with Priority = High (doesn't make sense)
  • Root Cause field appears on Tasks with Priority = High (also doesn't make sense)
  • Field shows in unintended contexts

Impact: Confusing user experience. Fields appear where they're irrelevant.

How to Avoid​

Solution: Narrow scope appropriately

Better:

Rule: Show Root Cause when Priority = High
Scope: Bug (only)

Or use compound conditions:

Rule: Show Root Cause when Priority = High AND Issue Type = Bug
Scope: All issue types

Best practice:

  • Use specific scope when possible (limits evaluation to relevant issue types)
  • Add Issue Type condition when scope needs to be broad
  • Test rule with different issue types to verify it only applies where intended

Verification:

  • ☐ List all issue types in your project
  • ☐ Test rule with each issue type
  • ☐ Verify rule only applies where it should
  • ☐ Narrow scope if rule applies too broadly

Forgetting User Role Conditions​

The Problem​

Mistake: Creating visibility rules without considering user permissions, accidentally exposing sensitive fields to unauthorized users.

Example:

Rule: Show Salary Range when Issue Type = HR Request
(No user-based conditions)

What happens:

  • ANY user creating "HR Request" sees Salary Range field
  • External contractors see salary information
  • Junior employees see manager salaries
  • Sensitive data exposed to wrong users

Impact: Security breach. Compliance violations. Privacy concerns.

How to Avoid​

Solution: Always add user conditions for sensitive fields

Better:

Rule: Show Salary Range when Issue Type = HR Request AND User in group "HR Team"

Or:

Rule: Show Salary Range when Issue Type = HR Request AND User has role "Administrators"

Security checklist for sensitive fields:

  • ☐ Identify fields containing sensitive data (salary, budget, personal info)
  • ☐ Add user group/role/permission conditions to ALL rules affecting these fields
  • ☐ Test with different user accounts (not just admin)
  • ☐ Verify unauthorized users cannot see sensitive fields
  • ☐ Document which groups have access to which fields

Fields that often need user conditions:

  • Salary information
  • Budget/financial data
  • Personal employee information
  • Internal notes/comments
  • Strategic/confidential project details

Not Testing with Actual Users​

The Problem​

Mistake: Testing rules only as Jira admin, not with regular user accounts that have different permissions.

Example:

Rule: Show Budget field when User has permission "Browse Projects"
Tested as: Jira Administrator (has ALL permissions)

What happens:

  • Rule works perfectly for admin (during testing)
  • Deploy to production
  • Regular users report: "Budget field not showing"
  • Permissions behave differently for non-admins

Impact: Rules work in testing but fail in production. Users frustrated.

How to Avoid​

Solution: Test with representative user accounts

Testing user matrix:

  • ☐ Jira Administrator (all permissions)
  • ☐ Project Admin (project-level permissions)
  • ☐ Regular user (basic permissions)
  • ☐ External user (limited permissions)
  • ☐ User in specific groups (Finance, Managers, QA, etc.)
  • ☐ User NOT in specific groups (verify rule doesn't apply)

Testing workflow:

  1. Create rule as admin
  2. Test rule as admin (verify basic functionality)
  3. Log out
  4. Log in as regular user
  5. Test rule again (verify it works for regular users)
  6. Repeat with different user roles

Common permission differences:

  • Admins can see all fields (even hidden ones in some contexts)
  • Regular users may not have "Edit" permission (affects locking rules)
  • External users may not have "Browse" permission for certain projects
  • Group membership affects group-based conditions

Hidden Required Field Trap​

The Problem​

Mistake: Creating separate rules that make a field required while another rule hides it.

Example:

Rule 1: Hide Budget field when Issue Type = Task
Rule 2: Require Budget field when Estimated Cost > 5000

What happens:

  • User creates Task with Estimated Cost = 6000
  • Budget field is hidden (Rule 1)
  • Budget field is required (Rule 2)
  • Required field is hidden - user can't submit form

Impact: Form submission impossible. User sees "Budget is required" error but can't see Budget field.

How to Avoid​

Solution: Ensure required fields are always visible

Option 1: Combine show and require

Rule 1: Show Budget field when Estimated Cost > 5000
Rule 2: Require Budget field when Estimated Cost > 5000
(Both rules have same condition - field is visible when required)

Option 2: Use mutually exclusive conditions

Rule 1: Hide Budget field when Issue Type = Task AND Estimated Cost < 5000
Rule 2: Require Budget field when Estimated Cost > 5000
(Conditions don't overlap - field can't be hidden and required simultaneously)

Detection checklist:

  • ☐ List all fields with "Hide" rules
  • ☐ List all fields with "Require" rules
  • ☐ Check for overlap (same field in both lists)
  • ☐ Verify conditions are mutually exclusive OR show-before-require pattern
  • ☐ Test with conditions that could trigger both rules

Ignoring Screen Limitations​

The Problem​

Mistake: Creating rules with actions not supported on the selected screen.

Example:

Screen: Issue View
Action: Make Field Required

What happens:

  • Rule is created and enabled
  • Rule never works (Make Required not supported on Issue View)
  • User expects validation but field is not required
  • No error message - rule silently fails

Impact: Rules don't work. Users expect behavior that never happens.

How to Avoid​

Solution: Understand screen-specific action support

Make Field Required:

  • ✅ Supported: Global Issue Create, Issue Transition
  • ❌ Not supported: Issue View

Other screen-specific behaviors:

  • Issue View: Empty read-only fields are automatically hidden (Jira behavior)
  • Issue Transition: Only fields on transition screen are available

Before creating a rule:

Not Documenting Rule Rationale​

The Problem​

Mistake: Creating rules without documenting WHY they exist or what business requirement they address.

Example:

Rule name: "Rule 1"
Description: (empty)

What happens:

  • 6 months later: "What does Rule 1 do? Why was it created?"
  • New team member: "Can I delete this rule? I don't know what it's for"
  • Business requirement changes but nobody knows if rule is still relevant
  • Rules become unmaintainable

Impact: Rule set becomes black box. Fear of changing anything because purpose is unclear.

How to Avoid​

Solution: Document every rule

Good documentation:

Rule name: Show Root Cause for High Priority Bugs
Description: Finance department requires root cause analysis for all
            high-priority bugs per QA process (approved Q2 2024).
            Field is hidden for low-priority bugs to simplify form.
Created by: Jane Smith (QA Team)
Date: 2024-03-15

Minimum documentation:

  • ☐ Descriptive rule name (explains what it does)
  • ☐ Business rationale (why it exists)
  • ☐ Who requested it (stakeholder, team)
  • ☐ When approved (date)

Where to document:

  • Rule description field (if available in UI)
  • Team wiki or README
  • Rule inventory spreadsheet
  • Version control commit messages

Pitfall Avoidance Checklist​

Use this checklist when creating new rules:

Before creating rule:

  • ☐ Check if field is native-required on Jira screen
  • ☐ Verify action is supported on selected screen
  • ☐ List all existing rules affecting same field (check for conflicts)
  • ☐ Identify if field contains sensitive data (add user conditions)

While creating rule:

  • ☐ Use specific scope (narrow to relevant issue types)
  • ☐ Add user conditions for sensitive fields
  • ☐ Ensure required fields will be visible (show-before-require)
  • ☐ Avoid circular dependencies (draw dependency diagram)
  • ☐ Document rule rationale

After creating rule:

  • ☐ Test as admin (verify basic functionality)
  • ☐ Test as regular user (verify permissions work)
  • ☐ Test with different issue types (verify scope is correct)
  • ☐ Test edge cases (empty values, boundary conditions)
  • ☐ Monitor for user confusion or support tickets

When You've Made a Mistake​

If you discover a pitfall in production:

  1. Immediate action:
    • Disable problematic rule
    • Verify issue is resolved
    • Communicate to users if needed
  2. Investigation:
    • Identify which pitfall occurred
    • Understand why it wasn't caught in testing
    • Document the mistake (learn from it)
  3. Fix:
    • Redesign rule to avoid pitfall
    • Test thoroughly in sandbox
    • Re-enable in production
  4. Prevention:
    • Add to team documentation
    • Update testing checklist
    • Train team members

Don't be afraid to disable rules that aren't working. Better to have no rule than a broken rule causing user frustration.

Design:

Testing:

Understanding:

Troubleshooting:

Learning from these common pitfalls helps you create rules that work reliably from day one. Test thoroughly, document clearly, and verify with actual users before deploying to production.