Avoka Transact Manager Installation Guide · All rights reserved. No parts of this work may be...

Installation GuideVersion 5.1.0

Avoka

Transact Manager

All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, ormechanical, including photocopying, recording, taping, or information storage and retrieval systems - without the

written permission of the publisher.

Products that are referred to in this document may be either trademarks and/or registered trademarks of therespective owners. The publisher and the author make no claim to these trademarks.

While every precaution has been taken in the preparation of this document, the publisher and the author assume noresponsibility for errors or omissions, or for damages resulting from the use of information contained in this

document or from the use of programs and source code that may accompany it. In no event shall the publisher andthe author be liable for any loss of profit or any other commercial damage caused or alleged to have been caused

directly or indirectly by this document.

Avoka Transact

Transact Manager Installation Guide

Version 5.1.0

© 2017 Avoka Technologies. All Rights Reserved.

Table of Contents

Part I Introduction 5

................................................................................................................................... 51 Who should read this document?

................................................................................................................................... 52 Planning your installation

Part II System Requirements 6

................................................................................................................................... 61 Software Requirements

................................................................................................................................... 62 Hardware Requirements

Part III Performing Installation 8

................................................................................................................................... 81 Database Server Configuration

................................................................................................................................... 142 Running the Transaction Manager Installer

................................................................................................................................... 293 Transact Manager Configuration

................................................................................................................................... 384 Apache Server Configuration

................................................................................................................................... 425 Virus Scanner Configuration

Part IV Upgrading Transact Manager 45

................................................................................................................................... 461 Back up TM Database

................................................................................................................................... 462 Upgrade TM Server Option Setup Steps

................................................................................................................................... 463 Reinstall TM Server Option Setup Steps

................................................................................................................................... 474 Updating the TM Database

................................................................................................................................... 485 Updating Apache Configuration

................................................................................................................................... 496 Finalizing and Verifying the Upgrade

................................................................................................................................... 497 Cleaning up the JDK Folder

................................................................................................................................... 498 Rollback Procedures

................................................................................................................................... 509 Upgrade Checklist

Part V Upgrading TM Version Notes 52

................................................................................................................................... 521 Version 4.0 Upgrade

................................................................................................................................... 542 Version 4.1 Upgrade

................................................................................................................................... 603 Version 4.2 Upgrade

................................................................................................................................... 624 Version 4.3 Upgrade

................................................................................................................................... 675 Version 5.0 Upgrade

................................................................................................................................... 686 Version 5.1 Upgrade

Part VI Installation Checklist 70

................................................................................................................................... 701 Install Prerequisites

................................................................................................................................... 702 Database Checklist

................................................................................................................................... 703 Transact Manager Checklist

................................................................................................................................... 714 Apache Checklist

Transact Manager Installation Guide

© 2017 Avoka Technologies. All Rights Reserved.

................................................................................................................................... 715 ClamAV Checklist

................................................................................................................................... 716 Security Checklist

IntroductionTransact Manager Installation Guide

© 2017 Avoka Technologies. All Rights Reserved. 5

1 Introduction

This document explains how to install and configure Avoka Transact Manager.

1.1 Who should read this document?

This document is intended for users who are installing, configuring, administering, or deployingTransact Manager, including evaluators, administrators, or developers.

If you are installing Transact Manager on a Microsoft Windows operation system then you should befamiliar with administering Microsoft Windows operating systems.

If you are installing Transact Manager on CentOS Linux, Oracle Linux or Red Hat Enterprise Linux or thenyou should be familiar with administering Linux operating systems.

1.2 Planning your installation

Before you get started with your installation read the planning section,

¨ Please ensure you have read this Transact Manager Installation Guide before commencing yourinstall

¨ If you are upgrading Transact Manager please follow instructions in the Upgrading TransactManager section before you commence your install

System RequirementsTransact Manager Installation Guide


2 System Requirements

This section discuss the system requirements for Transact Manager.

2.1 Software Requirements

Operating Systems

¨ Microsoft Windows Server 2012 or Windows Server 2008 R2 64 bit Edition on Intel x86-64

¨ CentOS Linux 6 on Intel x86-64

¨ Oracle Linux 6 (Unbreakable Enterprise Kernel) on Intel x86-64

¨ Red Hat Enterprise Linux Server AP 6 on Intel x86-64

Databases

¨ Microsoft SQL Server 2014 and 2012

¨ MySQL 5,7, 5.6 and 5.5 (InnoDB storage engine only)

¨ Oracle Database 12c and 11g

Additional Components

¨ Apache Web Server 2.2we recommend using the latest 2.2.x version for obtain the latest security patches

¨ SSL TLS Server certificate to enable Transact Manager over HTTPS

¨ Java SE 8u112, provided with Windows Setup Wizard, available from http://www.oracle.com/technetwork/java/javase/downloads/index.html

¨ ClamAV for Linux

¨ Symantec Scan Engine 5.2 for Windows

2.2 Hardware Requirements

Transact Application Servers

Transact Manager application runs best on the Intel x86-64 Xeon CPU architectures with high CPUperformance.

For on premise deployment we recommend server virtualization such as VMware or Microsoft Hyper-Vto provide enable better hardware utilization and improve operational support.

Recommended application server specification for Avoka Transact Manager (TM).

¨ Intel Xeon Processors 8 Cores with 2.4 GHz or greater clock speed (4 Cores minimum)

¨ 12 GB of RAM (8 GB minimum)

¨ 50 GB of local disk storage.

¨ 1 TB of shared SAN or NAS storage for shared transaction data storage of PDF receipts and fileattachments. Shared SAN or NAS storage must be highly available.

¨ IO subsystem should support 2000 IOPS or greater

Please note minimum configurations are only suitable for non-production environments or lowerenvironments not being used for performance load testing.

http://www.oracle.com/technetwork/java/javase/downloads/index.html

System RequirementsTransact Manager Installation Guide


Transact Database Servers

The database is a critical component in the Avoka Transact architecture and must provide highavailability to the application server nodes. The database server should support 2000 IOPS or greater.

Recommended database server specification for Avoka Transact Manager (TM)

¨ Intel Xeon Processors (8 Cores) with 2.4 GHz or greater clock speed

¨ 16 GB of RAM

¨ 500 GB of storage

For non production databases, a single database server may be used which supports multiple TMdatabases/schemas (UAT, Test, Dev).

Performing InstallationTransact Manager Installation Guide


3 Performing Installation

This chapter describes how to install a new Transact Manager instance.

Please Note: If you are upgrading an already existing Transact Manager instance, please follow theinstructions in the Upgrading Transact Manager section only.

3.1 Database Server Configuration

The first step in performing a Transact Manager installation is to create a database schema which willmanage the system's configuration, transaction and reporting data.

MySQL Configuration

Configure Binary Storage

Ensure MySQL server is configured to enable storage of large binary files in the database by followingthe steps below.

1. Stop the MySQL database.

2. Edit the MySQL configuration file, e.g.

$MYSQL/my.cnf or $MYSQL\my.ini

3. Enable the “Max. packet size” option and set the maximum packet size to 100 M to enable large BLOB

records to be stored in the database.

Set the start up parameter:

max_allowed_packet=100M

4. For MySQL version 5.6 databases, add the InnoDB log file size start up parameter:

innodb_log_file_size=1G

5. Restart the MySQL database to apply this change

Create Database

Please Note: the following instructions are for using mysql.

1. Login to mysql as the root user:

mysql -u root -p

2. Create a user named "txmanager":

CREATE USER 'txmanager'@'localhost' IDENTIFIED BY 'password';

Please note you should use a hardened password, and make a note of it, as you will need it whenrunning the Transact Manager installer.



3. Create a database named "txmanager":

CREATE SCHEMA `txmanager` DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci;

4. Grant database privileges to the txmanager user:

GRANT ALL PRIVILEGES ON txmanager.* TO 'txmanager'@'localhost' IDENTIFIED BY 'password';FLUSH PRIVILEGES;

Creating Tables

Later in the Transact Manager installer you will be provided the option to automatically create thedatabase tables. If you do not want to use this option and would rather create the tables manually thendo the following after running the Transact Manager installer:

Execute the table create SQL script:

mysql -u txmanager -p txmanager < [TM install folder]/sql/setup-db-mysql.sql

SQL Server Configuration

Configure TCP/IP Connectivity

The Transact Manager server connects to the SQL Server database using JDBC drivers which use TCP/IPprotocol. By default TCP/IP is not enabled on the Microsoft SQL Server 2005, 2008 and 2012 databases.Follow the steps below to enable TCP/IP connectivity:

Enable TCP/IP with SQL Server Configuration Manager

1. On the SQL server machine start SQL Server Configuration Manager.

2. Navigate to the SQL Server Network Configuration item, double click on the protocol named "TCP/IP" and change the setting to "Enabled". Apply your changes.

3. Navigate to the "IP Addresses" tab and scroll down to the TCP Port. The default value is 1433, whichwill be used in the Transact Manager installer when setting up the database connectionconfiguration. If you have configured an TCP Port other than 1433, please take a note of it so you canuse it later in the Transact Manager installer.



SQL Server TCP port configuration

Create Database

1. Log into the Microsoft SQL Server Management Studio as sa the admin user

2. Create a new database with the name txmanager and with the Owner sa.

SQL Server database schema creation

3. Go to the "Options" tab and adjust the database collation if necessary. Note: The collation should bein line with the language(s) that will be used in TM portals and forms. For example, for WesternEuropean languages the Latin1 collation should be used. You can check what collation the SQL serverinstance is set to by right clicking on the instance in Management Studio and selecting "Properties".



Setting the database collation

4. Create a txmanager user via Security > Logins.

SQL Server authentication, Login name: txmanager,No password policy, Default database: txmanager



SQL Server user creation

Make a note of the password; it will be needed when running the Transact Manager installer

5. Associate new user login with database. Databases > txmanager > Security > Users.

User name: txmanager Login name: txmanagerDefault schema: dbo Role Members: db_owner



Configuring role membership

Creating Tables

Later in the Transact Manager installer you will be provided the option to automatically create thedatabase tables. If you would rather create the tables manually do the following after running theTransact Manager installer:

1. Log into the Microsoft SQL Server Management Studio as txmanager

2.Open a new query window and execute the script contained in the file

[TM artefact folder]\sql\setup-db-sqlServer.sql

Oracle Configuration

Create Database

Please Note: the following instructions are for using SQL*Plus.

1. Login as the system user.

2. Create a user named "txmanager":

create user txmanager identified by password;

Please note you should use a hardened password, and make a note of it, as you will need it whenrunning the Transact Manager installer.

3. Grant connect and resource roles to the txmanager user:

grant connect, resource to txmanager;

Creating Tables

Later in the Transact Manager installer you will be provided the option to automatically create the



database tables. If you would rather create the tables manually, do the following after running theTransact Manager installer:

1. Using SQL*Plus Login as the txmanager user:

connect txmanager/password

2. Execute the SQL script (replacing "[TM artifacts folder]" with the setup installation directory):

@[TM artifacts folder]\sql\setup-db-oracle.sql

3.2 Running the Transaction Manager Installer

The Transact Manager Setup Wizard will lead you through a series of questions and then perform theTransact Manager installation for you.

Adding a Dedicated User (Linux only)

For security reasons, Transact Manager and related services must not be run as root, and should run as aseparate user account.

Here is how to set up the user for Transact Manager on Linux:

1. Log in as root

2. Create the future TM user

useradd tmuserpasswd tmuser

3. Give sudo access to tmuservisudoGo to last line, add this line (using vi syntax):

tmuser ALL=(ALL) ALL

Save and exit.

4. Log out as root

5. Log in as tmuser

6. Create TM directories with the correct permissions

sudo mkdir /datasudo chown -R tmuser /data

Installation Notes: Use /data as the destination directory when running the TM installer (you can use adifferent directory throughout if desired, just use the same one that you made accessible to tmuser). Inaddition, run the installer as tmuser.

Starting the Installer

Please ensure you have a JDK 1.6 or later installed on the server. You can quickly check this by running"java -version" on the command line.

On Microsoft Windows you need run to the Transact Manager installer with administrator privileges("Run as Administrator") so that it can create the Transact Manager Windows service.



On Linux you need to run the installer as the dedicated user (tmuser).

Running the Installer

Start the Transact Manager installer (avoka-tm-setup-5.1.0.jar) by opening a console, navigating to thefolder containing the installer and running the following command:

java -jar avoka-tm-setup-5.1.0.jar

After running this command you should see a welcome screen displaying the Transact Manager version.

Transaction Manager Setup Wizard

On Linux please ensure the user has read/write permissions on the installation folder as described insection Adding a Dedicated User (Linux only).

Headless Mode

The installer normally displays a GUI for the user to interact with. However, it can also be run in text-only mode if desired. The installation steps are the same, but the choices are all presented on theconsole.

The command to invoke the installer in text mode is:

java -jar avoka-tm-setup-5.1.0.jar text

If you need to automate TM installations, the installer can be passed a property file with all theinstallation settings. The property file is specified via a "-config" command line parameter, for example:

java -jar avoka-tm-setup-5.1.0.jar -config tm-installer.properties

To obtain a suitable property file for your installation, please contact Avoka Support.

Installation Mode

On the Installation Mode setup page you can choose whether to:

· Install the Transact Manager server, or

· Upgrade an existing Transact Manager server (the existing server must be at version 4.0 or later)



· Reconfigure an existing TM installation to use a different database, or

· Build a custom user portal

This guide will focus on the options to install or upgrade a Transact Manager server.

Please also select the environment where this TM server will be deployed: "AWS Cloud" if the server ishosted on the Amazon cloud or "On Premise" for on-premise deployments. The deployment modeaffects what screens will be shown in the installer. Ensure that you select the correct setting to avoidany issues.

Note for on-premise deployments you should be selecting the "On Premise" option.

Installation Mode page

License Key

On the "License Key" page you will be asked to enter the license key for your TM server. This license keyis issued by Avoka ([email protected]), and a unique key must be used for every TM instance,including development and test instances.

A TM instance maps to a TM database (Prod, UAT, Test, Dev), and TM instances may be composed ofseveral TM server nodes. For example a TM Prod instance will generally have at least 2 server nodes forhigh availability, while a TM Dev instance may only have 1 server node.

It is not permissible to install or run a TM server without a valid license key. Please make a note ofthese keys as they are needed when you install or upgrade a TM server using the installer.

Once you have entered your license key, click "Next" to proceed.

mailto:[email protected])



The License Key page

Please note for TM servers deployed on premise, the network firewall rules will need to allow TMManagement Console server nodes to upload license compliance reports to the endpoint: https://s3-us-west-2.amazonaws.com

License compliance reports contain transaction licensing meta data and are uploaded automatically atthe end of each day. If the license reporting is unable to be performed errors will be recorded in theSystem Error Log.

Data Retention Mode

On the "Data Retention Policy Mode" screen, you can choose how long transaction data (includingpersonally identifiable information entered by users) can be kept on the TM server. Note that thisaffects only the maximum possible data age; the exact settings can be configured in TM, as previously.

The "Strict" option will apply more restrictive policies on your server, ensuring that potentially sensitivedata is cleared out sooner. This option is recommended for all servers.

The "Relaxed" option uses the data retention policies that were in place before TM 4.3.3. It is thedefault when upgrading an existing TM server.

For details on both options, please refer to the knowledge base article at https://support.avoka.com/kb/display/AT43/Data+Retention+Management .

https://s3-us-west-2.amazonaws.com

https://support.avoka.com/kb/display/AT43/Data+Retention+Management



Data Retention Policy Mode page

Database Server

On the "Database Server" setup page you can choose the type of database server you will use tomanage the Transact Manager database. Note: This page is shown only if the deployment type is "On Premise". For "AWS Cloud" installs MySQLis used.

Your choice will be used to configure the Transact Manager server configuration files and applicationsfor the specified database. You can later change the database that is used by TM by running the installeragain (data will not be migrated to the new database).

If you are upgrading an existing server, please select the options configured for your server on this andthe following screens.

Database Server page

PDF Receipt Services

On the "PDF Receipt Services" setup page you can choose the whether to use the default PDF receiptgeneration services or to use Adobe LiveCycle ES4 or ES3 for generation PDF receipts with Transact



Manager. Note: This page is shown only if the deployment mode is "On Premise".

Your choice will be used to initialize the correct services in the Transact Manager applications.

PDF Receipt Services page

Server Memory

On the "Transact Server Memory" page you can configure how much memory will be available to the TMserver. We generally recommend using 4GB of RAM for production servers, but provide a 8GB optionwhen you need to cache large amounts of reference data in memory.

If you are running Transact Manager on a development or test server with limited memory choose the 2GB RAM option. Please note 512 MB option is recommended for development use only.

Configuring server maximum memory

Security Configuration

On the "Security Configuration" page, you can modify several key security settings that will be used inTransact Manager.



Configuring security settings

The first option specifies whether users can log into the system over HTTP. For development orevaluation purposes it is not necessary to use secure cookies. However for production or system testingpurposes this setting MUST be checked which will require users to log in over HTTPS.

Please note we strongly recommend using SSL with certificates issues by a valid CA (as opposed to self-signed certificates) on all servers, not just production servers. Many organizations spend a lot of timetracking down non-existent issues because they deployed self-signed certificates on test servers.

The second option specifies whether new services can only use Transact Fluent SDK, or whetherdevelopers can create legacy mode dynamic Groovy Services.

The third option specifies whether Groovy Services data access data is isolated to the currentOrganization the service is running under. This setting is recommended to ensure Groovy Services arenot able to access user transaction data or application configurations outside of their Organizationsecurity context.

Installation Directories

On the "Installation Directories" setup page you can configure the installation directories or use thedefaults.

The "Transact Manager server" directory is the directory where the server will be installed.

The "Setup installation directory" will contain the deployment modules and resources that are notdeployed to the Transact Manager server (e.g. SQL table creation scripts, LiveCycle archives).



Installation directories (turnkey install)

If you are upgrading an existing TM server, you will also be asked to provide a backup directory. Beforethe installer starts the upgrade, it will create a full backup of the TM server directory.

Installation directories (upgrade)

Please ensure that both the setup installation directory and the backup directory are empty if theyexist.

Before continuing, ensure that the TM service is not running as this will cause the upgrade to fail. Alsomake sure you have been following the upgrade steps in the upgrade instructions for your targetversion including backing up the database.

Modules and Spaces

On the "Modules and Spaces" setup page you can choose which modules to deploy onto the TransactManager server.



Modules and Spaces page

Depending upon your solution design, you may have separate servers for hosting public facing modules,and servers for hosting management modules.

Core Modules include:

· Transact Manager - provides Management Console, Transact Insights and Business Report modules

· Receipt Server - provides PDF receipting

Form Spaces include:

· Transact Web Plugin - provides default Web Plugin space for public facing anonymous andauthenticated form applications integrated with public web sites

· Transact Work Space - provides a default Work Space for business staff, often used for internalstaff performing task, job and help desk functions

· Transact Salesforce - provides a form space to support the Avoka Transact for Salesforceintegration

Please note if you need to create a custom Transact Work Space use the installer option "CreateTransact Workspace".

Forms and Example Content

On the "Forms and Example Content" setup page you can choose whether to deploy operationalmonitoring forms and examples content onto the Transact Manager server.



Forms and Example Content page

Monitoring Form includes:

· Transact Server Monitoring Form - provides a system availability monitoring form and organization

Example Content include:

· Maguire Forms and Work Space - provides example application forms, organization and WorkSpace portal.

The Monitoring Form provides an "Transact Server Monitoring" organization and a "Server Monitor Test"form which is designed for external server availability monitoring.

While the example content is great to install on TM development servers, it is not recommended thatyou install it on higher environments such as Production, Staging or Test.

Database Configuration

On the "Database Configuration" setup page you will need to configure the database connectionparameters for the database server you selected previously.

Your choice will be used to set up the Transact Manager server configuration files and applications forthe specified database.



Database Configuration page

If you are using an Oracle database, please ensure you set the database name correctly. For example ifyou are using the Oracle 11g Express Edition the database name would be 'XE'.

If you have already created the txmanager database and are running the installer for the first timeplease ensure that "Create the database tables" is ticked to automatically create the database tablesand indexes. These database operations will be performed using the user login you specify in theinstaller.

If you are upgrading an existing TM server, the option to create the database tables will not be availableas your server will already be using a functioning, fully initialized database. Simply enter the databaseconnection information for the current server. The schema will be automatically upgraded when TMstarts up.

Perform Installation

On the "Perform Installation" setup page click on the Install button to start the installation.

Perform Installation page

If an error occurs during installation you can click "Show Details" to view the detailed installation log.You can also navigate back using the "Back" button and correct any configuration settings and retry the



installation.

Installing JDK (Linux only)

On Linux servers, you need to install the Oracle Server JRE 1.8u112 appropriate for your platform.

The folder to install the JDK to must be: [TM install folder]/jdk1.8.0_112, e.g. /data/avoka/transact/manager/jdk1.8.0_112

If you do not correctly install the server JRE to this folder, TM will not start up.

JDK installation steps:

1. Download the server JRE from the Oracle website to a suitable temporary folder.

2. Open a command prompt and navigate to the downloaded file.

tar zxvf server-jre-8u112-linux-x64.tar.gz

Once finished, it'll create a folder called 'jdk1.8.0_112'

3. Move this folder to [TM install folder]/jdk1.8.0_112

4. Finally, add the Unlimited Strength Java Cryptography Extension (JCE) policy files to the Javainstallation. These enable Transact Manager to use AES-256 and SHA-512 cryptographic functions.

The local_policy.jar and US_export_policy.jar files are contained in the ZIP package provided withthe installer:

[TM artifacts folder]/linux/jce_policy-8.zip

Please copy these policy files into the directory, overwriting the existing files:

[TM install folder]/jdk1.8.0_112/jre/lib/security

Service Creation

Microsoft Windows

On Microsoft Windows servers the Transact Manager installer will automatically create a service named"Avoka Transaction Manager". This service will have a startup type of "Automatic" so it will be startedautomatically when the server is started.

Linux

On Linux servers you need to perform the following steps to configure and start Transaction Manager asa service.Note: If you are performing an upgrade, please ensure you keep a copy of the previous txmanager file.

1. Ensure Java SE 8u112 is installed on the server as described in the previous section.

2. Edit the [TM artifacts folder]/server/bin/standalone.conf file and set the JAVA_HOMEvariable to the Java SE 8u112 home directory.

3. Open an administrator command shell

4. Navigate to the server bin installation directory, for example: /data/avoka/transact/manager/server/bin

5. Add execute permission (chmod +x) on all the .sh files



6. Navigate to the database updater directory, for example: /data/avoka/transact/manager/server/standalone/db-updater

7. Add execute permission (chmod +x) on all the .sh files

8. Navigate to the PhantomJS directory in the server installation directory, for example: /data/avoka/transact/manager/phantomjs

9. Add execute permission (chmod +x) to the PhantomJS file inside the folder: chmod +x phantomjs

10. Copy [TM artifacts folder]/linux/txmanager to the directory /etc/init.d ("[TM artifactsfolder]" is the directory where the TM installer stores the artifacts it produces, and defaults to /usr/avoka-tm-install)

11. Edit the txmanager file and ensure the variable JAVAPTH is set to Java SE 8u112 bin directory

12. Add execute permission (chmod +x) on the txmanager file

13. Edit the txmanager file and change the associated parameters such as user, installation address,etc.

14. To start the Transaction Manager service use the command: service txmanager start

15. To stop the Transaction Manager service use the command: service txmanager stop

Linux Service ScriptA sample Linux Transaction Manager service file is provided in the installer: [TM artifacts folder]/linux/txmanager

Please see the example service script content below:

#!/bin/sh## $Id: jboss_init_redhat.sh 60992 2007-02-28 11:33:27Z [email protected] $# chkconfig: 2345 65 35# description: JBoss 7 for TM# processname: txmanager# pidfile: /var/run/txmanager.pid

#define where SFMANAGER is - this is the directory containing directories log, bin, conf etcSFMANAGER_HOME=${SFMANAGER_HOME:-"@{installation.dir}/server"}

#define the user under which jboss will run, or use 'RUNASIS' to run as the current userSFMANAGER_USER=${SFMANAGER_USER:-"root"}

#make sure java is in your pathJAVAPTH=${JAVAPTH:-"@{installation.dir}/jdk1.8.0_112/bin"}

#define the script to use to start jbossSFMANAGERSH=${SFMANAGERSH:-"./standalone.sh"}

SFMANAGER_CONSOLE=${SFMANAGER_CONSOLE:-"run.log"}

if [ "$SFMANAGER_USER" = "RUNASIS" ]; then SUBIT=""else SUBIT="su - $SFMANAGER_USER -c "fi

if [ -n "$SFMANAGER_CONSOLE" -a ! -d "$SFMANAGER_CONSOLE" ]; then # ensure the file exists touch $SFMANAGER_CONSOLE if [ ! -z "$SUBIT" ]; then



chown $SFMANAGER_USER $SFMANAGER_CONSOLE fi fi

if [ -n "$SFMANAGER_CONSOLE" -a ! -f "$SFMANAGER_CONSOLE" ]; then echo "WARNING: location for saving console log invalid: $SFMANAGER_CONSOLE" echo "WARNING: ignoring it and using /dev/null" SFMANAGER_CONSOLE="/dev/null"fi

#define what will be done with the console logSFMANAGER_CONSOLE=${SFMANAGER_CONSOLE:-"/dev/null"}

SFMANAGER_CMD_UPDATE_DB="cd $SFMANAGER_HOME/standalone/db-updater; ./update.sh;"SFMANAGER_CMD_START="cd $SFMANAGER_HOME/bin; $SFMANAGERSH"SFMANAGER_CMD_STOP="cd $SFMANAGER_HOME/bin; ./jboss-admin.sh --connect command=:shutdown"

if [ -z "`echo $PATH | grep $JAVAPTH`" ]; then export PATH=$PATH:$JAVAPTHfi

if [ ! -d "$SFMANAGER_HOME" ]; then echo SFMANAGER_HOME does not exist as a valid directory : $SFMANAGER_HOME exit 1fi

#echo SFMANAGER_CMD_START = $SFMANAGER_CMD_START

case "$1" instart) cd $SFMANAGER_HOME/bin if [ -z "$SUBIT" ]; then

eval $SFMANAGER_CMD_UPDATE_DB >${SFMANAGER_CONSOLE} 2>&1 &

if [ -f $SFMANAGER_HOME/bin/db-update.success ];

then echo "Starting TM..." eval $SFMANAGER_CMD_START >${SFMANAGER_CONSOLE} 2>&1 & else echo "Aborting..."

fi else $SUBIT "$SFMANAGER_CMD_UPDATE_DB >${SFMANAGER_CONSOLE} 2>&1 &"

if [ -f $SFMANAGER_HOME/bin/db-update.success ];

then echo "Starting TM..." $SUBIT "$SFMANAGER_CMD_START >${SFMANAGER_CONSOLE} 2>&1 &" else echo "Aborting..."

fi fi ;;stop) if [ -z "$SUBIT" ]; then $SFMANAGER_CMD_STOP else $SUBIT "$SFMANAGER_CMD_STOP" fi rm -rf $SFMANAGER_HOME/standalone/tmp ;;restart) $0 stop $0 start ;;*) echo "usage: $0 (start|stop|restart|help)"esac



Additional Steps (Linux Only)

Additional Fonts

Font substitution errors can occur when rendering forms and receipts, when the form was designedusing Windows fonts which are not present on the Linux server.

The TM installer includes a package of Microsoft Core TrueType fonts. If you have questions aboutMicrosoft Windows font licensing please see:

http://www.microsoft.com/typography/faq/faq8.htm

Installation instructions for additional fonts on Centos 6.3 are as follows:

1. Unzip msttcore font package at

[TM artifacts folder]/linux/msttcore.zip

to:

/usr/share/fonts

2. Execute the following command:

sudo fc-cache -fv

Install LibICU

To support Dynamic PDF Receipt rendering using PhantonJS 2 you need to ensure that the libicu library(international components for Unicode) is present. To install the library, run the following command:

sudo yum install libicu

Proxy Configuration

If your TM instance will be running behind a proxy, you may need to configure the proxy details on theTM server so it can connect successfully to external systems.

Configure the proxy by editing:

[TM server folder]/server/standalone/configuration/standalone.xml

Adapt and add one of the following lines. Note you may not need the proxy username, password ornonProxyHosts setting.

<system-properties>

<property name="http.proxyHost" value="proxyhostURL" />

<property name="http.proxyPort" value="proxyPortNumber" />

<property name="https.proxyHost" value="proxyhostURL" />

<property name="https.proxyPort" value="proxyPortNumber" />

<property name="https.proxyUser" value="username" />

<property name="https.proxyPassword" value="password" />

<property name="http.nonProxyHosts" value="localhost|www.someotherhost.com" />

</system-properties>

Save the file and restart the Transact Manager service to apply your changes.

If you have configured Transact Manager server behind a proxy you will need to the server can connect




to a Network Time Protocol (NTP) server to ensure the server's clock is correctly synchronized.

Installation Results

Depending on the installation mode chosen, the installer will log various information on the versioninstalled and what actions were performed. This information is stored in the TM server root directory(by default at C:\avoka\transact\manager (Windows) or /opt/avoka/transact/manager (Linux)) in a filenamed "installation-details.txt". If you run the installer again on the same server directory (e.g. for anupgrade), the installer will add to this file, providing a history of changes made by the installer.

Do not modify or remove this file as it provides important information about your server.

Adding an Additional TM Node

If your installation will consist of multiple TM nodes, run the installer on the first node as describedpreviously. For every additional TM node, run the installer again, making sure to do the following:

· Enter the same database connection details on the "Database Configuration" screens. All TM nodesshare the same database.

· Leave the "Create the database tables" checkbox on both these screens unticked.

After completing the installation, ensure to configure TM correctly for multi-node operation.

3.3 Transact Manager Configuration

The next installation step is to start Transact Manager and configure your installation.

Starting the TM Service

Please Note: Before starting Transact Manager you will need to ensure your database schema has beenalready created.

To start Transact Manager please open the Windows Services Management Console, select the "AvokaTransaction Manager" service and click on the start button.



Starting Avoka Transaction Manager service

Once the service has started its status should change to "Started", to stop the service simply click on thestop button.

The Transact Manager service should start in approximately 10-30 seconds depending upon theperformance of the machine. If database upgrades are being performed on startup (this is done by TMautomatically when a new version is deployed), the startup time may be longer depending on thenature of the upgrades.

To monitor the progress of the Transact Manager start up please view the log files:

C:\avoka\transact\manager\server\standalone\log\db-update.log

C:\avoka\transact\manager\server\standalone\log\server.log

To tail the server log files on Windows servers you can use the BareTail utility program:

http://www.baremetalsoft.com/baretail/

First Administrator Login

Log into the Transact Manager Management Console using the default administrator user with thecredentials: administrator / password .

http://localhost:9080/manager/

http://www.baremetalsoft.com/baretail/

http://localhost:9080/manager/



Log into TM Management Console

The next screen you will be presented with is the change password screen where you will need tochange the root administrator password. Default password rules will require a minimum of 12characters and a mix of letters and digits, upper and lower case characters and a special character. Notethe password complexity rules can be adjusted via the Local Security Manager, found under the menu"Security > Security Managers".

Changing the administrator password

Once you have completed these steps you be presented with the Home page, which provides jumppoints to key parts of the system.



TM Management Console home page

Hardening Administrator Access

One of the first things you should do with your Transact Manager instance is harden the defaultadministrator account.

There are two approaches to harden this account: The first is to simply harden the default administratorpassword, while the second approach is to create named user accounts for the system administratorsand disable the default administrator account.

Transact Manager will automatically enforce the first approach, but the second is also recommended asthis provides tighter security access control, and auditing information (automatically maintained by TM)references the named user accounts rather than a shared user account.

Disabling the Administrator Account

To disable the administrator account the first thing you need to do is to create a new user account foryourself. Navigate to the "Security > User Accounts" page and click on the "New" button.

Next create a new user account, ensuring the portal "Transaction Manager" is selected and click on the"Save" button.



Create a new named user account

Once you have created the account, navigate to the "Roles" tab, assign the "Administrator" role to yournew account and click "Save". If you do not do this, your new user account will not be able to access theTM management console.

Assigning the administrator role to the new user account

After this step you need to assign the new administrator user with "Enable Global Access" on the"Organizations" tab so they can manage all organizations on the server. Click "Save".



Enable global access for the administrator

The next step is to log out, and login using your new user account. Then navigate again to the "Security >User Accounts" page, and edit the default "administrator" account. Change the Account Status to"Inactive" and save these changes. Now this account cannot be used to log into the system.

Making the default administrator account inactive

All future users of the TM management console should be set up with their own account. Roles andassigned organizations and spaces can and should be adjusted according to the needs of the user.



Set Module Context Paths

You should set the context paths of the Transaction Manager and Business Reports modules so they areaccessible. These module configurations are available via the "System > Modules" page.

System Modules

Configuring Transaction Manager context path

Next you edit the context paths of the public facing Form Space modules so they are accessible. Thesemodule configurations are available via the "Forms > Form Spaces" page.

Configure Form Space context paths

Admin Environment Properties

With the Transaction Manager module an environment type message is displayed on the banner ofevery page. This is a very important reminder message for staff working across multiple environmentssuch as PROD, UAT, TEST and DEV.



By setting this environment message you can help prevent staff from making the wrong configurationchanges to the wrong environment. This is particularly important for your production environment, soplease configure CSS styles to highlight PROD servers.

To set the Admin Environment Name navigate to the page "System > Modules", edit the TransactionManager module and then click on the "Properties Edit" tab.

TM Admin Environment Properties

In this screen set the "Admin Environment Name" property, e.g. to "PROD", and then edit the "AdminEnvironment CSS Style" property and set color styles appropriate for that environment. For examplethe following CSS style:

#environmentCssStyle { position: absolute; top: 10px; text-align: center; width: 100%;} #environmentCssStyle span { color: red; background-color: #fcfcfc; font-weight: bold; font-size: 12pt; padding: 3px 12px; border: 2px solid red;}

will provide the Environment banner message style:



TM Admin Environment Message Style

On lower development TM environments it is recommended that you turn off some of the CSRF securityhardening settings to make it easier to work with multiple browser tabs open at the same time.

Configure Email Settings

Transact Manager needs an email server to be configured to enable it to send emails. To specify thedetails of your email server navigate to "System > SMTP Email Settings" and enter the configurationvalues for your SMTP server.

At a minimum you will need to specify a SMTP host and a default email sender address; dependingupon your email server you may also need to specify a port, user and/or password. Please use the"Send Test" button to confirm that your email server connection settings are correct.

Configure Email Settings



Data Retention Management

Transact Manager provides a data retention management system for controlling the growth of systemtransaction, analytics and log tables. By controlling database growth the system ensures thatperformance does not degrade over time.

When Transact Manager starts for the first time it will use pre-configured data retention managementpolicies, so it is important that you review these policies and ensure they meet your businessobjectives.

You can view the system's data retention policies by navigating to "System > Data RetentionManagement".

Global data retention policies

Please liaise with business owners to ensure the system data retention management policies havebeen agreed upon and then ensure the are configured in Transact Manager.

For information on data retention management please see the knowledge base article at https://support.avoka.com/kb/display/AT43/Data+Retention+Management.

3.4 Apache Server Configuration

The next step is to install and configure a public facing Apache server to connect to Transact Manager.

You can use Apache 2.2.22 or later with Transact Manager. Please ensure you keep Apache up to datewith the latest security patches.

Please note while you can use Apache 2.4 with Transact Manager, the following instructions are forApache version 2.2, and there are a number of module configuration differences between Apache 2.2and 2.4.

Using Microsoft IIS





If you are evaluating whether to use Microsoft IIS as the fronting web server, please note there is anissue with IIS 7.5, Firefox 3-4 and Adobe Reader which will prevent forms from submitting to IIS. Firefox3 and 4 add an additional HTTP "Referer" header when Adobe Reader submits a form. IIS 7.5 rejects thisrequest with a 400 error (refer to http://forums.iis.net/t/1162919.aspx).

If you intend to use IIS you will need to modify the request before it reaches the IIS web server anddelete the duplicate "Referer" header. Modifying the request can be done using a smart switch devicesuch as an F5 BIG-IP where you can execute scripts to modify HTTP requests.

Apache on Windows

1. Download latest Apache web server from Apache Lounge - http://www.apachelounge.com/download/win64/

2. Extract avoka-tm-setup\apache\win64\apache-windows-additional-config.zip to a temporary folder

3. Install Visual C++ 2010 Redistributable package – vcredist_x64.exe – included in Apache-Windows-additional-config.zip

4. Unzip httpd-2.2.xx-win64.zip to C:\ -- if using a different location/folder name, note the folderlocation

5. Make a backup of httpd.conf and httpd-ssl.conf

a. Rename [Apache folder]\conf\httpd.conf to httpd.conf.ori

b. Rename [Apache folder]\conf\extra\httpd-ssl.conf to httpd-ssl.conf.ori

6. Copy Apache configuration from Apache-windows-additional-config.zip

a. httpd.conf: copy to [Apache folder]\conf\

b. httpd-ssl.conf: copy to [Apache folder]\conf\extra\

7. Copy Apache configuration from avoka-tm-setup\apache\win64

a. mod_proxy.conf: copy to [Apache folder]\conf\

b. mod_deflate.conf: copy to [Apache folder]\conf\

c. mod_cache.conf: copy to [Apache folder]\conf\

8. Copy Apache mod_security configuration from avoka-tm-setup\apache\modsecurity

a. avoka-tm-setup\apache\modsecurity\config\win64\mod_security.conf: copy to [Apache folder]\conf\

b. avoka-tm-setup\apache\modsecurity\config\modsecurity.d folder: copy to [Apache folder]\conf\

c. avoka-tm-setup\apache\modsecurity\module\win64\mod_security2.so: copy to [Apache folder]\modules\

d. avoka-tm-setup\apache\modsecurity\module\win64\*.dll: copy to [Apache folder]\bin\

9. Copy valid SSL certificate, private key and chain or root CA – if the SSL certificate is not ready, skipthis step. There is a self-signed SSL certificate included with Apache zip, use that temporarily – userswill get certificate warning

a. copy SSL public certificate to [Apache folder]\conf\ssl

b. copy SSL private key to [Apache folder]\conf\ssl

c. copy SSL chain or root CA to [Apache folder]\conf\ssl

http://forums.iis.net/t/1162919.aspx



10. Modify httpd.conf and httpd-ssl.conf

a. Edit [Apache folder]\conf\httpd.conf

b. Look for ServerName and replace it with the server hostname or TM URL

c. If the httpd zip file is extracted to other location than C:, search for ‘C:/’ and replace it withcorrect location of [Apache folder]

d. Save and exit

e. Edit [Apache folder]\conf\extra\httpd-ssl.conf

f. Look for ServerName and replace it with the server hostname or TM URL

g. Edit SSLCertificateFile: location of SSL public certificate

h. Edit SSLCertificateKeyFile: location of SSL private key

i. Edit SSLCACertificateFile: location of SSL Root CA or Chain certificate

j. Look for RedirectMatch and replace the URL with TM URL

k. If the httpd zip file is extracted to other location than C:, search for ‘C:/’ and replace it withcorrect location of [Apache folder]

l. Save and exit

11. Create folder for mod_cache and mod_security

a. Create folder [Apache folder]\httpd_cache

b. Create folder [Apache folder]\logs\mod_security

12. Modify mod_cache.conf

a. Edit [Apache folder]\conf\mod_cache.conf

b. Edit CacheRoot: set it to [Apache folder]\httpd_cache

c. Save and exit

13. Confirm that TCP port 80 and 443 are opened in Windows firewall

14. Install Apache as windows service

a. Open CMD (run as administrator)

b. Go to [Apache folder]\bin

c. Type ‘httpd -k install’

d. It will install a Windows service called ‘Apache22’

15. Start Apache service

16. Check the logs for error

a. Error log: [Apache folder]\logs\error.log or [Apache folder]\logs\ssl_error.log

b. Access Log: [Apache folder]\logs\access.log or [Apache folder]\logs\ssl_access.log

c. SSL Request Log: [Apache folder]\logs\ssl_request.log

17. Test by going to https://localhost/manager or https://TMURL/manager



Apache on Linux

The next step is to install and configure a public facing Apache server to connect to Transact Manager.

You can use Apache 2.2.22 or later with Transact Manager. Please ensure you keep Apache up to datewith the latest security patches.

Please note while you can use Apache 2.4 with Transact Manager, the following instructions are forApache version 2.2, and there are a number of module configuration differences between Apache 2.2and 2.4.

Apache Linux installation

1. Install httpd and mod ssl package from repository sudo yum install httpd mod_ssl

2. Backup original httpd.conf and ssl.conf sudo cp /etc/httpd/conf/httpd.conf /etc/httpd/conf/httpd.conf.backup sudo cp /etc/httpd/conf.d/ssl.conf /etc/httpd/conf.d/ssl.conf.backup

3. Copy Apache configuration from avoka-tm-setup/apache/linux/apache-linux-additional-config.zip

httpd.conf copy to /etc/httpd/conf/

ssl.conf copy to /etc/httpd/conf.d/

4. Copy Apache configuration from avoka-tm-setup/apache/linux

mod_proxy.conf copy to /etc/httpd/conf.d/

mod_deflate.conf copy to /etc/httpd/conf.d/

mod_cache.conf copy to /etc/httpd/conf.d/

5. Copy Apache mod_security configuration from avoka-tm-setup/apache/modsecurity

avoka-tm-setup/apache/modsecurity/config/linux/mod_security.conf copy to /etc/httpd/conf.d/

avoka-tm-setup/apache/modsecurity/config/modsecurity.d folder copy to /etc/httpd/conf.d/

avoka-tm-setup/apache/modsecurity/module/linux/mod_security2.so copy to /etc/httpd/modules/

6. Copy valid SSL certificate, private key and chain or root CA – if the SSL certificate is not ready, skip thisstep. There is a self-signed SSL certificate included with httpd install, which you can use temporarily –however, this is not a supported configuration and users will get a certificate warning. sudo cp /location/of/SSL/public/certificate.crt /etc/pki/tls/certs/ sudo cp /location/of/SSL/chain/root/ca.crt /etc/pki/tls/certs/ sudo cp /location/of/SSL/private/key.key /etc/pki/tls/private/ sudo chown root:root /etc/pki/tls/certs/certificate.crt /etc/pki/tls/certs/ca.crt /etc/pki/tls/private/key.key sudo chmod 600 /etc/pki/tls/certs/certificate.crt /etc/pki/tls/certs/ca.crt /etc/pki/tls/private/key.key sudo chcon -u system_u -t cert_t /etc/pki/tls/certs/certificate.crt /etc/pki/tls/certs/ca.crt /etc/pki/tls/private/key.key

7. Modify /etc/httpd/conf/httpd.conf

Edit ServerName: FQDN/DNS/URL name for TM application

Save and exit

8. Modify /etc/httpd/conf.d/ssl.conf

Edit ServerName: FQDN/DNS/URL name for TM application

Edit SSLCertificateFile: location of SSL public certificate



Edit SSLCertificateKeyFile: location of SSL private key

Edit SSLCACertificateFile: location of SSL Root CA or Chain certificate

Edit RedirectMatch line: change the URL to match ServerName

Save and exit

9. Create folder for mod_cache sudo mkdir /var/httpd_cache sudo chown apache:apache -R /var/httpd_cache

10. If SELinux is enabled, add port 9009 to http_port_t sudo yum install policycoreutils-python sudo semanage port -a -t http_port_t -p tcp 9009

11. Configure SELinux file types sudo chcon -u system_u -t httpd_config_t /etc/httpd/conf/* -R sudo chcon -u system_u -t httpd_config_t /etc/httpd/conf.d/* -R sudo chcon -u system_u -t httpd_modules_t /etc/httpd/modules/mod_security2.so

12. Confirm that TCP port 80 and 443 are opened in IPTables

13. Enable httpd service sudo chkconfig --add httpd sudo chckonfig httpd on

14. Restart httpd/apache sudo service httpd restart

15. Check the logs for error

Error log: /var/log/httpd/error_log or /var/log/httpd/ssl_error_log

Access Log: /var/log/httpd/access_log or /var/log/httpd/ssl_access_log

SSL Request Log: /var/log/httpd/ssl_request_log

Mod Proxy

If you need to expose additional TM Form Spaces such as a new Work Space you will need to edit theApache mod_proxy.conf file to add the new context path and then restart the Apache service.

The example exposes a new Work Space with the context path /workspace. Note this context pathmust be included in the TM Work Space WAR files configuration.

# Forms Work SpaceProxyPassMatch /workspace ajp://localhost:9009/workspaceProxyPassReverse /workspace ajp://localhost:9009/workspace

3.5 Virus Scanner Configuration

Transact Manager support integration with online virus scan services to enable detection andelimination of virus uploaded file attachments. Currently Transact Manager supports integration with:

· ClamAV open source virus scanner for Linux systems - http://www.clamav.net/lang/en/

· Symantec Scan Engine commercial virus scanner for Microsoft Windows and Linux systems - http://www.symantec.com/

http://www.clamav.net/lang/en/

http://www.symantec.com/



ClamAV Configuration

We recommend that ClamAV virus scanner is installed on the same server as Transact Manager becausethe ClamAV STREAM protocol opens up TCP listener sockets over a range of ports which makes moredifficult to firewall on remote servers.

For information about installing ClamAV please see the User Guide at https://github.com/vrtadmin/clamav-faq/raw/master/manual/clamdoc.pdf

Please ensure you configure the ClamAV service to automatically update the virus definitions asdescribed at http://www.clamav.net/doc/cvd.html

The default ClamAV maximum file size in 25MB, you need to increase this value to 50MB in theclamd.conf file by adding the following configuration line and restarting the service.

# Close the connection when the data size limit is exceeded.# The value should match your MTA's limit for a maximum attachment size.# Default: 25MStreamMaxLength 50M

Once you have installed ClamAV make it the default virus scan service by accessing "System > ServiceDefinitions", filtering by service type "Virus Scan" and clicking on the "Make Default" link next to theservice named "ClamAV Virus Scan".

Making ClamAV the default virus scan service

Symantec Scan Engine Configuration

For information about installing Symantec Scan Engine, please see resources provided by Symantec: ftp://ftp.symantec.com/public/english_us_canada/products/symantec_scan_engine/5.1/manuals/GettingStarted.pdf

Once you have installed Scan Engine, in Transact Manager configure the "Symantec Virus Scan" serviceconnection and set the endpoint to the server running the Scan Engine service.

https://github.com/vrtadmin/clamav-faq/raw/master/manual/clamdoc.pdf

https://github.com/vrtadmin/clamav-faq/raw/master/manual/clamdoc.pdf

http://www.clamav.net/doc/cvd.html



Configuring service connection endpoint for SSE

After you have done this, make Scan Engine the default virus scan service by accessing "System >Service Definitions", filtering by service type "Virus Scan" and clicking on the "Make Default" link nextto the service named "ClamAV Virus Scan".

Making Scan Engine the default virus scan service

Upgrading Transact ManagerTransact Manager Installation Guide


4 Upgrading Transact Manager

This section describes the recommended procedure of upgrading Transact Manager to a newer version.

You have two choices on how to upgrade your server:

· Upgrade the existing server using the Setup Wizard task "Upgrade a Transact Manager 4.0+ server"

· Reinstall by uninstalling the existing server and then install a new server using the Setup Wizardtask "Install a new Transact Manager server"

With both upgrade modes Transact Manager will automatically upgrade the database when the serviceis restarted.

Where possible we recommend the first option as it will automatically backup your existing server andprovide an installation-details.txt file specifying the files changed during the upgrade process.

Please Note

The upgrade option is only supported for upgrading Transact Manager version 4.0 or later servers. If youhave an earlier version you should uninstall the existing server and the install a new Transact Manager



server.

Please ensure you review Upgrading TM Version Notes to see what additional configuration changesneed to be performed.

4.1 Back up TM Database

Before you start installing the new version, shut down Transact Manager service and back up theTransact Manager database.

IMPORTANT NOTE : Always back up the Transact Manager database before performing an upgrade

4.2 Upgrade TM Server Option Setup Steps

When performing the in-place upgrade option please follow the steps below.

1. Stop TM Service

Ensure the Transact Manager service is stopped.

2. Perform Upgrade with Setup Wizard

Using the Setup Wizard task "Upgrade a Transact Manager 4.0+ server", follow the wizard steps and takespecial care to ensure the same database version and database connection details are used.

If you have custom server shared modules JAR files deployed, perform the upgrade as normal. Afterwards, review your customized modules.xml file to ensure your custom JAR files are stillreferenced. If the module.xml has been updated, please edit it to add references to your custom JARfiles.

Once the upgrade has been completed please review the installation details log file which will specifywhat files have been added, updated or deleted.

/avoka/transact/installation-details.txt

4.3 Reinstall TM Server Option Setup Steps

When performing the re-installation upgrade option please follow the steps below.

1. Stop TM Service

Ensure the Transact Manager service is stopped.

2. Uninstall Service

Please uninstall the service used to run Transact Manager. On Windows systems, simply run thefollowing batch file with administrator privileges:

[TM server folder]/bin/service-uninstall.bat

On CentOS or RedHat Enterprise Linux, you do not need to uninstall the service.

3. Rename the TM Service installation Directory

Rename the existing Transact Manager service installation directory, so the new installation can use thispath. This will also provide you with a backup of the existing installation.

4. Perform new Transact Manager installation with Setup Wizard

Use the Setup Wizard to perform a new installation. Please follow any upgrade instructions as providedas well as the installation steps listed in section Running Transact Manager Installer.



Perform a new Transaction Manager installation

Take special care to ensure the same database version and database connection details are used, andalso ensure the "Create the database tables" option is unchecked.

Uncheck "Create the database tables"

5. Restore Custom Portal WAR files

Restore any custom Portal WAR files from your previous installation to the server deployments folder:

[TM server folder]/standalone/deployments

If your Portal or Module WAR file contains Java code you will need to have it regenerated so that itreferences the correct Transact Manager services, otherwise you may get linkage errors at runtime.

4.4 Updating the TM Database

Next, you need to make sure that database updates contained in the new version of Transact Managerare applied to the existing TM database. There is a separate module that runs before the TM serverstarts up and is responsible for updating the database and initializing core system configuration.

Note: Before performing this step, please ensure you have a database backup available.



Start Transact Manager using the service and monitor the logs in

[TM server folder]/standalone/log/db-update.log

Specifically, ensure that the database updates run successfully. A successful startup should contain abasic structure like this:

INFO [com.avoka.fc.core.service.DatabaseVersionService] ... Updating database...

INFO [com.avoka.fc.core.service.DatabaseVersionService] ... Results will be written to C:

\Avoka\transact\manager\server\standalone\log\db-update\db-version-updates-2013-03-25-

1436.txt

...

INFO [com.avoka.fc.admin.service.DatabaseVersionService] ... Update completed successfully

at 30 Apr 2013 10:32:23

INFO [com.avoka.fc.admin.service.DatabaseVersionService] ... 1 change(s) were applied to

the database.

Database schema update complete.

...

Configuration initialization complete.

Should an error occur while updating the database, Transact Manager will not start up and instead logmessages such as:

[ERROR] [com.avoka.fc.core.service.initialization.DatabaseVersionService] Please resolve

database update error

Database update failed

In this case, keep a copy of the log file as well the detailed log in the folder [TM server folder]/standalone/log/db-update as well as the database backup for investigation with your Avokasupport contacts, and perform a rollback to the old version. Note that the TM server will not start up ifthe database updater module exited due to an error.

4.5 Updating Apache Configuration

In TM 4.3, the Apache files "mod_proxy.conf" and "mod_security.conf" and has been updated, and theupdated file needs to be deployed to your Apache server(s) if you are upgrading from an older version.

The TM installer will have created the current set of Apache configuration files.

First, back up the existing configuration files:

[Apache folder]\conf\mod_proxy.conf (Windows)[Apache folder]\conf\mod_security.conf (Windows)

/etc/httpd/conf.d/mod_proxy.conf (Linux)/etc/httpd/conf.d/mod_security.conf (Linux)

Copy the configuration files:

[TM artifacts folder]/apache/[Operating System]/mod_proxy.conf

[TM artifacts folder]/apache/modsecurity/config/[Operating System]/mod_security.conf

to

[Apache folder]\conf\ (Windows)

/etc/httpd/conf.d\ (Linux)

Add any customized mod_proxy mappings to your new mod_proxy.conf file using the revised proxypattern:

# TM Example Maguire Portal



ProxyPass /maguire ajp://localhost:9009/maguire

ProxyPassReverse /maguire ajp://localhost:9009/maguire

Copy the Mod Security rule files:

[TM artifacts folder]/apache/modsecurity/config/modsecurity.d/activated_rules/

to

[Apache folder]\conf\ (Windows)

/etc/httpd/conf.d/ (Linux)

Restart Apache. Ensure Apache starts up successfully.

If errors occur during the installation, you can roll back the Apache change by deploying the previousconfiguration files you backed up and restarting Apache again.

4.6 Finalizing and Verifying the Upgrade

Now that the database is up to date, the TM server should also be starting up. Monitor the log file in:

[TM server folder]/standalone/log/server.log

If any unusual errors occur, please contact your Avoka support contacts with the logs. Shouldfunctionality be impacted, you may need to roll back to the old version of Transact Manager.

Once Transact Manager has started successfully, please log on to the TM Administration Console,navigate to "System > Server Nodes" and click "Synchronize Repositories". This will perform asynchronization with Adobe LiveCycle. Ensure the synchronization completes successfully.

Finally, test core functionality such as rendering and submitting forms to ensure that the system isrunning normally. As usual, monitor the error and event logs in Transact Manager.

Please Note: Ensure you have followed the "Upgrade Notes" section in the "Transact Manager ReleaseNotes" document for version specific instructions on configuration changes you may need to make withyour upgrade.

4.7 Cleaning up the JDK Folder

The TM server contains the Java Development Kit (JDK) it needs to run. The JDK is regularly updated,and the current JDK is deployed by the TM installer during an upgrade. However, the installer does notautomatically remove the old JDK. If you would like to remove obsolete JDK folders, you can do so afterhaving verified that the installation was successful.

The JDK folders are located here:

[TM install folder], e.g. C:\avoka\transact

If multiple JDK folders exist, you can delete the ones with lower version numbers.

Note that it is not necessary to remove the obsolete folders, other than to reclaim disk space.

4.8 Rollback Procedures

Should you need to roll back to the old version of Transact Manager, stop Transact Manager (if running).On Windows systems, uninstall the Transact Manager service by running the following batch file as an



administrator:

[TM server folder]/bin/service-uninstall.bat

On RedHat and Solaris, you will be replacing the service script when reinstalling the old version.

Delete the Transact Manager folder (by default C:\Avoka\transact\manager on Windowssystems).

If you upgraded your existing TM installation directly via the installer, please follow these steps:

· Delete the contents of the TM server folder (keeping any log files that may help find the problem thatcaused the rollback). By default the TM server directory is at C:\avoka\transact\manager (Windows) or/opt/avoka/transact/manager (Linux).

· Copy the contents of the backup directory you specified during installation (see InstallationDirectories) to the TM server folder.

· Reinstall the service. On Windows, open a command prompt as an administrator and run the file [TMserver folder]\server\bin\service.bat with a parameter of "install"). On RedHat and Solaris, redeploythe old txmanager file (see also Service Creation).

If you did a clean TM installation to a different folder, please follow these steps:

· Run the installer for the old version of Transact Manager and perform a turnkey installation asdescribed in section Running Transact Manager Installer. Make sure the installer does not attempt tocreate the database tables.

Finally, restore the Transact Manager database to the backup and start Transact Manager.

4.9 Upgrade Checklist

To upgrade an existing Transact Manager installation, you will need to do the following:

¨ Obtain Avoka Transact License Keys for each TM environment to be upgraded

¨ Ensure you have the Avoka Transact Manager installer for the old version as well as any customWAR files

¨ Ensure you have the same resources for the new Transact Manager version, as well as theupgrade instructions document specific to the new version, if applicable.

¨ Check the "Upgrade Notes" section in the "Transact Manager Release Notes" document for anyversion specific configuration changes which need to be performed prior to starting the upgradeprocess

¨ Take a backup of the Transact Manager database

¨ If you are doing a clean install rather than a direct upgrade of the current server folder, removethe TM service on Windows or back up the txmanager file on RedHat and Solaris.

¨ Perform a turnkey installation or an in-place upgrade using the new version of the TransactManager installer, reusing the existing database.

¨ Upgrade the Transact Manager LiveCycle application and form server WAR

¨ Start Transact Manager and monitor the log files

¨ Verify the installation was successful

¨ Check the "Upgrade Notes" section in the "Transact Manager Release Notes" document for anyversion specific configuration changes which need to be performed after the upgrade process.



Please follow the more detailed instructions in the previous sections for each step. If an error occursduring the upgrade, please refer to section Rollback Procedures.

Upgrading TM Version NotesTransact Manager Installation Guide


5 Upgrading TM Version Notes

This section details the notes for upgrading configurations from previous versions of Transact Manager. These reviewing and applying the relevant TM version instructions will be require to complete your TMupgrade.

Please note with every major version upgrade you should upgrade Form Space content to pickup anynew feature capabilities or security updates. For instructions on managing and upgrading Form Spacesplease see Transact Knowledge Base article: https://support.avoka.com/kb/display/AT43/Managing+Form+Spaces

5.1 Version 4.0 Upgrade

If you are upgrading a existing Avoka Transact Manager 3.5 or later server to version 4.0 please use theinstaller Setup Wizard upgrade a option. This will enable you to leave any custom portals and not haveto back and restore them while performing an upgrade.

Upgrading Existing Self Service Portals Web Plug-in modules

Transact Manager 4.0 is backwardly compatible with version 3.6 Portals and Web Plug-in modules(without customized Java code) and should work without any changes.

Existing portals will need to be recreated as version 4.0 portals if:

· they include customized Java code or classes under WEB-INF/classes

· they were created with Transact Manager version 3.5 or earlier

Upgrading Portals and Web Plugin Modules

Transact Manager 4.0 is backwardly compatible with version 3.6 Portals and Web Plug-in modules(without customized Java code) and should work without any changes.

Existing portals will need to be recreated as version 4.0 portals if:

· they include customized Java code or classes under WEB-INF/classes

· they were created with Transact Manager version 3.5 or earlier

Mobile FieldWorker Changes

The "Mobile FieldWorker" portal module has been renamed "TransactField App" in Transact Manager4.0. The default portal context path of this module does not change and remains "field-worker".

Two new Portal Properties have been added to control client behavior. These properties are:

· "Client Sync Mode" - specifies when the client app will perform syncing operations [ Immediate |Background | Manual | Editable ]

· "Client Sync WIFI Only" - specifies whether the client app will only sync when WiFi networks areavailable [ On | Off | Editable ]

The default values for these Portal Properties are 'Editable' which means the client app user can editthese settings on their device. The default values on the client app are:

· "Client Sync Mode" = Background

· "Client Sync WIFI Only" = Off

https://support.avoka.com/kb/display/AT43/Managing+Form+Spaces

https://support.avoka.com/kb/display/AT43/Managing+Form+Spaces



TransactField App Preferences

To maintain the equivalent client synchronization settings as Transact 3.6, you should set the PortalProperties as:

· "Client Sync Mode" = Immediate

· "Client Sync WIFI Only" = Off

Upgrading customized FieldWorker modules

If you have a customized FieldWorker WAR file, which may specify a different web context path, theywill need to recreate these in version 4.0.

To do this please ensure you:

1. copy version 4.0 "avoka-sf-field-worker.war" file and give it a unique name which includes the newcontext path

2. open the new WAR file and edit the file WEB-INF/jboss-web.xml and replace the <context-root>value with your customized context path

3. open the new WAR file and edit the file WEB-INF/classes/db-config1.xml and replace the <context-path> value with your customized context path

Email Templates

Transact Manager 4.0 introduces improved Email Templating which can be configured via Portal andOrganization Properties. To ensure no changes are made to existing email customized templates, thischange is only introduced in newly created Portals.

Improved email templating is controlled via the 2 new Portal Properties:

· "Email Template Mode" - specifies whether to use the Email Template HTML to wrap the emailmessage content [ Template | None ]

· "Email Template HTML" - specifies the border email template HTML, which will wrap existing emailmessage content if "Email Template Mode" is "Template"

If you want to introduce this email templating capability into an existing Portal you will need to copydefine these 2 properties in your portal.

GroovyScript Java API Changes

While we work very hard to ensure backward compatibility with existing Groovy scripts, we occasionallyhave at make breaking changes to upgrade the platform.



This version has a small number of changes to the Java Task API which may require retesting someexisting Groovy scripts. These changes include:

1. Task entity has been merged into the Submission entity, existing Task attributes are supported inthe Submission entity but with all the attributes being prefixed with task

2. TaskService methods will now return a Submission entity instead of a Task entity

3. TaskDao class has been removed, and its methods have been migrated into the SubmissionDao

This version introduces a new SubmissionDataService class which can be used by Groovy scripts to makechanges to submission XML data in a secure and controlled manner. If you have Groovy scriptsperforming submission XML data modifications through unpublished API method it is likely they will beblocked and you will need to modify your scripts to use this new SubmissionDataService class.

Receipt Numbers

Transact Manager 4.0 introduces an additional tracking number that can be used alongside the receiptnumber. By default, your forms will be configured to use the receipt number throughout (the "UseReceipt No. for Tracking Code" checkbox on the screenshot below).

Please refer to the TM Administration Guide, chapter "Form Configuration", section "Tracking Code andReceipt Number" for more details.

if you have any custom receipt number services, please review them to check whether they are usingthe "submissionXml" parameter. In TM 4.0, if a form is configured to use the receipt number for thetracking code, the receipt number service is called when the form is opened, at which point thesubmission XML is an empty string. Any custom receipt number service used in this context needs toaccess the submissionXml only if it is not an empty string. Otherwise parsing errors may occur.


When upgrading an existing TM server to TM version 4.1 please review the previous upgrade notes(since your TM version) and review the upgrade notes below.



Apache Mod Security Changes

In TM 4.1 an Apache Mod Security configuration files has been modified to increase the maximumrequest body size to 50 MB to avoid errors during form submission.

This change cannot be applied by the TM installer; instead, instructions to deploy the updatedconfiguration file to Apache, please see Upgrading Apache Configuration.

Portal and TransactField App Modules

Web Portal and Web Plug-in Modules

A number of fixes have been performed to the Web Portal content. It is recommended that you re-create your Web Portal WAR using the Transact Manager Setup Wizard and deploy the updated WAR fileto your server. This will then update your Portals Page and Resources base content, which you can thenreview and elect to pickup changes in the TM Management Console.

Below is a list of Portal resource base content changes which is highlighted by the red Last Modifiedcolumn.

Portal Base Content Changes

Next click on the red arrow butt to review the content changes.



Compare Portal Content Changes

If your portal contains custom Java classes and is not a pure content WAR file they you should recompileyou Portal project as a new Transact 4.1 portal. If you don't to this it is likely your portal will experienceJava class linkage errors when it runs, complaining of missing Java methods. To recompile your Portalrun the Transact Manager 4.1 Setup Wizard to create a new Java portal project and incorporate yourcustom changes into this project.

Next run the ant task to create a new WAR file and then deploy this to your TM server.

Custom TransactField App WAR files

Your TransactField App WAR file will be automatically replaced with the latest version when you run theinstaller. However if you have created a custom TransactField App WAR file with a different name, thenyou will need to replace these with a version 4.1 copy. To do this make the following changes:

1. Note the TransactField App WAR file name, the configured Portal name and its context path. You will need these values later

2. Backup your existing custom TransactField App WAR to another directory

3. Copy the default TransactField 4.1 WAR file to another directory: /transact/manager/server/standalone/deployments/avoka-sf-field-worker.war

4. Rename the copied TransactField 4.1 WAR file to the name of your previous custom WAR file

5. Open the WAR file using Zip file editing tool, e.g. 7-Zip

6. Edit the internal file \WEB-INF\jboss-web.xml and set the <context-root>field-worker</context-root> element content to the correct context path value.

7. Edit the internal file \WEB-INF\classes\db-config1.xml and set the <portalname="TransactField App"> attribute content to the correct portal name.

8. Deploy the customized TransactField App WAR file to your TM application server.



Job Task Assign API Changes

The Job Task Assign Service API has changed in version 4.1.

These changes include a new mandatory property 'Task Type' which specific what type of Task should beassigned. The valid types include 'Form', 'Review' and 'Anonymous'. Existing job definitions much beupdated to add the new 'Task Type' property for them to work, otherwise the Job Action will go into an'Error' state. If this happens you should update the job definition and the retry processing the job.

Parameter Name Required Description

Task Type Yes specify the type of task [ Form | Review | Anonymous ]

Task Form XML Data specify the form XML data for all types of ta

Task Input XML Prefil l specify the input XML prefil l for all types of tasks

Task AttachmentsPrevious Step

where to copy the attachments from

Task AttachmentsSubmission Step

specify whether to copy the attachments from the submission step

Data Retention Policy Change

TM allows you to set retention policies for data in your system, such as submission and error log data.Data older than the maximum age specified in the policies will be automatically purged. Some dataretention settings can be overridden on the organization level.

In TM 4.0, it was possible to set a global flag ("Enforce Global Threshold" on "System > Data RetentionManagement") that made it impossible for organization policies to be more lenient (i.e. keep data forlonger) than the global policies. This can help you ensure that a global hard limit of keeping submissiondata is adhered to throughout.

TM 4.1 makes the following changes:

· The same retention settings that can be overridden on the organization level can now also beoverridden on the form level. In other words, every form can potentially specify its ownretention policies for submission data. To access form level retention settings, edit the formand switch to the "Details" tab. By default, all forms will use the default retention policiesdefined on the organization and globally.

· The flag "Enforce Global Threshold" has been renamed to "Enforce System/Organization



Thresholds" has been switched on for all TM 4.1 servers. You can turn it off by accessing "System> Data Retention Management". We recommend that you leave the flag turned on if you wouldlike to enforce hard limits on submission data retention.

Transaction Processing

To decrease contention and streamline submission processing, TM 4.1 introduces a single job (named"Transaction Processing") to replace the following jobs:

· Receipt Render

· Submission Abandonment

· Submission Delivery

· Task Expiry

· Transaction History Creation

The aforementioned jobs will be automatically removed during the upgrade to TM 4.1. As the new jobtakes over their functionality, it needs to run frequently (by default every 5 minutes) and should not bepaused unnecessarily as this will stop submission processing.

The "Transaction Processing" job calls the default service of type "Transaction Processor", whichperforms the submission steps in the following order:

1. Abandonment

2. Receipting

3. Delivery

4. Task expiry

5. Transaction history creation

Each of these steps may be disabled temporarily by editing service parameters, but again, this willcause a backlog in submission processing and must be used with caution.



Service parameters for the "Transaction Processor" service

No manual upgrade steps are required for this feature, unless you would like to adjust the job runinterval or service parameters.

Error Log Service Change

Previously, the error log service in TM would in some circumstances roll back the current databasetransaction prior to logging the error. As this code can be called from Groovy services, we have removedthe rollback behavior completely to avoid accidentally rolling back a transaction.

If you have been using the error log service (com.avoka.fc.core.service.ErrorLogService) in your Groovyscripts, you need to make script changes only if you the scripts were actively using and relying on thetransaction rollback performed by the error log service. In that case, perform a rollback manually priorto logging the error. Otherwise, you do not need to modify your scripts at this point.

Do note that the following methods in the error log service have been deprecated and may be removedin a future version of TM:

public ErrorLog logException(Throwable error, boolean autoRollback)

public ErrorLog logException(Throwable error, HttpServletRequest request, boolean autoRollback, Submission submission)

public ErrorLog logException(Throwable error, HttpServletRequest request, boolean autoRollback, Submission submission, EmailQueue emailQueue)

public ErrorLog logExceptionNoRollback(Throwable error, Submission submission)

public ErrorLog logExceptionNoRollback(Throwable error, EmailQueue emailQueue)

public ErrorLog logExceptionNoRollback(Throwable error, HttpServletRequest request)

In all cases, the methods that can be used instead are listed in the Javadoc.

Forms Client Web Service Deprecation

The Forms Client Web Service has been deprecated in TM 4.1. It can still be used but may be removed ina future release.

This web service has been used used by TM to deliver submissions (WS Push only) and obtain prefilldata, generally from a TIA instance. The Transact Web Service Guide contains more information aboutthe methods supported by the Forms Client Web Service.

With the introduction of customizable Groovy services, there is no longer a need for a hard coded web



service API to perform these functions. If you are currently using the Forms Client Web Service, you canupgrade to TM 4.1 without needing to make changes; as it may be removed in future releases, however,do not expand its use and make plans to replace it with custom prefill/receipt number/deliveryservices.

Note that the Forms Server Web Service, which is a service TM exposes for TIA or custom clients toretrieve submission data, is not being deprecated or modified in any way. You can continue using WSPull delivery as previously.



Additional Font for Linux Servers

Font substitution errors can occur when rendering forms and receipts, when the form was designedusing Windows fonts which are not present on the Linux server.

The TM installer includes a package of Microsoft Core TrueType fonts. If you have questions aboutMicrosoft Windows font licensing please see:


Installation instructions for additional fonts on Centos 6.3 are as follows:

1. Unzip msttcore font package at[TM artifacts folder]/linux/msttcore.zip

to:/usr/share/fonts

2. Execute the following command:sudo fc-cache -fv

Adding libicu to Linux Servers

Transact Manager includes a PhantomJS receipt rendering module. For this module to work correctly ona Linux server, the libicu library has to be present.

To install the library, run the following command:

sudo yum install libicu

Upgrade License Configuration

Avoka Transact 4.2 includes a automated license compliance reporting system, relieving IT staff fromhaving to provided these licensing reports manually. To enable this automated license reportingrequires configuration settings by administrators when the login to an upgraded TM system.

After logging in administrators will be presented with the System Licensing screen where you will berequired to provide the Avoka Transact Licensee Name and specify whether the Transact EnvironmentType is a Production or Non-Production as in your license agreement.

Non-Production systems include UAT, Test and Development servers but do not include servers used toprovide any customer or staff sales and service transactions.




System License Page

For customers with on premise Avoka Transact deployments there is an option to use Manual LicenseReporting.

Manual License Reporting

To use the manual reporting option you will need to:

1. Deselect the Auto License Reporting option

2. Click on the "Request Manual License Reporting Key" email link, and send an email to youraccount representative requesting and obtain an manual reporting key

3. Enter the obtained key in the "Manual License Reporting Key" field

4. Specify a shared directory where all Transact Manager server nodes can write license reportingfiles to

5. Provide license reporting files to Avoka on a monthly basis.

If you have to use manual license reporting you initially set the configuration to automatic, and laterswitch to manual license reporting mode by changing these via the menu "System > System Licensing".

Form Web Portal Changes

The following Form Web Portal content changes have been made in TM 4.2 since version 4.1:

Page or Resource Path Content Changes

border-template.htm (Page) added 2FA support



cl ick/error.htm (Page) escaped displayed error message va lues

create-account.htm (Page) made eSignagure field display configurable

error.htm (Page) escaped displayed error message va lues

login.htm (Page) added 2FA support

secure/account/account-deta i l .htm (Page) added support for disabl ing user profi le edi ting

secure/account/jobs .htm (Page) search field width tweak

secure/account/submiss ion.htm (Page) changed group fi l ter label and tweaked layout

/resources/css/s tyle.css (Resource) added .icon-revert image s tyle

/resources/images/Avoka_Icon_Set_32.png (Resource) added revert i con to image set

/resources/includes/account/sub-header.html (Resource)

added support for disabl ing user profi le edi ting

/resources/includes/account/ti le-help-desk.html (Resource)

added form abandonment information

/resources/includes/account/ti le-todo.html (Resource) added task cla iming and revert support

/resources/includes/account/header.html (Resource) added support for disabl ing user profi le edi ting

For Transact deployments with Portals containing custom Java classes in the WAR file, they will need tobe recompiled to ensure any Transact 4.2 Java API changes are updated in custom Java code. Pleasecontact Avoka Support to obtain an TM version 4.2 Portal Java source code to merge with your customJava project. Please note we recommend that customers migrate off customized Java Portals to enablean easier an upgrade process.

TM Portal Java source code will only be provide to existing customers with custom Java projects, andwill not be made a available for new Java custom portals.



Apache Config Changes

In TM 4.3 new Apache Mod Security OS Command and SQL Injection protection rules have been added,and changes have been made to Mod Proxy configuration.

This change cannot be applied by the TM installer; instead, instructions to deploy the updatedconfiguration file to Apache, please see Upgrading Apache Configuration.

Form Work Space Changes

The following Form Work Space and Web-Plugin (Portal) content changes have been made in TM 4.3.4since version 4.2:


border-template.htm (Page) upgraded jQuery to 1.12.1

confi rmation.htm (Page) fixed typo



create-account.htm (Page) added Cross Frame Scripting (XFS) attack protection,removed ini tia l focus on user name field

form-attachments .htm (Page) number formatting adjustments

hosted-payment.htm (Page) added support for respons ive page layout support forsmal l screen devices

index.htm (Page) hide create account l ink i f Securi ty Manager does nota l low user account creation; a lso changed space nameand wording

landing.htm (Page) Adobe Reader wording adjustment and resource l inkupdate

login.htm (Page) added Cross Frame Scripting (XFS) attack protection

not-supported.htm (Page) added page to be displayed when an unsupportedbrowser i s used

/secure/change-password.htm (Page) added Cross Frame Scripting (XFS) attack protection

/secure/account/account-deta i l .htm (Page) added Cross Frame Scripting (XFS) attack protection

/secure/account/change-password.htm (Page) added Cross Frame Scripting (XFS) attack protection

/secure/account/help-desk.htm (Page) reworked search field order

/secure/account/home.htm (Page) added support for configurable "Account Quick Lis tsEnabled" porta l property

/secure/account/jobs .htm (Page) added support for "My Jobs" and date search fi l ter

/secure/account/profi le-edi t.htm (Page) added Cross Frame Scripting (XFS) attack protection

/secure/account/submiss ion.htm (Page) added support for new Groups search fi l ter

/secure/account/todo.htm (Page) added support for new Groups and Start Date searchfi l ters

/resources/includes/footer-panel .htm (Resource) improved search fi l ters layout

/resources/includes/account/sub-header.html(Resource)

fixed iOS 8.x menu padding i ssue

/resources/includes/account/ti le-submiss ion.html(Resource)

fixed ORM query performance i ssue; changed form nameresolution to a lways use the current name

/resources/includes/account/ti le-todo-min.html(Resource)

fix task display for Home page ti le rol lover mousepopups

/resources/js/header-menu-a jax.js (Resource) upgraded jQuery to 1.12.1

/resources/js/jquery-1.12.1.min.js (Resource) upgraded jQuery to 1.12.1

/resources/js/jquery.blockUI-2.70.js (Resource) upgraded jQuery to 1.12.1

/resources/js/searchTable.js (Resource) upgraded jQuery to 1.12.1

Important Note:

For Transact deployments with Portals containing custom Java classes in the WAR file, they will need tobe recompiled to ensure any Transact 4.3 Java API changes are updated in custom Java code. Please



contact Avoka Support to obtain an TM version 4.3 Portal Java source code to merge with your customJava project. Please note we recommend that customers migrate off customized Java Portals to enablean easier an upgrade process.

Please note minor TM 4.3.x upgrades with custom Java classes will also need to be recompiled to ensureany API changes are accounted form.

TM Portal Java source code will only be provide to existing customers with custom Java projects, andwill not be made available for new Java custom portals.

Brower Support Changes

In TM 4.3.3 the Browser Support Policy has been changed to activity prevent end user from usingunsupported legacy browsers to complete transactions. The unsupported browsers include:

· Microsoft Internet Explore 8.0



These browsers are no longer supported by Microsoft, please see the Microsoft Internet Explorersupport statement below:

· https://www.microsoft.com/en-au/WindowsForBusiness/End-of-IE-support

As Microsoft no longer provide security patches or fixes for zero day exploits for these browser, andthey now pose a significant security risk and liability risk to customers and end users.

In addition, these legacy browsers do not support modern security standards required for securitytransactions including:

· TLS 1.2 which is required for secure credit card transactions (PCI policy)

· Content Security Policy (CSP) to prevent JavaScript injection (XSS) attacks

With Avoka Transact 4.3.3 and later customers must explicitly configure their environments to supportIE10, IE9 or IE8. The default Transact Manager configuration does not support these browsers. Customers enabling support for legacy browsers do so at their own risk.

Browser Support Configuration

The default Transact Browser support policies can be configured at a global or system wide level via the'Form Submission Access Controller' service, or at an Organization level in the new OrganizationSecurity tab.

These configuration options allow you to explicitly support IE 10, IE 9 or IE 8.

https://www.microsoft.com/en-au/WindowsForBusiness/End-of-IE-support



Unsupported Browsers Page

If a end user with an unsupported browser attempts to open a form they will be redirected to a newForm Space "Not Supported" browsers page. This page will provide instructions to the user on how tocomplete the transaction using a supported browser and provide them with messaging as to why theirbrowser is not supported.

Customers can tailor the content of this page to provided their own messaging.

Data Retention Policy Changes

In TM 4.3.3, data retention policies have seen significant rework as well as performance improvement.This section describes what you should do during and after the upgrade; please refer to https://support.avoka.com/kb/display/AT43/Data+Retention+Management for details on data retention in TM.

When running the installer, you will be presented with the new "Data Retention Policy Mode" screen.





Data Retention Policy Mode screen

Use "Relaxed" if you want to keep the existing restrictions.

If you would like to tighten up data retention policies for purging personally identifiable information,select "Strict". This will affect the maximum age of transaction data in TM for future transactions. Duringthe upgrade, organization and form data retention settings will be adjusted to the new maximumvalues if necessary.

After upgrading TM to 4.3.4 and restarting the server, log on to the management console and review thedata retention settings at "System > Data Retention Management".

Data retention settings

Note that the settings at the top can now be adjusted freely within the allowable range rather thanchoosing from a set of predefined option. The "Unlimited" setting for transaction data is no longeravailable. TM is not intended to be a long-term repository for transaction data (which containspersonally identifiable information); rather, transaction data is delivered to other systems and can be



purged from TM afterwards.

There is now a setting for purging of finished collaboration jobs and associated submissions ("FinishedCollaboration Jobs (days)").

Again, please refer to https://support.avoka.com/kb/display/AT43/Data+Retention+Management for anexplanation of exactly how the settings work.

If you make any changes, save and click "Apply Policy" to update existing entities in TM (e.g.transactions).

If you have defined data retention policies on the organization and/or form levels, you may wish toreview and adjust these settings as well.

To see what data retention policy mode was chosen at installation/upgrade time, go to "System >System Info" and look at the value of the build property named "data,retention.policy").

IMPORTANT NOTE:

The Finished Collaboration Jobs policy is new and has a default setting of 180 days for finishedcollaboration jobs (status: Completed, Canceled, Expired'). Finished jobs and their associatedtransactions older than 180 days will be deleted after the upgrade.

If you have requirements to keep these records for longer that 180 days, you need to perform thefollow actions when you upgrade:

· before performing the upgrade, login to the Management Console, navigate to the System >Scheduled Jobs page, and click on 'Pause All Jobs' (this will prevent data being purged immediatelyafter the upgraded by background scheduled jobs)

· perform upgrade

· after the system has been upgraded, login to the Management Console

· navigate to Data Retention Settings and apply 'Finished Collaboration Jobs' policies for yourbusiness and any other settings required

· navigate to the System > Scheduled Jobs page, and click on 'Resume All Jobs' button




The following Form Web Portal content changes have been made in TM 5.0 since version 4.3:


cl ick/not-found.htm (Page) fixed redirect bug

login.htm (Page) improved access ibi l i ty with error s tate role=alertattributes .

WEB-INF/jboss -deployment-s tructure.xml updated l ibrary module includes

For Transact deployments with Portals containing custom Java classes in the WAR file, they will need tobe recompiled to ensure any Transact 5.0 Java API changes are updated in custom Java code. Pleasecontact Avoka Support to obtain an TM version 5.0 Portal Java source code to merge with your customJava project. Please note we recommend that customers migrate off customized Java Portals to enablean easier an upgrade process.




Please note minor TM 4.3.x upgrades with custom Java classes will also need to be recompiled to ensureany API changes are accounted form.

TM Portal Java source code will only be provide to existing customers with custom Java projects, andwill not be made available for new Java custom portals.

Updated Default Configurations

The following default configuration changes have been made with TM 5.0. New systems will includethese new defaults, while upgrades systems will maintain their existing configurations.

Configuration Description New Value Previous Value

Data Retention -Transaction His tory

Maximum period of time TransactionHis tory records are kept for.

2 years 5 years

Form Submiss ion AccessControl ler - CSP

Service parameter 'Form CSP HeaderValue' which enabled form CSP pol icies .

script-s rc 'sel f';object-s rc 'none'

-



After starting the TM server please check the TM Manager Server Nodes configuration to ensure each ofthe Server Nodes has the correct configurations specified. This is particularly important fordeployments with Adobe LiveCycle integration.


The following Form Web Portal content changes have been made in TM 5.1 compared to 5.0:


confi rmation.htm (Page) formatting change

receipt-chal lenge.htm (Page) new page that i s used to control access to user receiptsunder some ci rcumstances

redirect.jsp securi ty hardening

WEB-INF/cl ick.xml improved XSS protection

WEB-INF/jboss -deployment-s tructure.xml updated l ibrary module includes

Important Note:

When upgrading to TM 5.1, all WAR files need to be rebuilt. The TM installer will take care of thestandard TM modules (Transact Manage, Business Reports) and Form Space (Web Plugiin, Work Space,Maguire) as part of the upgrade.

However, if you have custom work space WAR files, you need to rebuild them by running the installerand choosing the option "Create a Transact Work Space". Please see the Transact online documentationfor more (article "Managing Form Spaces").

Additionally, if you have a T.Field form space deployed, you will need to deploy the updated WAR filemanually. It is located at [TM setup directory]/war/avoka-sf-field-worker.war and needs to be deployed

https://support.avoka.com/kb/display/ATMD5/Managing+Form+Spaces



to [TM server directory]/standalone/deployments.

If you do not ensure that all custom WAR files are rebuilt, your spaces may not work after the upgrade.Please contact Avoka Support with any concerns you have before upgrading your TM server.

Installation ChecklistTransact Manager Installation Guide


6 Installation Checklist

This chapter provides an installation check list to help ensure you complete all the necessary steps toinstall Avoka Transact Manager.

6.1 Install Prerequisites

To perform a complete Transact Manager installation you will need the following items:

¨ Obtain Avoka Transact License Keys for each TM environment to be created or upgraded

¨ Java SE 8u112 server JRE on the target server to run the Transact Manager installer and run theapplication on Linux servers

¨ Avoka Transact Manager installer

¨ Database server, with either MySQL, Oracle or SQL Server

¨ Apache Web Server 2.2.24 or later (optional)

¨ Email server (optional)

¨ LDAP directory server (optional)

¨ Virus scanner server (optional)

6.2 Database Checklist

¨ Create a 'txmanager' database/schema

¨ Create a 'txmanager' database user with sufficient permissions to execute DDL and SQLstatements against the 'txmanager' database/schema

¨ Create the 'txmanager' tables either using the installer or manually using the installer createscript

¨ Ensure the TM server can connect to the database server using TCP with the configured JDBCport

¨ If using MySQL database, please ensure that the initialization parameter 'max_allowed_packet'is set to at least 50M

6.3 Transact Manager Checklist

¨ On Linux servers ensure the Unlimited Strength Java Cryptography Extension (JCE) policy fileshave been deployed into the TM Java SE runtime installation

¨ Harden administrator account access

¨ Configure the deployed Transact Manager portals' context paths

¨ Configure the TM Admin Environment message properties

¨ Configure the LiveCycle server node definitions.

¨ Configure the Transact Manager server node definitions

¨ Configure the LiveCycle service connection details

¨ Configure the email settings



¨ Review and configure data retention policies

¨ Install additional MS fonts on Linux servers

¨ Install libicu library on Linux servers

¨ Ensure Transact Manager server can synchronize its clock with an NTP server, note this can be anissue when TM is deployed behind a proxy server

6.4 Apache Checklist

¨ If the Apache server is performing SSL termination ensure, ServerName is configured inhttpd.conf so that the Transact Integration Gateway (TIG) can call TM Web Services over HTTPS.Security changes in Java 1.8 require the server name to be present during SSL connectionhandshake.

¨ Ensure only the strongest SSL cipher (128 bits and above) is supported on the SSL Terminationdevice (SSL Offloader and/or Apache), and no weak SSL cipher is allowed.

¨ Ensure Apache Mod Proxy modules are enabled and configured, and make sure the proxypassand proxypassreverse settings are configured for the deployed Transact Manager modules andportals

¨ Ensure Apache Mod Cache module is enabled and configured, and make sure the cachingdirectory has been created and configured

¨ Ensure Apache Mod Deflate modules are enabled and configured

¨ Ensure SSL is enabled for production use and system testing.SSL termination can be provided with a smart switch with SSL offloading in front of the Apacheserver (recommended), or by Apache using the mod_ssl module.

¨ Ensure CA issued SSL certificates are installed for production and system testing. Please Note: It is highly recommended that self-signed SSL certificates NOT be used for testingpurposes as Adobe Reader behaves differently with self-signed certificates, and this oftenintroduces numerous complications during system acceptance testing.

¨ If PDF forms are using any Web Services from servers which are not on the same domain as theTM server, then a crossdomain.xml file will need to be deployed on the servers hosting the WebServices.

6.5 ClamAV Checklist

¨ Ensure the ClamAV configuration has maximum file size set to 50MB (StreamMaxLength 50M) andthe service has been restarted to apply this change.

6.6 Security Checklist

¨ Ensure Transact Manager was installed with the "Security Configuration" option to "Use securecookies (HTTPS)"

¨ Ensure external applications are only able to access Transact Manager applications over SSL (port443).

¨ Ensure only the strongest SSL cipher (128 bits and above) is supported on the SSL Terminationdevice (SSL Offloader and/or Apache), and no weak SSL cipher is allowed.

¨ Ensure that firewall rules for the Transact Manager server(s) only allows connections via the



Apache Web Server(s).

¨ Ensure that firewall rules for the Adobe LiveCycle server(s) only allows connections from theTransact Manager server(s) over the configured port, unless there are particular reasons to makethese servers externally available.

¨ Ensure that firewall rules for the database server only allow connections from the TransactManager server(s) over the configured JDBC port.

¨ Ensure that firewall rules for the database server only allow connections from the AdobeLiveCycle server(s) over the configured JDBC port, if the 'adobe' database is hosted on thedatabase server.

¨ Ensure the Transact Manager 'administrator' account is disabled. It is highly recommended thatall administration access is performed through named administrative user accounts, to ensurethat administrator access auditing is available.

¨ Recommend configuring 2 Factor Authentication for Production environments

¨ Ensure the Transact Manager server(s) machine administrator password is hardened.

¨ Ensure the Apache Web server(s) machine administrator password is hardened.

Date post:	30-Apr-2020
Category:	Documents
Upload:	others
View:	16 times
Download:	0 times

Avoka Transact Manager Installation Guide · All rights reserved. No parts of this work may be...

Documents