Updating the client

An existing installation of the primedocs Desktop Client can be updated in two ways: through central software deployment using the MSI package, or through the updater that the server provides on its download page. This page describes the updater.

The updater (primedocsInstaller.exe) is the same program used for a fresh installation. On start, it detects an existing installation and switches to update mode.

When to use the updater

Situation	Recommendation
No central software deployment, users may update themselves	Updater
Central software deployment (for example Intune, Configuration Manager, GPO)	Distribute the MSI package, see MSI parameters
Terminal Server or Citrix	Distribute the MSI package, see Terminal server installation

Do not combine with central software deployment

When the download is enabled on the server, clients can update themselves. Combined with central software deployment this leads to competing installations. Either enable the updater or deploy centrally.

On a Windows Server operating system, the client does not check for new versions. The update notice does not appear there, even when the download is configured.

Prerequisites

On the server

• The windowsClient section is configured in primedocs.config, including updaterLocation and the MSI paths. Without it, the download page provides no updater. See primedocs.config: Client download and update.
• An OIDC client for the Windows sign-in is registered (userAuthType="FromLogin" without redirectUri).
• The updater and the MSI package on the server come from the same version. If they differ, the updater stops with a corresponding message.

On the workstation

• The primedocs client is already installed. Without an existing installation, the updater asks for a setup code and performs a fresh installation.
• The primedocs server is reachable. The updater determines the package through the configured service address and downloads it from there. If the service address is configured with HTTPS, it downloads over HTTPS only, also after redirects (ten at most). A redirect to an HTTP address stops the download. HTTP is only allowed if the service address itself uses HTTP.
• Like the desktop client, the updater negotiates the TLS version with Windows. It does not pin TLS 1.1 or 1.2 and therefore also works against servers and reverse proxies that only offer TLS 1.3, provided Windows supports TLS 1.3.
• Microsoft Office 2013 or newer, consistently in the same bitness. If 32-bit and 64-bit products are mixed, the updater stops.
• An installation for all users (“per-machine”) requires administrator rights. The updater requests them through User Account Control. If the prompt is declined, a separate page explains why the rights are needed and offers Run as administrator for another attempt. A user-only installation needs no administrator rights, also for a fresh installation.
• The applications that use primedocs files can be closed. Otherwise Windows has to be restarted.

Procedure

1. Open the download page https://your-url.example.com/app/web/download and download the updater.

2. Start the updater. It compares the installed version with its own:

   Installed version	Behaviour
   No installation present	Fresh installation, setup code required
   Older than the updater	Update
   Identical	Message “primedocs is already installed”, start only
   Newer than the updater	Downgrade as a replacement installation
   Installed, but the program file is missing	Repair as a replacement installation, regardless of the version

3. Update (or Downgrade or Repair) starts the process. The updater downloads the MSI package and verifies it, see Package verification.

4. The updater shuts down a running primedocs itself. If other applications still have files from the primedocs installation folder loaded afterwards, for example Outlook or Word with the primedocs add-ins, it lists them. Office applications without loaded primedocs files do not block the update, provided the Windows Restart Manager is available. Close applications and continue closes them. Where Windows supports it (Restart Manager), Office keeps unsaved changes for recovery and the applications are reopened after the setup. Alternatively close the applications yourself, the setup then continues automatically. Only applications of your own Windows session are detected.

5. The updater then runs the installation and shows the current step and the progress in per cent. If files were still in use during the installation, it requires a Windows restart. Until then, the previous version stays active. It only asks for an Office restart if it did not close and reopen the Office applications itself.

No setup code is needed for an update. The service address, client ID and client secret, default datasource, cache and SSO settings, the ribbon configuration, custom folders for cache, settings and logs, the installation folder (except for an old OneOffixx installation) and the installed feature set are taken from the existing installation. The values come exclusively from the configuration of the detected installation. Leftovers of an earlier installation in the other context do not override them.

If the service address is missing from the existing configuration, or the primedocs.exe.config file is missing or not valid XML, the updater asks for a setup code. The code only replaces the connection data, all other settings are kept.

Installation context

The updater always updates an existing installation in the same context: a per-user installation stays a per-user installation, even if the updater runs with administrator rights, and a per-machine installation stays per-machine. The update page shows the detected context. Whether and in which context primedocs is installed is determined through Windows Installer. The updater only falls back to the registry if Windows Installer provides no information.

For a fresh installation, the rights the updater runs with decide: with administrator rights for all users, otherwise for the current user.

If primedocs is installed on the device both for the current user and for all users, the updater stops with a message. Remove one of the two installations under Apps in Windows Settings and start the updater again.

Downgrade, repair and the “fresh installation” option

For a downgrade, a repair and with the fresh installation option, the updater replaces the previous installation: it removes the previous version and then installs the new one. For a downgrade and a repair, the option is always set.

Both steps run in a single Windows Installer transaction. If the installation fails or is cancelled, Windows Installer restores the previous version. If the updater cannot start a transaction, it stops before removing anything. The user's settings, cache, signatures and distributed templates are kept during a replacement installation. Only a regular uninstall through Windows Settings removes this data.

Package verification

Before the updater installs the downloaded MSI package, it checks in this order:

1. The Authenticode signature of the package is valid.
2. The package is a primedocs package (same UpgradeCode).
3. The version of the package matches the version of the updater.
4. The package is signed with the same certificate as the updater.

If a check fails, the updater installs nothing. The certificate check cannot be switched off.

New version notice in the client

If minimumVersion or maximumVersion are set in primedocs.config, the Desktop Client checks its own version when connecting. If it falls outside the range, the client shows the configured notice with a link to the download page.

When the update fails

Message	Cause and action
“The installer does not match the version of the installation package.”	The local updater is older or newer than the package on the server. Use Open Download Page to obtain the current updater.
Notice that primedocs is installed twice	Remove either the installation for the current user or the one for all users under Apps in Windows Settings, then start the updater again.
Page about missing administrator rights	The installation applies to all users. Select Run as administrator and confirm the User Account Control prompt.
Error about the signature or certificate of the package	The package on the server does not come from the same delivery as the updater or has been modified. Place the updater and MSI packages of the same primedocs version on the server.
Error because an address does not use HTTPS	A download path or a redirect points to an HTTP address although the service address uses HTTPS. Switch absolute paths in windowsClient, for relative paths the address of the app in primedocs.config, and any redirects to HTTPS.
«Not all applications could be closed.»	Save your work and close the remaining applications manually. The setup then continues.
Notice about different Office bit versions	32-bit and 64-bit Office products are mixed on the device. Consolidate Office, then repeat the update.
Notice about an Office version that is too old	primedocs requires Office 2013 or newer.
Generic error during download or installation	Evaluate the logs, see Logs for failed updates.