Merge branch 'master' into develop

ALM-Rangers · Nov 27, 2015 · 47a8bee · 47a8bee
2 parents 723144a + 19fa68c
commit 47a8bee
Show file tree

Hide file tree

Showing 11 changed files with 558 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-## Migrate assets from RM server to VSO ##
+## Migrate assets from RM server to Visual Studio Team Services ##
 
 > **PREVIEW NOTICE**
 > This project is still *UNDER CONSTRUCTION*. Tooling and
@@ -8,25 +8,37 @@
 > product!
 
 ### What ###
-As Bob,the Release Manager, I would like to migrate my assets from 2015 or 2013 U4 RM server to VSO, and start using the Release hub in Team Web Access. 
+As Bob,the Release Manager, I would like to migrate my assets from 2015 or 2013 U4 RM server to Visual Studio Team Services, and start using the Release hub in Team Web Access. 
 
 ### What about TFS? ###
-This solution currently targets VSO, but will be applicable to migration to the new RM features in TFS in a future version of TFS.
+This solution currently targets Visual Studio Team Services, but will be applicable to migration to the new RM features in TFS in a future version of TFS.
 
 ### Why ###
-As the new release management capabilities are going to part of TFS, and as customers are currently using the WPF client along with RM server, there is a need to help them migrate their assets into the new model. Most of these customers are using agent-based release templates. 
+Customers have so far been interacting with RM Server using the WPF client, configuring the release templates and managing their pipelines using the XAML based workflow system. The new release management capabilities, that are available with VS Team Services and are going to be a part of TFS in a future version of TFS, are based on a light-weight workflow system.
 
-Their release templates are scripted using the RM server’s XAML based workflow system. The next generation of release management features in TFS are based on a light-weight workflow system and do not have all the fine-grain tasks that were otherwise available in RM server.
+The agent-based release templates authored using the WPF client used a set of fine-grained tasks that were available with the RM Server. The new workflow system does not provide all those tasks out of the box, making it harder to upgrade the templates to the new capabilities.
 
-However, since both of them leverage Powershell heavily, it is possible to at least partially migrate the data from one to the other. This project aims to provide the guidance and tooling to help you with this migration.
+However, since both of them leverage Powershell heavily, it is possible to partially migrate the data from one to the other. This project aims to provide the guidance and tooling to help you with this migration.
 
 ### Find out more ###
-- [Migration Overview](@) **COMING SOON**
-- [PowerShell Requirements and Setup](@) **COMING SOON**
-- [Migration tooling output](@) **COMING SOON**
-- [Command line walk-through](@) **COMING SOON**
-- [PowerShell Script usage walk-through](@) **COMING SOON**
 
-### Notices ###
+**General**
+
+- [Announcement: Moving from the earlier version of Release management service to the new one in Visual Studio Team Services](http://blogs.msdn.com/b/visualstudioalm/archive/2015/11/19/moving-from-the-earlier-version-of-release-management-service-to-the-new-one-in-visual-studio-team-services.aspx)
+- [Release Management for VSTS preview version](https://msdn.microsoft.com/Library/vs/alm/Release/overview-rmpreview)
+- [Migrating Release Management 2013/2015 to Release Management Service](http://incyclesoftware.com/2015/11/migrating-release-management-20132015-to-release-management-service/)
+
+**Guides**
+
+- [RM Workflow Migrator Guide](doc/RM-Workflow-Migrator-Guide.md)
 
+**Walk-throughs**
+
+- [Lab 1 - Using the RMWorkFlowMigrator to create release scripts](doc/Lab-1-Using-the-RMWorkFlowMigrator-to-create-release-scripts.md)
+- [Lab 2 - Using the resulting release scripts in a release pipeline](doc/Lab-2-Using-the-resulting-release-scripts-in-a-release-pipeline.md)
+
+### The team ###
+Daniel Mann, Dave McKinstry, David Pitcher, Derrick Cawthon, Josh Garverick, Josh Sommer, Niel Zeeman, Richard Albrecht, Richard Fennell, Sergio Romero, Shashank Bansal, Shaun Mullis, Stawinski Fabio, Vladimir Gusarov, William Salazar
+
+### Notices ###
 Notices for certain third party software included in this solution are provided here: [Third Party Notice](ThirdPartyNotices.txt).
diff --git a/doc/Images/HOLScreenShot1.png b/doc/Images/HOLScreenShot1.png
diff --git a/doc/Images/HOLScreenShot2.png b/doc/Images/HOLScreenShot2.png
diff --git a/doc/Images/HOLScreenShot3.png b/doc/Images/HOLScreenShot3.png
diff --git a/doc/Images/HOLScreenShot4.png b/doc/Images/HOLScreenShot4.png
diff --git a/doc/Images/HOLScreenShot5.png b/doc/Images/HOLScreenShot5.png
diff --git a/doc/Images/HOLScreenShot6.png b/doc/Images/HOLScreenShot6.png
diff --git a/doc/Images/HOLScreenShot7.png b/doc/Images/HOLScreenShot7.png
diff --git a/doc/Lab-1-Using-the-RMWorkFlowMigrator-to-create-release-scripts.md b/doc/Lab-1-Using-the-RMWorkFlowMigrator-to-create-release-scripts.md
@@ -0,0 +1,179 @@
+[VISUAL STUDIO ALM RANGERS](http://aka.ms/vsaraboutus)
+> PREVIEW – This guide will be updated periodically.
+
+### Introduction ###
+This hand on lab (HOL) provides a walk-through of the using the **RMWorkFlowMigrator** tool to export a Release Management Agent based deployment pipeline so that it can be reused in the Release Management service in Visual Studio Team Services (VSTS).
+
+To provide a sample release pipeline to export, this HOL uses the Fabrikam Fiber sample that from the 2015 version of the ALM Virtual Machine ([http://aka.ms/ALMVMs](http://aka.ms/ALMVMs)). The **RMWorkFlowMigrator** supports TFS 2013 Update 4 and later; hence, the 2013 version of the ALM VM is not supported for this HOL as it is based on update 3.
+
+# Lab 1 - Using RMWorkFlowMigrator to create release scripts #
+
+## Preparation ##
+Download the 2015 version of the ALM Virtual Machine ([http://aka.ms/ALMVMs](http://aka.ms/ALMVMs)).
+
+> *TIP: You can download the VM using Powershell see the post* [Download Brian Keller's VM with PowerShell](https://binary-stuff.com/post/download-brian-kellers-vm-with-powershell)
+
+The migration tool makes a direct, read only SQL connection to the Release Management databases.  This HOL assumes that the ALM Virtual Machine is running and that the user has logged in as a user with administrative rights; the *vsalm\brian* account is recommended for this lab.
+
+## Step 1 - Install the migration tool on the VM 
+1. Download the binary release zip file from [the repository on GitHub](https://github.com/ALM-Rangers/Migrate-assets-from-RM-server-to-VSTS).
+1. Connect to the ALM Virtual Machine using RDP or the Hyper-V console.
+1. Login as the *vsalm\brian* account.
+1. Copy the ZIP file from the Hyper-V host to the desktop on the ALM VM.
+1. Unblock and unzip the zip file to a new folder \(e.g. **c:\migrate**\).
+1. Open a command prompt, create a directory to accept the results from the tools \(e.g., **MD \migratorOutput**\) and change directory to that folder \(e.g., **cd \migratorOutput**\).
+1. Execute the **RMWorkflowMigrator.exe** executable \(e.g., **c:\migrate\RMWorkFlowMigrator.exe**\). This will display the command line usage and parameters:
+
+		C:\migrate\RMWorkflowMigrator.exe 
+		
+		Microsoft.ALMRangers.RMWorkflowMigrator 1.0.5799.30900
+		Copyright ©2015  Microsoft Corporation
+		
+		ERROR(S):
+		  -n/--SqlServerName required option is missing.
+		  -d/--DatabaseName required option is missing.
+		  -t/--TemplateName required option is missing.
+		  -s/--TemplateStage required option is missing.
+		
+		
+		  -n, --SqlServerName                 Required. The name of the SqlServer
+		                                      server hosting the Release Management
+		                                      database.
+		
+		  -d, --DatabaseName                  Required. The name of the Release
+		                                      Management database.
+		
+		  --ConnectTimeout                    (Default: 15) The length of time (in
+		                                      seconds) to wait for a connection to the
+		                                      SQL server before terminating the attempt
+		                                      and generating an error. By default
+		                                      timeout is 15 seconds.
+		
+		  -l, --NetworkLibrary                The name of the network library used to
+		                                      establish a connection to the SQL Server.
+		                                      Supported values include dbnmpntw (Named
+		                                      Pipes), dbmsrpcn (Multiprotocol),
+		                                      dbmsadsn (AppleTalk), dbmsgnet (VIA),
+		                                      dbmslpcn (Shared Memory) and dbmsspxn
+		                                      (IPX/SPX), and dbmssocn (TCP/IP). The
+		                                      corresponding network DLL must be
+		                                      installed on the system to which you
+		                                      connect. If you do not specify a network
+		                                      and you use a local server (for example,
+		                                      "." or "(local)"), Shared Memory is used.
+
+		  -t, --TemplateName                  Required. Name of the template to export.
+		                                      If the name contains spaces use "the name"
+		
+		  -s, --TemplateStage                 Required. Stage of the template to
+		                                      export. If the name contains spaces use
+		                                      "the name"
+		
+		  -o, --OutputFolder                  (Default: Output) The folder to output
+		                                      the migration PowerShell scripts to. Can
+		                                      be relative or absolute. If this
+		                                      parameter is being enclosed in quotation
+		                                      marks, do not include a trailing
+		                                      backslash. Ex: "C:\Output", not
+		                                      "C:\Output\"
+		
+		  -c, --CreateParameterizedScripts    (Default: False) Create scripts with
+		                                      parameter blocks instead of separate
+		                                      initialization scripts
+		
+		  -v, --Verbose                       (Default: False) Prints the detailed
+		                                      messages to standard output.
+		
+		  --help                              Display this help screen.
+
+
+		Microsoft.ALMRangers.RMWorkflowMigrator Tool
+		============================================
+		OutputFolder:                   Output
+		ConnectionString:               Integrated Security=True;Connect Timeout=15
+		TemplateName:
+		TemplateStage:
+		CreateParameterizedScripts:     False
+		Verbose:                        False
+
+## Step 2 - Migrating a Stage of a Template ##
+To migrate a stage of a template the correct parameters need to be passed to the migration tool. The migration tool requires four parameters as a minimum:
+- The SQL server name \(i.e., "-n"\)
+- The DB Name \(i.e., "-d"\)
+- The Template Name \(i.e., "-t"\)
+- The Template Stage \(i.e., "-s").
+
+> **NOTE:** The SqlServerName parameter of **.** \(period\) is being used in this HOL as an alias for the VMs local SQL server. **localhost** or the actual server name could be used. 
+
+> **NOTE:** This is the simplest usage of the tool, generating a connection string that assume Windows integrated security. If you require a different connection script use the **NetworkLibrary** parameter.
+
+1. Enter the following command line:
+
+    	C:\migrate\RMWorkflowMigrator.exe -n . -d ReleaseManagement -t "Fabrikam Call Center" -s Dev
+2. This command will generate the PowerShell release scripts from the migration tool in the **.\output** folder.     
+3. Setting more parameters allows more control over the migration.
+	- As migrations can take a while depending on the complexity of the stage, it can be useful to see the progress of the migration by adding the -v verbose flag. 
+	- As we will want to export a number of stages, it is a good idea to export each stage to a different output folder using -o parameter  
+4. Repeat the export with the revised parameters:
+
+        c:\migrate\RMWorkflowMigrator.exe -n . -d ReleaseManagement -t "Fabrikam Call Center"  -s Dev -v -o Dev
+        Microsoft.ALMRangers.RMWorkflowMigrator 1.0.5795.40004
+        Copyright c2015  Microsoft Corporation
+        
+        Release Management version detected: 14.0.23102.0 (2015 RTM)
+        
+        Connecting to the DB 'ReleaseManagement' on the SQL server '.'
+        Generating the scripts for the workflow 'Fabrikam Call Center' stage 'Dev' into folder 'Dev'
+        
+        Parsing release template
+        Server: VSALM
+        Action: Remove Web Site
+        Action: Copy File or Folder
+        Component: Fabrikam Call Center
+        Action: Create Web Site
+        Action: Copy File or Folder
+        Action: Create Web Site
+        Rollback: Rollback
+        Done parsing release template
+        Generating PowerShell
+        ContainerStart: 1 - Server VSALM  IsContainer: True IsEnabled: True
+        ActionStart: 1 - Action Remove Web Site  IsContainer: False IsEnabled: True
+        ActionEnd: 1 - Action Remove Web Site  IsContainer: False IsEnabled: True
+        ActionStart: 2 - Action Copy File or Folder  IsContainer: False IsEnabled: True
+        ActionEnd: 2 - Action Copy File or Folder  IsContainer: False IsEnabled: True
+        ActionStart: 3 - Component Fabrikam Call Center  IsContainer: False IsEnabled: True
+        ActionEnd: 3 - Component Fabrikam Call Center  IsContainer: False IsEnabled: True
+        ActionStart: 4 - Action Create Web Site  IsContainer: False IsEnabled: True
+        ActionEnd: 4 - Action Create Web Site  IsContainer: False IsEnabled: True
+        ContainerStart: 5 - Rollback Rollback  IsContainer: True IsEnabled: True
+        ActionStart: 1 - Action Copy File or Folder  IsContainer: False IsEnabled: True
+        ActionEnd: 1 - Action Copy File or Folder  IsContainer: False IsEnabled: True
+        ActionStart: 2 - Action Create Web Site  IsContainer: False IsEnabled: True
+        ActionEnd: 2 - Action Create Web Site  IsContainer: False IsEnabled: True
+        ContainerEnd: 5 - Rollback Rollback  IsContainer: True IsEnabled: True
+        ContainerEnd: 1 - Server VSALM  IsContainer: True IsEnabled: True
+        Done generating PowerShell
+        
+        Release workflow generated	
+
+5. In the **Dev** folder you will find a sub-folder for each server in the stage. This will contain a number of scripts for the release process, rollback steps and initialization. There is also a **DeployerTools** folder that contains all scripts and tools referenced by the exported scripts:
+
+    ![Export Folder Screenshot](Images/HOLScreenShot1.png)
+
+6.  The export process needs to be repeated for the other two stages in the pipeline
+
+	    c:\migrate\RMWorkflowMigrator.exe -n . -d ReleaseManagement -t "Fabrikam Call Center"  -s QA -v -o QA
+	    c:\migrate\RMWorkflowMigrator.exe -n . -d ReleaseManagement -t "Fabrikam Call Center"  -s Prod -v -o Prod
+
+> **Note** This lab makes an assumption that you need to extract a work-flow for each stage because the stages differ from one another. If the stages **do not differ**, the only difference is in the parameter values used in the scripts.  This means you could just create different versions of the initial script with the correct parameter values for each stage.
+
+
+## Step 3 - Using the generated scripts 
+The scripts generated by the **RMWorkflowMigrator** can be used as part of a manual deployment process or by the Release Management service in VSTS.
+
+Instructions on how to make use of them in a deployment pipeline can be found in [Lab 2 - Using the resulting release scripts in a release pipeline](Lab-2-Using-the-resulting-release-scripts-in-a-release-pipeline.md).
+
+---
+- **Richard Fennell** is a Visual Studio ALM Ranger 
+- **Dave McKinstry** is Visual Studio ALM Ranger and Technical Specialist at Microsoft
+- **William H. Salazar** is a Visual Studio ALM Ranger and Sr. Consultant at InCycle Software