administration guide 13r1 - verint...

LAGAN Enterprise 13R1

Administration Guide

Product Version: 13R1

Document Version: 1.0

31 May 2013

LAGAN Enterprise 13R1Administration 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 ........................................................................................................................................ 5

2.0 Authorisation ...................................................................................................................................... 6

2.1. Users and Roles............................................................................................................................. 6

2.2. Database Layout for Users and Roles ........................................................................................... 7

2.3. Restricting Access to Data............................................................................................................. 8

3.0 Current Object Details Configuration ................................................................................................ 11

3.1. Perspectives and Portlets ........................................................................................................... 11

4.0 Customising the Agent Desktop Menus and Toolbars ....................................................................... 13

4.1. Customising Menus and Toolbars ............................................................................................... 13

4.2. Configuring the Toolbar .............................................................................................................. 17

4.3. Configuring a Menu .................................................................................................................... 17

5.0 Operational Tools .............................................................................................................................. 21

5.1. eForm Bulk Update Migration Tool ............................................................................................ 21

5.2. Handling the New Location in the eForm. .................................................................................. 23

6.0 ODM Search Configuration ................................................................................................................ 25

6.1. Configuring Layout ...................................................................................................................... 25

6.2. Configuring a New Extension Type ............................................................................................. 26

6.3. Configuring Extensions to Existing Types .................................................................................... 28

6.4. Search Configuration .................................................................................................................. 28

6.5. Specify a Source to Search .......................................................................................................... 32

6.6. Search for Newly Created ODM Objects or Party Types ............................................................. 33

6.7. Trigger Creation for New ODM Objects or Party Types .............................................................. 34

6.8. Enforcing selection of a Preferred Contact Detail ...................................................................... 34

6.9. Applying the ODM Generic Search ............................................................................................. 35

7.0 SLA Calendar Configuration ............................................................................................................... 37

7.1. Configuring the Calendar ............................................................................................................ 37

8.0 Spell Checker ..................................................................................................................................... 38

8.1. Property Files .............................................................................................................................. 38

8.2. Locale Settings ............................................................................................................................ 42

8.3. Adding Words to the Dictionaries ............................................................................................... 43

8.4. Using Spell Checker ..................................................................................................................... 44

8.5. Spell Checker Availability ............................................................................................................ 45

9.0 XML Service Document Caching ........................................................................................................ 47

9.1. Redefining Cache Lifetime .......................................................................................................... 47

9.2. Disabling the Cache .................................................................................................................... 47

10.0 Concurrent User Limit ....................................................................................................................... 48

11.0 BSF Scripting for Forms and Objects .................................................................................................. 49

11.1. Configuring a Scripting Language ............................................................................................. 49

11.2. Writing a Form Validation Script .............................................................................................. 50

11.3. Adding a Validation Script to a Form ....................................................................................... 51

11.4. Writing an Object Validation Script .......................................................................................... 52


11.5. Adding a Validation Script to an Object ................................................................................... 53

12.0 Configuring Email .............................................................................................................................. 54

12.1. Configure Email Queues ........................................................................................................... 54

12.2. Configure LAGAN Email Service ............................................................................................... 54

12.3. Configuring CC and BCC Email Fields........................................................................................ 55

12.4. Email Forwarding ..................................................................................................................... 56

12.5. Importing Email Contacts ......................................................................................................... 57

13.0 Business Calendars ............................................................................................................................ 58

13.1. Creating a New Business Calendar ........................................................................................... 58

13.2. Updating a Business Calendar .................................................................................................. 59

13.3. Using the Business Calendar .................................................................................................... 60

14.0 Auto Response Emails ....................................................................................................................... 61

14.1. Configuring the Auto Response Email ...................................................................................... 61

14.2. Writing the Auto Response Email Templates ........................................................................... 61

15.0 Integrator Intranet (II) Components .................................................................................................. 63

15.1. II Component Memory Requirements ..................................................................................... 63

15.2. Configuring II Navigation Toolbar ............................................................................................ 63

15.3. Configuring a Mix of Browser Beans ........................................................................................ 65

16.0 Localisation ....................................................................................................................................... 66

16.1. Overview of Localisation .......................................................................................................... 66

16.2. Language Localisation .............................................................................................................. 66

17.0 Letter Fulfillment Configuration ........................................................................................................ 67

17.1. Auto-Resolving Dynamic Content ............................................................................................ 67

18.0 Configuration Object Key Updater..................................................................................................... 68

18.1. Background .............................................................................................................................. 68

18.2. Running the Utility ................................................................................................................... 68

19.0 Q-Matic Integration........................................................................................................................... 69

19.1. Configuration Studio ................................................................................................................ 69

19.2. Property File Configuration ...................................................................................................... 69

19.3. Other configuration ................................................................................................................. 69

20.0 Event Mapping Notes ........................................................................................................................ 70

21.0 Encrypting Database Passwords ........................................................................................................ 72

21.1. Configuring the Property File ................................................................................................... 72

21.2. Running the Migration Utility .................................................................................................. 72

22.0 Additional Configuration ................................................................................................................... 73

22.1. Adding Predefined Tasks .......................................................................................................... 73

22.2. Closing a Case with Incomplete Tasks ...................................................................................... 73

23.0 Single Report Security Model ............................................................................................................ 74

23.1. Model Overview ....................................................................................................................... 74

23.2. Installation & Configuration ..................................................................................................... 75

23.3. Complete Installation ............................................................................................................... 75

23.4. Eclipse Plugin............................................................................................................................ 75

23.5. Designing an Example BIRT Report .......................................................................................... 76

23.6. Pagination ................................................................................................................................ 79


23.7. Search Keys .............................................................................................................................. 81

23.8. Searching Date/Time values .................................................................................................... 83

23.9. Deploying Reports in Tomcat ................................................................................................... 84

23.10. Viewing a Report ...................................................................................................................... 85

24.0 Case Data Handling ........................................................................................................................... 87

24.1. Data Archive and Purge ............................................................................................................ 87

24.2. Archive and Purge Scheduler ................................................................................................... 90

24.3. Case Indexing Tool ................................................................................................................... 93

25.0 Auditing ............................................................................................................................................ 94

25.1. Auditable Object Types ............................................................................................................ 95

25.2. Basic Configuration .................................................................................................................. 96

25.3. Advanced Configuration........................................................................................................... 97

25.4. Implementation Overview ....................................................................................................... 98

Appendix A: Event Publisher ........................................................................................................................ 101

Configure Properties ............................................................................................................................. 101

XML Configuration ................................................................................................................................ 102

Configuring if an Event gets Published .................................................................................................. 102

Configuring where an Event gets Published .......................................................................................... 107

Configuring the Transport Protocol for an Event .................................................................................. 108

Configuring an Event Transformer ........................................................................................................ 109

Event Publisher Database Table ............................................................................................................ 109


1.0 Introduction

LAGAN Enterprise is an Interaction Management software product, designed to enable exceptional

levels of service across all channels. It is flexible, enabling it to be tailored for each specific client

organisation; modular, enabling it to be used in different vertical markets; and scalable, enabling it

to be played into virtually any size of contact centre.

LAGAN Enterprise is LAGAN's premier contact centre software product. This guide covers

configuration issues that may arise at installation time or as part of ongoing system

administration.


2.0 Authorisation

Authorisation is the ability of LAGAN to implement database independent logical partitioning. This

provides the ability to logically segment data, thus restricting access to only those users who have

permission to view/alter/create/delete that data. Although many database vendors offer their

own solutions for authorisation, these are normally expensive add-ons to the standard package.

2.1. Users and Roles

Users may perform a variety of functions. Each of these functions may require different privileges.

Assigning privileges to individuals would produce a large administrative overhead. Privileges are

normally assigned to roles. Individuals are then allocated roles based on their job functions.

Indeed, roles may be assigned to other roles to create a composite role. This provides the core

building block for logical partitioning. The privileges for individuals can then be tweaked as

necessary.

Example:

USERS JOB FUNCTION

FRED Administrator, needs access to everything

WILMA Data entry for accounts

BETTY Data entry for sales

JOHN Data entry for accounts and sales

JANET Security administrator, can do data entry for any department and can reset

passwords etc.

PETER Data entry for accounts and sales also privileges to produce management reports

From the list of job function the following roles are defined

ADMIN, SALES, ACCOUNTS, SECURITY, REPORTS


Figure 2.1: User Roles

2.2. Database Layout for Users and Roles

Working the above example through the database layout would be as follows:

LGNCC_USERS LGNOM_USERROLE:

USERID

FRED

WILMA

BETTY

JOHN

JANET

PETER

ROLENAME ROLEMEMBER

ADMIN SALES

ADMIN ACCOUNTS

ADMIN SECURITY

ADMIN REPORTS

ADMIN FRED

SECURITY SALES

SECURITY ACCOUNTS

SECURITY JANET

SALES BETTY

SALES JOHN

SALES PETER

ACCOUNTS WILMA


From the above there is a case for creating a new role ACCOUNTSandSALES. This would include

the users PETER and JOHN and the roles ACCOUNTS and SALES. This highlights the flexibility of this

approach in that it can be adapted to customer specific needs to provide an easy to manage and

flexible means to define users and work function.

2.3. Restricting Access to Data

Access to data is controlled by a set of rules which are defined on a per user / per role basis.

Users/roles can be granted access to all data within a table or a limited range of data within a

table. Access rights may be different for viewing, inserting, updating or deleting, e.g. a user may be

able to enter an item but not delete it.

The security access rules are fully configurable and flexible.

Consider the following example.

The sales department is divided by region. There are two ROLES defined for SALES, SALESNORTH

and SALESSOUTH.

JOHN has the role SALESSOUTH.

BETTY has the role SALESNORTH.

WILMA has the role SALES.

Figure 2.2: Access to Data

ACCOUNTS PETER

ACCOUNTS JOHN

REPORTS PETER


Users with the SALESSOUTH role can enter and view records on the SALES table with region of

SOUTH.

They can amend records in the SOUTH region that they originally created.

Users with the SALESNORTH role can enter and view on the records on the SALES table with region

of NORTH.

They can amend records in the NORTH region that they originally created.

Users with the SALES role can enter, view, amend and delete any record on the SALES table.

Sales Table (Columns)

CUSTOMERNAME

REGION

AMOUNT

CREATEDBY

SALESNUMBER

The LGNCC_SECURITYRULES table holds the role specific rules.

Columns

TABLENAME

CONDITION

ROLE

INSERTALLOWED

DELETEALLOWED

SELECTALLOWED

UPDATEALLOWED

Example Data

TABLENAME CONDITION ROLE I D S U

SALES ((REGION = ‘SOUTH’)) SALESSOUTH 1 0 1 0

SALES ((REGION = ‘SOUTH’) (CREATEDBY =

aCurrentUser))

SALESSOUTH 0 0 0 1

SALES ((REGION = ‘NORTH’)) SALESNORTH 1 0 1 0

SALES ((REGION = ‘NORTH’) (CREATEDBY =

aCurrentUser))

SALESNORTH 0 0 0 1


SALES 1 = 1 SALES 1 1 1 1

SALES 1 = 1 PETER 0 0 1 0

NOTE: From the above the user PETER can view any sales record. The 1 = 1 condition gives access to all

records. Conversely a 1 = 2 condition would deny access to all records.

There may be only 1 entry in the rules table for a given combination of TABLE, ROLE and allowed

field set to 1. Thus, there could not be another entry for SALES and PETER with DELETEALLOWED

set to 1, but there could be a different row for SALES and PETER with INSERTALLOWED set to 1 as

this row does not yet exist. The CONDITION clause allows complex rules so there is no need for

multiple rows.


3.0 Current Object Details Configuration

The Current Details screen displays information on the current client. This screen is totally

configurable.

3.1. Perspectives and Portlets

The screen can be configured to contain a collection of perspectives. Each perspective is made up

of a collection of portlets.

Consider the following example:

Figure 3.3: Current Details Example

Figure 3.1 shows an example with two perspectives, with the perspective in view containing six

portlets.

Annotated are:

One portlet.

The tabs at the top that allow the user to pick between different perspectives.

These tabs are for “stacked” portlets. These are portlets that occupy the same perspective space.

One of these portlets is displayed, and the others can be displayed using the tabs.

This edit control causes a dialog to appear which allows the user to edit the details contained

within this portlet. (Each data field can be configured to be editable or “read only” when it is

added to the portlet).

A maximise control, which causes the portlet to fill the entire perspective space.


Another example is illustrated.

Figure 3.4: Another Current Details Example

The above perspective is the default that is installed with the 8.0 release of LAGAN.


4.0 Customising the Agent Desktop Menus and Toolbars

It is possible to apply configuration to change the appearance of the Agent Desktop menu’s and

toolbars This allows the Agent Desktop to be customised for individual needs with agents using

menu options and buttons that are more relevant to them.

4.1. Customising Menus and Toolbars

The menu options and toolbar of the Agent Desktop menu can be customised by modifying the

files menu.xml and standardToolbar.xml respectively. These default files, which can be used for

reference purposes, can be found in the LAGAN.war file which is normally unpacked to the file

system by the container.

These files should not be directly modified; instead a copy of each should be made and then

pasted into the directory the LAGAN_HOME environment variable points to; it is then these copied

files that should be modified.

NOTE: If either of the files; standardToolbar.xml or menu.xml is modified, all instances of the Agent Desktop

will need to be restarted for the changes to take effect.

It’s also possible to add new menu buttons to the Agent Desktop that link through to web pages or

web applications; these custom options are referred to as Integrator Intranet (II) components.

The default menu and toolbar for the Agent Desktop will look like this:

Figure 4.1: Default Menu and Toolbar

By modifying the xml files, it is possible to produce a different look such as this:

Figure 4.2: New Customised Menu and Toolbar

4.1.1. Options for menu.xml

The list below outlines the default ID and relevant button that will be added to the Agent

Desktopwhen modifying the menu.xml file.

NOTE: The options are case sensitive; hence use capital letters for the menu or button ID where specified.


Menu Item or Button ID Toolbar / Menu Button

newcase Create new Case

newEnquiry Create new enquiry

sendLetter Create outbound letter

Send Email Create outbound email

createRelationship Create relationship

createManualInteraction1 Log a manual voice-in interaction

createManualInteraction3 Log a manual email-in

createManualInteraction5 Log a manual fax-in

createManualInteraction9 Log a manual face to face interaction

createManualInteraction10 Log a manual mail-in interaction

createManualInteraction12 Log a manual SMS interaction

handleCase Displays the Select Case dialog; enables a user to view

assigned cases and to take a case to process

organiseCases

Displays the Organise Cases dialog; enables a user to

perform actions such as close, take, etc to multiple

cases

handleInboundCorrespondence Displays the Select Correspondence dialog; enables a

user to select an inbound email to work on

print Print button

printPreview Print preview button

changePassword Change logon password

exit Exits the application

classify Classify button

linkCaseToInteraction Link Interaction to Case button; enables user to

associate the current interaction to an existing case

setInteractionClient Set Client button; enables the interaction to be

associated with a customer

addInteractionNote Add Interaction Note button; allows the user to

associate a note with the current interaction

iiNavigation Adds an II component


updateCase Update Case button; enables the case details to be

updated

addCaseNote Add Case Note button; enables the agent to add a note

to the selected case

addEvent Add Event button; enables an event to the selected the

case

endCase Release Case button; enables the user to release a case

they currently own.

finishCase Finish Case button; enables a user to close or re-allocate

a case on which they are currently working

releaseInteraction Release Correspondence button; enables a user to

return an inbound email to its queue

parkInteraction

Park Correspondence button; enables the user to ‘park’

i.e. put aside an email they’re currently dealing with

until later

finishInteraction Finish Interaction button; ends a contact i.e. voice-in,

face-to-face, etc

verifyInteractionClient Verify Interaction button; verifies the selected object

linkCases Link Cases; enables the user to link cases together

browseCaseLinks Browser Case Links; display the Case Browser screen

addEform Add eForm; enables the user to add an eForm to the

case

suspendSLA Suspend SLA; suspends the case SLA

unsuspendSLA Unsuspend SLA; un-suspends the case SLA i.e. it begins

to count again

closeCase Close Case; enables an open case to be closed

reopenCase Reopen Case; re-opens a closed case

deleteCase Delete Case; deletes a closed case

deleteCurrentObject Delete Current Object; deletes the selected object i.e.

individual, organisation, etc

addTask Add Task; Enables the user to add a task to a selected

case.

about Adds the About option

LAGAN Agent Desktop Help Adds the option for the Agent Desktop online help


NOTE: It is possible to use the commands above in the standardToolbar.xml. This will allow the menu option

to be displayed as a button on the toolbar.

4.1.2. Options for standardToolbar.xml

The options below can be added to the standardToolbar.xml file to provide access to the various

navigation screens, i.e. those that appear under the Go menu.

Button ID Toolbar Button

navigateTo5 Contact History button

navigateTo6 Current Client Details button; enables you to view the details

of the selected object i.e. individual, organisation, etc

navigateTo7 Messaging button; enables you to view and send general,

client and instant messages

navigateTo9 Search button; enables you to search for objects

navigateTo10

Information button; displays the default web page for the

application or those web pages configured within the script

flow

navigateTo12 Alarms button; displays any alarms that have been raised

within the system

navigateTo13 Past Calls button; displays those calls an agent has made or

received. Only valid if LAGAN Enterprise has CTI

navigateTo15

Real Time Monitor button; enables a supervisor to monitor

the volume of cases per queue, which agents are logged on

and those cases that have exceeded or about to exceed their

SLA

navigateTo29 Face to Face button; only valid if LAGAN Enterprise has been

integrated with Q-matic

navigateTo36 Case Search button; enables agents to search for the details

of a case(s)

navigateTo43 Activities Button; enables agents to pick up and process any

LAGAN BPM activities assigned to them

NOTE: It is possible to use the navigateTo commands in the menu.xml. This will allow the toolbar button to

be displayed under a menu option.


4.2. Configuring the Toolbar

To configure the Agent Desktops Toolbar modify the file, standardtoolbar.xml. Below is an

example of the standardtoolbar.xml file which would display the default toolbar for the Agent

Desktop:

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

<toolbar>

<button id="newcase" text="displayed" />

<button id="createManualInteraction1" text="displ ayed" />

<button id="finishInteraction" text="displayed" / >

<button id="navigateTo9" text="displayed" />



<button id="setInteractionClient" text="displayed " />

<button id="addCaseNote" text="displayed" />

<button id="updateCase" text="displayed" />

<button id="finishCase" text="displayed" />

<glue />

<placeholder id="quicksearch" />

</toolbar>

Configuring this file with one of the options in the tables in section 4.1 will change how the Agent

Desktop toolbar is displayed. For example if the line navigateTo5 is removed and navigateTo36 is

inserted instead, this would replace the Contact History button with the Case Search button on

the Agent Desktop Toolbar.

4.3. Configuring a Menu

To configure a menu within the Agent Desktop modify the file, menu.xml. Below is an example of

the menu.xml file which would display the default menus for the Agent Desktop:

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

<menubar id="mb" constraints="BorderLayout.NORTH" >

<menu id="file" text="menu.file">

<menu id="new" text="menu.new">

<menuitem id="newcase" />

<menuitem id="newEnquiry" />

<separator />

<menuitem id="sendLetter" />

<menuitem id="sendEmail" />

<separator />

<placeholder id="objectCreation" />

<separator />


<menuitem id="updateCase" />

<menuitem id="addCaseNote" />

<menuitem id="addEvent" />

<menuitem id="endCase" />

<menuitem id="finishCase" />

<separator />

<menuitem id="releaseInteraction" />

<menuitem id="parkInteraction" />

<menuitem id="finishInteraction" />

<separator />

<menu id="advanced" text="More actions">

<menuitem id="verifyInteractionClient" />

<separator />

<menuitem id="linkCases" />

<menuitem id="browseCaseLinks" />

<menuitem id="addEform" />

<menuitem id="addTask" />

<separator />

<menuitem id="suspendSLA" />

<menuitem id="unsuspendSLA" />

<separator />

<menuitem id="closeCase" />

<menuitem id="reopenCase" />

<separator />

<menuitem id="deleteCase" />

<menuitem id="deleteCurrentObject" />

</menu>

</menu>

<menu id="help" text="menu.help">

<menuitem id="about" />

</menu>

</menubar>

Configuring this file with one of the options in the tables in section 4.1 will change how the Agent

Desktop menu is displayed. For example if the following XML was removed from the menu.xml

file, the Update Case and Add Case Note would be removed from the Actions menu:




Alternatively if the following XML is removed then the entire Actions menu and all the options

within would be completely removed:

<menu id="actions" text="menu.actions">

<menuitem id="classify" />

<menuitem id="linkCaseToInteraction" />

<menuitem id="setInteractionClient" />

<menuitem id="addInteractionNote" />

<separator />



<menuitem id="addEvent" />

<menuitem id="endCase" />

<menuitem id="finishCase" />

<separator />

<menuitem id="releaseInteraction" />

<menuitem id="parkInteraction" />

<menuitem id="finishInteraction" />

<separator />

<menu id="advanced" text="More actions">

<menuitem id="verifyInteractionClient" />

<separator />

<menuitem id="linkCases" />

<menuitem id="browseCaseLinks" />

<menuitem id="addEform" />

<menuitem id="addTask" />

<separator />

<menuitem id="suspendSLA" />

<menuitem id="unsuspendSLA" />

<separator />

<menuitem id="closeCase" />

<menuitem id="reopenCase" />

<separator />

<menuitem id="deleteCase" />

<menuitem id="deleteCurrentObject" />

</menu>

</menu>

The XML can be configured in whatever way necessary to have all the menus and options within

them customised to suit specific installs.


5.0 Operational Tools

The Operational Tools functionality has changed since earlier versions. It still allows the Import

and Export of configuration data between two LAGAN systems, however this is now done using

the Operational Tools Wizard.

The Operational Tools Wizard guides the user through the process of moving configuration from

one server to the other.

To find out how to install and use the Operational Tools Wizard, please refer to the LAGAN

Operational Tools Guide.

5.1. eForm Bulk Update Migration Tool

With LAGAN eForms the expanded Ef3 folder is now secured and now requires a user name and

password. Historically this folder has been used to contain any user defined files which support

eForm development, such as style sheets and XSLT files.

When defining an eForm, the user would normally specify the location of such a file, which has

typically been stored in this, now secured, directory e.g. Ef3/myFile.css.

These files should now reside in Ef3config.war which avoids these security restrictions

and reduces the impact of future upgrades.

Existing eForms that are migrated will need to be updated to now refer to this alias instead of

directly referring to Ef3.

As changing these references would be tedious and error prone, LAGAN have provided a Bulk

Update Migration Tool that may alter ALL eForm Definitions (AND VERSION) residing in the

specified environment.

This tool is essentially a search and replace utility that will replace the contents of specified eForm

elements or tags when a condition or search criteria has been met. The main difference

with traditional search/replace tools is that we are using the tag or element name as an additional

condition that needs to be met i.e. only the contents within a specified tag will be altered when it

meets the criteria.

The tool was written to be as generic as possible, so it can be used for more than the scenario

outlined.

5.1.1. Scenarios

The following scenarios are used as examples in the tag.xml below.

1. Refer to the new alias for files that normally reside in Ef3

2. Server/Port names

3. Included files: html, jsp & txt

5.1.2. Operation

To use the Bulk Update Tool, navigate to the /tools/startup folder. In this folder you will find a file

called tag.xml (shown below)

This xml file allows a user to define what tags or elements in the eForm definition that you want to

search and replace their contents. The numbers denoted before each <Tag> element provide an

example of the corresponding scenario as outlined above.

To use the Bulk Update Tool, follow the steps outlined below:

Navigate to the /tools/startup folder.

Locate and open the tag.xml file.

Configure the tag.xml file as required and close.

Under the /tools/startup folder locate and execute the Eformdefinition.bat file.

Enter a valid Username and Password.

This will read the tag.xml and automatically update all eForms.

NOTE: The update tool is very powerful but LAGAN can only recommend its use in the scenarios outlined

above as it affects all eForm Defintion versions in your environment.

Tag.xml

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

<Start>

<Tag>

<Name>Form</Name>

<attribute>xmlns:flt=[http://www.LAGAN.com/wsdl/FLT ypes]</attribute>

<attribute>xmlns:wsse=[http://docs.oasis-

open.org/wss/2004/01/oasis-200401-wss-wssecurity-se cext-

1.0.xsd]</attribute>

<attribute>xmlns:soapenv=[http://schemas.xmlsoap.or g/soap/envelope/]</attr

ibute>

</Tag>



<Tag>

<Name>Style</Name>

<oldValue>Ef3</oldValue>

<newValue>Ef3config</newValue>

</Tag>



<Tag>

<Name>Javascript</Name>

</Tag>



<Tag>

<Name>ResultTransformer</Name>



</Tag>



<Tag>

<Name>Server</Name>

<oldValue>flweb</oldValue>

<newValue>LAGAN</newValue>

</Tag>



<Tag>

<Name>Server</Name>

<oldValue>8080</oldValue>

<newValue>9080</newValue>

</Tag>



<Tag>

<Name>Header</Name>

<oldValue>headers/Header1.jsp</oldValue>

<newValue>Ef3config/eForms/headers/Header2. jsp</newValue>

</Tag>

</Start>

5.2. Handling the New Location in the eForm.

In an eForm, the location of a customisable file could be modified in the following places.

Type of file Example tags, relative to Ef3

Style sheet <Style>myStyle.css</Style>

XSLT <ResultTransformer>myXSLTfile.xslt</ResultTransformer>


Images <Image>

<Path>myIcon.jpg</Path>

</Image>

Header <Header>myHeader.jsp</Header>

(NB, modified url will require absolute path to be given for header files)

Include jsp <Include>

<Path>myInclude_this.jsp</Path>

</Include>

(NOTE: Modified URL will require absolute path to be given for include files)

JavaScript <Javascript>http://localhost:8080/Ef3/name.js</Javascript>

These new locations could be referenced in the eForm as so:

Type of File Referenced via

Style sheets Accessed via absolute path - http://localhost:8080/Ef3config/myStyle.css

Or relative path - /Ef3config/myStyle.css

XSLT Accessed via absolute path - http://localhost:8080/Ef3config/myXSLTfile.xsl

Or relative path - /Ef3config/myXSLTfile.xsl

Images Accessed via absolute path - http://localhost:8080/Ef3config/myIcon.jpg

Or relative path - /Ef3config/myIcon.jpg

Header Must be an absolute URL - http://localhost:8080/Ef3config/myHeader.jsp

Include Must be an absolute URL -

http://localhost:8080/Ef3config/myInclude_this.jsp

JavaScript Accessed via absolute path - http://localhost:8080/Ef3config/name.js

Or relative path - /Ef3config/name.js

NOTE: For absolute paths, codebooks can be used to reference the correct location. For relative paths,

leading slash is required.


6.0 ODM Search Configuration

The configuration for the ODM Search is done through the odmsearch.properties file. It is used to

define advanced "grid-style" configuration for ODM Search Forms defined in the LAGAN

Configuration studio and in LGNOM_SEARCHTYPEMAP in a LAGAN database.

Configuration for a given search form in odmsearch.properties is optional; where this

configuration is not present the simple "list-style" configuration set up in the Form designer in the

Configuration Studio will be used. Configuration for a given form takes the form of 3 parts:

• A list of column widths

• A list of row heights

• A series of entries in the grid defined by the column widths and row heights denoting the

location of each item in the Form that is to be displayed

The results returned through an ODM search are limited through the key in the services.properties

file:

• odmsearch.searchlimit=100

The default value is 100. This setting helps prevent potential accidental overload of the database

when wide-ranging search criteria has been specified.

6.1. Configuring Layout

All keys used to configure layout for a given form in odmsearch.properties start with the following

format:

• odmgatewayservice.searchform.[formname]

Where [forname] is the name given to a form in the Configuration Studio. This is case insensitive

when used in odmsearch.properties. For example, all keys for the default Individual Search Form

begin as follows:

• odmgatewayservice.searchform.individualsearch

An example of column width configuration is shown below:

• odmgatewayservice.searchform.individualsearch.columns=0.15,0.35,0.15,0.35

This example divides the form display area into 4 columns of widths 15%, 35%, 15% and 35%

respectively.

NOTE: The column width configuration is always on a percentage basis and the widths for each column must

total 100% as shown above.

An example of row width configuration is shown below:

• odmgatewayservice.searchform.individualsearch.rows=0.2,0.2,0.2,0.2,0.2

This example divides the form display area into 5 rows each taking 20% of the total available

height. As with column width configuration, row height configuration is always on a percentage

basis and the heights for each row must total 100% as shown above.


An example of location configuration for several form items is shown below:

odmgatewayservice.searchform.organisationsearch.aPostcode.label.position=1,4

odmgatewayservice.searchform.organisationsearch.aPostcode.field.position=2,4

odmgatewayservice.searchform.organisationsearch.aPostcode.field.span=3,1

odmgatewayservice.searchform.organisationsearch.aAddressNumber.label.position=1,5

odmgatewayservice.searchform.organisationsearch.aAddressNumber.field.position=2,5

odmgatewayservice.searchform.organisationsearch.aStreetName.label.position=3,5

odmgatewayservice.searchform.organisationsearch.aStreetName.field.position=4,5

All entries for an individual form item start with the following pattern:

• odmgatewayservice.searchform.[formname].[formitemname]

Where [forname] is the name given to a Form in the Configuration Studio and [formitemname] is

the name of the Form Item we are defining layout for as configured in the Configuration Studio.

NOTE: [formname] is case insensitive but [formitemname] is case sensitive

If we examine the configuration there are two entries for each Form Item, a label and field entry.

The position entries are of the following format:

• odmgatewayservice.searchform.[formname].[formitemname].[label/field].position=[colum

n],[row]

Fields & Labels may have also span more than one column or row using the span property, as

shown below:

• odmgatewayservice.searchform.[formname].[formitemname].[label/field].span=[columns],

[rows]

So, in the above example, the aPostcode Form Item will have its Label placed in Column 1 of Row 4

while its Field will be placed in Column 2 or Row 4 and will span 3 Columns and 1 Row.

6.2. Configuring a New Extension Type

New Object types may be configured in addition to the Four standard Object types of Individual,

Organisation, Property and Street. Configuration of a new Object involves creation of Database

Tables in which to store the Object’s information and the creation of Meta Data to inform the

LAGAN Enterprise system that this new Object type exists and is available for use.

Version 8.0 also supports modeling new Object types in methods similar to both the existing Street

object (a single database table which holds all information about an object) or similar to the

existing Individual object where a database table serves as the “root” of the object and a series of

“child” tables hold information about the Individual which may occur multiple times E.g. Names,

Addresses, Phone numbers or Email addresses.


Database tables should be created in the way any database table would be created and may have

as many columns as the RDBMS platform supports. Tables must also conform to the following

guidelines.

• All tables must have a column declared as PRIMARY KEY which is of type NUMERIC (18) in SQL

Server or type NUMBER (18) in Oracle.

• All tables must have a column named DELETEIND of type CHAR(1), used to signify that an

object is deleted.

• If a table is a “child” table, it must have a column named FOREIGNKEYID of type NUMERIC (18)

in SQL Server or type NUMBER (18) in Oracle. This must be registered when configuring the

object, which will be explained later.

After creating a Database table to store an object’s details, an entry must be made into the

LGNCC_EXTENSIONSTORECATALOG table according to the following guidelines:

• Column TABLENAME – the name of the Database table used to hold the Object’s details

• Column PARENTTABLE – NULL

• Column FOREIGNKEYIDCOLUMN – NULL

An entry must also be placed in LGNCC_EXTSTORESEQUENCECATALOG according to the following

guidelines:

• Column TABLENAME – the name of the Database table used to hold the Object’s details.

• Column SEQUENCENAME – the value LGNOM_IDSEQ

An entry must be placed in LGNOM_OBJECTHIERARCHY according to the following guidelines:

• Column OBJECTTABLE – the name of the Database table used to hold the Object’s details

• Column Parent – NULL

An entry must also be placed in LGNOM_OBJECTDEFNS according to the following guidelines:

• Column OBJECTTYPE – A unique numeric type for this object

• Column OBJECTTABLE – the name of the Database table used to hold the Object’s details

• Column ISCLIENT – 1 if this object is a Client, 0 otherwise

Finally, an entry must also be placed in LGNOM_CODEDESC according to the following guidelines:

• Column ID – the next unique ID from the LGNOM_IDSEQ sequence.

• Column TYPECODE – the value IDTYPE

• Column CODE - the name of the Database table used to hold the Object’s details

• Column SHORTDESC – a short description

• Column LONGDESC – a longer description

• Column STARTDATE – the current date

• Column PERMITMODIFY – the value ‘N’


This completes the definition of a simple Object type similar to the core Street object. In order to

add a “child” record to this type, follow the steps below:

Define a database table.

Place an entry in LGNCC_EXTSTORESEQUENCECATALOG as in the method outlined above.

Place an entry in LGNCC_EXTENSIONSTORECATALOG similar to the method outlined above but

placing the name of the “parent” table in the PARENTTABLE column and “FOREIGNKEYID in the

FOREIGNKEYIDCOLUMN column.

Place an entry in LGNOM_CODEDESC as in the method outlined above.

The above description will configure a new type so it is available for use via Web Services. To

configure Portlets for the new object please refer to Portlet Configuration documentation.

6.3. Configuring Extensions to Existing Types

Extension of existing types is very similar to the configuration of new extension types. Firstly, the

following property must be set in system.properties in LAGAN_HOME:

odmextension=true

NOTE: The odmextension property is now set to true by default, however you should ensure that this

property is set correctly.

To extend an existing core Table, all that needs to be done is to add a new column to the table.

This column can then be accessed via Portlet Configuration and Web Services.

To add a new “child” record to an existing type, follow the steps outlined above using the

appropriate table which is used to store core Object’s details as the parent table.

6.3.1. Supported ODM Extensions

The following types are supported by ODM Extensions:

• VARCHAR2 (Oracle) / VARCHAR (SQL Server)

• NUMBER (Oracle) / NUMERIC (SQL Server)

• DATE (Oracle) / DATETIME (SQL Server)

6.4. Search Configuration

Existing searches may be customised either to modify search behaviour or to add additional search

parameters. Additionally, new searches can be configured against Extension types.

Search configuration is based around a Form (to collect search criteria), a Stored Procedure (to

receive this data and search against the database using the supplied criteria) and an implicit

mapping between the two. Forms used for searching are configured in the LAGAN Configuration

Studio under Forms -> Forms.


The implicit mapping noted above takes place via a relationship between Form Item Name and

arguments in the Search Procedure. For example, if a Form used for searching has a Form Item

named “ADDRESSLINE1” then the contents of this field will be passed through to a parameter

named “ADDRESSLINE1” in the Stored Procedure used to carry out this search. Any arguments on

a Stored Procedure which do not match up with a Form Item in the Form used for searching will be

passed through as NULL.

In addition to a list of search criteria configured in the search Form, each Stored Procedure will be

supplied with the following additional arguments:

• aSearchType: The numeric type of this search, as configured in LGNOM_SEARCHTYPEMAP.

• aUserId: The User ID of the user who has carried out this search.

• aOptions: The type of matching being used for this search. Valid types are as follows:

• ‘l’ – Case Sensitive LIKE

• ‘L’ – Case Insensitive LIKE

• ‘e’ – Case Sensitive EQUALS

• ‘E’ – Case Insensitive EQUALS

• ‘c’ – Case Sensitive “CONTAINS”

• ‘C’ – Case Insensitive “CONTAINS”

• ‘S’ – “Sounds Like”

If the above arguments are not required by a given stored procedure, they do not have to be

declared as arguments. The search results must be returned in the following 8-column format:

• Result named XREF1 – the contents of XREF1 in LGNOM_IDTYPELIST for this search result.

• Result named XREF2 – the contents of XREF2 in LGNOM_IDTYPELIST for this search result.

• Result named XREF3– the contents of XREF3 in LGNOM_IDTYPELIST for this search result.

• Result named DESCRIPTION – a textual description of this search result. This may be the

contents of DESCRIPTION in LGNOM_IDTYPELIST for this search result.

• Result named DETAILS – further textual description of this search result. This may be the

contents of DETAILS in LGNOM_IDTYPELIST for this search result

• Result named OBJECTTYPE – the contents of OBJECTTYPE in LGNOM_IDTYPELIST for this

search result.

• Result named OBJECTCATEGORY – the contents of OBJECTCATEGORY in LGNOM_IDTYPELIST

for this search result.

• Result named ISCLIENT – a value of 1 to signify that this search result is a Client or 0 to signify

that it is not.

After defining the Form & Stored Procedure to be used for searching, an entry must be made into

the LGNOM_SEARCHTYPEMAP according to the following guidelines:

• Column SEARCHTYPE – the numeric type of this search. This value must be unique in this

table.


• Column FORMKEY – the name of the Form to be used to collect criteria for this search.

• Column STOREDPROCEDURENAME – the name of the Stored Procedure to be used to search

• Column DISPLAYINDEX – a number which defines the position this search will be displayed in.

Searches will be displayed in ascending order of the value of this column.

In summary, the outline process to create a new search type is a follows:

1. Create a Form to gather search criteria.

2. Create a Stored Procedure to execute the search.

3. Add a row in to LGNOM_SEARCHTYPEMAP to make the search available.

4. To add criteria to an existing search type:

5. Modify the Form to add a new item.

6. Add the new argument to the Stored Procedure which executes the search.

6.4.1. Extending a Core Search

When extending a core search which will already have a Search Form defined for it, display

configuration must be added to odmsearch.properties. For example, if we add a field called

aExtensionField to the Individual Search Form we would need to add similar configuration to the

following:

• odmgatewayservice.searchform.individualsearch.aExtensionField.label.position=3,5

• odmgatewayservice.searchform.individualsearch.aExtensionField.field.position=4,5

NOTE: A new field must either replace an existing field in a layout or Column and Row widths must be

updated in order to display the field. See above for information on changing the layout.

6.4.2. Disabling a Search Type

To disable a search type we need to alter the LGNOM_SEARCHTYPEMAP database table. This is

different from previous versions where each of the 5 core search types could be disabled/enabled

using odmsearch.properties; this file is now only used to configure the layout of a search form.

To disable a search we need to set the DISPLAYINDEX value for the row in

LGNOM_SEARCHTYPEMAP which represents this search to -1. For example, to disable the Street

Search we would run the following SQL:

UPDATE LGNOM_SEARCHTYPEMAP SET DISPLAYINDEX = -1 WHERE FORMKEY =

'StreetSearch';

6.4.3. Add Criteria to an Existing Search type

To add criteria to an existing search type:

1. Modify the Form to add a new item


2. Add the new argument to the Stored Procedure which executes the search

6.4.4. Calling Extended Core Search Types via Web Services

New Search Types and extended Core Search Types can only be called using the searchForObject

FLWeb method. This call takes 3 parameters:

1. Search Type - the numeric type of the search as defined in LGNOM_SEARCHTYPEMAP

(see above)

2. One or more FWTKeyValue entries representing an argument to be passed to the Stored

Procedure that will execute this search.

3. Options - at present this contains solely the Matching Type to be used in this search (such

as like, equals etc.). See above for a list of possible values.

The Key for each FWTKeyValue entry should match the Argument name of the Argument you wish

to pass this value to on the corresponding Stored Procedure that will execute this search, similarly

to how Search Forms are configured against Stored Procedures in the Agent Desktop and Agent

Desktop Light. Any arguments on the stored procedure that do not have a value passed in will be

passed to the stored procedure as null. For example, to call the core Individual Search supplying

Surname, Phone number and a new argument added to LGNOM_ODM_SearchParty called

aMyNewArgument1 as parameters:

<soapenv:Envelope

xmlns:soapenv=" http://schemas.xmlsoap.org/soap/envelope/"

xmlns:flt=" http://www.LAGAN.com/wsdl/FLTypes" >

<soapenv:Header/>

<soapenv:Body>

<flt:FWTObjectSearchCriteria>

<SearchType>8</SearchType>

<Criteria>

<Key>aSurname</Key>

<StringValue>Smith</StringValue>

</Criteria>

<Criteria>

<Key>aPhoneNumber</Key>

<StringValue>02890</StringValue>

</Criteria>

<Criteria>

<Key>aMyNewArgument1</Key>

<StringValue>aValue1</StringValue>

</Criteria>

<Options>l</Options>

</flt:FWTObjectSearchCriteria>

</soapenv:Body>


</soapenv:Envelope>

NOTE: Even if a core search type, for example Party Search, has been extended that the old style methods

(such as searchForParty) will still work but that no data will be passed to any new arguments on the stored

procedure.

6.4.5. Error when Searching in Agent Desktop Light

The folllwing error may be displayed when searching within the Agent Desktop Light:

There was a problem processing the request

Didn't expect any parameters: none were declared

The entry of the SCHEMA column in the LGNCC_SCHEMA database column is incorrect. This

should match your database user name for Oracle installations or, for Microsoft SQL Server, your

database user name unless the user is configured with the dbo role in which case the SCHEMA

entry should be dbo. After changing the contents of this table your application server must be

restarted.

6.5. Specify a Source to Search

It is also possible to specify a source to search from the list of possible sources along with the

other criteria for a search. To achieve this, the following steps are required:

1. On the Form configuration screen within the Configuration Studio add a Form Item

named source of type Combo Form Item to the search form for the search you are

configuring.

2. This form item should have a value for each source in the configured list of sources plus

an extra value to signify All Sources. Each value should be a number corresponding to the

position in the list of sources, starting at 0 for the first source. The value for "All Sources"

should be -1.

3. Following the above example would result in a Combo Form Item with values -1 for All

Sources, 0 for the ODM and 1 for Quick Address. The name of the search form for each

search type is as follows:

• 2 – PartySearch

• 4 – PropertySearch

• 6 – StreetSearch

• 8 – IndividualSearch

• 10 - OrganisationSearch

4. For each entry in the above configured Combo Form Item, an entry should be added to

locale.properties to provide appropriate screen text. Following the above example, the

following entries would be placed in locale.properties.

form.PropertySearch.source.-1=All

form.PropertySearch.source.0=LAGAN

form.PropertySearch.source.1=QAS


5. Add layout information for the source component in odmsearch.properties in

LAGAN_HOME. Following the above example this may be similar to the following:

• odmgatewayservice.searchform.propertysearch.source.label.position=<COLUMN>,

<ROW>

• odmgatewayservice.searchform.propertysearch.source.field.position=<COLUMN>,

<ROW>

6. This may require the re-positioning of other components in the layout for form. The

easiest way to achieve this is to add another row to the layout. This would require, for

example, the following line:

• odmgatewayservice.searchform.streetsearch.rows=0.25,0.25,0.25,0.25

To become the following:

• odmgatewayservice.searchform.streetsearch.rows=0.2,0.2,0.2,0.2,0.2

NOTE: The total of all the values must equal 1. The following would then be added to odmsearch.properties:

• odmgatewayservice.searchform.propertysearch.source.label.position=1,5

• odmgatewayservice.searchform.propertysearch.source.field.position=2,5

6.5.1. Limiting Store Procedure Searches on a Per Search Type basis

In the services.properties file, add a line similar to the following:

• odmsearch.pertypesearchlimit=619,100,192,100

This line configures Search types 619 and 192 to limit results to a maximum of 100 each.

6.6. Search for Newly Created ODM Objects or Party Types

If you have created a new ODM Object or Party Type you need to use the searchForObject web

service call to search for them.

If you come across an error in the log file such as:-

org.springframework.jdbc.BadSqlGrammarException:

CallableStatementCallback; bad SQL grammar [

{call LGNIT_EXT_DOGSEARCH()}]; nested exception is

com.microsoft.sqlserver.jdbc.SQLServerException: Pr ocedure or function

'LGNIT_EXT_DOGSEARCH ' expects parameter '@aUserID' , which was not

supplied.

A possible cause could be that there is a space in the name of the stored procedure e.g.

'LGNIT_EXT_DOGSEARCH ' instead of 'LGNIT_EXT_DOGSEARCH' as technically this is not classed as

the same stored procedure.

NOTE: Within SoapUI you may find an error such as 'General Error, Code 10'.


6.7. Trigger Creation for New ODM Objects or Party Types

NOTE: There needs to be two triggers created for each new Object or Party Type.

One trigger should be on the LGNOM_IDTYPELIST table to insert a value into the 'Description' field.

If for example you where creating a Prisoner then Name would be a good detail to insert into this

field as it identifies the prisoner.

NOTE: If this trigger is not created the object or partytype cannot be retrieved using the FLWeb Services.

The second trigger should be on the new table you create e.g. if you where creating a new

LGNIT_PRISONER table for prisoners and you have the above trigger to insert the prisoners name

into the 'Description' field. If you subsequently where to update the Prisoners name, then this will

not automatically update the 'Description' field in the LGNOM_IDTYPELIST. Therefore you will

need a trigger on the LGNIT_PRISONER table to update the LGNOM_IDTYPELIST table when the

Prisoners name is updated.

6.7.1. ODM Extensions and MSS Triggers

Any MSS trigger which conforms to the following must be edited and recompiled so that the body

of the trigger processes the extra columns:

• uses INSTEAD OF.

• is applied to an ODM core table which has been extended with extra columns.

• processes columns by name.

6.8. Enforcing selection of a Preferred Contact Detail

This issue can be addressed through portlet configuration. There is a system of rules for radio

button behaviour (ie. the preferred column) in portlet tables which defaults to enforcing that at

most one row is selected but selection of any row is not mandatory. This can be changed to

normal radio button behaviour ie. one row and only one row must be selected as preferred. This

will have the effect of setting the first row added to any portlet table as preferred, which should

cover the case outlined above. This can be turned on with the following SQL:

• update lgncc_tablerules set ruleid = 1 where fieldid = 1407

Where 1407 is the portlet Field ID of the preferred column in question - 1407 applies to the

Preferred column of the Party address table. Preferred columns for other portlet tables are as

follows:

• Phone Contacts - 807

• Email Details - 2006


6.9. Applying the ODM Generic Search

Although ODM Generics are migrated to new table-based storage, the migration path for any

Generic searching is a manual one. There are some configuration changes that need to be

executed in order to upgrade the Generics Search.

For example, with a given Generic Big with a record type of REGDETAILS searching on VALUE1

column, the Generic search configuration would look like this:

• odmgatewayservice.genericsearch.genfield1.table=LGNOM_GENERICBIG

• odmgatewayservice.genericsearch.genfield1.recordtype=REGDETAILS

• odmgatewayservice.genericsearch.genfield1.column=VALUE1

Having migrated Generics using the standard LGNEX table prefix, the configuration should now

look like this:

• odmgatewayservice.genericsearch.genfield1.table=LGNEX_REGDETAILS

• odmgatewayservice.genericsearch.genfield1.column=VALUE1

NOTE: The recordtype value is now ignored.

6.9.1. Running the Generic Migration Tool

The GenericMigrator.bat is a tool that populates the LGNOM_GENERICBIG and

LGNOM_GENERICSMALL columns and values to the new table that would be use for searching.

For Example, if the column recordtype value under the LGNOM_GENERICBIG is REGDETAILS, the

new table that will be created will be LGNEX_ REGDETAILS.

To run the Generic Migration tool follow the steps outlined below:

Under the tools/startup folder, execute the file, GenericMigrator.bat –all

NOTE: If this tool is run twice with the ‘–all’ switch or with the same generic specified, you will receive errors

stating that certain tables are already in use.

Under the file services.properties, add the following fields for the generics to work.

odmgatewayservice.genericsearch.genfields1.table=

odmgatewayservice.genericsearch.genfields1.column=








NOTE: The table fields represent the specific database table that is mapped to the ODM object. And the

columns are the actual columns of the generic tables.

Sample Values:

odmgatewayservice.genericsearch.genfields1.table=LGNEX_REGDETAILS

odmgatewayservice.genericsearch.genfields1.column=value1


7.0 SLA Calendar Configuration

LAGAN provides a calendar which it uses for SLA’s to determine the target completion date taking

into account the working days and hours of an organisation. The default setting for this is:

• Saturdays and Sundays are marked as Holidays

• Start Time is 08:30

• End Time is 17:00

7.1. Configuring the Calendar

Making changes to the Calendar requires some previous knowledge of SQL, since any changes

must be made using SQL queries. The SLA Calendar is stored in database table: LGNCC_Calendar.

This table is composed of the following columns:

LGNCC_Calendar:

• CalDate – Calendar Date

• (MMM DD YYYY) for SQL Server

• (DD-MMM-YYYY) for Oracle

• startTime – Start of working day(0000-2400)

• endTime – End of working day(0000-2400)

• HolInd – Is Holiday(0,1) 1 indicating a holiday

If you wish to change the end of working time for the 9th

April 2013, to 17:30 then you should use

the following SQL query:

SQL Server

Oracle

Update LGNCC_Calendar

Update LGNCC_Calendar

Set endTime = 1730

Set endTime = 1730

Where CalDate = ‘Apr 9 2013’

Where CalDate = ’09-APR-2013’;

NOTE: Oracle and SQL server store calDate differently. SQL server requires a space in the first day digit if a

single digit, i.e.

‘Apr 9 2013’ – two spaces between Apr and 9

‘Apr 19 2013’ – One space between Apr and 1

Oracle requires month to be in uppercase


8.0 Spell Checker

The Spell Checker functionality allows the user of the Configuration Studio and the Agent Desktop

to check the spelling of the text that has been entered in any free text area.

This section will outline how to configure and implement the Spell Checker functionality.

8.1. Property Files

There will be a new property file, spellchecker.properties, deployed with the main LAGAN WAR

file that will contain all the configuration options for the Spell Checker. As with the other

properties files this will be located in the webapps\LAGAN\config folder.

It is recommended that the spellchecker.properties file is copied to the LAGAN_HOME folder so

that any changes made to it will take precedence over the file located in the webapps directory

The properties included in spellchecker.properties are detailed below with their default values in

the properties file:

8.1.1. Composite Word Configuration

1. SPLIT_WORDS_OPT (Default false)

If set to false the spell checker will treat concatenated words as all one word. If set to

true the spell checker will treat concatenated as one word unless it can't find it in its

dictionary, then it will try to find valid sub words and check these individually.

E.g.

If set to true, and dumptruckdriver was not found in the dictionary, the spell checker

would attempt to locate valid sub-words (in this case dump, truck, and driver), and treat

dumptruckdriver as correctly spelled if all sub-words are found in the dictionary

If set to false, report dumptruckdriver if it is not found in the dictionary

2. SPLIT_HYPHENATED_WORDS_OPT (Default true)

If set to false the spell checker will treat hyphenated words as all one word. If set to true

the spell checker will treat hyphenated words as one word unless it can't find it in its

dictionary, then it will split the words and try to check them individually

E.g.

If set to true, and bright-blue was not found in the dictionary, it will check both bright and

blue and treat bright-blue as correctly spelled if both words are found.

If set to false, report bright-blue as misspelled if not found in the dictionary.

3. SPLIT_CONTRACTED_WORDS_OPT (Default false)

If set to false the spell checker will treat words contracted using apostrophe as all one

word. If set to true the spell checker will treat words contracted using apostrophes as


one word unless it can't find it in its dictionary, then it will split the words and try to check

them individually

E.g.

If set to true, and quell'anno was not found in the dictionary, then the spell checker

would check both quell and anno, and treat quell'anno as correctly spelled if both words

are found in the dictionary

If set to false, report quell'anno if it was not found in the dictionary.

4. SUGGEST_SPLIT_WORDS_OPT (Default true)

If set to true the suggest method should attempt to split words into two valid sub-words.

If set to false split words will not be suggested.

E.g.

If set to true, it will suggest the boy as a replacement for theboy. If set to false, it will not

suggest the boy.

8.1.2. Mixed Case Configuration

1. REPORT_UNCAPPED_OPT (Default true)

If set to false uncapitalised words should not be reported. If set to true they will be

reported.

E.g.

If set to true, it will report canada, if set to false, it will not report canada.

NOTE: If using the REPORT_UNCAPPED option above, ensure that the IGNORE_CAPPED option is configured

differently. Having them both set to the same value will cause unexpected results.

2. IGNORE_CAPPED_WORD_OPT (Default false)

If set to true if words should be ignored if they begin with an upper-case letter. Set to

false if the words should be checked for spelling errors.

E.g.

If set to true, ignore Clarkson, if set to false, check Clarkson.

NOTE: If using the IGNORE_UNCAPPED option above, ensure that the REPORT_CAPPED option is configured

differently. Having them both set to the same value will cause unexpected results.

3. CASE_SENSITIVE_OPT (Default true)

If set to true any words with different letter-case patterns will be treated as different

words. If set to false any words containing different case patterns should be treated as

identical.

E.g.


If set to true, treat Canada and canada as two different words; if set to false, treat Canada

and canada as the same word

NOTE: Setting this option to false will degrade performance.

4. IGNORE_MIXED_CASE_OPT (Default false)

If set to true any words containing an unusual mixture of upper and lower-case letters

should be ignored. If set to false such words should be checked for spelling errors.

E.g.

If set to true, ignore PrintScreen; if set to false, check PrintScreen

NOTE: If using the IGNORE_MIXED_CASE option above, ensure that the REPORT_MIXED_CASE option is

configured differently. Having them both set to the same value will cause unexpected results.

5. REPORT_MIXED_CASE_OPT (Default false)

Set to true if words containing an unusual combination of upper and lower-case letters

should be reported. Set to false if such words should not be reported.

E.g.

If set to true, report TUesday; if set to false, do not report TUesday

NOTE: If using the REPORT_MIXED_CASE option above, ensure that the IGNORE_MIXED_CASE option is


6. IGNORE_ALL_CAPS_WORD_OPT (Default false)

Set to true if words consisting entirely of upper-case letters should be ignored. Set to

false if the words should be checked for spelling errors.

E.g.

If set to true, ignore ASAP; if set to false, check ASAP

8.1.3. Miscellaneous Configuration

1. STRIP_POSSESSIVES_OPT (Default true)

Set to true if possessives of the form's and s' should be removed from words before

checking their spelling. Set to false if words should be checked with their possessives

intact.

NOTE: The dictionaries provided with LAGAN’s spell checker contain no possessive word forms, so this

option should be enabled when using these dictionaries.

2. IGNORE_NON_ALPHA_WORD_OPT (Default true)

Set to true if words that contain no alphabetic characters should be ignored. Set to false

if the words should be checked for spelling errors.

E.g.


If set to true, ignore 12345, if set to false, check 12345.

3. IGNORE_DOMAIN_NAMES_OPT (Default true)

Set to true if words that appear to be Internet domain names should be ignored. Set to

false if these words should be checked for spelling errors. Words are considered to be

Internet domain names if they end in a dot (.) followed by two to four alpha-numerics.

E.g.

If set to true, ignore LAGAN.com; if set to false, check LAGAN.com

4. REPORT_DOUBLED_WORD_OPT (Default true)

Set to true if two occurrences of the same word separated only by spaces or carriage

returns should be reported. Set to false if doubled words should not be reported.

E.g.

If set to true, report the the, if set to false, do not report the the.

5. IGNORE_MIXED_DIGITS_OPT (Default false)

Set to true if words containing a mixture of letters and digits should be ignored. Set to

false if such words should be checked for spelling errors.

E.g.

If set to true, ignore Win95; if set to false, check Win95.

NOTE: If using the IGNORE_MIXED_DIGITS option above, ensure that the REPORT_MIXED_DIGITS option is


6. REPORT_MIXED_DIGITS_OPT (Default false)

Set to true if words containing a combination of letters and digits should be reported. Set

to false if such words should not be reported.

E.g.

If set to true, report June5; if set to false, do not report June5

NOTE: If using the REPORT_MIXED_DIGITS option above, ensure that the IGNORE_MIXED_DIGITS option is


7. ALLOW_ACCENTED_CAPS_OPT (Default true)

If set to true, capital letters containing accents (e.g., Être) are considered acceptable. If

set to false, any words containing accented capitals are considered misspelled. Should be

set to false if checking French Canadian, and set to true in all other cases.

Setting this option to false will degrade performance.


8. MinSuggestDepth=30

The suggestion depth is an integer value ranging from 0 to 100.

The value determines the trade-off between time to locate suggestions and the quality of

the suggestions produced. A value of 100 produces the best (most accurate) suggestions

but takes the most time. The spelling dialog box contains a "Suggest" button. When this

button is pressed, the suggestion depth value is increased by 10, and a new set of

suggestions is obtained. The user can repeatedly press the Suggest button to obtain

suggestions at increasingly higher depths (until the maximum depth, 100, is reached, at

which point the Suggest button is disabled).

9. Suggestions=typographical

This will configure the type of suggestions to be displayed in the Dialog. Can be

englishPhonetic or typographical.

8.1.4. Further Configuration

There is also a configuration entry in the adminapplication.properties file and the

userapplication.properties. This entry is:

# Spell checker configuration

application.spellchecker.checkspellingonformsubmission=false

This configuration entry determines whether or not a form, which has the spell checker

functionality, should be checked for spelling mistakes when it is submitted. The default value is

that it won't be. This can be overridden in two different ways.

The first is to put this entry into adminapplication.properties and/or userapplication.properties in

LAGAN_HOME and change the value to true.

The second is within the actual spell checker dialog itself. There is a check box labelled Check

spelling on form submission. This is settable for each user, whereas the configuration settings in

the properties files are global settings. This setting will be stored in the database as a user

preference and picked up when that user logs into the application.

8.2. Locale Settings

The spell checker has been implemented in such a way as to be specific depending on the locale of

the machine. The spell checker has been implemented to use the following locales:

1. English (United Kingdom)

2. English (United States)

3. English (Canada).


8.2.1. Dictionaries

The set of dictionaries to be loaded and used is dependant upon the locale of the machine and is

not a configurable setting. The set of dictionaries that will be used by the application are:

• accent.tlx: This contains words that have non-alphabetic characters such as apostrophe or

language specific character like acute or grave.

• correct.tlx: This contains common spelling mistakes and grammatical errors.

• tech.tlx: This contains technical terms that will subsequently be ignored, e.g. Bluetooth, CD-

ROM, HTTP

8.2.2. Locale Specific Dictionaries

Locale specific dictionaries will contain the most commonly used words for the relevant language.

Below is a list of the locale specific dictionaries in use:

• dictionary_en_[gb|us|ca].tlx:

• dictionary_en_[gb|us|ca].clx:

The above dictionaries are all stored within the \webapps\LAGAN\config folder and should be

considered Read-Only.

There are also two dictionaries that are editable. The first one is global_dictionary.tlx and is

located in \webapps\LAGAN\config folder. This dictionary should be copied into LAGAN_HOME

before being edited. The second one is userdic.tlx and is located in USER_HOME\LAGAN.

• global_dictionary.tlx

This will contain words added by an administrator of the system that may not be present in any of

the above dictionaries, but should not be flagged as a spelling mistake to any user. This could

include company name for example.

• userdic.tlx

This will contain words that have been added through the spell checker dialog. This dictionary is

specific to each user.

8.3. Adding Words to the Dictionaries

To add words to the global_dictionary.tlx within LAGAN_HOME the following steps should be

carried out:

1. Go to the \webapps\LAGAN\config folder, locate and copy global_dictionary.tlx into the

LAGAN_HOME directory.

2. Within LAGAN_HOME open the file with a text editor of your choice, (e.g. Notepad) and

enter the words you want to be part of the global dictionary.

3. Ensure that each word is followed by no spaces and a carriage return.

4. If you have configured the system to be case sensitive then this should be taken into

account when adding the words.


5. Save and close the global_dictionary.tlx file.

6. Any open applications will need to be restarted to pick up the new words

8.4. Using Spell Checker

The spell checker has been implemented in such a way as to provide an interface that is similar

and works in the same way as other spell checkers that the users of the system may have come

across.

The spell checker dialog provides options for the following:

• Ignore:

Ignore this instance of the selected word.

• Ignore All:

Ignore all instances of the selected word.

• Change:

Replace this instance of the selected word with the corrected spelling typed in the ‘Change to’

field, or the selected ‘suggested’ spelling.

• Change All:

Replace all instances of the selected word with the selected ‘suggested’ spelling.

• Suggest:

Additional suggested words

• Add:

Add the current word to the dictionary. (Dictionary will reside on the user’s local machine).

• Undo:

Undo last spelling change

• Cancel:

Close the dialog

As well as the following fields within the dialog:

• Not in dictionary:

This is the misspelled word that has been detected.

• Change To:

This is the word that the misspelled word will be changed to. This is editable by the user.

• Add words to:

This is the location of the user's local dictionary to which any new word will be added.


A screen shot of the spell checker dialog can be seen below, (Figure 8.1).

Figure 8.1: Spell Checker Dialog

The spell checker can be invoked in two ways:

1. Pressing the F7 key.

This will launch the spell checker dialog if there are spelling mistakes in the form that you

are currently editing.

2. On form submission (If configured).

The spell checker dialog will be displayed if there are spelling mistakes present.

If spelling mistakes are present in the form that you are currently editing and you invoke the spell

checker then the spell checker dialog will be displayed. This will display one spelling mistake at a

time and allow you to correct or ignore it before moving on to the next spelling mistake if one

exists.

8.5. Spell Checker Availability

The following lists outline the forms that the Spell Checker will be available from within each

LAGAN application:

8.5.1. Agent Desktop

• Case Dialog

• Case Forms

• New Email

• New Letter


• Case / Enquiry Note

• Case Event

• Manual Case Task

• Task Note

8.5.2. LAGAN Enterprise Configuration Studio

• Work Queue Notification

• Correspondence

• Client Notifications

• Escalation Rules

• Script Flow Node

• Task Type

• Task Priority

• Task Rule Recipient

• Task Definition

• Task List

• Create a Code Book

• New Code

• New Group

• New Business Rule Action

• Create Event

• Create / Modify Script Flow


9.0 XML Service Document Caching

By default, LAGAN caches XML documents for a period of time to conserve system resources.

9.1. Redefining Cache Lifetime

The services.properties file in the LAGAN_HOME directory has a ‘XML Services’ section where the

cache lifetime can be redefined.

The key takes the form:

xmlservice.documentcache.lifetimeinminutes=1

Replace 1 with the length of time in minutes you wish the cache to exist.

9.2. Disabling the Cache

Setting xmlservice.documentcache.lifetimeinminutes to 0 will disable caching.

NOTE: Choosing to disable caching will mean that changes to the XML documents will take effect

immediately. As the XML documents may be rebuilt more frequently, consideration must be given to the

need for picking up changes immediately versus the extra load.


10.0 Concurrent User Limit

You can set a limit on the number of users who can log in, and define the length of time an ECM

Agent Desktop login session can be idle before the user is deemed to be not logged in.

To turn on the concurrent user limit, insert a new record into the LGNCC_LICENSE table, setting

Feature to ‘CUL’ and Status to 1.

For example:

INSERT INTO LGNCC_LICENSE(feature, status) VALUES(‘CUL’, 1)

To configure the user limit and idle period, insert a new record into the

LGNCC_CONCURRENTUSERCONFIG table. The idle period is specified in minutes.

For Example:

INSERT INTO LGNCC_CONCURRENTUSERCONFIG(userLimit, idlePeriod) VALUES(100, 10)

If concurrent user limit is enabled but the LGNCC_CONCURRENTUSERCONFIG table is empty,

default values of 150 users and 15 minutes are used.

A user is considered active if they are logged in and have done one of the following within the idle

period:

• Created an Interaction

• Created an ODM object

• Updated an ODM object.

No action is taken with an idle login session. It will continue to function normally when the user

resumes work.


11.0 BSF Scripting for Forms and Objects

Cross field validation can be performed between fields on the Current Details screen, Brief Current

Details screen, and on the Individual and Organisation creation wizards. It can also be performed

between fields on the case forms.

Any BSF (Apache Bean Scripting Framework http://jakarta.apache.org/bsf) compliant scripting

language can be used but our examples will be performed using Groovy

(http://groovy.codehaus.org).

11.1. Configuring a Scripting Language

If you wish to configure an additional scripting language (Groovy is preconfigured by default) you

need to modify the services.properties file.

Search for the section entitled ‘BSF Scripting Languages’. You should find something resembling

the following:

#================================================== ==================

# BSF Scripting Languages

#================================================== ==================

scriptinglanguage1.name=groovy

scriptinglanguage1.engine=org.codehaus.groovy.bsf.G roovyEngine

scriptinglanguage1.extension=gy

#scriptinglanguage2.name=jython

#scriptinglanguage2.engine=org.apache.bsf.engines.j ython.JythonEngine

#scriptinglanguage2.extension=jy

Each scripting language you configure should have a set of entries here.

• Specify the name of the scripting language using the scriptinglanguageX.name key.

• Specify the Java class which operates as the BSF scripting engine (consult your scripting

language documentation to determine this) using the scriptinglanguageX.engine key.

• Specify the file extension used by the scripting language using the

scriptinglanguageX.extension key.

As you can see Groovy is configured by default, while the section relating to Jython

(http://www.jython.org) is commented out and simply provided as an additional example.

You must also add the Scripting Language’s JAR file to the services CLASSPATH. To add the JAR file,

copy it to the folder WEB-INF\lib under the LAGAN web application which resides in the web

container. Then restart the web container.


11.2. Writing a Form Validation Script

Some programming knowledge of Java and your chosen scripting language is required to write

validation scripts.

The basic principle is that two Java java.util.Map objects, one named fields and one named errors

are available as variables within the script. The fields variable contains all the fields which can be

compared. The errors variable is returned at the end of the script so that any validation errors can

be returned to the user.

The field values can be requested from the ‘fields’ variable by calling java.util.Map’s get method

passing the form field’s Name value. Here’s an example of this using Groovy:

• start = fields.get("startDate")

This captures the form field named startDate as the variable start. This has the Java type

java.util.Date. You can tell what Java type the variable is by consulting this chart:

Variable Java Type

Edit Field java.lang.String

Date Chooser java.util.Date

Number Spinner java.lang.Integer

Combo Box java.lang.String

Check Box java.lang.Boolean

Text Area java.lang.String

This value can then be compared to other field values.

Example:

start = fields.get("startDate")

end = fields.get("endDate")

if (start.after(end))

{

errors.put("startDate", "End Date is before Start Date")

}

return errors

If the start variable is after the end variable then an entry is put into the errors map. The key of

the entry (startDate) should be the name of the field there is a problem with. The value of the

entry is the message that will be displayed to the user.

All scripts should end by returning the ‘errors’ variable.


11.3. Adding a Validation Script to a Form

This must be configured on the LAGAN database. An example of how to do this is provided in the

lgncc_bsf_exampleCaseScript.sql file found in the database scripts directory.

You must first add a row to the LGNCC_BSFSCRIPT table describing the script as below, where:

• SCRIPTID is a unique ID for the script, e.g. 300

• SCRIPTINGLANGUAGE is the name of the scripting language being used, which must correlate

with the scriptinglanguageX.name key described in ‘Configuring a Scripting Language’ above,

e.g. groovy

• SCRIPTNAME is a meaningful filename for the script with a file extension that correlates with

the scriptinglanguageX.extension key described in ‘Configuring a Scripting Language’ above,

e.g. housingform.gy

• SCRIPT is the actual text of the script.

o The script can be a maximum of 4000 characters, however multiple scripts can be configured

against a form if larger scripts are required.

o If you are using double quotes (“) to delimit strings in your SQL then you must only use single

quotes (‘) in your script.

o You must remove all empty line breaks from inside your script to stop the database

interpreting these as the end of the SQL statement.

o If using Oracle you must enter the command ‘SET SCAN OFF’ before performing the insert to

stop it from interpreting the ‘&’ symbol as a scan. You can turn this on again after the insert

by entering the command ‘SET SCAN ON’.

insert into lgncc_bsfScript

values

(

SCRIPTID,

SCRIPTINGLANGUAGE,

SCRIPTNAME,

SCRIPT,

)

Example:

INSERT INTO lgncc_bsfScript

VALUES

(

300,

'groovy',

'endBeforeStart.gy',

'startDate = fields.get("startDate")

endDate = fields.get("endDate")

if (endDate != null && startDate != null)


{

if (startDate.after(endDate))

{

errors.put("startDate",

"End Date is before Start Date")

}

}

return errors

');

You then need to determine the form ID of the form you wish the script to validate. You can do

this by using the following SQL where NAME is the name of the form, and VERSION is the version

of the form.

select id from lgncc_form where name = 'NAME' and version = VERSION

You must then place an entry in the LGNCC_SCRIPTTARGET table in order to link the form to your

script as below where:

• SCRIPTID is the ID of your script.

• TARGETTYPE is the type of script, i.e. 0 for an object validation script, 1 for a form validation

script.

• TARGETID is the form ID of the form you wish the script to validate

insert into lgncc_scriptTarget

values

(

SCRIPTID,

TARGETTYPE,

TARGETID

);

Example: insert into lgncc_scriptTarget values (300 , 1, 101000149);

11.4. Writing an Object Validation Script

Writing a script to validate against an object (Individual, Organisation, etc.) when editing on the

Current Details Screen, Brief Current Details Screen, or entering values on the object creation

wizards is very similar to writing one for validating a case form with some differences:

• When getting the field values out of the ‘fields’ Map object you pass the key defined for the

portlet field in the column FORMITEMNAME in the database table LGNCC_FIELDEFS.

•


• Because the fields that appear on the screens are configurable by user role you can’t

guarantee that all the fields will be present in the ‘fields’ variable. You must check them to see

if they’re null before making comparisons.

Example:

start = fields.get("startDate")

end = fields.get("endDate")

if (start != null && end != null)

{

if (start.after(end))

{

errors.put("startDate", "End Date is before Start D ate")

}

}

return errors

Data that appears in tables also has to be handled differently due to its more complicated nature.

It takes the form of a java.util.List containing java.util.Map objects. Each Map in the list

represents a ‘row’ of the table. The value of the ‘column’ in this ‘row’ can be retrieved by invoking

the get method passing the key defined for the portlet table field in the column FORMITEMNAME

in the database table LGNCC_FIELDEFS in the same way as normal field values are retrieved from

the ‘fields’ Map.

Here’s an example of how iterate through table rows:

addressRows = fields.get("id9004")

Iterator iter = addressRows.iterator()

while (iter.hasNext())

{

columnMap = iter.next()

startDate = columnMap.get("startdate1426")

endDate = columnMap.get("enddate1427")

// ...

}

11.5. Adding a Validation Script to an Object

Follow the same process described in Adding a Validation Script to a Form above except when

inserting the row into the LGNCC_SCRIPTARGET table insert the ODM Object ID instead of the

Form ID i.e. 1 for an individual, 2 for an organisation, 3 for a property, 4 for a street, etc.


12.0 Configuring Email

The Email Service requires an SMTP-enabled email server. This should be in place before

configuring LAGAN Enterprise Email.

NOTE: Installing the SMTP-enabled email server is not covered in this document.

12.1. Configure Email Queues

For inbound emails the LAGAN Email Service downloads emails from the email server for queuing

and distribution. To do this, the Email Service must log on to the email server (using IMAP or

POP3) with an appropriate username and password, one for each email account which will receive

emails for LAGAN Enterprise.

Email accounts that LAGAN Enterprise should read from are configured in the LAGAN

Configuration Studio. The email address, username and password need to be supplied for each

account.

NOTE: The account may also be marked as Fax if a 3rd

party Fax to Email converter has been used to deliver

Faxes. LAGAN Enterprise will then know to mark the Email as a Fax when it stores it.

Configured accounts should then be mapped to correspondence queues in the Work Queues /

Inbound Correspondence section. It is possible to map several accounts one queue.

Inbound email processing goes through each account in the lgncc_emailaccount table and extracts

the emails. It then puts them into the queue referenced in LGNCC_QUEUEMAPPING. If there is no

such mapping AND there is no 'DEFAULT_MAPPING' entry then you get several errors reported in

the logs and the emails will continue to loop.

12.2. Configure LAGAN Email Service

The email configuration is present within two files, mail.properties and service.properties under

the LAGAN_HOME directory. The mail.properties file MUST be present if using email and should

be filled in with the appropriate server names for inbound and outbound mail (possibly the same).

E.g.

mail.inbound.host=mailserver

mail.outbound.host=mailserver

Additionally there are some values in the services.properties file:

email.inbound.protocol=imap

email.inbound.mailbox=inbox

email.inbound.retrieval.interval=60000

[email protected]

These lines only need to be present in the services.properties file in LAGAN_HOME if the above

defaults need to be overridden (the default from address should be).


12.3. Configuring CC and BCC Email Fields

For outbound email, the new CC and BCC fields can be turned on and off independently. This is

configured via the following properties in the userapplication.properties file:

• correspondence.showcc=true

• correspondence.showbcc=true

Both fields are turned on by default and settings apply to both the Agent Desktop and Agent

Desktop Light.

For inbound email, the details of both the CC and BCC fields are now recorded and are viewable in

both the Agent Desktop and Agent Desktop LIght applications when viewing the details of an

Email, (Figure 12.1 & 12.2)

Figure 12.1: Agent Desktop Light Inbound Email Details

Figure 12.2: Agent Desktop Inbound Email Details


12.4. Email Forwarding

The Email Forwarding functionality allows the optional creation of an Event Note when an Email is

forwarded. If this is configured, a Note with configurable text will automatically be added to the

relevant Interaction that contains the Email.

For example, if the functionality to add a note on forwarding is configured and an Email is

forwarded to [email protected], a Note with text Email was forwarded to

[email protected] will be added to the Interaction.

In order to configure this Note, an Event Mapping must be created via the Configuration Studio

under Enquiries > Event Mapping, (Figure 12.3). This should be configured using the Email

Interaction Forwarded Event with no Classification and with the Create a Note check box

selected.

Figure 12.3: Email Interaction Forwarding

The text of this Note can be configured by changing the following property in locale.properties:

eventnotetext.1230012=Email was Forwarded to %1

NOTE: The %1 in this text will be replaced by the address to which the Email is forwarded.

The forwarded Email itself will have some text pre-populated to the Subject and Body Text which

is configurable in services.properties:

email.forward.subjectprefix=FW:

email.forward.bodyprefix=This message was forwarded by LAGAN\n\n


12.5. Importing Email Contacts

The steps to import a list of email contacts are detailed in the Configuration Studio Help, however

this section will outline some additional information on the importing of email addersses.

NOTE: It is possible that an email address can be used by more than one contact, so long as their contact

names are different.

12.5.1. Disabling the Imported Address List

It is possible to disable the selector buttons that are visible within the Email dialog screen of the

Agent Desktop application. This would restrict the user from selecting from the list of imported

email addresses. This functionality can be enabled and disabled using the correspondence.show

property within the userapplciation.properties file

12.5.2. Database Tables

It is possible to remove all of the imported email addresses by using the Clear button within the

External Email Contacts node of the Configuration Studio. Using this option will clear the following

database tables that store the list of email addresses and the information of the most recent

import:

• LGNCC_EMAILCONTACT

• LGNCC_EMAILIMPORT

12.5.3. Import Errors

If the import fails an error report is displayed. The errors that are detected and reported are:

File level errors:

• no rows in file

• too many errors (parsing of the file will terminate when 100 errors are found)

Row level errors:

• name is empty

• email address is empty

• email address is invalid

• only one column supplied

• too many columns supplied

• duplicate row

Each row level error is reported with a line number. Blank lines are ignored, as are rows where

both the name and email address are empty.


13.0 Business Calendars

LAGAN previously only supported one working calendar within the system, however it has now

been enhanced to support additional working calendars (E.g. to support the working calendars of

different agencies). A new tool now exists that allows multiple business calendars to be created.

13.1. Creating a New Business Calendar

Follow the steps outlined below to create a new Business Calendar:

1. Locate and run the manageCalendar.bat file from the tools/startup folder of the

installation directory. E.g. C:\LAGAN\13R1-Install\tools\startup

2. This will launch the Business Calendar Configuration tool.

Figure 13.1: Business Calendar Configuration Tool

3. The Select Calendar drop down menu will contain a list of all of the previously created

Business Calendars. The Calendar Key field is a non editable description of the selected

Business Calendar.

4. To create a new calendar, click the New Calendar button. The Add New Calendar screen

will be displayed.

Figure 13.2: Add New Calendar Screen

5. Enter a name in the Calendar Name field and enter a calendar key in the Calendar Key

field.

NOTE: If there is no value entered in the Calendar Key field, a warning will be displayed that a default key

will be used. The key that is used will be the same as the Calendar Name field.


6. Selecting the Copy Main Calendar option will copy the default calendar configuration and

settings and use them with the newly created calendar.

7. Once the calendar has been created, the Calendar Settings screen will be displayed.

Figure 13.3: Calendar Settings

8. The Calendar Settings screen will allow working weeks and hours of each working day to

be set. It will also allow days that are not part of the working week to be set. E.g. Holidays

or Weekends.

NOTE: The dark shaded days are configured as holidays or non working days. Weekends (Saturdays &

Sundays) are configured as non working days by default.

9. Simply select the Month and Year from the drop down menus at the top. This will display

the relevant days and dates of the selected month.

10. To configure the working hours of any day within the month, simply click on the relevant

date.

11. Enter a time in the Start Time and End Time fields to set the working hours of that day.

12. Selecting Yes in the Holiday field will set the selected day as a holiday (or non working

day). Selecting No will set the date as part of the working week.

13. Once each day has been configured correctly, select OK to save the calendar settings.

13.2. Updating a Business Calendar

Follow the steps below to update a previously created Business Calendar:


1. Locate and run the manageCalendar.bat file from the tools/startup folder of the

installation directory. E.g. C:\LAGAN\13R1-Install\tools\startup

2. This will launch the Business Calendar Configuration tool.

3. Select the calendar you wish to update by selecting it from the Select Calendar drop

down list and click the Update button.

4. Simply select any dates that you wish to change and make the necessary modifications to

the Start Time, End Time or Holiday settings and click OK to save the changes.

13.3. Using the Business Calendar

Once the business calendars have been created and configured, they will be available to use. The

business calendars can then be used within the Configuration Studio, wherever Case or Task SLAs

can be configured. The user will be able to select an appropriate business calendar to be used in

the Due Date calculation.

NOTE: The business calendar will be greyed out until the working time check box is ticked.

The affected dialogues are:

• Process Definition - Create Case SLA

• Create Task Definition

• Create Rule Escalation

Figure 13.4: Create SLA Screen


14.0 Auto Response Emails

Auto Response Emails can be set up to automatically respond to an incoming email. These emails

can be set up to include relevant information as the customer’s name and interaction reference. A

case ID cannot be included at this stage, as the interaction has not been classified when the email

first comes in.

14.1. Configuring the Auto Response Email

If you wish to configure the auto response emails, you need to modify the services.properties file.

There are 2 settings related to the auto response emails:

emailservice.autoreply.setautoreply=false

This sets the auto response email’s on or off status. Set to true if you want to use auto response

emails.

emailservice.velocity.templatedirectory=../config

This sets the directory where the auto response email templates are found. The default directory

is set to the config directory of your LAGAN installation.

14.2. Writing the Auto Response Email Templates

The Auto Response Email templates are found in the template directory specified in the

services.properties file and are always named AutoResponseEmailSubject.vm (the template used

to specify the auto response email subject) and AutoResponseEmailBody.vm (the template used

to specify the auto response email body). These templates can be edited with any standard text

editor.

These templates can be written in free text, and will be picked up as thus, but for your

convenience, certain details can be dynamically added, these are:

$partyname If the originating email address is found in the ODM database belonging to an

Individual or Organisation, this value will contain the Individual’s or

Organisation’s full name.

$intref This is the interaction reference for the incoming email.

$creationdate This is the creation date for the incoming email interaction, which will equate

to the time the email is received.

With the party name value described above, we need to protect against the possibility that the

incoming email is not from a known Individual or Organisation, and therefore we need to catch

this in an ‘if’ statement. This can be done using the velocity template language, and can be seen in

the following example:

#if ( !$partyname )

#set( $partyname = "Sir/Madam" )


#end

Dear $partyname,

Thank you for your email, we will process your request as soon as possible.

Your reference number for this interaction is $intref.

Please quote this reference when contacting us with regards this query.

Thank you for your message.

#if ( $creationdate )

Creation Date: $creationdate

#end

In the above example, the party name is found in an ‘if’ statement with an exclamation mark

before it. This checks if the party name value actually exists, and adding the exclamation mark

signifies the condition where the client name does not exists (this would be true if no

corresponding name was found in the ODM database). In this condition, $partyname is assigned

the value Sir/Madam.

NOTE: An ‘if’ or ‘if-else’ statement must end in the #end notation. With the $partyname value now

guaranteed to be set, it can then be inserted into the start of the email template.

More on the velocity notation can be found on the Jakarta Apache website.

NOTE: The email service needs to be restarted to pick up any changes to the auto response email templates.


15.0 Integrator Intranet (II) Components

15.1. II Component Memory Requirements

The Agent Desktop can be configured to have an unlimited number of Integrator Intranet

(embedded web page) components, so it needs to be noted that the number of active II

components a user has will affect the memory required by the Agent Desktop, given an agent

computer only has a finite amount of memory to work with.

The exact memory required by a given II tab depends on the content and complexity of the pages

it is displaying. For example a single blank II page (i.e. using the URL about:blank, to show no

content) requires approximately 6Mb when using an embedded Internet Explorer in the Agent

Desktop, so this is the minimum that each II page will require.

Other approximate size examples for a page would be:

• 10Mb - an instance of Agent Desktop Light.

• 20Mb - A news website.

• 75Mb - KANA Knowledge process.

NOTE: An Agent Desktop with 10 active II components may require anything from 60Mb upwards on top of

the normal LAGAN memory footprint.

15.2. Configuring II Navigation Toolbar

A navigational toolbar can be configured either globally or on an individual basis for Integrator

Intranet components.

Figure 15.1: Integrator Intranet Components Screen with Navigation Toolbar


To enable the display of a navigation toolbar for all Integrator Intranet components that are

accessed from within the Agent Desktop, configure the following entry in the

userapplication.properties file:

integrator.intranet.allownavigationtoolbar=true (default false)

15.2.1. Configuring an Individual II Component

The navigation toolbar can be enabled for individual Integrator Intranet components. For example,

to enable the navigation toolbar for an Integrator Intranet component with the ID 1001, add the

following entry to the userapplication.properties file:

integrator.intranet.component1001.allownavigationtoolbar=true

The navigation toolbar can be configured to include an address bar.

Figure 15.2: Navigation toolbar and Address bar

15.2.2. Configuring the Address Bar

If the navigation toolbar is enabled for all Integrator Intranet components then the address bar

can also be enabled for all Integrator Intranet components by configuring the following entry

userapplication.properties file:

integrator.intranet.allowaddressbar=true (default false)

The address bar can be enabled for individual Integrator Intranet components. For example, to

enable the address bar for an Integrator Intranet component with the ID 1001, add the following

entry to the userapplication.properties file:

integrator.intranet.component1001.allowaddressbar =true

NOTE: Enabling the address bar for an Integrator Intranet component will have no effect if the navigation

toolbar is not also enabled for that Integrator Intranet component.


15.3. Configuring a Mix of Browser Beans

Although one of the defined browser beans can be specified as being the default, more than one

browser bean can be defined as being used with the ECM application. The default bean will be

Internet Explorer (IE), however XULRunner could also be used.

A new configuration property can be added to the appropriate ECM property file to specify which

rendering engine to use for any individual II component. The Agent Desktop application can run

multiple II components rendered by different beans simultaneously, without suffering a significant

performance impact.

The following II components are configurable within the userapplication.properties file:

integrator.intranet.component1001.browserbean=com.LAGAN.LAGANcentre.core.application.c

ommon.guicomponents.browser.NativeSwingMozillaBrowser

or using a key as defined in userapplication.properties

application.browserbean.key.IE=com.LAGAN.LAGANcentre.core.application.common.guicompo

nents.browser.WinIEBrowserintegrator.intranet.component1001.browserbean=IE


16.0 Localisation

16.1. Overview of Localisation

The text in the applications can be altered by putting entries in a locale.properties file in the

LAGAN_HOME directory. This file ONLY needs to contain the overrides to the default values.

16.1.1. Example: Changing the text on the title bar of the Case Search screen.

If the line, enquirysearchview.text.title=Case Search exists in the default locale file but the line

enquirysearchview.text.title=Case Search is present in the locale.properties file then the default

value will be overridden.

16.1.2. Example: Localising the Menu Text

NOTE: Some special notations are used to mark mnemonics and accelerators.

command.logout=&Logout@ctrl L

The parameter @ctrl L defines the accelerator (Ctrl L) for the action, and the & before the letter L

defines the mnemonic as the letter L; i.e. the L is underlined and Alt L will invoke the action.

These can be changed as well as the text.

E.g.

command.logout=End &Session@ctrl N

This would now have the new text (End Session) with S underlined. Hence Alt+S and Ctrl+N would

now perform the logout action.

16.2. Language Localisation

Multiple language versions of the application can be configured. The language variants are saved

according to the standard Java naming conventions as in the following examples:

• English: locale_en.properties

• Hungarian: locale_hu.properties

• Chinese: locale_zh_CN.properties


17.0 Letter Fulfillment Configuration

Letter Fulfilment can be performed using either Microsoft Word or Star Office Writer. By default,

MS Word is the selected application for this purpose, however if this needs changed to Star Office,

the following line must be included in the localapplications.properties file:

letterfulfilment.package=com.LAGAN.LAGANcentre.core.bean.correspondencemodel.StarOffice

WriterHandler

17.1. Auto-Resolving Dynamic Content

LAGAN Enterprise can be configured to attempt to automatically resolve dynamic content as soon

as it is dragged on to the content area. This is disabled by default, but can be enabled by editing

the userapplication.properties file changing the key

application.correspondenceview.autoresolvetemplates to True


18.0 Configuration Object Key Updater

This command line tool allows an administrator to change the keys for certain configuration

objects to ensure that the keys are the same across various systems; systems such as

development, test and production.

18.1. Background

Keys will be used in schemas exported by LAGAN as integration points to external systems; hence

if these keys are the same across all systems then integrations will not need to be changed as a

result of a migration. Each type of configuration object will have a unique key. Keys will be

meaningful strings which can only contain alpha-numeric characters and the underscore character.

In previous versions, an internal numeric id was exposed instead of a key which could, and often

did, change between systems. This forced integrations that used these ids to change, if they were

migrated to another system.

18.2. Running the Utility

The configuration object key updater utility is called ConfigurationObjectKeyUpdater and can be

found in the startup directory under the tools folder which resides in the LAGAN installation

directory.

To receive help on the utility run the following from the startup directory (this example is for

windows):

./ConfigurationObjectKeyUpdater.bat help

Basically the utility takes a file as a parameter. Each line in the file should contain three comma

separated values. These are as follows:

• The type of configuration object key to change

• The old key for this configuration object

• The new key for this configuration object.

Different configuration object keys can be supplied in the file and the utility will change them all

i.e. you can change enquiry subject, reason and type keys as well as case category keys using one

input file and one execution of the utility.

As an example the file could contain the following line:

subject,complaint,information

type,information,details

The utility will read the above lines and change the enquiry subject’s key from complaint to

information and the enquiry type’s key from information to details.


19.0 Q-Matic Integration

This section covers what steps are required to set up an installation of the Q-MATIC web (QMS)

application as an Integrator Intranet (II) component within the Agent Desktop. This is now the

preferred approach rather than the older server side integration.

19.1. Configuration Studio

Create a new II component for the QMS application. The ID for the II component has to be greater

than 1000 and unique. The name can be set to anything and the URL should be set to:

http://<server:port>/fox?command=login&UserName=<userid>&Password=<userpassword>&p

art=/

Where <server:port> is entered, this should be replaced with the actual server and port of where

the QMS application is running.

This component should be added to the LAGAN Group being used for the Face To Face work type.

The LAGAN user id and password must match exactly the Q-MATIC user id and password as these

login details are passed through directly from the Agent Desktop to the QMS application. If they

do not match then the user will have to enter their separate Q-MATIC login details on the login

screen in the QMS application II component.

19.2. Property File Configuration

19.2.1. locale.properties

To add a label and a shortcut key for the Q-MATIC II screen to the Go navigation menu add:

command.navigateto.integratorcomponent<component_ID>=Face to Face@ctrl Q

command.tooltip.navigateto.integratorcomponent<component_ID>=Q-Matic Suite

Where the <component_ID> has been entered, the ID used to create the II component in the

configuration studio should be used. For each branch location that will be used add a line for its

display name e.g. if there is a branch with id 10 whose name is Head Office add the line:

interactionviewers.facetofacedetails.location.10=Head Office

For each Q-MATIC queue that will be used add a line for its display name e.g. if there is a queue

with id 7 whose name is Enquiries add the line:

interactionviewers.facetofacedetails.queue.7=Enquiries

19.3. Other configuration

It is also possible to change the icon displayed for the menu option. To use the standard face to

face icon which is supplied in the Images.zip file in the classes folder of your LAGAN installation

you need to rename the icon file from FaceToFace16.png to

integratorcomponent<component_ID>.png within the zip file. Alternatively another suitable icon

can be used.


20.0 Event Mapping Notes

If you specify in event mapping that the mapping will create a note, the text of the note has to be

defined in the locale.properties file:

This file is found under the config folder under the LAGAN hierarchy on the application server

hosting the LAGAN Services.

In the property file each event will have an entry of the format:

eventnotetext.[number]=[text]

Where:

[number] is a seven digit event code, with first digit being:

1. For core

2. For script

3. For integrator java,

[text] is the text to be added to the history.

For example, the set below are all notes for Integrator Java raised events.

eventnotetext.3000001=Client Created (%1)

eventnotetext.3000002=Non Gaz Client Created

eventnotetext.3000003=Client Updated

eventnotetext.3000004=Non Gaz Client Updated

eventnotetext.3000005=Client Verified

eventnotetext.3000006=Status Changed, Now: %1

eventnotetext.3000021=Job Created: %1

eventnotetext.3000022=Job Updated: %1

The property file will be provided with default text for all the core and integrator java events

available. To configure the text, you must edit the property file, locate the appropriate event and

change the text, save the file and then restart the LAGAN Enterprise client to pickup the change.

NOTE: For further information on the use of the optional parameters (for example, %1 above), please

contact LAGAN support.

LAGAN Enterprise 13R1Administration Guide

For script events, when you create the event using the dialog above under the scriptflow design

tool, (by right clicking on a script node, s

the Event ID is shown but you must add 2000000, to get the full code, e.g. if the Event ID is 1 in the

dialog the value is 2000001, and the line you must insert in the

this property file.


Figure 20.1: Getting Script Event Codes


tool, (by right clicking on a script node, selecting properties, and then pressing the select button)


dialog the value is 2000001, and the line you must insert in the eventnotetext.2000001=My text

71


electing properties, and then pressing the select button)


eventnotetext.2000001=My text is


21.0 Encrypting Database Passwords

A migration utility has now been added that will allow the encryption of existing passwords, stored

within the LGNCC_DBCATALOG table. This chapter will outline how to run the migration utility and

the configuration required to set encrypted passwords.

21.1. Configuring the Property File

Before running the utility, a flag needs to be set in the services.properties file. The following flag

should be set to true:

dbcatalog.encryptpassword=true

21.2. Running the Migration Utility

NOTE: This migration utility should only be run if the property configuration has been completed and you

intend to use encrypted passwords.

1. Open a command prompt and browse to the [INSTALL DIRECTORY]\tools\startup

directory.

2. From this directory, run the following command:

DBCatalogEncryptionMigrator.bat -update

NOTE: For a Linux installation run DBCatalogEncryptionMigrator.ksh -update instead.

3. Once completed, this will set all the current unencrypted DB catalogue passwords to

encrypted passwords in the LGNCC_DBCATALOG table.

4. To confirm that the passwords have been encrypted, open the LGNCC_DBCATALOG table.

Encrypted passwords would look something like this; JGgjJGe4GYE=.

*WARNING*

This tool should not be run twice in -update mode. If this tool is run twice with the -update switch, all

passwords will be double encrypted and therefore become unusable and unrecoverable.


22.0 Additional Configuration

This chapter will outline other areas of the system that can be configured further.

22.1. Adding Predefined Tasks

A user can add predefined tasks to an existing case. You can set a system-wide configuration value

which controls whether or not any rules associated with added predefined tasks are activated.

The configuration value is casemanagementservice.addtask.attachrules in services.properties. To

activate rules for added predefined tasks, set it to true, otherwise set to false (this is the default).

Also in services.properties, the configuration value casemanagementservice.taskdatebasis

determines how the due date for an added task is calculated. 0 means the task due date/time is

calculated relative to the case creation date/time, and 1 means relative to now, i.e. the date/time

when the task is added.

22.2. Closing a Case with Incomplete Tasks

The LAGAN system can be configured in a number of different ways to handle incomplete tasks

when closing a case. Changes to this functionality should be done by configuring the

casemanagementservice.checktasksonclosecase property within the service.properties file.

The property is now a domain value and has three possible settings: TIGHT, LOOSE, NONE. The

default value is NONE.

• LOOSE:

If set to LOOSE a check for incomplete tasks is required before closing a case and

will give to the user the choice of closing a case.

• TIGHT:

If set to TIGHT a check for incomplete tasks is required before closing a case and

will prevent the user from closing a case if incomplete tasks are found.

• NONE

If set to NONE there will be no check for incomplete tasks and the case will be closed.


23.0 Single Report Security Model

This module is provided to allow the generation of reporting information that can be used at the

user level. It is not a replacement for the corporate level BI solution. As such, this module is

provided in a manner that allows it to be integrated into the Agent Desktop or Agent Desktop

Light, accessible for appropriate users.

The reporting platform is the Open Source BIRT platform. This has been integrated into the LAGAN

suite incorporating the LAGAN security model to control access to data. Reporting is performed by

generating a report that will produce pages and tables of data. The data contained (and implicitly

the columns available) is selected through the use of a Lucene based query.

Lucene provides a text based search language, which is easy to use and understand and includes

advanced features such as "fuzzy matching" of data. New web services are provided that accept a

Lucene query and return a XML list of case data. The BIRT reports are integrated through II

components.

23.1. Model Overview

23.1.1. Designing Reports

Reports will be designed using Lucene Syntax as a query string. The Lucene syntax is flexible and

usable for this purpose. With BIRT, reports can be designed by combining multiple data sets and

providing a SOAP template. An example of a SOAP template is shown below:

NOTE: The SOAP templates that can be used are outlined in section 24.3.2 below.

<SOAP-ENV:Body>

<m:FWTSearchCaseDetailsRequest

xmlns:m="http://www.LAGAN.com/wsdl/FLTypes">

<m:query xsi:type="xsd:string">&?query?&</m:que ry>

</m:FWTSearchCaseDetailsRequest>

</SOAP-ENV:Body>

The complete SOAP request template is generated by the BIRT report IDE, however the SOAP-

ENV:Body alone is sufficient and the remaining part of the soap request will be generated by the

custom driver using wsutil. Ensure to remove any other soap request parameters from the

template and retain the soap body part.

23.1.2. BIRT Implementation

When considering BIRT as the report view provider, it cannot be used out of the box to integrate

with the flweb service as the web service requires authentication. This can be done using the

custom java driver extension provided by BIRT from 2.2.1 onwards.

On the client side (considering BIRT viewer webapp is running on a client machine), the following

needs to be provided:

1. BIRT Viewer runtime (webapplication)

2. Custom Java Driver


3. JAR file needed for the custom driver to work (this includes wsutil and tools jar apart from

thirdparty libraries).

23.1.3. Searching for Data

Data will be searched via Lucene. As well as exact matching Lucene allows for "fuzzy matching" of

data which can offer benefits to customers. In the Case model, incremental updating of the Lucene

indices is used. The Lucene Document will be formed from the existing Case Type that is defined

within the FLWeb definitions.

For each data set, a search string shall be defined. This could be a set of keywords and search

strings connected using logical operators.

For example: caseHandler=John AND Category=Environment

23.1.4. Paging

BIRT does not have a framework to support loading pages of data from a web service in a lazy

loader fashion. It pulls the entire data either as a string or as an input stream and renders them.

The custom java driver can take care of loading individual pages from the webservice and combine

them before providing the same to the BIRT engine therefore avoiding stressing the webservice

with a huge data retrieval call. Only when the custom java driver completes fetching all the

records from the webservice, the report can be rendered.

23.2. Installation & Configuration

Before running a report, you will need to ensure that the Eclipse Report Designer has been

installed and configured. There are two ways of installing Eclipse:

23.3. Complete Installation

The latest release of the eclipse report designer IDE (All in one) can be downloaded from

http://www.eclipse.org/downloads/packages/node/609

23.4. Eclipse Plugin

The installation can also be achieved using the eclipse plug-in architecture.

1. In Eclipse go to the Help menu and select the Install new software option.

2. Click the Add button and enter in dialog

Name: birt

Location: http://download.eclipse.org/birt/update-site/3.7

3. Click OK once completed.

4. On the Install new software dialog select all packages and click Finish.


23.4.1. Dependent / Latest Build Files

There are three files generated while building the BIRT app:

1. casbirt.war: Application file for deployment in Tomcat.

2. casbirt.ear: Application file to be used for weblogic installation (bundles casbirt.war +

application.xml file).

3. LAGAN-birt-dependencies.jar: Dependency jar to be used in Eclipse report designer as

class path for the Java custom driver of a data source.

23.5. Designing an Example BIRT Report

Follow the steps below to create an example BIRT report:

NOTE: This is only one example of a BIRT report and there are many ways of doing this.

1. Launch Eclipse to create a new report project.

2. Open the Report Perspective and select File | New Project to

create a new project and select the Report Project type.

3. Once you have selected a project you can then add reports.

4. Select File | New Reports to create a new report. Enter a name for the report and lcik

Next.

5. Select the blank report from the templates and click Finish.

23.5.1. Defining a Data Source

Follow the steps below to define a new data source:

1. Open the Data Explorer tab. If it is not visible, select Window | Show View | Data

Explorer.

2. Right click Data Sources and select New Data Source.

3. Select Web Services Data Source, from the list available. Enter a name for the

data source and click Next.

4. In the Web Services Data Profile dialog, configure the webservice source as follows:

• WSDL: http://<hostaddress>:<port>/LAGAN/schema/FLService.wsdl

• SOAP End point: http:// <hostaddress>:<port>/LAGAN/services/FL

• Custom driver class: com.LAGAN.webservice.birtdriver.SOAPAdapter

• Driver classpath: <Path to the LAGAN-birt-dependencies.jar>

5. Click Test Connection to check if the report designer is able to communicate with

the webservice using the Driver class. If successful, you will see a Ping Succeeded

dialog.

6. Click Finish.


23.5.2. Defining Data Sets

Follow the steps below to define a new data set:

1. Open the Data Explorer tab. Right click Data Sets and select New Data Set.

2. Select a data source to be used and give the Data Set a name. Click Next.

3. Select a Web Service method (operation) which will be used to populate this dataset. You

must select one of searchCaseDetails, searchTaskDetails or searchInteractionDetails and

click Next.

4. The wizard will show the parameters that the WS operation requires. Verify that they are

the same and click Next.

5. The next page displays a template for the request. Please use an appropriate template

provided below for operations SearchCaseDetails, SearchTaskDetails and

SearchInteractionDetails and click Next.

6. In the next step select Use External Sample Data File and select a sample file. The sample

data file xml needs to be provided to the report designer.

7. Expand the XML node and select the appropriate row (e.g. CaseCoreDetails for case data)

and click the > button.

8. Click OK on the XSL dialog and click Next.

9. Select columns from the XML Structure and add to the Column Mapping. When adding,

please select the appropriate column type (e.g. Date Time for date fields).

10. Click on Show Sample Data to verify the XML response schema and then click Finish.

11. In the Edit Data Set dialog, select Parameters.

12. For each parameter, select Edit and click the Linked to report parameter button {}.

13. For each parameter, select an appropriate Name and Data Type. Click OK for each

parameter.

14. Link each of the SOAP request parameters to its corresponding report parameter. If the

report parameter does not exist, create them. The report parameter values will be filled

in into the SOAP request by the BIRT driver.

NOTE: The parameters username / password are used only while designing reports. When deployed in

tomcat, the username / password will be obtained through the browser or client.

Request template for SearchCaseDetails

<parameters>

<username>&?username?&</username>

<password>&?password?&</password>

</parameters>

<flt:FWTSearchCaseDetailsRequest

xmlns:flt="http://www.LAGAN.com/wsdl/FLTypes">

<flt:FWTLAGANCaseSearchParams>

<query>&?q?&</query>


<startIndex>&?startIndex?&</startIndex>

<numberOfRecords>&?numberOfRecords?&</numberOfRec ords>

<sortField>&?sortField?&</sortField>

</flt:FWTLAGANCaseSearchParams>

</flt:FWTSearchCaseDetailsRequest>

Request template for SearchTaskDetails

<parameters>



</parameters>

<flt:FWTSearchTaskDetailsRequest








</flt:FWTSearchTaskDetailsRequest>

Request template for SearchInteractionDetails

<parameters>



</parameters>

<flt:FWTSearchInteractionDetailsRequest








</flt:FWTSearchInteractionDetailsRequest>


23.5.3. Indexing

Before any data can be searched on indexes the search data must be created. This is done via a

scheduler - simply add the following property to services.properties in LAGAN_HOME.

caseDataIndexRebuild.interval=3600000

NOTE: A manual index can be started by logging into http://[server]:[port]/LAGAN/uwa/search/index.html.

23.5.4. Scripting

While running a report, the user will be queried for the report parameters by a dialog window. If

the user should not be queried for the parameter values either one of the following can be done

from the Report Parameters node of the Data Explorer.

1. Select each report parameter and mark them as hidden and specify a default value for it.

OR

2. Select each report parameter and mark them as hidden and uncheck the isRequired

check box. And set the values using script for the bforeOpen method of the dataset.

23.6. Pagination

The webservice provides pagination support by providing startIndex and numberOfRecords

parameters. This can be used in BIRT to provide pagination.

For Example, if the report needs to show details of all cases in a report, but should fetch only 50

cases per page, it could be down as shown below:

1. Add a column to the Data Set that is used to manage to count of records. This is a

computed column from the dataset

Figure 23.1: Edit Data Set

2. Add a new label (from the Palette) Next into a column in the table footer. The hyperlink

property of the label can be used to load the next page of the report.


NOTE: The startIndex of the hyperlink report adds the startIndex and NumberofRecords of the previous

page.

3. To hide the Next

a particular expression matches.

4. Similarly the Prev


Figure 23.2: Hyperlink Property


Next label on the last page, the visibility property of the label can be set when

a particular expression matches.

Figure 23.3: Hide Element

Prev label can be hidden if the startIndex of the report is 0.

80


label on the last page, the visibility property of the label can be set when

label can be hidden if the startIndex of the report is 0.


23.7. Search Keys

The following keys can be used to build a report query string either as

• Search Keys: E.g. case.caseid=[0* TO 9*], case.allocatedusername="Admin"

• Sort Fields: The sort field parameter in the report shall be specified with any one of the keys

below.

Case Fields Task Fields Interaction Fields

case.caseid task.taskid interaction.interactionid

case.departmentid task.taskname interaction.interactionreference

case.departmentname task.duration interaction.clientname

case.allocateduserid task.typeid interaction.clientcategory

case.allocatedusername task.typename interaction.date

case.allocation task.typedescription interaction.channelid

case.callbackdate task.targetcompletiondate interaction.channelname

case.callbackfax task.actualcompletiondate interaction.channelreference

case.callbackphone task.completionentereddate interaction.channeldata

case.casereference task.status interaction.enddate

case.category task.userid interaction.caseid

case.caseinternalid task.username

case.casedefinitionid task.hasnotes

case.casestatus task.ismanual

case.closeddate task.isdynamic

case.contactname task.caseid


case.currenthandler

case.lasteventdate

case.modifiedby

case.lastmodifieddate

case.location

case.modifieddate

case.duedatefornexttask

case.description

case.opendate

case.otherdescription

case.priority

case.scheduledpriority

case.scheduledstatus

case.slatime

case.severity

case.slasuspendeddate

case.sourceid

case.sourceuserid

case.sourceusername

case.shortdescription

case.sourcearea


case.status

case.targetfixdate

case.targetfixdays

case.targetfixhours

case.title

case.titleandreference

case.type

case.allocationstatus

case.workflowid

case.workflowname

case.workflowstep

case.subject

case.reason

case.classificationtype

23.8. Searching Date/Time values

The Lucene date format is YYYYMMDD, so to search for 25th August 2011, the value 20110825

needs to be used.

23.8.1. Date Ranges

To search a range, the minimum and maximum values need to be specified in the following format

as per Lucene specification.

Example, to search for all cases which were has call-back date in 2010, we can use

case.callbackdate={20100101 TO 20110101}

Boolean operators can be used in search strings to specify different criteria for the same search

term.


E.g: task.taskid=101000001 OR 101000002

task.taskid=(101000001 OR 101000002) is also valid

NOTE: The operator used is "OR". The pipe symbol "|" should not be used here.

The LAGAN webservice provides an option to combine multiple queries using boolean symbols &,

| and ! These can be used when searching for more than one term.

E.g.

task.taskid=(101000001 OR 101000002)&task.caseid=101000000000!task.taskid=101000002

For the above search syntax, the webservice constructs a lucene boolean query combining three

queries to match documents which have:

"task.taskid=(101000001 OR 101000002)"

and "task.caseid=101000000000"

but not "task.taskid=101000002"

Apart from the Lucene syntax, Multiple queries can be combined using &, | and ! operators. The

LAGAN web service will create a BooleanQuery by combining multiple queries given using the

above operators.

E.g. case.status=1&case.opendate={20100101 TO 20110101}

23.9. Deploying Reports in Tomcat

1. Checkout the project casbirt and build wsutil, CoreUtil, LAGANUtil.

2. Before running the ant build script on casbirt ensure the BIRT driver project has been

built as this will be included into casbirt.war.

3. Create the birt.properties file under the LAGANhome directory. Add the following setting

to this file: service.url=http://localhost:8080.

4. Copy the casbirt.war to TOMCAT_HOME/webapps directory and restart tomcat.

5. When Tomcat has restarted copy the report files .rptdesign to the

TOMCAT_HOME/webapps/casbirt/report directory.

6. View the report using the following browser URL:

<machine><port><webapp_name>/frameset?report=report/<report_design_filename.r

ptdesign>

NOTE: The birt-dependancies jar location as configured in the report design and should be accessible from

the machine where the birt runtime is being deployed. Also ensure that the runtime birt.war that is in

casbirt project is the same version as the eclipse designer version, if not this can cause issues when viewing

reports.


23.10. Viewing a Report

Follow the steps outlined below to view one of the available BIRT reports. In the example the BIRT

report will detail a list of LAGAN Cases.

1. Open a browser window and enter the URL of the relevant report.

E.g. http://[machine name]:[port]/casbirt/frameset?__report=LAGANCases.rptdesign

NOTE: Changing the Report Design file name will display different reports.

2. When prompted enter the Username and Password and click OK.

3. Once logged in the Report Parameter screen will be displayed.

Figure 23.4: Report Parameters

4. The UserName and Password fields will contain your logon credentials.

5. The Search Query field will contain the default value, case.caseid=[0* TO 9*] which will

return all cases.

6. Enter a number in the Start Index field and the Number of Records field. These will

determine how results are returned.

7. Leave the Sort Field as default and click OK.

8. Once the report has compiled, the results will be displayed.


Figure 23.5: Report Results


24.0 Case Data Handling

24.1. Data Archive and Purge

The system will allow Archiving and Purging of data as separate operations although the

operations can be combined to execute an archive & purge in one step.

NOTE: For a user to perform an Archive and Purge, the user needs to have all View and Delete permissions

apart from having "Archive and Purge" permissions. For example, Delete Note, Search Cases, Delete Task

etc. If sufficient permissions are not set, the user will see an Access Denied or Rollback error message.

Archive involves extracting all related case data for a user-specified set of cases and exporting the

data into an XML file on the file system. The user-specified set of cases is defined using a Lucene

search query (which is a simple text based language).

A Purge will permanently remove all data from the LAGAN database to ensure that it remains at a

manageable size. A user can purge the data using a simple web form into which the search criteria

can be entered, and the operation selected.

The Archive and Purge options are accessed through a web based form that is only accessible

directly by connecting using the URL.

NOTE: The web form cannot be navigated to through the standard LAGAN interface, so it is only available to

Administration staff.

24.1.1. Connecting to the Interface

Accessing the Archive and Purge options is done by connecting directly to the interface using the

following URL: http:[server name]/LAGAN/uwa/archive/archive.html

Once connected you will be presented with a log on screen where you are required to enter your

user credentials. Once successfully logged in, you will be presented with the Archive and Purge

screen.

Figure 24.1: Archive and Purge screen


Once connected to the arching and purge interface, you can perform three options:

1. Archive

2. Purge

3. Archive and Purge

24.1.2. Archive

If choosing to archive data from the LAGAN system, there are two actions you can choose, either

Perform or Search. Running a search will simply return a list of results for the search string that

was entered. Perform will run the action that has been selected.

For each archival, an archive.xml file is created and stored under the default directory with a

name representing a timestamp (yyyy_MM_dd_hh_mm_ss). The default storage directory is

LAGAN_HOME/archive but this can be changed by configuring the following property setting in

the services.properties file:

casemanagement.archive.dir=file:///${LAGAN_HOME}/archive

Follow the steps outlined below to run a search for data to archive.

1. In the Search String field enter a search string to find. E.g. case.caseid=101*

NOTE: A full table of search strings that can be used is available from the previous chapter.

2. Select the Archive radio button and then select the Search radio button and click the

Submit button.

3. Using the example criteria above the search will return a list of all closed cases with a

case ID containing 101.

Figure 24.2: Searching for Case ID’s

4. If you wish to Archive the results returned from the search, simply select the Archive

radio button and the Perform radio button and click the Submit button.


5. Once the archive is complete it will return a list of all the data has been archived and a

new XML file will be created in the default directory.

NOTE: If any cases that have been archived contained attachments, these will also be archived and listed in

the XML file.

Figure 24.3: Archive Complete

24.1.3. Purge

NOTE: Ensure that the Group ACL has 'GRANT' access for 'Delete'. This is to enable the purge process for

cases with interactions, interaction notes and attachments. Failure to do this will result in a failed Purge.

The steps used to search and perform a Purge are similar to that of archiving, however rather than

storing the data that has been returned, it will be completely removed from the system. Simply

select the Purge radio button and choose whether to Search or Perform a purge. Once a purge is

performed a list of the successfully purged data will be displayed.

NOTE: Unlike the archive option, using the Purge option will NOT create a historical XML file. The selected

data is simply removed.

24.1.4. Archive and Purge

The steps used to search and perform an Archive and Purge are similar to that of the other two

options. Simply select the Archive And Purge radio button and choose whether to Search or

Perform an archive and purge. Selecting this option will simply archive the data and then purge

the original from the system. As with the other two options it will return a list of results that have


been successfully archived and purged. Once complete an XML file will be created in the default

archive directory.

24.2. Archive and Purge Scheduler

The Archive and Purge Scheduler will enable you to create scheduled archive and purge jobs via a

scheduled configuration file. It will allow you to add, update or remove an archive and purge and

will allow multiple scheduled jobs with a cron expression and a Lucene search string for each

schedule.

The search string provided in the schedule configuration should be parsed by the archive API to

construct a valid Lucene search String (To enable the user to provide a relative value for specifying

a date value).

24.2.1. Configuration File

There are four parameters to Archive and Purge Scheduler configuration file:

1. Schedule Name

2. Search String

3. Cron Expression

4. Operation (can be one of archive, purge or archiveAndPurge)

Example:

deleteoldcases=purge,case.closeddate=00000000 TO <-180D>,"0 30 1 1 2/6 ? *"

The above configuration would schedule a purge task for cases which has a closed date older than

180 days (at the time of the job execution) for every 6 months.

The subsequent execution dates would be (assuming today is 19-December-2012)

Wed Feb 01 01:30:00 GMT 2013

Wed Aug 01 01:30:00 BST 2013

Fri Feb 01 01:30:00 GMT 2014

The string representing a relative date should be enclosed within angular brackets. Lucene

currently uses circular, square and curly brackets as part of its standard search syntax, hence these

special characters cannot be used for our purpose. Some valid values for representing a relative

dates are:

<0> OR <0d> for today

<5d> current date plus 5 days

<-5d> current date minus 5 days

<1m> current date plus 1 month

<-18m> current date minus 18 months


<-1y> current date minus 1 year and so on

A query can have multiple relative date values.

An example for a complex query is outlined below:

case.duedate=[<0> TO <5d>]&case.allocatedusername=A dmin&case.opendate=[<-

1Y> TO <0>]

Assuming today is 19-Dec-2012, the above search syntax will transform to the following Lucene

search string:

case.duedate=[20121219 TO

20121224]&case.allocatedusername=Admin&case.opendat e= [20121219 TO

20121219]

NOTE: The cron syntax would be the standard quartz implementation detailed at (http://www.quartz-

scheduler.org/documentation/quartz-1.x/tutorials/crontrigger)

24.2.2. Loading the Scheduled Configuration

The system needs to periodically check for changes in the schedule configuration file to load new

schedule configuration. The code should be able to locate all scheduled jobs currently active in the

system and replace them with the new set of scheduled jobs (in case there are changes to the

configuration).

One option of identifying currently active archive/purge scheduled jobs is to have a predefined

prefix for each scheduled job.

E.g. ARCHIVE_<job name specified in config file>

This would enable you to remove all active ARCHIVE_scheduled jobs with the new set of scheduled

jobs.

24.2.3. Configuring Archive-Purge Schedules

As specified above, the system could be configured with several Archive or Purge schedules. The following are the configuration steps an administrator needs to perform to add/update/remove schedules. There are two Configuration properties to set behaviour of the archive/purge scheduling operation:

1. archiveSchedule.properties

The archiveSchedule.properties file will contain the schedules that need to be currently

active in the system. Each line in this configuration file represents an archive/purge

scheduled job.

Example 1:

deleteoldcases=purge,case.closeddate=[00000000 TO <-1M>],0 30 1 1 * ? *

Purges closed cases on first of every month at 1:30am which have closed date older than

1 month)


Example 2:

archiveoldcases=archive,case.closeddate=[00000000 TO <-1M>],0 30 1 1 * ? *

Archives closed cases on first of every month at 1:30am which have closed date older

than 1 month.

Example 3:

archiveAndPurgeoldcases=archiveandpurge,case.closeddate=[00000000 TO <-1M>],0 30

1 1 * ?

Archives and Purges closed cases on first of every month at 1:30am which have closed

date older than 1 month.

2. archivescheduler.interval

The archivescheduler.interval is contained in the services.properties file and contains the

value in milliseconds and specifies the interval at which the scheduler configuration is

refreshed (the archiveSchedule.properties file is read and all the archive/purge schedules

in the system are updated according to the new configuration).

The default value is 86400000 milliseconds (24 hours).

24.2.4. Parsing the Search String to Construct a Lucene Query

The search string can either be a standard Lucene query (Used by the archive/purge UI and SRSM)

OR the query can have some specific syntax to indicate that it needs to be parsed to create a valid

Lucene query.

Example 1:

case.closeddate=<-60D> TO <0D>

This will be parsed by the archive API to construct case.closeddate=20111019 TO 20111219

(assuming today is 19-Dec-2011).

Example 2:

case.closeddate=00000000 TO <-180D>

This will be parsed to construct case.closeddate=00000000 TO 20110722 (from beginning of time

to 180 days back from today).

24.2.5. Error Handling

If there are any errors while performing an archive/purge scheduled task, an error message will be

written to the services.log file.


24.3. Case Indexing Tool

LAGAN Case Indexing uses Lucene internally and typically for a system with a huge number of

cases, the indexing is a time consuming process. During a full rebuild of the index, the index

location is locked by the indexing thread and hence other threads/processes accessing the index

store could not add data into the index. This includes case creation / update operations.

To resolve this issue, the existing indexing code, which easily runs out of memory while indexing a

relatively large number of cases, instead will index cases in batches instead of the previous process

which tries to index all at once.

The Case Indexing Tool, provide a method of performing a full index rebuild so that an

administrator can run an index rebuild at any desired time (including during a LAGAN upgrade

process).

24.3.1. Configuration

To use the tool and avoid an automatic index rebuild in LAGAN, set

casemanagementservice.index.autoCorrect=false (set to false as default) in the services.properties

file and use the tool to perform indexing if needed.

The logging configuration file is log4j_caseindexer.properties and by default the log file will be

log4j_caseindexer.log.

The following configuration parameters need to be specified before running the tool in

customtools.properties file.

Property Description

case.index.location Location for the Lucene index e.g. file:///D:/lucene_case

E.g. case.index.location=file:///D:/lucene_case (Windows)

case.index.location=file:////home/LAGAN/LAGAN/8-0-5/

install/LAGANhome (Unix)

case.index.pagesize Number of cases indexed per batch (to avoid memory issues)

E.g. case.index.pagesize=1000

24.3.2. Running the Case Indexing Tool

To run the tool use the following command on Windows:

cd D:\LAGAN\13R1-install\tools\startup

CaseIndexer.bat 2000

To run the tool use the following command on Unix:

cd /LAGAN/13R1-install/tools/startup

sh CaseIndexer.ksh 2000


25.0 Auditing

Audit is one of the LAGAN Supporting Data Services. Its success and usefulness is based on a highly

configurable and high performance architecture which can be tailored to each individual need.

Figure 25.1: Audit Overview

The audit module is capable of monitoring specific operations or groups of operations as required,

writing audit data to a separate database (or file) if desired for performance and security reasons.

The recorded audit data can include the following:

• User login / logoff

• Username and User ID

• Date and time of the audit event

• Summary of the information viewed / searched / updated / deleted

• IP Address and access channel (Agent Desktop, Agent Desktop LIght, Web Service etc)

The table below shows a comprehensive list of the operations and the objects for which audit data

can be captured.


Operations

Domain Object Create Read Update Delete Search Print

Case ��

(E)ODM �� N/A

Form �� N/A N/A

eForm �� N/A N/A ��

Codebook �� N/A N/A

Interaction �� N/A N/A N/A N/A

Message �� N/A

Notes �� N/A ��

Relationships �� N/A �� N/A N/A

Tasks ��

25.1. Auditable Object Types

25.1.1. LAGAN Cases

LAGAN Enterprise automatically audits a range of case related events, including:

• When a user creates a case

• When a user starts processing the case

• When a user closes a case

• Changes to priority or severity

• Changes to the current queue

• Changes to any of the information held in the case form in all of these situations, the audit

record includes the date and time the event took place, along with any other details specific

to the event E.g. The details of the user who changed the case priority.


This audit information is visible in various places within the various LAGAN Enterprise clients,

including the Further Details panel in the Current Case Agent Desktop screen. Here, the audit

information is shown in the first four rows of the table with the most recent event first. This

clearly shows the movement of the case from creation (by Madison), to Roger and then back to

Madison.

25.1.2. EODM Objects

LAGAN Enterprise automatically audits a range of events related to EODM objects (e.g.

individuals), including:

• What EODM searches (e.g. individual) a user performs

• What EODM records a user looks at

Access to this audit information is via the use of a reporting tool.

25.1.3. Enquiries

LAGAN Enterprise automatically audits case / enquiry searches using Enquiry Search screen.

25.1.4. User Logins / Logoffs

LAGAN Enterprise automatically audits every user that logs onto (and off) LAGAN Enterprise across

all LAGAN Enterprise clients that require a secure login (Agent Desktop, Agent Desktop Light) and

also any of its interface (e.g. Web Services). Access to this audit information would be via the use

of a reporting tool.

25.2. Basic Configuration

25.2.1. Properties

To enable Audit you need to set this in LAGAN_HOME/system.properties: audit=true

25.2.2. Database Tables

Migration script m1096 creates the Auditing database tables - runtime and configuration. It also

populates the configuration tables.

At runtime, the audit data is written to LGNAD_AUDITDATAHEADER and LGNAD_AUDITDATA

The configuration tables are LGNAD_DOMAINOPERATIONS and LGNAD_AUDITMETHOD.

Each row in LGNAD_DOMAINOPERATIONS identifies:

• A domain area, e.g. 'case', 'eform', 'odm'

• Five flags, one each for create, read, update, delete and search (CRUDS). Each flag can take

values 0, 1 or 9 meaning, respectively: disabled, enabled or not applicable.


So, a row containing 'case', 1, 0, 1, 1, 1 indicates that we are auditing case creates, updates,

deletes and searches, but not reads.

Each row in LGNAD_AUDITMETHOD identifies:

• A service interface method e.g. 'CaseManagementService createCase'

• The domain area to which it belongs e.g. 'case'

• Its operation type e.g. 'create'

• A flag (1 or 0) to indicate whether or not the method is being audited. The flag's setting is

dictated by the content of LGNAD_DOMAINOPERATIONS.

We know that for domain area 'case' and operation type 'create', audit is enabled; therefore the

flag setting for createCase in LGNAD_AUDITMETHOD is 1.

The two tables provide a separation between what an Admin user will see when configuring Audit

(LGNAD_DOMAINOPERATIONS) and what is used at runtime to determine if a particular service

interface method is to be audited (LGNAD_AUDITMETHOD). Details of interface and method

names are not exposed to the user.

There is no Admin client for configuring audit so until this is available, you must apply changes

directly to LGNAD_DOMAINOPERATIONS using a database client. You can then call stored

procedure LGNAD_AUD_UpdateConfig to apply the LGNAD_DOMAINOPERATIONS values to

LGNAD_AUDITMETHOD.

NOTE: LGNAD_AUD_UpdateConfig is a stop-gap solution to be removed at a later date, it is not installed by

default. If you want to use it, copy it from the CD and compile it in your database.

At any stage, the content of the configuration tables can be reset by calling

LGNAD_AUD_InsertBaseData.sql.

25.3. Advanced Configuration

25.3.1. Using a Different Database Schema

By default, audit data will be written to the same schema as the rest of the LAGAN tables. To use a

different database schema, follow these steps:

• In LAGAN_HOME/system.properties, set audit.separate.database=true

• In LAGAN_HOME/audit.properties, set the JDBC connection details for your other database

schema.

• Create the necessary tables and procedures in your other database schema.

No script is provided for creating the tables and procedures - you have to do it manually.

Unfortunately, because the audit runtime tables use a sequence for generating primary key

values, you need a number of supporting infrastructure items. Here is the complete list of what

you must install:

• Audit runtime tables: LGNAD_AUDITDATAHEADER and LGNAD_AUDITDATA.

• Audit Sequence: LGNAD_AUItemIDSEQ (see LGNCC_SEQUENCES).


• LAGAN schema table: LGNCC_SCHEMA. Populate as appropriate (compare with the table in

your core schema).

• Utility stored procedures: LGNCC_ISU_getKeyVal and LGNCC_ISU_getLocalPrefix.

25.3.2. Writing Data to a File

Audit data can also be written to a file using log4j - this should only be enabled for testing

purposes and never on a live system. To enable it, set auditservice.writedatatolog=true in

LAGAN_HOME/services.properties.

Suggested log4j config:

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

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

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

<param name="MaxFileSize" value="2MB"/>

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

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

<param name="ConversionPattern" value=" %m%n"/>

</layout>

</appender>

<logger

name="com.LAGAN.LAGANcentre.core.service.audit.Audi tServiceImpl">

<level value="debug"/>

<appender-ref ref="audit"/>

</logger>

25.4. Implementation Overview

25.4.1. Spring Configuration

Auditing is achieved by applying an aspect to selected LAGAN service interfaces. In this context, a

service interface is, for example, CaseManagementService or ODMService. The auditing aspect is

defined in declarativeServices.xml. It is applied to the service pointcut, before any security

interceptor.

NOTE: For the aspect to be applied successfully, the service interface class must follow this convention: its

name must end in the word "Service".

By default, the Spring configuration is wired to use a dummy audit interceptor unless audit is

enabled in system.properties, in which case the actual interceptor class AuditInterceptor is picked

up from audit.xml.

If audit.separate.database=true in system.properties, the alternative database details are picked

up from audit-database.xml.

25.4.2. Java Layer

At runtime, AuditInterceptor calls AuditConfigService.retrieveAuditMethod to determine if a given

method is to be audited, and calls AuditService.write to write out the audit data.


For any given service interface method, a Java annotation class called AuditMethod lets us choose

the arguments to be written as audit data, plus whether or not to use the return value.

For example:

@AuditMethod(argumentSelector = {true, false, false}, useReturnValue = false)

public void closeCase(CaseID aCaseID, String aReasonTitle, String aReasonDetails);

This says that when writing audit data for a call to closeCase, use only the first argument, and do

not use the return value.

NOTE: The primary location for method configuration is the database. The annotation on a given method

will only be inspected at runtime if the database configuration indicates that the method is being audited.

25.4.3. Auditable Java Objects

When a service interface method is being audited, AuditInterceptor attempts to convert the

method arguments and return value (if required) into audit strings in a format suitable for writing

to the database. This is aided by objects implementing the Auditable interface, which has two

methods:

• String toAudit(): similar to toString(), except the value it returns is a String representation of

the object in a format suitable for auditing.

• String getAuditObjectID(): returns a string representation of the object's identifier.

The format for audit data is |attributename1|attributevalue1|attributename2|attributevalue2|...

, i.e. attribute name/value pairs separated by '|'.

The rules for writing a toAudit method are:

1. Use Audit.buildString.

2. Define attribute names in lowercase, no spaces, underscores, hyphens. Use complete

words e.g. associatedobject. Do not use abbreviations, unless they are unambiguous and

well understood.

3. Protect attribute values against null, and ensure that the Audit delimiter character is

stripped out of any String which might include it.

4. Attribute names should be defined in one class, and reused if that attribute is contained

in another class. E.g caseid is used in the Enquiry class but defined in the CaseID class.

Obviously, some method arguments/return values are elementary Java types such as int and long,

which means that we have no toAudit or getAuditObjectID methods available. In such instances

we just log |id|value|.

25.4.4. Audit Data

LGNAD_AUDITDATAHEADER contains:

• UserID - who called the method

• AuditDate - when


• IPAddress - where the method called was made from

• Channel – Agent Desktop, Agent Desktop LIght, web service, etc

• ObjectID - the primary object ID involved in the method call. By convention we use the ID of

the first method argument

• DomainArea - e.g. 'case', as used in the configuration tables

• OperationType - CRUDS, as used in the configuration tables

LGNAD_AUDITDATA contains:

• Inputs - the method arguments as a concatenated audit string

• Outputs - the return value, or exception if one was thrown


Appendix A: Event Publisher

WARNING: The Event Publisher, as outlined below, has now been deprecated and replaced with the new

Integration offer. Details on the new Integration offer can be found in the LAGAN Integration Guide

available with the relevant release.

The Event Publisher is a means by which notifications can be made to external systems about

certain events that have occurred within LAGAN e.g. case creation. These notifications are called

published events. It employs an ESB (Enterprise Service Bus) messaging framework called Mini

Mule which is a light-weight Mule distribution to deliver events to disparate transport and

messaging technologies. Published events are handled by a separate thread which changes each

event into an event payload and sends it to the Mule server (an executing instance of Mini Mule).

This payload is then delivered to a configured transport or messaging protocol.

Examples of what transport mechanism Mini Mule can send events to are JMS, file, tcp and http.

By default the event publisher will not run when LAGAN is started. In order to enable the event

publisher to run the following property needs to set up in the system.properties file in the

LAGAN_HOME directory:

eventpublisher=true

LAGAN then needs to be restarted.

NOTE: If Mini Mule is to be configured to send a message to a JMS queue, as in case extender, the JMS

provider (e.g. Open JMS) must be running before LAGAN is started and the eventpublisher.jms property set

to true in the system.properties file.

If Mini Mule is to be configured to send ODM messages then the eventpublisher.cdi property should be set

to true in the system.properties file.

Configure Properties

This section will describe how to configure properties of the event publisher which dictate how it

is initialised and how it operates. These can be overwritten in the services.properties file in the

LAGAN_HOME directory.

• publishedeventsender.interval=60000 – this defaults to 60000 (1 minute in milliseconds) and

dictates how often the event publisher sender thread runs. This thread sends event payloads

to Mini Mule which in turn delivers them to the configured transport protocol.

• publishedeventreview.frequency=900000 – this defaults to 90000 (15 minutes in

milliseconds) and dictates how often the event publisher review runs. This thread tries to

resend any event payloads to Mini Mule that failed on a previous attempt.

• publishedeventcleanup.cronexpression=0 0 6 ? * * – Now, by default, the job is scheduled to

run once a day, at 6AM. This is completely configurable and uses the 'cron' format to express

its scheduling.

• eventpublisher.mule.serverurl=tcp://localhost:60504 – the default server url for this

instance of mini mule.

• eventpublisher.retrycount=3 – this defaults to 3 and configures the number of retry attempts

the event publisher should make with a published event that can’t be sent.


• eventpublisher.connection.retrycount=3 and eventpublisher.connection.frequency=5000 –

this defaults to 3 retries and 5000 milliseconds respectively. This tells Mini Mule how to

behave if a connector fails e.g. JMS connector. This configuration will try to connect 3 times

every 5 seconds if any connector’s connection is lost.

• eventpublisher.caseevent.updatequeueonly=true – a case event can be published on update

if any case detail, the case form or case eForm is updated. Setting this to true means that if

any other case detail, besides the queue, is changed then the event is not published.

• caseextendertransformer…..= details the various namespace tags that will be used to create

the classic case extender soap message with attachments.

• payloadfiler.path=/d:/temp/mule?transformers=CaseExtenderTransformer,

BPMTransformer and payloadfiler.filename=Eventpublisher – controls the path and name of

file output if using the file transport mechanism.

XML Configuration

The event publisher configuration consists of various XML files that have been written using Spring

configuration which starts and configures Mini Mule. They describe what criteria an event should

have before being published, where published events should be sent, what transport protocol

should they use and should the events be transformed into some other object before being sent.

Most of these XML files reside inside the core war file and do not change but the custom files are

in the LAGAN_HOME directory on the application server.

These files are called eventpublisher-core-custom.xml, eventpublisher-jms-custom.xml and

eventpublisher-cdi-custom. These files are clearly marked with comments. Explanation and

examples on how to configure this are taken from Mule documentation (produced by

SymphonySoft Limited http://www.symphonysoft.com). Be aware that the style of configuration

used is Spring and not the standard mule configuration.

Configuring if an Event gets Published

The criterion by which an event is published in Mule is configured using filters. The filters should

be configured in the caseFilter element for case events in eventpublisher-core-custom.xml and in

the odmFilter for ODM events in eventpublisher-cdi_custom.xml. Wildcard filters, specifically, are

used to filter on the contents of an event payload.

For example to only publish case events that are associated with a case queue called Complaint

the following filter should be placed in the router element in the caseFilter element:

<bean id="caseFilter" class="org.mule.routing.filte rs.WildcardFilter">

<property name="pattern" value="*[Queue=Complaint]* "/>

</bean>

There are many details of the event that can be filtered on. They are listed below in the following

tables with what the wild card pattern attribute should be:


Case Events

Event Detail Example Filter pattern

ID of case that event is based on. *[ObjectID=101000012]*

Event Type *[EventType=Case]* - must be Case.

Operation that caused the event *[Operation=Create]* - must be Create, Update, Close or

Reopen.

ID of user who caused the event *[User=jsmith]*

Queue that case is allocated to *[Queue=Complaint]*

User that case is allocated to *[AllocatedToUser=jsmith]*

Case classification subject *[Subject=Complaint]*

Case classification reason *[Reason=Roads]*

Case classification type *[Type=Potholes]*

Case classification title *[Title=Bad Roads]*

Case classification description *[Description=Classification for roads]*

Process definition *[Definition=Roadworks]*

Work flow *[WorkFlow=Road Process]*

Event Mapping *[EventMapping=2000101]*

Priority *[Priority=3]*

Severity *[Severity=3]*

ID of user that created the case *[SourceID=jsmith]*

Object associated with the case *[AssociatedObject=FullType: C1 XR1: 101000000340 XR2: null

XR3: null Desc: Mr James Brown Cat: 10]*


ODM Events

Event Detail Example Filter Pattern

ID of object that event is based on. *[ObjectID=C1#!101000001962#!null#!null]*

Event Type *[EventType=ODM]* - must be ODM.

Operation that caused the event *[Operation=Create_Object]* - must be

Create_Object, Update_Object, Delete_Object,

Reactivate_Object, CDI_Create_Object,

CDI_Update_Object, CDI_Delete_Object,

CDI_Delete_Object_On_Merge or

CDI_Delete_Object_On_Rollback.

ID of user who caused the event *[User=jsmith]*

Object type *[ObjectType=C1]*

Object first cross reference *[XReference1=101000001962]*

Object second cross reference *[XReference2=null]*

Object third cross reference *[XReference3=null]*

It is also possible to filter on more that one detail associated with an event using logic filters. There

are three types of logic filter:

1. AndFilter

2. OrFilter

3. NotFilter

AndFilter

An AndFilter combines two filters and only accepts if both filters match. For example to publish an

event only if the case is created on the Complaint queue:

<bean id="caseFilter" class="org.mule.routing.filte rs.logic.AndFilter">

<property name="leftFilter">

<bean class="org.mule.routing.filters.WildcardFilte r">

<property name="pattern" value="*[Operation=Create ]*"/>

</bean>

</property>

<property name="rightFilter">

<bean class="org.mule.routing.filters.WildcardFilt er">

<property name="pattern" value="*[Queue=Complaint] *"/>

</bean>


</property>

</bean>

OrFilter

An OrFilter combines two filters and accepts if either of the filters matches. For example to publish

an event if the case is operated upon on the Complaint queue or the Info queue:

<bean id="caseFilter" class="org.mule.routing.filte rs.logic.OrFilter">




</bean>

</property>



<property name="pattern" value="*[Queue=Info]*"/>

</bean>

</property>

</bean>

NotFilter

A NotFilter will accept if the filter assigned to it does not accept. For example to publish an event if

the case is operated upon any queue except the Complaint queue:

<bean id="caseFilter" class="org.mule.routing.filte rs.logic.NotFilter">

<property name="filter">



</bean>

</property>

</bean>

Logic Filters

Logic filters can be nested so that more complex logic can be expressed. It publishes the case

event if the case is operated upon on the Information queue or the case is created on the BPM

queue or the case is created on the Complaint queue. See the example below.

<bean id="caseFilter" class="org.mule.routing.filte rs.logic.OrFilter">


<bean class="org.mule.routing.filters.WildcardF ilter">


Configuring where an Event gets Published

Configuring where an event gets published is described in a different element in the

eventpublisher-core-custom.xml file and for ODM objects in the eventpublisher-cdi-custom.xml. If all events get sent to the same transport mechanism e.g. JMS then only the transport needs to

be configured. (This is discussed below).

Filters can be configured in the various …RouterFilter elements depending on where the event is

to be published. It is also possible to send some events to one transport mechanism and other

events to another. All the same details can be filtered on for this purpose (described above in the

previous section). Just replace the default wild card filter with whatever complex filter is required.

For examples see the bpmRouterFilter and knowledgeRouterFilter.

If an event needs to be sent to more than one transport mechanism then the matchall attribute in

the caseEventSenderRouter or odmEventSenderRouter element should be set to true.

Publish Changes to a Database Table

As part of CDI it is possible to publish changes in customer data to a database table. In order for

this to happen the following property needs to set up in the system.properties file in the

LAGAN_HOME directory:

eventpublisher.cdi=true

LAGAN then needs to be restarted. The odmEventSenderRouter should be configured as described

below.

A database table of the following structure should be created to receive published events:

• User ID - VARCHAR(100)

• Event type - NUMBER/NUMERIC(4)

• User Name - VARCHAR(50)

• Timestamp - DATE/DATETIME

• Details - VARCHAR(1000)

In the services.properties file in the LAGAN_HOME directory the following configuration should

then be completed:

• odmdbadapter.targettable.tablename

• odmdbadapter.targettable.useridcolumnname

• odmdbadapter.targettable.eventtypecolumnname

• odmdbadapter.targettable.usernamecolumnname

• odmdbadapter.targettable.timestampcolumnname

• odmdbadapter.targettable.detailscolumnname


Configuring the Transport Protocol for an Event

Configuring what transport protocol is used to publish the event is described in the routers list in

the caseEventSenderRouter and odmEventSenderRouter elements for case events and ODM

events respectively. We will describe how to configure a JMS and a virtual machine endpoint

below.

A JMS endpoint needs to have a JMS connector configured. In order to load the JMS mule

configuration set the eventpublisher.jms property to true in system.properties in the

LAGAN_HOME folder

Defining where jms is running is configured in eventpublisher-jms-custom.xml. This is performed

in the following section:

<bean id="jmsQueueConnector" class="org.mule.provid ers.jms.JmsConnector">

<property name="connectionFactoryJndiName"

value="TCPQueueConnectionFactory"/>

<property name="jndiInitialFactory"

value="org.exolab.jms.jndi.InitialContextFactory"/>

<property name="jndiProviderUrl" value="tcp://local host:3035"/>

</bean>

By default an Open JMS connector is configured, running on the same machine with its default

port. If using any other JMS provider then a different connector will have to be configured (see

Mule JMS Configuration).

All we need to do for Open JMS and case events is make the openjmsRouter the first router in the

list in the element caseEventSenderRouter in the file eventpublisher-core-custom.xml; also to

change the jms queue is simple. For example to send events to a queue called case_queue on

Open JMS the element change the constructor argument endpoint to be:

jms://case_queue?connector=jmsQueueConnector&transformers=CaseExtenderTransformer

,ObjectToJMSMessage in the file eventpublisher-jms-custom.xml.

Notice that the jmsQueueConnector is the name of the Open JMS connector configured earlier in

the file.

A virtual machine endpoint sends the message to another POJO (Plain Old Java Object) running in

the same java virtual machine as the Mule server. This object can then deal with publishing the

event in whatever manner it wants.

The POJO with this endpoint address must be configured in the eventpublisher-core.xml or

eventpublisher-core-custom.xml file. For example to send events to the testing logger POJO, which

just outputs the event received, the constructor argument endpoint will be:

• vm://localhost/Logger

Notice that this endpoint address is configured in the payloadLogger element further in the

eventpublisher-core.xml configuration file found in the LAGAN.war that was deployed. To look at

how you could add a custom virtual machine POJO look at the above file in conjunction with the

eventpublisher-core-custom.xml file and follow the pattern of either the BPM adaptor component

or the Knowledge handler component.


Configuring an Event Transformer

Before an event payload is published it can be transformed into another object e.g. case extender

classic SOAP message with attachments string. These transformers are configured in the

transformers attribute of the endpoint constructor argument. More than one transformer can be

used by listing them comma separated.

In order to produce the classic case extender SOAP message with attachments the

CaseExtenderTransformer is provided. Various transport protocols have their own transformer

e.g. for JMS there is the ObjectToJMSMessage transformer.

Hence to send the classic case extender SOAP message to a JMS queue in Open JMS called

case_queue the full endpoint constructor argument is:

jms://case_queue?connector=jmsQueueConnector&transformers=CaseExtenderTransform

er,ObjectToJMSMessage

NOTE: The & construct is used to separate parameters to the endpoint. We cannot use ‘&’ as it is a

reserved character in xml and will not be treated as the character ‘&’.

There is another transformer call FLWebTransformer which can be used which will transform the

case payload to the form of the case details returned from flweb with all the soap binding details

removed. All the flwebtransformer properties need to be configured in the services.properties file

in order to use this transformer.

There is another transformer called BPMTransformer which takes as its input the output of the

CaseExtenderTransformer. Its output is a valid XML message which BPM uses. Xpath expression

can be run against it successfully unlike the case extender message.

Event Publisher Database Table

The Event Publisher uses the lgncc_publishedevent database table. Below is a list of what the key

columns in the table mean:

ID: This is a unique primary key for the object to be published.

OBJECTID: This is the id of the object that is being published E.g. case id, odm object identifier

in the form FullType#!Xref1#!Xref2#!Xref3

EVENTTYPE: This is the type of object that is being published. The possible values are:

• Case

• ODM object

OPERATION: This is the operation that caused the event to be published.

For Case events these are:

• A Case was created

• A Case was updated

• A Case was closed


• A Case was reopened

For ODM events these are:

• An ODM object was created

• An ODM object was updated

• An ODM object was deleted

• An ODM object was reactivated

• An ODM object was created through CDI

• An ODM object was updated through CDI

• An ODM object was deleted through CDI

• An ODM object was deleted as a result of a merge through CDI

• An ODM object was deleted as a result of a merge rollback through CDI

STATUS: This is the status of the published event. The possible values are:

0 - The event is ready to be sent to mule for publication

1 - The event has been successfully published by mule

2 - The event was not published by mule but the number of attempts have not been

exceeded (defaults to 3)

-1 - The event could not be published and the maximum number of attempts was

exceeded

ATTEMPTS: This is the number of attempts to publish the event.

administration guide 13r1 - verint...

Documents