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 = CriticalAvoid:
Rule 1: Show Root Cause when Priority = High,
Require it when Priority = Critical,
Lock it when Status = Done,
Change label when Issue Type = IncidentWhy 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:
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:
Create one rule
Test it thoroughly (matching and non-matching conditions)
Verify it doesn't conflict with existing rules
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:
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:
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:
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:
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:
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:
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
Pattern: Validation + Show/Hide
Pattern: Validation + Conditional Required
3. Test Validation Edge Cases
Common 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:
Test happy path (valid values pass)
Test each failure condition (error message appears)
Test edge cases above
Test conditional logic (validation applies only when conditions met)
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:
Over-validation:
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:
Identify field type (date, number, text, etc.)
Review available validations for that type
Choose most appropriate validation
Write clear error message
Practical Guidelines
Start with High-Impact Rules
Priority order:
Rules that prevent common errors
Rules that save significant time
Rules that improve data quality
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
Do: Create separate focused rules
The "Copy-Paste" Problem
Don't: Duplicate rules with slight variations
Do: Use OR logic in conditions
The "Hidden Required" Trap
Don't: Require fields that can be hidden by other rules
Do: Ensure required fields are always visible
The "Status Dependency" Mistake
Don't: Use Status in conditions without understanding workflow
Do: Account for all relevant statuses
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.
Last updated