Designing Effective Rules

Well-designed rules are simple, maintainable, and solve real problems without over-engineering. This guide shares principles and patterns for creating rules that work reliably and are easy to understand months later.

Good rule design prevents maintenance headaches and ensures your Dynamic Screen Rules implementation scales as your team grows.

---

Core Principles

Keep Rules Simple

Principle: One rule should address one concern. Complex multi-action rules are harder to debug and maintain.

Good:

Rule 1: Show Root Cause when Priority = High
Rule 2: Require Root Cause when Priority = Critical

Avoid:

Rule 1: Show Root Cause when Priority = High,
        Require it when Priority = Critical,
        Lock it when Status = Done,
        Change label when Issue Type = Incident

Why simple rules are better:

• Easy to understand at a glance
• Simple to debug when something breaks
• Can be enabled/disabled independently
• Clear relationship between condition and action

Exception: Closely related actions on the same field can be combined if they share the same condition.

---

Use Descriptive Names

Principle: Rule names should explain what the rule does, not just number them sequentially.

Good:

• "Show Root Cause for High Priority Bugs"
• "Require Business Justification for Features over $10k"
• "Lock Fix Versions in Done Status"
• "Pre-fill Component for Backend Bugs"

Avoid:

• "Rule 1"
• "Bug Rule"
• "Field Hide"
• "My Rule"

Benefits:

• Team members understand rules without reading full configuration
• Easier to find the right rule when troubleshooting
• Self-documenting - names explain purpose
• Future you will thank present you

Naming pattern: [Action] [Field] [Condition]

• Action: Show, Hide, Require, Lock, Set
• Field: Root Cause, Budget Code, Priority
• Condition: for High Priority Bugs, when Status = Done

---

Document Why Rules Exist

Principle: Add comments or descriptions explaining the business reason for each rule.

Good documentation:

Rule: Show Salary Range for HR Team only
Why: Salary information is confidential. Only HR team members
     should see this field per company policy (approved Q2 2024).

Why documentation matters:

• New team members understand context
• You remember the reason 6 months later
• Stakeholders can review business logic
• Compliance and audit trails

What to document:

• Business requirement driving the rule
• Who requested it (team, stakeholder)
• When it was approved
• Edge cases or exceptions
• Related rules or dependencies

Where to add documentation:

• Rule description field (if available in Dynamic Screen Rules UI)
• External documentation (project wiki, README)
• Comments in rule configuration exports

---

Avoid Over-Engineering

Principle: Don't create rules for edge cases that rarely happen. Focus on common scenarios.

Good:

• "Show Root Cause for High and Critical priority"
• Covers 80% of important cases

Over-engineered:

• "Show Root Cause when Priority = High, except when Component = Documentation, unless Reporter is in External group, but only on Tuesdays"
• Edge case handling creates complexity with little benefit

How to avoid over-engineering:

• Ask: "How often does this scenario happen?"
• If less than 5% of cases, probably don't need a rule
• Start simple, add complexity only when proven necessary
• Use Jira native features for rare cases (manual field entry)

Better than complex rules:

• User training ("when Priority is High, please fill Root Cause")
• Jira automation for post-creation processing
• Manual review processes for edge cases

---

Test Incrementally

Principle: Verify each rule works correctly before creating the next one.

Testing workflow:

1. Create one rule
2. Test it thoroughly (matching and non-matching conditions)
3. Verify it doesn't conflict with existing rules
4. Move to next rule

Don't do:

• Create 10 rules at once
• Enable all rules simultaneously
• Hope everything works together

Why incremental testing matters:

• Isolate problems to single rule
• Understand interactions between rules
• Catch bugs early (easier to fix)
• Build confidence in rule set

Testing checklist per rule:

• ✅ Rule applies when conditions are met
• ✅ Rule doesn't apply when conditions aren't met
• ✅ Rule works for correct issue types (scope)
• ✅ Rule doesn't affect wrong issue types
• ✅ Rule works on correct screen (Create/View/Transition)
• ✅ No conflicts with existing rules

---

Design Patterns

Progressive Disclosure Pattern

When to use: Simplify forms by showing fields only when relevant.

Pattern:

• Hide optional fields by default
• Show fields when user makes selections that require them
• Guide users through progressive revelation

Example:

Condition: Issue Type = Feature
Action: Show Estimated Cost field

Condition: Estimated Cost > 10000
Action: Show Budget Code field
Action: Show Finance Approval field

Benefits:

• Clean initial form (fewer fields)
• Users aren't overwhelmed
• Context-aware - fields appear when needed

---

Validation Gate Pattern

When to use: Ensure data completeness at critical workflow stages.

Pattern:

• Require fields before allowing transitions
• Lock fields after work is complete
• Enforce business rules at decision points

Example:

Screen: Issue Transition
Condition: Status = Ready for Release
Action: Require Test Results field
Action: Require Release Notes field

Benefits:

• Workflow gates ensure quality
• Can't progress without required information
• Clear checkpoints for teams

---

Smart Defaults Pattern

When to use: Reduce manual data entry with intelligent pre-filling.

Pattern:

• Set default values based on context
• Use Smart Values for dynamic defaults
• Allow users to override if needed

Example:

Condition: Issue Type = Bug AND Component = Backend
Action: Set Field Value (Assignee) = Backend Team Lead

Condition: Priority = Critical
Action: Set Field Value (Due Date) = today().plusBusinessDays(1)

Benefits:

• Faster issue creation
• Consistent data entry
• Still flexible (users can change)

---

Role-Based Access Pattern

When to use: Show different fields to different user groups.

Pattern:

• Hide sensitive fields from unauthorized users
• Show administrative fields only to admins
• Provide role-appropriate forms

Example:

Condition: User in group "Finance Team"
Action: Show Budget Information field

Condition: User NOT in group "Managers"
Action: Hide Executive Summary field

Benefits:

• Data security (sensitive fields hidden)
• Cleaner forms for each role
• Compliance with access policies

---

Validation Rules Pattern

When to use: Enforce data quality, consistency, and business rules with real-time feedback.

Pattern:

• Validate field values against thresholds, ranges, or formats
• Provide custom error messages explaining what's wrong and why
• Apply validation conditionally based on context
• Combine multiple validations for comprehensive quality checks

Example:

Field: Story Points
Condition: Issue Type = Story

Validation Rule 1: Must not be empty
Message: "Story Points are required for all Stories"

Validation Rule 2: Number greater than 0
Message: "Story Points must be positive. Please estimate this Story."

Validation Rule 3: Number less than 41
Message: "Story Points exceeding 40 should be split into smaller Stories"

Benefits:

• Real-time feedback as users type (not after submission)
• Clear, actionable error messages
• Automated enforcement of business rules
• No coding required (vs. ScriptRunner workflow validators)

When to use Validation vs. Required Fields:

Scenario	Use Validation Rules	Use Required Fields
Conditional "must have value"	✅ Validation: Must not be empty	❌ Always required
Threshold checks (dates, numbers, text)	✅ Validation: Date after today, > 0	❌ Can't check thresholds
Custom error messages	✅ Validation: Specific, actionable	❌ Generic "required"
Cross-field consistency	✅ Validation: End Date > Start Date	❌ No cross-field checks
Simple always-required	⚠️ Either works	✅ Simpler configuration

Validation Rules Best Practices:

1. Write Clear Error Messages

Good:

• "Due Date must be at least 2 hours from now to allow time for triage and assignment"
• "Story Points must be greater than 0. Please estimate this Story before saving."
• "End Date must be after Start Date to create a valid timeline"

Bad:

• "Invalid value" (not specific)
• "Validation failed" (no guidance)
• "Error" (useless)

Best practices:

• State what's wrong clearly
• Explain why the validation exists (business reason)
• Provide actionable guidance (what should user do)
• Keep it concise (1-2 sentences)

2. Combine Validations for Comprehensive Checks

Pattern: Multiple validations on same field

Story Points field:
- Must not be empty (presence check)
- Greater than 0 (prevent zero)
- Less than 41 (enforce splitting)
Result: Story Points between 1-40, all aspects validated

Pattern: Validation + Show/Hide

- Show "Root Cause" when Priority = Critical
- Validate "Root Cause" minimum 30 characters when Priority = Critical
Result: Field appears only when relevant and must meet quality standard

Pattern: Validation + Conditional Required

- Validate Budget > 0 (all Features)
- Make "Approval Code" required when Budget > 10000
- Validate Approval Code minimum 8 characters
Result: Budget must be positive, high-cost features require valid approval

3. Test Validation Edge Cases

Common edge cases to test:

Validation Type	Edge Cases to Test
Must not be empty	Whitespace-only text (should fail), zero for numbers (passes)
Greater than 0	Zero (fails), negative (fails), empty (passes - needs separate)
Date after today	Today's date (fails), tomorrow (passes), past (fails)
Date after field	Equal dates (fails), one field empty (passes - fail-safe)
Min/Max text length	Exactly at threshold, whitespace padding, rich text (ADF)
Contains text	Case variations ("JIRA" vs "jira"), partial words
Not contains text	Case variations, substring vs exact match

Testing workflow:

1. Test happy path (valid values pass)
2. Test each failure condition (error message appears)
3. Test edge cases above
4. Test conditional logic (validation applies only when conditions met)
5. Test cross-field scenarios (both filled, one empty, both empty)

4. Validation vs. Workflow Validators

Use Validation Rules when:

• You need real-time feedback as users type
• You want custom, actionable error messages
• You need conditional validation based on field values
• You want centralized rule management
• No coding/scripting expertise available

Use Workflow Validators when:

• Validation is tied to specific workflow transitions
• You need workflow state-specific checks
• You're already using Jira workflow validators and prefer consistency
• Validation logic is workflow-centric ("can only transition if...")

Can combine both:

• Validation rule checks data quality on Create screen
• Workflow validator checks workflow state on transition
• Example: Validate Story Points > 0 on Create, workflow validator ensures Status history for Done transition

5. Don't Over-Validate

Good balance:

Incident Summary:
- Minimum 15 characters (prevents "Bug" or "Error")
- Result: Encourages detail without being burdensome

Over-validation:

Incident Summary:
- Minimum 15 characters
- Maximum 50 characters
- Must contain "JIRA-"
- Must not contain "TODO"
- Must not contain numbers
- Result: Users frustrated, spend more time on validation than actual work

Guidelines:

• Focus on high-value validations (prevent common errors, ensure critical data)
• Avoid validation for edge cases that rarely occur
• Don't validate for style preferences (let users have flexibility)
• Test with real users - if validation feels annoying, it probably is

6. Leverage Smart Filtering

How smart filtering works:

• System shows only validation types compatible with field type
• Date field → only date validations appear
• Number field → only number validations appear
• Text field → only text validations appear

Benefits:

• Users never see irrelevant validation options
• Cleaner, more intuitive configuration UI
• Prevents errors from selecting incompatible validations
• Makes validation selection faster (fewer options to review)

Design tip: When planning validations, think about field type first:

1. Identify field type (date, number, text, etc.)
2. Review available validations for that type
3. Choose most appropriate validation
4. Write clear error message

---

Practical Guidelines

Start with High-Impact Rules

Priority order:

1. Rules that prevent common errors
2. Rules that save significant time
3. Rules that improve data quality
4. Nice-to-have conveniences

Example prioritization:

• ✅ High impact: Require Root Cause for Critical bugs (prevents incomplete high-priority work)
• ✅ High impact: Pre-fill Due Date = 3 business days (saves time on every issue)
• ⚠️ Medium impact: Change field label based on context (improves clarity)
• ❌ Low impact: Hide field for specific component in one project (rare edge case)

---

Design for Maintenance

Make rules easy to modify:

• Use consistent naming conventions
• Group related rules together
• Document dependencies
• Avoid deep nesting of conditions

When someone needs to modify a rule:

• They should understand it in 30 seconds
• They should know why it exists
• They should be able to test changes safely

Maintainability checklist:

• ✅ Descriptive rule name
• ✅ Clear conditions (not overly complex)
• ✅ Single, obvious action
• ✅ Documentation of purpose
• ✅ Test cases documented

---

Consider User Experience

Rules should feel helpful, not restrictive:

• Don't hide fields users expect to see
• Don't require fields without context
• Provide clear labels when changing field names
• Show users why fields appear/disappear

Good UX:

• User selects Priority = High → Root Cause field appears (obvious why)
• Field label changes to "Steps to Reproduce" when Issue Type = Bug (clarifying)
• Due Date pre-fills with next Monday (saves time, user can change)

Poor UX:

• Field disappears with no explanation
• Required field suddenly appears without context
• Locked field prevents needed edit
• Too many fields hidden - user can't find what they need

---

Handle Edge Cases Gracefully

When edge cases arise:

• Evaluate: How common is this scenario?
• Document: Record the edge case in rule notes
• Decide: Add rule complexity OR handle manually

Options for edge cases:

• If common (>10% of cases): Add rule logic
• If rare (<5% of cases): Document workaround, handle manually
• If medium (5-10%): Consider simple rule OR training

Example decision:

• Edge case: "Show Budget field for non-managers, except Jane (who is not a manager but handles budgets)"
• Better solution: Add Jane to a "Budget Access" group, then rule becomes: "Show Budget field for Managers OR Budget Access group"
• Avoid: Complex "User NOT in Managers AND User != Jane" logic

---

Anti-Patterns to Avoid

The "Kitchen Sink" Rule

Don't: Combine unrelated actions in one rule

Rule: Show Root Cause, Require Description,
      Lock Priority, Set Component = Backend,
      Change label to "Bug Details"
      when Priority = High

Do: Create separate focused rules

Rule 1: Show Root Cause when Priority = High
Rule 2: Require Description when Priority = High
Rule 3: Set Component = Backend when Issue Type = Bug

---

The "Copy-Paste" Problem

Don't: Duplicate rules with slight variations

Rule 1: Show Field X when Priority = High
Rule 2: Show Field X when Priority = Critical
Rule 3: Show Field X when Priority = Blocker

Do: Use OR logic in conditions

Rule 1: Show Field X when Priority = High OR Priority = Critical OR Priority = Blocker

---

The "Hidden Required" Trap

Don't: Require fields that can be hidden by other rules

Rule 1: Hide Budget field when Issue Type = Task
Rule 2: Require Budget field when Estimated Cost > 1000
(If both conditions true: required field is hidden - user can't submit form!)

Do: Ensure required fields are always visible

Rule 1: Show Budget field when Estimated Cost > 1000
Rule 2: Require Budget field when Estimated Cost > 1000
(Show and require together)

---

The "Status Dependency" Mistake

Don't: Use Status in conditions without understanding workflow

Condition: Status = Done
(What if your project has "Done", "Closed", "Resolved" as completion statuses?)

Do: Account for all relevant statuses

Condition: Status = Done OR Status = Closed OR Status = Resolved

Or use status categories if available in your Jira setup.

---

Review and Iterate

Periodic rule review:

• Every 3-6 months, review all rules
• Ask: Is this rule still needed?
• Check: Is this rule working correctly?
• Update: Documentation if business logic changed

Signs a rule needs review:

• Users frequently ask why field is hidden
• Rule generates confusion or support tickets
• Business process changed but rule didn't
• Multiple rules conflict on same field

Continuous improvement:

• Collect user feedback on rule behavior
• Monitor which rules provide value
• Retire unused or problematic rules
• Refine based on real usage patterns

---

Summary Checklist

Use this checklist when designing new rules:

Before creating a rule:

• ☐ Clearly defined business requirement
• ☐ Verified field is supported (Supported Field Types)
• ☐ Confirmed screen supports action (Screens & Contexts)
• ☐ Checked for existing rules on same field

While creating a rule:

• ☐ Descriptive rule name (explains what it does)
• ☐ Simple condition (easy to understand)
• ☐ Single focused action (one concern)
• ☐ Documentation added (why it exists)

After creating a rule:

• ☐ Test with matching conditions
• ☐ Test with non-matching conditions
• ☐ Test with different user roles (if applicable)
• ☐ Verify no conflicts with existing rules
• ☐ Document in team wiki or README

---

Related Pages

Configuration:

• Creating Your First Rule - Step-by-step rule creation

Organization:

• Organizing Rules - How to structure rule sets
• Managing Rules - Enable, disable, edit rules

Testing:

• Testing Rules - Comprehensive testing strategies

Performance:

• Performance Considerations - Optimize rule sets

Avoiding problems:

• Common Pitfalls to Avoid - Mistakes to watch for

Well-designed rules are invisible to users - they just work. Follow these principles to create rules that solve problems simply and effectively.