Install Autoform DM (Interactive Installation)

This guide describes how to use the interactive Autoform DM installation wizard to install Autoform DM (in standalone mode) on a supported Windows operating system.

Note

For information about how to upgrade an existing Autoform DM system, see the Autoform DM Upgrade Guide.

How to Follow This Installation Guide

Follow the subsequent sections of this guide in sequence. In summary, the process is:

1. Complete prerequisite and preparatory steps. This includes making decisions (for example, which network port numbers Autoform DM will use), acquiring and installing prerequisite software (such as the Java runtime environment (JRE) that the installer will use), and preparing a database for Autoform DM to use.

2. Install Autoform DM. This involves making selections and entering values on each stage of the Autoform DM installation wizard, so that it can install Autoform DM according to your requirements, and appropriately configure the application server (Wildfly) that Autoform DM runs on.

3. Apply a license to Autoform DM.

4. Complete post-installation tasks. This includes ensuring that relevant network ports are open, and running basic functionality tests in the Autoform DM web application.

This guide also contains an Elements of an Autoform DM Installation section. Understanding what elements comprise a basic Autoform DM installation can help you to understand why the prerequisite steps of the installation process are needed, and understand what the Autoform DM installer does. This understanding can also help you to administrate your Autoform DM system after you have successfully installed and started it.

Elements of an Autoform DM Installation

The Autoform DM installer installs the following basic elements of an Autoform DM system:

• A JDK

• Wildfly (application server)

• Autoform DM software and files (as an EAR file installed in Wildfly's \standalone\deployment\ directory)

• A Windows service to provide easy start/stop/restart control over Autoform DM

An Autoform DM installation also relies on the following elements that must be present before you run the Autoform DM installer:

• A database.

  Note

  The installer does not create this database. Instead, you must create it as a prerequisite task of the installation process.

• A JRE for the installer to use.

  Note

  The installer is a Java application, so you must install a JRE for the installer to run on. Installing this JRE is a prerequisite task of the installation process. However, the installed JRE can be removed after Autoform DM has been successfully installed, because the installer installs a JDK for Wildfly (and so Autoform DM) to run on.

The following diagram illustrates how these elements interact.

Prerequisite and Preparatory Tasks

Decide Whether Autoform DM Will Use HTTP or HTTPS

By default, the installer configures Autoform DM to use HTTPS.

If using HTTPS, you must obtain a keystore that contains relevant certificates. If these are not available during installation, the installer can create a temporary self-signed certificate, which you can replace later.

Decide Which Network Ports Autoform DM Will Use

To avoid conflicts with other applications, consider what port Autoform DM will use for HTTPS connections and (if relevant) HTTP connections.

Tip

If multiple Autoform DM server instances will run on the same server computer, you can use the port offset feature to ensure that they do not use the same ports. In summary, you specify the same port numbers when you install each Autoform DM server instance (for example, port 443 for HTTPS), but you specify a different port offset for each server instance.

For example, if both instances' HTTPS Port is set to 443, and you set Port offset to 0 for the first instance and to 1 for the second instance, the first server's HTTPS port will be 443, and the second server's HTTPS port will be 444.

This configuration occurs at the Configure Wildfly (Application Server) stage of the installation process.

Create and Configure a Database

Before you install Autoform DM, you must create a database for it to use. When Autoform DM starts for the first time, it will configure the database.

Microsoft SQL Server

If necessary, install Microsoft SQL Server. For information about compatible Microsoft SQL Server versions, see the Database section of Autoform DM Compatibility Matrix.

Then, to create a suitable database, follow the instructions on the Create a Microsoft SQL Server Database for Autoform DM page.

Oracle

If necessary, install an Oracle database management system. For information about compatible Oracle versions, see the Database section of Autoform DM Compatibility Matrix.

For information about creating a suitable Oracle database, contact Formpipe.

Install a Java Runtime Environment (JRE)

The Autoform DM installer runs on Java. So, you must install a JRE or JDK on the Autoform DM server before you run the Autoform DM installer.

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.

Check that the Autoform DM Server Computer is Running a Supported Operating System

For information about compatible Microsoft Windows operating systems, see the Operating System section of Autoform DM Compatibility Matrix.

Install Autoform DM

The Autoform DM installation wizard has several pages. Together, these pages collect information that enables the installer to:

• Install Autoform DM application files

• Install Wildfly

• Install a JDK

• Configure Wildfly

After collecting this information, it installs this software and configures Wildfly.

1. Run the Autoform DM Installer

To run the interactive installer, double-click the installer EXE file (for example: Autoform-DM_Installer-v10.4.1.exe).

The installer will display its Welcome page.

Click Next.

Note

The installer is also available as a JAR file. Use the JAR file instead of the EXE installer if you have advanced installation requirements that necessitate the user of a JAR file.

2. Accept the End User Software Licence Agreement

Review the displayed End User Software Licence Agreement.

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

3. Select "New" Installation Type

Because this is a new installation (rather than an upgrade), click New. Then, 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.

Enter an appropriate Node name, then click Next.

5. Choose an Installation Location

Check whether the default installation path (which includes the node name) is appropriate. If necessary, enter a different location (or click Browse to select a location).

Then, click Next.

6. Choose Which Components to Install

Select the checkboxes beside the Autoform DM components that you want to install, then click Next.

Note

Application Server (Wildfly) and Autoform DM Server are mandatory components. So, 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, 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. The port number must be unique per server.

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 check box is cleared. If appropriate, select this option; the information above the check box describes when this option is relevant.

Complete this page then 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 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 his 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.

Complete this page then 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 that contains the HTTPS certificate that you want Autoform DM to use. You must also provide the accompanying credentials.

HTTPS certificate keystore to install: Select the Java KeyStore (JKS) or Personal Information Exchange (PFX) file that contains the SSL certificate that 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 continue, 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 configuration:

• alias: dm_cert

• password: dmcert

To continue, click Next.

Note

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

8. Configure Autoform DM

In the Archive Path box (on the DM Server configuration page), enter an existing location for Autoform DM to use as the document archive location (or click Browse to select a location). Then, click Next.

Warning

Ensure that Autoform DM has read and write permissions to this location.

Note

For standalone Autoform DM systems, you can specify a local path, such as the default c:\archive

To specify a remote location, you can use one of the following types of path:

• UNC path: Enter a reference to a network share. For example, \\nas\share\ARCHIVE

• iSCSI target: This type of path is robust and appears as a local path to the application.

If you want to use an advanced type of path (such as an Azure path), you must do this as a separate configuration task after you have successfully installed Autoform DM.

It is not recommended to use other remote path options such as symlinked paths and mapped drives.

9. Configure the Database Connection

The information that you enter on this page enables Autoform DM to connect to the database that you created during the earlier Create and Configure a Database part of the installation process.

Select target database: Select the type of database that Autoform will be using.

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 when you created the database.

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

To continue, click Next.

10. 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 user name and password. For user name, 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 continue, click Next.

11. 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).

To start installing the software, click Next.

12. 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 complete.

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

Click Done to close the installation wizard.

Apply a License to Autoform DM

To use the new Autoform DM instance, you must apply a valid license to it.

To do this, follow these steps:

1. In a web browser, go to <base-URL>/dm (substitute <base-URL> for the base URL of the Autoform DM installation, or for http://localhost or https://localhost if appropriate). For example, https://autoformDMServer/dm.

2. On the Autoform DM log in page, enter the following credentials, then click Login:

   • Username: admin

   • Password: ChangeMe

3. On the Autoform DM requires activation page, click Browse (see a in the image below), select your Autoform DM license file, then click Activate (b). Alternatively, paste the license key text (from that file) into the box (c) in the Update licence area, then click Activate.

   Note

   If you do not have a licence file available to you at this time, you can temporarily activate Autoform DM for 30 days. To do this, click Evaluate (see d below) in the Evaluation Mode area.

   

4. After the license successfully activates (or Autoform DM enters evaluation mode), click Continue to Autoform DM at the top of the page.

   

5. You will now be prompted to change the default password (ChangeMe). Choose a suitably secure password and enter it into the appropriate boxes. Click Confirm to continue.

Complete any Necessary Post-Installation Tasks

After completing the steps above, you might need to complete some of the following tasks.

Make Post-Installation Configuration Changes (in the node.properties File)

If you need to change or update some of the configuration values that were used during installation, you can edit them in the node.properties file which is in the \domain\configuration\ area of the Autoform DM installation's directory.

For example: C:\Program Files\Formpipe Software\Autoform DM\Server_<Autoform DM version number>\wildfly-<Wildfly version number>.Final\domain\configuration\.

The node.properties file is present in Autoform DM 8.2 and later. It is the default location for changing installation values. Do not make changes in other XML configuration files (to change configuration values) because those files will not have primacy over node.properties.

Example of Adjustable Values

# The bind address for the management interface

# This must be public for PDC/SDC (unless running everything on single host), but can remain local/private for other nodes

jboss.bind.address.management=0.0.0.0

# The port for the web management console and jboss cli, also used by the windows service

jboss.management.http.port=9990

# The port used by nodes in the cluster to connect to each other

jboss.management.native.port=9999

Refer to the information in the node.properties file itself for full details and explanations of the various properties that can be set. These properties include the Autoform DM logging level.

Other Post-Installation Tasks

Open Ports

Ensure that the HTTP and HTTPS ports chosen during installation are accessible through any firewalls between the target machine and clients.

Add Client WAR Files

If the client WAR files were not installed at the same time as the main software, and you want to install the Autoform DM client, copy the relevant WAR files to <Autoform DM installation directory>\wildfly-<Wildfly version number>.Final\standalone\deployments.

Remove the 'Data Definition Language' Role

Once the installation is complete, the database account can (and should ideally) have its permissions tightened to remove the ability to DROP, UPDATE, and ALTER tables. For example, remove the db_ddladmin role so the user only has the db_datareader and db_datawriter roles for SQL Server.

Perform a System Test

Once Autoform DM has started and has been activated, perform a series of actions that will enable you to confirm that the installation is working as expected. For example, you could:

1. Test logging in to Autoform DM.

2. Run a document search, or document import, or both.

3. View a document image from a document search.

4. Send an email.

5. Check that the editor/client are connecting to Autoform DM Server.

6. Check that the client application can start in the client.

Azure Storage Paths

If you wish to use Azure for one or more storage paths, you must set these up after Autoform DM is installed and running. Log into Autoform DM and configure the paths on the Server Settings page.

Collation Setup

If Autoform DM runs without errors, leave the collation settings as their default values. On SQL Server and Oracle, the default collation is based the locale setting of the server that the database system is installed on.

How to change collation on Oracle (See NLS_SORT)

How to change the collation on MS SQL Server

Warning

The collation that is used must be case-insensitive, so that it is compatible with the Autoform DM server.

Known Issues

Client WAR Files Cause Problems

If the Autoform DM Client WAR files cause issues with the deployment of Autoform DM, it may be because the application server has an issue with the WAR files' internal structure. Open the client.war and setup.war files in a program that can open ZIP archives, delete the WEB-INF directory, then redeploy the WAR files.

Installing with Oracle Database – Extra Permission Needed

Note

Autoform DM installations that use an Oracle database require you to follow extra configuration steps.

Autoform DM cannot select dba_ind_columns. For example:

Sql = SELECT index_name FROM dba_ind_columns WHERE UPPER(table_name) = 'TBLDOCUMENTS' AND UPPER(column_name) = 'SKEY1'

Error Msg = ORA-00942: table or view does not exist

The solution is to grant the pdm user the SELECT ANY DICTIONARY permission:

GRANT SELECT ANY DICTIONARY to pdm;