Perceptive TransForm E-Forms Manager 8.x. Installation and Configuration Guide March 1, 2012

Transcription

1 Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide March 1, 2012

2 Table of Contents 1 Introduction Intended Audience Related Resources and Documentation Conventions Used in this Guide Before You Install Overview System Requirements Administrative Rights Installing E-Forms Manager Installation Process Completing the Installation Upgrading E-Forms Manager Upgrade Process Completing the Upgrade Licensing E-Forms Manager Obtaining an Evaluation or Permanent License Applying the License Setting Up an External E-Forms Manager Database Overview Before You Begin Creating a new EFM Data Repository Migrating an existing EFM Data Repository Post-Configuration Configuring E-Forms Manager Server E-Forms Manager Configuration Files Starting and Stopping Services Changing the E-Forms Manager HTTP Listen Port Running the Administration Console and the E-Form Processing Engine on Separate Ports Running E-Forms Manager Behind a Reverse Proxy Configuring SSL support on E-Forms Manager Server Maintaining E-Forms Manager Data File Maintenance Uninstalling E-Forms Manager Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 2

3 1 Introduction The purpose of this guide is to provide instructions on how to install and configure the Perceptive TransForm E-Forms Manager software. 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 important ways in which you can customize configuration settings in order to conform to your environment requirements. From time to time, Perceptive Software releases upgrades and new versions of Perceptive TransForm E-Forms Manager and other software. So before using these instructions, make sure 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, please contact your Perceptive TransForm representative. 1.1 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. 1.2 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. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 3

4 1.3 Conventions Used in this Guide Within this guide you may find symbols that are meant to call special attention to noteworthy information, or text formatted in such a way as to indicate the type of information represented in the text. Special Notices Special notices are signified using the following conventions: NOTE Used for information that is of special significance or importance in the context of the subject matter being described. IMPORTANT Information associated with this symbol should be understood as especially significant in relation to the proper operation of the software. CAUTION A Caution notice may provide information essential to avoiding data loss or corruption, or damage to the system. STOP This may be found in the context of step-by-step instructions and will describe a situation in which you should discontinue the steps and perform some other type of operation. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 4

5 Fonts and Text Formatting The special typographical conventions described below are used within this guide: Bold: Italic: Courier: Indicates: Specific applications, programs, utilities, or services Text or other elements seen on user interfaces Text to be typed, viewed, or clicked on by a user Indicates: Titles of documentation or other publications Emphasis Token or variable names Indicates: Log file or console output File system paths File names URLs and hyperlinks Text file contents or snippets detailing configuration settings Examples of programming code or scripting Courier Bold: Indicates: Commands or other text provided as input by a user Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 5

6 2 Before You Install 2.1 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. As allowed by the installer, the Next button allows you to proceed to the next page, while the Back button allows you to return to the previous page. You can cancel the installation by clicking Cancel, however some parts of the installation cannot be canceled immediately and must complete before the rest of the installation can be exited. 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 will deploy the necessary software onto the system to a drive 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 can be adjusted or customized 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. CAUTION 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 will damage the ifiller Standalone installation. For more information on ifiller installation and configuration options, see the Perceptive TransForm ifiller 1.x Installation and Configuration Guide. Before running the installer, be sure that the computer on which you intend to install E- Forms Manager meets the requirements outlined in the next section. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 6

7 2.2 System Requirements For proper operation of the E-Forms Manager server application and for a proper user experience, the server and client systems should meet the requirements below: Server Minimum Recommended Operating System Windows 7 Professional (32-bit, Windows Server bit) Windows XP Professional SP 3 Windows Server 2008 (32- bit,64-bit) Windows Server 2003 R2 SP2 (32-bit,64-bit) Processor Intel Pentium 4, 2GHz Intel Core Duo, 2GHz Memory 1 GB of RAM 2 GB of RAM Hard Drive Space 500 MB 15 GB Client Client Software Browsers Supported by the E-Forms Manager User Interface Other Required Software Supported Vendor / Version Internet Explorer 7 and higher Mozilla Firefox 3.x and higher Safari 4 and higher Chrome 12 and higher Perceptive TransForm Filler 7.0 is needed to register the software after installation. A free copy can be installed along with E-Forms Manager. Perceptive TransForm Designer 7.0 is required to create E-Forms. A free evaluation copy may be installed with E-Forms Manager. 2.3 Administrative Rights A Windows user with administrative rights on the computer is needed to perform the installation and configuration steps in this guide. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 7

8 3 Installing 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 Upgrading 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. See the section Uninstalling E-Forms Manager for details. 3.1 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 will be launched to begin the installation process. Click the Next button to continue. 5. The Perceptive TransForm E-Forms Manager End User License Agreement screen will appear. Read the license agreement. If you accept the terms of the license agreement, check the I Accept box and click the Next button. 6. After accepting the license agreement the next screen allows you to choose a folder into which the E-Forms Manager software will be installed. By default, E- Forms Manager installs into the C:\Program Files\TransForm\EFM folder, however you can choose a different location by clicking the Browse button and choosing a folder. Once you have selected a destination folder or want to install into the default location, click the Next button. 7. Next, you can choose optional components to install with E-Forms Manager. Choose any of the optional components you wish to install and click the Next button. Each optional component is described below. The optional components available for installation are: o 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. Designer does not need to be installed on the same computer as E-Forms Manager; however, Designer will need to be installed in your organization in order to create and design e-forms. A Perceptive TransForm Designer specific installer exists that can be run to Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 8

9 install Designer on a different computer if you choose not to install Designer along with E-Forms Manager. o 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 so it is recommended that Filler is installed along with E-Forms Manager. NOTE Perceptive TransForm Filler will automatically be installed when Perceptive TransForm Designer is installed so you will not be prompted to install Filler separately if you chose to install Designer. o o 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. Choosing this option will 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 can be used when designing 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 can be used in designing e-forms that will be managed by E-Forms Manager. These e-form objects can be used in e-forms to enable E-Forms Manager related functionality such as submission, signing, Autofill, and Workflow Status. If you choose this option, the catalog is deployed 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 will begin installing E-Forms Manager. Part of the process installs a Java Runtime Environment (JRE) that is used to run E-Forms Manager. A notification will appear on the screen when the JRE installation begins (it may take a few minutes to complete). NOTE The JRE that is installed will only be used by E-Forms Manager and will not affect any other programs on the computer that depends on a Java Runtime Environment. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 9

10 9. After the E-Forms Manager related components and services have been installed, the installer for Designer or Filler will run if you chose to install them. Follow the wizards and prompts related to those installations. 10. When all of the installation tasks have been completed, you will be prompted to create an administrator account for E-Forms Manager. This account will be used to initially log into the E-Forms Manager console and perform 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, it is recommended 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. It is recommended that you use a combination of letters, numbers, and special characters to create a strong password. The Next button will be enabled once the value in the Password field and Confirm Password field match. Click the Next button to continue. 11. The installer will start E-Forms Manager in the background and you will be prompted as to whether you want to access the administration console. Choose Launch the Administration Console Now and click the Finish button in order 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 choose Finish setup without launching the Administration console instead. Shortcuts to the console have been placed on the Desktop and in the Start Menu, so you may use those to access the console later. 3.2 Completing the Installation At this point, E-Forms Manager is installed and running, and is configured to use its embedded database for storage of form catalog and other data. If you intend to use an external SQL Server or Oracle database instead, then you should: 1. Proceed to the section on Setting Up an External E-Forms Manager Database and follow the instructions for creating a new EFM repository. 2. Follow the steps to License E-Forms Manager. If you intend to use E-Forms Manager s embedded database, then you may immediately proceed to the section on Licensing E-Forms Manager. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 10

11 4 Upgrading E-Forms Manager This section describes how to upgrade an older version of E-Forms Manager to the current version. 4.1 Upgrade Process To upgrade 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 Starting and Stopping Services section of this guide. 2. Close any open programs. 3. If you have not done so already, download the E-Forms Manager Windows Installer program. 4. Run the setup program (TransForm-EFM-8.x-Setup.exe). 5. A wizard will be launched to begin the upgrade process. Click the Next button to continue. 6. The Perceptive TransForm E-Forms Manager End User License Agreement screen will appear. Read the license agreement. If you accept the terms of the license agreement, check the I Accept box and click the Next button. 7. After accepting the license agreement the next screen notifies you that an existing of E-Forms Manager has been detected and asks you to confirm that you wish to upgrade it to the current version. To continue with the upgrade, check the Upgrade box and click the Next button. STOP At this point, if you do not see the Installation Found screen above, then the installer does not detect an existing installation of E-Forms Manager on the computer and a new installation will be performed. Unless you want to begin a new installation, exit the installation process by clicking the Cancel button. 8. Next, you can choose optional components to install with E-Forms Manager. Choose any of the optional components you wish to install and click the Next button. Each optional component is described below. The optional components available for installation are: o 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 E-Forms Manager 8.x Installation and Configuration Guide Page 11

12 o 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 in order to avoid losing any customizations that may have been made to the existing installations. o o 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. Choosing this option will 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 get 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 can be used when designing 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 can be used in designing e-forms that will be managed by E-Forms Manager. These e-form objects can be used in e-forms to enable E-Forms Manager related functionality such as submission, signing, Autofill, and Workflow Status. If you choose this option, the catalog is deployed 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. 9. The next screen displays the Destination Folder and allows you to begin the upgrade. The upgraded version of E-Forms Manager will be installed to the same folder as the prior version so the Destination Folder cannot be changed. Click the Next button to begin upgrading E-Forms Manager. At this point the installer will begin upgrading E-Forms Manager. Part of the upgrade process will also upgrade the Java Runtime Environment (JRE) that is used to run E-Forms Manager. A notification will appear on the screen when the JRE upgrade begins (it may take a few minutes to complete). NOTE The JRE that is installed will only be used by E-Forms Manager and will not affect any other programs on the computer that depends on a Java Runtime Environment. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 12

13 10. Next, a program will be launched that will check the E-Forms Manager database to make sure that it s structure is compatible with this version of E-Forms Manager. If the database structure is incompatible, this program will upgrade the database to the structure that is needed by this version of E-Forms Manager. Click the Start button in order to begin the database compatibility check and upgrade. As the database check and upgrade occurs, information related to the current status of the upgrade will be displayed on the screen. The Finish button will be disabled until the database upgrade is completed. CAUTION 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 becomes 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. 11. Once the database compatibility routine is complete, the installer for Designer or Filler will run if you chose to install them. Follow the wizards and prompts related to those installations. 12. The installer will re-start E-Forms Manager in the background and you will be prompted as to whether you want to access the administration console. Choose Launch the Administration Console Now and click the Finish button in order to close the installer and launch the E-Forms Manager Administration Console. NOTE If the installation that is being upgraded has been modified so that the Administration Console and Processing Engine run on different ports, then additional steps will need to be performed to complete the upgrade. The installer will not automatically re-start E-Forms Manager. Refer to the next section titled Completing the Upgrade for the additional steps that need to be performed. 4.2 Completing 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 form catalog and other data as the prior version. If you want to change E-Forms Manager to use an external SQL Server or Oracle database instead of the embedded one, then you should proceed to the section Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 13

14 on Setting Up an External E-Forms Manager Database and follow the instructions for Migrating an Existing EFM Data Repository. Otherwise, see the Licensing E-Forms Manager section to determine whether you need to obtain an updated license. IMPORTANT When an E-Forms Manager software upgrade is performed, the server configuration file (C:\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, (i.e., custom listen ports, SSL configurations, etc.) it will be necessary to manually add these settings to the new server.xml configuration file. See the section on Configuring E-Forms Manager for detailed information on changing these settings. Upgrade of E-Forms Manager 7.2.x or later When the upgrade process needs to update the server configuration file any custom settings that were manually added to this file, (i.e., custom listen ports, SSL configurations, etc.) will be preserved Additional Steps for Installations Running Administration Console and Processing Engine on Separate Ports If prior to performing the upgrade E-Forms Manager had been configured to run the Administration Console and Processing Engine on separate ports, then the following steps need to be completed once the installer program finishes the upgrade: 1. Navigate to the FSBServer folder of the E-Forms Manager installation (e.g. C:\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 not just copy it. The efm.war file should not be present in the webapps folder after this step. 3. Delete the efm folder and its contents from the webapps-efm folder. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 14

15 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 the Administration Console can be launched. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 15

16 5 Licensing E-Forms Manager After performing a new installation of E-Forms Manager, you will need to license the software. You can immediately obtain an evaluation license so that you may begin using the software right away, then register for a permanent license that you can import once you receive it. If you upgraded from a version of E-Forms Manager that was prior to 7.2.0, you may need to obtain a new license in order to enable the use of new features such as the ifiller application add-on for browser-based access to Perceptive TransForm forms. Since you may not replace a permanent license with an evaluation license, you will need to choose the Perpetual License option in the instructions that follow to enable new features in an existing installation. If you upgraded from version or later of EFM, you will not need an updated license. 5.1 Obtaining an Evaluation or Permanent License To obtain a license for your E-Forms Manager installation: 1. Open the E-Forms Manager Administration Console by clicking on the E-Forms Manager desktop shortcut, or by choosing Start All Programs Perceptive TransForm Perceptive TransForm E-Forms Manager Administration Console from the Windows Start Menu. This will open the login page. (If you chose to start the console from the end of the installation process, you should already have the console open). 2. If this is a new installation, enter the administrator user ID and password that you provided during the installation routine. Otherwise, you may provide any E- Forms Manager login that has administrative privileges. Click the Log In button to go to the main page. 3. If this is a new installation, you will see a message at the top of the page that states that the application has not been licensed. Click the Administration icon at the right side of the screen, and from there choose the Licensing menu option. 4. On the Licensing page, click the link in the Registration section. 5. Click the Download Form button. This will open an e-form in Perceptive TransForm Filler that you will use to submit a registration and license request. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 16

17 NOTE If you do not have Perceptive TransForm Filler installed, the e- form will not open when this button is clicked. You must first obtain and install a free copy of Perceptive TransForm Filler. 6. When the e-form opens, complete the Contact Information section at the top. If you are a Perceptive TransForm partner or are evaluating or purchasing E-Forms Manager through an authorized Perceptive TransForm reseller, enter the name of the company in the Reseller / Partner field. 7. In the License Type section, specify whether you want to obtain an evaluation or a perpetual license. If you are upgrading a system with an existing perpetual license but you want to enable new features, you must choose the Perpetual option. 8. In the Annual Submission Capacity section, choose an option that represents the number of form submissions you expect to receive in this server on an annual basis. If you are choosing an Evaluation license, then the value you choose here does not matter a default capacity will be assigned to the license you receive. 9. Click the Submit License Request button at the bottom of the form. If you chose a Perpetual license, you will see a notification indicating that you will be contacted by a Perceptive TransForm representative. If you chose the Evaluation license option, then your screen in Filler will refresh immediately, and the form shown will be your license form. (You will be ed a copy of the form separately). Save the license form to your hard drive so that you can use it to import it into the system in order to activate it. For instructions on activation, follow the steps in the section below. STOP If you selected the Perpetual License option, you must wait until you receive the license before you can go on to the next set of steps which are related to applying the license to the E- Forms Manager software. 5.2 Applying the License The confirmation form you received for evaluation or permanent use of your installed E- Forms Manager application is a Perceptive TransForm form, a file with a.pff extension. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 17

18 You must save this file and upload it into the E-Forms Manager system in order to activate the software. The license confirmation form contains information about your license, including licensee information, licensed features, and annual submission capacity. After you have saved this form file, go to the License Registration screen (follow the steps above if you are not already on this screen) to apply the license. 1. On the License Registration screen, click the Import License button to open the Import License screen. 2. Click the Browse button and browse to the folder containing the saved license form. Select the saved license form from the file system. 3. Click the Import button. The license confirmation form will be uploaded into the system and will be used to enable functionality and activate features. You will then be taken back to the License Information screen, where the attributes of your license will be displayed. E-Forms Manager is now licensed. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 18

19 6 Setting Up an External E-Forms Manager Database This section provides instruction on how to set up E-Forms Manager to use an externally-managed Oracle or SQL Server database system as its data repository. 6.1 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, and 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 one 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/recovery for your E-Forms Manager system. The E-Forms Manager Data Repository Configuration (EFM DRC) utility is a program that you will 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 wish 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 will move all existing catalog, configuration, and submission data from E-Forms Manager s embedded database. The second option allows you to create a new, empty E-Forms Manager Data Repository in a supported database external to E-Forms Manager. This option will not move any existing catalog, configuration, and submission data from E-Forms Manager s embedded database, and is generally used immediately after new installations of E-Forms Manager. CAUTION Each time the EFM DRC utility is run, it drops any existing EFM Data Repository objects in the target database then recreates them. So you should only run the EFM DRC utility more than 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. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 19

20 6.2 Before You Begin Make sure the Database System is Supported The following Relational Database Management Systems (RDBMS) are supported: Microsoft SQL Server (2005 and 2008) Oracle (10g and 11g) Prepare the Database Please ensure that the database chosen for your E-Forms Manager data repository has been prepared according to the guidelines below. SQL Server 2005 and SQL Server 2008: Create or choose a SQL Server login whose default schema will contain the E-Forms Manager Data Repository. Make sure that the user is in the db_owner role. Oracle 10g and 11g: Create or choose a database user whose schema will contain the E-Forms Manager Data Repository. Make sure that this user has been granted the connect and resource roles 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 by E-Forms Manager. Follow the instructions below to install the driver that matches the database that you want to use. SQL Server 2005 and SQL Server 2008: 1. Download the latest Windows version of the Microsoft SQL Server JDBC Driver from The download consists of a self-extracting executable zip file named sqljdbc_<version>_enu.exe. 2. Run the downloaded executable to extract its contents to the Desktop or another temporary location. This will create 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 folder FSBServer\common\lib, relative to your E-Forms Manager installation. E-Forms Manager version 7.5 or later: If the SQL Server database instance that you will be connecting to requires clients to connect using Windows Authentication, the following steps should also be completed: 4. Copy the file sqljdbc_auth.dll 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. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 20

21 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. 5. Make sure that the target database has been configured to allow the computer account or user account access to it. Oracle 10g and 11g: 1. Download the latest release of the Oracle 11g JDBC driver (ojdbc5.jar) from Oracle s website - Make sure that you download the version of the driver that is for use with JDK 1.5 (ojdbc5.jar). 2. Place the file ojdbc5.jar into the folder FSBServer\common\lib, relative to your E-Forms Manager installation. Now you are ready to run the EFM DRC utility in order 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, go to the Migrating an existing EFM Data Repository section below. If you want to create a new, empty E-Forms Manager Data Repository in a supported database external to E-Forms Manager, go to the Creating a new EFM Data Repository section below. 6.3 Creating a new EFM Data Repository This section provides instruction on using the E-Forms Manager Data Repository Configuration Utility (EFM DRC) in order to create a new repository in the database you have chosen. Before you begin: Stop the E-Forms Manager Service The TransForm E-Forms Manager Server service must be stopped prior to running the EFM DRC utility. The EFM DRC utility will perform a check to be sure that the service is not currently running and will not allow a configuration to continue if the service is in a running state. For instructions on how to do this, refer to the Starting and Stopping Services section of this guide. Step 1: Configuration Options 1. Open the EFM DRC utility by choosing Start All Programs Perceptive TransForm Perceptive TransForm E-Forms Manager Data Repository Configuration from the Windows Start Menu. 2. Choose the Create a new EFM Data Repository option. Click the Next button to continue. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 21

22 Step 2: Preliminary Checks Next, the EFM DRC utility will check to make sure that the system and services are in the correct state in order for the configuration to proceed. If all of the preliminary checks succeed, a message will display stating this and allow the configuration to continue. Click the Next button to continue. If any of the checks should fail, an error message describing the failure will appear. Follow the instructions displayed to resolve the check failure so that the configuration may proceed. Step 3: Database Type Selection On the next screen you will be prompted to choose the type of database that will contain the new EFM Data Repository. Choose one of the supported database types from the drop down and click the Next button to continue. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 22

23 Step 4: Database Connection Properties Once you have chosen the database type, you will be prompted to enter the required connection properties that will be 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: Oracle Username Enter the username to be used to establish a connection to the target database that will contain the data repository. Password Enter the password of the user entered in the Username field above. Host Enter either the machine name or IP Address of the machine that hosts the target database you are configuring. Port Enter the port number on which the database is listening for TCP/IP connections. Name/SID Enter the SID of the database instance. SQL Server: Enter the name of the database. SQL Server Use Windows Authentication Check this box to use Windows Authentication to connect to the target database. Note: The additional steps related to Windows Authentication in the Prepare the Database section must be completed. Username Enter the username to be used to establish a connection to the target database that will contain the data repository. Not required if Use Windows Authentication is checked. Password Enter the password of the user entered in the Username field above. Not required if Use Windows Authentication is checked. 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 Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 23

24 Host value in the following format: ServerName\InstanceName, e.g. DBServer\SQLEXPRESS. 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. Name/SID Enter the name of the database. 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. Once you have entered all of the appropriate properties, click the Next button to continue. NOTE In addition to using these connection properties in order 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. Step 5: Database Connection Test The EFM DRC utility will use the connection properties entered in the previous step and attempt to establish a connection to the database. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 24

25 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 will display an error message. Click the Prev button to modify the connection properties (if needed) and perform the database connection test again. Step 6: Create / Migrate Repository The EFM DRC utility is now ready to create a new EFM Data Repository in the target database. Read the warning message displayed and click the Finish button to create a new EFM Data Repository. Once you have the clicked the Finish button, a progress bar will appear on the left side of the EFM DRC utility. This progress bar will display the current operation as the Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 25

26 process runs. The status window on the right hand side of the utility will also display information about the process. Step 7: Summary Once the EFM DRC utility has finished creating a new E-Forms Manager Data Repository, a summary screen will be displayed 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 Starting and Stopping Services section of this guide. If the EFM DRC utility failed to create a new E-Forms Manager Data Repository, a message stating that the process failed will be displayed 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 (e.g. C:\Program Files\TransForm\EFM\FSBServer\utilities). Once the problem has been corrected, you must run the EFM DRC utility again to create a new E-Forms Manager Data Repository. 6.4 Migrating an existing EFM Data Repository This section provides instruction on using the E-Forms Manager Data Repository Configuration Utility (EFM DRC) in order to move an existing EFM data repository from the database included with E-Forms Manager into the database you have chosen Before You Begin Before running the EFM Data Repository Configuration tool, follow the steps below. 1. Stop the TransForm E-Forms Manager Server service Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 26

27 The TransForm E-Forms Manager Server service must be stopped prior to running the EFM DRC utility. The EFM DRC utility will perform a check to be sure that the service is not currently running and will not allow a configuration to continue if the service is running. For instructions on how to stop this service, refer to the Starting and Stopping Services section of this guide. 2. Ensure 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 will check 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 Starting and Stopping Services section of this guide. 3. Backup the Existing Database (optional) 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 backup the existing embedded database. For instructions on how to backup an existing EFM Installation s embedded database see the Data File Maintenance section of this document. 4. Clean up Aging Content (optional) When migrating an existing EFM Data Repository, the EFM DRC utility will move all existing database objects and data into the new database. The length of time required to complete this task will correlate 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 see the Archival and Removal of Submitted Forms section of the E-Forms Manager online help Configuration Steps Step 1: Configuration Options 1. Open the EFM DRC utility by choosing Start All Programs Perceptive TransForm Perceptive TransForm E-Forms Manager Data Repository Configuration from the Windows Start Menu. 2. Choose the Migrate an existing EFM Data Repository option. Click the Next button to continue. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 27

28 Step 2: Preliminary Checks Next, the EFM DRC utility will check to make sure that the system and services are in the correct state in order for the configuration to proceed. If all of the preliminary checks succeed, a message will display stating this and allow the configuration to continue. Click the Next button to continue. If any of the checks should fail, an error message describing the failure will appear. Follow the instructions displayed to resolve the failure so that the configuration may proceed. Step 3: Database Type Selection Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 28

29 On the next screen you will be prompted to choose the type of database that will contain the EFM Data Repository. Choose one of the supported database types from the drop down and click the Next button to continue. Step 4: Database Connection Properties Once you have chosen the database type, you will be prompted to enter the required connection properties that will be 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: Oracle Username Enter the username to be used to establish a connection to the target database that will contain the data repository. Password Enter the password of the user entered in the Username field above. Host Enter either the machine name or IP Address of the machine that hosts the target database you are configuring. Port Enter the port number on which the database is listening for TCP/IP connections. Name/SID Enter the SID of the database instance. SQL Server Use Windows Authentication Check this box to use Windows Authentication to connect to the target database. Note: The additional steps related to Windows Authentication in the Prepare the Database section must be completed. Username Enter the username to be used to establish a connection to the target database that will contain the data repository. Not required if Use Windows Authentication is checked. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 29

30 Password Enter the password of the user entered in the Username field above. Not required if Use Windows Authentication is checked. 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, e.g. DBServer\SQLEXPRESS. 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. Name/SID Enter the name of the database. 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. Once you have entered a value for all of the properties, click the Next button to continue. NOTE In addition to using these connection properties in order 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. CAUTION Each time the EFM DRC utility runs, it drops any existing EFM Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 30

31 Data Repository objects in the target database then recreates them. So you should only run the EFM DRC utility more than 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 will use the connection properties entered in the previous step and attempt 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 will display an error message. Click the Prev button to modify the connection properties (if needed) and perform the database connection test again. Step 6: Create / Migrate Repository The EFM DRC utility is now ready to migrate the existing EFM Data Repository to the target database. Read the warning message displayed and click the Finish button to migrate the existing data repository. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 31

32 Once you have the clicked the Finish button, a progress bar will appear on the left side of the EFM DRC utility. This progress bar will display the current operation as the process runs. The status window on the right hand side of the utility will also display 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 will update the status widow every few seconds with a series of ellipses to provide a visual cue that the process is still running. CAUTION It may take between several minutes and several hours to migrate the data repository. Closing the program while the migration process is running will result in an incomplete data repository in the target database. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 32

33 Step 7: Summary Once the EFM DRC utility has finished the migration of the E-Forms Manager Data Repository, a summary screen will be displayed 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 Starting and Stopping 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 will be displayed 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 (e.g., C:\Program Files\TransForm\EFM\FSBServer\utilities). Once the problem has been corrected, you must run the EFM DRC utility again to migrate the E-Forms Manager Data Repository. 6.5 Post-Configuration This section provides instruction on some optional steps you may need to perform following a switch to an external database Manually Removing the Dependency between the E-Forms Manager Window Services Once 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 will appear in the Summary screen. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 33

34 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 will allow the Windows service that controls the embedded database to be stopped and disabled since it is no longer needed. To manually modify the TransForm E-Forms Manager Server service so that it no longer depends on the TransForm_EFM_DB service: 1. Open a DOS prompt, and navigate to the service directory of the E-Forms Manager installation (e.g. C:\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. Once the batch file runs, you can verify that the Windows services have been modified successfully 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 Restoring 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, you can follow the steps below. IMPORTANT If your EFM system has been in use with an externallymanaged Oracle or SQL Server database, any data created in the new repository will not be available once you go back to the original configuration. To reset E-Forms Manager to its original data repository configuration: 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 (e.g. C:\Program Files\TransForm\EFM\FSBServer\service). 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 Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 34

35 (e.g. C:\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 will start up automatically in step 8 above. Also, by replacing the application configuration file, server.xml, E- Forms Manager s connection settings have been restored to point to the embedded database Changing 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, follow the steps below: 1. Stop the TransForm E-Forms Manager Server service. 2. Navigate to the conf folder of the E-Forms Manager installation (e.g. C:\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. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 35

36 5. Locate the line of the file beginning with <Resource name="jdbc/sbspool". 6. If you need to change the user name for the connection, change the value associated with the username attribute to the new user name. 7. If you need to change the password: a. Open a DOS command prompt and navigate to the utilities directory under your E-Forms Manager installation, (e.g. C:\Program Files\TransForm\EFM\utilities). b. Run the EncryptPassword.bat utility, followed by the password that you want to use. For example, >EncryptPassword mypassword This will print out an encrypted version of the password you provided. Copy this encrypted password string to the clipboard. c. 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. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 36

37 7 Configuring 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 don t 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, then the E-Forms Manager server will not start properly, making it necessary to make it listen on a different port. Or 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 properly change these types of settings, as well as general guidelines on different deployment scenarios. 7.1 E-Forms Manager Configuration Files There are several configuration files that are part of the E-Forms Manager installation which are referenced in the instructions below for the various configuration changes described. The table here lists these and describes these files, and provides their locations so that the instructions that follow will 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, e.g., C:\Program Files\TransForm\EFM\. Configuration File Location Description Name 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, which 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 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. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 37

38 7.2 Starting and Stopping 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/or starting one or both of these services. To start or stop the E-Forms Manager related Windows services: 1. Launch the Windows Services management console (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 will automatically call for stopping the main E-Forms Manager service. 7.3 Changing the E-Forms Manager HTTP Listen Port E-Forms Manager contains a Tomcat Servlet engine which 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, follow the steps below: 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, then port 80 is most likely being used. If E-Forms Manager is configured to run on a port that is already in use, it will either 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 Starting and Stopping Services section of this guide. 3. Open the server.xml file in a text editor such as WordPad. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 38

39 4. If the server that E-Forms Manager is installed on already has another Tomcat server, you should change the Shutdown Port value in order 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 you want your server to run on. 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. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 39

40 6. Save and close the server.xml file. 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: 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 on this file and choose 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. Once 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: 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 choose the Form Publication menu item. The Form Publication screen will be displayed. 2. 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. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 40

41 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, you will see error messages indicating a problem connecting to the server. 7.4 Running 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. These two components of E-Forms Manager can be configured 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. Complete the following steps to change the components to run on separate ports: Step 1: Change Form Publication Settings 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 choose the Form Publication menu item. The Form Publication screen will be displayed. 2. On the Form Publication page, change the value in the Port field to the Form Processing application s new listen port number (e.g. 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 1. Navigate to the FSBServer folder of the E-Forms Manager installation (e.g. C:\Program Files\TransForm\EFM\FSBServer). 2. Create a new folder in the FSBServer folder named webapps-efm. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 41

42 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 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. Backup 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. Edit the copied Service element as follows: Change the Service name from Catalina to Catalina-efm Change the Connector port to the Form Processing application s new listen port number (e.g. 80) Change the Engine name from Catalina to Catalina-efm Change the appbase of the localhost Host from webapps to webappsefm After all of the above edits have been made the two Service elements in the server.xml file should look like the following: Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 42

43 NOTE The Service elements in the server.xml file may look slightly different than above if other customizations to the file have been made. 11. Save and close the server.xml file. Step 3: Restart E-Forms Manager Server service 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 will need to be updated. Simply change the port number of these bookmarks or links, if any, to the new port. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 43

44 7.5 Running E-Forms Manager Behind a Reverse Proxy A typical use of E-Forms Manager in a reverse proxy setting appears as follows: This example depicts an organization, acme.com, with a proxy-enabled web server exposed to the internet on port 8080 and/or 443. 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, you would do the following in the E-Forms Manager console to enable end users to communicate with E-Forms Manager through the proxy in order 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 choose the Form Publication menu item. The Form Publication screen will be displayed. 2. 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, e.g., 4. Change the Port value to match the reverse proxy server listen port number. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 44

45 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. 7.6 Configuring 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 several steps that involve: 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, and Setting form publication properties to use the secure protocol and port Obtaining 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 in order to encrypt its communications with client browsers. All of the Certificate Authorities (CA s) 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, then the correct type of certificate can be issued. The steps that follow will give examples of the specific types of information to provide. All of the steps in this section should be performed on the server on which E-Forms Manager is installed. They 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 steps 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). These scripts should be run from this directory in order to work properly. Step 1: Generate a Local Certificate Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 45

46 This step will generate a local certificate store and certificate that will be used to create a request for an SSL certificate from a certificate authority. 1. Open the file env-settings.bat in a text editor such as Notepad to edit it. Change the value associated with the EFM_HOSTNAME variable to the fully qualified host name of the E-Forms Manager server. 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. For example: set EFM_HOSTNAME=eforms.acme.com In release 7.5 of E-Forms Manager an additional variable, EFM_KEYSIZE, was added to the env-settings.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. For example: set EFM_KEYSIZE=2048 Once 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. 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 will be prompted with several other questions described below: a. 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 step 1, e.g., server1.acme.com b. What is the name of your organizational unit? Enter a value that reflects your department or role, e.g., Information Technology. c. What is the name of your organization? Enter your organization name, e.g., Acme Corporation. d. What is the name of your City or Locality? Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 46

47 Enter the city portion of your organization s address, e.g., Fairfax e. What is the name of your State or Province? Enter the state portion of your organization s address, e.g., Virginia f. What is the two-letter country code for this unit? Enter US if you are in the United States. Lastly, you will be prompted to verify that what you entered is correct. If so, type yes after the prompt and hit Enter. You will then be prompted for your keystore password. Enter the value that you specified above, and hit Enter. At the completion of the steps above, a file called efmkeystore.jks will have been 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 will use 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. 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: 1. From the command prompt, run the script 02-create-csr.bat. This will create a file called certreq.csr and place it into the current directory. This file will be 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 will be 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 Certificate Authority to be signed. Each CA has a different set of steps for providing SSL certificates, and 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 (e.g., 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. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 47

48 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, choose "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, choose Web Server or Intranet. 7. When the CA interface displays the name of the certificate and/or 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: 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. The next set of steps will have you import the certificates into the key store you generated previously Importing the Certificate to the Key Store Now that you have a signed certificate in X.509 format, you will 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, follow steps 4 through 6 below. Step 4: Import the Root Certificate From the command prompt, with the current directory set to utilities\ssl as in the prior steps, run the script 03-import-root-cert.bat, passing as a parameter the name of the file in the certs directory containing the root certificate received from the CA. For example: 03-import-root-cert.bat verisign-root-cert.cer.crt When prompted for the keystore password, enter the password you specified when generating the original certificate for signing. For example: Enter keystore password: mypass Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 48

49 When prompted as to whether or not to trust the certificate, type yes and hit Enter. For example: Trust this certificate? [no]: yes You should see the message: Certificate was added to keystore. Step 5: Import the Intermediate Certificate This step imports the intermediate certificate(s) received from the CA into the key store. (Some provide more than one intermediate certificate). Run the script 04-import-inter-cert.bat 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, e.g., 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: 04-import-inter-cert.bat PositiveSSLCA.crt INTER1 04-import-inter-cert.bat UTNAddTrustServerCA.crt INTER2 When prompted for the keystore password, enter the password you specified when generating the original certificate for signing. For example: Enter keystore password: mypass If prompted as to whether or not to trust the certificate, type yes and hit Enter. For example: Trust this certificate? [no]: yes You should see the message: Certificate was added to keystore 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. From the command prompt, run the script 05-import-server-cert.bat, passing as a parameter the file name of the server certificate received from the CA, which should be located in the certs directory. For example: 05-import-server-cert.bat server1_acme_com.crt Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 49

50 When prompted for the keystore password, enter the password you specified when generating the original certificate for signing. For example: Enter keystore password: mypass You should see the 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 Updating 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 (e.g., 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-ssl-sample.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. Following the steps below, you will back up and modify this configuration file, using a configuration portion of the example file and setting specific to your environment. 1. Create a directory on the server to hold the trusted certificate store, such as C:\ \TransForm\Certificates. 2. Copy or move the efmkeystore.jks file that was created in the previous set of steps into this directory. 3. Stop the E-Forms Manager server if it is running, by stopping the Windows service called TransForm E-Forms Manager Server. See Starting and Stopping Services for more information. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 50

51 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 server.xml in Notepad or another text editor. 6. Open the server-ssl-sample.xml file in Notepad or another text editor. 7. Copy the Connector element from server-ssl-sample.xml (circled below) and replace the existing Connector element in server.xml, e.g. <Connector port= 8080 />, with the copied content. 8. Edit the Connector element of the server.xml file to make it reference the keystore you created, by making the following changes: Replace the token KEYSTORE_LOCATION with the full path to the folder containing the efmkeystore.jks file. For example, keystorefile="c:/transform/certificates/efmkeystore.jks" Replace the token KEYSTORE_PASSWORD with the password you assigned to the key store when generating it, for example, keypass="mypass" 9. Save and close the server.xml file. 10. If Perceptive TransForm ifiller is installed on this same server, then the following steps are required to ensure ifiller is available under SSL. If ifiller is not installed on this server, then this step should be skipped. a. Open the file FSBServer\conf\wrapper.conf in Notepad or another text editor. (You should create a backup copy first). b. Edit the wrapper.conf file, adding a line at the end of the section labeled Java Additional Parameters that looks like the following: wrapper.java.additional.5=- Djavax.net.ssl.trustStore=C:/TransForm/Certificates/ef mkeystore.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. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 51

52 Specify the full path to the EFMTrustStore.jks file, and use forward slashes instead of backslashes to separate directory names. c. Save and close the wrapper.conf file. 11. Start the E-Forms Manager Server service. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 52

53 7.6.4 Updating Form Publication Properties Finally, 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: 1. Log into 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 will need to be changed in order to reach the console application. See the instructions on editing these shortcut properties in the section on Changing the E-Forms Manager Listen Port. 2. Go to the Administration section of the console and choose the Form Publication menu item. The Form Publication screen will be displayed. 3. 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 Click the Save Changes button at the bottom of the screen. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 53

54 8 Maintaining E-Forms Manager NOTE 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 Oracle or SQL Server database instead, the information in this section will not apply to your installation. 8.1 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 of 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 and. It is also highly recommended that aging submissions and signature records (which contain data and also the submitted/signed documents) be archived and removed periodically in order 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 Creating 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 that 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: 1. Log into the E-Forms Manager console, go to the Administration area, and choose the DB Backup menu option. This opens the Database Backup screen. 2. Click the Edit button to configure a scheduled backup. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 54

55 On this screen, enter the following information: Backup Destination: Enter an absolute path to a directory in which the backed-up database files will be stored. 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: Choose the frequency on which the backup routine should run. Options are Daily, Weekly, and Monthly. If you choose Weekly you may specify one or more days of the week on which to run the backup. If you choose Monthly, you can specify a particular day of the month. Start Time: Choose the time of day at which the routine to begin. Enabled: Check this box to enable the routine. Click the Save button when you have entered the settings. The system will verify the path you have chosen and if it is valid the window will be closed and the settings saved. At any time, you can initiate the backup routine manually by clicking the Run Backup Now button. You can check on the status of the routine and on past jobs by clicking on the View Log button Restoring from a Backup If the E-Forms Manager system should ever 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. Perceptive TransForm E-Forms Manager 8.x Installation and Configuration Guide Page 55