Data Migration Tool For Azure Dev Ops Guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 60

Download
Open PDF In Browser	View PDF

Data Migration Tool for
Azure DevOps
Migration Guide

Last updated: April 3, 2019

Download
the latest
version of
this guide.

https://aka.ms/TFSImportData

Published: November 2016
Last updated: April 3, 2019
Change history
Date

Description of changes

September 2018 Updated to reflect that Visual Studio Team Services
(VSTS) has been rebranded to be Azure DevOps
Services.
November 2017 Updated to reflect the fact that the TFS Database
Import Service is now in GA. Additional updates
cover the changes to the identity import
experience.
October 2017

Updated the guide to reflect that import codes are
no longer required for queuing imports. Several
other sections were updated to cover common
questions.

August 2017

Updated guidance to reflect the new
improvements made to TfsMigrator and changes
to the import specification file. In addition, content
was added to section one to address some
common questions.

April 2017

Removed sections that are no longer needed,
minor text tweaks to make common questions
on scenarios clearer, added additional technical
documentation links, and corrected some broken
links.

April 2016

Initial version of the TFS to Visual Studio Team
Services Migration Guide

November 2016 Initial version of the TFS to Visual Studio Team
Services Migration Guide

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of
publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of
Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.
This guide is for informational purposes only. Microsoft makes no warranties, express or implied, in this document. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in,
or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise),
or for any purpose, without the express written permission of Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this
document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any
license to these patents, trademarks, copyrights, or other intellectual property.
© 2016 Microsoft Corporation. All rights reserved.
The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious.
No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be
inferred. Microsoft, Azure, Visual Studio, Xamarin, Windows, Windows Server, SQL Server, Active Directory, Power BI, Office 365, SharePoint, and
PowerShell are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. The names of
actual companies and products mentioned herein may be the trademarks of their respective owners.

Introduction
Ever since Azure DevOps Services was released to provide a hosted SaaS service for
development teams, Azure DevOps Server (formely Team Foundation Server) customers
have been asking Microsoft to be able to import their Azure DevOps Sever databases to take
advantage of all the great capabilities of Azure DevOps Services. We are happy to say that
the data migration tool for Azure DevOps is now available.
This Migration Guide will walk through the different steps along the way. We have organized
the guide into six phases of the migration timeline. The goal of the migration is to move your
team from on-premises Azure DevOps Server to Azure DevOps Services in the cloud. After
the migration, your team will be able to connect to Azure DevOps Services and keep working
like usual with all of the data, permissions, and customizations from your TFS database.

This guide is not meant to replace the technical documentation for the data migration tool,
but is more of a way for you to easily gather the tasks you will need to perform and the
resources you will need to be successful.

How to give feedback for this guide
If you have any suggestions for how we can make this
guide better, please e-mail us at AzureDevOpsImport@
microsoft.com

Download
the latest
version of
this guide.

https://aka.ms/TFSImportData

Introduction
How to find a DevOps Partner to help
We highly recommend finding a trained Microsoft Partner with the DevOps Competency,
Microsoft Consulting Services, or Microsoft Premier Support to help you with your migration
project to Azure DevOps Services. The team at Microsoft has been working very closely
to train the DevOps Partner community so that they can understand the different parts of
migrating to Azure DevOps Services.
Some Microsoft customers may even have help or funding available as part of their Premier
Support Agreement, Enterprise Agreement, or other programs available to assist with getting
help with migrating to Azure DevOps Services and adopting Microsoft Azure. You can contact
your Azure App SSP or Microsoft Reseller to find out more information and if you qualify.
Your Azure App SSP or Microsoft Reseller can help
make recommendations for getting in touch with a
trained Partner to help you with your migration to
Azure DevOps Services. You can also find a list of
trained DevOps parters available at https://aka.ms/
FindDevOpsPartner.

Task: Find a DevOps Partner

Find a DevOps
partner.

https://aka.ms/FindDevOpsPartner

DevOps Partner Name:

Partner Contact Info:

Introduction
How to find your Azure App SSP (Solution Sales Professional)
You may have questions about the different options available for getting access to the
developer tools and services of the Microsoft Cloud including Azure DevOps Services. Your
Azure App SSP or Microsoft Reseller is best equipped to give your team the best guidance
for different types of help available to you. Reach out to your Microsoft Reseller if you
have one, or if you need help with finding your Azure App SSP, you can reach out to us at
FindYourDevSalesRep@microsoft.com.
My Azure App SSP or
Microsoft Reseller:

Contact Info:

How to ask questions about the migration
During your migration, you may have questions that come up. Our first recommendation is to
work with a trained DevOps Partner or Microsoft Consulting Services. If you are not able to
get an answer from them, you can e-mail us at AzureDevOpsImport@microsoft.com.

Get Started

Data Migration Tool for Azure DevOps Migration Guide

Get Started

Task summary

Choose datacenter: Choose the datacenter for your Azure
DevOps organization.

Download data migration tool: Download the data migration tool
from https://aka.ms/DownloadTFSMigrator.

Reserve Azure DevOps Services organization(s): Reserve

Azure DevOps Services organization(s) for each of the desired
final names.

In this first phase, we are going to help you start your Azure DevOps
Services migration project and help you understand why you would want
to migrate from Azure DevOps Server (formely Team Foundation Server)
to Azure DevOps Services.
Note: If you’re currently on Team Foundation Server (TFS), please note
that the product has been rebranded to be Azure DevOps Server with the
2019 release. This guide is still applicable for migrating to Azure DevOps
Server if your organization is using TFS. However, you will still have to
upgrade to one of the supported versions mentioned in chapter 3 of this
guide.

1 Get Started
Why migrate to Azure DevOps Services?
If you are a on-premises Azure DevOps Server customer, you have already understood
how valuable it is to bring your development team together in one place with traceability
from each aspect of the development life-cycle. Now that Azure DevOps Services has been
launched, many customers who have migrated from Azure DevOps Server have said they did
so because:

Upgraded every three weeks

Since Azure DevOps Services is cloudbased, Microsoft automatically upgrades
your organization with the latest features
as they are released. You can stay
up to date on new releases at
https://aka.ms/
AzureDevOpsFeatureTimeline.
Azure DevOps
Features
Timeline.

https://aka.ms/
AzureDevOpsFeatureTimeline

Simplified administration

The Microsoft team will monitor your
Azure DevOps Services organization
around the clock to make sure it is
available for your team. You no longer
need to worry about managing the core
TFS infrastructure any longer.

Accessible from anywhere

Your team members will have the
flexibility they need to securely access
your organization from work, home, or
their mobile devices. If you have remote
development teams, you will have a
great solution to collaborate together
from anywhere.

Cloud-first innovation

Microsoft releases features to Azure
DevOps Services ahead of making it
available in updates from Azure DevOps
Server. You’ll be able to make your team
more productive much sooner.

Included with Visual Studio
subscriptions

Visual Studio (formerly MSDN) subscribers
have Azure DevOps Services already
included as one of their subscription
benefits.

Power your Cloud
Modernization initiatives

Adopting Azure DevOps Services will
help your company with modernizing and
driving agility and DevOps practices by
making it easier to deploy your apps to
the cloud and increase delivery of new
business value.

Leverage developer services in
the Microsoft Cloud
Using Azure DevOps Services allows
you to also take advantage of the many
other developer services in the Microsoft
Cloud like Azure, on-demand build &
deployment servers, the Load Testing
Service, Application Insights, HockeyApp,
Xamarin Test Cloud, and many others.

Get Started

Ready for the Enterprise
Azure DevOps Services is ready for teams of any size including development teams in large
enterprises. There are many enterprise customers who have adopted Azure DevOps Services
and empowering their development teams to collaborate more effectively. Microsoft is also
migrating to Azure DevOps Services as its single engineering system to build its commercial,
internal products, and cloud-based services.

Scalable to any team

Supports teams of any size: from tens to thousands. Backed by a 99.9% SLA and monitored
by our 24x7 operations teams.

Secure by design

Core Azure services provide a secure foundation. Multi-layered security and governance
technologies, operational practices, and compliance policies keep your data locked down.

Compliant

Azure DevOps Services is built on Azure and has the compliance certifications many
enterprises need including ISO 27001 and SOC 1 and SOC 2 compliance which demonstrate
our commitment. More information is available in Phase 2 of this guide.

Azure Active Directory integration

Integration with Azure AD makes it easy to manage entire organizations. Use a common
identity to access both cloud and on-premises resources. Establish and enforce password
lifetime and complexity controls. Enable additional security features like multi-factor
authentication.

Choice of data location

Teams can choose to host their data in different locations around the world including Europe,
Australia, Brazil, India, and the United States.

1 Get Started
Fundamental differences between TFS and Azure DevOps
Authentication
With Azure DevOps Server, you typically connect to a server on your on-premises network
and authenticate with Windows Authentication and Active Directory. With Azure DevOps
Services, you’ll authenticate with Azure Active Directory organization credentials. To provide
additional security, you can also require multi-factor authentication, IP address restrictions,
conditional access, and more. In Phase 2 of this guide, you will go through the steps of
setting up Azure Active Directory if your company has not implemented Azure Active
Directory.

Reporting

Both Azure DevOps Server and Azure DevOps Services have a variety of tools to give your
teams insight into the progress as well as the quality of your software projects. These include:
yy Dashboards and lightweight charts

yy Excel reports, SQL Server Reporting Services reports, and SharePoint dashboards are
available only in Team Foundation Server and not in Azure DevOps Services. These
powerful options have been more complicated to use.

yy A Power BI connector is available only in Azure DevOps Services which provides a nice
combination of simplicity and power.

yy REST APIs are also available for getting live data from Azure DevOps Services
programmatically

Note: Process Customization is now possible in Azure DevOps
Services. If your team projects in Azure DevOps Server includes
process template customizations, you will validate them to make sure
existing customizations are supported during Phase 4 of this migration
guide. Once validated, the data migration tool will import your
database including your process customizations.

Get Started

Data Migrated
Since each collection maps to one database in Azure DevOps Server, and the migration
process works by importing an entire collection, all databases in the collection will be
brought over to Azure DevOps Services. More specifically, this means that all of your work
items, work item history, TFVC changesets, TFVC changeset history, Git data, build definitions,
build history, and other data stored in the collection will be migrated over. Furthermore, the
work item, TFVC changeset, and Git commit numbers/IDs will be retained and won’t change
as part of the migration. It’s important to note that some data isn’t brought along during the
migration. Any data that resides in a separate database outside the collection database won’t
be imported. Prime examples of this scenario include reporting and SharePoint data. There
are also a few other instances where data won’t be brought over:

yy Extensions - Extensions will need to be reinstalled post import. Local extensions will need
to be published to the Marketplace as private extensions and shared with the account
post import to be installed. We’re working on adding Extensions to the migrations as
soon as possible.

yy Service Hooks - Service Hooks data currently isn’t included in the migration process.
Hooks will need to be reconfigured after import.

yy Load Test - Load test data will not be brought over as part of import. You will have to
reconfigure load test after import.

yy Mentions - Mentions of users in work item discussions will remain but reference the
on-premise identity and not the new AAD identity. Hovering on the user name will not
display a contact card. Mentions of pull requests and other work items will have an invalid
hyper-link.

yy Project Server Integrations - Project Server Integration does not exist for Azure DevOps
Services.
Some Azure DevOps Server features can be in preview for import to Azure DevOps
Services. You can elect to include preview features with your import. If a feature isn’t listed
above or in a preview, then the data will be included in your import every time you run
one. You can learn more about what features are in preview by visiting https://aka.ms/
AzureDevOpsImportPreviewFeatures.

1 Get Started
Process Customizations
Azure DevOps Services supports two different process models:
yy Inherited

yy Hosted XML

By default, Hosted XML is turned off in Azure DevOps Services. Only if you have customized
a project in Azure DevOps Server, we will turn on the Hosted XML process model during
import. Once your project is on Hosted XML, there is a path to upgrade it to inherited post
import: https://aka.ms/XMLtoInherited

When importing into Azure DevOps Services, there are limitations and key principles that we
want to make you aware of:

yy Azure DevOps Services is English only - Azure DevOps Server supports multiple
languages, however today, Azure DevOps Services only supports English. If your collection
uses the non-English language, you can’t use the Import Service. This is also true if your
collection has been non-English in the past, and you have converted the language to
English during a TFS upgrade.

yy Inheritance - A project which was created from the Agile, Scrum or CMMI process
template and was never customized, will be on the Inheritance process model after the
import.

yy Hosted XML - Any project with customizations will use the Hosted XML process model.

yy Process per customized project - Although Azure DevOps Services allows projects
to share a process, the data migration tool will create a Hosted XML process for each
customized team project. For example, if you have 30 customized projects, you will have
30 Hosted XML processes to manage. If you want to further customize your Hosted XML
process all your projects, you will need to update each Hosted XML process separately.

yy Consolidate Processes - Azure DevOps Services currently does not support
consolidating projects to use a shared process.

yy Process validation - The process validation of the data migration tool will detect the
target process model for each project. Before you can migrate, you need to fix any
process validation errors for the Hosted XML projects. You might want to consider
updating the process of your projects to match one of our processes (Agile, Scrum or
CMMI) to take benefit of the Inheritance process model. Learn more on the process

Get Started

validation types in our documentation.

New Work Item Form
Work items in Azure DevOps Services have been given a face lift. This is the same modern
experience that appears in TFS 2017 for on-premises customers. If you’re already using the
new modern work item experience then this section can be skipped. The new user experience
provides the building blocks for:
yy Improved readability and usability

yy Richer, interactive experiences within the work item including discussion, code viewing
and more

yy Extensibility support

When a collection is imported, the form definitions for all work item types (WITs) defined
in your project collection undergo an automated transformation to the new layout. This
is a best-effort transformation meant to maintain the field groupings and layout of your
customized WIT definitions. You can manually opt-in to the new experience on-premises
before migrating to the cloud.

Reviewing and optimizing the transformed web layout will allow you to adjust this new
layout to your own needs. Even though these changes can also be done once the import is
completed we recommend you to do them beforehand to prepare for the change.

1 Get Started
Relationship between Azure DevOps Server databases and
Azure DevOps organizations
Before diving too deeply into planning your migration, it’s important to understand at a highlevel how the database import process functions. Imports operate on two main concepts:

Team Project Collection

Collections in Azure DevOps Server are a physical container for team projects and their
artifacts. Each collection equates to a single SQL database and are the source of import
for migrations to Azure DevOps Services.

Azure DevOps Services organization

Organizations are the management unit in the cloud-hosted service. Logically they
map 1:1 to the concept of a team project collection in Azure DevOps Server. Therefore,
organizations are the destination of imports for migrations to Azure DevOps Services.
Azure DevOps Services organizations are represented as https://dev.azure.com/contoso
where contoso represents the name of the Azure DevOps Services organization.
Each time you import a team project collection SQL database, the data migration tool will
create a brand new Azure DevOps organization with a name that you provide. This means
that you cannot import a collection database into an existing Azure DevOps Services
organization or consolidate multiple collection databases into a single Azure DevOps Services
organization. It is a one-to-one mapping between team project collections and Azure
DevOps Services organizations.

Get Started

Team project collection mapping worksheet
Collection
name: