Hierarchy Configuration
Learn how to create and manage custom requirements hierarchies for your organization.
Overview
Hierarchy Configuration allows Admins to define custom requirement types and levels that match your engineering methodology.
This feature requires Admin role and Professional or Enterprise tier.
Default Hierarchy
All new organizations start with the traditional systems engineering hierarchy:
Level 1: Customer Request (CR)
Level 2: System Requirement (SYS)
Level 3: Subsystem Requirement (SUB)
Level 4: Function Requirement (FUN)
Level 5: Subfunction Requirement (SFUN)
Level 6: Detailed Requirement (L6)
Creating Custom Hierarchy
Access Hierarchy Configuration
- Click "Admin" in sidebar
- Select "Hierarchy Configuration"
- Click "Create New Configuration"
Define Hierarchy Levels
For each level (minimum 2, maximum 10):
1. Level Order
Position in hierarchy (1 = top, higher = lower level)
2. Requirement Type Name
Full name of the requirement type
Examples:
- Customer Request
- Epic
- Feature
- User Story
- System Requirement
Tips:
- Use clear, descriptive names
- Consistent with your methodology
- Familiar to your team
3. Abbreviation
Short code for custom IDs (2-6 characters)
Examples:
- CR (Customer Request)
- EP (Epic)
- FEAT (Feature)
- US (User Story)
- SYS (System)
Tips:
- Keep it short (2-4 chars ideal)
- Uppercase for consistency
- Unique within hierarchy
- Easy to type
4. Allowed Parent Types
Which levels can be parents of this level?
Example:
Level 1: Epic (EP)
Allowed Parents: (none - root only)
Level 2: Feature (FEAT)
Allowed Parents: Epic
Level 3: User Story (US)
Allowed Parents: Feature, Epic
You can allow multiple parent types for flexibility. For example, User Stories could go under Features OR directly under Epics.
Configuration Options
Skip Levels
Allow Skip Levels: Users can skip hierarchy levels
Example with Skip Levels Enabled:
Epic (EP-001)
├── Feature (EP-001.FEAT-001)
└── User Story (EP-001.US-001) ← Skipped Feature level
Recommended: Enable for flexibility, especially in Agile environments
Strict Hierarchy
Enforce Strict Hierarchy: Users must follow exact level progression
Example with Strict Hierarchy:
Epic → Feature → User Story (only)
Can't create:
- Epic → User Story (skips Feature)
- User Story under Epic (wrong parent type)
Recommended: Enable for regulated industries (aerospace, medical, automotive)
Save Configuration
- Review all levels
- Check parent relationships make sense
- Click "Save Configuration"
- Configuration becomes active immediately
Hierarchy Examples
Example 1: Agile (Simple)
1. Epic (EP)
2. Feature (FEAT)
3. User Story (US)
Use Case: Software development, Agile teams
Allowed Parents:
- Feature → Epic
- User Story → Feature
Custom ID Example:
- EP-001: User authentication
- EP-001.FEAT-001: Login functionality
- EP-001.FEAT-001.US-001: As a user, I can log in with email
Example 2: Automotive (Complex)
1. Vehicle Requirement (VEH)
2. System Requirement (SYS)
3. Subsystem Requirement (SUB)
4. Component Requirement (COMP)
5. Interface Requirement (INTF)
6. Detailed Requirement (DET)
Use Case: Automotive systems engineering (ASPICE)
Custom ID Example:
- VEH-001: Safety requirements
- VEH-001.SYS-001: Airbag system
- VEH-001.SYS-001.SUB-001: Front airbag module
- VEH-001.SYS-001.SUB-001.COMP-001: Crash sensor
- VEH-001.SYS-001.SUB-001.COMP-001.DET-001: Sensor shall trigger at 15g
Example 3: Medical Device (FDA)
1. User Need (UN)
2. System Requirement (SYS)
3. Functional Requirement (FUN)
4. Design Requirement (DES)
5. Verification Requirement (VER)
Use Case: FDA regulated medical devices
Allowed Parents:
- SYS → UN
- FUN → SYS
- DES → FUN
- VER → DES, FUN, SYS (multiple for traceability)
Example 4: Minimal (Startup)
1. Feature (FEAT)
2. Requirement (REQ)
Use Case: Fast-moving startups, MVPs
Simple structure: Just two levels for speed
Managing Configurations
View Active Configuration
Admin → Hierarchy Configuration shows:
- Current active configuration
- All hierarchy levels
- Type names and abbreviations
- Parent relationships
- Version number
- Creation date
View History
See all past configurations:
- Admin → Hierarchy Configuration
- Click "View History"
- See list of all versions
Each version shows:
- Version number
- Creation date
- Creator (which admin made it)
- Active status
- Level structure
Activate Previous Version
To revert to an older configuration:
- Admin → Hierarchy Configuration → History
- Find version to restore
- Click "Activate"
- Confirm activation
Activating a different configuration requires migrating all projects. See Hierarchy Migration.
Impact on Projects
New Projects
New projects automatically use the active hierarchy configuration at creation time.
Each project stores a snapshot of the hierarchy, so future changes don't affect it until manually migrated.
Existing Projects
When you change hierarchy configuration:
- ❌ Existing projects DON'T automatically update
- ✅ Projects continue using their hierarchy snapshot
- ✅ You can migrate projects manually (see migration guide)
This prevents breaking existing projects when you update the hierarchy.
Custom IDs
Custom ID format depends on hierarchy:
Traditional:
CR-001
CR-001.SYS-001
CR-001.SYS-001.SUB-001
Agile:
EP-001
EP-001.FEAT-001
EP-001.FEAT-001.US-001
Validation and Constraints
Hierarchy Validation
System enforces:
✅ Minimum 2 levels (e.g., Feature → Requirement) ✅ Maximum 10 levels (technical limit) ✅ Unique abbreviations within configuration ✅ Valid parent relationships (no circular dependencies) ✅ At least one root type (type with no required parent)
❌ Cannot save if:
- Duplicate abbreviations
- Circular parent dependencies
- No root-level types
- Less than 2 or more than 10 levels
Abbreviation Rules
- Length: 2-6 characters
- Format: Letters and numbers only
- Case: Uppercase recommended (enforced)
- Uniqueness: No duplicates within hierarchy
Valid:
- CR, SYS, SUB, FUN, SFUN, L6
- EP, FEAT, US
- REQ, SPEC
Invalid:
- C (too short)
- SUBSYSTEM (too long)
- SY-S (no special characters)
- sys (should be uppercase)
Best Practices
Designing Hierarchy
- Start with Standard: Modify default rather than creating from scratch
- Match Methodology: Align with your team's process (Agile, Waterfall, V-Model)
- Not Too Deep: 3-6 levels is usually sufficient
- Not Too Shallow: At least 3 levels for proper decomposition
- Clear Names: Unambiguous, familiar to team
- Short Abbreviations: 2-4 characters ideal
Choosing Abbreviations
✅ Good Abbreviations:
- Industry standard (CR, SYS, SUB for systems engineering)
- Intuitive (FEAT for Feature, US for User Story)
- Distinct (EP, FEAT, US - all clearly different)
❌ Poor Abbreviations:
- Ambiguous (REQ could mean many things)
- Similar (SYS and SYT - easy to confuse)
- Too long (SYSREQ instead of SYS)
Hierarchy Depth
| Depth | Use Case | Example |
|---|---|---|
| 2 levels | Simple projects, MVPs | Feature → Requirement |
| 3-4 levels | Agile software | Epic → Feature → Story → Task |
| 4-6 levels | Systems engineering | CR → SYS → SUB → FUN → SFUN → L6 |
| 6-8 levels | Complex systems (aerospace) | Add interface, HW, SW levels |
| 8+ levels | Not recommended | Too complex to manage |
Parent Relationships
Strict Linear (recommended for beginners):
A → B → C → D
Each level has exactly one possible parent type.
Flexible (for experienced teams):
A → B → C
A → C (skip B)
B → D
C → D
Multiple parent options for flexibility.
Troubleshooting
Can't Create Hierarchy
Cause: Free tier doesn't support custom hierarchy
Solution: Upgrade to Professional or Enterprise
Validation Error: "Circular Dependency"
Cause: Parent relationships form a loop
Example:
A allows parent: B
B allows parent: C
C allows parent: A ← Creates loop
Solution: Remove one relationship to break the loop
Validation Error: "No Root Type"
Cause: All types require a parent (no top-level type)
Solution: Ensure at least one type has no required parents
Can't Activate Old Version
Cause: Would require migrating all projects
Solution: Use Migration Tool to update projects first
What's Next?
- Hierarchy Migration - Migrate projects to new hierarchy
- Creating Requirements - Use your custom hierarchy
- User Management - Share with team