Avoka Transact Transaction Manager Installation Guide · All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, or mechanical,

Installation GuideVersion 4.3

Avoka Transact

Transaction 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

Transaction Manager Installation Guide

Version 4.3

© 2015 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

................................................................................................................................... 63 Adobe LiveCycle Support

Part III Performing Installation 8

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

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

................................................................................................................................... 273 LiveCycle Server Configuration

................................................................................................................................... 394 Transaction Manager Configuration

................................................................................................................................... 475 TM LiveCycle Services Configuration

................................................................................................................................... 546 Apache Server Configuration (Windows)

................................................................................................................................... 567 Apache Server Configuration (Linux)

................................................................................................................................... 578 Virus Scanner Configuration

Part IV Upgrading Transaction Manager 60

................................................................................................................................... 611 Back up TM Database

................................................................................................................................... 612 Upgrade TM Server Option Setup Steps

................................................................................................................................... 623 Reinstall TM Server Option Setup Steps

................................................................................................................................... 634 Upgrading LiveCycle Modules

................................................................................................................................... 635 Updating the TM Database

................................................................................................................................... 646 Updating Apache Configuration

................................................................................................................................... 657 Finalizing and Verifying the Upgrade

................................................................................................................................... 658 Cleaning up the JDK Folder

................................................................................................................................... 669 Rollback Procedures

................................................................................................................................... 6610 Upgrade Checklist

Part V Upgrading TM Version Notes 68

................................................................................................................................... 681 Version 4.0 Upgrade

................................................................................................................................... 712 Version 4.1 Upgrade

................................................................................................................................... 763 Version 4.2 Upgrade

................................................................................................................................... 794 Version 4.3 Upgrade

Part VI Installation Checklist 80

................................................................................................................................... 801 Install Prerequisites

Transaction Manager Installation Guide

© 2015 Avoka Technologies. All Rights Reserved.

................................................................................................................................... 802 Database Checklist

................................................................................................................................... 803 Transaction Manager Checklist

................................................................................................................................... 814 Apache Checklist

................................................................................................................................... 815 Security Checklist

................................................................................................................................... 826 Adobe LiveCycle Checklist

IntroductionTransaction Manager Installation Guide

© 2015 Avoka Technologies. All Rights Reserved. 5

1 Introduction

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

1.1 Who should read this document?

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

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

If you are installing Transaction Manager on CentOS Linux, Oracle Linux or Red Hat Enterprise Linux orthen you 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 Transaction Manager Installation Guide before commencingyour install

If you are upgrading Transaction Manager please follow instructions in the UpgradingTransaction Manager section before you commence your install

System RequirementsTransaction Manager Installation Guide


2 System Requirements

This section discuss the system requirements for Transaction 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

Oracle Database 12c and 11g

MySQL 5.6 and 5.5 (InnoDB storage engine only)

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 Transaction Manager over HTTPS

Java SE 8u60, 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

Transaction Manager runs best on the Intel x86-64 Xeon CPU architectures with high CPU performance.We recommend server virtualization such as VMware ESX to provide enable better hardware utilizationand improve operational support.

Recommended specification for a server deployed with Avoka Transaction Manager (TM)

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

8 GB of RAM

100 GB of disk storage. Please note SAN storage is not required for server nodes

2.3 Adobe LiveCycle Support

This section describes the requirements for existing customers using Adobe LiveCycle with AvokaTransact.

Avoka Transact supports integration with Adobe LiveCycle ES 3 and ES 4.

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

System RequirementsTransaction Manager Installation Guide


Use of Adobe LiveCycle ES 2.5 is not recommended because of very poor PDF receipt generationperformance.

For information on supported Abobe LiveCycle platforms please see the link below:

https://helpx.adobe.com/livecycle/help/livecycle-es4-supported-platforms.html

Recommended specification for a server deployed with Avoka Transaction Manager (TM) and AdobeLiveCycle (LC)

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

12 GB of RAM

100 GB of disk storage. Please note SAN storage is not required for server nodes

When Adobe LiveCycle Output is used for PDF receipt generation it is highly recommended customersinstall Adobe LiveCycle on the same servers as Avoka Transaction Manager.

Two Servers with TM and LC collocated

LiveCycle Process Management

For systems using Adobe LiveCycle Process Management (PM) for delivery integration or businessworkflows we recommend deploying LiveCycle PM onto a separate server from the LiveCycle Formserver nodes. The persistent LiveCycle PM workflows have very different database and server clusteringrequirements than the stateless LiveCycle form rendering services used by Transaction Manager.

When TM systems are under heavy customer loads, the CPU requirements for LC Output receiptrendering is very high and will negatively impact LiveCycle Process Management performance.

High availability LiveCycle Process Management solution have complex deployment architecturerequirements including: Virtual IP addresses, JEE application server clustering, database serverclustering and shared SAN storage with synchronized SAN and database backup policies. Including TMLC form servers in this complex mix makes diagnosing integration and performance issues difficult.

https://helpx.adobe.com/livecycle/help/livecycle-es4-supported-platforms.html

Performing InstallationTransaction Manager Installation Guide


3 Performing Installation

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

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

3.1 Database Server Configuration

The first step in performing a Transaction 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 Transaction 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 Transaction 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 Transaction 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 Transaction Manager server connects to the SQL Server database using JDBC drivers which use TCP/IP protocol. 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 Transaction 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 Transaction 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 Transaction 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 Transaction 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 theTransaction 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 Transaction Manager installer.

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

grant connect, resource to txmanager;

Creating Tables

Later in the Transaction 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 theTransaction 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 Transaction Manager Setup Wizard will lead you through a series of questions and then perform theTransaction 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 Transaction 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 Transaction Manager installer with administrator privileges("Run as Administrator") so that it can create the Transaction Manager Windows service.



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

Running the Installer

Start the Transaction Manager installer (Avoka-TM-Setup.jar) by opening a console, navigating to thefolder containing the installer and running the following command:

java -jar Avoka-TM-Setup.jar

After running this command you should see a welcome screen displaying the Transaction Managerversion.

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.jar text

Installation Mode

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

Install the Transaction Manager server, or

Upgrade an existing Transaction Manager server (the existing server must be at version 3.5 orlater)

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 Transaction Manager server.



Installation Mode page

Database Server

On the "Database Server" setup page you can choose the type of database server you will use tomanage the Transaction Manager database.

Your choice will be used to configure the Transaction Manager server configuration files andapplications for the specified database. You can later change the database that is used by TM by runningthe installer again (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 ES3 for generation PDF receipts with TransactionManager.

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



PDF Receipt Services page

Server Memory

On the "Transact Server Memory" 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 Transaction Manager on a development or test server with limited memory choosethe 2 GB 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 inTransaction 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 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 "Transaction 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 Transaction 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.

Finally, you can choose to clean up the modules directory in the TM server during an upgrade. This willcause the installer to remove obsolete module JAR files. Please note that during an upgrade, theinstaller will only add and overwrite files in the server directory, but not delete any files, which meansthat obsolete files such as module JAR files will remain. However, this also means that any customadditions you made to the TM server directory (e.g. custom modules or WAR files) will remain in placeafter the upgrade.

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 Portals

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

Install Modules and Portals 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:

Transaction Manager - provides Management Console and Business Report modules

Form Spaces include:

Transact Web Plugin Space - provides default module presenting Web forms

TransactField App Space - provides default module for supporting TransactField App forms

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"which is designed for external server availability monitoring.

The "Maguire Forms and Work Space" option should not be deployed on production systems, howeverfor development and test systems this example content provides an excellent resource.

To create a custom Transact Work Space use the installer option "Create Transact Workspace" and loadthe into your server.

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 Transaction Manager server configuration files and applications



for the 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.

History Database Configuration

On the "History Database Configuration" screen, you can set up database connection details for thedatabase where TM stores transaction history data used in reporting. You can either re-use the main TMdatabase to store transaction history data, or you can specify a different database that may beoptimized for reporting purposes.



History Database Configuration page

By default, the fields will be populated with the values you entered on the "Database Configuration"screen. If you would like to use a different schema, ensure the schema and access rights for thedatabase user have been set up and enter the details.

Note: When doing a fresh install, always tick "Create the database tables". When installing TM 4 to a server which is running an older version of TM, do not tick "Create thedatabase tables". The tables will be created at server startup time.

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 theinstallation.



Installing JDK (Linux only)

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

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

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-8u60-linux-x64.tar.gz

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

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

4. Finally, add the Unlimited Strength Java Cryptography Extension (JCE) policy files to the Javainstallation. These enable Transaction 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 with theinstaller:

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

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

[TM install folder]/jdk1.7.0_80/jre/lib/security

Service Creation

Microsoft Windows

On Microsoft Windows servers the Transaction Manager installer will automatically create a servicenamed "Avoka Transaction Manager". This service will have a startup type of "Automatic" so it will bestarted automatically 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 8u60 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 8u60 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 8u60 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_60/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 Transaction Manager service to apply your changes.




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" and "History DatabaseConfiguration" screens. All TM nodes share 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 asdescribed in section Server Nodes and Service Connections.

3.3 LiveCycle Server Configuration

This optional section is for existing customers using Adobe LiveCycle with Transaction Manager.

Customers not using Adobe LiveCycle should skip this section.

Deploy Form Server WAR

Transaction Manager provides a Form Server module (WAR) which must be deployed onto the AdobeLiveCycle server(s).

This Form Server module is used to communicate with the LiveCycle server(s) across the network. Thismodule provides Transaction Manager with a LiveCycle process invocation proxy, and also provides loadbalancing and server health metrics information.

Please follow the deployment instructions for the application server used to run Adobe LiveCycle.

Installing Form Server to Adobe LC on JBoss

Shut down Adobe LiveCycle and wait until the shutdown has been completed.

Copy the file:

[TM artifacts folder]/livecycle/avoka-tm-form-server.ear

to the directory:

[LiveCycle install folder]/jboss/server/lc_turnkey/deploy/deploy.last

Please Note: You will probably need to create the deploy.last directory under the deploy directory. Thisensures the module is started after all the Adobe applications have finished starting.

The JBoss server directory may be aep_turnkey on Adobe Digital Enterprise Platform (ADEP) versionsof LiveCycle:

[LiveCycle install folder]/jboss/server/aep_turnkey/deploy/deploy.last



Restart Adobe LiveCycle and monitor the log files to ensure the module is loaded without issues.

The Transaction Manager Form Server module is mounted to the context: /form-server

http://server-name:8080/form-server/

Installing Form Server to Adobe LC on WebLogic

Create a folder named "tm-ears" in

[BEA root folder]\user_projects\domains\[domain name]

(for a standard install, this would be

C:\bea\user_projects\domains\base_domain)

Copy the file

[TM artifacts folder]/livecycle/avoka-tm-form-server.ear

to the tm-ears directory.

Log on to the WebLogic administration console for the LiveCycle server.

Click "Lock and Edit" and navigate to "Deployments". Click the "Install" button. Click "Upload your file"and select the EAR file copied to tm-ears.

Uploading the Form Server module to WebLogic

Click "Next". You should see a message that the file has been uploaded successfully.

Click "Next".

Ensure "Install this deployment as an application" is selected and click "Next". You will see a list oftarget servers you can deploy to.

Tick the server representing your Adobe LiveCycle installation (see below for an example) and click"Next" twice.

http://server-name:8080/form-server/



Selecting the server to deploy the Form Server module to

Ensure that "Yes, take me to the deployment's configuration screen" is selected and click "Finish".

On the deployment configuration screen, enter a deployment order of 110 to ensure that the module isstarted after LiveCycle.

Click "Save" and then "Activate Changes".

Go back to the "Deployments" screen and start the new deployment (avoka-tm-form-server).

Installing Form Server to Adobe LC on IBM WebSphere

Login to the WebSphere administration console, then navigate to the WebSphere enterpriseapplications page.

Naviage to the Enterprise Applications page in the administration console

Click on the "Install" button and browser to the avoka-tm-form-server.ear file in the install folder, clickon the "Next" button and then choose "Fast Path".

[TM install folder]/livecycle/avoka-tm-form-server.ear



On the "Install New Application" page select the "Avoka Transaction Manager - Form Server" webmodule and click on the "Next" button.

Install New Application configuration

Now select the Virtual host to deploy the form server on and click the "Next" button.

Select the Virtual Host

Next click on the "Finish" button on the summary page. Finally to start the application select the avoka-tm-form-server-ear in the application list and click on the "Start" button.



Start the Form Server application

Install LiveCycle Archive

The next step is to install the Transaction Manager LiveCycle Archive (LCA) file. The LCA file used byTransaction Manager contains processes for integrating with LiveCycle.

To install the Transaction Manager LCA file log in to the LiveCycle ES Admin UI commonly found at:

http://hostname:8080/adminui/ (JBoss)

http://hostname:7001/adminui/ (WebLogic)

http://hostname:9080/adminui/ (WebSphere)

This web application should be running on the LiveCycle ES server. Log in using the administratorcredentials configured when the LiveCycle ES server was installed.

Go to "Services > Applications and Services > Application Management". You will see the list ofLiveCycle applications currently installed on your system.

http://hostname:8080/adminui/





Deployed LiveCycle applications

Click "Import" and upload the Transaction Manager LCA file

[TM artifacts folder]/livecycle/avoka-tm-4.0-es2.lca

Click "Preview" and review the information shown on the next screen. Tick the check box "Deployassets to runtime when import is complete" and click "Import".

Previewing the SmartForm Manager LiveCycle application

You should then see "FormCenter" (Avoka Transaction Manager application processes) in the list ofapplications.



Install Reader Extensions Certificate

If you want Transaction Manager to Reader extend PDF forms during the rendering process, you need toinstall a Reader Extensions certificate. Render extended PDF forms can be saved offline, make WebService calls and use 2D bar codes.

If you are have Transaction Manager with the Adobe LiveCycle OEM license, then Avoka Technologiescan provide you with the Reader Extension certificate. Otherwise you will need to obtain the ReaderExtension certificate from Adobe.

To install a Reader Extensions certificate, access the LiveCycle Admin UI again.

Navigate to "Settings > Trust Store Settings > Local Credentials".

Click "Import" and fill in the form as shown below:

Importing the Reader Extensions certificate

The alias has to be "FORMCENTERRECREDENTIAL". Upload your Reader extension credential (typically a.pfx or .p12 file) and enter the password associated with your credential.

Click "OK" and review the credential, which should now be displayed in the list. If you want to renamethe alias, you will also need to rename it in the Transaction Manager LiveCycle application processes.

System Settings

To ensure optimal system performance there are a number of low level LiveCycle configuration settingsyou should make.

Default Document Max Inline Size

LiveCycle provides a system setting called the "Document Default Max Inline Size" which determinesthe maximum size of Documents stored in memory before they are written out to the file system.Keeping rendered PDF form and receipt documents in memory significantly improves applicationperformance, as RAM access time is much faster that disk I/O.

The default LiveCycle "Document Default Max Inline Size" setting is 64 KB, which is far too small. It isrecommended that this value be changed to 10 MB, which should ensure any PDF documents beingrendered stay in memory. Please note when LiveCycle generates PDF/A documents there may betemporary files which are much larger that the final output file.



To change this setting globally you need to set a JVM argument on the LiveCycle service:

-Dcom.adobe.idp.defaultMaxInlineSize

On the JBoss application server you can configure this setting in the

[LiveCycle folder]/jboss/bin/run.conf.bat

file by adding a JAVA_OPTS parameter:

set "JAVA_OPTS=%JAVA_OPTS% -Dcom.adobe.idp.defaultMaxInlineSize=10485760"

If this value is configured correctly you will see its value logged in the boot log file [LiveCycle folder]\jboss\server\adep_turnkey\log\boot.log

On the WebLogic application server you can configure this setting in the WebLogic AdministrationConsole under the LiveCycle Server > Configuration > Server Start page in the Arguments configurationfield.

Setting JVM Argument on WebLogic

XML Pool Max Size

The LiveCycle application server uses native processes (XMLForm) for performing some PDF operations.To improve system performance LiveCycle manages a pool of XMLForm process instances, with thedefault maximum pool size of 4 instances.

The optimal maximum number of XMLForm instances is 1.5 - 2 x number of CPU cores on the server. Ifthe server is being used exclusively LiveCycle Forms or LiveCycle Output then use 2 x the number ofCPU cores. However if the server is hosting a TM service as well then use the 1.5 x number of CPU cores.So a 4 core server used exclusively for LiveCycle should have a max XMLForm pool size of 8.



To change this setting globally you need to set a JVM argument on the LiveCycle service:

-Dcom.adobe.xmlform.bmc.POOL_MAX=8


[LiveCycle]/jboss/bin/run.conf.bat

file by adding a JAVA_OPTS parameter

set "JAVA_OPTS=%JAVA_OPTS% -Dcom.adobe.xmlform.bmc.POOL_MAX=8"

On the WebLogic application server you can configure this setting in the WebLogic AdministrationConsole under the LiveCycle Server > Configuration > Server Start page in the Arguments configurationfield.

For information about XMLForm settings please see:

http://blogs.adobe.com/livecycle/2010/12/native-c-components-of-livecycle.html

Database Connection Pool Settings

The default LiveCycle database connection pool maximum size in 30. This setting is too low for very highload scenarios, and this value should be increased to 100 connections.


[LiveCycle]/jboss/server/adep_turnkey/deploy/adobe-ds.xml

file by editing the <max-pool-size> elements:

Settting max-pool-size in LiveCycle Connection Pool

On the WebLogic application server you can configure this setting in the WebLogic AdministrationConsole by editing the data source and navigating to Configuration > Connection Pool.

http://blogs.adobe.com/livecycle/2010/12/native-c-components-of-livecycle.html



Setting WebLogic Connection Pool Size

LiveCycle Temp Directory Location

You should ensure the LiveCycle temp directory is not located under the Windows directory, and isunder a drive which has plenty of storage space for temporary files.

LiveCycle Temporary Files Directory

LiveCycle Backup Mode Setting

LiveCycle has a mode to enable database backups where it does not delete temporary files from theGlobal Document Storage (GDS) and TEMP directories while the database backup is being performed.This is to ensure the database accurately reflects the state of the GDS directory. This mode howevershould not be left on as it will prevent LiveCycle from purging old files, and over time the build up of



temporary files can fill up storage drives and cause system outages.

Ensure LiveCycle Backup Mode is switched off

XMLForm Logging

On production servers the XMLForm process can generate a lot of WARN level messages when renderingPDF receipts and executing the forms' JavaScript. These messages can obscure useful logging messagesand lead to excessive log file growth.

On JBoss production servers it is recommended that you adjust the default com.adobe category toWARN, and add a category filter for the XMLFormService. To do this, edit the Log4J configuration file:

[LiveCycle]\jboss\server\aep_turnkey\conf\jboss-log4j.xml

Add / edit the com.adobe category and add a category filter for com.adobe.document.XMLFormService

<category name="com.adobe"> <priority value="WARN"/> </category> <category name="com.adobe.document.XMLFormService"> <priority value="ERROR"/> </category>

On the WebLogic application server you can configure the global application logging level in theWebLogic Administration Console under the LiveCycle Server > Logging > General page by showing theAdvanced options and setting the "Minimum severity to log". This value should be set to "Warn" onproduction servers.



Configure WebLogic Global Logging Level

Please note that the default LiveCycle logging levels are fine for development and testing purposes.

Linux Server Configuration

For Adobe LiveCycle deployed on RedHat or CentOS Enterprise Linux there are some additional systemchanges which need to be performed to ensure LiveCycle can render PDF documents.

Additional Libraries

The native Adobe XMLForm.exe has dependencies on the following Linux shared libraries to renderPDF/A documents. To install these libraries use YUM package manager:

yum install glibc.i686

yum install libgcc.i686

yum install libX11.i686

Below is an example LiveCycle error log you will see when these libraries are not present:

ERROR [STDERR] (ProcessResource@c4d36fb(name=XMLForm.exe,pid=0) Error Reader)

/data/adobe/es3/jboss/server/lc_mysql/svcnative/XMLFormService/bin/XMLForm.exe:

/data/adobe/es3/jboss/server/lc_mysql/svcnative/XMLFormService/bin/XMLForm: /lib/ld-linux.so.2: bad ELF interpreter: No such file or directory



Additional Fonts

As part of section Installing Additional Fonts (Linux Only), MS Core TT Fonts were already added to thesystem. Please copy the fonts from

/usr/share/fonts/msttcore

to the Adobe LiveCycle fonts directory, e.g.

/data/adobe/es3/fonts/msttcore

Restart the LiveCycle service to apply the changes.

3.4 Transaction Manager Configuration

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

Starting the TM Service

Please Note: Before starting Transaction Manager you will need to ensure your database schema hasbeen already created.

To start Transaction Manager please open the Windows Services Management Console, select the"Avoka Transaction 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 Transaction 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 the



nature of the upgrades.

To monitor the progress of the Transaction 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 Transaction Manager Management Console using the default administrator user with thecredentials: administrator / password .

http://localhost:9080/manager/

Log into TM Management Console

The next screen you will be presented is the change password screen where you will need to changethe root administrator password. Default password rules will require a minimum of 8 characters and amix of letters and digits.

Changing the administrator password

After changing the administrator password, you will be presented with the System Licensing screenwhere you will be required to provide the Avoka Transact Licensee Name and specify whether theTransact Environment Type 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.

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

http://localhost:9080/manager/



System License Page

This information is used to provide automated license compliance reporting to Avoka. For customerswith on premise Avoka Transact deployments there is an option to use Manual License Reporting.

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 your accountrepresentative 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 Transaction 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".

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



TM Management Console home page

Hardening Administrator Access

One of the first things you should do with your Transaction 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.

Transaction Manager will automatically enforce the first approach, but the second is also recommendedas this provides tighter security access control, and auditing information (automatically maintained byTM) 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" so they canmanager multiple organizations.



Configure Enable Global Access to 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



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

Configure Email Settings

Transaction Manager needs an email server to be configured to enable it to send emails. To specify thedetails of your email server navigate to "System > Email Settings" and enter the configuration values foryour 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

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

When Transaction Manager starts for the first time it will use pre-configured data retentionmanagement policies, so it is important that you review these policies and ensure they meet yourbusiness objectives.

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 Transaction Manager.

3.5 TM LiveCycle Services Configuration

This optional section is for existing customers using Adobe LiveCycle with Transaction Manager. Customers not using Adobe LiveCycle should skip this section.

If you are deploying Avoka Transaction Manager with Adobe LiveCycle then you man need to performsome additional configurations depending upon your deployment topology.

With Avoka Transaction Manager server nodes are defined for the Transaction Manager and LiveCycleJava server processes. This information is used by Transaction Manager to make calls to LiveCycleservers and also to enable logging of performance and system health information.

Avoka Transaction Manager and Adobe LiveCycle servers can be deployed in a number of deploymentmodels, which require corresponding Server Node configurations to be defined.

Single Server Deployment Model

The simplest deployment model is a single server configuration with Apache, Avoka TM and Adobe LCall installed on the same server host. This deployment model is depicted in the diagram below.

When Avoka TM and Adobe LC are installed on the same server host, it is often referred to as a



collocated installation.

Single Server with TM and LC collocated

With this deployment model the TM Server Node definitions will be automatically created when theserver starts running. The server node name, server URL and group will be based on the serverhostname.

Server Node configuration of Single Server with TM and LC collocated

Two Server Deployment Model

The next deployment model has two servers both configured with Apache, Avoka TM and Adobe LCinstalled on two server hosts. This deployment model is depicted in the diagram below.

Again as Avoka TM and Adobe LC are installed on the same server hosts, it is often referred to as acollocated installation.

In front of the two servers is a smart switch which will balance the load across the two servers withsticky sessions. This deployment model provides high availability (HA) as the loss of a single servernode will not halt the service.



Two Servers with TM and LC collocated

With this deployment model the TM Server Node definitions will be automatically created when theserver starts running. The server node name, server URL and group will be based on the serverhostname.

Server Node configuration of Two Servers with TM and LC collocated

Four Server Deployment Model

The next deployment model has four servers two configured with Apache and Avoka TM, and anothertwo servers configured with Adobe LC. This deployment model is depicted in the diagram below.

In front of the two TM servers is a smart switch which will balance the load across these two serverswith sticky sessions. Behind these servers we have two LC servers, with the TM servers load balancingtraffic between them. If a LC becomes unavailable the TM servers will direct traffic to the other server.This deployment model provides high availability (HA) as the loss of a TM or LC server node will not haltthe service.

For general HA requirements we recommend the previous model, as it is easier to configure andmanage. However if you have very heavy PDF form rendering requirements and/or LC CPU basedlicensing you may wish to use this deployment model.



Four Servers with TM and LC split

To configure Server Nodes for this deployment model you will first need to change a System >Deployment Property named "LC Form Servers Load Balanced" and set its value to true. This will stopTM from automatically creating Server Nodes configurations and allow you to configure them manually. By default this property will be false.

Turning on "LC Form Servers Load Balanced" deployment property

You will need to define a server node for each TM and LC server host. The server node Group will beused by TM to load balance LC service requests across the available LC machines in the same group. Ifyou have multiple data centers you should define a separate server group for each data center. This willstop TM trying to load balance requests to servers in different data centers.



Server Node configuration of Four Servers with TM and LC split

Server Nodes

Generally you will not need to modify the Server Node configurations, as they will be automaticallycreated when your servers start.

To explicitly tell Transaction Manager where the LiveCycle and Transaction Manager servers are located,we need to define them in "System > Server Nodes".

Configuring server nodes

Edit the LC Form Server node and enter its correct server node URL and server host name so that theTransaction Manager servers can locate it. Please click on the "Test Connection" button to ensureTransaction Manager can connect to the Form Server module (avoka-tm-form-server.war) deployed onthe LiveCycle server.



Configuring LC Form Server node location

If you have multiple LiveCycle servers you need to create a new server node definition for each node.

You should also define the location of the Transaction Manager server nodes, to enable reportingmetrics to be created.

LC Service Connections

To ensure Transaction Manager can call LiveCycle processes deployed on the LiveCycle server nodes weneed to ensure the service connection details are correct. The "FormServer Connection" details arepassed to the TM Form Server module running on the LiveCycle server nodes and are used to make EJBconnections to the LiveCycle services. These connection details are local to the LiveCycle servermachine.

To check these details navigate to "System > Server Connections" and edit the "FormServer Connection"entry. The default endpoint value should be correct and be using a local reference, however theusername / password credentials may need to be updated to match the credentials on your LiveCycleservers. If you have multiple LiveCycle servers with different authentication credentials you will needto configure separate service connections for each LiveCycle server, and match these to their associatedLiveCycle server node definition.



Service connection details for LiveCycle on JBoss

Service connection details for LiveCycle on WebLogic

Service connection details for LiveCycle onWebSphere

Once you have defined the LiveCycle FormServer Service Connection(s) you should click "SynchronizeRepositories" on the System > Server Nodes page. This will test connectivity and authentication withthe LiveCycle servers from Transaction Manager.

If you can't synchronize with the LiveCycle Repositories check the service connection details, that youcan reach the LiveCycle servers from the Transaction Manager servers, and that the LiveCycle path /dscis not blocked by any firewalls.



3.6 Apache Server Configuration (Windows)

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

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

Please note while you can use Apache 2.4 with Transaction 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.

Installation Steps

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\

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



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, skip thisstep. There is a self-signed SSL certificate included with Apache zip, use that temporarily – users willget 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

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 with correctlocation 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 with correctlocation 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

3.7 Apache Server Configuration (Linux)

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

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

Please note while you can use Apache 2.4 with Transaction 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

3.8 Virus Scanner Configuration

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

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 Transaction Managerbecause the ClamAV STREAM protocol opens up TCP listener sockets over a range of ports which makesmore difficult 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

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 Transaction Manager configure the "Symantec Virus Scan"service connection and set the endpoint to the server running the Scan Engine service.

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".

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



Making Scan Engine the default virus scan service

Upgrading Transaction ManagerTransaction Manager Installation Guide


4 Upgrading Transaction Manager

This section describes the recommended procedure of upgrading Transaction Manager to a newerversion.

You have two choices on how to upgrade your server:

Upgrade the existing server using the Setup Wizard task "Upgrade a Transaction Manager 3.5+server"

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

With both upgrade modes Transaction Manager will automatically upgrade the database when theservice is 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



Setup Wizard upgrade option is only supported for upgrading Transaction Manager version 3.5 or laterservers. If you have an earlier SmartForm Manager version you should uninstall the existing server andthe install a new Transaction 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 Transaction Manager service and back up theTransaction Manager database.

IMPORTANT NOTE : Always back up the Transaction 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 Transaction Manager service is stopped.

2. Perform Upgrade with Setup Wizard

Using the Setup Wizard task "Upgrade a Transaction Manager 3.5+ server", follow the wizard steps andtake special care to ensure the same database version and database connection details are used.

If you have custom server shared modules JAR files deployed please uncheck the option "Clean upserver module JARs". After the upgrade has been performed you should review your customizedmodules.xml file to ensure your custom JAR files are still referenced. If the module.xml has beenupdated, please edit it to add references to your custom JAR files.

Clean up Server Module JARs option

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

Please note the first time an upgrade is performed a large number of files will be changed, as the JARand WAR file manifest packing has been changed in TM 3.6.5 to support better diff analysis between



version changes.

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 Transaction Manager service is stopped.

2. Uninstall Service

Please uninstall the service used to run Transaction 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 Transaction Manager service installation directory, so the new installation can usethis path. This will also provide you with a backup of the existing installation.

4. Perform new Transaction 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 Transaction 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 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 Transaction Manager services, otherwise you may get linkage errors at runtime.

4.4 Upgrading LiveCycle Modules

If you are using Adobe LiveCycle, please follow the instructions in sections Deploy Form Server WARand Install LiveCycle Archive to install the new form server WAR and LiveCycle archive. Before installingthe new LiveCycle archive, please undeploy and delete the existing application named "FormCenter".

Note: If you have a custom version of the "FormCenter" application, please back up the application first,and ensure you have a new version of the customized "FormCenter" application available to install.

4.5 Updating the TM Database

Next, you need to make sure that database updates contained in the new version of TransactionManager are applied to the existing TM database. There is a separate module that runs before the TMserver starts 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 Transaction 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, Transaction Manager will not start up and insteadlog messages 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.6 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).

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.7 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 Transaction Manager.

Once Transaction 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 Transaction Manager.

Please Note: Ensure you have followed the "Upgrade Notes" section in the "Transaction ManagerRelease Notes" document for version specific instructions on configuration changes you may need tomake with your upgrade.

4.8 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.

Multiple JDK folders

In the screenshot above, you can see that two JDK folders exist. The one named "jdk.1.7.0_25" could besafely deleted.



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

4.9 Rollback Procedures

Should you need to roll back to the old version of Transaction Manager, stop Transaction Manager (ifrunning). On Windows systems, uninstall the Transaction Manager service by running the followingbatch 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 Transaction 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 Transaction Manager and perform a turnkey installation asdescribed in section Running Transaction Manager Installer. Make sure the installer does not attemptto create the database tables.

Afterwards, if you are using Adobe LiveCycle, redeploy the old version of the form server WAR moduleand the LiveCycle archive as described in sections Deploy Form Server WAR and Install LiveCycleArchive.

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

4.10 Upgrade Checklist

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

Ensure you have the Avoka Transaction Manager installer for the old version as well as anycustom WAR files and LiveCycle applications

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

Check the "Upgrade Notes" section in the "Transaction Manager Release Notes" document forany version specific configuration changes which need to be performed prior to starting theupgrade process

Take a backup of the Transaction 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 Transaction



Manager installer, reusing the existing database.

Upgrade the Transaction Manager LiveCycle application and form server WAR

Start Transaction Manager and monitor the log files

Verify the installation was successful

Check the "Upgrade Notes" section in the "Transaction Manager Release Notes" document forany version specific configuration changes which need to be performed after the upgradeprocess.

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 NotesTransaction Manager Installation Guide


5 Upgrading TM Version Notes

This section details the notes for upgrading configurations from previous versions of TransactionManager. These reviewing and applying the relevant TM version instructions will be require tocomplete your TM upgrade.

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 Transaction Manager 3.5 or later server to version 4.0 please usethe installer Setup Wizard upgrade a option. This will enable you to leave any custom portals and nothave to back and restore them while performing an upgrade.

Installer Upgrade Option

Upgrading Existing Self Service Portals Web Plug-in modules

Transaction 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 Transaction Manager version 3.5 or earlier

Upgrading Portals and Web Plugin Modules

Transaction 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 Transaction Manager version 3.5 or earlier

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

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



Mobile FieldWorker Changes

The "Mobile FieldWorker" portal module has been renamed "TransactField App" in TransactionManager 4.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

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

Transaction 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

Transaction Manager 4.0 introduces an additional tracking number that can be used alongside thereceipt number. By default, your forms will be configured to use the receipt number throughout (the"Use Receipt 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 Transaction Manager Setup Wizard and deploy the updated WARfile to your server. This will then update your Portals Page and Resources base content, which you canthen review 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 recompile



you 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 Transaction 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. Youwill 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/OrganizationThresholds" 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 Groovy



scripts, 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 webservice 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

Transaction Manager includes a PhantomJS receipt rendering module. For this module to work correctlyon a 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 your accountrepresentative 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 Transaction 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 (Portal) content changes have been made in TM 4.3 since version 4.2:

Page or Resource Path Content Changes

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

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

fix task display for Home page ti le rol lover mousepopups

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. Pleasecontact 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.

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.

Installation ChecklistTransaction Manager Installation Guide


6 Installation Checklist

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

6.1 Install Prerequisites

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

Java SE 8u60 on the target server to run the Transaction Manager installer and run theapplication on Linux servers

Avoka Transaction 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)

Adobe LiveCycle ES4 or ES3 application 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 Transaction 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 Transaction Manager portals' context paths

Configure the LiveCycle server node definitions.

Configure the Transaction 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

6.4 Apache Checklist

If the Apache server is performing SSL termination ensure, ServerName is configured inhttpd.conf so that the Transact Integration Agent (TIA) can call TM Web Services over HTTPS.Security changes in Java 1.7 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 Transaction Manager modulesand portals

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 Security Checklist

Ensure Transaction Manager was installed with the "Security Configuration" option to "Usesecure cookies (HTTPS)"

Ensure external applications are only able to access Transaction Manager applications over SSL(port 443).

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 Transaction Manager server(s) only allows connections via theApache Web Server(s).

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

Ensure that firewall rules for the database server only allow connections from the TransactionManager 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 the



database server.

Ensure the Transaction Manager 'administrator' account is disabled. It is highly recommendedthat all administration access is performed through named administrative user accounts, toensure that administrator access auditing is available.

Ensure the Adobe LiveCycle 'administrator' account password is hardened, and this hardenedpassword has been updated in Transaction Manager service connections.

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

Ensure the Adobe LiveCycle server(s) machine administrator password is hardened.

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

Please also review Adobe "Hardening and Security for LiveCycle ES2" http://help.adobe.com/en_US/livecycle/9.0/securityHardening.pdf

6.6 Adobe LiveCycle Checklist

If Adobe LiveCycle is required then ensure you complete the following configuration items:

Ensure a LiveCycle ES turnkey installation has been performed. See the installation instructionsfor the appropriate ES version:ES2: http://help.adobe.com/en_US/livecycle/9.0/installturnkey.pdfES3: http://help.adobe.com/en_US/livecycle/10.0/InstallTurnkey/lc_install_turnkey.pdf

Ensure LiveCycle global default document max inline size property is configured to 10 MB:

–Dcom.adobe.idp.defaultMaxInlineSize=10485760

Ensure XMLForm Pool JVM argument is configured to run a 2 x number CPU cores. So on a 4 coreserver the LiveCycle server should have the JVM argument:

-Dcom.adobe.xmlform.bmc.POOL_MAX=8

Ensure LiveCycle database connection pools have been configured with max size of a least 100connections

Ensure LiveCycle server is not configured to be in backup mode

Ensure TEMP directory is NOT in the default C:\WINDOWS directory

Ensure LiveCycle log files are configured to be rolled over.

Ensure the Transaction Manager server(s) can access the LiveCycle server(s) using HTTP.

Ensure the LiveCycle server context path /dsc* is not blocked to Transaction Manager, as this isrequired by Transaction Manager to synchronize with the LiveCycle repositoriesadfasdf

http://help.adobe.com/en_US/livecycle/9.0/securityHardening.pdf

http://help.adobe.com/en_US/livecycle/9.0/securityHardening.pdf

http://help.adobe.com/en_US/livecycle/9.0/installturnkey.pdf

http://help.adobe.com/en_US/livecycle/10.0/InstallTurnkey/lc_install_turnkey.pdf