Migrating to the Current Version of TestStand

The following sections describe the recommended migration procedure for each previous TestStand version.

Migrating From TestStand 4.0.1 or earlier

TestStand 4.1 includes significant changes to the directory structure to add support for Microsoft Windows Vista and later operating systems.  Use the table below to migrate any customized components to the current TestStand directory structure.

¹Refer to the Configuration Files topic in the TestStand help for more information on the contents of each configuration file.  You only need to migrate files containing settings you have customized.
²In TestStand 3.5, the default location for types files was moved to <TestStand>\Components\User\TypePalletes.  In TestStand 3.5 or later, your types will be migrated when you migrate the Components\User directory.  If yo have any other custom type pallette files in this location, you must migrate these as well.
³Includes Frontend and Station Callbacks, Icons, Language resource files, Process Models, Step and Data Types, Tools, Sequence File Translators.  Note: if you need to migrate customizations to the process models, you must follow the procedure outlined in the Manually Migrating process Model Changes section to migrate your model customizations to the new TestStand version. 

In addition to migrating the items in the table, you must complete the following tasks to account for the new directory locations when you migrate to the current version of TestStand:

• Update projects and files that reference files and directories that have been moved. You can use the Engine.GetTestStandPath method to obtain file and directory paths programmatically.
  
  Note: If you use relative paths to reference files in the <TestStand> directory, the paths might break.
  
  Some ADEs might return warnings when you update projects and files and then attempt to open a project, known warnings include:

• ADE	Warning Description	Resolution
  LabWindows/CVI	"some files were not found" warning when you open a project	Remove the files from the project and re-add them from the <National Instruments>\Shared\CVI\instr\TestStand\API directory in LabWindows/CVI 8.5 or later and from the <CVI>\instr\TestStand\API directory in LabWindows/CVI 8.1.1 or earlier.
  Visual Studio	"some TestStand API or adapter support files were not found" warning when you open a project	Add the $(TestStand), $(TestStandAppData), and $(TestStandPublic) environment variables as needed to the Additional Include Directories control for the project.

  
  
• Use the TestStand Deployment Utility to update deployable images or installers for deployable images to redirect file destinations to the TestStand 4.1 or later destinations.  Select View Destination in the Distributed Files tab and select the new location in the Installation Destination control in the Installer Properties section of the Distributed Files tab.

If you made changes to the default process models, follow the procedure outlined in the  Manually Migrating process Model Changes section to migrate your model customizations.

If you made changes to the report and/or database options, follow the procedure outlined in the Manually Migrating Result Processing Settings section to migrate these options.

If you are migrating from TestStand 2.0.1 or earlier, and you are planning to uninstall the previous TestStand version, you must complete the following steps to safely uninstall it and preserve all configuration files and files located in the User subdirectories.  Otherwise, the uninstaller for TestStand 2.0.1 or earlier remove the <TestStand>\OperatorInterfaces\User directory and its contents.

1. Move the <TestStand>\OperatorInterfaces\User directory to a location outside
   the <TestStand> directory.
2. Navigate to the standard Windows Control Panel facility for adding and removing
   programs and run the TestStand uninstaller. If the uninstaller launches a dialog box that
   requests confirmation to remove all TestStand configuration files and pre-installed user
   components, click No.
3. When the uninstaller completes, move the <TestStand>\OperatorInterfaces\User directory back
   into the original <TestStand> directory.

You can now install the new TestStand version  into this directory.

Migrating From TestStand 4.1 to 4.2.1

Refer to the Manually Migrating User Components and Settings section for general migration information.

If you made customizations to the process models, follow the procedure outlined in the Manually Migrating process Model Changes section to migrate your model customizations.

If you made changes to the report and/or database options, follow the procedure outlined in the Manually Migrating Result Processing Settings section to migrate these options..

Migrating From TestStand 2010 or 2010 SP1

TestStand 2010 and later includes a migration utility to facilitate the migration process. NI recommends using this utility to migrate your customized components and settings. To use the Migration Utility, follow the procedure outlined in the Migrating User Components and Settings Using the Migration Utility section. 

If you made customizations to the process models, you must manually migrate these customizations due to TestStand 2012 model architecture changes.  Follow the procedure outlined in the Manually Migrating process Model Changes section to migrate your model customizations.

Note: If you prefer to migrate user components and settings manually, refer to the Manually Migrating Process Model Changes section. If you choose to manually migrate customizations to the report or database options, you must also follow the procedure outlined in the Manually Migrating Result Processing Settings section to migrate your result processing settings, respectively.

Migrating From TestStand 2012 or Later

TestStand 2010 and later includes a migration utility to facilitate the migration process. NI recommends using this utility to migrate your customized components and settings. To use the Migration Utility, follow the procedure outlined in the Migrating User Components and Settings Using the Migration Utility section. 

Because TestStand 2012 and later use the newer TestStand process model architecture, the full migration process can be completed using the migration utility.

Note: If you prefer to migrate user components and settings manually, refer to the Manually Migrating User Components and Settings section.  In addition to the files in this section, you must also migrate the result processing configuration file, located at <TestStand Public>\Cfg\ModelPlugins\ResultProcessing.cfg 

The information below is non version-specific migration information.  For information on how to migrate from a specific version, refer to the Version Specific Migration Procedures section of this document.

Migrating User Components and Settings Using the Migration Utility

TestStand 2010 and later includes a migration utility to facilitate the migration process.  Complete the following steps to use the TestStand Migration Utility to copy settings, configuration, and public component files from the directories of TestStand 2010 or later to the current version of TestStand. 

1. Launch the TestStand Migration Utility.
   • Windows 8 - Click the NI Launcher tile on the Start screen and select TestStand»Tools»Compatibility»TestStand Migration Utility.
   • Windows 7 or earlier - Select Start»All Programs»National Instruments»TestStand»Tools»Compatibility»TestStand Migration Utility.
     
     Note: If you have more than one version of TestStand installed on the computer, the utility launches a dialog box in which you can specify the previous version of TestStand from which you want to migrate.
     
     When you migrate from TestStand 2010 SP1 or TestStand 2010 to the current version of TestStand, the utility migrates the report and database options to the format for result processing configuration options for the current version of TestStand. Refer to the Migrating Result Processing Settings Using the Migration Utility section for more information.
2. Select the previous version of TestStand. The utility checks the computer for all the files you can migrate to determine whether the files have changed since installation. The utility launches a status indicator dialog box during this process. When the utility finishes checking the files for changes, the utility main window launches.
3. Use the Files to Copy control to select the files you want to copy. By default, the utility selects files you added or modified in the previous version of TestStand.
4. Expand the directories in the Files to Copy control to view the files you can migrate and whether those files have changed since installation. The Conflicts column includes any conflicts that could affect the migration of the files you specify.
   
   Note: The utility overwrites any file you create or modify in the current version of TestStand if the file also exists in the corresponding directory of the previous version of TestStand and if you select the file in the Files to Copy control. Although the utility creates a backup copy of all overwritten files, verify that the utility will not overwrite any files you intend to keep in the version of TestStand to which you are migrating.  Refer to the Integrating your Customizations with Newer TestStand Components section for information on merging customized files with newer versions
   
5. Click Migrate Files to begin the migration. When the migration completes successfully, the utility generates a text file report that contains the results of the migration, including where the utility stored the file backups and which files were moved.
   
   Note: Consider the following behavior when using the TestStand Migration Utility:
   
   • The utility only moves files and does not update any other information or settings, such as registry keys.
     
   • If the <TestStand Public>\Components directory of the previous version of TestStand includes files installed by an installer other than the TestStand installer, you might need to use that specific installer to move the files for the files to function and uninstall properly from the <TestStand Public>\Components directory of the new TestStand version. NI recommends that you use an installer that targets the new TestStand version to install any such components instead of using the utility to copy the components. However, some installed components can function properly when copied to another directory and are safe to migrate with the utility.

Migrating Result Processing Settings Using the Migration Utility

The TestStand 2012 or later process models include significant changes to implement a plug-in architecture for model sequence files. TestStand 2012 or later uses the plug-in mechanism to decouple result processing from the process models. As part of this change, the result processing options move from the TestStandModelReportOptions.ini and TestStandDatabaseOptions.ini files into a single ResultProcessing.cfg file, located in the <TestStand Application Data>\Cfg directory, that stores configuration information for all result processing model plug-ins.

While the result processing options files from TestStand 2010 SP1 or earlier are not directly compatible with TestStand 2012 or later process models, the Migration Utility can convert the configuration files to the new format.  The following actions are available in the TestStand Migration Utility to migrate the result processing configuration options from TestStand 2010 SP1 or earlier to the current version of TestStand.

• Apply to new models - Creates a new configuration in a configuration set named Migrated from TestStand Version. The utility automatically selects a unique name for the configuration if the utility has already used the default name in a previously completed migration. Refer to the migration report for the specific configuration names the utility uses.
• Apply to legacy models - Copies the options files from TestStand 2010 SP1 or earlier to the current TestStand directory so you can use the previous configurations with the equivalent legacy TestStand 2010 process models in the current version of TestStand. When you migrate database options, the utility renames TestStandDatabaseOptions.ini to TestStandDatabaseSchemas.ini.
  
  Note: Refer to the Using the Legacy Model Switcher Tool section of the TestStand 2012 New Features topic in the NI TestStand Help for more information about using the Legacy Model Switcher tool to use the equivalent legacy TestStand 2010 process models.
• Apply to new and legacy models - Adds a new configuration in the Migrated from TestStand Version configuration set and copies the options files from a previous version of TestStand.

Note: The utility does not support migrating the configuration files from TestStand 2010 SP1 or earlier if you modified the ReportOptions or DatabaseOptions data types defined in the default process models.

Manually Migrating User Components and Settings

Because TestStand 4.1 and later versions use the same directory structure to store user components, migrating user components is a straightforward process when migrating from TestStand 4.1 and later.  Use the table below to migrate custom settings and components to the new TestStand version

Note: If you made changes to the default version of a component (for example modifying the sequential process model file in the <TestStand>\Components\Models directory), you must migrate these files as well.  NI recommends that you keep all custom files in the <TestStand Public> location.

¹ Refer to the Configuration Files topic in the TestStand help for more information on the contents of each configuration file.  You only need to migrate files containing settings you have customized.
² Includes Callbacks (FrontEnd and Station), Icons, Language resource files, Process Models, Step and Data Types, Tools, Sequence File Translators.  
Note: If you need to migrate customizations to the process models from TestStand 2010 SP1 or previous, you must use the procedure in the Manually Migrating process Model Changes section.

Importing Custom Tools Menu Items to TestStand

If you used custom Tools menu items in a previous version of TestStand, complete the following steps to import the items into a new TestStand Version.

1. Select Tools»Customize in the previous version of the TestStand Sequence Editor to launch the Customize Tools Menu dialog box.
2. Click Export Items to File to launch the Export Tools Menu dialog box.
3. Select the Tools menu items to export to a Tools menu file and click OK.
4. Create a Setup\ToolMenusToInstall directory in the <TestStand Public> directory of the new TestStand version.
5. Place the Tools menu file you created in step 3 in the new directory.

TestStand will add the new menu items to the Tools menu and delete the Tools menu file upon launch.

Manually Migrating Process Model Changes

The TestStand 2012 process models include significant changes to implement a plug-in architecture for model sequence files.  For this reason, you must manually migrate process model files when migrating from TestStand 2010 SP1 or earlier. There are two available options for migrating to the new TestStand version

• Merge your customizations with the newer process models.  To accomplish this, refer to the Migrating Model Customizations to TestStand 2012 or Later document.
• Use your customized process model instead of the current process models.  Note that you cannot use any of the new model files if you choose this approach.  Follow the steps below to migrate your model files to the new TestStand version
  1. In the new TestStand version, back up all files in the <TestStand>\Components\Models directory
  2. Move the contents of the <TestStand>\Components\Models directory from the previous TestStand version to the <TestStand>\Components\Models directory of the new TestStand version
  3. Move the contents of the <TestStand>\Components\User\Models directory from the previous TestStand version to the <TestStand Public>\Components\Models directory of the new TestStand version
     
  Note: If you take this approach, you will not have access to any new model features, such as the plug-in architecture and offline results processing.

Manually Migrating Result Processing Settings

The TestStand 2012 or later process models include significant changes to implement a plug-in architecture for model sequence files. TestStand 2012 or later uses the plug-in mechanism to decouple result processing from the process models. As part of this change, the result processing options move from the TestStandModelReportOptions.ini and TestStandDatabaseOptions.ini files into a single ResultProcessing.cfg file, located in the <TestStand Application Data>\Cfg directory, that stores configuration information for all result processing model plug-ins.

Complete the following steps to migrate result processing options from TestStand 2010 SP1 or previous for use with the current TestStand process models.

 Note: Consider the following caveats when migrating result processing options:

• This procedure is not supported for migrating TestStand 4.0 or earlier default database schemas. If you want to use TestStand 4.0 or earlier database schemas with TestStand 2012 or later, click Reload NI Schemas on the Schemas tab of the Database Options dialog box to launch the Reload NI Schemas dialog box, and click the 2.x to 4.0 button to reload the database schemas from TestStand 4.0 or earlier.
• To migrate result processing options to the equivalent legacy TestStand 2010 process models, complete only step 1. However, NI does not recommend using the equivalent legacy TestStand 2010 process models unless you encounter an incompatibility in an existing test system when you use the current TestStand process models or unless other circumstances prevent you from using the current TestStand process models.

1. Copy the TestStandModelReportOptions.ini and TestStandDatabaseOptions.ini files from the Cfg directory of your TestStand version to the <TestStand Application Data>\Cfg directory of the current version of TestStand.
2. Rename TestStandDatabaseOptions.ini to TestStandDatabaseSchemas.ini.
3. Open a command prompt, and type the following command to launch the version switcher tool with the migration settings
   
   "<TestStand>\Components\Models\TestStandModels\TestStand 2010 Process Models (Legacy)\LegacyModelSwitcher.exe" /migration
   
   where <TestStand> is the TestStand directory for the new TestStand version.
   
   Note:  The /migration command-line argument disables the type version checking the Legacy Model Switcher ordinarily performs and automatically merges the types in the report and database options in the equivalent TestStand 2010 process models with the types in the TestStand 2012 or later process models.
   
4. In the Legacy Model Switcher Utility window, Confirm that you have enabled the options to migrate report and database options from the legacy models. Refer to the Using the Legacy Model Switcher Tool section of the TestStand 2012 New Features topic in the NI TestStand Help for more information about using the Legacy Model Switcher tool. 
5. Launch the TestStand Sequence Editor.
6. Select Configure»Result Processing to launch the Result Processing dialog box.
7. Enable the Show More Options option.
8. Verify that the Active Configuration ring control specifies Options from Legacy Models.

Integrating Your Customizations with Newer TestStand Components

TestStand includes several components you can customize, such as process models, user interfaces, and certain step types. When upgrading to a newer version of TestStand, it is important to consider the alternatives for integrating your customizations to a component with the improvements implemented by NI.  This section provides information on considerations for integrating customized TestStand components.

You must first determine the changes between the current TestStand version of the the component and the original version of the component you modified.  Consider that subsets of different versions of the same component are not necessarily interoperable without modifications. For example, you cannot replace a single sequence in the current TestStand default process models with the corresponding sequence from older process models without making further modifications. If you customized the process models, you must ensure that TestStand can find all the subordinate components the process models use and that any of those components that are ActiveX servers are registered. Additionally, the default process model sequence for TestStand uses separate sequences, DLLs, and ActiveX servers to support database logging and report generation features.

Based on the complexity of customizations you have made, choose one of the following approaches for integrating the files:

• Changes you made to the component are less complex than changes implemented in TestStand 2012 — apply your customizations to a copy of the newer version of the component.
• Changes you made to the component are more complex than changes implemented in TestStand 2012 — apply the changes to the newer version of the component to the custom version of the component. Ensure that the component is interoperable with other components that depend on it.

You can use the following types of file comparison tools: