@fromsvenwithlove/devops-issues-cli/docs/field-compatibility-guide.md

AI-powered CLI tool and library for Azure DevOps work item management with Claude agents

# Azure DevOps Field Compatibility Guide

This guide helps you understand which fields work across all Azure DevOps organizations and which may be organization-specific.

## ✅ Safe Fields (Work in ALL Organizations)

These `System.*` fields are guaranteed to be available in every Azure DevOps organization regardless of process template or customization:

### Core System Fields
- **System.Title** - Work item title *(required)*
- **System.Description** - Work item description
- **System.State** - Work item state (New, Active, Resolved, Closed, etc.)
- **System.AreaPath** - Area path for organizing work items *(inherited from parent in bulk create)*
- **System.IterationPath** - Iteration/sprint assignment *(inherited from parent in bulk create)*
- **System.Tags** - Semicolon-separated tags
- **System.Id** - Unique work item identifier *(read-only)*
- **System.WorkItemType** - Type of work item *(read-only)*

### Audit Fields *(read-only)*
- **System.CreatedBy** - User who created the work item
- **System.CreatedDate** - Creation timestamp
- **System.ChangedBy** - User who last modified the work item
- **System.ChangedDate** - Last modification timestamp

### Assignment Fields
- **System.AssignedTo** - Currently assigned user *(optional)*

## ⚠️ Process Template Dependent Fields

These `Microsoft.VSTS.*` fields **may not be available** in all process templates:

### Priority and Severity
- **Microsoft.VSTS.Common.Priority** - Priority level (1-4)
  - ❌ **NOT available in Basic process template**
  - ✅ Available in Agile, Scrum, CMMI

- **Microsoft.VSTS.Common.Severity** - Bug severity level
  - ❌ **NOT available in Basic process template**
  - ✅ Available in Agile, Scrum, CMMI

### Planning Fields
- **Microsoft.VSTS.Scheduling.StoryPoints** - Agile story points
  - ❌ **NOT available in Basic process template**
  - ✅ Available in Agile, Scrum
  - ❓ May be called differently in CMMI

- **Microsoft.VSTS.Scheduling.Effort** - Feature effort estimation
  - ❌ **NOT available in Basic process template**
  - ✅ Available in Agile, Scrum, CMMI

- **Microsoft.VSTS.Common.BusinessValue** - Business value score
  - ❌ **NOT available in Basic process template**
  - ✅ Available in Agile, Scrum, CMMI

### Work Tracking Fields
- **Microsoft.VSTS.Scheduling.OriginalEstimate** - Original time estimate
- **Microsoft.VSTS.Scheduling.RemainingWork** - Remaining work time
- **Microsoft.VSTS.Common.AcceptanceCriteria** - User story acceptance criteria
- **Microsoft.VSTS.TCM.ReproSteps** - Bug reproduction steps

## 🚫 Organization-Specific Fields (AVOID in Examples)

These fields are customized per organization and should not be used in test data:

### Custom Fields
- **Custom.*** - Any field with "Custom." prefix
- Organization-specific field names
- Custom picklist values
- Modified field constraints

### Examples of Organization-Specific Customizations
- Custom work item types beyond Epic, Feature, User Story, Task, Bug
- Custom states beyond New, Active, Resolved, Closed
- Custom area path structures
- Custom iteration path naming conventions

## 📋 Process Template Comparison

| Field | Basic | Agile | Scrum | CMMI |
|-------|-------|-------|-------|------|
| System.Title | ✅ | ✅ | ✅ | ✅ |
| System.Description | ✅ | ✅ | ✅ | ✅ |
| System.AssignedTo | ✅ | ✅ | ✅ | ✅ |
| System.State | ✅ | ✅ | ✅ | ✅ |
| System.AreaPath | ✅ | ✅ | ✅ | ✅ |
| System.IterationPath | ✅ | ✅ | ✅ | ✅ |
| System.Tags | ✅ | ✅ | ✅ | ✅ |
| Microsoft.VSTS.Common.Priority | ❌ | ✅ | ✅ | ✅ |
| Microsoft.VSTS.Scheduling.StoryPoints | ❌ | ✅ | ✅ | Varies |
| Microsoft.VSTS.Common.AcceptanceCriteria | ❌ | ✅ | ✅ | ✅ |

## 💡 Best Practices for Compatibility

### 1. Use System Fields First
Always prefer `System.*` fields when possible. Note that AreaPath and IterationPath are automatically inherited from the parent work item when using bulk create:

```json
{
  "metadata": {
    "parentId": "12345"
  },
  "workItems": [
    {
      "type": "User Story",
      "title": "User login functionality",
      "description": "Implement secure user authentication",
      "fields": {
        "tags": "authentication;security"
      }
    }
  ]
}
```

### 2. Make Process-Specific Fields Optional
If you must use `Microsoft.VSTS.*` fields, make them optional:

```json
{
  "metadata": {
    "defaults": {
      "tags": "sprint-1"
    }
  },
  "workItems": [
    {
      "type": "User Story",
      "title": "Basic user story",
      "description": "Works in all process templates"
    }
  ]
}
```

### 3. Provide Process-Specific Examples
Create separate examples for different process templates:

- `examples/basic-process-example.json` - Only System fields
- `examples/agile-process-example.json` - Includes story points, acceptance criteria
- `examples/scrum-process-example.json` - Scrum-specific fields

### 4. Document Field Dependencies
Always document which process templates your examples support:

```json
{
  "_comment": "This example works with: Basic, Agile, Scrum, CMMI process templates",
  "metadata": {
    "defaults": {}
  },
  "workItems": [...]
}
```

## 🔧 CLI Tool Behavior

The Azure DevOps CLI tool will:

- ✅ **Accept** all System fields without warnings
- ⚠️ **Warn** about Microsoft.VSTS fields that may not exist in all templates
- ❌ **Skip** invalid assignedTo values with warnings
- 🔄 **Continue** processing even if some fields are unavailable
- 🏗️ **Inherit** AreaPath and IterationPath from parent work items automatically in bulk create
- 📋 **Use single create approach** for automatic field inheritance (eliminates mandatory area/iteration path requirements)

## 📚 Additional Resources

- [Azure DevOps Process Templates](https://docs.microsoft.com/en-us/azure/devops/boards/work-items/guidance/choose-process)
- [Work Item Field Reference](https://docs.microsoft.com/en-us/azure/devops/boards/work-items/guidance/work-item-field)
- [Customize Process Templates](https://docs.microsoft.com/en-us/azure/devops/organizations/settings/work/customize-process)