📚 Documentation
Complete guide to using Work Item Twins for Azure DevOps.
📑 Table of Contents
Overview
Work Item Twins is an Azure DevOps extension that helps you synchronize work items between two different project boards within the same organization. This is particularly useful for teams that need to track the same work in multiple projects.
💡 Key Concept: A "twin" is a linked copy of a work item in another project. Changes to either twin can be synchronized automatically or manually.
Key Features
🔄 Automatic Sync
Field synchronization is automatically triggered when you save changes to either twin work item.
📋 One-Click Creation
Clone a work item from one project to another with a single click from the work item toolbar.
⚙️ Flexible Configuration
Choose which fields to sync during twin creation. Exclude State and/or Assigned To as needed.
🔗 Parent Linking
Optionally select a parent work item in the target project when creating a twin.
Installation
Work Item Twins is available from the Visual Studio Marketplace.
Requirements
- Azure DevOps Services (cloud) or Azure DevOps Server 2019+
- Project Collection Administrator or Project Administrator permissions to install
- Contributor permissions to create and sync work items
Installation Steps
- Visit the Visual Studio Marketplace
- Click "Get it free"
- Select your Azure DevOps organization
- Click "Install"
- The extension will be available immediately in all projects
Creating Twins
Follow these steps to create a twin work item:
- Open a work item in Azure DevOps that you want to twin
- Click "Work Item Twins" in the work item toolbar
- Select target project from the dropdown list
- Select work item type for the twin (must match the source type)
- Optional: Search for and select a parent work item in the target project
- Configure fields to synchronize (defaults to all editable fields)
- Optional: Check boxes to exclude State and/or Assigned To from sync
- Click "Create Twin Work Item"
✓ Success: Once created, both work items will be tagged with "Work Item Twin" and linked together. The panel will show the twin relationship and enable synchronization controls.
Synchronization
Work Item Twins provides two synchronization modes:
Automatic Synchronization
When you save changes to either twin work item, the extension automatically triggers synchronization. Only fields with different values are updated to minimize unnecessary changes.
⏱️ Sync Buffer: A 5-second buffer prevents sync loops when both work items are updated in rapid succession.
Manual Synchronization
Use the "Manual Sync" button to force synchronization at any time. The sync direction is automatically determined:
- The extension compares
System.ChangedDateof both twins - Field values are copied from the more recently updated item to the older one
- Only fields with different values are updated
Smart Field Handling
The extension intelligently handles various field types:
| Field Type | Behavior |
|---|---|
| System Fields | Never synced (ID, Project, Created Date, etc.) |
| Area Path | Mapped to target project's structure |
| Iteration Path | Mapped to target project's structure |
| Read-only Fields | Automatically excluded |
| Computed Fields | Automatically excluded |
| Description/Repro Steps | Handled correctly per work item type |
⚠️ Note: Comment synchronization is not currently supported and will be added in a future update.
Field Configuration
When creating a twin, you can customize which fields are synchronized:
Default Behavior
By default, all editable fields are selected for synchronization. This ensures complete data consistency between twins.
Excluding Fields
Common fields you might want to exclude:
- State: Keep different workflow states in each project
- Assigned To: Assign to different team members in each project
Always Excluded Fields
These system fields are never synchronized:
- System.Id
- System.Project
- System.AreaPath (remapped)
- System.IterationPath (remapped)
- System.CreatedDate
- System.CreatedBy
- System.Rev
- System.Watermark
Navigation
Once twins are linked, navigation is easy:
- Navigate to Twin: Click the "Navigate to Twin" button in the panel to jump directly to the linked work item
- Twin Tag: Work items with twins are tagged with "Work Item Twin" for easy identification in queries and boards
- Panel Status: The Work Item Twins panel shows the current sync status and twin details
Data Storage
Twin configurations are stored securely using Azure DevOps Data Storage Service:
- Data is stored within your Azure DevOps organization
- Configurations are accessible only within your organization
- No data is stored on external servers
- Data persists across browser sessions and users
Migration
If you used a previous version of this extension that stored configurations in tags, the extension will automatically migrate your twin configurations:
- On first use, the extension detects legacy tag-based configurations
- Configurations are automatically migrated to the new Data Storage system
- Existing twin relationships continue to work seamlessly
- No manual intervention required
Troubleshooting
Twin Not Syncing
- Ensure both work items have the "Work Item Twin" tag
- Check that you have edit permissions for both work items
- Try using the "Manual Sync" button
- Verify the twin configuration in the panel
Fields Not Updating
- Confirm the field is not in the excluded list
- Check if the field is read-only or computed
- Verify the field exists in both projects' work item types
Extension Not Appearing
- Refresh your browser (Ctrl+F5)
- Clear browser cache and cookies
- Verify the extension is installed for your organization
- Check you have an active subscription or trial
Frequently Asked Questions
Can I create twins across organizations?
No, twins can only be created between projects within the same Azure DevOps organization.
What work item types are supported?
All standard and custom work item types are supported. Twins must be created with matching work item types.
Can I delete a twin relationship?
Yes, you can remove the "Work Item Twin" tag from both work items to break the relationship. The work items themselves will remain.
What happens if I delete one twin?
The remaining work item will continue to exist but will no longer have a twin to sync with. Remove the "Work Item Twin" tag to clean up.
How does the trial work?
When you install Work Item Twins, you can start a 7-day free trial with full access to all features. No credit card required.
How is billing handled?
Billing is per Azure DevOps organization on an annual basis ($999/year). One subscription covers all users and projects within your organization.
Need more help?
Contact our support team at support@innovaapps.ai or use the "💡 Request a Feature" button in the extension panel.