diff --git a/docs/Reference/Generated/MigrationTools.xml b/docs/Reference/Generated/MigrationTools.xml index 2f28ac271..050bad172 100644 --- a/docs/Reference/Generated/MigrationTools.xml +++ b/docs/Reference/Generated/MigrationTools.xml @@ -258,32 +258,32 @@ - => @"feature/OpenTelemetry" + => @"topic/update-docs-2" - => @"803de11b" + => @"26082d82" - => @"803de11bbcfb055ccf1ac358a06d24b4f80f3a5d" + => @"26082d82552f59963aad53b364d73bb74bf60803" - => @"2024-08-29T21:59:31+01:00" + => @"2024-08-30T09:13:07+01:00" - => @"0" + => @"6" - => @"v16.0.0-Preview.4" + => @"v16.0.0-Preview.4-6-g26082d82" @@ -318,7 +318,7 @@ - => @"0" + => @"6" diff --git a/docs/Reference/ReflectedWorkItemId.md b/docs/Reference/ReflectedWorkItemId.md deleted file mode 100644 index f6cb41b08..000000000 --- a/docs/Reference/ReflectedWorkItemId.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: ReflectedWorkItemId -layout: page -pageType: index ---- - -The Azure DevOps migrations Tools has no internal state, and uses a field on the work item to track the migration of work items. This field is always referd to in the docs as `ReflectedWorkItemId` and is used to track the work item in the target. It enables the ability to resume migrations as well as to be able to scope the work items based on a query and have multiple runs overlap. - -## How to add the ReflectedWorkItemId - -To add the `ReflectedWorkItemId` to your target project you can use the follow the [Add a custom field to a work item type (Inheritance process)](https://learn.microsoft.com/en-us/azure/devops/organizations/settings/work/add-custom-field?view=azure-devops) documentation from Microsoft. If you are on the older XML process you can follow the [Add a custom field to a work item type (On-premises XML process)](https://learn.microsoft.com/en-us/azure/devops/organizations/settings/work/import-process/customize-process?view=azure-devopss) documentation. - -Note: We can [help you get off those horible legacy XML Process](https://nkdagility.com/capabilities/azure-devops-migration-services/). - -## How to use the ReflectedWorkItemId - -In your configuration file under `MigrationTools:Endpoints` there willbe both a `Source` and a `Target` endpoint. On the `Target` endpoint there should be a property called `ReflectedWorkItemID*` (depending on the specific endpoint implmnetation) that will have a property value like `Custom.ReflectedWorkItemId`. This is the field that the tool will use to track the work items in the target. - -```json -{ - "Endpoints": { - "Source": { - "Collection": "https://dev.azure.com/nkdagility-preview/", - "Project": "MigrationTest", - "ReflectedWorkItemIDFieldName": "Custom.ReflectedWorkItemId", - "AllowCrossProjectLinking": false, - "AuthenticationMode": "Prompt", - "PersonalAccessToken": "" - }, - "Target": { - "Collection": "https://dev.azure.com/nkdagility-preview/", - "Project": "MigrationTest", - "ReflectedWorkItemIDFieldName": "Custom.ReflectedWorkItemId", - "AllowCrossProjectLinking": false, - "AuthenticationMode": "Prompt", - "PersonalAccessToken": "" - } - } -} -``` - -When you create the field you will be able to see the`RefName` (diferent from the display name) in the field settings. This is the value that you will use in the configuration file. It will always have at least one `.` in the name. On the inherited processes it will be `Custom.ReflectedWorkItemId` (unless you created your process and added the field many moons ago, inwhich case it will be `processName.ReflectedWorkItemId`). On the XML process it will be whatever you want to call it But I recommned something like `TfsMigrationTool.ReflectedWorkItemId` or just `ReflectedWorkItemId`. - -## Notes for Work Items you cant Customise! - -If you need to migratae work items that you cant customsie, then you will need to use one of the built in fields and I recommned `Microsoft.VSTS.Build.IntegrationBuild`. This field is only used by builds, and is realitively safe to use. This is primerally of concern for [How-to: Migrating Plans and Suits](_howto/migrating-plans-and-suits.md). diff --git a/docs/_includes/sidebar.html b/docs/_includes/sidebar.html index 9af6cb035..de63d1fd2 100644 --- a/docs/_includes/sidebar.html +++ b/docs/_includes/sidebar.html @@ -1,12 +1,21 @@
-
+
...
@@ -63,7 +63,6 @@
- {% include cardpanel-contribute.html expand = true %}
Getting Support
@@ -78,9 +77,34 @@
Getting Support
In this article
{{ content | toc_only }} +
+ +
{% endif %} + {% include cardpanel-contribute.html expand = true %}
diff --git a/docs/getting-started.md b/docs/getstarted/index.md similarity index 99% rename from docs/getting-started.md rename to docs/getstarted/index.md index c8af32dfe..0425ead0a 100644 --- a/docs/getting-started.md +++ b/docs/getstarted/index.md @@ -5,6 +5,8 @@ pageType: index toc: true pageStatus: published discussionId: +redirect_from: + - /getting-started/ --- If you want to perform a bulk edit or a migration then you need to start here. This tool has been tested on updating from 100 to 250,000 work items by its users. diff --git a/docs/getstarted/introvideos.md b/docs/getstarted/introvideos.md new file mode 100644 index 000000000..0ceff935a --- /dev/null +++ b/docs/getstarted/introvideos.md @@ -0,0 +1,10 @@ +--- +title: Introductory Videos +layout: page +pageType: index +toc: true +pageStatus: published +discussionId: +--- + +- [Video Overview](https://youtu.be/RCJsST0xBCE) \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 2b0fb1b24..e3d392f3f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,7 +3,7 @@ title: Azure DevOps Migration Tools layout: page pageType: index template: index-template.md -toc: true +toc: false pageStatus: published discussionId: --- @@ -62,10 +62,6 @@ For the most part we support moving data between `((Azure DevOps Server | Team F - [Community Support](https://github.com/nkdAgility/azure-devops-migration-tools/discussions) - [Commercial Support](https://nkdagility.com/capabilities/azure-devops-migration-services/) -## Tutorials - -- [Video Overview](https://youtu.be/RCJsST0xBCE) - The documentation for the preview is on [Preview](https://nkdagility.com/docs/azure-devops-migration-tools/preview/)] #### External Walkthroughs and Reviews diff --git a/docs/permissions.md b/docs/permissions.md deleted file mode 100644 index 0d90d4454..000000000 --- a/docs/permissions.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Permissions -layout: page -pageType: index -toc: true -pageStatus: published -discussionId: ---- - -The permissions are courently governed by the needs of the [TFS Client Object Model](https://learn.microsoft.com/en-us/azure/devops/integrate/concepts/dotnet-client-libraries?view=azure-devops) from Microsoft. Microsoft [Announced the deprecation of the WIT and Test Client OM](https://devblogs.microsoft.com/devops/announcing-the-deprecation-of-the-wit-and-test-client-om-at-jan-1-2020-2/) in 2020, however this is still the only way to interact with versions of TFS from 2010 to 2018 with any consistantcy. We are working on moving our tools to the REST API, but this is a large task and will take some time. - -## Minimum Permission Requirements - -At this time the documented minimum required permissions for running the tools are: - -- Account in both the source and target projects with "Project Collection Administrator" rights -- PAT with "full access" for both the Source and the Target - -Note: I have been informed by the Azure DevOps product team information that ObjectModel API only works with full scoped PATs, so it won't work with any PAT that has specific scopes. - -### However! Unsupported Permission Options - -We have seen that the tools may work with less permissions however the following has not been full tested and is not currently supported: - -- Project and Team (Read, write, & manage) -- Work Items (Read, Write & Manage) -- Identity (Read & Manage) -- Security (Manage) - -If you do try this out then please let us know how you get on! - -## TFS, VSTS, & Azure DevOps Server Configuration (On-Premises Only) - -There are some additional requirements that you will need to meet in order to use the tool against your TFS or VSTS server. The Azure DevOps Migration Tools use a flag to Bypass the Work Item rules engine and write data into TFS\VSTS that may not comply with the rules. For example you can write data directly into the `Closed` state without starting at `New`. This is very useful for migrations but requires some pre-requisites. - -## Bypass Rules - -For on-premises instances you need to be part of the `Project Collection Service Accounts` group. You can do this by calling the following command: - -`tfssecurity /g+ "Project Collection Service Accounts" n:domainusername ALLOW /server:http://myserver:8080/tfs` - -This is not required for Azure DevOps Service targets, but you do need to be a Collection Admin on the Target. - -## Migration State - -In order to store the state for the migration you need to use a custom field, the `ReflectedWorkItemId` field which needs added to the Target only. The way you add this depends on the platform you are using. - -### Azure DevOps - -1. Create a custom field called `ReflectedWorkItemId` of type `Text (single line)` by following this [guide](https://docs.microsoft.com/en-us/azure/devops/organizations/settings/work/add-custom-field?view=azure-devops) -1. Add this custom field to all work item types to be migrated (e.g. Bug, User Story, Task, Test Case, etc) - -### Team Foundation Server (TFS) - -Use the `witadmin exportwitd` command to export each work item and add: - -```xml - -``` - -to the Fields section. - -Then use `witadmin importwitd` to re-import the customized work item type template. - -See [MSDN for more details](https://msdn.microsoft.com/en-us/library/dd236914.aspx) - -### Visual Studio Team Services (VSTS) - -With the advent of the [data migration tool for Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/migrate/migration-overview) there are potentially two ways you need to consider when customising a VSTS process template. It all depends how the Team Project was created. - -#### Inherited Templates - the future #### - -If you created the Team Project via the web based VSTS UI. You need to [add a custom field through the VSTS UI](https://blogs.msdn.microsoft.com/visualstudioalm/2015/12/10/adding-a-custom-field-to-a-work-item/) to be able to use the tool. - -The name you should use for the custom field on a VSTS instance is not `TfsMigrationTool.ReflectedWorkItemId` as .(period) are not valid characters for field name. Instead just use `ReflectedWorkItemId` but note that in the `configuration.json` file the name you need to enter is `NameOfYourCustomisedTemplate.ReflectedWorkItemId`. Where`NameOfYourCustomisedTemplate` is the name of your customised template, any spaces in the name will be replaced by _ (underscore). - -#### Custom Templates #### - -If you migrated a TPC to VSTS using the [data migration tool for Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/migrate/migration-overview) that already had customisations then it will not allow creating an inherited process. You have to exit you customisation in a different manner: - -- Export the current process (this is done from the same Account > Settings page where you do any process customisation in VSTS); this downloads the current customised process as a .ZIP file. -- Once you have the .ZIP file, unpack it and edit the work item type definitions as detailed above for an on-premises installation. -- Once the fields have been added then zip up the folder structure again and re-import it into your VSTS instance, where it will be applied to the Team Project it was exported from. - -### TIP: Checking the actual 'ReflectedWorkItemIDFieldName' ### - -If you are in any doubt over the full name in use for the `ReflectedWorkItemIDFieldName` on either the source or target systems, it can vary based on the type of customisation, use the following process to confirm it - -- Open Visual Studio, connect to the customised Team Project -- Via Team Explorer > Work, create a new work item query. Make sure the `ReflectedWorkItemId` is one of the output columns -- Save the work item query as a file on your local PC -- Open the resulting file in a text editor and check the actual name, it should be in the form `NameOfYourCustomisedTemplate.ReflectedWorkItemId` or `TfsMigrationTool.ReflectedWorkItemId` - -### Editing the configuration ### - -Once you have created the `ReflectedWorkItemId` field and confirmed you have the correct full name for both, the Source and the Target, you will need to edit `configuration.json` to match your values: - - -```JSON -{ - "Source": { - ... - "ReflectedWorkItemIDFieldName": "TfsMigrationTool.ReflectedWorkItemId", - ... - }, - "Target": { - ... - "ReflectedWorkItemIDFieldName": "TfsMigrationTool.ReflectedWorkItemId", - ... - }, - - ...... other stuff - - ], - - ...... other stuff - -} -``` diff --git a/docs/setup/ReflectedWorkItemId.md b/docs/setup/ReflectedWorkItemId.md new file mode 100644 index 000000000..3e900b280 --- /dev/null +++ b/docs/setup/ReflectedWorkItemId.md @@ -0,0 +1,93 @@ +--- +title: ReflectedWorkItemId +layout: page +pageType: index +pageStatus: published +redirect_from: + - /Reference/ReflectedWorkItemId/ +--- + +The Azure DevOps migrations Tools has no internal state, and uses a field on the work item to track the migration of work items. This field is always referd to in the docs as `ReflectedWorkItemId` and is used to track the work item in the target. It enables the ability to resume migrations as well as to be able to scope the work items based on a query and have multiple runs overlap. + +Se below how to add the `ReflectedWorkItemId` to your target project as its diferent for Azure DevOps, TFS, and if you imported your Collection from TFS to Azure DevOps. + +## How to use the ReflectedWorkItemId + +In your configuration file under `MigrationTools:Endpoints` there willbe both a `Source` and a `Target` endpoint. On the `Target` endpoint there should be a property called `ReflectedWorkItemID*` (depending on the specific endpoint implmnetation) that will have a property value like `Custom.ReflectedWorkItemId`. This is the field that the tool will use to track the work items in the target. + +```json +{ + "MigrationTools": { + "Version": "16.0", + "Endpoints": { + "Target": { + "EndpointType": "TfsTeamProjectEndpoint", + "Collection": "https://dev.azure.com/nkdagility-preview/", + "Project": "migrationSource1", + "AllowCrossProjectLinking": false, + "ReflectedWorkItemIDFieldName": "Custom.ReflectedWorkItemId", + "Authentication": { + "AuthenticationMode": "AccessToken", + "AccessToken": "alakjhsaggdsad67869asdjksafksldjhgsjkdghsdkfhskdf", + "NetworkCredentials": { + "UserName": "", + "Password": "", + "Domain": "" + } + }, + "LanguageMaps": { + "AreaPath": "Area", + "IterationPath": "Iteration" + } + } + } + } +} +``` + +When you create the field you will be able to see the`RefName` (diferent from the display name) in the field settings. This is the value that you will use in the configuration file. It will always have at least one `.` in the name. On the inherited processes it will be `Custom.ReflectedWorkItemId` (unless you created your process and added the field many moons ago, inwhich case it will be `processName.ReflectedWorkItemId`). On the XML process it will be whatever you want to call it But I recommned something like `TfsMigrationTool.ReflectedWorkItemId` or just `ReflectedWorkItemId`. + +## Work Items you cant Customise! + +If you need to migratae work items that you cant customsie, then you will need to use one of the built in fields and I recommned `Microsoft.VSTS.Build.IntegrationBuild`. This field is only used by builds, and is realitively safe to use. + +This is primerally of concern for [How-to: Migrating Plans and Suits](_howto/migrating-plans-and-suits.md). + +## How to add the ReflectedWorkItemId + +To add the `ReflectedWorkItemId` to your target project you can use the follow the [Add a custom field to a work item type (Inheritance process)](https://learn.microsoft.com/en-us/azure/devops/organizations/settings/work/add-custom-field?view=azure-devops) documentation from Microsoft. If you are on the older XML process you can follow the [Add a custom field to a work item type (On-premises XML process)](https://learn.microsoft.com/en-us/azure/devops/organizations/settings/work/import-process/customize-process?view=azure-devopss) documentation. + +**Note: We can [help you get off those horible legacy XML Process](https://nkdagility.com/capabilities/azure-devops-migration-services/).** + +### Azure DevOps + +With the advent of the [data migration tool for Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/migrate/migration-overview) there are potentially two ways you need to consider when customising an Azure DevOps process. It all depends how the Team Project was created. + +#### Inherited Process #### + +If you created the Team Project via the web based Azure DevOps UI. You need to [add a custom field through the VSTS UI](https://blogs.msdn.microsoft.com/visualstudioalm/2015/12/10/adding-a-custom-field-to-a-work-item/) to be able to use the tool. + +The name you should use for the custom field on a VSTS instance is not `TfsMigrationTool.ReflectedWorkItemId` as .(period) are not valid characters for field name. Instead just use `ReflectedWorkItemId` but note that in the `configuration.json` file the name you need to enter is `NameOfYourCustomisedTemplate.ReflectedWorkItemId`. Where`NameOfYourCustomisedTemplate` is the name of your customised template, any spaces in the name will be replaced by _ (underscore). + +#### XML Process #### + +If you migrated from on-premises to the cloud using the [data migration tool for Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/migrate/migration-overview) that already had customisations then it will not allow creating an inherited process. Editing the XML Process is much like the on-premises process, but you dont have access to `witadmin` so you will need to do the following: + +- Export the current process (this is done from the same Account > Settings page where you do any process customisation in VSTS); this downloads the current customised process as a .ZIP file. +- Once you have the .ZIP file, unpack it and edit the work item type definitions as detailed above for an on-premises installation. +- Once the fields have been added then zip up the folder structure again and re-import it into your VSTS instance, where it will be applied to the Team Project it was exported from. + +### Team Foundation Server (TFS) Customisation + +Use the `witadmin exportwitd` command to export each work item and add: + +```xml + +``` + +to the Fields section. + +Then use `witadmin importwitd` to re-import the customized work item type template. + +See [MSDN for more details](https://msdn.microsoft.com/en-us/library/dd236914.aspx) + diff --git a/docs/setup/index.md b/docs/setup/index.md new file mode 100644 index 000000000..e79e3f1aa --- /dev/null +++ b/docs/setup/index.md @@ -0,0 +1,29 @@ +--- +title: Setting up the Azure DevOps Migration Tools +layout: page +pageType: index +toc: true +pageStatus: published +discussionId: +--- + +To use these tools you will need to install them and configure your target environment (TFS or Azure DevOps). The following pages will guide you through the process: + +1. [Installation](installation.md) + +The tools are run using `devopsmigration` from the command line. You can use the `--help` option to see the available commands. + +```shell +devopsmigration --help +``` + +2. [Permissions](permissions.md) + +The tools require specific permissions on TFS or Azure DevOps to be able to run. This page will guide you through the minimum permissions required to run the tools. + +3. [ReflectedWorkItemId](reflectedworkitemid.md) + +We use a field on the work item to track the migration of work items. This field is always referred to in the docs as `ReflectedWorkItemId` and is used to track the work item in the target. It enables the ability to resume migrations as well as to be able to scope the work items based on a query and have multiple runs overlap. + +1. [Getting Started](../getstarted/) + diff --git a/docs/installation.md b/docs/setup/installation.md similarity index 98% rename from docs/installation.md rename to docs/setup/installation.md index e76d00902..1c9042e0f 100644 --- a/docs/installation.md +++ b/docs/setup/installation.md @@ -5,6 +5,8 @@ pageType: index toc: true pageStatus: published discussionId: +redirect_from: + - /installation/ --- Install the Azure DevOps Migration Tools on Windows. diff --git a/docs/setup/permissions.md b/docs/setup/permissions.md new file mode 100644 index 000000000..5fdb057db --- /dev/null +++ b/docs/setup/permissions.md @@ -0,0 +1,44 @@ +--- +title: Permissions +layout: page +pageType: index +toc: true +pageStatus: published +discussionId: +redirect_from: + - /permissions/ +--- + +The permissions are courently governed by the needs of the [TFS Client Object Model](https://learn.microsoft.com/en-us/azure/devops/integrate/concepts/dotnet-client-libraries?view=azure-devops) from Microsoft. Microsoft [Announced the deprecation of the WIT and Test Client OM](https://devblogs.microsoft.com/devops/announcing-the-deprecation-of-the-wit-and-test-client-om-at-jan-1-2020-2/) in 2020, however this is still the only way to interact with versions of TFS from 2010 to 2018 with any consistantcy. We are working on moving our tools to the REST API, but this is a large task and will take some time. + +## Minimum Permission Requirements + +At this time the documented minimum required permissions for running the tools are: + +- Account in both the source and target projects with "Project Collection Administrator" rights +- PAT with "full access" for both the Source and the Target + +Note: I have been informed by the Azure DevOps product team information that ObjectModel API only works with full scoped PATs, so it won't work with any PAT that has specific scopes. + +### However! Unsupported Permission Options + +We have seen that the tools may work with less permissions however the following has not been full tested and is not currently supported: + +- Project and Team (Read, write, & manage) +- Work Items (Read, Write & Manage) +- Identity (Read & Manage) +- Security (Manage) + +If you do try this out then please let us know how you get on! + +## TFS, VSTS, & Azure DevOps Server Configuration (On-Premises Only) + +There are some additional requirements that you will need to meet in order to use the tool against your TFS or VSTS server. The Azure DevOps Migration Tools use a flag to Bypass the Work Item rules engine and write data into TFS\VSTS that may not comply with the rules. For example you can write data directly into the `Closed` state without starting at `New`. This is very useful for migrations but requires some pre-requisites. + +## Bypass Rules + +For on-premises instances you need to be part of the `Project Collection Service Accounts` group. You can do this by calling the following command: + +`tfssecurity /g+ "Project Collection Service Accounts" n:domainusername ALLOW /server:http://myserver:8080/tfs` + +This is not required for Azure DevOps Service targets, but you do need to be a Collection Admin on the Target. \ No newline at end of file