@fromsvenwithlove/devops-issues-cli

# Bulk Create Work Items The `bulk-create` command allows you to create multiple work items in a hierarchical structure from a JSON file. This is perfect for setting up entire features, epics, or project structures at once. ## Features - 🎯 **Hierarchical Structure**: Create nested work items (Epic → Feature → User Story → Task) - 🔗 **Link to Existing Items**: Attach new hierarchies to existing work items using `parentId` - 📝 **JSON Schema Validation**: Validates your hierarchy before creation - 🔍 **Preview Mode**: See what will be created before committing - ✅ **Dry Run**: Validate without creating anything - 📊 **Progress Tracking**: Real-time progress updates during creation - 🔗 **Parent-Child Linking**: Automatically creates proper Azure DevOps relationships - 🎨 **Interactive Builder**: Build hierarchies step-by-step without writing JSON - 💾 **ID Mapping**: Save mapping of temporary IDs to actual Azure DevOps IDs ## Usage ### From JSON File ```bash # Create work items from JSON file devops-issues bulk-create hierarchy.json # Preview before creating devops-issues bulk-create hierarchy.json --preview # Dry run (validate only) devops-issues bulk-create hierarchy.json --dry-run # Skip confirmation prompt devops-issues bulk-create hierarchy.json --yes # Verbose output with details devops-issues bulk-create hierarchy.json --verbose # Save ID mapping to file devops-issues bulk-create hierarchy.json --save-mapping ``` ### Interactive Builder ```bash # Start interactive hierarchy builder devops-issues bulk-create ``` ## JSON Structure ### Basic Structure ```json { "metadata": { "parentId": "12345", "areaPath": "MyProject\\Team1", "iterationPath": "MyProject\\Sprint 1", "defaults": { "assignedTo": "user@company.com", "priority": 2 } }, "workItems": [ { "type": "Epic", "title": "User Authentication System", "description": "Complete authentication system", "fields": { "businessValue": 100, "priority": 1 }, "children": [ { "type": "Feature", "title": "Login Functionality", "children": [ { "type": "User Story", "title": "User can login with email", "acceptanceCriteria": "Given valid credentials...", "children": [ { "type": "Task", "title": "Create login API endpoint", "fields": { "originalEstimate": 4 } } ] } ] } ] } ] } ``` ### Metadata Section The `metadata` section defines global settings: - **parentId**: (Optional) ID of existing work item to link as parent for root items - **areaPath**: Default area path (inherited by all work items) - **iterationPath**: Default iteration path (inherited by all work items) - **defaults**: Default field values applied to all work items **Note**: The project name is automatically retrieved from your environment configuration (`.env` file or environment variables). ### Linking to Existing Work Items The `parentId` field allows you to attach your entire hierarchy to an existing work item in Azure DevOps. This is useful for: - Adding Features to an existing Epic - Adding User Stories to an existing Feature - Creating Tasks under an existing User Story - Building sub-hierarchies under any existing work item **Example: Adding Features to an Existing Epic** ```json { "metadata": { "parentId": "12345", "areaPath": "MyProject\\Authentication" }, "workItems": [ { "type": "Feature", "title": "Multi-Factor Authentication", "children": [...] } ] } ``` **Example: Adding User Stories to an Existing Feature** ```json { "metadata": { "parentId": "67890" }, "workItems": [ { "type": "User Story", "title": "User can enable SMS MFA", "children": [...] }, { "type": "User Story", "title": "User can enable app-based MFA", "children": [...] } ] } ``` The `parentId` must be a valid work item ID that exists in your Azure DevOps project and that you have access to view and link. ### Work Item Properties Each work item supports: - **type**: Epic, Feature, User Story, Task, or Bug - **title**: Work item title (required) - **description**: Detailed description - **acceptanceCriteria**: Acceptance criteria (User Stories only) - **reproSteps**: Reproduction steps (Bugs only) - **fields**: Azure DevOps field values - **children**: Array of child work items ### Supported Fields | Field Name | Azure DevOps Field | Work Item Types | Description | |------------|-------------------|-----------------|-------------| | `assignedTo` | System.AssignedTo | All | Assigned user email | | `state` | System.State | All | Work item state | | `tags` | System.Tags | All | Tags (semicolon separated) | | `severity` | Microsoft.VSTS.Common.Severity | Bug | Severity level | ## Hierarchy Rules Azure DevOps enforces specific parent-child relationships: - **Epic** → Feature, User Story - **Feature** → User Story - **User Story** → Task, Bug - **Task** → Task - **Bug** → Task ## Inheritance Rules 1. **Area Path**: Children inherit parent's area path unless overridden 2. **Iteration Path**: Children inherit parent's iteration path unless overridden 3. **Default Values**: All work items inherit values from `metadata.defaults` 4. **Field Override**: Work item `fields` override inherited values ## Examples ### Simple Feature with Tasks ```json { "metadata": { "defaults": { "assignedTo": "dev@company.com" } }, "workItems": [ { "type": "Feature", "title": "User Profile Management", "children": [ { "type": "User Story", "title": "User can edit profile", "children": [ { "type": "Task", "title": "Create profile edit API", "fields": { "originalEstimate": 4 } }, { "type": "Task", "title": "Build profile edit UI", "fields": { "originalEstimate": 3 } } ] } ] } ] } ``` ### Bug with Investigation Tasks ```json { "metadata": { "areaPath": "MyProject\\Support" }, "workItems": [ { "type": "Bug", "title": "Login fails on mobile devices", "description": "Users report login failures on mobile browsers", "reproSteps": "1. Open app on mobile\n2. Enter credentials\n3. Click login\n4. Error occurs", "fields": { "severity": "High", "priority": 1 }, "children": [ { "type": "Task", "title": "Investigate mobile login issue", "fields": { "originalEstimate": 2 } }, { "type": "Task", "title": "Fix mobile login bug", "fields": { "originalEstimate": 4 } } ] } ] } ``` ## Error Handling The bulk-create command provides detailed error reporting: - **Schema Validation**: Reports JSON structure issues - **Hierarchy Validation**: Checks parent-child type relationships - **Azure DevOps Validation**: Validates against project work item types - **Creation Errors**: Reports failures during work item creation - **Partial Success**: Continues creating other items if some fail ## Best Practices 1. **Start Small**: Begin with simple hierarchies and build complexity gradually 2. **Use Dry Run**: Always validate with `--dry-run` before creating 3. **Preview First**: Use `--preview` to visualize the hierarchy 4. **Save Mappings**: Use `--save-mapping` to track created work item IDs 5. **Consistent Naming**: Use clear, consistent titles and descriptions 6. **Proper Types**: Follow Azure DevOps work item type hierarchy rules 7. **Field Validation**: Ensure field values match Azure DevOps constraints ## Troubleshooting ### Common Issues 1. **Invalid JSON**: Check JSON syntax with a validator 2. **Schema Errors**: Review error messages for missing required fields 3. **Type Hierarchy**: Ensure parent-child relationships follow Azure DevOps rules 4. **Field Values**: Verify field values match Azure DevOps field types 5. **Permissions**: Ensure you have work item creation permissions in the project ### Error Messages - `Invalid parent-child relationship`: Check hierarchy rules - `Work item type X cannot have children`: Some types can't be parents - `Field validation failed`: Check field values and types - `Authentication failed`: Verify your PAT token - `Global parent work item X not found or not accessible`: Check that `parentId` exists and you have access - `Parent temporary ID X not found`: Internal hierarchy reference error ### API Limit Issues If you encounter errors with large hierarchies: 1. **"Request too large" or HTTP 400 errors**: Your hierarchy may exceed Azure DevOps limits - The tool automatically handles 200-item API limits via batching - If issues persist, try reducing `AZ_DEVOPS_BATCH_SIZE` to 100 or 50 2. **Timeout errors with large projects**: - Large hierarchies (1000+ items) may take time to process - Monitor batch progress messages to track status - Consider running cache warm-up first: `npm run warm-cache` 3. **Rate limiting errors**: - Azure DevOps may throttle requests for very large operations - The tool includes automatic delays, but manual retry may be needed ## Performance - Work items are created sequentially to maintain parent-child relationships - Small delay (100ms) between creations to avoid API throttling - Progress tracking shows real-time status - Cache is cleared after successful creation - Typical speed: 1-2 work items per second ### Large Hierarchy Handling For large hierarchies (>200 work items), the tool automatically: - **Batches API requests**: Azure DevOps limits `getWorkItems()` calls to 200 items maximum - **Progress tracking**: Shows batch progress (e.g., "Fetching batch 2/5 (200 items)...") - **Configurable batch size**: Set `AZ_DEVOPS_BATCH_SIZE` environment variable (default: 200) - **Automatic chunking**: No manual intervention required for large projects **Configuration Example:** ```bash # For testing with smaller batches export AZ_DEVOPS_BATCH_SIZE=50 # Default (recommended for production) export AZ_DEVOPS_BATCH_SIZE=200 ``` **Performance Notes:** - Batch processing adds minimal overhead - Each batch is processed sequentially for API stability - Large hierarchies (1000+ items) may take several minutes to fetch - Use cache warming (`scripts/warm-cache.js`) to improve subsequent performance ## Limitations - Maximum hierarchy depth: 4 levels (Epic → Feature → User Story → Task) - Sequential creation (not parallel) to maintain relationships - Limited to standard Azure DevOps work item types - Requires proper Azure DevOps permissions for work item creation