Viz Pilot User Guide

Version 8.7 | Published September 25, 2023 ©

Unattended Installation

Easily install or upgrade your system. Unattended installations are typically used to save time for large-scale roll-outs. This section covers the following topics:

Configuration 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.

Local configuration is defined in two locations:

  1. Some configuration files are stored in the %PROGRAMDATA%\Vizrt\Viz Pilot x.y\Config folder.

  2. In addition, a number of Registry keys 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, a Configuration Bundle has been created (hereafter referred to as bundle). A bundle is a zip-file that contains a copy of all the configuration files and configuration values from the Registry, and some metadata (version information, etc.). The bundle can be read by the Changing Settings and applied to the current system.

Configuring Viz Pilot in Non-GUI Mode

The Changing Settings is primarily used to provide an interface (GUI) for user configuration of Viz Pilot Components. The tool opens automatically on regular installation, and can subsequently be opened manually. The Changing Settings also has a non-GUI mode of operation used to manage bundles.

Installing a bundle requires it to be run from a CMD shell with elevated privileges:

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

  2. Right-click the entry cmd.exe and 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.

  3. 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.

  4. You can then run PilotConfiguration.exe --help to see the help text for the program. The help text indicates which options require elevated privileges. An error message appears if you're running an option that requires elevation from a normal CMD shell.

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 wish to see the same verbose output, append --verbose to any command line used.

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

Creating a Configuration Bundle

You must first configure one workstation to the correct state. You may need to change configuration settings and test the changes a few times before the configuration is acceptable, before creating the bundle.

Creating the Bundle

  1. Run 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, an error message will appear and the Changing Settings will close. If that occurs, either delete the existing file or modify the filename before running the command again.

An ordinary zip file is created. You can unzip the file to see or alter the configuration. For example, if you do not want to distribute the keyboard settings, you can delete the file from the bundle.

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

Installing a Configuration Bundle

To apply the settings in an existing bundle to your current workstation, use the Changing Settings’s option installbundle as follows:

  1. PilotConfiguration.exe --installbundle=%USERPROFILE%\Desktop\config.zip. This overwrites any local configuration with the configuration from the bundle.

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

Note: Applying settings from a bundle removes local settings only - not those in the bundle. For example, if the local system contains a keyboard.cfg file, but the bundle does not, the local configuration file will be deleted. The same applies registry values under the keys mentioned above.

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. Although a full tutorial on how to use msiexec is not provided below, options specific to the Viz Pilot system’s installer are covered.

To run an unattended installation using default options, showing only a progress-bar, run the following command:

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

This runs the installer in Basic UI mode, where the overall progress bar is displayed and the Changing Settings is not displayed. The installer will be installed in the default folder. Of course, since installing with default settings is not always the desired behavior, hooks can be used to select the install location, set the list of components to be installed, and supply the installer with a configuration bundle to install.

This section contains the following topics:

Installation Location

The directory where the bulk of the software will be installed 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 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, the installation will be moved to the new folder, in the same way as is done when selecting a new folder when running the installer interactively.

Feature Selection

Installing all the features of the Viz Pilot system’s installer is not required when running unattended. Select which features are to be installed by listing the features by name. Since feature names are not easily extracted from the MSI, a list has been included below. In a similar manner to setting the install location, supply a comma-separated list of the required features in an 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 only.

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

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's also possible to specify a configuration bundle during an unattended install. This is also done through MSI properties, using 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. Depending on your specific setup, a drive named Z: might not 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

Customized Installations

All these options can 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 to perform 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. The exact names of the tools used may differ if you're using a different version of Windows Server.

This section contains the following topics:

Background

In a Windows domain, settings for different client computers are distributed in Group Policy Objects (GPOs). 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 can on the command line examples using msiexec.exe, so you 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 a transform during an installation. The tools used to create GPOs allow the specification of a transform to apply to a package, providing an opportunity to apply customizations.

Creating a Transform

One way to create a transform using a freely available tool, Orca, is shown below:

  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 only (nothing else is installed, including 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 you how to use the transform, a configuration bundle and Viz Pilot MSI installer to create a GPO. Since the example uses Windows Server 2012 R2, the exact steps might vary according to the specific version of Windows Server being used.

First, prepare a network share to host the MSI, transform and configuration bundle. This network share must be readable by the target client’s computer account, since there will be no interactive user logged in to lend their access credentials to the installer process when the install is being run unattended. Although this can be done by setting the share as read-only to Everyone, the details and best way of doing this will differ according to the network.

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, create a GPO representing the 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's important that you access the GPO 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 where Viz Pilot will be installed. 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 must 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, so that they do not need to be entered manually in the installer GUI. Specifying the values on the command line is primarily done during a silent/unattended installation, using the Windows Installer parameters quiet or passive. See Microsoft’s Windows Installer documentation for more options.

See also Pilot Data Server Installation.

Pilot Data Server with Graphic Hub Database

Use the following parameters to install Pilot Data Server with a Graphic Hub database:

  • 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

Use the following parameters to install Pilot Data Server with an Oracle database:

  • 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