Environment
Situation
This technical note describes how to migrate Verastream Host Integrator (VHI) from version 6.x to version 7.0 or higher in a Windows environment. The upgrade process migrates the existing configurations, host application models, and Web Builder projects.
Note: If you already have version 7.0 or 7.1 installed, see KB 7021581 instead.
Resolution
64-Bit vs. 32-Bit
Beginning with version 7.5, your Windows system must be 64-bit. If you still need support for 32-bit Windows, please install version 7.1 SP2 (7.1.2026) in your environment. For more information about supported platforms, see also KB 7021532.
Upgrading Your Server(s)
When upgrading from a prior version (6.0, 6.5, or 6.6) on Windows, you can migrate the existing configuration to the new installation. The process is as follows:
- Prior to upgrading, note whether you
have security enabled for Servers or Domains in your existing
installation. (Because these settings are not automatically migrated,
you will manually restore any non-default settings in step 14.c.)
- Open the Administrative WebStation interface: Click Start > Programs > Attachmate Verastream > Host Integrator > Administrative WebStation.
- If security is enabled, log in as a user in the Administrator profile; otherwise use blank credentials.
- Make a note of any non-default configuration for the following items.
| Location in Left Navigation Tree |
Default Value |
| Security > Domains |
Security is unchecked |
| Security > Servers |
Security is unchecked |
If you have trouble accessing Administrative WebStation, you can instead check whether your existing clients specify a user name and password in the connect method calls. If connections are successfully established without credentials, Server or Domain security is not enabled.
- If you are using SSL encryption for host connections and the host requires a client certificate, make a copy of your C:\Program Files\VHI\securehost\certificate.pem file. You will manually restore it in step 13 below.
- After downloading the version 7.x product from https://download.attachmate.com/upgrades, run the downloaded .exe file as an administrative user. You may be presented with a Security Warning dialog confirming the file is published by Attachmate.
- Select a folder to unpack installation files. Click the ellipsis button (“...”) to browse to a different folder location. If you unpack to the Desktop, a subfolder is recommended.
- After the unzip process is complete, setup.exe automatically starts. Accept the license agreement to proceed.
- When the existing installation is detected, you are prompted with the following dialog message:
Setup has detected an existing Verastream Host Integrator
installation. You can migrate settings files to your new installation.
Do you wish to migrate the settings?Click Yes. Files are copied to a separate temporary folder (%TMP%\vhi6xbackup), and this folder location is temporarily stored in the system registry (HKEY_LOCAL_MACHINE\Software\VHILegacyBackup\VHI6xInstallDir).
- After data has been successfully backed up, the following dialog message displays:
To complete the migration, please uninstall the existing copy of
Verastream Host Integrator. When you have uninstalled, you may run this
setup again, at which time you will be allowed to restore your saved
settings. Setup will now exit.Click OK to proceed.
- If you have been running a .NET web application or web service that uses the VHI connector, the appconncom.dll and xerces-c_1_4.dll files may remain loaded and locked by IIS. To unlock these files, terminate the aspnet_web process in Windows Task Manager, stop the IIS service, or restart the system.
- Uninstall the existing version: In Control Panel, click "Programs and Features," "Uninstall a program," or "Add or Remove Programs" (depending on your Windows version and view).
The uninstall process removes the old program files, but retains many data files for migration (such as deployed models and Web Builder projects).
Note: If you are upgrading multiple systems in your installation environment, it is strongly recommended that you repeat the above steps 1 through 9 on all systems before proceeding. For more information on setting up a version 7.x multi-server installation for load distribution and failover, see also Technical Notes 10108 and 10103.
- Run setup.exe again (in the folder location from step 4 above).
Important: Make a note of the administrative password you set during the installation process. Blank administrative credentials are no longer supported. (You will need to enter the administrative credentials later when running Administrative Console in step 14.b., or when installing an additional server for load distribution and failover.)
For additional information on installing Host Integrator, see the Installation Guide for your product version, available from https://support.microfocus.com/manuals/vhi.html.
- After Setup installs the new files and performs configuration, you are prompted whether to restore settings.
Setup has detected stored settings that were saved from a previous installation. Would you like to restore these settings?Click Yes.
- Setup temporarily stops the session server service to restore its configuration. The following data is migrated:
- Session server configuration (session pools, model variable lists, etc.)
- Deployed models
- Session server log data
- Authentication and authorization configuration (profile OS groups and LDAP settings)
- Load balancing domains
- Web Builder projects
If migration and conversion is successful, the following message displays:
The migration of the stored settings was completed successfully.Also, the VHI6xInstallDir value (from step 6) is removed from the registry, so future upgrades will migrate 7.x data (not re-migrate 6.x data).
If any steps of the migration process fail, see the migrateto7.log file in the folder specified by the value of your TMP environment variable.
- If you backed up a certificate.pem file in step 2, copy your certificate.pem file into the securehost subdirectory.
Note: Beginning in version 7.1, the securehost subfolder is automatically created by the installer. However, in version 7.0, you must manually create a subfolder named securehost within the folder specified by the VHI_ROOT system environment variable (typically C:\Program Files\Attachmate\Verastream\HostIntegrator).
- Verify successful migration and restore previous settings.
- Run Administrative Console from the installed shortcut (Attachmate Verastream > Host Integrator > Administrative Console).
- Connect to the management server and log in with user name "admin" and the administrative password set during installation (step 10 above).
- If Session Server Explorer is not currently displayed, click Perspective > Host Integrator > Session Servers.
- Restore any custom security settings that were noted in step 1 above: Under Servers, right click your server name and click Properties > General > Security.
Beginning in version 7.0, security is configured on a per-server basis only and also applies to connections using a load distribution domain.
Host Application Models
This section addresses the use of existing models that were created in previous versions (5.5 through 6.6).
Keep Unchanged vs. Convert
You can choose from two upgrade approaches for your models:
- You can leave the existing model(s) unchanged. Compatibility settings are automatically enabled (where applicable) to maintain the same behavior as in earlier versions.
In the server upgrade process, models deployed to the session server are automatically moved from the previous installation location (typically C:\Program Files\VHI\deploy) to C:\Program Files\Attachmate\Verastream\HostIntegrator\deploy. Also, the source models created with Design Tool are moved from the previous installation location (typically C:\Program Files\VHI\models) to <Documents>\Attachmate\Verastream\HostIntegrator\models for version 7.1.x (or C:\Program Files\Attachmate\Verastream\HostIntegrator\models for version 7.0).
-OR-
- You can manually convert models to the new version and re-deploy. Use this approach if you need to make changes to a model, or you want to take advantage of the latest product functionality (such as performance improvements).
- Open the model in Design Tool. You may see the following dialog:
Figure 1. Prior Version Model: 'This model was created with a prior version of Verastream Host Integrator....'- Verify the model continues to behave as you expect. For example, in certain cases it may be necessary to delete a pattern and re-add it. You should also verify that other aspects of the model, such as operations, recordsets, and procedures, behave correctly.
- Save the model. Note: Once you convert a model file to a newer version, it can no longer be loaded by an earlier version of Session Server or Design Tool.
- To take full advantage of the latest product functionality, disable compatibility settings in the model and re-test as appropriate. For more information on compatibility settings, see the "Compatibility Settings for Host Integrator Upgrades" topic in the VHI User Guide. For example, in VHI 7.6, see http://docs2.attachmate.com/verastream/vhi/7.6/en/topic/com.attachmate.vhi.help/html/reference/compatibility_switches.xhtml.
Java Event Handlers
If your pre-7.0 model uses Java event handler scripting code to customize session server behavior, you may need to make changes as follows:
- If building event handlers sporadically fails (unable to delete tmp\vhi_model.jar), edit your existing build.xml file as described in KB 7021565.
- To use the cleaneventhandlers.bat command, copy or edit your build.xml file as described in Technical Note 10109.
- If you created a project with an external IDE (such as IntelliJ or Eclipse), the scriptapi.jar file is no longer a valid referenced library. The file has moved from C:\Program Files\VHI\lib\java to C:\Program Files\Attachmate\Verastream\HostIntegrator\lib\container\services\ssscript\lib. To resolve this issue, you must update the reference in your Java IDE project.
Web Builder Projects
Generally, projects created in earlier versions can be deployed, undeployed, and deleted in version 7.x, but you may not be able to modify them. You should be aware of the following issues.
VHI Web Server Changed
After upgrading to version 7.5, any existing pre-7.5 Java projects must be re-built and re-deployed. See also KB 7021330.
Project Type Changes
Some project types that were in previous versions of Web Builder are no longer available for creating new projects:
- Beginning in version 7.5, Java web application and .NET web application project types are moved to the Legacy tab.
- Beginning in version 7.0, Web Builder no longer supports creating new web service projects, since web services are automatically provided by the session server. If you have an existing Java or .NET web service project in Web Builder, you can continue to re-build it after upgrading to version 7.x. For more information, see KB 7021550.
- If you have any user-defined project types created in previous versions of Web Builder, projects based on these types may not display in Web Builder version 7.x, or fail to build. For more information, see Technical Notes 10120 and 10138.
- Beginning in version 7.0, Web Builder can no longer create VB6 projects (Visual Basic ActiveX DLL or ASP Procedure-Based Web Application) or Enterprise Java Beans (EJBs).
- Beginning in version 6.5, for Web Builder .NET and Java web application projects, there are no longer separate "procedure-based" and "screen-based" (rejuvenation) project types. The web application project types incorporate the functionality of screen-based or procedure-based project types.
Web Builder continues to provide support for generating Java and .NET web applications, Java Beans, and .NET Class Libraries.
Project Files Moved
In the installer upgrade process, Web Builder projects are moved from the previous installation location (typically C:\Program Files\VHI\projects) to C:\Program Files\Attachmate\Verastream\HostIntegrator\projects. Beginning in version 7.1, when you first run Web Builder, projects are migrated to <Documents>\Attachmate\Verastream\HostIntegrator\projects.
Client Applications
It is recommended that you install the new connector API files on systems running client applications. While you may be able to continue using the old connector, an "Undefined error message" indicates that a connector upgrade is required. The error message may also include an error number that can provide further information. See the list of error numbers at http://docs2.attachmate.com/verastream/vhi/7.1sp2/en/topic/com.attachmate.vhi.help/html/reference/h_rte.html.
Note: If you have statically linked to any of the connector files in your applications, you must re-link to the connector files after upgrading in order to take advantage of new methods and features.
Beginning in version 6.5, the COM connector file name has changed from appconn.dll to appconncom.dll.
Beginning in version 6.6, the .NET Connector no longer supports .NET 1.1 client applications.
BizTalk and J2EE Changes
If you are currently using these technologies, you will need to make changes in conjunction with your Host Integrator 7.x upgrade:
- BizTalk: The Verastream Interface for Microsoft BizTalk Server is no longer supported or included with Verastream Host Integrator. To integrate host data into a BizTalk orchestration project, web services are the recommended approach.
- J2EE: Java EE Connector Architecture (JCA) Resource Adapter (RA), also known as the J2EE Connector, is no longer supported. To integrate host data into your application server (such as BEA/Oracle WebLogic, IBM WebSphere, or Sun GlassFish Enterprise Server), web services are the recommended standard. Also, the Java connector and JDBC are still supported.
For more information about using Host Integrator web services, see KB 7021550.
SNMP Changes
This section applies if you are using an SNMP network management station to monitor Verastream Host Integrator Session Server.
After upgrading to version 7.x, update your management station with the new Management Information Base (MIB) file installed at hostintegrator/lib/java/vhi.mib. The MIB uses the Attachmate organization ID (1371) instead of WRQ (820).