You’ve identified the core constraints. Here’s how to properly link release phases to hierarchical requirements in Rally 2023:
1. Understanding HierarchicalRequirement Structure:
Rally’s HierarchicalRequirement type (User Stories, Features, Epics) has a ‘Release’ field that references Release objects only - not Release Phases. Release Phases are timeline subdivisions within a Release and don’t have direct foreign key relationships with stories. The data model is:
- Release → has multiple Release Phases (timeline segments)
- HierarchicalRequirement → references one Release (not phases)
2. Parent Field Limitations:
The Parent field on HierarchicalRequirement is strictly for story hierarchy (Feature → Story → Task), not for release planning. It cannot reference Release or Release Phase objects. Your API call is failing because you’re trying to use an incompatible field type.
3. Cross-Workspace Constraints:
Rally 2023 enforces workspace boundaries for object relationships. If your requirements hierarchy spans multiple workspaces:
- Parent-child links only work within same workspace
- Release references must be in same workspace as the story
- Cross-workspace queries require explicit workspace scope in API calls
To check workspace alignment:
GET /hierarchicalrequirement/{StoryOID}?fetch=Workspace,Release
Compare Workspace OIDs - they must match.
4. Type Definitions and Allowed Relationships:
Verify your type configuration allows Release association:
- Navigate to Workspace Setup > Types > HierarchicalRequirement
- Check ‘Allowed Relationships’ section
- Release field should show type: ‘Release’ (not ReleasePhase)
If you need phase-level planning, Rally expects you to use Iteration planning instead, or align stories to Release Phases using date ranges.
5. Correct API Approach for Release Assignment:
To link a User Story to a Release (not phase):
POST /hierarchicalrequirement/{StoryOID}
{
"Release": "/release/{ReleaseOID}"
}
For phase-level tracking, use custom fields or date-based filtering:
POST /hierarchicalrequirement/{StoryOID}
{
"Release": "/release/{ReleaseOID}",
"c_ReleasePhase": "Phase 2",
"PlannedStartDate": "2025-11-01",
"PlannedEndDate": "2025-11-30"
}
6. Workaround for Phase-Level Planning:
Since direct phase linking isn’t supported, use one of these approaches:
Option A - Date-Based Alignment:
Query Release Phases for their date ranges, then filter stories by PlannedStartDate/PlannedEndDate to show which phase they fall into. Build custom reports using this logic.
Option B - Custom Field Reference:
Create a custom dropdown field ‘Release Phase’ on HierarchicalRequirement with values matching your phase names. Update this manually or via WSAPI. This gives you phase visibility without enforcing referential integrity.
Option C - Iteration-Based Planning:
Map each Release Phase to specific Iterations (sprints). Link stories to Iterations instead of directly to phases. This is Rally’s recommended approach for detailed timeline planning.
7. Multi-Workspace Solution:
For cross-workspace scenarios, consolidate release planning into a single workspace, or use Portfolio Items (Features/Epics) as the linking layer. Portfolio Items can aggregate stories across workspaces while maintaining release associations in the parent workspace.
The key insight: Rally’s data model separates strategic release planning (Release object) from tactical timeline planning (Iterations/Sprints). Release Phases are UI constructs for visualization, not first-class objects with relationship fields. Use Iterations for detailed phase-level planning, or custom fields for phase tracking if Iterations don’t fit your process.