Export Work Item Mapping Tool
Writes a JSON file that maps each source work item ID to the ID of the target work item it was migrated to, so you can trace, audit and post-process a migration.
Overview
The Export Work Item Mapping Tool records which target work item each source work item was migrated to, and writes those pairs to a JSON file at the end of the run. Use the file to trace a work item across the migration, to check that everything arrived, or as input to your own scripts.
Tool for exporting mappings of work item IDs from source to target. Work item migration processor uses this tool to record work item ID mappings. The mappings will be saved to file defined in options at the end of the migration.
How It Works
- Recording: as
TfsWorkItemMigrationProcessorfinishes each work item that has a target work item, it records the pair of IDs. This includes work items that already existed in the target from an earlier run. - Saving: when the processor finishes, including when it stops after a failure, the mappings are written to
TargetFile. The mappings are written to<TargetFile>.tmpfirst and then copied overTargetFile, so a failure while writing the mappings leavesTargetFileas it was. The final copy is not atomic: a failure during that copy can still leaveTargetFileincomplete. - Merging: with
PreserveExistingset totrue(the default), the mappings already inTargetFileare loaded and kept. If a source ID is mapped to a different target ID in this run, the new target ID wins and a warning is logged.
If the same source ID is recorded twice in one run with different target IDs, the first mapping is kept and an error is logged.
The tool only writes the file. The migration does not read it back to find work items on a re-run: that uses the reflected work item ID field (see ReflectedWorkItemId ).
topUse Cases
- Traceability: look up where a source work item went.
- Auditing: compare the number of mappings with the number of source work items you expected to migrate.
- Post-processing: feed the map into scripts that update references outside Azure DevOps, such as links in wikis or external systems.
Configuration Structure
The tool is off unless you enable it. When Enabled is true, TargetFile must be set, or the configuration fails validation with 'TargetFile' is not set, so work item mappings cannot be saved.
Options
topSample
{
"MigrationTools": {
"Version": "16.0",
"CommonTools": {
"ExportWorkItemMappingTool": {
"Enabled": true,
"TargetFile": "c:\\temp\\WorkItemMappings.json",
"PreserveExisting": true
}
}
}
}Defaults
There are no defaults! Check the sample for options!Basic Examples
Add the tool to CommonTools in your configuration:
{
"MigrationTools": {
"CommonTools": {
"ExportWorkItemMappingTool": {
"Enabled": true,
"TargetFile": "c:\\temp\\WorkItemMappings.json",
"PreserveExisting": true
}
}
}
}
Output
The file is a JSON object. Each key is a source work item ID and each value is the target work item ID, both as strings:
{
"101": "5001",
"102": "5002",
"107": "5003"
}
Common Scenarios
- Migrating in several runs: keep
PreserveExistingset totrueand point every run at the sameTargetFile, so the file holds every mapping from every run. - Starting a fresh map: set
PreserveExistingtofalse, and the file holds only the work items processed in this run.
Good Practices
- Use a separate
TargetFilefor each source and target project pair. - Keep the file with your migration logs; it is the quickest way to answer “where did work item 123 go?”.
Troubleshooting
- No file is written: check that
Enabledistrueand that the folder inTargetFileexists and can be written to. Failures are logged asFailed to save work item mappings to '<file>'. - A mapping is missing: only work items that
TfsWorkItemMigrationProcessorprocessed and that have a target work item are recorded. Work items filtered out before processing, for example byFilterWorkItemsThatAlreadyExistInTarget, are not recorded in that run; keepPreserveExistingon to keep them from earlier runs.
Schema
This is the JSON schema that defines the structure and validation rules for this configuration.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://devopsmigration.io/schema/schema.tools.exportworkitemmappingtool.json",
"title": "ExportWorkItemMappingTool",
"description": "Tool for exporting mappings of work item IDs from source to target.\r\n Work item migration processor uses this tool to record work item ID mappings.\r\n The mappings will be saved to file defined in options at the end of the migration.",
"type": "object",
"properties": {
"Enabled": {
"description": "If set to `true` then the tool will run. Set to `false` and the tool will not run.",
"type": "boolean",
"default": false
},
"PreserveExisting": {
"description": "Indicates whether existing mappings in the target file should be preserved when saving new mappings.\r\n Default value is `true`.",
"type": "boolean",
"default": true
},
"TargetFile": {
"description": "Path to file, where work item mapping will be saved.",
"type": [
"string",
"null"
]
}
}
}In this article
Project Information
Azure DevOps Marketplace
Maintainer
Created and maintained by Martin Hinshelwood of nkdagility.com
Getting Support
Community Support
The first place to look for usage, configuration, and general help.
Commercial Support
We provide training, ad-hoc support, and full service migrations through our professional services.
Azure DevOps Migration Services