Upgrade Autoform DM

This guide describes how to upgrade Autoform DM (when it is in standalone mode).

Overview

Autoform DM product releases follow the Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH) system. An Autoform DM release is a major release, a minor release, or a patch release.

The type of software changes made in a new Autoform DM version determines that new software version’s category (as described below) and consequently its version number:

• Major release: Contains significant changes, including incompatible Application Programming Interface (API) changes.

• Minor release: Contains moderate changes, such as new functionality that has been added in a backward-compatible manner.

• Patch release: Contains minimal changes such as bug fixes (always added in a backward-compatible manner).

The first part of a release’s version number indicates the software’s major version, the second is the minor version, and the third is the patch version. For example, if the version number is 3.2.1, then 3 is the major version number, 2 is the minor version number, and 1 is the patch version number.

The release’s category (major, minor, or patch) determines which element of the version number is incremented to form the new release’s version number.

Summary of the Upgrade Process

The upgrade process depends on whether the currently installed Autoform DM version and the new version differ only in patch version number.

If only the patch version number differs (for example, you are upgrading from 10.4.1 to 10.4.2), you are doing a “patch upgrade”.

If the minor version differs (for example, 10.4.3 to 10.5), you are doing a “minor upgrade”; if the major version differs (for example, 9.2.2 to 10.5), you are doing a major upgrade.

Patch Upgrades

The upgrade risk is very low. The software is upgraded by replacing the application’s .ear file.

See Pre-Upgrade Checklist and Upgrade Process for Patch Upgrades.

Minor and Major Upgrades

To do a minor or major upgrade, you must use the Autoform DM installer. It will install the new software to a location that contains the major and minor elements of the version number:

C:\Program Files\Formpipe Software\Autoform DM\Server_<major version>.<minor version> - <node name>

See Pre-Upgrade Checklist and Upgrade Process for Major and Minor Upgrades.

Pre-Upgrade Checklist

Before you upgrade Autoform DM, do everything in the following list:

Warning

To ensure that the upgrade succeeds and the new software is performant, you must complete the following tasks.

• To determine the best upgrade path, refer to Notable Autoform DM Versions.

• To learn about any significant software changes, refer to the release notes for the new version, and the release notes for any versions released after the currently installed version but prior to the new version.

• To learn which versions of relevant other software (such as databases, operating systems, and other integrated products) are compatible with the new Autoform DM version, refer to the Compatibility Matrix.

  • Locally test any client applications to discover whether they need to be modified for compatibility with the new Autoform DM version.

• To ensure the current server specification is sufficient, refer to the System Requirements document for the new Autoform DM version.

Upgrade Process for Patch Upgrades

To do a patch upgrade, follow these steps:

1. Make a backup of the current Autoform DM installation’s pdm_app_module.ear file.

   Note

   If Autoform DM is currently installed in the default location, the file is in the following location:

   C:\Program Files\Formpipe Software\Autoform DM\Server_<major version>.<minor version) - <node name>\wildfly-x.x.x.Final\standalone\deployments

2. Download the new Autoform DM patch release and locate the pdm_app_module.ear file in the download package.

3. Copy that file, then overwrite the currently installed pdm_app_module.ear file.

The upgrade is complete.

Upgrade Process for Major and Minor Upgrades

The process for major and minor upgrades involves installing the new Autoform DM version alongside the existing Autoform DM version (while the existing software is stopped). You can then test the connection and functionality of the new software before uninstalling the old version.

Where “install” is mentioned, you can use the manual method described in Installation Steps or do a “silent” install.

Before You Begin

Complete the following tasks before you begin the upgrade:

• Copy the .exe or .jar installer file from the new Autoform DM version’s installation package to the Autoform DM server.

• The Autoform DM installer runs on Java. So, if a JRE or JDK (Java 1.8 or later) is not already installed on the Autoform DM server, you must install a JRE before you run the Autoform DM installer.

  Note

  For more information about this install-time Java requirement (and about the associated Java licensing implications), see Autoform DM and Java Licensing.

  For information about compatible JREs, see the Java Runtime Environment (JRE) – Server Installer section of Autoform DM Compatibility Matrix.

• If the installation will use the Autoform DM client software, copy the setup.war and client.war files from the Autoform DM version’s installation package.

  Note

  Ensure that you are using Autoform DM Client WAR files that are compatible with the Autoform DM version that you are upgrading to:

  • Autoform DM Client 9 WAR files are not compatible with Autoform DM 10.

  • Autoform DM Client 10.0.x and 10.1.0 WAR files are compatible with Autoform DM 9.1.x, 9.2.x, and 10.0.x only.

  • Autoform DM Client 10.1.1 WAR files are compatible with Autoform DM 10.1.x and later only. This assumes that the Auform DM Client is running on a modern Windows version that uses TLS 2.0 or later.

Upgrade Process Testing

Formpipe recommends performing the upgrade on a test system first, before upgrading a live production environment.

Summary of the Upgrade Process

To upgrade Autoform DM, follow this process:

1. Collect information about the current Autoform DM installation (or copy its .properties file, which records this information).

2. Stop the existing Autoform DM service.

3. Stop any software that is integrated with Autoform DM (such as BPM and Lasernet).

4. Perform a full backup of the current Autoform DM database and archive.

5. Perform the upgrade and start the new Autoform DM service. You can follow the manual upgrade steps or do a silent install.

6. Follow an approved test plan to verify the new install.

7. Start integrated products (such as BPM and Lasernet) and verify that they can connect to Autoform DM.

8. After the upgraded software install has passed testing and is running satisfactorily, you can uninstall the superseded Autoform DM version.

Collect Information About the Current Installation

Before you install the new version, record the following important information about the current installation. You will need some of this information during the upgrade process.

• Server Name / IP Address

• Ports (HTTP, HTTPS, management port, port offset)

• Autoform DM administrator username

• Autoform DM administrator password

• Installation directory

• Archive directory

• Database server name

• Database type (Microsoft SQL Server, Microsoft SQL Azure, or Oracle)

• Database port (if not default)

• Database name (AFPDM by default)

• Database username (pdm by default)

• Database password (pdm by default)

• Windows Service username (if any)

Tip

From Autoform DM 9.0.0, much of this information is recorded in the installation-record.properties file (generated by the Autoform DM installer that last ran on the server). You can use this file with the silent installation process to automate much of the installation.

The installation steps below describe the manual upgrade process.

Manual Installation Steps

Follow these steps to manually install the new Autoform DM version:

1. Run the Autoform DM Installer

1. To run the installer that you copied to the Autoform DM server, double-click the installer EXE file (for example: Autoform-DM_Installer-v10.4.1.exe). The installer will display its Welcome page.

2. Click Next.

2. Accept the End User Software Licence Agreement

1. Review the displayed End User Software Licence Agreement.

2. If you accept the terms of the agreement, click I accept the terms of this license agreement.

3. Click Next.

3. Select "Upgrade" Installation Type

1. Click Upgrade.

2. Click Next.

4. Enter a Node Name

Each distinct installation of Autoform DM on a particular computer (and so, each running instance of Autoform DM on that computer) is referred to as a node. Each of these instances is differentiated by its node name, which the installer automatically includes in that Autoform DM installation's service name and installation file path.

A node's name could indicate that Autoform DM instance's role (for example, Test or Production). Or, it could be used to indicate the Autoform DM software version number.

To specify the node name:

1. Enter an appropriate Node name.

2. Click Next.

5. Choose an Installation Location

1. Check whether the default installation path (which includes the node name) is appropriate.

2. If necessary, enter a different location (or click Browse to select a location).

3. Click Next.

Note

This should be a directory that is separate from any existing Autoform DM installs, because the new Autoform DM version will be installed alongside the currently installed version. That version of the software can be uninstalled after the upgraded Autoform DM system has been tested.

6. Choose Which Components to Install

1. Select the checkboxes beside the Autoform DM components that you want to install.

2. Click Next.

Note

Application Server (Wildfly) and Autoform DM Server are mandatory components. They are automatically selected and are grayed (so that their checkboxes cannot be cleared).

Service: This component is a Windows Service that represents this installation of Autoform DM.

Autoform DM Client: This component is the optional Autoform DM client application. This component requires additional files (client.war and setup.war) to be present in the same directory as the Autoform DM installer (so that they are available for the installer to copy to the required location). If you select the Autoform DM Client component but these two files are not present alongside the Autoform DM installer, an error will occur if you click Next.

Alternatively, you can manually install the Autoform DM client after the Autoform DM installation is complete. To do this, clear the Autoform DM Client checkbox, complete the Autoform DM installation, and then manually copy the files listed below to the location listed below.

Appropriately substitute <installation directory> and <version>.

7. Configure Wildfly (Application Server)

The next few pages of the installation wizard collect configuration settings for the application server (Wildfly).

Application Server Configuration Page

Username, Password, and Retype Password: Set the access credentials for the application server management console.

Note

These credentials are used to access the Wildfly management console, not the Autoform DM web application.

Local HTTP management port: If necessary to avoid a port clash, change the default value. If multiple installations of Autoform DM will run simultaneously on the server, each installation must have a unique Local HTTP management port value.

HTTPS is configured by default. Click Setup HTTPS with a custom certificate (recommended) if you are able to provide a keystore containing the certificate that you want to use. Else, if you click Setup HTTPS with a generated certificate, the installer will generate a self-signed certificate, which you can change for a custom certificate at a later date.

Enable proxy forwarding header support: By default, this checkbox is cleared. If appropriate, select this option; the information above the checkbox describes when this option is relevant.

To complete this stage:

1. Specify appropriate application server configuration settings on this page.

2. Click Next.

Application Port Configuration Page

HTTP Port and HTTPS Port: The default HTTP Port is 80 (standard HTTP port), and the default HTTPS Port is 443 (standard HTTPS port). Change these port numbers if there is a risk of a port number clash with other services or web servers that are installed on the same server.

Port offset and Custom: The ports that an Autoform DM instance uses must be for the sole use of that Autoform DM instance. If multiple Autoform DM instances are installed and running on a server, and those instances all have the same HTTP Port and HTTPS Port numbers, a port clash will occur unless each instance has a different Port offset.

The Port offset resolves this problem by adding the specified number to the port numbers that are used by the Autoform DM instance that you are installing. For example, if HTTPS Port is set to 443 and you select 50 from the Port offset list, the instance will use port 493 for HTTPS communication. You can select a value from the Port offset list, or select Custom from the list and enter a number into the Custom offset box.

Note

Port offset does not affect Local http management port.

To complete this stage:

1. Specify appropriate port configuration settings on this page.

2. Click Next.

HTTPS Certificate Configuration Page

If you selected Setup HTTPS with a custom certificate (on the Application Server configuration page), you must provide a keystore containing the HTTPS certificate you want Autoform DM to use and supply the accompanying credentials.

HTTPS certificate keystore to install: Select the Java KeyStore (JKS) or Personal Information Exchange (PFX) file containing the SSL certificate you want to install. The installer will copy this keystore to a location within the Autoform DM installation directory.

Use Key alias, Keystore Password, and Retype Keystore Password to provide the access credentials for that keystore.

To complete this stage:

1. Select the key file.

2. Provide the required credentials.

3. Click Next.

Warning

After you click Next, the installer will validate the supplied access credentials against the selected keystore. If the credentials are not valid, you will be unable to proceed with this installation.

HTTPS Generated Certificate Configuration Page

If you selected Setup HTTPS with a generated certificate (on the Application Server configuration page), you must enter Hostname, Organisation, and Organisational Unit values that enable the installer to generate a self-signed certificate.

You can use the default values or change them.

The generated certificate will have the following credentials programmed into it:

• alias: dm_cert

• password: dmcert

To complete this stage:

1. If necessary, change the Hostname, Organisation, and Organisational Unit. Otherwise, if the default values are acceptable, leave them as they are.

2. Click Next.

Note

The automatically generated certificate is intended to speed up the installation and deployment process while establishing a base level of security. To provide a more secure environment, Formpipe recommends that you replace the generated (temporary) certificate with a custom certificate as soon as possible.

8. Configure the Database Connection

The information that you enter on this page enables Autoform DM to connect to the database that the currently installed version of Autoform DM uses.

Note

When the new version of Autoform DM starts (after the upgrade is complete), it will upgrade this database.

Select target database: Select the type of database that Autoform DM will connect to.

Warning

Do not use the H2 database type for production systems. It is intended only for temporary test installations.

Hostname: Enter the host name of the computer that is hosting the database.

Database name, Username, Password, and Retype Password: Enter values that match those used by the database that the currently installed version of Autoform DM uses.

Unless directed otherwise, use the default Min connection pool size and Max connection pool size.

To complete this stage:

1. Specify appropriate database configuration settings on this page.

2. Click Next.

9. Configure the Windows Service

If you selected Service (on the Select Installation Packages page), you must configure the Windows service that the installer will create. This service represents the new Autoform DM installation.

Service Startup Mode: If you click Automatic, the Autoform DM service starts automatically when the computer starts. If you click Manual, a user of that computer must manually start the Windows service.

Start the service after installation: By default, this option is selected.

Next, specify the identity that the service will run under:

• To use the Windows LocalSystem account: Leave Username, Password, and Retype Password blank.

  Note

  The LocalSystem account cannot access archive file locations on other computers.

• To use an existing user account: Enter that user account's username and password. For Username, use a <domain>\<user> format; appropriately substitute <domain> and <user>. If the user is on the local domain, substitute <domain> for . (period). Ensure that the specified account has Log on as a service privileges, and will be able to access the archive file location.

To complete this stage:

1. Specify appropriate Windows service configuration settings on this page.

2. Click Next.

10. Review the Pre-Installation Summary

The Summary Configuration Data page summarizes the settings and configuration values that the installer will use to install and configure Autoform DM and the application server (Wildfly).

The HTTP Port and HTTPS Port that the new installation will use are calculated from the port number and offset entered earlier and are displayed here. If they differ from the default values, make a note of them.

Note

Autoform DM stores the location of the archive directory in its database. On the installer’s Database configuration page, you specified which database the currently installed Autoform DM system uses. As a result, the new version of Autoform DM will use the same database. When the new software version starts, it will connect to the database and read the archive directory location.

As a result, the new version of Autoform DM will use the same archive directory as the currently installed version.

To start installing the software, click Next.

11. Install the Software and Monitor Installation Progress

The Autoform DM installer will install and configure the software. Progress bars on the Installation page indicate how much of the process remains to be completed.

After the installer successfully installs the software, it will display an Installation Finished page.

Click Done to close the installation wizard.

12. Log In to the New Autoform DM Installation

After the software is installed, the corresponding Windows service will start. Open a web browser and log in to the new installation. Autoform DM will indicate that it is upgrading the database, and then you will be able to use the Autoform DM web application.