Using Sample Scripts

Overview

There are 2 scripts located in the ~\bin\ApiHelp\samples folder of your installation (install.ps1, update.ps1). In case of an update or a new installation, extract the content of the setup exe file with a common packer program to any folder and use the scripts to perform the installation. The necessary settings for the installation or update must be provided by editing the config files in the same folder. 

Preparation of Settings File

To execute a setup by script, the same settings provided interactively in the setup wizard must be available during the script execution. The wizard has checks to evaluate the settings, the script will simply fail with an error.

The format of the config files is a simple XML format. Most of the settings are simple to understand, important points are:

• If no service account is set, the script will interactively ask for the account and the password.
• The installer directory is the root of the unpacked files, this is the folder that contains the bin, config, web, svc folders and other folders.
• The InstallationDirectory is the target directory, the wizard offers the folder C:\Program Files (x86)\Matrix42\Matrix42 Workplace Management by default.
• The Skip... settings offer to skip some steps during the installation.

You should never perform an update by first copying the installation files over the existing installation and then execute the update script, this will disturb the normal update process and can corrupt your database!

Running Scripts

The scripts are only samples and not signed. You have to allow running this kind of scripts by using the cmdlet Set-ExecutionPolicy to set the policies for running unsigned scripts.

After editing the settings file the installation is started by opening an administrative command shell and explicitly running the PowerShell command with the script name as a parameter.

powershell -File "fullpathtofile\Install.ps1" -Config "fullpathtofile\Profile.Install.config"

Or you can open an administrative PowerShell console, navigate to the folder ~\bin\ApiHelp\samples and run the script directly:

 .\install.ps1 .\profile.install.config

Differences to Setup Wizard

The setup wizard contains logic that validates the input parameters, tries to connect a SQL server before running SQL statements, or checks report server settings. The scripts don't contain these steps and will fail when a parameter is first used.

For updates the setup wizard contains a rollback logic that in case of errors tries to restore the previous state of the application (in case you didn't skip any backup steps). The update script doesn't contain this rollback mechanism, it contains backup steps but it is your responsibility to perform a manual rollback in case of errors.

The database backup cmdlet only backup the production and reference DB, the history and warehouse DB are not contained in the automatic backup.