Perceptive TransForm E-Forms Manager

Transcription

1 Perceptive TransForm E-Forms Manager Installation and Setup Guide Version: 8.x Date: February 2017

2 Lexmark. All rights reserved. Lexmark is a trademark of Lexmark International Inc., registered in the U.S. and/or other countries. All other trademarks are the property of their respective owners. No part of this publication may be reproduced, stored, or transmitted in any form without the prior written permission of Lexmark.

3 Table of Contents Introduction... 5 Intended audience... 5 Related resources and documentation... 5 Before you install... 5 Overview... 5 System requirements... 6 Administrative rights... 6 Install E-Forms Manager... 6 Installation process... 6 Complete the installation... 8 Upgrade E-Forms Manager... 8 Upgrade process... 8 Complete the upgrade Upgrade of E-Forms Manager 7.1.x or earlier Upgrade of E-Forms Manager 7.2.x or higher Additional steps for Administration Console and Processing Engine Set up an external E-Forms Manager database Overview Before you begin Make sure the database system is supported Prepare the database Copy the appropriate JDBC Driver to E-Forms Manager Server Migrate an existing EFM data repository Before you begin Step 1: Configuration options Step 2: Preliminary checks Step 3: Database type selection Step 4: Database connection properties Step 5: Database connection test Step 6: Create or migrate the repository Step 7: Summary Create a new EFM data repository Before you begin: Stop the E-Forms Manager service

4 Step 1: Configuration options Step 2: Preliminary checks Step 3: Database type selection Step 4: Database connection properties Step 5: Database connection test Step 6: Create or migrate the repository Step 7: Summary Post-configuration Manually remove the dependency between E-Forms Manager Windows services Restore the default E-Forms Manager data repository configuration Change the database user credentials Configure E-Forms Manager Server E-Forms Manager configuration files Start and stop services Change the E-Forms Manager HTTP listen port Run the Administration Console and the E-Form Processing Engine on separate ports Step 1: Change form publication settings Step 2: Configure E-Forms Manager Server Step 3: Restart the E-Forms Manager Server service Step 4: Update bookmarks to the published forms list page Run E-Forms Manager behind a reverse proxy Configure SSL support on E-Forms Manager Server Obtain an SSL certificate Import the certificate to the key store Update the E-Forms Manager Server configuration Update form publication properties Maintain E-Forms Manager Data file maintenance Create a database backup routine Restore from a backup Uninstall E-Forms Manager Troubleshooting Requested resource not available error Connection issues using a proxy server

5 Introduction This guide provides instructions on how to install and configure Perceptive TransForm E-Forms Manager. After having read and followed these instructions, you should have an E-Forms Manager system running and configured for your environment, and you should be familiar with the ways you can customize the configuration settings to conform to your environment requirements. Perceptive Software periodically releases upgrades and new versions of Perceptive TransForm E-Forms Manager and other software. Before using these instructions, ensure that they pertain to the version of the software that you plan to install, upgrade to, or have currently in use. This guide pertains to all 8.x versions of E-Forms Manager unless otherwise noted. If, after using this guide, you find that the E-Forms Manager system does not function properly or as expected, contact your Perceptive TransForm representative. Intended audience This guide is intended for system administrators who are responsible for installing software and maintaining the servers and network of the organization into which the software installation and configuration steps will be performed. Related resources and documentation Before performing a new installation or upgrade of the E-Forms Manager software, refer to the corresponding release notes for detailed information about the features and changes included in that release and for information about any known issues with the software. Before you install Overview The installation package for E-Forms Manager is distributed as an executable setup program. The installation process uses a standard Windows wizard with prompts that guide you through the installation process. The installation package contains the resources necessary for performing new installations or for upgrading prior versions of the software to the current version. The installation program deploys the necessary software to a location specified during the installation process. It also creates and starts services by which the application runs automatically, one for the HTTP server process and another for the E-Forms Manager configuration and catalog database. Certain configuration files that specify environment-specific runtime settings for the E-Forms Manager server are deployed with default settings, which you can adjust or customize by following steps outlined later in this guide. Variations on some of these files are provided by the installer and can be used as examples for custom configuration. Important Do not install E-Forms Manager on a computer on which a Perceptive TransForm ifiller server system is already installed and running as a Standalone installation. Doing so damages the ifiller Standalone installation. For more information on ifiller installation and configuration options, refer to the Perceptive TransForm ifiller 8.x Installation and Configuration Guide. 5

6 System requirements For proper operation of the E-Forms Manager server application and for a proper user experience, ensure that the server and client systems meet the requirements according to the Perceptive TransForm Technical Specifications. Administrative rights A Windows user with administrative rights on the computer is required to perform the installation and configuration steps in this guide. Install E-Forms Manager Follow the steps in this section to perform a new installation of E-Forms Manager. If you already have a prior version of E-Forms Manager installed and you want to upgrade it, skip this section and read the Upgrade E-Forms Manager section. Before beginning a new installation, check your environment to ensure that you don t already have a prior version of E-Forms Manager installed, or that any prior versions have been completely removed. Refer to the section Uninstall E-Forms Manager for details. Installation process To install E-Forms Manager, complete the following steps. 1. Close any open programs. 2. If you have not done so already, download the E-Forms Manager Windows Installer program. 3. Run the setup program, TransForm-EFM-8.x-Setup.exe. 4. A wizard launches to begin the installation process. Click the Next button to continue. 5. In the Perceptive TransForm E-Forms Manager End User License Agreement screen, read the license agreement. If you accept the terms of the license agreement, select the I Accept box and click the Next button. 6. After accepting the license agreement, the next screen allows you to select the folder where you want to install E-Forms Manager. By default, E-Forms Manager installs into the C:\Program Files\TransForm\EFM folder. To select a different location, click the Browse button and select a folder. After you select a destination folder, or if you want to install into the default location, click the Next button. 7. Optional. You can select optional components to install with E-Forms Manager. Select the optional components and click the Next button. Each optional component is described below. Perceptive TransForm Designer. Perceptive TransForm Designer is a desktop WYSIWYG application that allows users to design e-forms that can be freely distributed across the Internet as well as be managed by an E-Forms Manager. Designer does not need to be installed on the same computer as E-Forms Manager; however, Designer does need to be installed in your organization to create and design e-forms. A specific Perceptive TransForm Designer installer exists that you can use to install Designer on a different computer if you choose not to install Designer along with E-Forms Manager. 6

7 Perceptive TransForm Filler. Perceptive TransForm Filler is a simple, intuitive desktop application that allows users to view, fill out, save, and print e-forms. Filler is required to view and fill out a registration form for a new installation and to view certain e-forms within E-Forms Manager; it is recommended that you install Filler along with E-Forms Manager. Note Perceptive TransForm Filler is automatically installed when Perceptive TransForm Designer is installed, so you are not prompted to install Filler separately if you chose to install Designer. Sample Forms. Sample Forms is a collection of pre-designed e-forms that provides useful examples of simple e-form design concepts and E-Forms Manager automation features like electronic submission and signing. Select this option to place the collection of sample e-forms into the My Documents\My Forms\E-Forms Manager Sample Forms folder of the current Windows user. E-Forms Manager Form Design Catalog. A Design Catalog is a collection of e-form objects that the user can access to design e-forms. Attributes of an e-form object such as font, color, and size are stored along with the object in the catalog so that the objects can be used when designing new forms. The E-Forms Manager Form Design Catalog contains e-form fields and buttons that the user can access to design e-forms that are managed by E-Forms Manager. These e-form objects are used in e-forms to enable E-Forms Manager related functionality, such as submission, signing, autofill, and workflow status. If you select this option, the catalog deploys as a file named E-Forms-Manager-8.x.cat into the My Documents\My Forms\E-Forms Manager Sample Forms folder of the current Windows user. 8. The next screen allows you to verify that the installation Destination Folder is correct. If the Destination Folder is correct, click the Next button to begin installing E-Forms Manager. At this point, the installer begins installing E-Forms Manager. Part of the process installs a Java Runtime Environment (JRE) that is used to run E-Forms Manager. A notification appears on the screen when the JRE installation begins, which may take a few minutes to complete. Note The JRE that is installed is only used by E-Forms Manager and does not affect any other programs on the computer that depend on a Java Runtime Environment. 9. After the E-Forms Manager related components and services are installed, the installer for Designer or Filler runs if you chose to install them. Follow the wizards and prompts related to these installations. 10. When all of the installation tasks are completed, you are prompted to create an administrator account for E-Forms Manager. This account is for initially logging in to the E-Forms Manager console and performing administrative tasks, such as creating one or more other administrator accounts. Enter a user ID for the initial E-Forms Manager administrator account. Although a standard user ID is supplied for you, we recommend that you change it to something not easily guessed. Enter and confirm a password. The password must be at least six characters in length and cannot include spaces. We recommend that you use a combination of letters, numbers, and special characters to create a strong password. The Next button is enabled once the value in the Password field and Confirm Password field match. Click the Next button to continue. 7

8 11. The installer starts E-Forms Manager in the background and you are prompted as to whether you want to access the administration console. Select Launch the Administration Console Now and click the Finish button to close the installer and launch the E-Forms Manager Administration Console so that you can license the software and perform initial administrative tasks. Note If you want to license the software and perform initial administrative tasks later, you can select Finish setup without launching the Administration console instead. Shortcuts to the console are available on the Desktop and in the Start Menu; you may use those to access the console later. Complete the installation At this point, E-Forms Manager is installed, running, and configured to use its embedded database for storage of the form catalog and other data. If you intend to use a supported external database instead, complete the following steps. 1. Proceed to the Setting Up an External E-Forms Manager Database section and follow the instructions for creating a new EFM repository. 2. After performing a new installation of E-Forms Manager, you must license the software. Refer to the Perceptive TransForm Licensing Guide for instructions on how to license TransForm. Upgrade E-Forms Manager This section describes how to upgrade an older version of E-Forms Manager to the current version. Upgrade process To upgrade E-Forms Manager, complete the following steps. 1. Ensure the Maintenance Expiration for the TransForm license has not expired. If this date is expired, upload the new license from the Customer Portal. 2. Stop the E-Forms Manager related Windows services. For instructions, refer to the Start and stop services section of this guide. 3. Close any open programs. 4. If you have not done so already, download the E-Forms Manager Windows Installer program. 5. Run the setup program, TransForm-EFM-8.x-Setup.exe. 6. A wizard launches to begin the upgrade process. Click the Next button to continue. 7. In the Perceptive TransForm E-Forms Manager End User License Agreement screen, read the license agreement. If you accept the terms of the license agreement, select the I Accept box and click the Next button. 8. After accepting the license agreement, the next screen notifies you that an existing E-Forms Manager installation has been detected and prompts you to confirm that you want to upgrade it to the current version. To continue with the upgrade, select the Upgrade box and click the Next button. Notes At this point, if you do not see the Installation Found screen, the installer does not detect an existing installation of E-Forms Manager on the computer and a new installation is performed. If you do not want to begin a new installation, click the Cancel button to exit the installation process. 8

9 If, during the upgrade, TransForm is completely uninstalled and then reinstalled, a new license must be requested and issued. 9. Optional. You can select optional components to install with E-Forms Manager. Select any of the optional components you want to install and click the Next button. Each optional component is described below. Perceptive TransForm Designer. Perceptive TransForm Designer is a desktop WYSIWYG application that allows users to design e-forms that can be freely distributed across the internet as well as be managed by E-Forms Manager. Perceptive TransForm Filler. Perceptive TransForm Filler is a simple, intuitive desktop application that allows users to view, fill out, save, and print e-forms. Important If Perceptive TransForm Filler or Designer is already installed, you should not install them again to avoid losing any customizations that may have been made to the existing installations. Sample Forms. Sample Forms is a collection of pre-designed e-forms that provides useful examples of simple e-form design concepts and E-Forms Manager automation features like electronic submission and signing. Select this option to place the collection of sample e-forms into the My Documents\My Forms\E-Forms Manager Sample Forms folder of the current Windows user. Note that if you already have sample forms installed, any modifications you made to them may be overwritten unless you have saved copies outside of the My Documents\My Forms\E- Forms Manager Sample Forms folder. E-Forms Manager Form Design Catalog. A Design Catalog is a collection of e-form objects that you can use to design e-forms. Attributes of an e-form object such as font, color, and size are stored along with the object in the catalog so that the objects can be used when designing new forms. The E-Forms Manager Form Design Catalog contains e-form fields and buttons that you can use to design e-forms that are managed by E-Forms Manager. You can use these e-form objects to enable E-Forms Manager related functionality such as submission, signing, autofill, and workflow status. If you select this option, the catalog deploys as a file named E-Forms-Manager- 8.x.cat into the My Documents\My Forms\E-Forms Manager Sample Forms folder of the current Windows user. 10. The next screen displays the Destination Folder and allows you to begin the upgrade. The upgraded version of E-Forms Manager is installed to the same folder as the prior version; the Destination Folder cannot be changed. Click the Next button to begin upgrading E-Forms Manager. At this point, the installer begins upgrading E-Forms Manager. Part of the upgrade process also upgrades the Java Runtime Environment (JRE) that is used to run E-Forms Manager. A notification appears on the screen when the JRE upgrade begins, which may take a few minutes to complete. Note The JRE that is installed is only used by E-Forms Manager and does not affect any other programs on the computer that depend on a Java Runtime Environment. 11. A program then launches that checks the E-Forms Manager database to make sure that its structure is compatible with this version of E-Forms Manager. If the database structure is incompatible, this program upgrades the database to the structure that is needed by this version of E-Forms Manager. Click the Start button to begin the database compatibility check and upgrade. As the database check and upgrade occurs, information related to the status of the upgrade displays on the screen. The Finish button is disabled until the database upgrade is completed. Important Depending on a number of factors, it may take between several seconds and several hours to upgrade the database structure. Do not attempt to close this window until the Finish button 9

10 is enabled and the status on the window indicates that the database compatibility check and upgrade is complete. Closing the program while the upgrade process is running may corrupt the database. 12. After the database compatibility routine is complete, the installer for Designer or Filler runs if you chose to install them. Follow the wizards and prompts related to those installations. 13. The installer re-starts E-Forms Manager in the background and prompts you as to whether you want to access the administration console. Select Launch the Administration Console Now and click the Finish button to close the installer and launch the E-Forms Manager Administration Console. Note If the installation you are upgrading has been modified so that the Administration Console and Processing Engine run on different ports, then you must perform additional steps to complete the upgrade. The installer does not automatically restart E-Forms Manager. Refer to the Complete the upgrade section for the additional required steps. Complete the upgrade At this point, the E-Forms Manager system has been upgraded and is running. E-Forms Manager is still configured to use the same database for storage of the form catalog and other data as the prior version. If you want to change E-Forms Manager to use a supported external database instead of the embedded one, proceed to the Set up an external E-Forms Manager database section and follow the instructions for Migrating an Existing EFM Data Repository. Otherwise, refer to the TransForm Licensing Guide to determine whether you need to obtain an updated license. Note When you perform an E-Forms Manager software upgrade, the server configuration file, located at [drive:]\program Files\TransForm\EFM\FSBServer\conf\server.xml, is automatically backed up. The backed up server configuration file is renamed as server.xml.installer.yyyymmddhhmm, where the last portion of the file name contains a timestamp representing the date and time of the upgrade. Upgrade of E-Forms Manager 7.1.x or earlier If the prior server configuration file contains any custom settings that were manually added to the file, such as custom listen ports and SSL configurations, it is necessary to add these settings to the new server XML configuration file manually. Refer to the Configure E-Forms Manager section for detailed information on changing these settings. Upgrade of E-Forms Manager 7.2.x or higher When the upgrade process needs to update the server configuration file, any custom settings that were manually added to this file, such as custom listen ports and SSL configurations, are preserved. Additional steps for Administration Console and Processing Engine If, prior to performing the upgrade, E-Forms Manager was configured to run the Administration Console and Processing Engine on separate ports, complete the following steps after the installer program finishes the upgrade. 1. Navigate to the FSBServer folder of the E-Forms Manager installation: [drive:]\program Files\TransForm\EFM\FSBServer. 2. Move the efm.war file from the webapps folder to the webapps-efm folder, overwriting the existing file. Important Make sure that you move the file and do not just copy it. The efm.war file should not be present in the webapps folder after this step. 10

11 3. Delete the efm folder and its contents from the webapps-efm folder. 4. Launch the Windows Services management console and start the TransForm E-Forms Manager Server service. 5. At this point, E-Forms Manager is running and you can launch Administration Console. Set up an external E-Forms Manager database This section provides instructions on how to set up E-Forms Manager to use an externally managed database system as its data repository. Overview Every E-Forms Manager installation includes an embedded database engine that is automatically configured to act as the EFM Data Repository. This embedded database is an enterprise-grade, relational database system that allows E-Forms Manager to be used in production installations without requiring a separately managed RDBMS. No additional setup steps are required to use it. However, beginning with version 7.3.0, you can configure E-Forms Manager to use another database system in your environment as an alternative to the system provided with E-Forms Manager. Among other benefits, this type of configuration allows you to make use of your own storage, database infrastructure, and backup and recovery for your E-Forms Manager system. The E-Forms Manager Data Repository Configuration (EFM DRC) utility is a program that you can use to set up E-Forms Manager to use an external database system instead of the embedded one. In this utility program, E-Forms Manager s catalog, configuration, and submission data is collectively referred to as the E-Forms Manager Data Repository. The EFM DRC utility is installed as part of the E-Forms Manager installation process and should be run from the same computer as the E-Forms Manager installation that you want to configure. There are two configuration options available in the EFM DRC utility. The first option allows you to migrate the E-Forms Manager Data Repository from an existing E-Forms Manager installation to a supported database external to E-Forms Manager. This option moves all existing catalog, configuration, and submission data from E-Forms Manager s embedded database. This option should always be used to migrate existing data, even immediately after a new installation, unless instructed to do otherwise. The second option allows you to create a new, empty E-Forms Manager Data Repository in a supported database that is external to E-Forms Manager. This option does not move any existing catalog, configuration, or submission data from E-Forms Manager s embedded database. This option should only be used if instructed to do so by support personnel or other documentation. Important Each time the EFM DRC utility is run, it drops any existing EFM Data Repository objects in the target database and then recreates them. Therefore, you should only run the EFM DRC utility one time using the same connection settings if you intend to remove or replace any E-Forms Manager data that exists there. The remainder of this section provides instructions on how to configure an E-Forms Manager installation to use a database system other than the embedded database to store its catalog, configuration, and submission data. 11

12 Before you begin Make sure the database system is supported The following Relational Database Management Systems (RDBMS) are supported. Microsoft SQL Server (2008, 2008R2, 2012, and 2014) Oracle (10g, 11g, and 12c) MySQL (5.5, 5.6, and 5.7) and InnoDB Storage Engine Prepare the database Ensure that the database chosen for your E-Forms Manager data repository has been prepared per the guidelines below. SQL Server Create or choose an SQL Server login whose default schema contains the E-Forms Manager Data Repository. Make sure that the user is in the db_owner role. Oracle Create or choose a database user whose schema contains the E-Forms Manager Data Repository. Make sure that this user has been granted the connect and resource roles. MySQL Create or choose a database user whose schema contains the E-Forms Manager Data Repository. Make sure that the user has full rights (excluding GRANT OPTION) in the schema. Increase max_allowed_packet E-Forms Manager may store data in the database that exceeds the default max_allowed_packet setting of 1M. To allow E-Forms Manager to store data that exceeds 1M, modify the my.ini configuration file for the MySQL instance and set the max_allowed_packet setting to 100M (for example, max_allowed_packet=100m). Copy the appropriate JDBC Driver to E-Forms Manager Server Before you can use the Data Repository Configuration Utility, you must first obtain the appropriate JDBC driver for the target database and place it into a location where it can be properly referenced by the utility and E-Forms Manager. Follow the instructions below to install the driver that matches the database you want to use. Note If you use E-Forms Manager or higher, skip steps 1 through 5 below, as the JDBC driver is included in the installation. SQL Server 1. Download the latest Windows version of the Microsoft SQL Server JDBC Driver from the Microsoft website. The download consists of a self-extracting executable zip file named sqljdbc_<version>_enu.exe. 12

13 2. Run the downloaded executable to extract its contents to the Desktop or another temporary location. This creates a folder called Microsoft SQL Server JDBC Driver Copy the file sqljdbc4.jar from the Microsoft SQL Server JDBC Driver 3.0\sqljdbc_3.0\enu folder into the FSBServer\common\lib folder, relative to your E-Forms Manager installation. Note For E-Forms Manager, version 7.5 or higher, if the SQL Server database instance you are connecting to requires clients to connect using Windows authentication, you should complete the following steps 4. Copy the sqljdbc_auth.dll file from the Microsoft SQL Server JDBC Driver 3.0\sqljdbc_3.0\enu\auth\x86 folder into the FSBServer\fsrvjini folder, relative to your E-Forms Manager installation. Note E-Forms Manager currently runs as a 32-bit application, so use the file from the x86 folder even if the operating system is 64-bit application. 5. Make sure that the target database is configured to allow the computer account or user account access to it. Oracle To install the latest version of the Oracle 10g and 11g releases, complete the following steps. Note If you use E-Forms Manager or higher, skip steps 1 and 2 below as the JDBC driver is included in the installation. 1. Download the latest release of the Oracle 11g JDBC driver (ojdbc6.jar) from Oracle s website. Refer to the Oracle website for more information. 2. Place the ojdbc6.jar file into the FSBServer\common\lib folder relative to your E-Forms Manager installation. MySQL To install the latest version of the MySQL, complete the following steps. 1. Download the latest Windows version of the MySQL JDBC Driver from the MySQL website. 2. Run the downloaded executable and then locate the newly installed.jar file. 3. Rename the file mysql-connector-java-bin.jar 4. Copy this file into the FSBServer\common\lib folder, relative to your E-Forms Manager installation. Now you are ready to run the EFM DRC utility to configure the E-Forms Manager Data Repository. If you want to migrate the E-Forms Manager Data Repository from an existing E-Forms Manager installation to a supported database external to E-Forms Manager, refer to the Migrate an existing EFM data repository section below. If you want to create a new, empty E-Forms Manager Data Repository in a supported database that is external to E-Forms Manager, refer to the Create a new EFM data repository section below. Migrate an existing EFM data repository This section provides instructions on using the E-Forms Manager Data Repository Configuration Utility to move an existing E-Forms Manager Data Repository from the default included database to a supported external database. To migrate to an existing EFM data repository, complete the following steps in order. 13

14 1. Before you begin 2. Configure options 3. Preliminary checks 4. Database type selection 5. Database connection properties 6. Database connection test 7. Create or migrate the repository 8. Summary Before you begin Before running the EFM Data Repository Configuration tool, complete the following steps. 1. Stop the TransForm E-Forms Manager Server service. You must stop the TransForm E-Forms Manager Server service prior to running the EFM DRC utility. The EFM DRC utility performs a check to ensure that the service is not currently running and does not allow a configuration to continue if the service is running. For instructions on how to stop this service, refer to the Start and stop services section of this guide. 2. Ensure the E-Forms Manager Database service is running. The TransForm_EFM_DB service must be running prior to running the EFM DRC utility. The EFM DRC utility checks to ensure that it can connect to the embedded database before allowing the repository configuration process to continue. For instructions on how to check if this service is running and to start it if necessary, refer to the Start and stop services section of this guide. 3. Optional. Back up the existing database. When configuring a data repository for an existing E-Forms Manager installation, it is highly recommended that the existing embedded database be backed up before proceeding. Use the E- Forms Manager database backup functionality located in the Administration tab of E-Forms Manager to back up the existing embedded database. For instructions on how to backup an existing EFM Installation s embedded database, refer to the Data file maintenance section of this document. 4. Optional. Clean up aging content. When migrating an existing EFM Data Repository, the EFM DRC utility moves all existing database objects and data into the new database. The length of time required to complete this task correlates with the amount of existing data in the embedded database. It is recommended that you use the Aging Content feature of E-Forms Manager to archive and remove aged submission related data prior to running of the E-Forms Manager Data Repository Configuration utility. For instructions on how to archive and remove existing submission related data, refer to the Archival and Removal of Submitted Forms section of the E-Forms Manager online help. 14

15 Step 1: Configuration options To configure options to migrate an existing EFM data repository, complete the following steps. 1. To open the EFM DRC utility, select Start > All Programs > Perceptive TransForm > Perceptive TransForm E-Forms Manager > Data Repository Configuration from the Windows Start Menu. 2. Select the Migrate an existing EFM Data Repository option. Click the Next button to continue. Step 2: Preliminary checks The EFM DRC utility checks to ensure that the system and services are in the correct state for the configuration to proceed. If all of the preliminary checks succeed, a message displays stating this and allows the configuration to continue. Click the Next button to continue. 15

16 If any of the checks should fail, an error message describing the failure displays. Follow the instructions displayed to resolve the failure so that the configuration may proceed. Step 3: Database type selection On the next screen, you are prompted to select the type of database that will contain the EFM Data Repository. Select one of the supported database types from the list and click the Next button to continue. Step 4: Database connection properties After you chose the database type, you are prompted to enter the required connection properties that the EFM DRC utility will use to connect to the database. Enter the connection properties in the fields provided. The fields that are provided vary based on the chosen database type. SQL Server To define the connection properties for an SQL server, in the E-Forms Manager Data Repository Configuration dialog box, complete the following step. 1. Use Windows Authentication. Select this box to use Windows Authentication to connect to the target database. Note You must complete the additional steps related to Windows Authentication in the Prepare the database section. 2. Username. Enter the user name used to establish a connection to the target database that will contain the data repository. This is not required if you checked Use Windows Authentication. 3. Password. Enter the password of the user entered in the Username field above. This is not required if you checked Use Windows Authentication. 4. Host. Enter either the server name or IP Address of the machine that hosts the target database you are configuring. To connect to a named instance, specify the Host value in the following format. ServerName\InstanceName, such as DBServer\SQLEXPRESS. 5. Port. Enter the port number on which the database is listening for TCP/IP connections. If connecting to a named instance, leave this field blank and do not provide a port number. 6. Database. Enter the name of the database. 7. Schema. Enter the name of the default schema assigned to the user specified in the Username field above. The default value is dbo but, if this user has been assigned a different default schema, you must enter that schema name instead. Oracle 10g/11g or 12c To define the connection properties for an Oracle server, in the E-Forms Manager Data Repository Configuration dialog box. 1. Username. Enter the user name used to establish a connection to the target database that will contain the data repository. 1. Password. Enter the password of the user entered in the Username field above. 2. Host. Enter either the machine name or IP address of the machine that hosts the target database you are configuring. 16

17 3. Port. Enter the port number on which the database is listening for TCP/IP connections. 4. SID (10g/11g option only). Enter the SID of the database instance. 5. Server (12c option only). Enter the Service Name of the database instance. 6. After you enter a value for all of the properties, click the Next button to continue. MySQL To define the connection properties for a MySQL server, in the E-Forms Manager Data Repository Configuration dialog box, complete the following step. 1. Username. Enter the user name to be used to establish a connection to the target database that contains the data repository. 2. Password. Enter the password of the user entered in the Username field above. 3. Host. Enter either the machine name or IP Address of the machine that hosts the target database you are configuring. 4. Port. Enter the port number on which the database is listening for TCP/IP connections. 5. Database. Enter the name of the database. 6. After you enter all of the appropriate properties, click the Next button to continue. Note In addition to using these connection properties to connect to the database during this configuration process, the EFM DRC Utility also changes the E-Forms Manager installation to use the same connection properties for accessing its Data Repository. For information on how to change the user that E-Forms Manager will use to access its Data Repository, refer to the Post-configuration section of this guide. Important Each time the EFM DRC utility runs, it drops any existing EFM Data Repository objects in the target database then recreates them. Therefore, you should only run the EFM DRC utility one time using the same connection settings if you intend to remove or replace any E-Forms Manager data that exists there. Step 5: Database connection test The EFM DRC utility uses the connection properties entered in the previous section and attempts to establish a connection to the database. If the database connection test is successful, you may proceed to the next section by clicking the Next button. 17

18 If a connection cannot be established, the EFM DRC utility displays an error message. Click the Prev button to modify the connection properties (if needed) and perform the database connection test again. Step 6: Create or migrate the repository The EFM DRC utility is now ready to migrate the existing EFM Data Repository to the target database. Read the warning message and click the Finish button to migrate the existing data repository. After you click the Finish button, a progress bar displays on the left side of the EFM DRC utility. This progress bar displays the current operation as the process runs. The status window on the right side of the utility also displays information about the process. The amount of time it takes for this process to complete depends largely on the size of the existing embedded E-Forms Manager database. The EFM DRC utility updates the status widow every few seconds with a series of ellipses to provide a visual cue that the process is still running. 18

19 Important It may take several minutes to several hours to migrate the data repository. Closing the program while the migration process is running results in an incomplete data repository in the target database. Step 7: Summary After the EFM DRC utility has finished the migration of the E-Forms Manager Data Repository, a summary screen displays, informing you that the process is complete. At this point, you may restart the TransForm E-Forms Manager Server service. For instructions on how to do this, refer to the Start and stop services section of this guide. If the EFM DRC utility failed to complete the migration of the E-Forms Manager Data Repository, a message stating that the process failed displays in the status window. You should consult the EFM DRC utility log file for further details on the error that prevented the data repository from being created. The EFM DRC utility log file is named EFM-DRC.log and is located in the utilities folder of your E-Forms Manager installation (for example, [drive:]\program Files\TransForm\EFM\FSBServer\utilities). Once the problem is corrected, you must run the EFM DRC utility again to migrate the E-Forms Manager Data Repository. Create a new EFM data repository This section provides instructions on using the E-Forms Manager Data Repository Configuration Utility (EFM DRC) to create a new repository in the database you chose. To create the repository, complete the following processes in the order specified. 1. Stop the E-Forms Manager service 2. Configuration options 3. Preliminary checks 4. Database type selection 5. Database connection properties 6. Database connection test 19

20 7. Create or migrate the repository 8. Summary Before you begin: Stop the E-Forms Manager service You must stop the TransForm E-Forms Manager Server service prior to running the EFM DRC utility. The EFM DRC utility performs a check to verify that the service is not currently running and does not allow a configuration to continue if the service is in a running state. For instructions on how to complete this process, refer to the Start and stop services section of this guide. To create a new EFM data repository, you need to access the E-Forms Manager Data Repository Configuration wizard and complete the following procedures. Each step is listed in the left pane of the wizard. The following sections of this guide step you through the EFM data repository creation. Step 1: Configuration options To configure the EFM repository options, complete the following steps. 1. Open the EFM DRC utility by selecting Start > All Programs > Perceptive TransForm > Perceptive TransForm E-Forms Manager > Data Repository Configuration from the Windows Start menu. 2. Select the Create a new EFM Data Repository option. Click the Next button to continue. Step 2: Preliminary checks The EFM DRC utility checks to make sure that the system and services are in the correct state for the configuration to proceed. If all of the preliminary checks succeed, a message displays stating this and allows the configuration to continue. To accept the EFM DRC utility check, complete the following step. Review the information that displays in the E-Forms Manager Data Repository Configuration page and click the Next button to continue. 20

21 If any of the checks should fail, an error message describing the failure displays. Follow the instructions displayed to resolve the check failure so that the configuration may proceed. Step 3: Database type selection You are then prompted to select the type of database that will contain the new EFM Data Repository. To select a database that contains the new EFM Data Repository, select one of the supported database types from the list and click the Next button to continue. Step 4: Database connection properties After you chose the database type, you are prompted to enter the required connection properties that are used by the EFM DRC utility to connect to the database. Enter the connection properties in the fields provided. The fields that are provided vary based on the chosen database type. To enter the required connection properties, complete the following steps based on your operating system. SQL Server To define the connection properties for an SQL server, in the E-Forms Manager Data Repository Configuration dialog box, complete the following steps. 1. Use Windows Authentication. Select this box to use Windows Authentication to connect to the target database. Note You must complete the additional steps related to Windows Authentication in the Prepare the database section. 2. Username. Enter the user name you want to use to establish a connection to the target database that will contain the data repository. This is not required if you select the Use Windows Authentication option 3. Password. Enter the password of the user entered in the Username field above. This is not required if you select the Use Windows Authentication option. 21

22 4. Host. Enter either the server name or IP Address of the machine that hosts the target database you are configuring. To connect to a named instance, specify the Host value in the following format: ServerName\InstanceName, such as DBServer\SQLEXPRESS. 5. Port. Enter the Port number on which the database is listening for TCP/IP connections. If connecting to a named instance, leave this field blank and do not provide a port number. 6. Database. Enter the name of the database. 7. Schema. Enter the name of the default schema assigned to the user specified in the Username field above. The default value is dbo but, if this user has been assigned a different default schema, you must enter that schema name instead. 8. After you enter all of the appropriate properties, click the Next button to continue. Oracle 10r/11g or 12c To define the connection properties for an Oracle server, in the E-Forms Manager Data Repository Configuration dialog box, complete the following steps. 1. Username. Enter the user name used to establish a connection to the target database that contains the data repository. 2. Password. Enter the password of the user entered in the Username field above. 3. Host. Enter either the machine name or IP address of the machine that hosts the target database you are configuring. 4. Port. Enter the port number on which the database is listening for TCP/IP connections. 5. SID (10g/11g option only). Enter the SID of the database instance. 6. Service (12c option only). Enter the Service Name of the database instance. 7. After you enter all the appropriate properties, click the Next button to continue. 22

23 MySQL To define the connection properties for a MySQL server, in the E-Forms Manager Data Repository Configuration dialog box, complete the following steps. 1. Username. Enter the user name to be used to establish a connection to the target database that contains the data repository. 2. Password. Enter the password of the user entered in the Username field above. 3. Host. Enter either the machine name or IP Address of the machine that hosts the target database you are configuring. 4. Port. Enter the port number on which the database is listening for TCP/IP connections. 5. Database. Enter the name of the database. 6. After you enter all of the appropriate properties, click the Next button to continue. Note In addition to using these connection properties to connect to the database during this configuration process, the EFM DRC Utility also changes the E-Forms Manager installation to use the same connection properties for accessing its Data Repository. For information on how to change the user that E-Forms Manager uses to access its Data Repository, refer to the Post-configuration section of this guide. Step 5: Database connection test The EFM DRC utility uses the connection properties entered in the previous step and attempts to establish a connection to the database. If the database connection test is successful, you may proceed to the next step by clicking the Next button. If a connection cannot be established, the EFM DRC utility displays an error message. Click the Prev button to modify the connection properties (if needed) and perform the database connection test again. Step 6: Create or migrate the repository The EFM DRC utility is now ready to create a new EFM Data Repository in the target database. 23

24 Read the warning message displayed and click the Finish button to create a new EFM Data Repository. After you click the Finish button, a progress bar displays on the left side of the EFM DRC utility. This progress bar displays the current operation as the process runs. The status window on the right side of the utility also displays information about the process. Step 7: Summary After the EFM DRC utility finishes creating a new E-Forms Manager Data Repository, a summary screen displays, informing you that the process is complete. At this point, you may restart the TransForm E- Forms Manager Server service. For instructions on how to do this, refer to the Start and stop services section of this guide. 24

25 If the EFM DRC utility fails to create a new E-Forms Manager Data Repository, a message stating that the process failed displays in the status window. Consult the EFM DRC utility log file for further details on the error that prevented the data repository from being created. The EFM DRC utility log file is named EFM-DRC.log and is located in the utilities folder of your E-Forms Manager installation: [drive:]\program Files\TransForm\EFM\FSBServer\utilities. Once the problem is corrected, you must run the EFM DRC utility again to create a new E-Forms Manager Data Repository. Post-configuration This section provides instruction on some optional steps you may need to perform following a switch to an external database. Manually remove the dependency between E-Forms Manager Windows services After a repository creation or migration process is completed, the EFM DRC utility attempts to disable the embedded E-Forms Manager database service since it is no longer needed. In the event that the EFM DRC utility is unable to disable the service, an error message displays in the Summary screen. If you see this message, the data repository has been configured as specified during the execution of the EFM DRC utility and it is safe to restart the TransForm E-Forms Manager Server service. However, it is recommended that you perform the service modification manually. This allows the Windows service that controls the embedded database to be stopped and disabled since it is no longer needed. To modify the TransForm E-Forms Manager Server service manually so that it no longer depends on the TransForm_EFM_DB service, complete the following steps. 1. Open a DOS prompt and navigate to the service directory of the E-Forms Manager installation: [drive:]\program Files\TransForm\EFM\FSBServer\service). 2. Run the Remove-ASA-Dependency.bat batch file. The batch file removes the dependency from the TransForm E-Forms Manager Server service and stops and disables the TransForm_EFM_DB service. After the batch file runs, you can verify that the Windows services are modified by viewing the Properties of each service in the Windows Services management console. The TransForm E-Forms Manager Server service should no longer list the TransForm_EFM_DB service as a dependency and the TransForm_EFM_DB service s status should be set to Stopped with a Startup Type of Disabled. Restore the default E-Forms Manager data repository configuration Should you find it necessary to restore E-Forms Manager to its default data repository configuration so that it again uses the embedded database, use the procedure in this section. Important If your EFM system has been in use with an externally managed Oracle, SQL Server, or MySQL database, any data created in the new repository is not available once you go back to the original configuration. To reset E-Forms Manager to its original data repository configuration, complete the following steps. 1. Stop the TransForm E-Forms Manager Server service. 2. Open a DOS prompt and navigate to the service directory of the E-Forms Manager installation. For example, navigate to [drive:]\program Files\TransForm\EFM\FSBServer\service. 25

26 3. Run the Replace-ASA-Dependency.bat batch file. The batch file restores the dependency between the services and sets the Startup Type of the TransForm_EFM_DB service back to Automatic. 4. Navigate to the conf folder of the E-Forms Manager installation. For example, navigate to [drive:]\program Files\TransForm\EFM\FSBServer\conf. 5. Create a backup copy of the existing server.xml file in this directory. 6. Restore the version of the server.xml file that was in use before the EFM DRC utility ran by renaming the latest EFM DRC backup of that file to server.xml. The EFM DRC backup server.xml file is named server.xml.efmdrc.yyyymmddhhmm, where the last portion of the file name contains a timestamp representing the date and time that the EFM DRC utility was run. 7. Open the efmdb.properties file (also in the conf folder) in a text editor and change the value of the DATABASE_TYPE property to default. Save and close this file. 8. Start the TransForm E-Forms Manager Server service. At this point, the dependency between the E-Forms Manager service and the embedded database service should be restored, so the database service starts up automatically. Also, by replacing the application configuration file, server.xml, E-Forms Manager s connection settings are restored to point to the embedded database. Change the database user credentials In some cases, it may be necessary to change the database credential settings used by E-Forms Manager to connect to an externally managed database. To do this, complete the following steps. 1. Stop the TransForm E-Forms Manager Server service. 2. Navigate to the conf folder of the E-Forms Manager installation. For example, navigate to [drive:]\program Files\TransForm\EFM\FSBServer\conf. 3. Create a backup copy of the existing server.xml file in this directory. 4. Open the server.xml file in a text editor. 26

27 5. Locate the line of the file beginning with <Resource name="jdbc/sbspool". 6. Optional. If you need to change the user name for the connection, change the value associated with the user name attribute to the new user name. 7. Optional. If you need to change the password, complete the following substeps. 1. Open a DOS command prompt and navigate to the utilities directory under your E-Forms Manager installation. For example, navigate to [drive:]\program Files\TransForm\EFM\utilities. 2. Run the EncryptPassword.bat utility followed by the password that you want to use. For example, enter >EncryptPassword mypassword. 3. This prints out an encrypted version of the password you provided. Copy this encrypted password string to the clipboard. 4. On the same line of the server.xml file, replace the existing value for the password attribute with the encrypted password. 8. Save and close the server.xml file. 9. Start the TransForm E-Forms Manager Server service. 27

28 Configure E-Forms Manager Server When E-Forms Manager is installed, it is configured automatically with default settings that define characteristics of the application and the server process it uses, such as its listen port for HTTP requests, memory used by the service, and more. Normally, the server starts up once it is installed and these settings do not need to be changed. However, there can be circumstances in which it is appropriate or necessary to make changes to certain types of configurations. For example, if the default port used by E- Forms Manager (8080) is already in use on the server, the E-Forms Manager server does not start properly, making it necessary to make it listen on a different port. Sometimes customers may want to make the E-Forms Manager HTTP interface listen over a secure connection, which requires configuration steps to make it reference an SSL certificate. This section of the guide provides details on how to change these types of settings, as well as general guidelines on different deployment scenarios. E-Forms Manager configuration files Several configuration files that are part of the E-Forms Manager installation are referenced in the instructions below for the various configuration changes described. The following table lists these files, a description of each file, and the file location so that the instructions that follow do not have to provide this information each time these files are referenced. Locations listed are relative to the folder in which E- Forms Manager is installed, such as [drive:]\program Files\TransForm\EFM\. Configuration File Name Location Description server.xml FSBServer\conf Contains the settings that determine overall behavior of the HTTP engine, such as the listen port. This is a standard Apache Tomcat server configuration file that has settings specifically for E-Forms Manager. efmdb.properties FSBServer\conf Contains parameters that are used by E-Forms Manager to specify which type of database is being used as the EFM Data Repository. wrapper.conf Note This configuration file was removed from versions 8.12 and higher. FSBServer\conf Contains settings and parameters that define parameters for the TransForm E-Forms Manager Server Windows service, such as application library path and memory settings. Start and stop services The E-Forms Manager server process and its embedded database engine are controlled by Windows services. When E-Forms Manager is installed, two Windows services are created. These services are named TransForm E-Forms Manager Server and TransForm_EFM_DB, respectively. There are several tasks related to the maintenance and configuration of E-Forms Manager that may involve stopping and starting one or both of these services. 28

29 To start or stop the E-Forms Manager related Windows services, complete the following steps. 1. Launch the Windows Services management console by clicking Control Panel > Administrative Tools > Services. 2. Check the list of services for a service named TransForm E-Forms Manager Server or one named TransForm_EFM_DB. 3. Use the controls in the management console to start or stop the services. Note Since the main E-Forms Manager service (TransForm E-Forms Manager Server) cannot run without the embedded database engine (TransForm_EFM_DB), it has been configured by the installation as having a dependent relationship with it. So stopping the database service automatically calls for stopping the main E-Forms Manager service. Change the E-Forms Manager HTTP listen port E-Forms Manager contains a Tomcat Servlet engine that it uses to serve forms to users, handle requests from forms to perform operations such as submission and signing, and to serve up the administration console. By default, the E-Forms Manager application server accepts HTTP requests on port In some environments, such as those in which another Tomcat server is already running, it may be necessary to change the port that E-Forms Manager runs on to another port, such as 80. To change the E-Forms Manager server listen port to accept requests on a port other than 8080, complete the following steps. 1. Make sure that the port you want to use is not already in use by another process on the server. For example, if an Apache or IIS web server is installed and running on the same machine as the E-Forms Manager server, port 80 is most likely being used. If E-Forms Manager is configured to run on a port that is already in use, either it will fail to start correctly or it will cause problems with the other process that is using that port. 2. Launch the Windows Services management console and stop the TransForm E-Forms Manager Server service. For instructions on how to do this, refer to the Start and stop services section of this guide. 3. Open the server.xml file in a text editor such as WordPad. 29

30 4. If the server that E-Forms Manager is installed on already has another Tomcat server, you should change the Shutdown Port value to avoid conflicts. To do this, find the line beginning with the text <Server port= 8005 and change the value from 8005 to another port that is not in use. 5. To change the E-Forms Manager listen port, find the line beginning with the text <Connector port= Change the "8080" value to the port on which you want your server to run. For example, if you want E-Forms Manager to listen on port 80, change this to <Connector port="80". Leave the rest of the line exactly as it is. 6. Save and close the server.xml file. 30

31 The desktop and start menu shortcuts that open the application console contain URLs that reference the application by host name and port. Since the server s listen port has changed, the shortcuts are now invalid and need to be changed. To change the shortcut destination, complete the following steps. 1. In Windows Explorer, browse to the TransForm E-Forms Manager shortcut file located in the FSBServer folder relative to the E-Forms Manager installation location. Right-click this file and select Properties. 2. On the Web Document tab, change the URL value from 8080 so that the port number in the URL reflects the new listen port. If you set the port to 80, you may simply remove the ":8080" portion of the URL. 3. From the Services console on your server, start the TransForm E-Forms Manager Server process. After the E-Forms Manager service has started, it is necessary to change the Form Publication properties in E-Forms Manager so that forms may be properly opened from and communicate with E-Forms Manager. To do this, complete the following steps. 1. Launch the E-Forms Manager Administration Console and log in using an account with administrative privileges. Go to the Administration section of the console and select the Form Publication menu item. 2. In the Form Publication screen, change the value in the field labeled Port to the new listen port number and then click the Save Changes button at the bottom of the screen. 3. Test the changes by opening forms from the E-Forms Manager catalog and attempting to sign or submit them. If any of the configuration settings are incorrect, an error message displays that indicates a problem connecting to the server. Run the Administration Console and the E-Form Processing Engine on separate ports By default, the Administration Console and the E-Form Processing Engine run on the same port. You can configure these two components of E-Forms Manager to listen on separate ports. One reason for running these components on separate ports is that it requires only a simple firewall configuration to block access to the Administration Console to users outside of your organization while allowing all users to open and submit e-forms. To change the components to run on separate ports, complete the following steps in the order listed. 1. Change form publication settings 2. Configure E-Forms Manager Server 3. Restart the E-Forms Manager Server service 4. Update bookmarks to the published forms list page Step 1: Change form publication settings To change form publication settings, complete the following steps. 1. Launch the E-Forms Manager Administration Console and log in using an account with administrative privileges. Go to the Administration section of the console and select the Form Publication menu item. 31

32 2. In the Form Publication screen, on the Form Publication page, change the value in the Port field to the Form Processing application s new listen port number (for example, 80). Click the Save Changes button at the bottom of the screen. 3. Launch the Windows Services management console and stop the TransForm E-Forms Manager Server service. Now that the service has been stopped, the next step is to configure the E-Forms Manager Server. Step 2: Configure E-Forms Manager Server To configure E-Forms server, complete the following steps. 1. Navigate to the FSBServer folder of the E-Forms Manager installation. For example, navigate to [drive:]\program Files\TransForm\EFM\FSBServer. 2. Create a new folder in the FSBServer folder named webapps-efm. 3. Move the efm.war file from the webapps folder to the new webapps-efm folder. Important Make sure that you move the file and do not just copy it. The efm.war file should not be present in the webapps folder after this step. 4. Delete the efm folder and its contents from the webapps folder. 5. Delete the efm folder and its contents from the work/catalina/localhost folder. 6. Delete the efm.xml file from the conf/catalina/localhost folder. 7. Back up the server.xml file. 8. Open the server.xml file in a text editor such as WordPad. 9. Copy the Service XML element (<Service name= Catalina >) that defines the Catalina service and paste the copied content below the original Service element. 10. To edit the copied Service element, complete the following steps. 1. Change the Service name from Catalina to Catalina-efm. 2. Change the Connector port to the Form Processing application s new listen port number (for example, 80). 3. Change the Engine name from Catalina to Catalina-efm. 4. Change the appbase of the localhost Host from webapps to webapps-efm. After all of the above edits are made, the two Service elements in the server.xml file should look like the following example. 32

33 Note The Service elements in the server.xml file may look slightly different from the above example if other customizations to the file have been made. 11. Save and close the server.xml file. Step 3: Restart the E-Forms Manager Server service To restart the E-Forms Manager Server service, complete the following steps. 1. Launch the Windows Services management console and start the TransForm E-Forms Manager Server service. 2. Test the changes by opening forms from the E-Forms Manager catalog and attempting to sign or submit them. If any of the configuration settings are incorrect, you will see error messages indicating a problem connecting to the server. Step 4: Update bookmarks to the published forms list page After you have tested and verified the port changes, the last step is to update any bookmarks or links to the Published Forms List Page that is provided by E-Forms Manager. Also, any bookmarks or links that allow a user to download or view a form directly from the E-Forms Manager catalog using its Published URL need to be updated. Simply change the port number of these bookmarks or links, if any, to the new port. Run E-Forms Manager behind a reverse proxy A typical use of E-Forms Manager in a reverse proxy setting appears as in the following example. 33

34 This example depicts an organization, acme.com, with a proxy-enabled web server exposed to the internet on port 8080 or 443, if not both. In this example, an E-Forms Manager server is running behind the firewall on a host not directly exposed to the internet and using default settings, including a default HTTP listen port of E-Forms Manager s form publication settings, however, specify a host name, protocol, and port that match those of the reverse proxy server. Protocol. HTTP (HTTPS if the reverse proxy server is SSL-enabled) Host Name. Port. 80 (443 if the reverse proxy server is SSL-enabled) After setting up a reverse proxy server and enabling the appropriate configurations for this type of routing, complete the following procedure in the E-Forms Manager console. This enables the end users to communicate with E-Forms Manager through the proxy to obtain forms and for these forms to communicate with the E-Forms Manager server. 1. Launch the E-Forms Manager Console and log in using an account with administrative privileges. Go to the Administration section of the console and select the Form Publication menu item. 2. In the Form Publication screen, change the value in the Server Protocol field to match the protocol used by the reverse proxy server to handle client requests. 3. Change the value in the Host Name field to match the host name that clients will use to communicate through the reverse proxy server. For example, enter 4. Change the Port value to match the reverse proxy server listen port number. 34

35 5. Click the Save Changes button at the bottom of the screen. 6. Test your changes by opening forms from the E-Forms Manager catalog and attempting to sign or submit them. If any of the configuration settings are incorrect, you will see error messages indicating a problem connecting to the server. Configure SSL support on E-Forms Manager Server Another option for providing access to E-Forms Manager in an encrypted mode, if the reverse proxy option is not available, is that of running E-Forms Manager s own HTTP server process as an SSL server. This involves the following steps. Obtaining an SSL certificate. Placing the certificate in a key store that is accessible to the server. Configuring the HTTP engine to use the certificate to encrypt communications. Setting form publication properties to use the secure protocol and port. Obtain an SSL certificate The HTTP server software on which E-Forms Manager runs is a Java-based servlet/jsp engine. This type of server uses a specific type of SSL certificate to encrypt its communications with client browsers. All of the Certificate Authorities (CA) that issue digital certificates provide this type but it is important when requesting the certificate that you specify the type of tool that was used to generate the request. If this is done properly, the correct type of certificate can be issued. The following steps give examples of the specific types of information to provide. You should perform all of the procedures in this section on the server on which E-Forms Manager is installed. These procedures involve the use of a Java utility called keytool, which is included with the E- Forms Manager installation in the FSBServer\jre1.6.0_16\bin folder relative to the folder in which E-Forms Manager was installed. These procedures are performed using a set of scripts also provided with the E- Forms Manager installation, located in the utilities\ssl folder located directly under the E-Forms Manager installation location. The default location is C:\Program Files\TransForm\EFM\utilities\ssl. You should run these scripts from this directory to work properly. To obtain an SSL certificate, complete the following procedures in the order listed. 1. Generate a local certificate 2. Generate a certificate signing request 3. Submit the certificate signing request to a CA 4. Import the root certificate 5. Import the intermediate certification 6. Import the server certificate Step 1: Generate a local certificate This procedure generates a local certificate store and certificate that is used to create a request for an SSL certificate from a certificate authority. 1. Open the file env-settings.bat file in a text editor, such as Notepad. Change the value associated with the EFM_HOSTNAME variable to the fully qualified host name of the E-Forms Manager server. 35

36 The host name value should match a DNS name that points to the server (either public or private) and will be the name to which the SSL certificate is registered. Example set EFM_HOSTNAME=eforms.acme.com In release 7.5 of E-Forms Manager, an additional variable, EFM_KEYSIZE, was added to the envsettings.bat file. To generate a certificate request with a key size other than the default size of 1024 bit, change the value associated with the EFM_KEYSIZE variable to the desired key size. Example set EFM_KEYSIZE=2048 After you ve changed the EFM_HOSTNAME value and optionally the EFM_KEYSIZE value, save and close the file. 2. Open a command prompt and navigate to the utilities\ssl directory under the E-Forms Manager installation location. Run the script 01-local-cert.bat from the command prompt. 3. When prompted for the keystore password, enter a value that you will use in subsequent steps as the password to your new certificate store. Important Be sure to remember or write down this password, as it will be required in subsequent steps and by your server configuration. After you enter the password, you are prompted with several other questions described below. 1. What is your first and last name? Enter the host name of your server. This should match exactly the value that you specified for EFM_HOSTNAME in the first step of this procedure. For example, enter server1.acme.com. 2. What is the name of your organizational unit? Enter a value that reflects your department or role. For example, you could enter Information Technology. 3. What is the name of your organization? Enter your organization name. For example, you could enter Acme Corporation. 4. What is the name of your City or Locality? Enter the city portion of your organization s address. 5. What is the name of your State or Province? Enter the state portion of your organization s address. 6. What is the two-letter country code for this unit? Enter US if you are in the United States. 7. When prompted, verify that what you entered is correct. Type yes after the prompt and press ENTER. You are then prompted for your keystore password. Enter the value that you specified above and press ENTER. At the completion of the steps above, a file called efmkeystore.jks is created in the utilities\ssl directory. This file contains a digital certificate that was generated using the information you entered. The next set of steps uses this key store file to generate a Certificate Signing Request (CSR) that must be provided to a Certificate Authority (CA) who can provide back a signed digital certificate. 36

37 Step 2: Generate a certificate signing request Now that you have created a certificate named as your server s host name, you must generate a signing request that can be used by a certificate authority (CA) to sign your new certificate. To do this, complete the following step. From the command prompt, run the 02-create-csr.bat script. This creates a file called certreq.csr and places it into the current directory. This file is used to send to the CA to get a set of signed certificates back. Note The script in this step also creates a certs subdirectory, which is used in subsequent steps to hold certificate files once received back from the CA. Step 3: Submit the certificate signing request to a CA This step involves submitting the certificate request that was created in previous step and giving it to a CA to be signed. Each CA has a different set of steps for providing SSL certificates; options and costs vary among them. Before proceeding with these steps, you should decide which CA you want to use. 1. Go to the web site of the certificate authority you plan to use. 2. Open the certificate request (certreq.csr) that you created in the previous step in Notepad or another text editor. 3. When the CA site asks you for the certificate request, copy the contents of the CSR file from the editor to the clipboard and paste them into the appropriate text field in the CA website. 4. Provide all of the other information requested by the CA. 5. If prompted for the type of tool or software that was used to generate the certificate request, select "Java / Sun Microsystems" or the option that most closely matches this. If nothing matches and only Microsoft and Apache appear in the list, you should be able to select an option stating that your server type does not appear in the list. 6. If asked to provide information on what the certificate will be used for, select Web Server or Intranet. 7. When the CA interface displays the name of the certificate and the host with which it will be registered, ensure that the information is correct and matches the DNS or host name of the server on which it will be installed. 8. Wait for your certificates to be returned from the CA. You will likely receive a zip file that contains several files, or an with links to certificate text or files, including the following components. A root CA certificate One or more intermediate certificates A signed certificate specifically for your server 9. Follow the instructions provided by the CA to obtain the root, intermediate, and server certificates. Place the certificate files (unzipping them if necessary) into the utilities\ssl\certs directory. During the next set of steps, you will import the certificates into the key store you generated previously. Import the certificate to the key store Now that you have a signed certificate in X.509 format, you need to import the certificate and its associated root and intermediate certificates into the key store that you generated in the steps above. To do this, complete the following steps. 37

38 Step 4: Import the root certificate To import the root certificate, complete the following steps. 1. From the command prompt, with the current directory set to utilities\ssl as in the prior steps, run the 03-import-root-cert.bat script, passing, as a parameter, the name of the file in the certs directory containing the root certificate received from the CA. Example 03-import-root-cert.bat verisign-root-cert.cer.crt 2. When prompted for the keystore password, enter the password you specified when generating the original certificate for signing. Example Enter keystore password: mypass 3. When prompted as to whether or not to trust the certificate, type yes and press ENTER. Example Trust this certificate? [no]: yes You should see this message: Certificate was added to keystore. Step 5: Import the intermediate certificate This step imports the intermediate certificates received from the CA into the key store (some provide more than one intermediate certificate). 1. Run the 04-import-inter-cert.bat script for each intermediate certificate received from the CA. This script takes two parameters. The name of the intermediate certificate file (found in the certs directory) An alias for the certificate so that it can be referenced in the keystore, for example, INTER1. Provide a different alias each time you run this command. An example of the two calls made when using a certificate received from PositiveSSL would be similar to the following example. 04-import-inter-cert.bat PositiveSSLCA.crt INTER1 04-import-inter-cert.bat UTNAddTrustServerCA.crt INTER2 2. When prompted for the keystore password, enter the password you specified when generating the original certificate for signing. Example Enter keystore password: mypass 3. If prompted as to whether or not to trust the certificate, type yes and press ENTER. Example Trust this certificate? [no]: yes You should see the message: Certificate was added to keystore 38

39 Step 6: Import the server certificate The final step in creating the certificate store imports the certificate you generated at the beginning of this process, which has been signed by a CA, into the key store. 1. From the command prompt, run the 05-import-server-cert.bat script, passing, as a parameter, the file name of the server certificate received from the CA, which should be located in the certs directory. Example 05-import-server-cert.bat server1_acme_com.crt 2. When prompted for the keystore password, enter the password you specified when generating the original certificate for signing. Example Enter keystore password: mypass You should see this message: Certificate reply was installed in keystore The generation of the certificate store is now complete. It is contained in the file named efmkeystore.jks, which is in the directory from which the scripts above were run. Update the E-Forms Manager Server configuration At this point, the new server certificate, along with the required intermediate and CA certificates that it references, are all present in the keystore file efmkeystore.jks. The final remaining task is to update the E- Forms Manager server configuration to make it listen on the standard SSL port (443) and reference this keystore so that its certificates may be used in encrypting communications. Note If another web server (for example, IIS) is running on the same machine as E-Forms Manager and is listening on port 443, then E-Forms Manager will fail to start correctly due to the port conflict. If you want to have E-Forms Manager listen on the standard SSL port 443, you must first make sure that no other process is using this port. The E-Forms Manager installation contains a sample server configuration file called server-sslsample.xml, which is located in the FSBServer\conf folder of the E-Forms Manager installation. The server settings used to reference the keystore and to run the server as an SSL server are contained in this file. The settings used by the E-Forms Manager server are located in the file server.xml, located in the same folder. To back up and modify this configuration file, using a configuration portion of the example file and setting specific to your environment, complete the following steps. 1. Create a directory on the server to hold the trusted certificate store, such as [drive:]\ \TransForm\Certificates. 2. Copy or move the efmkeystore.jks file that was created in the previous set of steps into this directory. 3. Stop E-Forms Manager Server (if it is running) by stopping the Windows service called TransForm E- Forms Manager Server. Refer to the Start and stop services section for more information. 4. Make a backup copy of the server.xml file by copying and renaming the copy in the same directory or by copying it off to another location. 5. Open the server.xml file in Notepad or another text editor. 6. Open the server-ssl-sample.xml file in Notepad or another text editor. 39

40 7. Copy the Connector element from the server-ssl-sample.xml file (as in the below examples) and replace the existing Connector element in the server.xml file, for example, <Connector port= 8080 />, with the copied content. Refer to one of the following examples. Versions prior to 8.10 Versions 8.10 or higher 8. Edit the Connector element of the server.xml file to make it reference the keystore you created by making the following changes. 1. Replace the token KEYSTORE_LOCATION with the full path to the folder containing the efmkeystore.jks file. Example keystorefile="c:/transform/certificates/efmkeystore.jks" 2. Replace the token KEYSTORE_PASSWORD with the password you assigned to the key store when generating it. Use keypass= mypass for versions prior to 8.10 and keystorepass= mypass for versions 8.10 and higher. Examples The Connector element of the server.xml file should look similar to the below examples, except for your keystore path and password. Versions prior to 8.10 Versions 8.10 or later 40

41 9. Save and close the server.xml file. 10. If Perceptive TransForm ifiller is installed on this same server, the following steps are required to ensure ifiller is available under SSL for versions prior to If ifiller is not installed on this server, or for versions 8.12 and higher, skip this step. 1. Open the FSBServer\conf\wrapper.conf file in Notepad or another text editor (create a backup copy first). 2. Edit the wrapper.conf file, adding a line at the end of the section labeled Java Additional Parameters that resembles the following example. wrapper.java.additional.5=- Djavax.net.ssl.trustStore=C:/TransForm/Certificates/efmkeystore.jks To add this new line to the file, you may find it helpful to copy the one above it, which starts with wrapper.java.additional.4=, then paste it below and edit it. When doing so, remember to change the parameter name to use an index of 5 instead of 4. Specify the full path to the efmkeystore.jks file; use forward slashes instead of backslashes to separate directory names. 3. Optional. If you use the TransForm product with the eauthorize integration, you must ensure that you update the configuration to support TLS1.2. Add an additional line at the end of the section labeled Java Additional Parameters that resembles the following example. wrapper.java.additional.6=-dhttps.protocols=tlsv1,tlsv1.1,tlsv Save and close the wrapper.conf file. 11. Complete the following steps for versions 8.12 and higher. 1. Browse to the FSBServer\bin directory and double-click FormattaEFMServer.exe. A dialog appears that allows you to edit the server properties. 2. On the Java tab, under Java Options, add the following text on a separate line after the last option. -Djavax.net.ssl.trustStore=C:/Formatta/Certificates/efmkeystore.jks 3. Specify the full path to the efmkeystore.jks file, and use forward slashes instead of backslashes to separate folder names. 41

42 4. Optional. If you use the TransForm product with the eauthorize integration, you must ensure that you update the configuration to support TLS1.2. Add an additional line after the efmkeystore.jks entry that resembles the following example. -Dhttps.protocols=TLSv1,TLSv1.1,TLSv Click Apply and then click OK to close the dialog box. 12. Start the E-Forms Manager Server service. Update form publication properties Finally, you must update the Form Publication Settings in E-Forms Manager to reflect the fact that it is now accepting requests over an SSL connection. To do this, complete the following steps. 1. Log in to the E-Forms Manager Console as a user with administrative privileges. Note Since the server s listen port and protocol have changed, the desktop and start menu shortcuts on the server need to be changed to reach the console application. Refer to the instructions on editing these shortcut properties in the Changed the E-Forms Manager listen port section. 2. Go to the Administration section of the console and click the Form Publication menu item. 3. In the Form Publication screen, change the value in the Server Protocol to HTTPS. 4. Change the value in the Host Name field to match the fully qualified host name for the server, which should match exactly the name used when generating the certificate. 5. Change the Port value to

43 6. Click the Save Changes button at the bottom of the screen. Maintain E-Forms Manager The information in this section only applies to E-Forms Manager systems that are configured to use its embedded database as its data repository. If your E-Forms Manager system is using an external database instead, the information in this section will not apply to your installation. Data file maintenance Under its default configuration, E-Forms Manager relies on an embedded database engine whose storage resides in files under the E-Forms Manager installation. These data files contain most of the data and configurations used by the application, including the form catalog, submitted and signed forms, and all the elements and settings defined in the Administrative area of the E-Forms Manager console. Although E-Forms Manager provides all of the necessary access to the data contained in this database through its own interfaces and operations, it is essential that the database be backed up regularly. It is also highly recommended that aging submissions and signature records, which contain data, and the submitted and signed documents, be archived and removed periodically to keep the database files from growing to an unwieldy size. The E-Forms Manager console allows you to create scheduled routines that let the system automatically perform these maintenance operations on a regular basis. Create a database backup routine One of the first things you should do after installing E-Forms Manager is to create a schedule database backup. The backup process, once defined, creates a hot backup of the E-Forms Manager embedded database so that the application does not have to be stopped while backups are run. This process essentially makes a copy of the application s data files to a folder location you can specify, allowing them to be stored away and used for recovery purposes. The data file set consists of two files named fsbs.db and fsbs.log. To create a scheduled backup routine, complete the following steps. 1. Log into the E-Forms Manager Console, go to the Administration area, and click the DB Backup menu option. This opens the Database Backup screen. 2. Click the Edit button to configure a scheduled backup. 43

44 3. On this screen, enter the following information. Backup Destination. Enter an absolute path to a directory in which to store the backed up database files. The path you specify may be a local drive, mapped or shared drive, or a UNC path. The location you specify must allow file sizes as large as your existing E-Forms Manager database files. Schedule Type. Select the frequency on which the backup routine should run. Options are Daily, Weekly, and Monthly. If you select Weekly, you may specify one or more days of the week on which to run the backup. If you select Monthly, you can specify a particular day of the month. Start Time. Set the time of day at which the routine is to begin. Enabled. Select this option to enable the routine. 4. Click the Save button when you have entered the settings. The system verifies the path you chose and, if it is valid, the window closes and the settings are saved. 5. At any time, you can initiate the backup routine manually by clicking the Run Backup Now button. You can check the status of the routine and past jobs by clicking the View Log button. Restore from a backup If the E-Forms Manager system should have to be restored or rebuilt and you have copies of the data files from a prior backup, you can follow the steps below to associate them with your E-Forms Manager Server. If the E-Forms Manager software needs to be reinstalled, complete the following steps to perform an installation of the software. 1. Stop the E-Forms Manager Services if they are running. Make sure that you stop both the TransForm E-Forms Manager Server service and the TransForm_EFM_DB service. 2. Copy the backed up data files (fsbs.db and fsbs.log) into the asa\win32\data folder relative to the E- Forms Manager installation location. If you do not want to overwrite the existing ones, save them off first. 3. Start the TransForm_EFM_DB service and the TransForm E-Forms Manager Server service. At this point, E-Forms Manager is running using the data from the backup. 44

45 Uninstall E-Forms Manager To perform a complete uninstall of the E-Forms Manager software and services, use the following procedure. Important If configured to use the embedded database as its data repository, the E-Forms Manager installation includes a set of data files that contain most of the application and configuration data including the form catalog. These files are automatically removed when E-Forms Manager is uninstalled. If you want to keep a copy of this information for use on another system, be sure to save a backup copy of these files first to another location. For information on how to do this, refer to the Data file maintenance section. After you have backed up any wanted files and are ready to uninstall E-Forms Manager, complete the following steps. 1. Stop the E-Forms Manager related Windows services. For instructions on how to do this, refer to the Start and stop services section of this guide. 2. Open the Windows Add or Remove Programs control panel (Control Panel > Add or Remove Programs). 3. In the list of programs, locate Perceptive TransForm E-Forms Manager (followed by a version number) and click the Change/Remove button. 4. A wizard opens to begin the uninstall process. On the first screen, select the Automatic option and click the Next button. The uninstall process begins and may take several minutes as it stops services, deregisters the software and services, and removes files. You are notified when it is complete and may be prompted to reboot the system. Next, you need to ensure that it has been uninstalled completely. 5. Go back to Services and refresh the Services list to make sure that both of the E-Forms Manager related services were removed. If the TransForm E-Forms Manager Server service still exists, open a command prompt and run the following command. sc delete TransForm E-Forms Manager Server 6. Refresh the services list and ensure that it no longer exists. If the TransForm_EFM_DB service still exists, open a command prompt and run the following command. sc delete ASANYe_FEM-ASA Refresh the services list and ensure that it no longer exists. 7. Check the file system for prior installed E-Forms Manager software and delete any remaining files or directories that exist there. The standard location is [drive:]\program Files\TransForm\EFM. Troubleshooting The following section provides an overview of the most common issues that occur when installing TransForm. For additional information, refer to the TransForm documentation. Requested resource not available error If you receive the following error once the E-Forms Manager is installed, ensure that the TransForm E- Forms Manger Server and the TransForm_EFM_DB services are running. If either fails to start after manually starting, uninstall and re-install the software. 45

46 TransForm has an internal Tomcat instance that conflicts with previous Tomcat instances that use port Refer to Change the E-Forms Manager HTTP listen port. After the previous settings are complete, edit the E-Forms Manager URL in the ifiller properties file to match the new connector port number. The properties file is located here at [drive:]\program Files\TransForm\EFM\FSBServer\conf\ifller.properties. Connection issues using a proxy server If you have connection issues using a proxy server, complete the following steps. 1. Make sure the TransForm EFM setup installer is at a minimum version Stop the TransForm E-Forms Manager Server service. 3. Browse to the TransForm\EFM\FSBServer\conf folder in the TransForm installation folder. 4. Open the efm.properties file. 5. Follow the instructions in the Proxy Settings section and provide the appropriate values for the proxy server. Specifically, you should complete the following substeps. 1. Uncomment http.proxyhost and http.proxyport and provide the appropriate values. 2. Uncomment http.nonproxyhosts and add additional hosts, if any, that should be reached directly and bypass the proxy server. 3. If the proxy server requires authentication, uncomment http.proxyuser and http.proxypassword and provide the appropriate values. 6. Save and close the efm.properties file. 7. Start the TransForm E-Forms Manager Server service. 46