Viz Pilot User Guide

Version 8.2 | Published July 23, 2018 ©

Unattended Installation

The Unattended installation type is an automated installation technology that allows you to install or upgrade a system with minimal user intervention. Unattended installations are typically used during large-scale roll-outs when it would be too time consuming and costly to have administrators or technicians interactively install the system on individual computers.

This section contains the following topics:

Relevant Files and Settings

The Viz Pilot system is configured through a combination of local configuration settings on each workstation running the client software, and the list of VCP parameters available in your Pilot Data Server web interface.

The local configuration is defined various places. First there are several configuration files stored in the %PROGRAMDATA%\Vizrt\Viz Pilot x.y\Config folder.

In addition, there are a number of Registry keys that also contain relevant information:

  • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\\[vizrt]\ActiveX x.y

  • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\\[vizrt]\viz|content pilot x.y

  • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\\[vizrt]\Preview Engine
    To apply a previously prepared configuration to a Viz Pilot installation, we have created a mechanism called a Configuration Bundle (referred to as just bundle after this point). A bundle is a zip-file that, in addition to some metadata (version information, and so on), contains a copy of all the configuration files and configuration values from the Registry. This bundle can then be read by the Viz Pilot Configuration Tool and applied to the current system.

Viz Pilot Configuration in non-GUI Mode

The Viz Pilot Configuration Tool’s primary usage is to present the user with a GUI to configure various aspects of the Viz Pilot Components. It is automatically opened during a regular installation, and can later be opened manually at any point.

The Viz Pilot Configuration Tool also has a non-GUI mode of operation, and this is what is used to manage bundles. When installing a bundle it requires elevated privileges, so it must be run from a CMD shell with elevated privileges. To do this:

  1. Press the Windows key, and then type cmd.

  2. Right-click the entry cmd.exe and from the menu that opens, select Run as administrator.
    You should now have a command prompt that is elevated. This can be verified by looking for the Administrator: prefix in the window title.

Tip: If you want to create a bundle, it can be run from a normal CMD shell without selecting the Run as administrator option.

Navigate to the installation folder where you installed Viz Pilot, and then to the sub-folder Configuration. If the default paths are used on a 64-bit system, this will be %ProgramFiles(x86)%\Vizrt\Viz Pilot x.y\Configuration. You can then run PilotConfiguration.exe --help to see the help text for the program. The help text will point out which options require elevated privileges.

If you are running an option that requires elevation from a normal CMD shell, an error message will be displayed.

All operations performed by the configuration program are logged in the file %ProgramData%\Vizrt\Logs\Viz Pilot x.y\configuration.log. By default, only important messages are shown on the console, but if you want to see the same verbose output you can append --verbose to any command line used.

Creating a Configuration Bundle

When creating a bundle, the first thing you need to do is to configure one workstation to the correct state. This probably means several cycles of changing configuration settings and testing the changes before the configuration is acceptable.

When this is done you create a configuration bundle by running PilotConfiguration.exe --createbundle=%USERPROFILE%\Desktop\config.zip. This will create a zip-file called config.zip on the current user’s Windows desktop. Note that if the file already exists, the Viz Pilot Configuration Tool will exit with an explanatory error message. In that case, either delete the existing file or modify the filename before running the command again.

The file created is a normal zip file. You can unzip it with normal tools if you want to see what configuration is included. If you for example do not want to distribute the keyboard settings, you can delete this file from the bundle.

Note: Be precise when editing bundles manually, and always test your changes thoroughly before rolling them out.

Installing a Configuration Bundle

If you have a bundle and want to apply the settings in it to your current workstation, you use the Viz Pilot Configuration Tool’s option installbundle like this: PilotConfiguration.exe --installbundle=%USERPROFILE%\Desktop\config.zip. This will overwrite any local configuration with the one from the bundle.

Tip: For detailed information about what has been changed, use the --verbose option.

Note: Applying settings from a bundle will remove settings that exist locally, but not in the bundle. For example, if the bundle does not have a keyboard.cfg file, but the local system does, the local configuration file will be deleted. The same applies to registry values under the keys mentioned earlier.

Unattended Installation from the Command Line

Since the Viz Pilot system is distributed as a Microsoft Installer package, the standard MSI tool has been used to facilitate an unattended installation. The command msiexec.exe can be used for this. This will not be a full tutorial on how to use msiexec, but the options specific to the Viz Pilot system’s installer will be covered.

To run an unattended installation with the default options and showing just a progress-bar UI, run the following command:

msiexec /qb /i VizPilot-x.y.z.z.msi

This will run the installer in the Basic UI mode (which means just showing the overall progress bar and not displaying the Viz Pilot Configuration Tool) and install it in the default folder. Of course, installing with the default settings is not always the desired behavior, so we provide hooks for selecting the install location, setting the list of components to be installed, and supplying the installer with a configuration bundle to install.

This section contains the following topics:

  • Installation Location

  • Feature Selection

  • Configuration Bundles

  • Icons on the Windows Desktop

  • Putting it all Together

Installation Location

The directory where the bulk of the software will be installed to is controlled through an MSI property called INSTALLDIR. By default, this is either %PROGRAMFILES%\Vizrt\Viz Pilot x.y if no earlier version of Viz Pilot has been installed, or alternatively the installation folder of the earlier Viz Pilot version. Some files will be installed outside of this folder, either in the Windows system folder or the %PROGRAMFILES%\Vizrt\Common folder. These files cannot be moved by changing the INSTALLDIR property.

To override the INSTALLDIR property using msiexec you append INSTALLDIR="C:\the\correct\folder" to the msiexec command line. For example:

msiexec /qb /i VizPilot-x.y.x.x.msi INSTALLDIR="D:\Software\Viz Pilot x.y"

If an earlier Viz Pilot version is already installed, this will move the installation to the new folder in the same way as selecting a new folder when running the installer interactively would do.

Feature Selection

It is not required to install all the features of the Viz Pilot system’s installer when running unattended. Selecting which features to be installed is based on listing up the names of the features. Since these are not easily extracted from the MSI, we supply a list of them below. Similar to how you set the install location, you supply a comma-separated list of the required features in a MSI property named ADDLOCAL on the command line:

msiexec /qb /i VizPilot-x.y.x.x.msi ADDLOCAL="Director,GPIDrivers"

This will install Viz Pilot’s Director component and the drivers for GPI integration, but nothing else.

Viz Pilot Components in Unattended Installations

Feature ID

What will be installed

Common

Common files for all the features.Note: This is always automatically installed and need not be specified.

Documentation

The PDF and HTML documentation

Director

Director control room client

TimecodeMonitor

Timecode Monitor

TrioPlugin

Viz Trio Data Resource Plugin

VizPilotNews

Viz Pilot News

TemplateWizard

Template Wizard

ObjectStore

Object Store

InifileEditor

Inifile Editor

OracleDrivers

Oracle Drivers

GPIDrivers

GPI Drivers for Director

LocalPreviewPlugin

Local Preview Plugin for Director and Viz Pilot News

SpellcheckPlugin

Spell check plugin

SpellcheckPluginDictionaries

Default dictionaries for the Spell check plugin

QuickCG

Quick CG

Configuration Bundles

It is also possible to specify a configuration bundle during an unattended install. Again, this is done through MSI properties, this time a property named CONFIGBUNDLE.

msiexec /qb /i VizPilot-x.y.x.x.msi CONFIGBUNDLE="%USERPROFILE%\Desktop\config.zip"

This will install Viz Pilot in the default location, with the default set of features, and the configuration from the config.zip bundle located on the current user’s desktop.

Note that when specifying remote paths in the CONFIGBUNDLE property, network drive mappings on Windows are on a per user basis, and a drive named Z: might not (depending on your specific setup) exist for the user running the installation. To avoid issues, specify remote resources with a UNC path (for example \dist-server\vcp\config.zip) and make sure the network share is readable by the machine account.

Icons on the Windows Desktop

To place icons on the current user’s desktop during installation, use the MSI property INSTALLDESKTOPSHORTCUTS. For example:

msiexec.exe /qb /i VizPilot-x.y.x.x.msi INSTALLDESKTOPSHORTCUTS=1

Putting it all Together

All these options can of course be specified together to customize the installation to your specifications. For example:

msiexec /qb /i VizPilot-x.y.x.x.msi CONFIGBUNDLE="%USERPROFILE%\Desktop\config.zip" ADDLOCAL="VizPilotNews" INSTALLDIR="D:\Software\Viz Pilot x.y"

Remote Unattended Installation using Active Directory

There are multiple ways of doing remote unattended installations of software packages in Windows networks. The distribution of software through Active Directory and Group Policy Objects has been chosen as an example. The techniques used here can be adjusted to match your specific setup.

We have used Windows Server 2012 R2 in this example, so the exact names of the tools used might be different if using another version of Windows Server.

This section contains the following topics:

  • Background

  • Creating a Transform

  • Creating a GPO with an Applied Transform for Distributing Viz Pilot

  • Troubleshooting

Background

In a Windows domain, settings for different client computers are distributed in Group Policy Objects. These are self-contained units of configuration. One of the things they can specify is the installation of packages in MSI format, which is what we will use.

One limitation here is that you cannot define arbitrary MSI properties like you could on the command line examples using msiexec.exe, so we need to use an alternative configuration method. MSI provides a mechanism called a transform. A transform is a collection of changes applied to an installation. By applying a transform to a base installation package, the installer can add or replace data in the installation database. The installer can only apply transforms during an installation. The tools used to create GPOs allow the specification of a transform to apply to a package, so this gives us an opportunity to apply our customizations.

Creating a Transform

We will show one way of creating a transform using a freely available tool, Orca.

  1. First, start Orca.

  2. In the File menu, click Open.

  3. Navigate to the Viz Pilot installer, and open it.

  4. Select Transform > New Transform.
    The title of the Orca window should now say (transformed by Untitled).

  5. Locate the Property table in the listing on the left-hand side, and select it.

  6. Right-click the property list and select Add Row.

  7. Enter a property name of INSTALLDIR.

  8. In the next window, enter the value of E:\Vizrt\Viz Pilot x.y.
    This sets the installation location.

  9. Right-click again and add a row with the name ADDLOCAL and value VizPilotNews,ObjectStore.
    This is a comma-separated list of feature IDs that will be installed. In this example we install Viz Pilot News and the Object Store client, but nothing else (including the bundled Oracle Instant Client libraries.)

  10. Repeat this procedure (if required) for the CONFIGBUNDLE property.

  11. When you are satisfied with the new values in the property table, select Transform > Generate Transform.
    Save the transform file to the preferred location.

Creating a GPO with an Applied Transform for Distributing Viz Pilot

We will now show how to use the transform, a configuration bundle and Viz Pilot MSI installer to create a GPO. We use Windows Server 2012 R2, so the exact steps might vary with different versions of the Windows Server.

First you need to prepare a network share that will host the MSI, transform and configuration bundle. This network share must be readable by the target client’s computer account, because when running the install unattended, no interactive user will be logged in and lending their access credentials to the installer process. One way of doing this is just to set the share as read-only to Everyone, but the details and best way of doing this will be different in various networks.

In this example, we will use the UNC path \server\software to represent this share. Put all three files on this share. The three paths are:

  • \server\software\VizPilot-x.y.x.x.msi

  • \server\software\transform.mst

  • \server\software\config.zip
    You might end up having multiple transform.mst and config.zip pairs to support different sets of configuration in your setup.

First, we need to create a GPO representing our software installation.

  1. Start the Group Policy Management tool.

  2. Place the GPO in the Group Policy Objects container.
    We are using the domain structure, so this container is preferred here, but there might be a better location for it in your domain.

  3. Right-click the Group Policy Objects container, and select New.

  4. Give it a descriptive name, for example Viz Pilot installation.

    Note: Make sure the Source Starter GPO is set to (none).

  5. Click OK.

  6. Right-click the GPO we just created in the Group Policy Objects container, and click Edit.

  7. In the Group Policy Management Editor window that opens, navigate to Computer Configuration > Policies > Software Settings.

  8. Right-click it and select New > Package.

  9. Using the file selector that appeared, navigate to the installer file.

    Note: It is important that you access it through the network share, even though it might also be visible through the local disk.

  10. In our case we navigate to and select \server\software\VizPilot-x.y.x.x.msi.

  11. In the box that appears, click Advanced.
    The properties windows for this package will now be shown.

  12. Go to the Modifications tab and click Add.

  13. Navigate to and select the transform file.

    Note: Again, make sure to use the network share.

  14. Click OK.

  15. Close the Group Policy Management Editor window.
    You now have a GPO that is configured to install Viz Pilot, but it needs to be assigned to a set of clients to take effect. In our case, all our relevant clients are in the Clients container on the top level of the domain, and we will link the GPO to this container.

  16. In the Group Policy Management window, right-click the container in the list on the left hand side, and then click Link an Existing GPO.

  17. Select the GPO you just created in the list, and click OK.
    The clients should now install the software on the next reboot.

Troubleshooting

Using this method of installing software has one major drawback; there is no reporting back to a central location about installation issues or configuration errors. For installation issues related to the MSI installer itself, you will need to enable general logging of all MSI installations. If the installer finishes, but something is wrong in the configuration, the Viz Pilot Configuration program logs to the file %PROGRAMDATA%\Vizrt\Logs\Viz Pilot x.y\configuration.log.

MSI Properties

  • INSTALLFOLDER: The location Viz Pilot will be installed to. Note that various support files are not affected by this, for example files that must be deployed to the Windows system folder or the files in %PROGRAMFILES%\vizrt\Common.

  • CONFIGBUNDLE: The path to a configuration bundle that should be applied to the system during installation.

  • ADDLOCAL: The list of feature-names to install.

  • INSTALLDESKTOPSHORTCUTS: If this is set to any value, the installer will place shortcuts to installed programs on the current user’s desktop.

Pilot Data Server Unattended Installation

Pilot Data Server configuration values can be provided on the command line when performing an installation, avoiding the need to enter these manually in the installer GUI. Specifying the values on the command line is primarily used during a silent/unattended installation, which can be done using the Windows Installer parameters, quiet or passive. Refer to Microsoft’s Windows Installer documentation for more options.

See also Pilot Data Server Installation.

Pilot Data Server with Graphic Hub Database

To install Pilot Data Server with a Graphic Hub database use the following parameters:

  • CONNECTION_METHOD="GH": Indicates that the Pilot database is running on a Graphic Hub

  • GH_HOST: Hostname of the Graphic Hub REST server

  • GH_PORT: Graphic Hub REST port

  • GH_USER_ID: Username for accessing the Graphic Hub REST server
    For example:

msiexec /i <path/to/msi> CONNECTION_METHOD="GH" GH_HOST="localhost" GH_PORT="19398" GH_USER_ID="Guest" /quiet

Pilot Data Server with Oracle Database

To install Pilot Data Server with an Oracle database use the following parameters:

  • CONNECTION_METHOD="Oracle": Indicates that the Pilot database is running on Oracle

  • ORACLE_USERNAME: Oracle database username

  • ORACLE_PASSWORD: Oracle database password

  • ORACLE_DATA_SOURCE: Oracle data source containing Oracle server host and the database (or instance) name
    For example:

msiexec /i <path/to/msi> CONNECTION_METHOD="Oracle" ORACLE_USERNAME="pilot700" ORACLE_PASSWORD="pilot700" ORACLE_DATA_SOURCE="bdvcpdb/vizrtdb" /quiet