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 Formify implementation scales as your team grows.

---

Core Principles

Keep Rules Simple

Principle: One rule should address one concern. Each rule has one action on one field; keep its conditions focused on one reason too. Rules that pack several unrelated reasons together are harder to debug and maintain.

Good:

Rule 1: Hide Root Cause when Priority = Low
Rule 2: Require Root Cause when Priority = Critical

Avoid:

Rule 1: Hide Root Cause when Priority = Low
        OR Issue Type = Story
        OR Labels contains documentation
        OR User is not in group "QA"

Split it into separate Hide rules on Root Cause, one per reason. The field is hidden whenever any of them applies, just as with the OR.

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

When several fields react to the same situation: create one rule per field and give the rules the same conditions.

---

Make Rules Easy to Recognize

Principle: Formify names each rule from its settings, so a rule is as easy to recognize as the fields and values it uses. You can't type or edit a rule's name.

Generated names read like this:

• "Hide root Cause when Priority not equals High and Priority not equals Critical"
• "Require business Justification when Cost Band equals Over 10,000"
• "Make fix versions read-only when condition" (an Issue status condition)

Format: [Action] [field] when [Field] [operator] [value] and …

To keep names clear:

• Give fields and select list options clear names in Jira: options named in words, not codes, give names like "when Cost Band equals Over 10,000" instead of "when Band equals 3"
• Prefer Field value conditions where they fit: Issue status, User group, User role and User permission conditions appear only as "condition" in the name (the card's IF lines show them in full)
• Check the rule, not only the name: the work types appear under Scope, but the name always joins conditions with "and", even in a rule set to OR, and the card doesn't show AND/OR either. Open Edit rule to see which operator the rule uses

Benefits:

• Team members understand rules without reading full configuration
• Easier to find the right rule when troubleshooting
• The name always matches what the rule does, because it changes with the rule

If your team uses its own categories or prefixes, keep them in a rule inventory outside Formify (see Organizing Rules).

---

Document Why Rules Exist

Principle: Write down the business reason for each rule, outside Formify.

Good documentation:

Rule: Hide budget Code when condition (User group: is not in group Finance)
Why: Only the Finance team fills in Budget Code; other requesters
     were entering guesses (agreed with Finance, 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:

• External documentation (project wiki, README)
• A rule inventory spreadsheet

Formify rules have no description field and can't be exported, so keep this documentation outside the app.

---

Avoid Over-Engineering

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

Good:

• "Hide Root Cause unless Priority is High or Critical"
• Covers 80% of important cases

Over-engineered:

• "Hide Root Cause unless Priority = High, except when Labels contain 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 work types (scope)
• Rule doesn't affect other work types
• Rule works on correct screen (Create Issue, Issue 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 with a Hide field rule whose condition is the opposite of when they're needed
• The field appears as soon as the user's selection makes that condition stop matching
• Guide users through progressive revelation

Example:

Rule 1: Hide Cost Band field (select list) when Issue Type not equals Feature

Rule 2: Hide Budget Code field when Cost Band not equals Over 10,000
Rule 3: Hide Finance Approval field when Cost Band not equals Over 10,000

An empty Cost Band also matches "not equals", so Budget Code and Finance Approval stay hidden until the user picks Over 10,000. A Show field rule wouldn't do this on its own: a field on the screen is visible unless a rule hides it. When a condition has no opposite (contains, contains any of, or several conditions joined by OR), add a Hide field rule with no conditions and put a Show field rule with the condition below it on the field's Visibility tab. Both rules need the same Work type selection: the order of the list applies only among rules with the same work types, and rules with different work type selections have no guaranteed order between them.

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
Rule 1: Require Test Results field when Issue status is in status In Testing
Rule 2: Require Release Notes field when Issue status is in status In Testing

Each rule has one action on one field, so each gated field gets its own rule with the same condition.

On a transition, the Issue status condition checks the status the issue is leaving, so this gate applies when work moves out of In Testing (for example to Ready for Release). To gate one transition only, put the fields on that transition's screen only.

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 Area (select list) = Backend
Action: Set Field Value (Assignee) = Backend Team Lead

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

Due Date can be set on the Global Issue Create screen only; rules on Due Date have no effect on Issue View or in transition dialogs, except one: in a transition dialog a Must not be empty validation on Due Date always fails and blocks the transition, even when Due Date is filled, because Jira doesn't give apps the Due Date value there. Don't add one to a transition.

Benefits:

• Faster issue creation
• Consistent data entry
• Still flexible: users can change the value, and a later run doesn't overwrite their edit. Two cases reset it: when the rule's Smart Value source field or one of its condition fields changes, the field goes back to its value from before the rule and the rule sets its value again if its conditions still match; and on the Create screen, changing the issue type applies the rule's value again

---

Role-Based Forms Pattern

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

Pattern:

• Hide fields from users who don't work with them
• Keep administrative fields off other users' forms
• Provide role-appropriate forms

Example:

Condition: User is not in group "Finance Team"
Action: Hide Budget Information field

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

Benefits:

• Cleaner forms for each role
• Users see the fields they actually fill in
• Fewer wrong values from people guessing at fields they don't own

Hiding a field is not access control: its value stays readable elsewhere in Jira, for example in search, list views and the Jira mobile app. Users who must not see the data need Jira permissions or issue security levels.

---

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 1 day from today 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

- Hide "Root Cause" when Priority not equals 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 Cost Band = Over 10,000
- Validate Approval Code minimum 8 characters
Result: Budget must be positive, features in the top cost band 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 "[Customer]"
- 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 one rarely used option in one project (rare edge case)

---

Design for Maintenance

Make rules easy to modify:

• Keep a rule inventory with each rule's purpose
• 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:

• Rule name easy to read (clear field and option names in Jira)
• 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: "Hide Budget field from non-managers, except Jane (who is not a manager but handles budgets)"
• Better solution: Add Jane to a "Budget Access" group, then rule becomes: "Hide Budget field when User is not in group Managers AND User is not in group Budget Access"
• Avoid: Exceptions for individual people in rule logic

---

Anti-Patterns to Avoid

The "Kitchen Sink" Rule

Don't: Plan one requirement as a single rule that changes many fields

When Priority = High: show Root Cause, require Description,
lock Priority, set Labels = backend,
change label to "Bug Details"

Do: Each rule has one action on one field, so turn the requirement into separate focused rules, each with only the conditions it needs

Rule 1: Hide Root Cause when Priority not equals High
Rule 2: Require Description when Priority = High
Rule 3: Set Labels = backend when Issue Type = Bug

---

The "Copy-Paste" Problem

Don't: Duplicate rules with slight variations

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

Do: Use OR logic in conditions

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

A rule joins all its conditions with one operator, AND or OR. If the rule also needs a condition that must always hold, list the priorities to leave out instead, each as a "not equals" condition joined by AND. On a select list or radio buttons field, a single is one of condition does the same job (see operators by field type).

---

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 Cost Band = Over 1,000
(If both conditions true: required field is hidden - user can't submit form!)

Do: Ensure required fields are always visible

Rule 1: Hide Budget field when Issue Type = Task
Rule 2: Show Budget field when Cost Band = Over 1,000
Rule 3: Require Budget field when Cost Band = Over 1,000
(Show and require together)

Give the Hide field and Show field rules the same Work type selection, and keep the Show field rule below the Hide field rule on Budget's Visibility tab: rules with the same work types run from top to bottom, so the Show field rule brings the field back whenever the Require rule applies. The order of the list applies only among rules with the same work types; rules with different work type selections have no guaranteed order between them.

---

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: Issue status is in status Done, Closed, Resolved

One Issue status condition can list several statuses. On the Issue Transition screen it checks the status the issue is leaving, not the one it is moving to.

---

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:

• Right tab for the behavior (Visibility, Required, Value…)
• Simple condition (easy to understand)
• Work types set to only the work types that need the rule
• 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.