Team Foundation Server to

Azure Devops Services

Migration Guide

Last updated: September 20, 2018

 Published: November 2016
Download
Last updated: September 20, 2018
the latest
version of Change history
this guide. Date Description of changes

September 2018 Updated to reflect that Visual Studio Team Services

(VSTS) has been rebranded to be Azure DevOps
Services.
https://aka.ms/TFSImportData 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

Novemberr 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, Team Foundation Server customers have been asking Microsoft to be
able to import their TFS databases to take advantage of all the great capabilities of Azure
Devops Services. We are happy to say that the TFS Database Import Service for Azure Devops
Services 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 Team Foundation Server (TFS) to Azure Devops Servicesin 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 Database Import
Service 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

Download
If you have any suggestions for how we can make this the latest
guide better, please e-mail us at AzureDevOpsImport@ version of
microsoft.com this guide.

https://aka.ms/TFSImportData

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
1
 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 Find a DevOps
make recommendations for getting in touch with a partner.
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 https://aka.ms/FindDevOpsPartner

DevOps Partner Name:

Partner Contact Info:

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
2 Last updated: September 20, 2018
 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.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
3
1 Get Started

Team Foundation Server to Azure Devops Services Migration Guide

 Get Started 1
Task summary

††Choose datacenter: Choose the datacenter for your Azure Devops

organization.

††Download TFS Migrator tool: Download the TFS Migrator 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 Team Foundation Server to Azure Devops Services.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
5
1 Get Started
Why migrate to Azure Devops Services?
If you are a Team Foundation 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 lifecycle. Now that Azure Devops Services has been launched, many
customers who have migrated from Team Foundation Server have said they did so because:

Upgraded every three weeks Cloud-first innovation

Since Azure Devops Services is cloud- Microsoft releases features to Azure
based, Microsoft automatically upgrades Devops Services ahead of making
your organization with the latest features it available in updates from Team
as they are released. You can stay Foundation Server. You’ll be able to make
up to date on new releases at  your team more productive much sooner.
https://aka.ms/
AzureDevOpsFeatureTimeline. Included with Visual Studio
subscriptions
Azure Devops Visual Studio (formerly MSDN) subscribers
Features have Azure Devops Services already
Timeline. included as one of their subscription
benefits.

Power your Cloud

https://aka.ms/ Modernization initiatives
AzureDevOpsFeatureTimeline Adopting Azure Devops Services will help
your company with modernizing and
driving agility and DevOps practices by
Simplified administration making it easier to deploy your apps to
the cloud and increase delivery of new
The Microsoft team will monitor your
business value.
Azure Devops Services organization
around the clock to make sure it is Leverage developer services in
available for your team. You no longer
need to worry about managing the core
the Microsoft Cloud
TFS infrastructure any longer. Using Azure Devops Services allows
you to also take advantage of the many
Accessible from anywhere other developer services in the Microsoft
Your team members will have the Cloud like Azure, on-demand build &
flexibility they need to securely access deployment servers, the Load Testing
your organization from work, home, or Service, Application Insights, HockeyApp,
their mobile devices. If you have remote Xamarin Test Cloud, and many others.
development teams, you will have a
great solution to collaborate together
from anywhere.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
6 Last updated: September 20, 2018
 Get Started 1
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.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
7
1 Get Started
Fundamental differences between TFS and Azure Devops

Authentication
With TFS, 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 TFS 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 Team Foundation 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 Database Import Service will import your database
including your process customizations.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
8 Last updated: September 20, 2018
 Get Started 1
Data Migrated
Since each collection maps to one database in TFS, 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. supported until TFS 2017 Update 1 is
released
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
hyperlink.
yy Project Server Integrations - Project Server Integration does not exist for Azure Devops
Services.

Some TFS 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.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
9
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 TFS, we will turn on the Hosted XML process model during import. Once your
project is on Hosted XML, there is no path to migrate it to the Inheritance process model. This
is on our roadmap for the end of 2018.
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 - TFS 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 TFS 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 Import Service 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 TfsMigrator 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 validation types in
our documentation.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
10 Last updated: September 20, 2018
 Get Started 1
New Work Item Form
Work items in Azure Devops Services have been given a facelift. 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.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
11
1 Get Started
Relationship between TFS databases and Azure Devops
organizations
Before diving too deeply into planning your migration, it’s important to understand at a high-
level how the database import process functions. Imports operate on two main concepts:

Team Project Collection

Collections in TFS 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 TFS. 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.

Note: In the future, Azure Devops Services will be introducing the

concept of “organizations” that will allow your company to group
multiple Team Services organizations.

Each time you import a team project collection SQL database, the Database Import Service
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.
A

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
12 Last updated: September 20, 2018
 Get Started 1
Team project collection mapping worksheet
Collection  Azure Devops
name: organization
name:

Collection  Azure Devops

name: organization
name:

Collection  Azure Devops

name: organization
name:

Collection  Azure Devops

name: organization
name:

Collection  Azure Devops

name: organization
name:

Datacenter location
You have options for the location of your Azure Devops Services organization data. You
will need to select a region where your data will be imported and mark down that region’s
shorthand code. Later on in the import process you will use that shorthand code. You can
find supported regions for import at https://aka.ms/AzureDevOpsImportPreviewFeatures.

††Task: Choose the datacenter for your Azure Devops Services

organization.
Selected region’s shorthand code:

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
13
1 Get Started
Purchases needed for Azure Devops Services
Another question that typically comes up is what type of licensing will a company need to
adopt Azure Devops Services? The good news is that you are likely to have all of the licenses
you already need. We have created a simplified worksheet below that you can walk through
that should cover most cases. If you have any specific questions about your situation, be sure
to reach out to your Developer Solution Sales Specialist or Microsoft Reseller.

User licenses worksheet

1 Number of team members

2 Number of stakeholders

3 Subtract Line (2) from Line (1)

Number of Visual Studio Subscribers
4
(formerly known as MSDN Subscribers)
5 Subtract Line (4) from Line (3)

6 Subtract 5 from Line (5)

 Stakeholders are free.
 Visual Studio Subscribers have Azure Devops Services included as a benefit of the
subscription.
 Each Azure Devops Services organization gets five free users.

You have no charge for an unlimited number of stakeholders to be able to access your Azure
Devops Services organizations without needing a user license. You also do not have a charge
for any Visual Studio (formerly known as MSDN) subscribers since Azure Devops Services is
included as a benefit of the subscription. Each Azure Devops Services organization includes
no charge for access to the core features of Azure Devops Services for the first five users.

This leaves you with the total number of Azure Devops Services user licenses that you will
need to purchase to cover your team also represented by Line 6 in the worksheet above.

You will ultimately purchase any needed Azure Devops Services user licenses through
the Visual Studio Marketplace or the Azure portal. We will discuss this more in Phase 5 of
this guide.

You can find out more about pricing for Azure Devops Services at
https://aka.ms/AzureDevOpsPricing and leveraging the Azure Pricing Calculator. There
are additional services that you could take advantage of like hosted load testing services,
Test Manager extensions, and more that would have additional costs. If you have any questions
about your specific situation, you can reach out to your DevOps Partner, Microsoft Reseller, or
your Microsoft Developer Solutions Sales Specialist.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
14 Last updated: September 20, 2018
 Get Started 1
Download TFS Migrator tool
The bulk of the work throughout the migration to Azure Devops Services is handled by a new
tool available from Microsoft called TFS Migrator. TFS Migrator will be used throughout this
guide with the following high-level steps:
yy Validating a TFS team project collection
yy Prepare and generate the files used to customize the import
yy Queueing an import of a TFS database with the Database Import Service

You will want to download the latest version of the TFS Migrator tool and then you will run it
from a Windows PC. The user who runs this tool must have:
1. The TFSEXECROLE role in SQL Server, and
2. Permissions to connect to both the TFS configuration and collection databases

††Task: Download the TFS Migrator tool from

https://aka.ms/DownloadTFSMigrator.

Tip: The TFS Migrator tool will be continually updated based on

feedback and our learnings from importing many customer TFS
databases. Be sure to download the latest version of the TFS Migrator
tool each week to keep up to date.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
15
1 Get Started
Reserve your Azure Devops Services organization name(s)
Since the migration project make take some
time to complete, you may want to “reserve” Download the TFS
the name of your Azure Devops Services Migration Tool
organization so that the name can be
available for your final import. For example,
if you are from Contoso company and want
a Team Services organization that matches
your company name like https://dev.azure.com/
contoso, you can create an organization with that https://aka.ms/DownloadTFSMigrator
name now.

However, we mentioned above that you can only import into a brand-new Azure Devops
Services organization. That is okay, because you when you are ready to start the final import,
you could import into a Azure Devops Services organization named https://dev.azure.com/
contoso-temporary and then rename it to the desired name of https://dev.azure.com/contoso
after deleting the originally reserved organization or changing its name to something else.

Tip: If the desired name is already taken, we can help facilitate passing
your contact information to the current owner of the organization.
They can then choose to reach out to you if they want to transfer
ownership or rename their existing organization so that you can
create a new organization with the desired name.

††Task: Reserve Azure Devops Services organization(s) for each of the

desired final names.

Project Limits
Customers with a large numbers of projects in a collection should note that Azure Devops
Services has a limit of 300 projects per organization. Above 300 projects certain experiences,
such as connecting to the organization from Visual Studio, start to degrade. If your collection
has more than 300 projects then you will either need to split the collection or delete older
projects to get below the limit.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
16 Last updated: September 20, 2018
2 Cloud
Prerequisites

Team Foundation Server to Azure Devops Services Migration Guide

2 Cloud Prerequisites
Task summary

††Implement Azure Active Directory: Make sure your team has

a working Azure Active Directory tenant by implementing
Azure Active Directory to synchronize with your on-premises
Active Directory environment.

In the second phase of your migration to Azure Devops Services, we

want to help you focus on some of the prerequisites for migrating their
data to the cloud that many organizations have faced. Some of these
may pertain to you and you will find the resources in the section helpful
to your organization. There are other organizations who already have
each of these prerequisites in place and will be able to bypass the second
phase completely.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
18 Last updated: September 20, 2018
 Cloud Prerequisites 2
Compliance
Azure Devops Services is built on all the great reliability, scalability, and standards compliance
that Microsoft Azure has come to be known for. In addition to the bedrock foundation that
Azure provides, Azure Devops Services has taken the extra steps of getting certification
for individual compliance standards that customers need for their cloud‑based software
development services. To date, Azure Devops Services has the following compliance
certifications:
1. ISO 27001:2013
2. SOC 1 Type 2
3. SOC 2 Type 2
4. HIPAA BAA (Business Associate Agreement)
5. EU Model Clauses

The SOC audit for Azure Devops Services covers

controls for data security, availability, processing
integrity, andjconfidentiality.

Some of our customers who have migrated from Team Foundation Server to Azure Devops
Services have needed to go through internal security reviews before adopting Azure Devops
Services. We have found that the following resources were important in helping internal
security teams feel comfortable with their company adopting Azure Devops Services.

Our internal data protection and security whitepaper

Microsoft strives for transparency about how
we protect your data through multi‑layered Data protection
security and governance technologies, and security
operational practices, and compliance policies. compliance policies
The team has documented its data protection whitepaper.
and security practices in a whitepaper. You can
learn more by reading that whitepaper at
https://aka.ms/AzureDevOpsSecurity.

Compliance audit report https://aka.ms/AzureDevOpsSecurity

requests
The compliance audit reports are available upon request for companies who have Non-
Disclosure Agreements in place with Microsoft. These audit reports were performed by
our auditor, Deloitte. If you would like a copy of these reports, you can send us an e-mail
at AzureDevOpsImport@microsoft.com or you can reach out to your Developer Solution
Specialist.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
19
2 Cloud Prerequisites
Azure Active Directory
The main task for Phase 2 is to make sure your team has a working Azure Active Directory
tenant that will be used for authenticating your team members in your Azure Devops Services
organization.

††Task: Implement Azure Active Directory to synchronize with your

on-premises Active Directory environment.
User authentication in Team Foundation Server is handled on-premises by using
Active Directory. With Azure Devops Services,
users are authenticated through an Azure Active
Microsoft Organizations
Directory tenant which works very similarly to
Active Directory on‑premises. In Phase 5, you will (or MSAs) are available to
be verifying an identity map file that will map your use for authentication with
on‑premises Active Directory organizations to Azure Devops Services but
matching Azure Active Directory organizations. This
will allow each of your team members to see their
not available for mapping
individual history, preserve security permissions, when you are importing
and make sure they have access to all of their a Team Foundation
personal settings including favorites, personal Server database using the
queries, etc.
Database Import Service.
Many companies who leverage services from the
Microsoft Cloud including Office 365 and Azure, already have an Azure Active Directory
tenant setup that is synchronizing user organizations and groups from Active Directory on-
premises. Our recommendation is to not setup a separate Azure AD tenant for your Azure
Devops Services implementation. You will want to use the same Azure Active Directory tenant
as other Microsoft Cloud services at your company.

If your company already has Azure Active Directory available, then you can skip this step in
this guide and move forward.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
20 Last updated: September 20, 2018
 Cloud Prerequisites 2
Synchronizing identities and groups with Azure AD Connect
By synchronizing your on-premises Active Directory with Azure Active Directory, your team
members will be able to use the same credentials to authenticate and your Azure Devops
Services administrators will be able to leverage your Active Directory groups for setting
permissions within your Azure Devops Services organization.

To setup the synchronization, you will want to use the Azure AD Connect technology. You will
likely want to work with your IT department, your DevOps Partner, Microsoft Premier Support,
or Microsoft Consulting Services to help set up Azure AD Connect with your on-premises
environment.

The documentation for setting up Azure AD Connect is available at https://aka.ms/

AzureADConnect.

Note: DirSync was a predecessor technology to Azure AD Connect.

You will want to upgrade to Azure AD Connect if you are using DirSync.

To read more about how Azure Devops Services can be set up to use Azure Active Directory,
you can visit: https://aka.ms/AzureDevOpsAADOrganization. Since you will be importing
your TFS database, you will not be following the steps exactly in that article but it is good
reference information for how it works. The TFS Database Import service will set up the link to
your Azure Active Directory tenant when your Azure Devops Services organization is created
as part of the beginning of the Database Import service process.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
21
2 Cloud Prerequisites
Additional security for Cloud authentication
Once you have Azure Active Directory setup, we have seen many customers take additional
steps that are available natively with Azure Active Directory to provide additional security
measures for access to development team data as well as other data in Microsoft Cloud
services like Office 365 and Azure. The next sections cover optional additional steps you can
take to further secure your Azure Devops Services organization.

Multi-Factor Authentication
One of the main additional security mechanisms that our customers have added is taking
advantage of Multi-Factor Authentication (MFA) requirements as part of getting access to
the data stored in a Azure Devops Services organizations. Two-step verification is a method
of authentication that requires more than one verification method and adds a critical second
layer of security to user sign-ins and transactions. It works by requiring any two or more of
the following verification methods:
yy Something you know (typically a password)
yy Something you have (a trusted device that is not easily duplicated, like a phone)
yy Something you are (biometrics)

You can learn more about setting up Multi-Factor Authentication requirements with Azure
Active Directory here: https://aka.ms/AzureADMFA

Conditional Access
The other common security practice we see with teams adopting Azure Devops Services is
to set conditional access rules in Azure Active Directory that provide for additional security
mechanisms based on which applications they are signing into and from what location they
are signing-in from. For example, you may want to specify that accessing Azure Devops
Services always requires MFA or that MFA is only required if your team member is accessing
Azure Devops Services from outside of the office (i.e., when they are at home, from their
phone, or traveling).

Conditional Access capabilities allow for powerful combinations of security policies based on
your organization’s needs. You can find more information about setting up Azure Conditional
Access here: https://aka.ms/AzureConditionalAccess

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
22 Last updated: September 20, 2018
3 Upgrade TFS

Team Foundation Server to Azure Devops Services Migration Guide

3 Upgrade TFS
Task summary

††Upgrade your Team Foundation Server: Upgrade your

Team Foundation Server to one of the supported versions.

††Run “Configuration Features”: Run the “Configure

Features” wizard on every team project in each of your
team project collections.

One of the major prerequisites for migrating your Team Foundation

Server database is to get your database schema version as close as
possible to what is currently deployed in Azure Devops Services. In Phase
3 of your migration project, you will work on upgrading your Team
Foundation Server to one of the supported versions for the Database
Import Service in Azure Devops Services.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
24 Last updated: September 20, 2018
 Upgrade TFS 3
Timeline of support for TFS versions
It is important to note that the TFS Database Import Service for Azure Devops Services does
not support all versions of TFS databases. At any given time, the Database Import service
will support the current version of TFS and the previous version. Updates are included in the
timeline for supported versions.

We have included a visual representation of how long individual releases will be supported
as soon as new versions come out. We do not currently have release dates for future TFS
updates so we have added sample release dates as examples to help you understand the
impact on the supported database versions timeline.

See which versions of TFS are currently supported here: https://aka.ms/

AzureDevOpsImportSupportedVersions

Sample release schedule

TFS 2017 TFS 2017 TFS 2017
RTM Update 1 Update 2
NOV DEC JAN FEB MAR APR MAY JUN JUL

TFS 2015 Update 3 Support

TFS 2017 RTM Support

TFS 2017 Update 1 Support

TFS 2017 Update 2 Support

~6 month support window (varies)

Sample release schedule—dates are examples and not actual.

Note: It is important to look ahead in the entire migration process. If

you need to upgrade, we suggest that you upgrade to the latest version
of TFS at any given time since you may have a longer migration project
cycle than other customers.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
25
3 Upgrade TFS
Tip: It’s required that you complete at least one “dry run” import per
database you want to import. You should include padding in your
migration timeline for at least one “dry run” database import attempt
to test out the dry run imported Azure Devops Services organization.
We will cover that in Phase 5 and Phase 6 of this guide but it is good
to understand this now so that you can plan accordingly for upgrading
your TFS server and then migrating to Azure Devops Services before
you will need to upgrade your server again.

Upgrade paths
Microsoft has been releasing Team Foundation Server for over 10 years now so many
customers are on various versions. Your goal will be to get to the latest version of TFS as
mentioned in the previous section. Depending on which version of TFS you currently have in
production, you have a few different paths to get you to the latest version of TFS. However,
TFS 2018 does not allow you to have a single-step upgrade from every version of TFS in
the past so your upgrade path may include a few interim steps along the way. We have
summarized each of the upgrade paths in the diagram below from which TFS version you
currently have installed.

If you are using TFS 2012, TFS 2013, TFS 2015, or TFS 2017 upgrade directly to TFS 2018. If
your TFS deployment is on an earlier version, you will need multiple steps. See the illustration
above for our recommended steps.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
26 Last updated: September 20, 2018
 Upgrade TFS 3
Tip: TFS Updates are self-contained as of TFS 2012. As such, there
is no need to upgrade to an RTM version of TFS and then apply the
update – just upgrade to the update version directly. See TFS System
Requirements for Dependencies.

One thing to remember as you plan for upgrades for your Team Foundation Server
environment are the underlying system requirements of the dependencies of TFS at different
TFS versions. TFS has several dependencies that you will need to verify are still supported
along your upgrade path:
yy Operating System yy Project Server yy Office
yy SQL Server yy Visual Studio IDE yy Team Foundation Server Build Agent
yy SharePoint

There is a full list of system requirements for every version of TFS available for your reference
at https://aka.ms/TFSSystemRequirements.

Upgrading Team Foundation Server

Now that you know what your upgrade path looks like for your Team Foundation Server
environment, you can start the steps of upgrading. This is when you will likely want to work
with your selected DevOps Partner, Microsoft Consulting Services, or Microsoft Premier
Support to help you with planning out the upgrade portion of your Azure Devops Services
migration project. Each of these partners are well trained in the steps necessary to upgrade
your Team Foundation Server environment.

††Task: Upgrade your Team Foundation Server.

Upgrade resources
For your convenience, we are including each of the Upgrade Guides for the different Team
Foundation Server upgrades you may need to perform given the upgrade paths above.
yy TFS 2018 Upgrade Guide: https://aka.ms/TFS2018Upgrade
yy TFS 2017 Upgrade Guide: https://aka.ms/TFS2017Upgrade
yy TFS 2013 Update 5 Upgrade Guide: https://aka.ms/TFS2013Upgrade
yy TFS 2012 Update 3 Upgrade Guide: https://aka.ms/TFS2012Upgrade
yy TFS 2010 Upgrade Guide: https://aka.ms/TFS2010Upgrade

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
27
3 Upgrade TFS
Post-upgrade steps
Now that you have upgraded your Team Foundation Server to TFS 2018, there are some
additional post-upgrade tasks that we highly suggest taking before you move to the next
phase of your Azure Devops Services migration project.

Configure Features wizard

††Task: Run the “Configure Features” wizard on every team project in
each of your team project collections.
The process used by your team projects does not get upgraded along with your collection
databases. Instead, you’ll need to run the Configure Features wizard to incorporate process
changes that enable new functionality like agile planning tools and code reviews. This step
is an important part of migrating to Azure Devops Services, since it helps to ensure that the
processes used in your team projects conform to the requirements of the Database Import
Service. To find out more about how to use the “Configure Features” wizard, you can find the
documentation article at https://aka.ms/TFSConfigureFeatures.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
28 Last updated: September 20, 2018
 Upgrade TFS 3
Applying process template updates manually
If you have heavily customized your process or have used third party process templates,
the “Configure Features” wizard may not be able to automatically configure features
for your team projects. In these cases, you will need to configure features manually.
See the section in the documentation article titled “Apply updates manually” in
https://aka.ms/TFSConfigureFeatures for more information. If you find yourself in this
situation, we highly recommend working with a trained DevOps Partner, Microsoft
Consulting Services, or Microsoft Premier Support.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
29
4 Validate Your
TFS Server

Team Foundation Server to Azure Devops Services Migration Guide

 Validate Your TFS Server 4
Task summary

††Run validations with TFS Migration tool: Run the validation of

each team project collection database with the TFS Migrator tool.

††Review logs and fix errors: Review the logs and fix any errors that
were found.

††Repeat validation checks: Repeat the validation and error fixing

process until there are no more errors remaining in the logs.

Now that you have your Team Foundation Server environment upgraded
to the latest version, you will start the work of ensuring that it is ready
to import. The focus of Phase 4 is using the TFS Migrator tool to run
verification steps to discover any errors. This section of the guide will also
help you troubleshoot some common errors that may come up as well as
what to do to fix them.
If you have not downloaded the latest version of the TFS Migrator tool,
refer to Phase 1 of this guide for where to download it.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
31
4 Validate Your TFS Server
Validating a team project collection
Since each team project collection is its own SQL database in TFS, you will run the validation
process on each team project collection in your environment. Validation will examine a variety
of aspects of your collection, including:
yy Size of your collection database
yy Collation of the SQL database
yy Identities of users in the collection
yy Analyze process template customizations

††Task: Run the validation of each team project collection database with
the TFS Migrator tool.
You begin a validation by using the TFS Migrator tool. We recommend that you run the TFS
Migrator tool from one of the application tier (AT) servers for your TFS environment. You can
find out more about the specific command-line options by requesting the help text with the
command below.

TfsMigrator validate /help

The most common way to start a validation is to specify the URL of the team project
collection with the command below.

TfsMigrator validate /collection:http://localhost:8080/tfs/

DefaultCollection

There is additional technical documentation available for the validation phase available at
https://aka.ms/AzureDevOpsImportValidate.

Review validation warnings and errors

Once the TFS Migrator
tool is finished, there
will be a set of log
files and a set of
results printed to the
command prompt
screen.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
32 Last updated: September 20, 2018
 Validate Your TFS Server 4
If there were no errors and all the validation checks have passed, then your team project
collection is ready and you can move on to the next phase. If it does not say that all of the
validation checks have passed, then you will need to look through the log files to find any
errors and fix them.

††Task: Review the logs and fix any errors that were found.
There are a set of logs that are generated during the validation phase. The main log that
you will want to focus on is the TfsMigrator.log file which contains the main details on the
validation checks that were run. The other files exist to contain only the errors in the section
of the validation checks that match their file name.

The TryMatchOobProcesses.log contains the list of errors that would block your projects
from landing in the inherited process model post import. TfsMigrator will look at your
projects and determine if a project is using an Out-of-Box (OOB) process such as Agile,
Scrum, or CMMI. If it is, and it does not contain any customizations, that project will be
brought into the inherited model. Errors in this file will not prevent you from doing an import.
If you have customizations that you want to keep during import then this log can be ignored.
Instead you should focus on the errors in the TfsMigrator.log file.

Learn more about how processes are imported at https://aka.ms/ImportProcesses

There are several types of errors that could show up in the logs from the validation checks.
Solutions for many of the errors are being documented in our troubleshooting guide at
https://aka.ms/AzureDevOpsImportTroubleshooting. You should also leverage your trained
DevOps Partner, Microsoft Consulting Services, or Microsoft Premier Support to help you
with solutions for each of the errors you encounter.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
33
4 Validate Your TFS Server
Process template errors
The most common types of errors that we have seen have been process template errors that
are either because the latest features of TFS have not been added to older team projects or
there are customizations that Azure Devops Services does not support now. There are many
customizations that Azure Devops Services does support so the validation checks only look
for customizations that need to be fixed before migrating to Azure Devops Services.

A list of supported process customizations is available at

https://aka.ms/SupportedProcessCustomizations

At the end of Phase 3, you ran the “Configure Features” wizard on each of the team projects
in your collections so you should not have any errors related to missing process template
items from newer features of TFS.

For the remaining types of process errors, you will use the witadmin.exe command-line tool
that is included with installations of Visual Studio. There is deeper technical documentation
for addressing many of the process errors that show up in the validation logs at https://aka.
ms/ImportProcesses.

There are a few tips for tools you can use to help you with addressing process errors in
addition to witadmin.exe.

To help with troubleshooting process template errors, you may want to automate exporting
the process templates for each of the team projects in your team project collection. There is
an undocumented command for the TFS Migrator tool that will help you out. You can add
this option at the end of the validate command to generate zip files of each of the process
templates used by each of the team projects.

TfsMigrator validate /collection:http://localhost:8080/tfs/

DefaultCollection -SaveProcessZips

Another tool that many TFS administrators find helpful in this scenario is the TFS Team Project
Manager available on CodePlex at https://aka.ms/TeamProjectManager. One of the most
useful features of this tool is the ability to compare each team project with known process
templates (like the out of the box process templates). You can then look at the comparison
details for the work item types and project process configuration settings to see what
is different.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
34 Last updated: September 20, 2018
 Validate Your TFS Server 4
Collection size
The TFS Database Import Service for Azure Devops Services can import very large databases,
but once a database reaches a certain size it will have to be imported using a method other
than the DACPAC method discussed heavily in the latter part of this guide. TfsMigrator will
let you know if you need to use the alternative method of setting up a SQL Azure VM to
complete an import. If you don’t see any collection size warnings then you can continue with
the DACPAC method. Details on proceeding with both methods are discussed in Phase 6. This
includes links to deeper technical documentation for configuring a SQL Azure VM should you
need to go that route.

SQL Database collation

There are only two collations natively supported by the TFS Database Import Service and
Azure Devops Services. Those two collations are:
yy SQL_Latin1_General_CP1_CI_AS
yy Latin1_General_CI_AS

If you have a different collation, it’s still possible to import. See the following page for more
details: https://aka.ms/AzureDevOpsImportCollations

Repeating the validation checks

There will be a few iterations where you will resolve some errors and then repeat running
the validation checks to see if the error is no longer detected in the validation log files.
You will want to repeat this process until there are no more errors and you see the success
confirmation that all collection validation checks have passed.

††Task: Repeat this validation and error fixing process until there are no
more errors remaining in the logs.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
35
5 Get Ready
for Import

Team Foundation Server to Azure Devops Services Migration Guide

 Get Ready for Import 5
Task summary

††Assign, activate, and map Azure Devops Services subscriptions:

Ensure that each of the Visual Studio (formerly MSDN)
subscriptions are assigned, activated, and mapped to each
subscriber’s Azure Active Directory organization.

††Generate import settings: Generate import settings and related

files using the TfsMigrator prepare command.

††Provide the configurable settings: Provide the configurable

settings in the Import Specification file.

††Review the Identity Map log file

††Task: Create an Azure Storage Container in the same datacenter
as the final Azure Devops Services organization.

Now that you have confirmed that your Team Foundation Server
collection database is validated, your team can start to prepare for
your dry run and final imports. This section of the guide is dedicated to
preparing your team and generating the files that are needed by the TFS
Database Import Service in Azure Devops Services.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
37
5 Get Ready for Import
Subscriptions
You may remember from Phase 1 of this guide that Visual Studio (formerly MSDN)
subscribers include access to Azure Devops Services as a benefit of their subscription.
Taking advantage of that benefit requires that each subscription is assigned, activated, and
mapped to the Azure Active Directory organization for the subscriber if the subscription is
not assigned to the Azure Active Directory organization from the beginning. This will likely
take some time since each of your team members will potentially have action items and you
will want to work with your company’s designated Visual Studio Subscriptions Administrator
(formerly MSDN Administrator).

††Task: Ensure that each of the Visual Studio (formerly MSDN)

subscriptions are assigned, activated, and mapped to each
subscriber’s Azure Active Directory organization.
The high-level set of steps for each subscription your team owns are:
1. The Visual Studio Subscriptions Administrator logs into the Administrator’s Portal and
assigns a subscription to each of the team members. The recommended approach for
this step is to assign the subscription to the Azure Active Directory organization of
the subscriber.
2. The subscriber then goes to the subscriber portal and logs in with the same e-mail
address to activate the subscription.
3. If the subscription was activated using a Microsoft Organization (MSA), then
the subscriber will need to link their Azure Active Directory organization to their
subscription so that Azure Devops Services will recognize the subscriber’s benefit when
they login to Azure Devops Services with their Azure Active Directory organization.

Assign subscription
In the first step, the Subscriptions Administrator for your company will log in to the
Administrator’s Portal (https://aka.ms/VSSubscriptionAdminPortal) and assign each of the
available subscriptions to the relevant team members.

The new portal supports assigning a subscription to an Azure Active Directory organization,
so we highly recommend that the administrator assigns the subscription to the Azure Active
Directory organization for the subscriber (i.e., johndoe@contoso.com) instead of assigning to
a personal Microsoft Organization (johndoe@outlook.com).

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
38 Last updated: September 20, 2018
 Get Ready for Import 5
Activate subscription
Each subscriber will then login to the Visual Studio Subscriptions Portal at https://
my.visualstudio.com with the organization that was assigned. If the administrator assigned the
subscription to the subscriber’s Azure Active Directory organization, then they need to sign-in
with their Azure Active Directory organization.

Link subscription to Azure Active Directory organization

Many legacy subscribers will find that their subscription was assigned to and activated
with a Microsoft Organization. The last step for each subscriber to take is to link the
Visual Studio Subscription to their Azure Active Directory organization. There are a
few different methods for doing this step which are documented at https://aka.ms/
LinkVSSubscriptionToAADOrganization.

Note: This is a very important step for each subscriber to complete

before the final production import of your TFS database.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
39
5 Get Ready for Import
Help with subscriptions
If your team needs any help with activating the benefits of your subscriptions, you can
reach out to the Support team at https://aka.ms/VSSubscriptionHelp. When creating a new
support case, choose “Organization, Subscription, and Billing Support” and then “Activate my
subscription benefits” to get started.

Generate import files with prepare step in TfsMigrator

You are ready to generate the import specification and related files you will need to queue
an import of your TFS collection database. This section will cover the different files that are
produced but first you will need to run the prepare command to generate them.

TfsMigrator prepare /collection:http://localhost:8080/tfs/DefaultCollection/

tenantDomainName:contoso.com /Region:CUS

The tenant domain name option is the name of your company’s Azure Active Directory
tenant. The prepare command will contact your Azure Active Directory tenant so it will
prompt you to login with a user from the tenant with permissions to read information
about all of the users in the Azure Active Directory tenant. It is important to understand
that the prepare command needs to have access to the Internet for this step. If your TFS
server does not have access to the Internet, then you will need to run this command from
a different computer.

Organization region refers to the location you plan to import your TFS collection into Azure
Devops Services. In Phase 1 you selected a region and recorded its shorthand code to be
used in the prepare command. Just in case, a list of supported regions can be discovered on
the following page https://aka.ms/ImportSupportedRegion.

More information about the prepare command is available at

https://aka.ms/TfsMigratorPrepare.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
40 Last updated: September 20, 2018
 Get Ready for Import 5
††Task: Generate import settings and related files using the
TfsMigrator prepare command.

Import specification file

The import specification file is a JSON file that will instruct the TFS Database Import service
how to configure your imported Azure Devops Services organization, specify the source file
locations, and customize the import.

††Task: Provide the configurable settings in the Import Specification file.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
41
5 Get Ready for Import
Several of the fields are auto-populated during the prepare step but some will need to be
configured by you. The fields that you will need to provide are:
yy Organization Name: the name of the Azure Devops Services organization that you want
to be created for importing your data.
yy Location: a backup of your database and import files will be uploaded to an Azure
storage container. This field specifies the SAS key that will be used by the TFS Database
Import Service to securely connect to and read the source files from the Azure storage
container. Creating the storage container will be covered later in Phase 5 and generating
a SAS key will be covered in Phase 6 before you queue a new import.
yy Dacpac: a file that packages up your collection’s SQL database.
yy Import Type: The type of import: DryRun or ProductionRun

More information about the import specification file can be found at

https://aka.ms/AzureDevOpsImportSpecification.

Note: Each import specification file is meant for a single collection.

If you try to use an import specification file generated for another
collection the import won’t start. You will need to run prepare for
each collection you wish to import and use the generated import
specification file to queue the import.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
42 Last updated: September 20, 2018
 Get Ready for Import 5
Identity Map Log
Arguably the identity map log is of equal importance to the actual data that you will be
migrating to Azure Devops Services. When reviewing the log file it’s important to understand
how identity import operates and what the potential results could entail. When importing an
identity, they could either end up becoming active or historical. The difference between active
and historical identities is that active identities can log into Azure Devops Services whereas
historical identities cannot. It’s important to note that once imported as a historical identity,
there is no way to move that identity to become active.

For a detailed explanation of the identity map log file see the following page: https://aka.ms/
AzureDevOpsIdentityMapLog

††Task: Review the Identity Map log file

Historical vs. active identities
When importing an identity, the Import service will decide whether the identity will become
active or historical.

Note: It is important to note that once an identity is imported as a

historical identity, there is no way to transition that identity to become
active again in the future.

Active identities

Identities that will be active users in Azure Devops Services after imported. Active identities
will have a license and show up as a user in the organization after migration. Active identities
are included in the mapping file. If you want an identity to be active post-migration, make
sure to include a correct mapping in the identity mapping file.

Historical identities

Identities that are not specified in the identity mapping file or the identity mapping line
is not completely filled out. Historical identities do not have access to the Azure Devops
Services organization post-migration, do not have licenses, and do not show up as a user in
the organization. They will be included in the history of data like version control, work items,
builds, and other places where they have contributed in the past. Historical identities are
recommended for users that are no longer at the company or will not ever be needing access
to the Azure Devops Services organization again. Historical identities cannot be converted to
an active identity in the future.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
43
5 Get Ready for Import
Licenses
During import, licenses are assigned automatically for all users displayed as ‘active’ in the
“Expected Import Status” column of identity map log. If automatic license assignment is
incorrect, don’t worry all license assignments can be changed via the Azure Devops Services
User Hub by editing the “access level” of the user(s) after import is complete. We realize that
our assignment may not always be perfect, so you will have until the 1st of the following
month to reassign licenses as needed. If by the 1st of the next month you haven’t linked a
subscription to your organization and purchased the correct number of licenses, all of your
grace period licenses will be revoked. Alternatively, if auto assignment assigned more licenses
than you purchased for next month, then you will not be charged for the extra licenses, but all
unpaid licenses will be revoked. To avoid losing access, we recommend you link a subscription
and purchase needed licenses before the 1st of the month. For all dry runs, licenses are free
for as long as the organization is active.

Azure Devops Subscriptions

††Task: Verify and update licenses in the identity map
Visual Studio Subscriptions (formerly known as MSDN benefits) aren’t assigned by default for
imports. Instead, users with Visual Studio Subscriptions will be automatically upgraded to use
that license. As long as a user’s work organization is linked correctly, Azure Devops Services
will automatically apply their Visual Studio subscription benefits on their first login post
import.

You don’t need to repeat a dry run import if users don’t automatically get upgraded to use
their Visual Studio Subscription in Azure Devops Services. Visual Studio Subscription linking is
something that happens outside of the scope of an import. As long as the work organization
gets linked correctly before or after the import then the user will automatically have their
license upgraded on the next sign in. Once they’ve been upgraded successfully, next time you
import the user will be upgraded automatically on the first sign in to the organization. See
earlier in Phase 5 for details on setting up this link.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
44 Last updated: September 20, 2018
 Get Ready for Import 5
Create an Azure Storage Container in chosen datacenter
Using the TFS Database Import Service for Azure Devops Services requires having an
Azure Storage container in the same Azure datacenter as the final Azure Devops Services
organization. For example, if you intend for your Azure Devops Services organization to
be created in the Central United States datacenter, then you will want to create the Azure
Storage container in that same datacenter. This will drastically speed up the time that it takes
to import the SQL database since the transfer will occur within the same datacenter.

††Task: Create an Azure Storage Container in the same datacenter as

the final Azure Devops Services organization.
You can find out more about creating storage containers at https://aka.ms/
CreateAzureStorageContainer.

Worksheet
Azure Storage
Container
Name:

Datacenter
Location:

Set up Azure subscription for billing

A grace period is placed on the newly imported Azure Devops Services organization to allow
your team to finish any steps it needs and correct license assignments. If you anticipate
needing to purchase any additional user plans, build/deployment pipelines, hosted build
services, hosted load test services, or other developer services, we highly recommend making
sure that you have an Azure Subscription ready for linking to your imported Azure Devops
Services organization once the import has completed. The grace period ends on the first day
of the following month after you have completed your import.

We will remind you again in Phase 6 for when you will need to do the linking. This
preparation step is more about making sure that you know which Azure Subscription you will
use in that later step. You can find out more about setting up an Azure Subscription for Azure
Devops Services billing at https://aka.ms/AzureDevOpsSetupBilling.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
45
6 Import

Team Foundation Server to Azure Devops Services Migration Guide

 Import 6
Task summary

††Dry run of end-to-end import: Complete a dry run of the end-to-

end import before scheduling your production import.

††Detach the team project collection: Detach the team project

collection in TFS Administration Console.

††Create portable backup: Create portable backup of the Team

Project Collection SQL database.

††Upload SQL database backup: Upload SQL database backup and

identity map to Azure Storage Container.

††Generate SAS key: Generate a SAS key for the Azure Storage
container and modify your import settings file to include the
SAS Key.

††Delete previous dry run organizations: Delete any previous dry

run Azure Devops Services organizations.

††Rename imported organization: Rename the imported Azure

Devops Services organization to the desired name that was
reserved in Phase 1.

††Set up billing: Set up the billing for the Azure Devops Services
Organization with the Azure subscription identified in Phase 5.

††Reconnect to new organization: Reconnect on-premises

build servers to the newly-imported Azure Devops Services
organization.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
47
6 Import
The great news is that your team is now ready to begin the process of
starting a dry run of your import and then finally a full production import
run. In this phase of the guide, we will walk through the final steps to
queue an import as well as discuss the other topics that typically come up
at the end of the migration project to get you prepared.

††Task: Complete a dry run of the end to end import before scheduling
your production import.

Considerations for roll back planning

A common concern that teams have for the final production run is to think through what the
rollback plan will be if the import failures. This is also why we highly recommend doing a dry
run to make sure you are able to import into Azure Devops Services successfully and that
everything is as you expected it to be post import.

Rollback for the final production run is fairly simple. Before you queue the import, you will
be detaching the team project collection from Team Foundation Server which will make it
unavailable to your team members. If for any reason, you need to roll back the production
run and have Team Foundation Server come back online for your team members, you can
simply attach the team project collection on-premises again and inform your team that
they will continue to work as normal while your team regroups to understand any potential
failures.

You can then reach out to Azure Devops Services customer support for assistance with
understanding the cause of the failure. Customer support tickets can be opened from the
following page https://aka.ms/AzureDevOpsImportSupport. It’s important to note that if the
issue requires product group engineers to engage that those cases will be handled during
regular business hours.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
48 Last updated: September 20, 2018
 Import 6
Timing worksheet
One thing that is very helpful is to keep track of the timing for each of the steps during the
dry run import so that you can start to plan out your final production import timeframe. The
worksheet below will help you keep track of the different steps to time for your dry run(s) and
production import.

Time for each step

Dry Run Import #1 Dry Run Import #2 Production Import

Detach Collection

Generate Backup
of SQL Database

Upload Backup
and Identity Map
to Azure Storage

Queue Import

Final UAT
Verification of
Imported Azure
Devops Services
Organization

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
49
6 Import
Detach your team project collection from Team
Foundation Server
Before generating a backup of your SQL database, the TFS Database Import Service requires
the collection to be completely detached from Team Foundation Server (not SQL). The detach
process in TFS transfers user identity information that is stored outside of the collection
database and makes it portable to move to a new TFS server or in this case, to Azure Devops
Services.

††Task: Detach the team project collection in TFS

Administration Console.
Detaching a collection is easily done from the TFS Administration Console on your TFS
server. There is a walkthrough for detaching the team project collection at https://aka.ms/
DetachTFSCollection.

Generate database backup

If TfsMigrator didn’t produce any warnings about your collection’s size, the TFS Database
Import Service is able to import from a specific SQL backup format: DACPAC. You can find the
command-line tool necessary for generating DACPAC files in the SQL Server Data Tools. Here
is a sample command-line entry for generating a DACPAC backup file.

SqlPackage.exe /sourceconnectionstring:”Data Source=localhost;Initial

Catalog=Tfs_Foo;Integrated Security=True” /targetFile:C:\DACPAC\
Tfs_Foo.dacpac /action:extract /p:ExtractAllTableData=true
/p:IgnoreUserLoginMappings=true /p:IgnorePermissions=true
/p:Storage=Memory
There is more information about generating DACPAC backup files and where to find SQL
Server Data Tools available at https://aka.ms/CreateTFSBackupDACPAC.

††Task: Create portable backup of the team project collection

SQL database.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
50 Last updated: September 20, 2018
 Import 6
Alternate method: importing large collection databases
If TfsMigrator warned that your collection was too big, you will not want to generate a
DACPAC backup of your SQL database. There is an alternate method that you will need to
take which is setting up your own SQL Server in the same Azure datacenter, restoring the
database there, and updating your import settings with a connection string to your database
for the TFS Database Import Service to use to create a direct connection for importing your
database.

You can find out more about the alternate method of importing if you have a large collection
at https://aka.ms/AzureDevOpsImportLargeCollection.

Dry run only: attach team project collection again

If this is your dry run import, once the SQL database backup of the fully detached TFS team
project collection has fully completed, you can attach the team project collection again to
make it available to your team members while you continue the rest of the import steps.

If this is your production import, we do not recommend attaching your collection to TFS
again unless you need to rollback your final import attempt and have TFS available for your
team members to continue working.

Upload backup and identity map to Azure Storage Container

Once you have your DACPAC backup file ready, you can upload it to the Azure Storage Once
you have your DACPAC backup file ready, you can upload it to the Azure Storage container
that you created in Phase 5 of this guide. The time to copy can vary depending on your
Internet speed and the size of your backup file. If you’re providing your collection data via
the alternate SQL Azure VM method then you don’t need to upload anything to a storage
organization - it’s not required.

One of the best methods for copying to an Azure Storage container is by using the AzCopy
tool. You can find out more how to use it at https://aka.ms/StorageAzCopy.

††Task: Upload SQL database backup and identity map to Azure

Storage Container

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
51
6 Import
Generate SAS key for the Azure Storage Container
The last setting in the import settings file that you will need to update is the SAS key for the
Azure Storage Container so that the TFS Database Import Service can securely connect to the
storage container to give the Import Service the minimal set of permissions needed to access
your team’s data. The SAS key can even be time limited to cut off access after a desired time
period. It is strongly recommended that you time limit the key to be enabled for at least a
minimum of seven days.

Note: It is important to treat the SAS key as a secret. Do not leave the
key in an insecure location as it grants read and list access to any data
that you have stored in the container.

You can find out how to generate a SAS key at https://aka.ms/GenerateSASKey.

††Task: Generate a SAS key for the Azure Storage container and modify
your import settings file to include the SAS key.

Delete previous dry run import Azure Devops Services

organizations
Before you can run a second dry run import or the final production import, you will
need to make sure you delete any previous Azure Devops Services organizations
that were created in a previous dry run. You can follow the steps at https://aka.ms/
AzureDevOpsDeleteOrganization.

††Task: Delete any previous dry run Azure Devops Services

organizations.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
52 Last updated: September 20, 2018
 Import 6
Queue the import
You are now ready to queue the import with the TFS Database Import Service. Ensure that the
import specification file has been completed. Then you can simply queue the import with the
following command.

TfsMigrator import /importFile:C:\TFSDataImportFiles\import.json

This will begin the import and the user that queued the import will own the imported
account. They will also receive an e-mail whenever the import has failed or succeeded. If you
receive an email that your import failed please reach out to Azure Devops Services customer
support for assistance at https://aka.ms/AzureDevOpsImportSupport.

Post-import steps
A success e-mail will be sent to the organization owner as soon as the import has successfully
completed. At this point, anyone with access will be able to login to the newly imported
Azure Devops Services organization. There are a few remaining items that you may want to
perform but for the most part, the Azure Devops Services organization is ready for your team
members to use.

We have captured some of the common steps here but you can find an updated list of
post‑import topics at https://aka.ms/AzureDevOpsPostImport.

Rename final imported organization to desired name

In Phase 1 of this guide, you may have preemptively created organizations with the final
Azure Devops Services organization names that you want to use. If this is your final import,
you can rename your newly imported Azure Devops Services organization to that desired
name. The steps to take at a high‑level are:
1. Rename placeholder organization to a different name. For example, from dev.azure.
com/contoso to dev.azure.com/contoso-old
2. Wait for approximately 1 hour for the desired name to become available again
3. Rename the newly imported organization to the desired name. For example, from dev.
azure.com/contoso-import to dev.azure.com/contoso

You can rename a Azure Devops Services organization by following the directions at https://
aka.ms/AzureDevOpsRenameOrganization.

††Task: Rename the imported Azure Devops Services organization to

the desired name that was reserved in Phase 1.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
53
6 Import
Set up billing
Now that the Azure Devops Services Organization is created, you can complete the final
steps of linking the Azure subscription identified in Phase 5 of this guide so that billing is now
linked correctly.

Note: If you are not needing to purchase any additional licenses or

needing any additional services like builds, deployments, load testing,
marketplace extensions, etc. then you can skip this step.

As a reminder, the final steps of setting up billing with an Azure subscription are detailed at
https://aka.ms/AzureDevOpsSetupBilling.

††Task: Setup the billing for the Azure Devops Services Organization
with the Azure subscription identified in Phase 5.

Configure build agents

If you were using automated build or deployment servers in your Team Foundation Server
environment, you can now connect them to your Azure Devops Services organization. As
part of the import, all of your build definitions have been brought over, but agents and pools
need to be reconfigured against the new Azure Devops Services organization.

You can find the additional steps needed at https://aka.ms/AzureDevOpsPostImportBuilds.

††Task: Reconnect on-premises build servers to the newly imported

Azure Devops Services organization.

Hosted build and deployment pipelines

Your team can also explore taking advantage of the hosted build servers available now that
your team has adopted Azure Devops Services. Many customers who have transitioned from
Team Foundation Server to Azure Devops Services have told us that they were able to retire
some of their custom build hardware by leveraging the hosted build & deployment services
available in Azure Devops Services.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
54 Last updated: September 20, 2018
 Summary
Congratulations! Your team is now in Azure Devops Services and you do
not need to worry about upgrading your instance again. Now that you
are in Azure Devops Services you will receive new updates frequently and
have many opportunities to implement tools and processes that will help
your team to be more effective in building quality software.

Roadmap and release notes for Visual Studio Team Services

New releases are deployed approximately every three weeks and we want to make sure you
and your team have the information you need to stay up to date with everything that is new.
At the same time, we want to make sure you know where we are investing in helping your
development teams.

You can find both our roadmap and a detailed set of release notes for each deployment at
https://aka.ms/AzureDevOpsFeatureTimeline.

Deployment
roadmap and
release notes.

https://aka.ms/
AzureDevOpsFeatureTimeline

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
55
 Summary
Find new extensions in the Azure Devops Services Marketplace
The Azure Devops Services Marketplace is one of the major benefits of adopting Azure
Devops Services because each of the extensions are extremely easy to install and configure
with your Azure Devops Services Organization. There are many extensions that will add new
build/deployment tasks, integrations with many third-party services, and add incredible value
for your teams to get more out of the information & functionality in Azure Devops Services.

Some of the first extensions you should immediately install are:

yy Code Search
yy Package Management
yy HockeyApp
yy Microsoft Teams Integration
yy Test & Feedback
yy Application Insights

You can find the Azure Devops Services Marketplace at https://aka.ms/Azure Devops
ServicesMarketplace.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
56 Last updated: September 20, 2018
 Summary
Move forward with other developer services from the
Microsoft Cloud
Working in Azure Devops Services means that it is much easier to take advantage of the many
other services available for development teams. Be sure to look at these additional services in
the Microsoft Cloud.
yy Microsoft Azure
yy SQL Server and SQL Azure
yy Application Insights
yy HockeyApp
yy Xamarin Test Cloud
yy Development/Test Labs in Microsoft Azure
yy Office 365
yy Dynamics

Stay connected and involved

As your teams start to leverage more of the many solutions available in Azure Devops
Services, please be sure to stay connected and involved with helping us know what you think
we should be building to make Azure Devops Services even better. We have a User Voice
site where you can suggest new features and vote on other developer’s feature requests to
help us prioritize our future investments. You can find that User Voice site at https://aka.ms/
AzureDevOpsUserVoice.

Introduction | 1. Get Started | 2. Prerequisites | 3. Upgrade | 4. Validate | 5. Get Ready | 6. Import | Summary
Last updated: September 20, 2018
57
© 2016 Microsoft Corporation.