installation guide 13r1 - kana communitykanacommunity.verint.com/documents/320423/498001/... · 1.0...

LAGAN Enterprise 13R1

Installation Guide

Product Version: 13R1

Document Version: 1.0

31 May 2013

Installation Guide 1

NOTICES

This edition applies to Version 13R1 of the LAGAN Enterprise product suite. Make sure you are

using the correct edition for the level of the product.

You may comment on errors or omissions with regard to accuracy, organisation, subject matter,

completeness or presentation of this document. Please limit your comments to the contents of

this document only. Speak to your LAGAN representative if you have suggestions about the

product itself.

When you send us comments, you grant KANA a non-exclusive right to use or distribute your

comments in any way it believes appropriate, without incurring any obligation to you.

Copyright © 2013 KANA Software Inc. All rights reserved.

LAGAN, the LAGAN logo, LAGAN CRMTM, LAGAN EnterpriseTM, LAGAN Agent DesktopTM and LAGAN

Agent Desktop LightTM are either registered trademarks or trademarks of KANA Software Inc. in the

United Kingdom and/or other countries.

This software may not be used, sold, licensed, transferred, copied or reproduced in whole or in

part or in any manner or form except in accordance with the licence agreement provided with this

software or with the prior written consent of the copyright owner.


TABLE OF CONTENT

NOTICES ........................................................................................................................................................... 1

1.0 Introduction ........................................................................................................................................ 4

2.0 Requirements ...................................................................................................................................... 5

2.1. System Requirements ................................................................................................................... 5

2.2. Security Requirements.................................................................................................................. 5

2.3. Apache Tomcat Settings ............................................................................................................... 5

2.5. Tomcat Database Connection Pooling .......................................................................................... 7

2.6. Oracle Application Server (OAS) ................................................................................................... 9

2.7. Websphere Application Server (WS) .......................................................................................... 11

2.8. Embedded browser control within LAGAN Enterprise ............................................................... 12

2.9. Deploying LAGAN Webapps in Weblogic .................................................................................... 13

3.0 Installation Files ................................................................................................................................ 18

3.1. Installation CD Overview ............................................................................................................ 18

3.2. Copy the Installation Files ........................................................................................................... 18

4.0 Running the Installation Wizard ........................................................................................................ 20

4.1. Windows Installation .................................................................................................................. 20

4.2. Unix / Linux Installation .............................................................................................................. 24

4.3. Checking the Installation ............................................................................................................ 24

4.4. Creating the LAGAN_HOME Folder ............................................................................................ 25

4.5. Setting the Environment Variable............................................................................................... 25

5.0 Database Installation ........................................................................................................................ 27

5.1. Database User Permissions......................................................................................................... 27

5.2. MSS Database Schema................................................................................................................ 27

5.3. MSS Database Setup ................................................................................................................... 28

5.4. Oracle Database Setup ............................................................................................................... 29

5.5. Database Value Changes............................................................................................................. 30

6.0 Deploying the War Files .................................................................................................................... 31

6.1. Deploying the Lagan.war File ...................................................................................................... 31

6.2. Deploying the Laganresources.war File ...................................................................................... 31

7.0 eForms Installation ........................................................................................................................... 33

7.1. Deploying the Ef3.war File .......................................................................................................... 33

7.2. Deploying the Ef3Config.war File ................................................................................................ 33

7.3. eForm Configuration ................................................................................................................... 34

7.4. Content Repository ..................................................................................................................... 34

8.0 Clustering LAGAN Applications .......................................................................................................... 37

8.1. Multicasting ................................................................................................................................ 37

8.2. Configuring the LAGAN Application ............................................................................................ 37

8.3. Testing the Multicast .................................................................................................................. 38

8.4. Configuring eForms ..................................................................................................................... 38

9.0 Business Configuration Migration Tool .............................................................................................. 39

10.0 Hotfixes ............................................................................................................................................. 40

11.0 Testing the Installation ...................................................................................................................... 41


11.1. LAGAN Configuration Studio .................................................................................................... 41

11.2. Starting the Agent Desktop ...................................................................................................... 42

11.3. Testing the Agent Desktop Functionality ................................................................................. 43

11.4. Testing the Agent Desktop Light Functionality ........................................................................ 43

11.5. Testing the Web Services ......................................................................................................... 43

12.0 Optional Installations ........................................................................................................................ 45

12.1. Local Monitor ........................................................................................................................... 45

12.2. C3 ............................................................................................................................................. 45

12.3. Universal Adaptor .................................................................................................................... 46

12.4. Optional Steps .......................................................................................................................... 47

13.0 Configuring the Installation ............................................................................................................... 48

13.1. HTML Help Files........................................................................................................................ 48

13.2. Single Sign On ........................................................................................................................... 49

13.3. Universal Queue ....................................................................................................................... 50

13.4. Auditing .................................................................................................................................... 50

13.5. Self Service Option ................................................................................................................... 51

13.6. Logging ..................................................................................................................................... 51

14.0 Installing the QuickAddress Adaptor ................................................................................................. 55

14.1. Pre-requisites ........................................................................................................................... 55

14.2. QAS Installation ........................................................................................................................ 55

14.3. Configuration ........................................................................................................................... 57

14.4. Setup ........................................................................................................................................ 58

14.5. Address Format ........................................................................................................................ 59

15.0 CTI Light ............................................................................................................................................ 61

15.1. Property file Configuration ...................................................................................................... 61

15.2. Web start configuration ........................................................................................................... 61

15.3. Configuration Studio ................................................................................................................ 62

15.4. Optional Configuration ............................................................................................................ 62

16.0 Mixed Media Integration Adaptor (MMI) .......................................................................................... 63

16.1. Property File Configuration ...................................................................................................... 63

16.2. Web Start configuration ........................................................................................................... 64

16.3. Configuration Studio ................................................................................................................ 64


1.0 Introduction

LAGAN Enterprise™ is a family of innovative solutions that enable an organisation to implement

customer interaction management strategies across a variety of contact channels, including web,

voice and email. LAGAN allows an organisation to implement and upgrade such strategies rapidly

due to its advanced Java-based architecture and highly developed integration methodology.

The objective of this manual is to help those responsible for the installation and configuration of

LAGAN’s ECM solution. The manual describes how to install the various components of LAGAN

Version 13R1.

Terminology:

Throughout this Installation Guide, the LAGAN Application Server machine is referred to as APPSERVER and

the LAGAN Database Server machine is referred to as DBSERVER.

Also, the term UNIX is used to refer to UNIX and Linux platforms.


2.0 Requirements

This chapter will outline any requirements that should be considered before beginning the

installation. Please ensure these requirements are met before continuing with the installation.

2.1. System Requirements

For a full list of system requirements for this release, please refer to the relevant System

Requirements document. The Systems Requirement document for 13R1 can be found at:

http://connect.LAGAN.com/ProductInformation/LAGANECMInformation/Release%20Notes/Frontl

ine/Pages/default.aspx

2.2. Security Requirements

While LAGAN is not responsible for the security requirements of any installation, the following are

just some of the security requirements that should be verified before beginning with the LAGAN

installation:

• What are the internal security policies for deployments?

• Is the operating system and non-LAGAN software on the server up to date?

• Are reverse proxy servers being used in the DMZ?

• Is Network Address Translation (NAT) being used?

• Has the operating system of the LAGAN server been hardened?

• Is HTTPS being used?

• Is the security certificate up to date?

• Is the communication between LAGAN self service components and internal LAGAN servers

restricted to HTTP and specific ports on the firewall?

2.3. Apache Tomcat Settings

Ensure that the following tomcat settings are configured:

How to change Tomcat’s JVM heap settings:

1. Start the Tomcat Monitor, Start | Programs | Apache Tomcat 7.0 | Monitor Tomcat.

2. Right click on the Apache Tomcat icon in the bottom right hand corner of the Windows

Task bar

3. Select Configure...

4. Click on the Java tab and adjust the Initial memory pool and Maximum memory pool

settings as appropriate.


Figure 2.1: Java Memory Pool

NOTE: The above Memory Pool settings are based on a 32bit system. For 64bit systems, the Initial value

should not exceed 60% of the physical RAM, but start with 2048MIN/2560 as the Maximum value. Values

should go up in 1024 increments for both values if jvisualVM shows higher memory utilization.

5. Also, if your database is Oracle, the JVM must be run with an Oracle 9i compatibility flag,

otherwise date/time values will not be retrieved correctly.

6. Add the following configuration to the Java Options section:

• -Doracle.jdbc.V9Compatible=true

• -XX:MaxPermSize=128m

• -XX:+HeapDumpOnOutOfMemoryError

• -XX:HeapDumpPath=D:/temp

NOTE: The path in the DumpPath needs to be validated to ensure that it is valid.

7. The following options should also be added to ensure that you can get thread dumps and

connect to JMX.

• Dcom.sun.management.jmxremote.port=8999

• Dcom.sun.management.jmxremote.ssl=false

• Dcom.sun.management.jmxremote.authenticate=false


2.5. Tomcat Database Connection Pooling

The default database pool used by LAGAN/Spring (Apache DBCP) does not support database

failover. That is if the connection pool is closed (e.g. database failure) it cannot be reopened

without restarting the LAGAN application.

This section outlines how to configure the Tomcat connection pooling on both an MSSQL database

and an Oracle database.

2.5.1. Oracle Database

A highly available connection pool can be achieved by defining a datasource in Tomcat using the

Oracle JDBC driver. Follow the steps outlined below to configure the datasource:

1. Copy the ojdbc14.jar to $CATALINA_HOME/common/lib.

2. Create a context descriptor for LAGAN in Tomcat with an Oracle JNDI connection pool

resource as outlined below.

$CATALINA_HOME/conf/Catalina/localhost/LAGAN.xml

<Context path="/LAGAN" docBase="/LAGAN">

<Resource name="jdbc/LAGAN"

auth="Container"

type="oracle.jdbc.pool.OracleDataSource"

driverClassName="oracle.jdbc.driver.OracleDriver"

factory="oracle.jdbc.pool.OracleDataSourceFactory"

url="jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=o n)(ADDRESS=(PROTOCOL=TC

P)(HOST=bfs-ltdb-2-vip)(PORT=1521))(ADDRESS=(PROTOC OL=TCP)(HOST=bfs-ltdb-

1-vip)(PORT=1521)) (CONNECT_DATA=(SERVICE_NAME=ltor acls01.LAGAN.com)))"

user="FL_PG"

password="FL_PG"

maxActive="20"

maxIdle="10"

maxWait="-1"

connectionCachingEnabled="true" />

</Context>

3. You will then need to edit the following:

• docBase to match the location of your expanded webapp

• url to a valid JDBC connection string

• user and password with your database connection credentials

4. Edit the LAGAN.war/WEB-INF/dataSourceContext-local-pool.xml to use this JNDI

datasource as outlined below:

LAGAN.war/WEB-INF/dataSourceContext-local-pool.xml

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"

"http://www.springframework.org/dtd/spring-beans.dt d">

<beans>

<bean id="dataSource"

class="org.springframework.jndi.JndiObjectFactoryBe an">

<property name="jndiName" value="java:comp/env/jdbc /LAGAN"/>

</bean>

</beans>


NOTE: value="java:comp/env/jdbc/LAGAN" should match the name of your Resource as defined above i.e.

Reource name="jdbc/LAGAN" ==> value="java:comp/env/jdbc/LAGAN"

5. Restart Tomcat

2.5.2. MSSQL Database

Following the steps outlined below to configure the connection pooling for an MSSQL database:

1. Stop Tomcat on the application server.

2. Copy the tomcat\webapps\LAGAN\WEB-INF\lib\sqljdbc.jar into the

tomcat\common\lib directory.

3. Create the file LAGAN.xml in the tomcat\conf\catalina\localhost directory and insert

into the file the following (modifying the username, password and url connection string

as appropriate):

Tomcat/conf/catalina/localhost/LAGAN.xml


<Context path="/LAGAN" docBase="LAGAN" reloadable=" true"

crossContext="true" >

<Resource

auth="Container"

driverClassName="com.microsoft.sqlserver.jdbc.SQLSe rverDriver"

factory="org.apache.tomcat.dbcp.dbcp.BasicDataSourc eFactory"

maxActive="20"

maxIdle="10"

maxWait="-1"

name="jdbc/Microsoft"

password="LAGAN"

removeAbandoned="true"

removeAbandonedTimeout="600"

type="javax.sql.DataSource"

url="jdbc:sqlserver://vm2-bfs-win2k:1133;databaseNa me=l701"

username="l701"

validationquery="select 1"/>

</Context>

4. Take a copy of the file dataSourceContext-local-pool.xml in the

tomcat\webapps\LAGAN\WEB-INF directory.

5. Edit the contents of dataSourceContext-local-pool.xml and replace with the following:

dataSourceContext-local-pool.xml


<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"

"http://www.springframework.org/dtd/spring-beans.dt d">

<beans>

<bean id="dataSource"

class="org.springframework.jndi.JndiObjectFactoryBe an">

<property name="jndiName" value="java:comp/env/jdbc /Microsoft"/>

</bean>

</beans>

6. Restart Tomcat


7. Rename the jdbc.properties file to notused.jdbc.properties, as other spring config files

might define the "dataSource" bean, e.g. QuickAddress.xml that also might have to be

replaced with the above.

8. After startup, check that the following appears in the Tomcat stdout log.

• AbandonedObjectPool is used.

(org.apache.tomcat.dbcp.dbcp.AbandonedObjectPool@91d7c)

• LogAbandoned: false

• RemoveAbandoned: true

• RemoveAbandonedTimeout: 600

9. Test LAGAN to ensure that it works as expected.

2.6. Oracle Application Server (OAS)

Ensure that the following OAS settings are configured:

If Oracle 10g is being used, then you must configure the correct Java options. The default JVM

start-up parameters for oc4j need to be adjusted so that the JVM has enough memory to run the

LAGAN application.

If OC4J is being used:

1. In the <install-dir>\bin folder, edit oc4j.cmd and set the following:

2. set JVMARGS=%OC4J_JVM_ARGS% -Xms512m -Xmx512m -XX:PermSize=128m -

XX:MaxPermSize=256m

3. If Oracle 10g is being used, edit the <install-dir>/opmn/conf/opmn.xml, and check the

values for the java-options node, an example follows:

<ias-component id="default_group">

<environment>

<variable id="LAGAN_HOME" value="d:\LAGANhome"

append="false"/>

</environment>

<process-type id="home" module-id="OC4J" st atus="enabled">

<module-data>

<category id="start-parameters">

<data id="java-options" value="-Xrs -server -Xms5 12m -

Xmx512m -

XX:PermSize=128m -XX:MaxPermSize=256m –

Doracle.jdbc.V9Compatible=true-XX:AppendRatio=3 -

Djava.security.policy=$ORACLE_HOME/j2ee/home/config /java2.policy

-Djava.awt.headless=true -Dhttp.webdir.enable=false "/>

</category>

4. Also, if the database is Oracle, the JVM must be run with an Oracle 9i compatibility flag,

otherwise date/time values will not be retrieved correctly.

5. Add -Doracle.jdbc.V9Compatible=true to the end of the java options.


2.6.1. OAS Specific installation

When deploying under OAS, it is important to configure the webapps so that the support jars

shipped with the LAGAN applications are used in preference to any pre-installed on OAS.

To do this complete the steps outlined below:

1. Edit the classpath. When deploying the war file, the 3rd

(final) screen has an option for

configuring classpath.

2. Select this, and from the Configuration Page, untick the inherit system libraries option

and tick the search local jars first option.

3. Then proceed to finish the deployment.

4. To ensure that the OAS setup will work correctly, the jmxContext.xml file will need to be edited.

5. After unpacking the LAGAN.war file browse to the WEB-INF directory and copy the

jmxContext.xml file to the desktop.

6. Edit the following entry key:

<entry key="LAGAN Log Configuration:name=Log Configuration Reloader" value-

ref="log4JConfigurationReloader"/>

7. Remove the LAGAN Log Configuration text, so the updated line would look like:

<entry key=":name=Log Configuration Reloader" value-ref="log4JConfigurationReloader"/>

8. Save the updated file and copy it back directly to the opened archive. This will replace the

existing jmxContext.xml file with the new one.

2.6.2. OAS Class Loading

Under OAS it is necessary to configure Class Loading when deploying the webapp. There are 2

methods of doing this:

1. Manual Setup:

On the final page of the deployment wizard, select the Configure Class Loading icon,

(looks like a pen). On the configuration page, unselect inherit settings, and select Search

in local classes first. Deploy.

2. Auto Setup:

There is a file called LAGAN_plan.dat in the core\common\LAGAN directory. When

deploying the webapp, the first page has an option to Select an existing deployment

plan. Select this option and enter the path for the LAGAN_plan.dat file. This will configure

the webapp for correct deployment.


2.7. Websphere Application Server (WS)

2.7.1. Websphere Specific Installation Activities

1. When deploying to IBM Websphere Application Server (WS), it is important to set the

LAGAN_HOME environment variable within WS so that LAGAN.war can reference the

LAGAN config directory.

NOTE: This directory needs to be manually copied to each WebSphere app server in the cluster.

2. This can be achieved using the IBM Integrated Solutions Console once WS has been

installed:

WebSphere Application Server > [Server Name] > Java and Process Management >

Process definitions > Environment Entries

Figure 2.2: Integrated Solution Console

Figure 2.3: Application Servers


3. Use the New Application wizard to deploy each LAGAN application. The LAGAN

installation media comes with 2 .ear files that are specific to WebSphere deployments.

They should be used instead of the equivalently names .war files. The order of

deployment should be:

• LAGAN.ear

• ef3.ear

• Followed by each of the optional .war files that apply to your solution

When progressing through the application installation wizard, simply select the correct

file on the first page, all other settings should be at their defaults. Remember, when

deploying LAGAN and the supporting web applications, the Context Root must be in

lower case, E.g. “LAGAN”, “knowledge” etc.

4. The launch page for the installed LAGAN Enterprise application will be

http://[APPSERVER]:[port]/LAGAN/index.html

5. To restart WS you can do so via the WS service but to restart a specific application it is

done via the IBM console as Applications, Enterprise Applications, check required

application, click Stop and then click Start.

6. Getting log information from WS: Websphere logs: The default log location is:

D:\ProgramFiles\IBM\WebSphere\AppServer\profiles\[AppSrv01]\logs\[server1]-

SystemErr.log and SystemOut.log Alternatively, use the WS console: Troubleshooting,

Logs and Trace, [server1], JVM Logs, Runtime tab.

7. LAGAN logs: all Log4j logs need to be defined with explicit paths as Catalina_home does

not exist as a WS environment variable.

2.7.2. Websphere Memory Settings

As with Apache Tomcat, it is recommended that the memory heap settings are configured

appropriately. Follow the steps below to configure these settings:

1. From the left hand pane of the WS console, select Servers | WebSphere Application

Servers.

2. From the list of servers available select the relevant server name. This will populate the

Configuration tab with the server information.

3. Under Server Infrastructure, select Java and Process Management | Process Definition.

4. Select Java Virtual Machine and check that the Initial Heap and Maximum Heap settings

are set to 256MB and 1536MB (if using a 32-bit JVM) or 256MB and 2048Mb (if using a

64-bit JVM).

2.8. Embedded browser control within LAGAN Enterprise

The embedding of the Microsoft controls within LAGAN Enterprise is essentially in order to render

HTML pages. More specifically, we make use of Microsoft's HTML document renderer to display

the page within a Java window, and its WebBrowser control for the browsing capabilities.

On the technical side it is the JVM which creates an actual 'canvas' (window pane) and allows a

real Windows reference to this to be passed to the above controls. It should be understood that

this is NOT the Internet Explorer application that has been embedded. This application is

controlled by the image file IEXPLORE.EXE and a number of DLL files. What Microsoft exposes as a

web browser control is a more limited set of functionality.

The behaviour of the embedded browser can be different when viewing the same URL inside it

and within an actual instance of the Internet Explorer application. Issues can arise with use of

session ids and Javascript. Compatibility with running inside Internet Explorer is not guaranteed.

Furthermore, when the browser application starts to load its own 'external' applications, including

some use of COM and so-called Single Sign On web-apps, then these resources may be beyond our

control - thus there is no proper way of closing them down or cleaning them up. When using the

Internet Explorer application it has full control over all of these and thus can shutdown cleanly.

Use of such external applications should be combined with ensuring that the Agent Desktop

application is closed down after logging out – and not logged into again.

As described on the Microsoft web site:

The WebBrowser control adds browsing, document viewing, and data downloading capabilities to

your applications. Applications using this control will allow the user to browse sites on the

Internet's World Wide Web, as well as folders in the local file system and on a network. The

WebBrowser control supports Web browsing through both point-and-click hyperlinking and URL

navigation. The control maintains a history list that allows the user to browse forward and

backward through previously browsed sites, folders, and documents.

2.9. Deploying LAGAN Webapps in Weblogic

This section outlines the steps that are required when deploying the LAGAN Webapps in a

Weblogic environment.

NOTE: Ensure that Weblogic has been installed and is successfully working before continuing with this

section.

2.9.1. Server Settings

1. Ensure the server has been configured with LAGAN_HOME variable.

2. From the Admin server select Environment > Servers to select the server you require.

3. Click Configuration > Server Start.

4. In the Arguments text area enter:

-DLAGAN_HOME=/opt/LAGAN/LAGANhome -XX:MaxPermSize=256m

5. Ensure the server is started by clicking on the Control tab for the server.

6. In the config.xml file, disable the enforce-valid-basic-auth-credentials property for

Weblogic.

Example:

<security-configuration>



<enforce-valid-basic-auth-credentials>false</en force-valid-basic-auth-

credentials>



</security-configuration>


NOTE: If this is enabled then any web pages that require basic authentication (E.g Agent Desktop Light) will

also require authentication with WebLogic. This would mean having to authenticate twice with different

accounts.

2.9.2. Create JNDI JDBC DataSource

The default connection pooling provided by DBCP does not support re-establishing connections

automatically therefore the J2EE containers JDBC connection data sources should be used.

1. Log into weblogic and select Services > JDBC > Data Sources and click New.

2. If you wish to use a JNDI data source the following should be set in system.properties

jndidatasource=true

3. The name of the JNDI Data Source can then be configured in jdbc.properties as follows

(where jdbc/LAGAN is the name of the Data Source):

jdbc.jndiDataSourceName=jdbc/LAGAN"

JDBC Data Source Properties

Property Example value

Name JDBC QA-LAGAN

JNDI Name jdbc/qa-LAGAN

Database Type Oracle

Database Driver Oracle's Driver (Thin XA) for RAC Service-Instance connections;

Versions:10,11

Service name rac

Database name QA-LAGAN

Hostname bfs-ltdb-cls-1

Port 1521

Database User Name QA-LAGAN

Password QA-LAGAN

Driver Class Name oracle.jdbc.xa.client.OracleXADataSource

URL jdbc:oracle:thin:@bfs-ltdb-cls-1:1521/rac


2.9.3. Unpack and Deploy EAR/WAR File

An EAR file for the LAGAN application is included on the distribution CD. This should be "exploded"

or unpacked onto the local file system to make it ready for deployment. Follow the steps below to

unpack and deploy the LAGAN EAR file:

1. Copy the ear file to the server.

E.g. cp LAGANcd/core/common/wars/*.war /opt/LAGAN/tmp/

2. Extract the ear contents to disk into a folder with the same name as the ear E.g.

LAGAN.ear.

3. In the ear, repeat the process for all war files.

4. To assist in this process a shell script can be executed.

NOTE: For consistency of use it is recommended that the ear be copied to a standard location (E.g.

/opt/LAGAN/downloads) and this script be run from there.

5. The script will create a deployments folder under the current directory which contains

the exploded files. The script can be invoked as follows:

./explode-ear.sh LAGAN.ear

6. Create a file called explode-ear.sh and paste the script contents into it. You also need to

make the script executable by executing:

chmod +x explode-ear.sh

7. This script can explode an ear plus embedded wars or a single war.

NOTE: Ensure to complete the above steps for each WAR or EAR file.

2.9.4. explode-ear.sh Script

#!/bin/bash

#

# script to explode an ear and any associated war f iles

#

# explode the ear

# $1 is the folder containing the ear

# $2 is the name of the ear

# $3 is the folder in which to explode the ear

function explode-ear {

if [ -d $3/$2 ]; then

echo $3 already has a $2 folder, please check

exit 1

fi

echo exploding $1/$2 into $3

mkdir -p $3/$2

pwd=`pwd`

cd $3/$2

jar xvf $1/$2

for w in *.war;

do

explode-war $w `pwd`


done

cd $pwd

}

# function to explode a war, this will explode into a folder with the same

name

# as the war. The war will be renamed to prevent a name clash. BE CAREFUL

# The war should exist in the current directory

# $1 is the name of the ear

# $2 is the folder in which to explode the war

function explode-war {

wardir=`pwd`

warname=$(basename $1)

warfile=$(basename $1)

cd $2

if [ -d $warname ]; then

echo `pwd` already has a $warname folder, pleas e check

exit 1

fi

if [ -f $warname ]; then

mv $warname $warname.bak

warfile=$warname.bak

fi

mkdir $warname

echo exploding $wardir/$warname into $2

cd $warname

jar xvf $wardir/$warfile

cd $wardir

}

function myusage {

echo "File is missing or is not an ear/war $1"

echo "usage:"

echo " $(basename $0) <ear name>"

exit 1

}

if [[ $# -eq 0 || ! -f $1 ]]; then

myusage $1

fi

deploydir=deployments

earfile=$1

sfx=${earfile#*.}

if [ "$sfx" = "ear" ]; then

explode-ear `pwd` $earfile $deploydir

elif [ "$sfx" = "war" ]; then

explode-war $1 $deploydir

else

myusage $1

fi


2.9.5. Deploying WAR files

Follow the steps outlined below to deploy the relevant WAR files:

1. In the Admin server click Environment > Deployments > Install.

2. Browse to the folder containing your expanded WARs E.g.

/opt/LAGAN/tmp/deployment/LAGAN.ear.

3. Select the expanded WAR folder E.g. LAGAN

4. Select Install this deployment as an application.

5. Select All servers in the cluster as a target.

6. Set the Security as DD Only and the Source accessibility to Copy this application onto

every target for me.

2.9.6. Configuring log4j Logging

The best approach for capturing log4j messages in Weblogic is to configure the default logger to

use log4j. This approach means that we do not need to specify application (LAGAN) level logging

within the war or ear file. For more information on this visit the following location:

http://download.oracle.com/docs/cd/E12840_01/wls/docs103/ConsoleHelp/taskhelp/logging/

SpecifyTheLoggingImplementation.html

2.9.7. Dealing with Deployment Errors

It seems that certain WebLogic installations are unable to read properties files from within the

WEB-INF/classes folder. This can result in deploy time errors that are shown in the WL console

such as, NullPointerException or Missing Resource Bundle, depending on the application being

deployed. To resolve these errors:

1. Copy the missing properties to the domain folder.

2. For example, if the domain is base_domain the file(s) should be copied to

/opt/bea/Oracle/Middleware/user_projects/domains/base_domain/

3. Different systems can have different domains, but the place to look for is the

user_projects/domains/<DOMAIN_NAME>/ folder.

4. You also need to edit the file knowledgesearch.war/WEB-INF/knowledgeSearch-

servlet.xml and remove the config/ prefix from the location of the messages definition.

Example:

<bean id="messages" class="java.util.ResourceBundle " factory-

method="getBundle">

<constructor-arg index="0" value="messages "/>

</bean>


3.0 Installation Files

The LAGAN core installation is installed in a number of steps:

1. Creating the Installation Directory and copy the Installation files from the CD.

2. Complete the Installation Wizard and check it was successful.

3. Create the LAGAN Database.

4. Deploy the LAGAN.war file

5. Deploy the Ef3.war and Ef3Config.war files

6. Install the client application.

3.1. Installation CD Overview

The installation CD contains LAGAN software for both Windows and UNIX.

The media layout is as follows:

Top level

• core: Used for installation on Windows

• tar: Contains a tar archive used for installation on UNIX. The tar archive

contains a UNIX-compatible copy of core

• manuals: LAGAN documentation

Platform level

Under core there are three directories:

• unix: Unix software

• windows: Windows software

• common: Software common to both Windows and UNIX

3.2. Copy the Installation Files

Follow the steps below to create the installation directory and copy the installation files. The

following information will detail both the Windows and Unix steps.

3.2.1. Windows Steps

On the APPSERVER, create an installation directory. E.g. [Drive]:\LAGAN\v9-install

Insert the LAGAN Installation CD and copy the entire CD contents to the newly created installation

directory. E.g. [Drive]:\ LAGAN\v9-install


3.2.2. Unix Steps

From the installation media locate the <release>.tar.gz.

Copy this file to the newly created installation directory and extract the contents of the tar file; tar

–xzvf <release>.tar.gz

Ensure all the .ksh files are executable; find <extract_dir> -name “*.ksh” | xargs chmod a+x

Create an installation directory. E.g. [Installation Directory]/ LAGAN/v9-install

Copy the entire media contents into the newly created installation directory.


4.0 Running the Installation Wizard

To begin the installation of LAGAN Enterprise, a simple installation wizard needs to be run. To

complete the installation wizard, follow the steps outlined below:

NOTE: The same installer should be run for either a UK or US installation. The installer will now

automatically install the correct version of LAGAN based on the locale of the machine.

4.1. Windows Installation

1. Open a command prompt and change directory to the following directory [Installation

Dir]\core\windows\install.

2. Within this directory execute the Run_Installer.bat file. This will begin the installation

wizard

3. Once the installation wizard begins, the first screen to be displayed is the Installation

screen (Figure 4.1).

Figure 4.1: Installation Screen

4. The Install Type field will display the type of installation that is to run, either Windows or

Unix / Linux

5. In the Installation Drive field the drive letter of where the installation will be created is

automatically entered. This can be modified if necessary.

6. In the Installation Directory the path name of the installation directory should be

automatically entered. This can be modified if necessary.

7. The Java Directory field will be auto-populated with the path name of the Java

installation directory. Ensure that this is the correct path name.

8. The CD Drive / Tar Unpack Directory field will be auto-populated with the directory

where the installation is being run from. This is where the .tar files will be unpacked to.

9. The Custom Jars field allows the path name to be entered of any .jar files that have been

customised for this particular installation.


10. Once these fields have been completed, click the Next button. This will display the

Service Location screen, (Figure 4.2).

Figure 4.2: Service Location Screen

11. The Service Location information defines the protocol details of how the client will

connect to the LAGAN Enterprise system.

12. The Protocol field will be auto-populated with http. This can be changed if necessary to

https.

13. The Host Name field will display the name of the APPSERVER that LAGAN Enterprise is

being installed on.

14. The Port field will display the connection port number and will be auto-populated with

the port number 8080.

15. The Host Machine Connection String field will be greyed out and cannot be edited

directly. This field displays the connection string using the information that has been

entered in the previous three fields.

16. In the Search Service Name field enter the name of the Search Service to be used.

17. The ODM Gateway Service Name field should not be changed from the default value.

18. The XML Provider Service Name field should not be changed from the default value.

19. The Document Repository Service Name field should not be changed from the default

value.

20. Once all the information has been correctly entered, click the Next button. This will

display the Services screen, (Figure 4.3).

NOTE: The information required in this screen is reliant on a Database Schema existing. Please ensure the

steps in Section 5.1 have been completed.


Figure 4.3: Services Screen

21. From the Database Type drop down menu, select the relevant database type. The

options available are Microsoft SQL Server 2005, Microsoft SQL Server 2005, Oracle 10g

or Oracle 11g.

22. In the Database Name field edit the 'host' (Oracle) or 'host name' (SQL Server) string,

replacing it with the hostname of your database server. E.g. For a SQL Server 2005

installation this might be "jdbc:sqlserver://server01:1433"

23. In the Database User Name field enter the username that will have access to the

database.

24. In the Database Password field enter the password for the username in the previous

field.

25. Once these details have been entered, click the Next button. This will display the LDAP

screen, (Figure 4.4).

Figure 4.4: LDAP Screen


NOTE: Using LDAP (Lightweight Directory Access Protocol) will allow you to download User, Group and Role

information from a central directory. Before deciding to use this option, check with a system administrator

that LDAP is to be used.

26. If LDAP is not being used, click the Next button to continue the installation. (Proceed to

point 30).

27. If LDAP is being used, check the LDAP tickbox. This will enable the LDAP Admin Group

field.

28. Enter the relevant group name in the LDAP Admin Group field.

29. Click the Next button. This will display the Install screen, (Figure 4.5).

Figure 4.5: Install Screen

30. If any of the information previously entered needs to be changed, click the Back button to

the relevant screen and change the appropriate information.

31. When all the correct information has been entered, click the Install button to begin the

installation.

32. Once the installation process has finished an Information box will be displayed, (Figure

4.6).

Figure 4.6: Information Box

33. Click the OK button to complete the Installation Wizard.


4.2. Unix / Linux Installation

1. Open a command prompt and change directory to the following directory [Installation

Dir]/core/unix/install.

2. Within this directory execute the Run_Installer.ksh file. This will begin the installation

wizard.

3. The Installation wizard will be the same as a Windows Installation. Follow the steps

outlined in Section 4.1 to complete the Installation wizard.

4.3. Checking the Installation

Once the Installation Wizard has finished it is recommended to check to ensure that the

installation was successful. There are a number of things to check to ensure a successful

installation:

4.3.1. Checking the Log File

1. Browse to the installation directory that was entered during the Installation wizard, E.g.

D:\LAGAN\v9-install.

2. Within this directory there will be a newly created file called InstallLog.log. Open this log

file and check to ensure that no errors have been reported.

4.3.2. Successfully Created Installation Directory

NOTE: If you are unsure that the installation was successful please contact your local LAGAN representative

to confirm any errors with the log file.

1. If the installation has completed successfully a folder called LAGANhome will have been

created in the directory defined during the installation process (E.g. D:\LAGAN\v9-

install).

2. Browse this directory and check the contents of the LAGANhome folder. If the installation

was successful the LAGANhome folder will contain the following files:

• jdbc.properties

• mail.properties

• odmsearch.properties

• system.properties

• userapplication.properties

• cas.properties

• flwebdatetimelist.properties

• log4j.xml

• log4j-ef3.xml


4.4. Creating the LAGAN_HOME Folder

As mentioned in previous sections, once the installation has been completed a LAGANhome folder

will be created in the installation directory. All files in this folder have the correct values taken

from the installer dialogs.

It is strongly recommended that a new folder called LAGAN_HOME is created and all the files from

the generated LAGANhome are copied to this folder. This means that the installer can be run

again at future dates, without overwriting any custom configurations of the property files.

Therefore all property files deployed under the web application should be considered Read-Only

and any modifications should be applied to the version in LAGAN_HOME.

4.5. Setting the Environment Variable

On Windows, the LAGAN_HOME folder must be set as a System Environment Variable, not a User

environment variable. Follow the steps below to set the correct environment:

1. Select the Environment Variables button from Start | Control Panel | System | Advanced

Tab.

Figure 4.7: Environment Variables

2. Under the System Variable pane, click the New button. This will display the New System

Variable dialog.

3. In the Variable Name field enter LAGAN_HOME.

4. In the Variable Value field enter the path directory of the LAGAN_HOME folder.

5. Once both these fields have been completed click OK to add the variable.


6. After setting LAGAN_HOME as a system variable you should restart Windows, otherwise

Tomcat may fail to pick up the new environment variable and the LAGAN Enterprise will

not start.

NOTE: Future web application deployments will overwrite existing files under the deployed web application.

If changes area applied to these files they will be lost.


5.0 Database Installation

The LAGAN database should be installed on the DBSERVER and is installed in the following stages:

1. Creation of a database Schema.

2. Running the relevant install batch file for the database type (MSSQL or Oracle).

3. Optional installations.

5.1. Database User Permissions

For SQL Server it would be advised to set the user as the database owner, this will give the

required permissions on the LAGAN database for both install and runtime.

For an Oracle install the user would need the following default permissions:

• Create Session

• Create Table

• Create View

• Create Sequence

• Create Procedure

• Create Synonym

• Create Trigger

• Create Type

Also for Oracle assign Quota Unlimited on default tablespace.

NOTE: These are the permissions required to install LAGAN on Oracle. For runtime operation, the LAGAN

user will also need CRUD permissions on all LAGAN database objects.

5.2. MSS Database Schema

Before running the script that will create the LAGAN Schema, a new database should be created.

Normally this will be done by a database Administrator and should be in place before continuing

the installation. A database login should also be allocated for use by the installation script.

Below are a few things that should be checked to ensure the database and user has been created

successfully:

1. A database has been created for exclusive use of the LAGAN application

2. A database user has been created with sufficient permissions to log into that database, to

read and write data and to create objects such as tables, views and indexes. The

db_owner role is commonly granted for this purpose, though a stricter permissions

model is possible.


3. Check that the database user has been mapped to a database login and that the new

LAGAN database is defined as the default for that user.

4. Ensure that the default schema name for the database user is set to dbo.

5.3. MSS Database Setup

NOTE: The database installer script will no longer ask for the Database Schema Name, Keyprefix, Database

Owner Name or a Description. These will be installed with default values.

Follow the steps outlined below to create the LAGAN Database using Microsoft SQL Server:

NOTE: Please ensure that you run the scripts from the folder that was created by the installer and NOT from

the CD or install media folder. Scripts run from the CD media folder may initially appear to run correctly, but

will be missing key localisation information.

1. On the DBSERVER, open a command prompt and change directory to the following

directory [Installation Dir]\LAGAN\v9-install\scripts.

2. Within this directory execute run the msssetup.bat file. This will begin the database

installation.

3. The first prompt will ask to Enter the drive that the scripts are running from. Enter the

drive letter and press Enter. E.g. D:

4. The next prompt will ask to Enter the Installation Directory. Enter the full path of the

installation directory where the scripts are located and press Enter. E.g.

[Drive]:\LAGAN\v9-install

5. The third prompt will ask to Enter the name of the database server. Enter the relevant

machine name (E.g. DBSERVER) and press Enter.

6. The next prompt will ask to Enter the database user name. Enter a relevant user name

that has administrative privileges to the new database and press Enter.

7. The final prompt will ask to Enter the database password. Enter the relevant password

for the username that was entered in the previous step and press Enter.

8. Once all the database information has been entered, the command prompt will display a

list of all the information that was previously entered.

9. Check that this information is correct and press Enter to continue, or Ctrl C to quit.


Figure 5.1: Database Setup

10. This will now begin the process of creating the LAGAN Database.

11. Once the installation has been completed, Output logs will be generated in the scripts

folder. Examine these to ensure no errors have occurred.

NOTE: If nothing appears under ‘Invalid stored procedures’ in CreateDB.log, then all of the core stored

procedures compiled successfully.

5.4. Oracle Database Setup

NOTE: The database installer script will no longer ask for the Database Schema Name, Keyprefix, Database

Owner Name or a Description. These will be installed with default values.

Follow the steps outlined below to create the LAGAN Database using Microsoft SQL Server:

1. On the DBSERVER, open a command prompt and change directory to the following CD

directory [Installation Dir]\LAGAN\v9-install\scripts.

2. Connect to the database: sqlplus username/password@dbname

3. Run the oracle setup script using: start oraclesetup.sql

4. This will now begin the process of creating the LAGAN Database.

5. Once the installation has been completed, Output logs will be generated in the scripts

folder. Examine these to ensure no errors have occurred.

NOTE: If nothing appears under ‘Invalid stored procedures’ in CreateDB.log, then all of the core stored

procedures compiled successfully.


5.5. Database Value Changes

The LAGAN database has now been created, and has used default values for the following:

• Database Schema Name

• KeyPrefix

• Database Owner

• Description

In the unlikelihood that the values should need changed, the following will outline where to

change the values held within these fields:

update lgncc_schema set <FIELD> = <value>

where <FIELD> <value> is one, or more, of:

• Field: schema, Value: Name of current schema [50 chars]

• Field: keyPrefix, Value: The 2 digit prefix to be added to generated id's [2 digits]

• databaseOwner, Value: 1 if the current user is the database owner, 0 otherwise [1 digit in

range 0..1]

• description, Value: Free text description


6.0 Deploying the War Files

The installation requires the deployment of two .war files; Lagan.war and Laganresources.war.

The sections below outline how to deploy and check each of these.

6.1. Deploying the Lagan.war File

The Lagan.war file (Web Application Archive file) is a specialised JAR file used to distribute a

collection of JavaServer Pages, Servlets, Java classes, XML files, Tag libraries and static Web pages

that together constitute LAGAN Enterprise’s Web application.

1. To deploy the Lagan.war file using Tomcat follow the steps outlined below:

2. Copy the Lagan.war file from the following directory, core\common\wars to the

following Tomcat directory, Tomcat\WebApps.

3. Open Start | All Programs | Administrative Tools | Services.

4. Locate the Tomcat service and select Stop.

5. Once the service has stopped, select the Tomcat service again and select Start.

6. Once the Tomcat service has restarted the Lagan.war file will automatically be deployed.

This will generate a new folder within the Tomcat\WebApps directory called LAGAN.

NOTE: Additionally, the jamon-2.7.jar file should be copied from \core\common\jamon on the installation

CD to the common library location for the servlet container in use. In Tomcat, for example, this will be the

common\lib directory of the Tomcat installation.

6.1.1. Checking the Deployment

After deploying the Lagan.war file, it is good practice to check that the deployment has been

successful.

1. Browse to the following Tomcat directory, Tomcat 7.0\webapps.

2. If the Lagan.war was unpacked successfully, there should be a folder within this directory

called LAGAN.

3. Open this folder to display all the files that have been unpacked.

NOTE: If you are installing LAGAN with an OAS setup ensure that the jmxContext.xml file has been

configured correctly. Details on this can be found in section 2.3.1 of this guide.

6.2. Deploying the Laganresources.war File

The Laganresources.war file is used to distribute a collection of JavaServer configuration pages,

Servlets, Java classes, XML files, Tag libraries and static Web pages.

To deploy the Laganresources.war file using Tomcat follow the steps outlined below:

1. Copy the Laganresources.war file from the following directory, core\common\wars to

the following Tomcat directory, Tomcat\WebApps.






After deploying the Laganresources.war file, it is good practice to check that the deployment has

been successful.


2. If the Laganresources.war was unpacked successfully, there should be a folder within this

directory called Laganresources.



7.0 eForms Installation

7.1. Deploying the Ef3.war File

The Ef3.war file is used to distribute a collection of JavaServer Pages, Servlets, Java classes, XML

files, Tag libraries and static Web pages. Deploying the Ef3.war file will allow the ability to view

unpublished eForms in the Configuration Studio.

To deploy the Ef3.war file using Tomcat follow the steps outlined below:

1. Copy the Ef3.war file from the following directory, core\common\wars to the following

Tomcat directory, Tomcat\WebApps.





After deploying the Ef3.war file, it is good practice to check that the deployment has been

successful.


2. If the Ef3.war was unpacked successfully, there should be an Ef3 folder in this directory.


7.2. Deploying the Ef3Config.war File

The Ef3Config.war file is used to distribute a collection of JavaServer configuration pages, Servlets,

Java classes, XML files, Tag libraries and static Web pages.

To deploy the Ef3Config.war file using Tomcat follow the steps outlined below:

1. Copy the Ef3Config.war file from the following directory, core\common\wars to the

following Tomcat directory, Tomcat\WebApps.





After deploying the Ef3Config.war file, it is good practice to check that the deployment has been

successful.


2. If the Ef3Config.war was unpacked successfully, there should be a folder within this

directory called Ef3Config.



7.3. eForm Configuration

1. If the web application is not running on port 8080, copy the file eform.properties file

from Ef3\WEB-INF\classes\config in the Web Application to LAGAN_HOME on the

APPSERVER.

2. Replace localhost:8080 with the machine name and port of the APPSERVER on which the

web application is running. The eform.properties file under LAGAN_HOME should be

modified instead of the version deployed with the Ef3 war file.

3. The default date value is dd/MM/yyyy and can be changed by modifying datePatter in

the eform.properties file. The version of the properties file in LAGAN_HOME should be

changed, instead of the version deployed with the Ef3 war file.

4. Restart the Web Application Server.

7.3.1. eForm Preview Option

If you want to use the eForms Preview option from the Configuration Studio, create/edit the file

adminapplication.properties in LAGAN_HOME on APPSERVER and add these entries:

• eformdefinitionconfigview.baseurl=http://APPSERVER[:PORT]/Ef3/

• eformdefinitionconfigdialog.showxmlparameteronly=true

• eformdesigner.webappdirectory=http://APPSERVER[:PORT]/LAGAN/classes/

• eformdesigner.previewport=8888

• eformdesigner.previewbasedirectory=http://APPSERVER[:PORT]/LAGAN/config/

7.4. Content Repository

LAGAN uses Apache Jackrabbit to manage its content repository. This is currently only used for

eForm versioning. To install Apache Jackrabbit follow the following steps.

NOTE: MSSQL 2008 requires a new JDBC driver and the jackrabbit content repository will not connect to a

MSS 2008 database using the current driver. The installation media will now contain two versions of the

Microsoft jar and you will need to select the correct driver for their version of the database. The new jar is

sqljdbc4.jar.

1. Copy the jackrabbit folder from the LAGANhome folder under the installation folder to

the new LAGAN_HOME directory.

2. Configure the repository.xml in the jackrabbit folder for either Oracle or MSS. Oracle is

commented in by default – change this if MSS is required.

3. You need to supply the database jdbc connection string, user name and password in

various locations within the repository.xml file.

4. This should be a different schema from the core LAGAN schema and it should exist and be

empty.


5. The jackrabbit-webapp-1.4.war file should be deployed in the webapp directory and

Tomcat should be restarted. This war file can be found in the

core/common/optional/EForm_Versioning folder on the CD.

6. Place the jcr-1.0.jar from the core\common\optional\EForm_Versioning folder on the

CD onto servlet container. E.g (TOMCAT DIR)\webapps\jackrabbit-webapp-1.4\WEB-

INF\lib

7. Start the servlet container in order to expand the jackrabbit war file then stop it again.

8. Copy either the Oracle or MSS driver from core\common\optional\EForm_Versioning

folder on the CD to the class path of the jackrabbit web app i.e. into the WEB_INF/lib

directory.

9. Restart the servlet container. Initialise the Jackrabbit web app using the URL (E.g.

http://localhost:8080/jackrabbit-webapp-1.4) and go to the section entitled Use an

existing content repository. Enter the full path to the jackrabbit directory under

LAGAN_HOME, and press Access Content Repository.

10. Ensure that the jackrabbit URL within the services.properties file is set to

jcr.rmi.url=//localhost:1099/jackrabbit.repository. within the LAGAN_HOME folder.

11. When using Websphere, load the Jackrabbit application using the following URL:

http://localhost:8080/jackrabbit

NOTE: If this fails check the web server logs. If a port conflict is the cause of the error:

Copy the configuration key jcr.rmi.url from <Web Server Web Application Directory>\LAGAN\WEB-

INF\services.properties to LAGAN_HOME\services.properties and change the port for this URL (default is

1099) to another value e.g. from //localhost:1099/jackrabbit.repository to

//localhost:1097/[TBD:jackrabbit.repository].

Also change the value of the configuration key rmi.port, in the file bootstrap.properties in the jackrabbit

folder of the web server, to be the same as the new port value (Its default is 0 which uses the default RMI

port i.e. 1099).

12. You should now be able to populate and browse the repository via the Jackrabbit web

app. You should also see the Jackrabbit database tables in the database.

13. Stop the servlet container again. Add jcr.connection=rmi to system.properties in

LAGAN_HOME.

14. Restart the servlet container. You should now be able to access the version control and

locking functionality of eForms.

15. eformservice.locktimeoutinminutes can be set in services.properties within the

LAGAN_HOME folder to dictate when a locked eForm will timeout. The default is 120 (i.e.

2 hours)

7.4.1. OAS Particulars

1. The jcr jar file needs to be added as a shared library resource. It needs to be called jcr.

You do not need to add the oracle drivers if using OAS and an oracle database.

2. When deploying the Jackrabbit war add the jcr jar to the class path, inherit all jars from

the parent and enable directory browsing.


3. The undeploy/redeploy mechanism using the OAS Admin client does not seem to work

with Jackrabbit. If oc4j is started and then Jackrabbit is deployed it works.

4. There is a Jackrabbit issue stopping the welcome.jsp page from compiling with OAS so, to

initialise Jackrabbit, go to the URL http://localhost:8888/jackrabbit-webapp-

1.4/bootstrap/missing.jsp

7.4.2. WebLogic Particulars

The jcr jar should be copied to the domain/lib folder. For example, if WebLogic is installed in

/opt/bea (so the user_projects folder is /opt/bew/user_projects), and the domain to be used is

LAGAN_domain, then the folder name is /opt/bea/user_projects/domains/LAGAN_domain/lib

There is a Jackrabbit issue stopping the welcome.jsp page from compiling with WebLogic. In

WebLogic deployments the jackrabbit war file should be expanded onto the filesystem (e.g.

/opt/downloads/jackrabbit-webapp-1.4.war/ folder). You should edit the welcome.jsp in that

folder and remove the following line:

log("Error accesing the repository", e);

This should be line 27 in the original file.


8.0 Clustering LAGAN Applications

IMPORTANT NOTE:

This section of the Installation Guide should only be used by those who are configuring their LAGAN

installation in a clustered environment.

The caching.distribution.multicastgroupaddress and the caching.distribution.multicastgroupport (optional)

details MUST BE supplied by the local network administrator as this information will be specific to each

clustered installation.

8.1. Multicasting

Multicasting is common in clustering technologies as it allows nodes to dynamically register

interest on a multicast group:port to join a cluster. The cluster then communicates via

multicasting to keep all nodes in sync. This allows you to add (or remove) nodes on the cluster

without need to modify configuration on each peer.

The LAGAN application uses Ehcache which in its default configuration requires multicasting to

function. Also if you are using Tomcat as your J2EE container then multicasting is required for the

most reliable clustering.

NOTE: The multicast range is between 224.0.0.0 to 239.255.255.255 (inclusive). You can use any value in this

range if you require an alternative to 230.0.0.1.

Component Multicast Group Multicast Port Details

Ehcache 230.0.0.1 4446 This is the default configuration in

LAGAN.war: LAGAN.war/WEB-

INF/services.properties

Tomcat 230.0.0.1 4444 This is the suggest configuration

8.2. Configuring the LAGAN Application

1. Enable the LAGAN application for a clustered environment by editing the

system.properties file in $LAGAN_HOME.

cluster=true

2. If necessary change the multicast address which LAGAN cluster traffic is sent on by

editing the services.properties file in $LAGAN_HOME (default is 230.0.0.1).

caching.distribution.multicastgroupaddress=228.0.0.118

3. Add the multicast port by editing the services.properties file:

caching.distribution.multicastgroupport=4446

4. Add a <distributable/> tag to the <web-app> definition in the

$CATALINA_HOME/webapps/LAGAN/WEB-INF/web.xml file:


<web-app>

<display-name>LAGAN 9-0-0</display-name>

<description>LAGAN Enterprise Case Management</des cription>

...

<distributable/>

...

</web-app>

5. Edit tomcat/webapps/LAGAN/web-inf/dataAccessContext-mssql.xml and replace the

dbSpecificSchedulerFactoryTemplate bean.

<bean id="dbSpecificSchedulerFactoryTemplate" abstr act="true"

class="org.springframework.scheduling.quartz.Schedu lerFactoryBean">

<property name="quartzProperties">

<props>

<prop

key="org.quartz.jobStore.driverDelegateClass">org.q uartz.impl.jdbcjobstore

.MSSQLDelegate</prop>

<prop key="org.quartz.jobStore.selectWithLockSQL">S ELECT * FROM {0}LOCKS

with (UPDLOCK,ROWLOCK) WHERE LOCK_NAME = ?</prop>

</props>

</property>

</bean>

8.3. Testing the Multicast

1. Download the file multicastTest.zip.

2. On each of the application servers start the receive script E.g. receive.bat

3. On one of you application servers start the send script E.g. send.bat

4. The above scripts will test multicasting on 230.0.0.1:4446, if you wish to test on a

different port then you can supply these as options

E.g.

./receive.sh 228.0.0.1 4444

./send.sh 228.0.0.1 4444

8.4. Configuring eForms

To configure the LAGAN eForms for session replication you need to add a <distributable/> tag to

the $CATALINA_HOME/webapps/Ef3/WEB-INF/web.xml file:

<web-app>

<display-name>Eform Application</display-name>

<description>Eform Application</description>

...

<distributable/>

...

</web-app>


9.0 Business Configuration Migration Tool

This is a command line utility that allows the import/export of complete Business Configuration for

a defined classification.

The BCMT is located in the tools\startup folder of the installation media. Open a command line

interface and navigate to the relevant directory. Once there the bcmt.bat (or .ksh) can be run with

one of the import/export options.

NOTE: For further details on how to use the BCMT, please refer to the Operational Tools Guide.


10.0 Hotfixes

Between each maintenance release, LAGAN may issue hotfixes for a specific version of the LAGAN

product. These hotfixes are to correct small defects to the relevant version. After each new

installation, it is highly recommended that any available hotfixes for the installed version are

downloaded and applied.

These hotfixes can be downloaded from the relevant version folder on the LAGAN ftp site.

E.g. ftp://ftp.LAGAN.com/pub2/HotFixes/13R1/


11.0 Testing the Installation

At this point the core installation should be complete and the following tasks should have been

completed:

1. Copied the Installation files from the CD to an Installation Directory.

2. Completed the LAGAN Enterprise Installation Wizard.

3. Created a new folder called LAGAN_HOME and installed files copied to it.

4. Created and configured a new LAGAN Database.

5. Deployed the Lagan.war file.

6. Completed the Operational Tools Wizard. (If Applicable).

7. Deployed the Ef3.war file and installed eForms. (If Applicable).

8. Checked for and installed any hot fixes for the relevant version.

Once these steps have been completed it is advisable to check that the installation was successful.

The following information will run through several steps that should be completed that will verify

if the installation was successful.

11.1. LAGAN Configuration Studio

The LAGAN Configuration Studio allows the administrator to add or configure various components

that will display different functionality to the agents using the Agent Desktop and Agent Desktop

Light applications. Using the LAGAN Configuration Studio, create the following components:

1. Create a New Group with some components assigned to it, including enquiry search, and

the ability to create interactions and cases.

2. Create a New User and assign this user to the Group.

3. Create, Save and Publish a simple eForm.

4. Check that the eForm can be viewed using the following URL:

http://<applicationservername>:<portnumber>/Ef3/<eFormname.xml>

5. Create an eForm definition for this eForm.

6. Create a simple Case Form.

7. Create a Case Work Queue.

8. Create a Process Definition which references the previously created case work queue,

eForm and case form.

9. Create a classification and associate it with the process definition from the previous step.

10. Create a database catalog and ensure that it can connect to the database.

NOTE: For details on how to complete the above steps, please refer to the LAGAN Configuration Studio User

Guide.


11.2. Starting the Agent Desktop

NOTE: Ensure Java Web Start is installed on the client machine before beginning.

1. On the client machine, open a new browser window and enter the following URL:

http://APPSERVER:[port]/LAGAN/

NOTE: Replace APPSERVER with the Machine Name or IP address of the APPSERVER and [port] which

defines the port on which the servlet container is configured to listen, (8080).

2. This will display the LAGAN Client Launch Screen, (Figure 13.1).

Figure 11.1: LAGAN Client Launch Screen

3. Click on the Agent Desktop image on the left to begin installing the Agent Desktop

application.

4. Once the Agent Desktop application has been installed on the client machine, the user

will be presented with a login box, (Figure 12.2).

Figure 11.2: LAGAN Agent Desktop Login Window


5. Enter the newly created User ID in the User ID field.

6. Enter the associated Password for the new user and click the Log In button.

7. If the Installation was created successfully, the user should be logged in and the Agent

Desktop application should be displayed.

NOTE: If the user’s credentials are not successful, try entering Admin/Admin as a User ID and Password. If

these credentials are successful, check the User details within the Configuration Studio to ensure it has been

created correctly.

11.3. Testing the Agent Desktop Functionality

Once successfully logged into the Agent Desktop, complete the following list of actions to ensure

that the correct functionality is available:

1. Start an interaction.

2. Create a new Individual.

3. Search for this individual.

4. Delete this Individual.

5. Classify this interaction with the classification that was created.

6. Ensure that the case form and eForm are viewed correctly.

7. Complete the case form and eForm to create the case.

8. Perform a search for the case to ensure it can be found.

9. Finish the interaction.

11.4. Testing the Agent Desktop Light Functionality

Once successfully logged into the Agent Desktop Light, complete the following list of actions to

ensure that the correct functionality is available:

1. Log into the Agent Desktop Light with the user that was created.

2. Create a new case with the classification that was created.

3. Search for an individual.

4. Logout of the Agent Desktop Light.

11.5. Testing the Web Services

One final test is to check that the Web Services are functioning correctly. Complete the following

list of actions to ensure that the correct functionality is available:

1. Browse to http://servername:port/LAGAN.


2. Click on both View WSDL links – (under Service: FL and Service: FLAuth)

3. Browse to http://servername:port/LAGAN/services/FL

4. Browse to http://servername:port/LAGAN/services/FLAuth


12.0 Optional Installations

Certain components can be optionally installed, if required, in order to allow LAGAN Enterprise to

integrate with other systems. These components are:

• Local Monitor

• C3

• Universal Adaptor

They are not installed by default but are present on the CD. They should be installed into a

hierarchy such as D:/LAGAN. In the rest of this chapter this directory will be know as

LAGAN_OPTIONAL_DIR.

12.1. Local Monitor

The local monitor resources reside on the CD under core\windows\optional\localmonitor. Follow

the steps outlined below to install and configure Local Monitor:

1. Copy the folder core\windows\optional\localmonitor from the CD to your

LAGAN_OPTIONAL_DIR.

2. Under this folder, locate the InstallMonitor.bat file. Right click this file and select Edit

from the menu.

3. Once the file has been opened, replace the [TBD: DIRECTORY] entry with

LAGAN_OPTIONAL_DIR\localmonitor.

4. Close and Save the changes to this file.

5. Under the same directory, locate the LocalMonitor.conf file.

6. Edit the LocalMonitor.conf file, replacing the [TBD: LocalMonitor Install Dir] entry with

LAGAN_OPTIONAL_DIR\localmonitor.

7. Also set the ExtraRegistryJars property to ExtraRegistryJars = ..

8. To install the local monitor run InstallMonitor.bat.

12.2. C3

The C3 resources reside on the CD under core\windows\optional\C3. Follow the steps outlined

below to install and configure C3:

NOTE: If running against an MSS database ensure the MSS jars are copied to the

LAGAN_OPTIONAL_DIR\C3\lib folder.

1. Copy the folder core\windows\optional\C3 from the CD to the LAGAN_OPTIONAL_DIR.

2. Under the Startup folder, locate the C3.bat file. Right click this file and select Edit from

the menu.

3. Once the file has been opened, replace the [TBD: INSTALLATION DIRECTORY] entry with

LAGAN_OPTIONAL_DIR\C3.


4. Also, replace the [TBD: DIRECTORY] entry with the full path of the bin directory under the

JRE that is installed.

5. Replace the [TBD: DRIVE LETTER] entry with the drive letter of LAGAN_OPTIONAL_DIR.


7. Locate the servicecontrollocale.properties file.

8. Edit this file and replace the [TBD: DEFAULT CONNECTION STRING] entry with the same

database connection string as the jdbc.url property in jdbc.properties under the

LAGAN_HOME directory.

9. Also, replace the [TBD: DEFAULT USER NAME] entry with the same User Name used to

connect to the database as the jdbc.username property in jdbc.properties under the

LAGAN_HOME directory.


11. To start C3 run the C3.bat file.

12.3. Universal Adaptor

The Universal Adaptor resources reside on the CD under

core\windows\optional\UniversalAdaptor. Follow the steps outlined below to install and

configure Universal Adaptor:

NOTE: If running against an MSS database ensure the MSS jars are copied to the

LAGAN_OPTIONAL_DIR\C3\lib folder.

1. Copy the folder core\common\optional\UniversalAdaptor to your

LAGAN_OPTIONAL_DIR.

NOTE: For a Unix installation, copy the folder core\unix\optional\UniversalAdaptor\startup to the

LAGAN_OPTIONAL_DIR directory.

2. Under the Startup folder, locate the common.bat file. Right click this file and select Edit

from the menu.

3. Once this file has been opened, replace the [TBD: INSTALLATION DIRECTORY] entry with

LAGAN_OPTIONAL_DIR\UniversalAdaptor.

4. Replace the [TBD: DIRECTORY] entry with the full path of the home directory where the

JRE is installed.

5. Also, replace the [TBD: DRIVE LETTER] entry with the drive letter of

LAGAN_OPTIONAL_DIR.


7. The Registry must be started first before running the Universal Adaptor.

8. To start Universal Adaptor run the UniversalAdaptor.bat file. Alternatively Universal

Adaptor can be started using C3.


12.4. Optional Steps

These steps will add optional functionality to LAGAN, if needed.

1. Enhanced Security

Run the command:

update lgncc_license set status=1 where feature=‘ESM’;

2. Replication

Run the command:

update lgncc_license set status=1 where feature=‘REPLICATION’;


13.0 Configuring the Installation

This chapter will detail other functionality that is available within LAGAN Enterprise that may be of

use after installing the core product.

When making changes to configuration in the properties files it is highly recommended to take a

copy of these files. It is usually best to name them with a date-timestamp combination; for

example, 20101209.1430.services.properties.

NOTE: This naming mechanism automatically can group these files together under Windows Explorer when

sorted by name. If the date/timestamp is appended to the properties file name then the directory/folder

contents are less clear to see.

13.1. HTML Help Files

The HTML Help files that are available with LAGAN Enterprise are delivered as a set of zipped files

that must be hosted on the internal intranet. Once configured, the Help files will be available from

the Help menu from within the Agent Desktop, Configuration Studio and Agent Desktop Light

applications.

13.1.1. Deploying the Help Files

To deploy any of the help files, unzip the help content to a folder from which the client’s website

can be served. Please refer to the Web Services Guide for more detailed instructions.

NOTE: The .zip files containing the HTML help files can be downloaded from the LAGAN ftp site.

The set of HTML help files consists of:

• Agent Desktop (UK)

• Agent Desktop (US)

• Agent Desktop Light (UK)

• Agent Desktop Light (US)

• Configuration Studio (UK)

• Configuration Studio (US)

13.1.2. Configure Property File

Once the Help files are setup and available, the location must be configured within the LAGAN

application.

1. To configure the location of the Agent Desktop and Agnet Desktop Light help files, edit or

create a property in the userapplication.properties file as follows:

application.onlinehelp.url=http://APPSERVER[:port]/ECM%20Virtual%20Office%20(UK)

/ecm_virtual_office.htm


application.ews.onlinehelp.url=http://APPSERVER[:port]/ECM%20Workstation%20(UK)

/ecm_workstation.htm

2. To configure the location of the Configuration Studio help file, edit or create a property

in the adminapplication.properties file as follows:

application.configstudio.onlinehelp.url=http://APPSERVER[:port]/ConfigurationStudio/

configuration_studio.htm

13.2. Single Sign On

Using the Single Sign On (Seamless Sign On) feature means that users will not be prompted for

their username / password when they start the LAGAN application, rather they will be logged on

to the LAGAN application using the username of their current logon (e.g. Microsoft Windows)

session.

SSO can be turned on/off separately for the Agent Desktop (rich client) and Agent Desktop Light

(thin client)

SSO is configured within 2 files located in the LAGAN_HOME directory:

system.properties:

• sso.thinclient=true

• sso.richclient=true

sso.properties:

• sso.domaincontroller=[TBD: DOMAINCONTROLLER eg DC.XYZ.COM]

• sso.domain=[TBD: DOMAIN eg XYZ.COM]

• sso.stripdomain=true

• sso.serviceaccountname=[NAME]

• sso.serviceaccountpassword=[PASSWORD]

If you are using NTLM (which means you are using SSO with the thinclient), then you need to

configure your domain and domain controller, otherwise ignore these settings.

Stripdomain is used to determine if the domain does or does not form part of the username

configured within the LAGAN application. If usernames in the LAGAN system take the form

"[email protected]" then sso.Stripdomain should be set to FALSE. If they appear as

"john_smith" then sso.stripdomain should be set to TRUE. The serviceaccountname and

serviceaccountpassword can be ignored.

NOTE: If using SSO with Java 7 ensure the following registry key is set:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters

allowtgtsessionkey REG_DWORD (1)

Once set ensure the machine is rebooted.


13.2.1. Java Jar File

For SSO to work using NTLM in the Agent Desktop Light, you need to manually download an extra

java jar file and install it on the application server. The jar file is the jcifs.jar and can be

downloaded from http://jcifs.samba.org/. This needs to be installed in a common/shared location

where it is accessible on the server (E.g. shared/lib on Tomcat).

NOTE: For Spring Security NTLM to work a full international version of the JRE must be installed on the

server or a 'cp860' error will occur when SSO is attempted. (Need to do a custom install and select extra

languages).

13.3. Universal Queue

By default Universal Queue is configured to process these work types: inbound calls, cases and

emails. To change this:

1. Edit the services.properties file on APPSERVER and go to the Work Type Configuration

section.

2. Add or comment out servicename and id values as appropriate.

3. Adjust the count and worktype index values to reflect the number of uncommented

work types.

13.4. Auditing

If the licensable Auditing option has been purchased then to ensure that auditing is switched on

the database table LGNCC_LICENSE should contain a row with a column value of AUDIT for

FEATURE and a value of 1 for the column STATUS.

This will enable the auditing of events such as:

• Sign on

• Password validation

• Searches

• Contact history retrieval

• Modifications to configuration data

Additionally it should be confirmed that any database sizing exercise performed for the initial

LAGAN Enterprise product install has taken into account the additional disk space required to

house Audit data.

NOTE: Depending on the amount of auditing implemented and the systems usage this could potentially

constitute a significant use of storage.


13.5. Self Service Option

NOTE: In a production environment the selfservicetoolkit web application should not be deployed such that

it is accessible to the public internet. The selfservice web application is designed to be deployed to the

public internet and it needs to be able to access the selfservicetookit web application. The self service

toolkit should either be deployed on a separate installation of your J2EE container which is not visible to the

public internet, but is accessible to the selfservice web application, or a reverse proxy should be used.

1. Copy the core\common\wars\selfservicetoolkit.war file from the installation CD to the

Web Application Server.

2. Deploy the selfservicetoolkit.war file as per the instructions for your Web Application

Server.

3. Open the config.properties file in the deployed selfservicetoolkit hierarchy under WEB-

INF\classes.

4. Set frontline_webservice_address and authorisation_webservice_address to the

address of the FL authorisation service and FL webservice respectively.

5. Set userid and password to be the user ID and password of the LAGAN Enterprise account

the Self Service Option will use.


7. Copy the core\common\wars\selfservice.war file from the installation CD to the Web

Application Server machine.

8. Deploy the selfservice.war file as per the instructions for your Web Application Server.

9. Open the config.properties file in the deployed selfservice hierarchy under WEB-

INF\classes. Set the host and port of URL defined by case_details_url to the host and port

of where the selfservicetoolkit.war was deployed.


13.6. Logging

Logging for the LAGAN Enterprise system is controlled using Log4j and configured via a series of

files contained in the LAGAN_HOME directory. The following is a summary of each log file and its

purpose:

• log4j.xml: Logging for the server side of the product, Web Services and Agent Desktop Light.

• log4j-user.xml: Logging for the Agent Desktop

• log4j-admin.xml: Logging for the Configuration Studio

When any of the above log files are missing no logs will be generated for the specific piece of

functionality. Logging can be turned off very easily by renaming one of the above files. LAGAN

uses Four levels of logging via Log4j:

• TRACE (Most Logging)

• DEBUG

• INFO

• ERROR (Least Logging)

Log4j configuration is based around two basic concepts; a Logger and an Appender. Loggers

define groups of code in a hierarchical fashion and associate log levels and a named Appender

with each group of code.

For example, if there are two loggers com.LAGAN with level ERROR and com.LAGAN.util with level

INFO, all code under com.LAGAN.util will log all statements with LEVEL info. Even though

com.LAGAN.util is hierarchically underneath com.LAGAN, com.LAGAN.util has its own specific log

level associated with it and Log4j will obey this.

Appenders provide a destination for logs, typically a file. Appenders typically have more than one

Logger directed to them and Loggers can be directed to more than one Appender. This method

provides an extremely flexible way of configuring logging. Sample Log4j configuration is provided

in LAGAN_HOME for each of the files mentioned above in the files log4j-sample.xml, log4j-user-

sample.xml and log4j-admin-sample.xml and several more specific examples are detailed below.

13.6.1. "Rolling File" Appender

The following XML defined a Rolling File appender. Any logs directed to this appender will appear

in a file named stdoutr.log which will never exceed 5000kb in size and will have a series of backups

named stdoutr.1, stdoutr.2 etc. up to a maximum of 5



<appender name="stdoutr" class="org.apache.log4j.Ro llingFileAppender">

<param name="File" value="${catalina.home}/logs/std outr.log"/>

<param name="Append" value="true"/>

<param name="MaxFileSize" value="5000KB"/>

<param name="maxBackupIndex" value="5"/>

<layout class="org.apache.log4j.PatternLayout" >

<param name="ConversionPattern" value="%p [%t] %c{2 } (%M:%L) - %m%n"/>

</layout>

</appender>

13.6.2. Logging for a Given User

The following XML defines the log file user_Admin.log and will send all logs for the user named

Admin to this file with log level DEBUG.

<logger name="com.LAGAN">

<level value="debug"/>

<appender-ref ref="user_Admin"/>

</logger>

<appender name="user_Admin"class="org.apache.log4j. RollingFileAppender">

<param name="File" value="${catalina.home}/logs/use r_Admin.log"/>

<param name="Append" value="true"/>

<param name="MaxFileSize" value="5000KB"/>

<param name="maxBackupIndex" value="5"/>

<layout class="org.apache.log4j.PatternLayout ">

<param name="ConversionPattern" value="%d{dd-MMM-yy yy HH:mm:ss:SSS} %-5p

[%t] [%X{operation} %X{authorisation}] %c{1} %M %m% n"/>

</layout>

<filter class="com.LAGAN.util.log4j.MDCFilter">

<param name="MatchKey" value="authorisation"/>

<param name="MatchValue" value="Admin"/>

<param name="ExactMatch" value="true"/>

</filter>

</appender>

13.6.3. Logging Database Calls & Parameters

The following XML will send logs detailing all executed database calls and the values of arguments

used in these calls to the file dbcalls.log

<logger name="org.springframework.jdbc.core.Stateme ntCreatorUtils">


<appender-ref ref="dbcalls"/>

</logger>

<logger name="org.springframework.jdbc.core.JdbcTem plate">


<appender-ref ref="dbcalls"/>

</logger>

<appender name="dbcalls" class="org.apache.log4j.Ro llingFileAppender">

<param name="File" value="${catalina.home}/ logs/dbcalls.log"/>

<param name="Append" value="false"/>

<layout class="org.apache.log4j.PatternLayo ut">

<param name="ConversionPattern" value="%d{dd-MMM- yyyy

HH:mm:ss:SSS} %-5p [%t] [%X{operation} %X{authori sation}] %c{1}

%M %m%n"/>

</layout>





<filter class="org.apache.log4j.varia.Strin gMatchFilter">

<param name="StringToMatch" value="Setting SQL stat ement parameter

value"/>

</filter>


14.0 Installing the QuickAddress Adaptor

The LAGAN QuickAddress Adapter allows address datasets such as PAF (post office address file)

and LPG (Land and Property Gazeteers) to be looked up in real time by the LAGAN application. This

eliminates the need to pre-load LAGAN Enterprise with address information, saving time and

effort.

Some of the features available within QAS are:

• Real-time searches from your Quick Address Server, accessed over the network using HTTP.

• Ability to search both LAGAN-hosted data and QAS data in the same search (search order is

configurable. This is useful is LAGAN data is already loaded, but it's desirable to search QAS

data in parallel, e.g. for out of district searches. Duplicate detection and suppression is

included.

• Supports the new QAS LPG datasets, which are user-maintainable and can return the property

UPRN.

• Configurable address return formats.

• Also supported via LAGAN webservices, meaning integrated systems (such as Self Service

eForms) can also invoke searches of QAS address data.

14.1. Pre-requisites

Before installing QAS ensure the following pre-requisites are met:

• LAGAN Enterprise 13R1.

• Quick Address Pro Web v6 and later (also known as QuickAddress Gateway) with the GBR or

LPG datasets).

14.2. QAS Installation

QuickAddress Pro Web is a product from QAS Ltd that can be used to query Postal Address Files

for addresses.

To install the LAGAN QuickAddress Adaptor, so that property searches in LAGAN Enterprise can

query PAF files a, perform the following steps:

1. Install QuickAddress Pro Web, following the instructions in the QuickAddress Pro Web

Integration Guide. Install the GBR or USA dataset, as appropriate for your region.

2. Locate the folder core\common\optional\QAS_Layouts on the LAGAN CD and select the

appropriate file for your region from:

• ODMPropertyLayoutUK.txt

• ODMPropertyLayoutUS.txt

Append the contents of this file to the end of the QuickAddress configuration settings file

C:\Program Files\QAS\QuickAddress Pro Web\QAWSERVE.INI.

3. In the QAWSERVE.INI file, ensure that EngineIntensity is set to 1 (for CLOSE matching).


NOTE: Refer to the QuickAddress documentation for further information about engine search intensity. The

recommended setting is 1 (for close matching).

Setting EngineIntensity to 0 (for EXACT matching) can cause the QuickAddress Adaptor to fail to function

correctly. Having performed a search and selected a property that was returned by QuickAddress it may not

be possible to set that property as the current object.

4. In the QAWSERVE.INI file, ensure that SLMaxMatches is set to the maximum number of

addresses that you wish to be returned for a search. Possible values are in the range 0 –

1000 (where 0 causes the maximum number of matches to be returned).

5. Restart the QuickAddress Pro Server Windows service, to pick up the changes to the

QAWSERVE.INI file.

6. Using WinZip, open the file C:\Program Files\QAS\QuickAddress Pro Web\proweb.war

and extract proweb.jar, placing it in the LAGAN Enterprise installation lib folder.

7. Locate the QuickAddress Service section in the services.properties file.

8. Edit the endpointurl value and set it to the appropriate endpoint URL for your

QuickAddress Service. This value should match the ServerWsdlUrn setting in your

QAWSERVE.INI file, E.g. http://myserver:2021/.

9. The searchtimeout value is the value in milliseconds of the search timeout period. The

default value is 10000 (10 seconds). Adjust this value if required or set it to 0 to cause

searches not to timeout.

10. For US customers, comment out the 3 lines:

• qasservice.dataid=GBR

• qasservice.addresslayout=ODMPropertyLayoutUK

• qasservice.layouthandlerclass=com.LAGAN.LAGANcentre.core.service.odmgateways

ervice.quickaddress.QASLayoutHandlerUK

11. Also uncomment the following 3 lines:

• #qasservice.dataid=USA

• #qasservice.addresslayout=ODMPropertyLayoutUS

• #qasservice.layouthandlerclass=com.LAGAN.LAGANcentre.core.service.odmgateway

service.quickaddress.QASLayoutHandlerUS

12. Stop the LAGAN services.

13. Edit the server classpath and add ../lib/proweb.jar.

14. Restart the LAGAN services.

15. Edit the libraries.jnlp file in the LAGAN installation webstart folder, and add the following

entries in the resources section:

• <jar href="lib/proweb.jar" download="lazy"/>

• <jar href="lib/axis.jar" download="lazy"/>


14.3. Configuration

Different configuration is required to use the data sets. The section below will outline this

configuration.

14.3.1. Properties

The following properties

Property: qasservice.providerconfiguration

Options / Example: qasOnly, qasFirst or qasSecond

Description: This defines the order in which property sources are searched. qasOnly will result in

only QAS being searched, qasFirst will result in QAS being searched first then LAGAN second and

qasSecond will result in LAGAN being searched second.

When both sources are used, any duplicate suppression that is formed will result in the first result

encountered being returned. E.g. If qasFirst is used and duplicates are found, the properties

returned from QAS will be returned in the search results. Defaults to qasFirst.

Property: qasservice.endpointurl

Options / Example: http://localhost:2021

Description: Endpoint URL of the QAS install.

NOTE: The QAS installs on port 2021 by default. This property defaults to http://localhost:2021

Property: qasservice.searchtimeout

Options / Example: 10000

Description: Timeout in milliseconds. Default is 10000 (10 seconds)

Property: qasservice.dataid

Options / Example: GBR, LPG

Description: ID of the data set to search against. If you are not sure what to set this to, look in

QAWServe.ini within the QAS installation at the "InstalledData" property. Defaults to GBR.

Property: qasservice.addresslayout

Options / Example: ODMPropertyLayoutUK or ODMUPRNPropertyLayoutUK

Description: This corresponds to a defined layout in QAS, configured either by hand in

QAWServe.ini or through the Configuration Editor. Defaults to ODMPropertyLayoutUK.

Property: qasservice.propertymaintainer


Options / Example: uprnPropertyMaintainer or descriptionPropertyMaintainer

Description: Defines how the integration will look in the LAGAN database to check whether a

property has previously been copied in from QAS. Using descriptionPropertyMaintainer will

match on the Property's description whilst using uprnPropertyMaintainer will match on the

Property's UPRN. Default is descriptionPropertyMaintainer.

Property: odmgatewayservice.searchallfactories.property

Options / Example: false, true

Description: If you are using qasFirst or qasSecond as the value for

qasservice.providerconfiguration, this property defines whether the second search source will be

searched against if any results are returned from the first. If this is set to true, the second source

will not be searched if the first source returns any results. Defaults to false.

Property: odmgatewayservice.suppressduplicates.property

Options / Example: false, true

Description: Defines whether duplicates will be suppressed when searching multiple sources.

Defaults to true.

14.4. Setup

This section will describe setup for both LPG and GBR data sets. All instructions assume that QAS

has been installed and is functioning correctly on port 2021; if you have installed QAS on a

different port, please amend the instructions as necessary.

14.4.1. GBR Data Set Setup

Most of the configuration for the GBR data set is included in default settings but is included in the

steps below for clarity's sake, denoted as optional.

1. In the services.properties file, set qasservice.endpointurl to the Endpoint URL pointing to

your QAS installation (eg. http://bfs-product-17:2021).

2. In the services.properties file set qasservice.providerconfiguration to your chosen

search source configuration. (Optional)

3. In the services.properties file, set qasservice.dataid=GBR. (Optional)

4. In the services.properties file set the following configuration:

qasservice.addresslayout=ODMPropertyLayoutUK. (Optional)


qasservice.layouthandlerclass=com.LAGAN.LAGANcentre.core.service.odmgatewayserv

ice.quickaddress.QASLayoutHandlerUK. (Optional)


qasservice.propertymaintainer=descriptionPropertyMaintainer. (Optional)


7. Open QAWServe.ini in the directory you installed QAS in.

8. Open ODMPropertyLayoutUK.txt in the core\common\optional\QAS_Layouts directory

and append the contents to the end of QAWServe.ini.

9. In the system.properties file set quickaddress=true.

10. Restart the Quick Address service and start the LAGAN Application.

14.4.2. LPG Data Set Setup

1. In the services.properties file, set qasservice.endpointurl to the Endpoint URL pointing to

your QAS installation (eg. http://bfs-product-17:2021)

2. In the services.properties file set qasservice.providerconfiguration to your chosen

search source configuration. (Optional)

3. In the services.properties file, set qasservice.dataid=LPG.


qasservice.addresslayout=ODMUPRNPropertyLayoutUK.


qasservice.layouthandlerclass=com.LAGAN.LAGANcentre.core.service.odmgatewayserv

ice.quickaddress.QASLayoutHandlerUK. (Optional)


qasservice.propertymaintainer=uprnPropertyMaintainer.

7. Open QAWServe.ini in the directory you installed QAS in.

8. Open ODMUPRNPropertyLayoutUK.txt in the core\common\optional\QAS_Layouts

directory and append the contents to the end of QAWServe.ini.

9. In the system.properties file set quickaddress=true.

10. Restart the Quick Address service and start the LAGAN Application.

14.5. Address Format

The QuickAddress integration expects the QAS layout used to retrieve full address details to have

either 14 or 15 elements. The elements returned by this Layout will be mapped into the Property

object as follows:

1. Address Number

2. Address Line 1

3. Secondary Street Name

4. Locality

5. Town

6. County


7. Postcode

8. PO Box

9. Building Name

10. Sub Building Name*

11. Organisation

12. Department

13. RM Delivery Point Suffix

14. Sub Building Number*

15. UPRN

*NOTE: Sub Building Name and Sub Building Number are concatenated in the format "SBNAME SBNUM.


15.0 CTI Light

This section covers the steps that are required to set up a LAGAN installation that employs a soft

phone using the CTI Light interface. Third party soft phone jars are not supplied with the core CD;

it is the responsibility of the installer to obtain these jars before installation.

15.1. Property file Configuration

In userapplication.properties in LAGAN_HOME perform the following steps:

1. Set the property application.usectilight to true.

2. Set the property application.ctilightadaptor to be the package name of your CTI Light

adaptor class. (e.g. com.LAGAN.LAGANcentre.macfarlane.CTIMacfarlaneAdaptor for

Macfarlane, com.LAGAN.LAGANcentre.siemens.CTISiemensAdaptor for Siemens and

com.LAGAN.LAGANcentre.core.ctilight.CTILightSimulator for the CTI Light Simulator).

3. Set the property ctilight.provider.host to be the server name of the telephony server that

the soft phone will connect to.

4. Set the property ctilight.provider.port to be the port that the telephony server listens on.

5. As usual, the property telephony.outbounddialprefix should be set up if required for

outbound dialling.

6. As usual, the property mappings telephony.agentstation1.ip and

telephony.agentstation1.extension etc should be set up to map an agent’s phone to

their IP address. If using the name of the client machine rather than the IP address then

the property telephony.agentstation1.name should be used. Only one of these methods

should be used, not a mixture of both.

NOTE: Ensure that when listing all the IP/name to extension mappings that the indices start at 1 and are

continuous e.g. if you have configured extensions with indices 1, 2 and 4; then 4 will not be read.

7. Configure any soft phone specific properties if required.

15.2. Web start configuration

Any new jars need to be placed in the lib directory under the expanded LAGAN web application in

the servlet container. The jars also need to be added to the web start jnlp files for downloading as

follows:

1. Any third party jars (i.e. those not signed with the LAGAN certificate) should be added to

libraries.jnlp in a similar fashion to the other jars that are already in this file (e.g. cti.jar

and gui.jar for Macfarlane; procenter-toolbar.jar for Siemens). All jars that a CTI Light

partner produces should be placed here.

2. If LAGAN has produced the adaptor in some pre version 6.1 integrations, then the jar

containing LAGAN’s CTI Light adaptor packages should be signed, using the same

certificate as the other core jars, and added to the userapplication.jnlp file, in a similar

fashion to the other jars that are already in this file (e.g. Siemens.jar for Siemens).

Otherwise see the point above for newer integrations.


15.3. Configuration Studio

If an agent is going to use CTI Light then they have to belong to a telephony group. Instructions on

group configuration can be found in the Configuration Guide.

If required the user external system functionality can be employed in order to separate out the

telephony switch agent IDs and the LAGAN agent Ids.

To configure this, follow the instructions in the Configuration Guide in the User Configuration

chapter on how to configure external systems.

15.4. Optional Configuration

By default an agent has to end an interaction before a new incoming call will screen pop. There is,

however, a configuration component called Telephony Options which has a feature called End

Interaction on Answer. If this is selected and added to an agent’s group then, when a new call

comes in and the call is answered, the existing interaction will be ended automatically.


16.0 Mixed Media Integration Adaptor (MMI)

This section covers what steps are required to set up an installation that employs a third party

toolbar which implements the Mixed Media Integration (MMI) Adaptor interface. The MMI

Adaptor is an extension of the CTI Light interface which allows an agent to handle calls and

messages delivered by a third party Universal Queue. Third party tool bar jars are not supplied

with the core cd; it is the responsibility of the installer to obtain these jars before installation.

16.1. Property File Configuration

In userapplication.properties in LAGAN_HOME perform the following steps:

1. Set the property application.usemmiadaptor to true.

2. Set the property application.mmiadaptor to be the package name of your toolbar class

that implements the MMI adaptor.

E.g. com.LAGAN.LAGANcentre.core.mixedmediaintegration.MMIAdaptorSimulator for the

MMI Adaptor Simulator.

3. Set the property mmiadaptor.provider.host to be the server name of the MMI server

that the third party toolbar will connect to.

4. Set the property mmiadaptor.provider.port to be the port that the MMI server listens

on.

5. As usual, the property telephony.outbounddialprefix should be set up if required for

outbound dialling.

6. If the agent is to handle calls as well as inbound correspondence then an extension

number must be configured. Refer to the CTI Light property file configuration section for

details on this.

7. By default any replies to incoming messages are sent back through the MMI Adaptor to

the third party Universal Queue (recommended). To override this behaviour and to send

them back through the LAGAN Email server, set the property

mmiadaptor.replyusingadaptor to false.

8. By default when the incoming call flashing icon is pressed, any current message

interaction will be parked. To override this behaviour, so that an agent must manually

park the interaction before the incoming call screen is allowed to pop, set the property

mmiadaptor.parkinteraction.automatic to false.

9. Configure any MMI Adaptor specific properties if required.

In system.properties in LAGAN_HOME perform the following step:

Set the property mmiadaptor to true. TomCat, or whatever application server is employed, will

need to be restarted in order to pick up this property change.

If required the user external system functionality can be employed in order to separate out the

universal queue agent IDs and the Frontline agent Ids.

To configure this, follow the instructions in the Configuration manual in the User Configuration

chapter on how to configure external systems.


16.2. Web Start configuration

Any new jars need to be placed in the lib directory under the expanded LAGAN web application in

the servlet container. The jars also need to be added to the web start jnlp files for downloading as

follows:

Any third party jars (i.e. those not signed with the LAGAN certificate) should be added to

libraries.jnlp in a similar fashion to the other jars that are already in this file. All jars that a MMI

Adaptor partner produces should be placed here.

16.3. Configuration Studio

If an agent is going to use MMI Adaptor then they have to belong to a telephony group or an

inbound correspondence push group. Instructions on group configuration can be found in the

Configuration Guide.

installation guide 13r1 - kana communitykanacommunity.verint.com/documents/320423/498001/... · 1.0...

Documents