work-item-fields

Azure DevOps Work Item Fields Reference (Verified)

System Fields (All Work Item Types)

Display Name	Reference Name	Type	Description
ID	System.Id	Integer	Unique identifier
Title	System.Title	String	Work item title
State	System.State	String	Current state
Reason	System.Reason	String	Reason for state
Work Item Type	System.WorkItemType	String	Bug, Task, etc.
Assigned To	System.AssignedTo	Identity	Person assigned
Created By	System.CreatedBy	Identity	Creator
Created Date	System.CreatedDate	DateTime	Creation timestamp
Changed By	System.ChangedBy	Identity	Last modifier
Changed Date	System.ChangedDate	DateTime	Last modified
Area Path	System.AreaPath	TreePath	Area classification
Iteration Path	System.IterationPath	TreePath	Sprint/iteration
Tags	System.Tags	String	Semicolon-separated
Description	System.Description	HTML	Rich text description
History	System.History	HTML	Discussion entry
Rev	System.Rev	Integer	Revision number
Board Column	System.BoardColumn	String	Kanban column
Board Lane	System.BoardLane	String	Swimlane

Common Fields by Category

Scheduling

Display Name	Reference Name	Type
Story Points	Microsoft.VSTS.Scheduling.StoryPoints	Double
Effort	Microsoft.VSTS.Scheduling.Effort	Double
Original Estimate	Microsoft.VSTS.Scheduling.OriginalEstimate	Double
Remaining Work	Microsoft.VSTS.Scheduling.RemainingWork	Double
Completed Work	Microsoft.VSTS.Scheduling.CompletedWork	Double
Start Date	Microsoft.VSTS.Scheduling.StartDate	DateTime
Finish Date	Microsoft.VSTS.Scheduling.FinishDate	DateTime

Priority & Severity

Display Name	Reference Name	Values
Priority	Microsoft.VSTS.Common.Priority	1, 2, 3, 4
Severity	Microsoft.VSTS.Common.Severity	1 - Critical, 2 - High, 3 - Medium, 4 - Low
Value Area	Microsoft.VSTS.Common.ValueArea	Business, Architectural
Risk	Microsoft.VSTS.Common.Risk	1 - High, 2 - Medium, 3 - Low

Bug-Specific

Display Name	Reference Name	Type
Repro Steps	Microsoft.VSTS.TCM.ReproSteps	HTML
System Info	Microsoft.VSTS.TCM.SystemInfo	HTML
Found In	Microsoft.VSTS.Build.FoundIn	String
Integration Build	Microsoft.VSTS.Build.IntegrationBuild	String

Link Types (VERIFIED from az boards work-item relation list-type)

Display Name	Reference Name	Usage
Child	System.LinkTypes.Hierarchy-Forward	workItemLink
Parent	System.LinkTypes.Hierarchy-Reverse	workItemLink
Successor	System.LinkTypes.Dependency-Forward	workItemLink
Predecessor	System.LinkTypes.Dependency-Reverse	workItemLink
Related	System.LinkTypes.Related	workItemLink
Duplicate	System.LinkTypes.Duplicate-Forward	workItemLink
Duplicate Of	System.LinkTypes.Duplicate-Reverse	workItemLink
Tested By	Microsoft.VSTS.Common.TestedBy-Forward	workItemLink
Tests	Microsoft.VSTS.Common.TestedBy-Reverse	workItemLink
Affects	Microsoft.VSTS.Common.Affects-Forward	workItemLink
Affected By	Microsoft.VSTS.Common.Affects-Reverse	workItemLink
Referenced By	Microsoft.VSTS.TestCase.SharedParameterReferencedBy-Forward	workItemLink
References	Microsoft.VSTS.TestCase.SharedParameterReferencedBy-Reverse	workItemLink
Test Case	Microsoft.VSTS.TestCase.SharedStepReferencedBy-Forward	workItemLink
Shared Steps	Microsoft.VSTS.TestCase.SharedStepReferencedBy-Reverse	workItemLink

Verified CLI Commands for Fields and Links

List all relation types

az boards work-item relation list-type -o table

Show work item with relations

az boards work-item relation show --id 123 -o json

Add parent-child relationship

# Add child link (work item 123 becomes parent of 456)
az boards work-item relation add --id 123 --relation-type "Child" --target-id 456 -o json

# Add parent link (work item 123 becomes child of 789)
az boards work-item relation add --id 123 --relation-type "Parent" --target-id 789 -o json

# Add related link
az boards work-item relation add --id 123 --relation-type "Related" --target-id 456 -o json

Note: Friendly Names vs Reference Names

The CLI uses friendly names (from the "Name" column), not reference names:

• Use "Parent" not "System.LinkTypes.Hierarchy-Reverse"
• Use "Child" not "System.LinkTypes.Hierarchy-Forward"
• Use "Related" not "System.LinkTypes.Related"

Tip: Run az boards work-item relation list-type -o table to see all available friendly names in the "Name" column.

Create with fields

az boards work-item create \
  --type "Bug" \
  --title "Login fails" \
  --fields "Microsoft.VSTS.Common.Priority=1" \
           "Microsoft.VSTS.Common.Severity=2 - High" \
           "System.Tags=urgent;login" \
  -o json

Update fields

az boards work-item update \
  --id 123 \
  --state "In Progress" \
  --assigned-to "[email protected]" \
  --fields "Microsoft.VSTS.Scheduling.RemainingWork=4" \
  -o json

Add comment (discussion)

az boards work-item update --id 123 --discussion "This is my comment" -o json

List All Fields in Project

az boards work-item list-fields -o table

Field Gotchas

1. Identity fields: Use email or display name, not GUID
2. HTML fields: Wrap in HTML tags: <p>Description</p>
3. TreePath fields: Use backslash: Project\Area\SubArea
4. Tags: Semicolon-separated in API, comma-separated in CLI
5. DateTime: ISO 8601 format: 2024-01-15T10:30:00Z
6. Double fields: Use decimal: 4.5 not 4,5
7. State values: Must match exactly including case - check your process template