Retain Web Administration Guide

Retain International
33 Beaufort Court
Admirals Way
London
E14 9XL
United Kingdom

1 646 688 4496 (USA)

0845 458 8660 (UK)
+44 20 7538 4774 (World)

[email protected]
www.retaininternational.com

© 2009 Retain International Limited

 Contents

Table of Contents

1 Introduction
.....................................................................................................................................4
2 About.....................................................................................................................................5
this Guide
3 Deployment
.....................................................................................................................................6
3.1 Installation
.......................................................................................................................................................................6
Overview
3.2 Global
.......................................................................................................................................................................7
Deployment Archive
File Categories
...................................................................................................................................................................7
Folder...................................................................................................................................................................7
Structure
3.3 Single
.......................................................................................................................................................................8
Instance Setup
Database Setup
...................................................................................................................................................................8
Using the Deployment Tool
...................................................................................................................................................................10
Installing Application Server
...................................................................................................................................................................14
Installing the Services and External Processes
...................................................................................................................................................................15
Startup
...................................................................................................................................................................16
Security Configuration
...................................................................................................................................................................16
Global Archive Configuration Files
...................................................................................................................................................................16
Troubleshooting
...................................................................................................................................................................17
3.4 Multiple
.......................................................................................................................................................................17
Instances Setup
Editing Deployment Settings
...................................................................................................................................................................18
Installing Application Servers
...................................................................................................................................................................21
Load...................................................................................................................................................................23
Balancer Module
Installation and Configuration
................................................................................................................................................23
Outage Notification ................................................................................................................................................25
Web Authentication methods
................................................................................................................................................26
File Distribution
...................................................................................................................................................................26
Startup procedure
...................................................................................................................................................................27
Troubleshooting
...................................................................................................................................................................27
4 Administration
.....................................................................................................................................28
4.1 View
.......................................................................................................................................................................28
Templates
4.2 Calculated
.......................................................................................................................................................................29
Fields Reference
Introduction
...................................................................................................................................................................29
Customisation
...................................................................................................................................................................29
Rules...................................................................................................................................................................29
for Designing Calculated Fields
Adding Calculated Fields
...................................................................................................................................................................32
Constants
...................................................................................................................................................................32
CalcFields.cff ................................................................................................................................................32
DefineCompany.cff ................................................................................................................................................32
CompanyConsts.cff ................................................................................................................................................33
4.3 Built-in
.......................................................................................................................................................................33
Calculated Fields
Calculated Fields Files
...................................................................................................................................................................34
Calculated Fields for Diaries
...................................................................................................................................................................34
Conflicts
...................................................................................................................................................................34
Define Company
...................................................................................................................................................................34
Database Independence
...................................................................................................................................................................34
Fast ...................................................................................................................................................................34
Time
Company Constants
...................................................................................................................................................................35
Phonetics
...................................................................................................................................................................35
Pre-calculated Fields
...................................................................................................................................................................35
Request Economics
...................................................................................................................................................................35
Scenarios
...................................................................................................................................................................35
Security
...................................................................................................................................................................35
Triggers
...................................................................................................................................................................35
Team...................................................................................................................................................................35
Variance
...................................................................................................................................................................36
Wallchart
...................................................................................................................................................................36
2 2
 Contents

4.4 Retain
.......................................................................................................................................................................36
Data Builder
Command Line Usage
...................................................................................................................................................................36
Setting the Configuration File
...................................................................................................................................................................38
Logging Configuration File
...................................................................................................................................................................40
5 Appendices
.....................................................................................................................................41
5.1 Configuration
.......................................................................................................................................................................41
Files
ClntCnfg.ini
...................................................................................................................................................................41
Retain.ini
...................................................................................................................................................................42
RetainCalcFieldsGlobal.ini
...................................................................................................................................................................43
RetainGlobal.ini
...................................................................................................................................................................43
RetainHelpGlobal.ini
...................................................................................................................................................................50
RetainServersService.Ini
...................................................................................................................................................................50
RetainStaticFileMappingGlobal.ini
...................................................................................................................................................................50
Rwplog.ini
...................................................................................................................................................................51
SvrCnfg.ini
...................................................................................................................................................................52
Servers.ini
...................................................................................................................................................................55
5.2 Hardware
.......................................................................................................................................................................56
Specification
Introduction
...................................................................................................................................................................56
Retain Web Architecture
...................................................................................................................................................................57
Database Requirements
...................................................................................................................................................................58
Deployment with up to 100 concurrent users
...................................................................................................................................................................59
Description ................................................................................................................................................59
Hardware and Software Specification
................................................................................................................................................59
Deployment with up to 500 concurrent users
...................................................................................................................................................................60
Description ................................................................................................................................................60
Hardware and Software Specification
................................................................................................................................................61
Deployment with up to 1000 concurrent users
...................................................................................................................................................................62
Description ................................................................................................................................................62
Hardware and Software Specifcation
................................................................................................................................................63
5.3 Installation
.......................................................................................................................................................................63
Checklists
Hardware and File Locations Configuration
...................................................................................................................................................................63
Deployment Checklist
...................................................................................................................................................................64
Deployment Update Checklist
...................................................................................................................................................................66
6 Support Services
.....................................................................................................................................67
Index
..........................................................................................................................................68

3
 Introduction

1 Introduction

Retain Web Administration Guide

Retain Web Viewer

www.retaininternational.com

© 2009 Retain International Limited

4 4
 About this Guide

2 About this Guide

This user guide provides instructions and reference information for the deployment of Retain Web.

The Installation Overview provides an overview of the process involved in deploying the software, while the
detailed information for each of the steps is presented in the succeeding sections.

The Global Deployment Archive presents a description of the contents of the Global Software Archive where
software and configuration files are retrieved for all of the deployment activities.

The Single Instance Setup describes the procedure of setting up an initial standalone Retain Web application
server.

The Multiple Instances Setup is to replicate the single application server instance across all of the server
machines that have been allocated for the deployment.

Lastly, the appendices provide the hardware specification, a list of configuration files and installation
checklists.

Note: Depending on your setup, some of the settings defined in this guide may not be applicable to the Retain
Web edition you are using.

5
 Deployment

3 Deployment
3.1 Installation Overview

In order to deploy Retain Web into your organisation, the following steps need to be taken:

1. Decide on the Deployment Structure

Retain Web offers a range of configurations in terms of the number of server machines, application server
instances and web servers. The first step is to decide where the Global Deployment Archive will be stored,
which database will host the repository and which server machines will be used for hosting the application
servers, load balancer modules and the running of reports.

2. Publish the Global Deployment Archive

Unzip the software bundle provided by Retain International Ltd into the location where you have decided to
publish the Global Deployment Archive. Create a share against the folder so it can be accessible to the
domain user who will be running Retain Web.

3. Repository Initialisation
Create a new repository in one of the supported databases and run the database scripts provided in the
Global Deployment Archive to create the initial tables and data structures.

4. Single Server Configuration and Troubleshooting

Deploy and configure a single instance of Retain Web, Retain Wallchart, Retain Server and Retain
Security Manager. Make sure you can connect to Retain Web and that all the pages reflect the settings
you want to provide the users with, such as the fields that will be visible.

5. Global Archive Configuration

Copy the configuration files you have modified from the single server configuration into the Global
Configuration Archive, so they can be used by all Retain web application server instances, once the
distributed deployment begins.
Configure the global configuration file which will enable the Retain Web Deployment tool to configure each
distributed instance.

6. Application Servers Installation

Using the Global Deployment Tool, install Retain Web instances on the servers you have decided to use
in step 1. The Install Tool will copy all the files needed by these Retain Web instances and write the local
configuration file for each of them. A manual step might be needed in order to run the Retain Web
instances as a service and possibly under a particular domain user.

7. Load Balancer Installation

Using the Global Deployment Tool install the load balancer module on the server machine(s) you have
decided to use in step 1. The Install Tool will copy all the files needed by the module and configure its ini
file. Manual steps will still be needed to configure the Internet Information Services in order to run the
module.

8. Application Server Startup

Start up all your application server instances.

9. Load Balancer Startup

Start up all your load balancer modules.

10. Check the Deployment

Check the URL of the deployment health check page to see if the load balancer module can communicate
with the server instances. Having done that, try logging on to Retain Web.

6 6
 Deployment

3.2 Global Deployment Archive

The Global Deployment Archive is the central repository of a Retain Web installation. All the files needed
during the deployment process are stored here.

File Categories

The files stored in the global repository can be divided into the following categories:

· Application Server module

Application server is the software responsible for the connection between the client and the selected
database. It handles most of the business logic and data access of the application.

· Load Balancer module

Load balancer spreads the work between two or more computers in order to get the optimal resource
utilisation. It provides a single service from multiple servers.

· Global Calculated Fields Files

Calculated fields files are used internally by the software for calculations based on fields from the database
and provide additional derived information.

· Global Configuration Files

These files contain various configuration settings used throughout the installment, deployment and startup
of Retain Web.

· Database Scripts
Database scripts files may be customised according to the user's needs. By running these scripts you can
initialise a new Retain repository and get it ready to deploy Retain Web.

· Retain version 5 Server and Client Files

Retain Server operates between the client and the database, acting as an interpreter and adding extra
functionality to the database system. It serves as the connection to database, maintaining as well as
servicing a separate connection for each client as well as building the security model.

Folder Structure

The following list shows the main folders within the Global Archive:

· CalcFields
Contains the calculated fields files used by Retain Web and Retain Wallchart which provide additional
derived information to the user. They are used internally by software to determine, for instance, the booking
request queues shown to a user.

· Documentation
Contains the user and administration guides for Retain Web edition you are using.

· Database Scripts
This folder contains all the database scripts (customised according to client's requirements) that can be run
to initialise a new Retain repository and get it ready to deploy Retain Web.

· Global Configuration
This folder contains the global deployment configuration tool and 2 global configuration files:
WebPortalDeployment.ini contains all the information needed to describe the deployment on the server
machines that have been chosen to host Retain Web. This configuration file is used by the Retain Web
Deployment Tool.
RetainGlobal.ini is the global Retain Web configuration file which will be accessed by all web application
server instances.
See Configuration Files chapter for more details.

7
 Deployment

· Global Installer
This folder contains an application that runs on each hosting server for the deployment and which will copy
onto it the necessary executable and configuration files for both the load balancer and web application
server modules.

· Interoperability
This folder contains bespoke tools which are used by the customer to import external data into Retain
repository, or the other way around. The contents of the folder depend on the customisations implemented
for the customer.

· IWRetainWeb
This folder contains the executable, configuration and static files for the load balancer module.

· SecurityConfiguration
This folder contains a text file representation of the logical security setup which has been implemented for
the customer.

· BatchFileTemplates
This folder contains various database related tools.

· Retain Enterprise
This folder contains Retain Server as well as Retain Security Manager which is used to configure the server
settings of the deployment. Retain Servers will have to be installed following the instructions in the Retain
Enterprise Deployment Guide in order to allow the generation of reports.

· RetainServersService
This folder contains the software that will install a service called RWPAppServers which will run all of the
application servers.

· WebPortal
This folder contains the executable and configuration files for the web application server module which will
be copied to the hosting server machines defined in the Global Configuration file WebPortalDeployment.ini

3.3 Single Instance Setup

This chapter describes how to configure a single instance of Retain Web application server. This option
enables the users to connect directly to the application server instance without having to use the load
balancer module.

This configuration should be performed before a more complex deployment in order to confirm that the
software runs properly and that the repository and the main configuration files are compatible with the
business requirements.

The single instance setup is also the suggested configuration for the demo deployments. System
Administrators of Retain Web should configure a standalone instance in order to perform troubleshooting
once the deployment has gone live.

Database Setup

The first step in Retain Web deployment is the creation of a repository which will hold the Retain data.

'Database Scripts' folder in the Global Deployment Archive contains the scripts which are needed for creating
this initial repository. Your DBA should provide you with a new database schema for hosting the repository.

Oracle 9i and 10g

Before running the following database script, double check with your DBA that Oracle Text has been installed
on the Oracle instance.

8 8
 Deployment

In the Global Deployment Archive go to the 'Database Scripts' -> 'Oracle' folder. It consists of 'Log',
'RecurringScripts' and 'Setup' folders and the two scripts that need to be run:

To set up the Retain database schema, run the SetupORA.sql script using SQLPlus against the Retain
database user.

In addition, UpdateORA.sql needs to be run overnight and after the database is created.

Sql Server 2005

Prerequisites:
MS SQL Server 2005 with full text Indexing installed or MS SQL Server 2005 Express Edition with Advanced
Features with full text Indexing installed. Also, Windows User 'Everyone' has full control of
'FullTextSearchSQL.dll' file found in the DbScripts-> SQLServer-> Setup sub folder.

In the Global Deployment Archive go to the 'Database Scripts' -> 'SQLServer' folder. It consists of 'Log',
'RecurringScripts' and 'Setup' folders and the two scripts that need to be run:

To create the database, run SetupSQL.bat. The parameters used are <Sql server name> <database name>
<Login id> <Password>.

In addition, UpdateSQL.bat needs to be run overnight and after the database is created with the same
parameters.

Note: All the log files are stored in the 'Log' folder.

9
 Deployment

Using the Deployment Tool

The Deployment Tool is a tool that helps you to configure all the necessary settings for setting up one or more
Retain Web instances without having to manually edit the configuration files.

The tool is called WebPortalDeployment.exe and it can be found in the 'Global Configuration' folder:

[GLOBAL ARCHIVE SETTINGS]

This section provides settings for the Global Deployment Archive.

· PATH
This is the UNC path to the Global Deployment Archive, usually a shared drive on a central server. E.g.: \
\server1\GlobalDeploymentArchive.

· USER NAME
The username needed to authenticate to the machine where the Global Deployment Archive is stored.
Empty by default.

· PASSWORD
The password needed to authenticate to the machine where the Global Deployment Archive is stored.
Empty by default.

Note that USER NAME and PASSWORD will typically be used when the Global Deployment Archive is not on
the same machine as server instances.

[LOAD BALANCER SETTINGS]

10 10
 Deployment

This section contains settings for the load balancer module. If more than one load balancer module is used,
the network team will need to provide a round robin resolution of the Retain Web URL in order to spread the
load among the server machines. Otherwise, different URLs could be used to access the same deployment,
possibly organised by departments.

· MACHINES
The number of server machines which will host the load balancer module. Each of these machines will
need a working configuration of Internet Information Services.

Note: when setting up a single Retain Web instance, you do not need a load balancer, thus MACHINES
should be set to 0.

· BASE FOLDER
This is the folder where the software modules will be installed by the Web Deployment Tool. A new folder
will be created, if it does not exist. E.g.: C:\RetainWebl\LoadBalancer

[APPLICATION SERVERS SETTINGS]

This section contains the settings for server machine(s) where the Retain Web instances will be installed.

· MACHINES
Represents the number of server machines which will host the application server module.

· INSTANCES
Represents the number of instances of the application server that will be installed on each of the hosting
server machine. A separate folder will be created for each instance, called RetainWebN, where N is a
number between 1 and MACHINES.

· BASE FOLDER
This is the folder where the different RetainWeblN folders will be installed. A new folder will be created, if it
does not exist.
E.g.: C:\RetainWeb\AppServer

· HTTP PORT
The IP port used by the first instance of the application server module on each server machine, for instance
7777. The following instances on each application server machine will have ports assigned according to the
HTTP PORT STEP setting.

· HTTP PORT STEP

The number which is added to each instance to the initial HTTP PORT setting, in order to determine the
port on which each application server instance will run on a given hosting machine. For instance, if the
HTTP PORT is 7777 and the HTTP PORT STEP is 2, the first application server instance would run on port
7777, the second instance on 7779, the third instance on 7781 and so on.

· HTTPS PORT and HTTPS PORT STEP

These two settings are analogous to the HTTP ones and represent the ports used for HTTPS connections.
They should not correspond to ports which will be used by the HTTP protocol.

· CONFIG FILE
This is the UNC path to the RetainGlobal.ini file used by the whole Retain Web deployment. The
RetainGlobal.ini file can be found in the "Global Configuration" folder in the Global Archive. E.g.: \\server1
\GlobalDeploymentArchive\Global Configuration\RetainGlobal.ini

· SVRCNFG
This is the UNC path to the SvrCnfg.ini file used by Retain Servers. E.g.:
\\server1\GlobalDeploymentArchive\Retain Enterprise\Retain Server\SvrCnfg.ini

· CALC FIELDS
This is the UNC path to the calculated fields file (CalcFields.cff) used by the whole Retain Web deployment.
The Calc Fields files can be found in the 'CalcFields' folder in the Global Archive. E.g.: \\server1

11
 Deployment

\GlobalDeploymentArchive\CalcFields\CalcFields.cff

[BATCH FILES SETTINGS]

This section provides the settings for the batch file processes. These processes are typically used to stop/
start the different services, and to update different types of files on the different server instances.

· PATH
Represents the location of the batch files. A new folder will be created, if it does not exist. E.g.: C:
\RetainWeb.

· MACHINE
The name of the machine where the batch files are saved, usually the same server as the global archive

[DATABASE SETTINGS]
This section contains the necessary information required in order to connect to the database. With the current
configuration Oracle 9i and 10g; SQL Server 2005 databases are supported.

· DB NAME
When connecting to an Oracle database, this is the SID of the database to connect to. For SQL Server
databases, use the ADOConnectionString.exe to create the connection string.

ADOConnectionString.exe can be found in the 'Database Scripts' folder in the Global Archive. When
specifying the connection parameters, make sure that you tick the 'Allow saving password' check box in the
'Connection' tab.

· USER NAME
The username to be used in order to connect to the database. Usually blank for SQL Server database as
the user name is already specified in the connection string (DB NAME).

· PASSWORD
The password to be used in order to connect to the database. Usually blank for SQL Server database as
the password is already specified in the connection string (DB NAME).

[REPORT SERVERS SETTINGS]

This section provides settings for the report generator module to determine the Retain Server to connect to.

· INSTANCES
The number of Retain Server instances (machines or different ports on the same machine) dedicated to
running reports.

· THREADS
Represents the number of threads that will be used by the instance of the application server module which
will schedule reports. In all of the deployment only one instance of the application server will perform this
operation and the specific instance is the first instance on the first application server machine.

[RETAIN SERVERS SETTINGS]

This section provides settings for Retain server(s) that will be used.

· MACHINES
The number of machines that will host the RetainServer.exe module.

· INSTANCES
The number of instances of Retain Server that will be installed on each hosting machine. A separate folder

12 12
 Deployment

will be created for each instance, called RetainWebN, where N is a number between 1 and MACHINES.

· BASE FOLDER
This is the folder where the different RetainWebN folders will be installed. A new folder will be created, if it
does not exist. E.g.: C:\RetainWeb\AppServer

· TCP/IP PORT
This is the port number of Retain Server. E.g.:11444.

· STEP
The number which is added for each instance to the initial TCP/IP PORT setting, in order to determine the
port on which each application server instance will run on a given application server hosting machine. For
instance, if TCP/IP PORT is 11444 and the STEP is 2, the first application server instance would run on
port 11444, the second instance on 11446, the third instance on 11448 and so on.

· CALC FIELDS
This is the UNC path to the calculated fields file (CalcFields.cff) used by the whole Retain Web deployment.
The Calc Fields files can be found in the 'CalcFields' folder in the Global Archive. E.g.: \\server1
\GlobalDeploymentArchive\CalcFields\CalcFields.cff

[SMTP SERVER SETTINGS]

This section provides settings for the SMTP server used for emailing reports and documents and is used by
Retain Web Enterprise edition only.

· HOST
This is the location of the SMTP server.

· PORT
This is the port number of the SMTP server.

· FROM
The email address that will appear in the 'From' field when emailing reports and documents.

· USER NAME
The username used for the above email account.

· PASSWORD
The password used for the above email account.

13
 Deployment

Installing Application Server

Once Global Configuration File using the deployment tool has been configured, it is time to install the
application server instance on the machine designated for this purpose.

1. Go to the 'Global Installer' folder in the Global Deployment Archive.

2. Double click on the RWPDeployment.exe file. You should be presented with a window similar to the one
shown in the following picture:

Installation Tool

3. Click on the button and navigate to the WebPortalDeployment.ini, stored in the 'Global Configuration'
folder in the Global Archive:

Installation Tool: Selecting a File

4. Click on the button. After a while, a success message should be displayed:

Installation Tool: Success Message

5. The Retain Web instance should now be installed on the designated machine in the folder specified under
'Application Servers Settings' section in the Deployment Tool.

14 14
 Deployment

Installing the Services and External Processes

After installing the application server instance, the various services can be installed and started. A set of batch
files are created in the location specified in the 'Batch Files Settings' section using the Deployment Tool:

· InstallServices.bat: Installs all the services on the machine it runs on. This file is installed on all the server
machines.

· UnInstallServices.bat: Uninstalls all the services on the machine it runs on. This file is installed on all the
server machines.

· startAllMachineServers.bat: Starts all the services on all server machines. This file is installed on the
server specified in the 'Batch Files Settings' section.

· stopAllMachineServers.bat: Stops all the services on all server machines. This file is installed on the
server specified in the 'Batch Files Settings' section.

· startServices.bat: Starts all the services on the machine it runs on. This file is installed on all server
machines.

· stopServices.bat: Stops all the services on the machine it runs on. This file is installed on all server
machines.

To install services, run InstallServices.bat file.

Once the service is running, set up the external processes. These are the processes that will typically be
scheduled to run overnight using Windows Scheduler. They will update the data in the database.

External Processes:

· RetainDataBuilder.exe: This application is located in the 'Interoperability'->'RetainDataBuilder' folder in the

Global Archive. This process generates documents in the database from various sources. SIConfig.ini will
have to be configured with the appropriate settings before it can run (see Retain Data Builder
documentation). These documents are typically used for searching purposes.

· HTBFormatCmd.exe: (SQL Server only) This process generates html representations of the documents in
the database. This application can be found in the 'Interoperability'->'HTBFormat' folder.
Note that SvrCnfg.ini has to be configured with the correct database connections settings before this
application can run.

Oracle specific scripts:

· UpdateORA.sql: This script should be scheduled to run overnight. It can be found in the 'Database
Scripts'->'Oracle' folder in the Global Archive.

SQL Server specific scripts:

· UpdateSQL.bat: This batch file should be scheduled to run overnight. It takes the following parameters:
<dbserver> <dbname> <dbusername> <dbpassword>. The file can be found in the 'Database Scripts'-
>'SQLServer' folder in the Global Archive.

15
 Deployment

Startup

Once all the files are appropriately configured, run the startAllMachineServices.bat file (from the location
specified in the 'Batch Files Settings' section using the Deployment Tool) to start the application server
services.

Launch your browser and enter this URL: http://<servername>:<portnumber>/Files/static/html/webPortal.html?

User=Manager ('Manager' is one of the users already created by default in the system).

Note: the URL above is for a single instance installation only. When using a load balancer module, the
<servername> would be the load balancer server machine and the <portnumber> would not be required.

Security Configuration

Once Retain Security Manager is set up (see Retain Security Manager User Guide for details), in order to be
able to log on to Retain Web, at least one resource has to be created in the repository and linked to a security
user. You can either create a new security user (see Security Model chapter for more information) or use one
of the three predefined Retain Web users:

· RWP_Planner - User who is able to edit resources, jobs and schedules of other users

· RWP_Manager - User who is able to request resources on his/her jobs and can create as well as edit jobs

· RWP_Individual - User who can edit his/her schedule only

You are able to create resources and assign them appropriate security rights using either Retain Security
Manager or Retain Wallchart. When a new resource is created, in order to be able to log on to Retain Web at
least two fields will have to be filled in:

User Name - which will be used to log on

User ID - which is one of the Retain Web security users

Global Archive Configuration Files

The main Global Archive configuration files are:

· RetainGlobal.ini
This file may need to be edited manually. It defines the runtime settings of the application server. Also, the
file specifies the authentication method to be used for user log on, the fields to be displayed in various tabs,
the documents included in the text search and so on.

· Retain.ini
These settings are determined using the Deployment Tool. The file defines the HTTP ports the server will
listen on for connections, which file contains the runtime settings of Retain Web and what means should be
used to obtain the data from Retain data model. These settings should not be edited manually.

· SvrCnfg.ini
These settings are determined using the Deployment Tool. This is the same file that is used by Retain
Server and it determines the database to connect to as well as general settings that affect performance.

See Configuration Files chapter for more information.

16 16
 Deployment

Troubleshooting

This section lists some possible issues that may arise when launching Retain Web as well as suggested
solutions.

· When I try to connect using the browser I get a 404 page not found error:
§ Check using the Task Manager if RetainWeb.exe is running. If not, try to run RetainWeb.exe manually
from the 'WebPortal' installation folder.

Double clicking on the RetainWeb.exe will open up the following window:

In the 'Runtime parameters' edit-box enter the string USER=Username where Username corresponds to the
Logon value you have entered following the steps in the Security Configuration section. E.g.: USER=Manager.
'Manager' is one of the users already created by default in the system.

To launch Retain Web, click on the small browser icon at the top left corner (or press keyboard shortcut F9)
and a browser window displaying Retain Web pages will open.

· When I double click on RetainWeb.exe, nothing happens:

§ Check that you have entered the correct database, username and password details in the SvrCnfg.ini.
§ Confirm that only one instance of RetainWeb.exe is running on the same port.
§ Try deleting the LockFile from the 'Licence' folder.

· Can not connect to RetainWeb.exe:

§ Check that the port number used in the URL is the same as in Retain.ini (found in the 'Config' folder).
§ Check that the path to calculated fields in SvrCnfg.ini is correct, i.e. pointing to the relevant calculated
fields.

· When I launch Retain Web I get a message: 'User not Authenticated' or 'Could not connect to
database':
§ Check the spelling of the username you are trying to log on as and compare it with the entry in your
database.
§ Check SvrCnfg.ini to see if you are connecting to the right database.

3.4 Multiple Instances Setup

To deploy multiple Retain Web instances as well as load balancer modules you need to:

1. Set up a single Web Portal instance and make sure it works.

2. Edit the single instance setup settings using the Deployment Tool.

3. Setup and start the service for the Web Portal application server instances on each hosting machine.

4. Setup and start the service for the Load Balancer Module on each hosting machine.

5. Check that you can run all Retain Web instances.

17
 Deployment

Editing Deployment Settings

The Deployment Tool is a tool that helps you to configure all the necessary settings for setting up one or more
Retain Web instances without having to manually edit the configuration files.

The tool is called WebPortalDeployment.exe and it can be found in the 'Global Configuration' folder:

[GLOBAL ARCHIVE SETTINGS]

This section provides settings for the Global Deployment Archive.

· PATH
This is the UNC path to the Global Deployment Archive, usually a shared drive on a central server.
E.g.: \\server1\GlobalDeploymentArchive.

· USER NAME
The username needed to authenticate to the machine where the Global Deployment Archive is stored.
Empty by default.

· PASSWORD
The password needed to authenticate to the machine where the Global Deployment Archive is stored.
Empty by default.

Note that USER NAME and PASSWORD will typically be used when the Global Deployment Archive is not on
the same machine as server instances.

[LOAD BALANCER SETTINGS]

18 18
 Deployment

This section contains settings for the load balancer module. If more than one load balancer module is used,
the network team will need to provide a round robin resolution of the Retain Web URL in order to spread the
load among the server machines. Otherwise, different URLs could be used to access the same deployment,
possibly organised by departments.

· MACHINES
The number of server machines which will host the load balancer module. Each of these machines will
need a working configuration of Internet Information Services.

· BASE FOLDER
This is the folder where the software modules will be installed by the Web Deployment Tool. A new folder
will be created, if it does not exist.
E.g.: C:\WebPortal\LoadBalancer

[APPLICATION SERVERS SETTINGS]

This section contains the settings for server machine(s) where the Retain Web instances will be installed.

· MACHINES
Represents the number of server machines which will host the application server module.

· INSTANCES
Represents the number of instances of the application server that will be installed on each of the hosting
server machine. A separate folder will be created for each instance, called WebPortalN, where N is a
number between 1 and MACHINES.

· BASE FOLDER
This is the folder where the different WebPortalN folders will be installed. A new folder will be created, if it
does not exist.
E.g.: C:\WebPortal\AppServer

· HTTP PORT
The IP port used by the first instance of the application server module on each server machine, for instance
7777. The following instances on each application server machine will have ports assigned according to the
HTTP PORT STEP setting.

· HTTP PORT STEP

The number which is added to each instance to the initial HTTP PORT setting, in order to determine the
port on which each application server instance will run on a given hosting machine. For instance, if the
HTTP PORT is 7777 and the HTTP PORT STEP is 2, the first application server instance would run on port
7777, the second instance on 7779, the third instance on 7781 and so on.

· HTTPS PORT and HTTPS PORT STEP

These two settings are analogous to the HTTP ones and represent the ports used for HTTPS connections.
They should not correspond to ports which will be used by the HTTP protocol.

· CONFIG FILE
This is the UNC path to the RetainGlobal.ini file used by the whole Retain Web deployment. E.g.: \\server1
\GlobalDeploymentArchive\Global Configuration\RetainGlobal.ini

· SVRCNFG
This is the UNC path to the global SvrCnfg.ini file used by the whole Retain Web deployment. E.g.: \
\server1\GlobalDeploymentArchive\SvrCnfg.ini

· CALC FIELDS
This is the UNC path to the calculated fields file (CalcFields.cff) used by the whole Retain Web deployment.
E.g.: \\server1\GlobalDeploymentArchive\CalcFields\CalcFields.cff

[BATCH FILES SETTINGS]

19
 Deployment

This section provides the settings for the batch files.

· PATH
Represents the location of the batch files. A new folder will be created, if it does not exist. E.g.: C:
\WebPortal.

· MACHINE
The name of the machine where the batch files are saved, usually a shared drive on a central server.
E.g.: server1

[DATABASE SETTINGS]
This section contains the necessary information required in order to connect to the database.

· DB NAME
When connecting to an Oracle database, this is the SID of the database to connect to. For SQL Server
databases, use the ADOConnectionString.exe to create the connection string.

ADOConnectionString.exe can be found in the 'Database Scripts' folder in the Global Archive. When
specifying the connection parameters, make sure that you tick the 'Allow saving password' check box in the
'Connection' tab.

· USER NAME
The username to be used in order to connect to the database. Usually blank for SQL Server database as
the user name is already specified in the connection string (DB NAME).

· PASSWORD
The password to be used in order to connect to the database. Usually blank for SQL Server database as
the password is already specified in the connection string (DB NAME).

[REPORT SERVERS SETTINGS]

This section provides settings for the report generator module to determine the Retain Server to connect to.

· INSTANCES
The number of Retain Server instances (machines or different ports on the same machine) dedicated to
running reports.

· THREADS
Represents the number of threads that will be used by the instance of the application server module which
will schedule reports. In all of the deployment only one instance of the application server will perform this
operation and the specific instance is the first instance on the first application server machine.

[RETAIN SERVERS SETTINGS]

This section provides settings for Retain server(s) that will be used.

· MACHINES
The number of machines that will host the RetainServer.exe module.

· INSTANCES
The number of instances of Retain Server that will be installed on each hosting machine. A separate folder
will be created for each instance, called WebPortalN, where N is a number between 1 and MACHINES.

· BASE FOLDER
This is the folder where the different WebPortalN folders will be installed. A new folder will be created, if it
does not exist. E.g.: C:\WebPortal\AppServer

20 20
 Deployment

· TCP/IP PORT
This is the port number of Retain Server. E.g.:11444.

· STEP
The number which is added for each instance to the initial TCP/IP PORT setting, in order to determine the
port on which each application server instance will run on a given application server hosting machine. For
instance, if TCP/IP PORT is 11444 and the STEP is 2, the first application server instance would run on
port 11444, the second instance on 11446, the third instance on 11448 and so on.

· CALC FIELDS
This is the UNC path to the calculated fields file (CalcFields.cff) used by the whole Retain Web
deployment.
E.g.: \\server1\GlobalDeploymentArchive\CalcFields\CalcFields.cff

[SMTP SERVER SETTINGS]

This section provides settings for the SMTP server used for emailing reports and documents and is used by
Retain Web Enterprise edition only.

· HOST
This is the location of the SMTP server.

· PORT
This is the port number of the SMTP server.

· FROM
The email address that will appear in the 'From' field when emailing reports and documents.

· USER NAME
The username used for the above email account.

· PASSWORD
The password used for the above email account.

Installing Application Servers

Once you have configured the Global Configuration File using the Deployment Tool, it is time to install the
application server instances on the server machines you have designed for this purpose.

Note: Before running this tool, make sure you stop any Retain services that were started whilst setting up a
single instance.

The procedure described below should be followed for each of the server machines that will host application
servers.

1. Log on to the server machine.

2. Go to the Start Menu and choose Run.

3. Type in or paste the UNC path of the Global Deployment Archive, for example \\server1
\GlobalDeploymentArchive, and press enter.

4. Copy the 'Global Installer' folder from the Global Archive to Desktop.

5. Double click on the RWPDeployment.exe file. You should be presented with a window similar to the one
shown in the following picture:

21
 Deployment

Installation Tool

6. Click on the button and navigate to the WebPortalDeployment.ini, stored in the 'Global Configuration'
folder in the Global Archive:

Installation Tool: Selecting a File

7. Click on the button. After a while, a success message should be displayed:

Installation Tool: Success Message

8. Install Services:

After installing the application server instance, the various services can be installed and started. A set of batch
files are created in the location specified in the 'Batch Files Settings' section using the Deployment Tool:

· InstallServices.bat: Installs all the services on the machine it runs on. This file is installed on all the server
machines.

· UnInstallServices.bat: Uninstalls all the services on the machine it runs on. This file is installed on all the
server machines.

· startAllMachineServers.bat: Starts all the services on all server machines. This file is installed on the

22 22
 Deployment

server specified in the 'Batch Files Settings' section.

· stopAllMachineServers.bat: Stops all the services on all server machines. This file is installed on the
server specified in the 'Batch Files Settings' section.

· startServices.bat: Starts all the services on the machine it runs on. This file is installed on all server
machines.

· stopServices.bat: Stops all the services on the machine it runs on. This file is installed on all server
machines.

To install services, run InstallServices.bat file.

Load Balancer Module

The Load Balancer Module balances the load between the application server instances. It consists of an
ISAPI dll (IWISAPIRedirect.dll) and a service application (RWPHCM.exe).

The Load Balancer Module requires an IIS web server to run and it servers static content requested from the
client.

Installation and Configuration

In order to install the Load Balancer module, please perform the following procedure on each server machine
which has been designed to host it.

1. Log on to the server machine.

2. Go to the Start Menu and choose Run.

3. Type the UNC path of the Global Deployment Archive, for example \\server1\RWPGlobalArchive, and
press enter.

4. Copy the 'Global Installer' folder from the Global Archive to Desktop.

5. Double click on the RWPDeployment.exe file. You should be presented with a window similar to the one
shown in the following picture:

Deployment Tool

6. Click on the button and navigate the file system choosing the Global Deployment configuration file,
stored in the Global Configuration folder of the global archive.

7. Click on button and wait for a success message to appear saying 'Installation Completed'.

23
 Deployment

8. Go to the location where the Load Balancer module has been installed, for example C:
\Content\Retain\IWRetainWeb. Double click the Inst.bat file which will install a service called RWPHCM.
This service will constantly monitor the current status of the application server instances in the
deployment.

9. Edit the hclog.ini configuration file for RWPHCM. This file determines the logging level and where the log
files will be stored. Please edit the
log4delphi.appender.fileAppender.File setting which should point to a folder in the file system where the
Windows predefined user LOCALUSER is able to write to. The rest of the file is auto-documented, but the
default values should be suitable for most situations.

10. Go to Control Panel-> Administrative Tools-> Services and start the RWPHCM service.

11. From the Administrative Tools open the Internet Information Services (IIS) Manager.

12. Drill down the tree control on the left to: Internet Information Services-> Your Computer Name-> Web
Sites-> Default Web Site or the web site you have decided to use for the load balancer.

13. Right click on Default Web Site and choose New -> Virtual Directory.

14. Click on Next in the dialog that will pop up.

15. Type in 'IWRetainWeb' in the Alias field, then click on Next.

16. Click on Browse and select the base Load Balancer folder. For example: C:\Content\Retain\IWRetainWeb
.

17. Make sure that the following boxes are checked: Read, Run Scripts, Execute, and Write. Then click on
Next. Click on Yes should a warning message pop up.

18. Under the Default Web Site a new entry called IWRetainWeb should appear.

19. On the tree control navigate to Web Service Extensions and click on the Add a new Web service
extension...

20. In the wizard that pops up, enter 'IWRetainWebExt' as the Extension name and then click on the Add
button. In the Add File dialog click on the Browse button and select the IWISAPIRedirect.dll file. Click on
OK. Check the 'Set extension status to Allowed' then click 'OK' to close the wizard.

The new web extension should appear in the list on the right of the screen, as illustrated below:

21. On the tree control navigate to Application Pools, right click on it and select New -> Application Pool...

24 24
 Deployment

22. In the wizard that appears, enter 'IWRetainWebAppPool' as the Application Pool ID, select 'Use default
settings for new application pool' and then click on OK. The new application pool should appear under
Application Pools.

23. Navigate the tree control to Internet Information Services-> Your Computer Name-> Web Sites-> Default
Web Site-> IWRetainWeb. Right click on it and choose the properties from the popup menu.

24. Select 'IWRetainWebAppPool' for the Application Pool drop down menu and make sure 'Scripts and
Executable' is selected for Execute Permissions. Your configuration should be similar to the following
image:

25. Make sure that the IWRetainWebAppPool is started by navigating to it and clicking on the triangle on the
toolbar if it is not grayed out.

26. Now make sure that the Default Web Site is running, analogously to the previous step.

27. Close the management console. You now should be able to run the deployment.

Outage Notification

When by some reason an outage occurs (if there is no available Web Portal application or service that can
handle the user request or a communication failure), a special page will be displayed to the users showing the
error information.

A template is used to render this page. It is a file located in the same directory as the IWISAPIRedirect.dll and
the RetainWeb.ini files. The name of the template is configured in RetainWeb.ini.

RetainWeb.ini settings

25
 Deployment

[Outage]
· TemplateFileName=OutageTmpl.html
Used to configure the name of the template file that is used when rendering the outage notification page.

· IsPlanned=0
Determines whether the outage is planned or not. The default value is 0.

· PlannedErrorMsg=Retain Web Portal is currently unavailable due to essential maintenance work.<br>We

apologise for the inconvenience.
The message used when a planned outage occurs.

· NonPlannedErrorMsg=Retain Web Portal is currently unavailable.<br>We apologise for the

inconvenience.
The message used when an unplanned outage occurs.

The outage notification mechanism depends on the IsPlanned setting (see above).

If it is set to 1, it means that the maintenance work is currently being carried out (e.g. a server update). In this
case, the message defined in the PlannedErrorMsg setting will be displayed.

If it is set to 0, (which is its default setting), it means that the server is running normally and we do not expect
any disruptions. If in this case an outage occurs, the message defined in the NonPlannedErrorMsg setting will
be displayed together with a ‘For more details click here’ link. This link will show additional information
regarding the causes of the outage.

Note: When changing a setting in RetainWeb.ini, you need to re-initialise the IWISAPIRedirect.dll. This can
be done by restarting the application pool that the IIS uses for the IWISAPIRedirect.dll.

Web Authentication methods

Retain Web has 3 different types of authentication.

1. Integration with Single Sign on Systems like Active Directory or Siteminder.

When using this type of authentication, the single sign on system will populate a HTTP header containing
the username of the authenticated user. The application server will then use this value to log on to Retain.
Simple IIS authentication where the username is set in a HTTP header also works.

2. Simple web authentication. When using this method the user will be presented with a logon dialog.

3. Querystring. This is typically only used when setting up the system. When using this form of
authentication, a query string variable is added to the URL:

<URL>?User=username

File Distribution

In order to distribute the files on the server machines designated to host them, you should first of all copy all
the configuration files that you edited in the previous phase to the Global Archive.

If you plan to use the Load Balancer Module, you should also edit this configuration:

RetainGlobal.ini - This file is located in the Config folder. By default, you will find the following
settings in the [Global] section:
;URLBase=/IWRetainWeb/IWISAPIRedirect.dll
URLBase=

You should remove the comment from the first line and put it on the second line to get the following result:

26 26
 Deployment

URLBase=/IWRetainWeb/IWISAPIRedirect.dll
;URLBase=

See Configuration Files chapter for more information.

Startup procedure

Once you have successfully deployed the modules, it is time to start the Application Servers by running
startAllMachineServers.bat process. This file is installed into the location specified by the setting in the "Batch
Files" section in the deploy tool. If you cannot start up the servers on other machines, a startServers.bat file is
installed on all the server machines in the location specified in the "Batch Files" section in the deploy tool.

If using the Load Balancer Module, you may check the health check page to see the current status of the
application servers present in the <%RWP% deployment. Run Internet Explorer and type in the following
URL http://hostname/IWRetainWeb/IWISAPIRedirect.dll/healthcheck where hostname is the name or address
of the server running the Load Balancer Module.

If everything is in order you may connect to the Retain Web URL:

The URL when using the Load Balancer Module is http://hostname/IWRetainWeb/IWISAPIRedirect.dll/

Files/static/html/webPortal.html, where hostname is the name or address of the machine running the Load
Balancer Module. If your global configuration is set up to use a querystring variable to authenticate (see
the RetainGlobal.ini file), you need to add this to the URL: ?User=Username where Username is a user or
resource in the Retain database.

The URL without using the Load Balancer Module is http://hostname:Port/Files/static/html/webPortal.

html?User=Username, where hostname is the name or address of the machine running the Application
Server and port is the port number specified in Retain.ini.
For example: http://Server2:7777/Files/static/html/webPortal.html?User=John

Note: You can also specify a default selection that will be applied to Jobs and Individuals pages within the
URL: http://hostname:Port/Files/static/html/webPortal.html?selection=ressel1 where ?selection=ressel1 is a
selection defined in the JobSel and PeopleSel sections within the RetainGlobal.ini file.

Troubleshooting

Failed to authenticate
· Are you using the correct authentication method?
· Does your user exist in the database?
· Have you set the correct HTTP Header for the user name when using a Single Sign on system?

Oddly formatted web page

· If you are using a Load Balancer, have you got all the necessary files in the Files sub folder?
· Have you got the Template and Template_templ folder in the root of the application server installations?

No application servers are up and running

· Are the application server services installed and running?

Cannot connect when using a Load Balancer

· Have you setup IP and port numbers to the application servers?

Get a 'Cannot connect to database' message when trying to connect

· Have you setup the connection details in Deployment Tool?
· Have you got a valid location setup for the Calculated fields in Deployment Tool?

27
 Administration

4 Administration
4.1 View Templates

View Templates allow you to have predefined views for Jobs and Individuals pages. Once you select a certain
view template, all the settings of that template will be applied to the Planner view.

Depending on the edition of Retain Web you are using, you might be able to edit the existing settings of a
view template.

To do that, go to the 'WebPortal'-> 'Config'-> 'xml'-> 'pln_view_templates' folder.

· view name and code

The name and the code of the view template as it will appear in Retain Web.
Example: view name="Resources by Office" code="resbyoffice"

· base_table name
The database table the view template is based on.
Example: base_table name="RES"

· rotate_to code
The rotate view (the alternate view that you will be presented with when clicking on the button)
Example: rotate_to code="jobsbyoffice"

· default_selection code
The selection applied to the view by default. For example: default_selection code="ressel1"

· grouping
The grouping of jobs and resources. Identify the table and the field names as well as whether the field can
have a null value (if 'false') or not (if 'true').
Example: group table="RES" field="RES_OFFICE" isid="false"

· name_fields
The columns which will be displayed on the left-hand side of the Wallchart.
Example: if you want to display resources' current grade and office alongside their name, set the following
values:
<name_fields>
<field name=" CurrGrade" />
<field name=" RES_OFFICE " />
</name_fields>

· col_scheme
The colour scheme selected (default or ghost).
Example: <col_scheme>Ghost</col_scheme>

· mark_non_work default
if set to 'true', the non-working regions are being marked. If false, are not marked.
Example: mark_non_work default="true"

· view_mode mode
The time view displayed (monthly, weekly or daily).
Example: view_mode mode="week"

· days_per_week
The number of working days displayed (5 or 7 days).
Example: days_per_week days="7"
project_view default
If set to 'true', the project view is turned on. If set to 'false', turned off.

· startdate
Defines the start date. Can be offset relative to today.

28 28
 Administration

Example: <startdate use-offset="true" offset="-14" />

4.2 Calculated Fields Reference

Introduction

Retain Web uses calculated fields to pre-calculate values that are used in different areas of the application.
Calculated fields provide additional derived information to the user and are used by the software internally to
determine certain values. Another advantage of using calculated fields is speeding up calculations thus
enhancing performance.

When Retain Server is fired up it registers, calculates and stores a number of calculated fields that are used a
multiple times in Retain Web processes. This allows the server to calculate the fields once and reuse them
afterwards, avoiding redundancy.

Calculated fields are specified in the text files with a .cff (calculated field file) extension. By default, all the
calculated field files are in the CalcField folder in the root folder of Retain Web installation (this might vary
depending on the installation). Retain Servers are configured from SvrConfg.ini initialisation file to use specific
set of calculated field files. You can use the relative or absolute path to point to calculated field files folder.

You can customise/create new calculated fields according to your requirements with Retain International's
supervision and consent only. Moreover, the standard set of calculated fields should be enough to work with
and adding or changing the standard set of files should be avoided.

A calculated field file can contain:

· Calculated/Function field
· Calculated Table
· Calculated View
· Macros

Calculated tables and views act like database tables and views although they are created dynamically and
destroyed when Retain Server is shutdown.

Customisation

You can customise certain areas of Retain Web using calculated fields, although only with Retain
International’s supervision and consent.

For example, you can add custom fields to appear in reports if you are using Retain Enterprise Reports.
Another area is configuring security, e.g. how the values will appear in drop downs for a specific user.
Possible areas which you might consider customising are:

· Company Constants
· Reports
· Security

Rules for Designing Calculated Fields

General Instructions

This sections is for those who want to create calculated fields. The person should have a basic knowledge of
SQL and general principles of programming. A good knowledge of underlying database structure can be very
useful and helps in writing and understanding calculated fields.

Comments

29
 Administration

A comment is the text that will be ignored while processing calculations in calculated field files. You can use
comments when writing calculated fields. Writing comments is always recommended as they are helpful for
future reference. You can use the following comment styles:
· Bracketed Comments: Introduced by /* and ended with */ bracketed comments can span over
multiple lines.
· Curly Brackets: Introduced by { and ended with } these comments can also span over multiple
lines.
· Semi Colon: Comments that are introduced by semi colon and can only appear at the beginning of
the line. They are used for commenting on a single line.
· Double Forward Slash: Comments that are introduced by // and can only appear at the beginning of
the line. They are also used for commenting on a single line.

Naming Conventions

The following rules should be followed when naming is constructed (Function fields, Functions, Macros, etc.):
· Field names should be self explanatory and should reflect the intention of the field.
· Do not use special characters.
· Do not use spaces.
· Name the fields using the first letter of a word in upper case.

Available Structures/Objects

The following structures/objects can be specified when creating calculated fields:

· Tables
· Function Fields
· Views
· Macros

Structure of the File

There are no strict rules for the structure of a calculated field file. Ideally, it should be similar to the following:

· General information about the file

· List of USE Statements
· List of Macros
· List of tables and its Function fields

Tables and Function Fields

Function fields will be based on database tables. To write function fields for a database table, follow this
syntax:

Table = <table name>

{
FunctionField
{
FieldName = <Field Name>
FieldDescription = <Field Description>
Calc = <Calculation Formula>
From = <From Clause to pull values from a table>
BaseField = <Base Field>
Link = <Link>
Condition = <One or more conditions to filter data>
NullValue = <Value if result is Null>
FieldType = <Type of field>

30 30
 Administration

· Table Name: The name of the table that the calculated field will be based on.
· Field Name: The calculated field name.
· Field Description: The description of the field. This should provide a clear indication of the
purpose of the calculated field and its usage.
· Calc: The calculation formula that will be used to calculate the result.
· From: This is similar to the SQL From clause and specifies the names of tables that the field
should pull the data from. We can also use this to alias the table names.
· BaseField: The value that a calculated field will be based on.
· Link: Link specifies the potential link between two fields.
· NullValue: The value in case the result is null.
· FieldType: The field type of the result. E.g.: integer, string etc.

You can specify as many fields as you like for a table. Fields should be nested inside the body of a table, i.e.
within the curly brackets.

Views

Views defined in calculated fields are similar to views in the database. They are used to represent data from
multiple tables.

Macros

Macros are essentially SQL statements that are grouped together to compute specific data. This is similar to
functions in some programming languages. Macros can be called multiple times and you can also pass
arguments to macros.

Conditional Logic

Calculated fields support specification of conditional logic statements. Specify Boolean conditions using the
following syntax:

? <condition(1)>
action if condition true
|? <condition(2)>
action if condition true
|? <condition(n)>
action if condition true
/?

Available Functions

The predefined functions, which can be used while creating calculated fields, are:

· REPL: Replace the string with specified value.

· DB_CODE: Sspecify the target database.

31
 Administration

Adding Calculated Fields

It is possible to add calculated fields but this is not advisable or supported. Moreover, no utilities exist that
would aid the creation of fields. However, if you have decided to make changes, the following guidelines
should be observed:

1. Back up the existing files before making any changes.

2. Create new calculated fields wherever possible and do not delete/amend the existing ones.
3. Add fields to the end of the file. A table can exist in more than one group, thus there is no need to squeeze
the calculated field at the top of the file.
4. Clearly mark the changes you have made, so that if the altered file is supplied by Retain, your changes
could be easily fitted into the modified file.
5. Read through the existing set of calculated fields.
6. Calculated fields can refer to other fields or calculated fields against a table and currently no mechanism
exists for referring to fields from another table.
7. Do not make calculated fields that may directly or indirectly refer back to themselves.
8. Work on a file using a test server.

Constants

Constants defined in Retain Web yield the same value throughout the Retain Web process.

Constants that need to be configured when Retain Web is installed for the first time are the following:

· Company Name
· Skill attributes
· Any Company Constants

CalcFields.cff

CalcFields.cff specifies the files included in the calculation. By default, a number of files are provided for
Retain server to be able to run. Calculated files can be included using the USE keyword.

If you want to included a file, apply the USE keyword followed by the equal sign and the file name. For
example, if you want to include a file called ABC.cff, type in:

USE=ABC.cff

Note that the file should be in the same folder and that the specification of absolute or relative paths is not
supported.

DefineCompany.cff

To customise Retain Web according to a specific installation, some of the constants that will be used
throughout Retain have to be defined.

DefineCompany.cff file specifies the name of the company for which Retain Web is implemented. This name
will be used in other calculated field files.

By default, the define company file looks like this:

REPL(COMPANY) = NOCOMPANY

Replace NOCOMPANY with the name of your company and save the file. After changing your company name
you need to rename the NOCOMPANYConsts.cff file to the company name you have specified in the
DefineCompany.cff file. For example, if the name of your company is ABC, set the following values:

DefineCompany.cff

32 32
 Administration

REPL(COMPANY) = ABC

NOCOMPANYConsts.cff

Rename the file to ABCConsts.cff

Note that only the 'NOCOMPANY' string is changed and Consts.cff remains the same.

CompanyConsts.cff

Company constants are defined in the CompanyConts.cff file. By default, the file looks like this:

CompanyConsts.cff

REPL(RESUMEID) = 1
REPL(SKILLSDOCID) = 1003
REPL(BOOKINGHISTORYDOCID) = 1000
REPL(RESOURCEDATADOCID) = 1001
REPL(RESPREFDOCID) = 1002
REPL(RESUMENAME) = CV
REPL(SKILLDOCNAME) = SKILLSDOC

REPL function is used to specify values for the following constants: Resume, Skills, Booking History,
Resource Data, Resource Preference Documents as well as Resume Name and Skills Document Name.
These constants represent the unique IDs of attributes in the ATR table.

If you want to add another skill attribute, you need to add it to Retain database as well as the CompanyConts.
cff file. For example, if you want to add skill attribute Qualification Matrix with ID 108 to the database, you
need to type in:

REPL(QUALIFICATIONMATRIXID) = 108

4.3 Built-in Calculated Fields

The following calculated field files are installed by default together with Retain Web:
CalcFields.cff
· CalcFieldsDGD.cff
· ConflictsAllScenarios.cff
· ConflictsNoScenarios.cff
· ConflictsSA.cff
· DBInd.cff
· Debug.cff
· DefineCompany.cff
· Dependencies.cff
· FastTime.cff
· Forecast.cff
· ModelSecurity.cff
· NOCOMPANYConsts.cff
· OldRevenueCost.cff
· OriginalTime.cff
· Phonetics.cff
· Precalc.cff
· RequestEconomics.cff
· RevenueCost.cff
· ScenarioFilter.cff

33
 Administration

· scenarios.cff
· Security.cff
· Team.cff
· Triggers.cff
· Variance.cff
· Wallchart.cff

Calculated Fields Files

This file defines the files that Retain Web will use in calculations. The files are included by using the key word
USE.

For example, if you want to include a new file called NewCalcFldFile.cff, add the following to the CalcFields.
cff:

USE=NewCalcFldFile.cff.

Calculated Fields for Diaries

This file contains the fields that are used in diaries.

Conflicts

The following files contain the fields that are involved in booking conflicts:

· ConflictsAllScenarios.cff
· ConflictsNoScenarios.cff
· ConflictsSA.cff

Define Company

This file contains the company name. It should be replaced by a specific company name.

Database Independence

This file contains the function mapping that is available for a different database.

Fast Time

These are the basic calculation fields that are used when scheduling.

34 34
 Administration

Company Constants

By default, NOCOMPANYconsts.cff file contains company constants.

This file should be renamed according to a specific company. Also, the constants defined for skills should be
modified according to the database settings.

Phonetics

This file contains functional fields/tables used by Retain Wallchart's phonetic algorithm for indexing names by
sound.

Pre-calculated Fields

Pre-calculated fields speed up calculations. They are mostly used for reports.

Request Economics

This file contains fields that are used for the booking requests calculations.

Scenarios

This file is used by Retain Wallchart for the functionality of scenarios. Scenarios are mechanisms used for
grouping bookings together.

Security

These macros are mostly used to represent security and business rules, such as the drop down values that
will be visible to a specific user. You might consider customising these fields in the Security.cff file.

Triggers

This file contains database triggers that are run upon specific events. A database trigger is a code that is
automatically executed in response to certain events on a particular table in the database. By default, there
are two files for triggers: Triggers and SQL Triggers.

Team

These calculated fields are related to the team functionality.

This file is to be edited before deployment in order to reflect the company's decisions on how the manager
and administrator roles are determined and how to affect the team work flow.

35
 Administration

Variance

These calculated fields define the variance calculated fields which compare budgeted time, revenue and cost
to the planned schedule.

Wallchart

These calculated fields are used by Retain Wallchart.

4.4 Retain Data Builder

Retain Data Builder (previously known as Skill Importer) is a tool that imports different types of data into the
database for use with Retain Web. It is intended for use with Oracle and MS SQL Server databases.

Retain Data Builder is run either using the config.ini configuration file (located in the 'Interoperability->
RetainDataBuilder' folder) to provide the options or through the command line. The tool can be easily
configured to be run nightly through a Windows scheduled job.

Furthermore, it creates html representations of the information used during quick searches.

Note: If you are using Oracle, you will need to run Retain Data Builder from a PC where the Oracle client is
installed.

Command Line Usage

1. Go to Start-> Run... Type in cmd and press Enter. A command line window will open.

2. In this window change to the folder where Retain Data Builder has been installed using the cd command.

3. Assuming your Retain Data Builder is located in c:\RWPGlobalArchive\Interoperability\RetainDataBuilder

use the following command:
cd c:\RWPGlobalArchive\Interoperability\RetainDataBuilder.

4. To run the software, type RetainDataBuilder.exe followed by the options you need.

When run through the command line without any parameters, the application will present you a help message:

Usage: RetainDataBuilder.exe [options]

Options:

-h, --help show this help message and exit

-x CONNECTION_STRING, --connection-string=CONNECTION_STRING
database connection string
-t DATABASE_TYPE, --database-type=DATABASE_TYPE
Database Type. This is a required setting. 'mssql' for
MS SQL server and 'oracle' for Oracle
-d DATABASE, --database-host=DATABASE
database host name (this must be set if connection
string is not set)
-n DATABASE_NAME, --database-name=DATABASE_NAME
database name (this must be set if connection string
is not set and when the database is MS SQL server)
-u USER, --user=USER database username (this must be set if connection
string is not set)
-p PASSWORD, --password=PASSWORD
database password (this must be set if connection
string is not set)
-j FNA_D_FILE Dump Functional access values file

36 36
 Administration

-a FNA_FILE Load Functional access values file

-l LOG_CONFIG_FILE, --log-config-file=LOG_CONFIG_FILE
configuration file for the debug log

The following is a categorised explanation of the available options:

Database Connection Options

This information should always be provided in order to allow Retain Data Builder to connect to the database
instance. At least one other option which performs an action should be passed as well, otherwise the help
message will be displayed.

-x CONNECTION_STRING Database connection string.

-t DATABASE_TYPE Database Type. This is a required setting. Use 'mssql' for MS SQL Server
and 'oracle' for Oracle.
-d DATABASE Database host name (this must be set if connection string is not set).
-n DATABASE_NAME Database name (this must be set if connection string is not set and when the
database is MS SQL Server).
-u USER Database username (this must be set if connection string is not set).
-p PASSWORD Database password (this must be set if connection string is not set).

Security Model Related Options

These options allow to export and import part of the Retain security model to and from a text file.

Writes the logical security rules of all the logical security profiles in the
repository to the file pointed by 'DUMP_SECURITY_FILE'.
-c LOAD_SECURITY_FILE Reads the logical security roles from the text file pointed by '
LOAD_SECURITY_FILE' and imports them in the repository. If one of the
imported roles does not exist, it will create a new one; otherwise it will update
the existing logical rules.
-j FNA_D_FILE Writes all the functional access values and roles contained in the repository to
the text file pointed by 'FNA_D_FILE'.
-a FNA_FILE Reads the functional access roles and associated values from the 'FNA_FILE'
text file and imports them in the repository. If a functional access role does
not exist, a new one is created; otherwise the existing functional access
values are overwritten with those imported.
Exports the table field information to the FLD_D_FILE file, where each row
corresponds to a record of the fld table. The fields should be comma
separated and the order of the exported fields should be FLD_TBL,
FLD_NAME, FLD_PRD_ID, FLD_ATTRIBUTE, FLD_VALUE.
-e FLD_FILE Imports the table field information from the 'FLD_FILE' text file, where each
row corresponds to a record of the FLD table. The fields should be comma
separated and the order of the exported fields should be FLD_TBL,
FLD_NAME, FLD_PRD_ID, FLD_ATTRIBUTE, FLD_VALUE .
These data can be exported through a text file from an Oracle database using
the following query, saving the output to a text file:
select fld_tbl||','||fld_name||','||fld_prd_id||','||fld_attribute||','||fld_value from fld
order by fld_tbl, fld_name, fld_attribute;

Various Options

37
 Administration

-h Shows the command line options.

-l LOG_CONFIG_FILE By default, the Retain Data Builder logging system is called log_config.ini.
This option allows to use another configuration filename.

Setting the Configuration File

To run Retain Data Builder you will need to set the options in the config.ini file which is included in the
standard setup and is in the same folder as the RetainDataBuilder.exe (Interoperability-> RetainDataBuilder).
Once you have set the options you will only need to run the executable.

Configuration Settings
Note: To omit any operation you may either comment out the operation’s setting and the related settings with
a ';' or leave blank after '='.

Fields/Sections Default Description

Values

[database]
constring The connection with the database is established either through the
connection string or the database settings.
dbtype Database Type. This is a required setting. Use 'mssql' for MS SQL
server and 'oracle' for Oracle.
dbhost Database host name (this must be set if connection string is not set).
dbname Database name (this must be set if connection string is not set and
when the database is MS SQL server).
dbuser Database username (this must be set if connection string is not set).
dbpassword Database password (this must be set if connection string is not set).
encoding Windows-1252 Encoding that works with your database server.
date_format %d-%b-%Y Specify the date format to be applied when dealing with the documents
(if not provided the default %d-%b-%Y option will be used). The rules
for formatting are described in http://docs.python.org/lib/module-time.
html under “strftime” section

res_selection_con Resource selection condition for document generation, e.g.

d RES_OFFICE IN ('London', 'Rome'). In this example the documents will
be created only for the resources from the London and Rome offices.
This should be a valid SQL condition to be attached to the “where”
clause of the SQL statement.
bkg_hist_doc True Creates a document for each resource which lists the job he/she has
worked on as recorded in the Retain repository (any non-blank value
will perform the operation).
resource_doc True Creates a document for each resource which shows the data contained
in the resource table on the repository (any non-blank value will perform
the operation).
preferences_doc True Creates a document for each resource who has filled in one or more
preferences, representing them in a text document (any non-blank
value will perform the operation).
skills_doc True Creates a document for each resource which shows the information in
Details-> Skills section (any non-blank value will perform the operation).

38 38
 Administration

resume_folder Imports a list of files from a folder in the file system which represents
the resume/CV of a resource (any non-blank value will perform resume
import). With the default settings the filename needs to start with the
same string as the username used by the resource when connecting to
Retain Web. When multiple files match the username, only one is kept.
search_fieldname res_usrlogon Resource field based on which the match with the filename is
performed (must be set for the resume import).
regular_expr ^(\w+) Regular expression that describes the matching rule of the filename
with the specified resource field.
With the default settings of search_fieldname=res_usrlogon and
regular_expr=^(\w+) the resumes/CVs would be matched and imported
only if the filename starts with any of the resource logons.
filter_condition Filter_condition allows to delete imported resume/CV files based on a
condition. This should be a valid SQL condition to be attached to the
'where' clause of an SQL statement.

[security]
Writes the logical security rules of all the logical security profiles in the
repository to the file pointed by 'DUMP_SECURITY_FILE'.
load_security_file Reads the logical security roles from the text file pointed by '
LOAD_SECURITY_FILE' and imports them in the repository. If one of
the imported roles does not exist, it will create a new one; otherwise it
will update the existing logical rules.
fna_d_file Writes all the functional access values and roles contained in the
repository to the text file pointed by 'FNA_D_FILE'.
fna_file Reads the functional access roles and associated values from the '
FNA_FILE' text file and imports them in the repository. If a functional
access role does not exist, a new one is created; otherwise the
existing functional access values are overwritten with those imported.
Exports the table field information to the FLD_D_FILE file, where each
row corresponds to a record of the fld table. The fields should be
comma separated and the order of the exported fields should be
FLD_TBL, FLD_NAME, FLD_PRD_ID, FLD_ATTRIBUTE,
FLD_VALUE .
fld_file Imports the table field information from the 'FLD_FILE' text file, where
each row corresponds to a record of the fld table. The fields should be
comma separated and the order of the exported fields should be
FLD_TBL, FLD_NAME, FLD_PRD_ID, FLD_ATTRIBUTE,
FLD_VALUE .
These data can be exported through a text file from oracle database
using the following query, saving the output to a text file:
select fld_tbl||','||fld_name||','||fld_prd_id||','||fld_attribute||','||fld_value
from fld order by fld_tbl, fld_name, fld_attribute;
fld_d_condition fld_d_condition allows to specify an SQL condition for dumping field
information. This should be a valid SQL condition to be attached to the
'where' clause of an SQL statement.
[config]
log_config_file log_config.ini By default, the Retain Data Builder logging system is called log_config.
ini . This option allows to use another configuration filename.

39
 Administration

Logging Configuration File

The logging configuration file allows you to define where the logging information should be saved and which
level of verbosity is needed.

The logging facilities allow writing to one or more output media and with different levels of verbosity.

The default log ini file provides two outputs: one to the screen and one to a text file.

The section the users are most likely to be willing to change is the name of the file the log is written to, the
debug level and whether at each run a new file should be created or just appended to.

The section to modify in the ini file is [handler_base_handler].

The level option, by default level=DEBUG, will be quite verbose. The possible values that can be assigned are
INFO, WARN and ERROR. Messages in the log file will be written only if they meet or exceed the defined
level.

The option

args=('RetainDataBuilder.log', 'w')

allows you to change the file name by changing 'RetainDataBuilder.log' with the required destination
file.

The second string 'w'causes the log file to be overwritten at every run. It can be changed to an 'a' which will
cause the log file to only append data to an existing file.

40 40
 Appendices

5 Appendices
5.1 Configuration Files
ClntCnfg.ini

This configuration file resides on the client machines.

[CACHE]
· TABLENAME=CACHE SIZE (number of records)
The cache settings are normally not used (the cache is unlimited), although might be set for the BKG table
only.

[CONNECT]
· ProgressBar
When set to 1, Retain shows a progress bar while it is connecting.

[SECURITY]
· CONFIRMCHANGES
If set to 1, the user will be asked if he/she wants to save the changes made using Retain Security. If set to 0,
the changes will be saved automatically. The default value is 0.

[log]

· writelog
If set to 2, provides useful debugging information when Retain is not working or is running particularly slowly.

[ScenarioManager]
· AlwaysShowFilterArrow
When set to 1, the filter arrow next to column names in the Scenario Manager is always shown. When set to
0, the filter arrow is shown only when you move the cursor over the column name.

· ShowBkgFiltering
When set to 1, the filtering for scenario bookings in the Scenario Manager is enabled.

· BookingsViewSyncMode
When set to 1, the same filtering and settings are shown for all of the scenario bookings within the Scenario
Manager. When set to 0, each set of scenario bookings has a separate filtering and settings.

· UnselectAllAtStart
When set to 1, all the scenarios in the Scenario Manager are deselected by default.

· ShowCustomFiltering
When set to 1, shows the custom filters in the Scenario Manager. The default value is 1.

[DropDown]
· VisibleCompareMechanisms
This setting defines which linked field operators are enabled. The default value is 'Like,LikeCaseSensitive'.

To enable multiple operators, separate them by a comma. The possible values are:

41
 Appendices

- Like

- LikeCaseSensitive

- Equals

- NotEquals

- GreaterThan

- LessThan

- GreaterEquals

- LessEquals

[Wallchart]
· DisableDefaultNotebook
When set to 1, disables the Default notebook feature within Wallchart. The default value is 0, that is the 'Save
As Default Notebook' option is enabled.

Retain.ini

This configuration file is the local configuration for a single instance of Retain web application server module.
It determines which ports the server will listen on for connections and where to look for the RetainGlobal.ini
file.

Also, this file sets a limit to the number of threads which will be reserved for running the on demand and
scheduled reports.

[Global]
· cachedir
Represents the folder where the temporary cache used by the DLLServer module will be stored.

· globalconffile
UNC path to the RetainGlobal.ini file.
Example: \\note11\RWPGlobalArchive\Global Configuration\RetainGlobal.ini

· globalconffilebackup
UNC path to a backup version of the RetainGlobal.ini file, should the first path be unreadable.
Example: \\server2\RWPGlobalArchive\globalconf\RetainGlobal.ini

· globalsvrcnfg
This setting is currently not used.

· globalsvrcnfgbackup
This setting is currently not used.

· server
The alias of the RetainServer used to store and retrieve data from the repository. By default, an embedded
server in the form of a DLL is used to access the repository.
Example: DllServer

· webport
The TCP/IP port the server will listen on for new HTTP connections.
Example: 7777

42 42
 Appendices

· sslport
The TCP/IP port where the server will listen on for new HTTPS connection.
Example: 7778

RetainCalcFieldsGlobal.ini

RetainCalcFieldsGlobal.ini contains calculated field mappings used internally by the system. These calculated
fields should return either 'Y' or 'N' for True or False, respectively.

[CalcFields]
· IsViewable
IsViewable is used in the Planner, for JOB and RES records.

· IsSelectable
IsSelectable is used in all incremental drop-down controls. IsSelectable can be defined for any table.

· IsSearchable
IsSearchable is used in the Search Result.

· IsMyBRQAdmin
IsMyBrqAdmin is used to determine whether the user is a BRQ administrator.

· IsMyBRQAdminView
IsMyBrqAdminView is used in the Planner and this field is used to determine which BRQ records to display.

· IsAdminJob
IsAdminJob is used to determine whether the user is an administrator of a job.

· IsMyMgrJob
IsMyMgrJob is used to determine whether the user is a manager of a job.

· IsMgrDelegateJob
IsMyMgrDelegateJob is used to determine whether the user is a delegate manager of a job.

· ForecastIsMyJob
ForecastIsMyJob is used to determine whether a job is user's own job.

· ForecastAvailTimeNeg
ForecastAvailTimeNeg is used to determine available time that allows negative values.

· ForecastStdHours
ForecastStdHours is used to determine standard working hours for a resource.

RetainGlobal.ini

This configuration file determines the common behaviour and configuration of Retain application server
instances. It determines which authentication method to use and the URL it expects to receive as input (for
Retain Web), the fields which will be displayed and other general options.

For Retain Web, RetainGlobal.ini is usually stored on the Global Archive and shared between all the
application instances in order to minimise the file which will need updating when one or more settings need
changing.

For Retain Wallchart,

43
 Appendices

Note: some of the settings described below are edition specific and therefore may not be applicable/available
to you, depending on your setup.

[GLOBAL]
This section contains general settings regarding authentication, URL and behavioral models for both Retain
Web and Retain Wallchart.

· URLBase
This setting represents a URL path which should be added to the base links within Retain Web. When in
standalone mode, the setting should be left blank; however, when the application server instance is part of
a multi application server instance deployment, it should reflect the URL path of the Load Balancer module.
Example: /IWRetainWeb/IWISAPIRedirect.dll

· Server
The middle tier component to connect to in order to access Retain repository. Possible values are:

Dllserver
This is the default setting, and should be left as it is in normal circumstances.

HOSTNAME:PORT
Assuming that Retain Enterprise Server is running on a machine called RETENTSRV with IP address
192.168.100.100 on port 11450, the following entries 'RETENTSRV:11450’ or ’192.168.100.100:11450'
could be used to make Retain Web use it as the middle tier. Such usage is not advised nor supported by
Retain International Ltd; it could be useful only for debugging or testing.

· DefaultAdmin
Username, defined in Retain Security Manager, used to launch and use the Report sub-module for
scheduled reports.

· Authmethod
Defines how the user has to authenticate in order to use Retain Web.

dialog
When initially accessing the website the user is prompted with a dialog window where he has to enter
username and password.

siteminder
The user credentials are provided by Siteminder, Active Directory or any other integrated sign on software
that populates an HTTP Header with the authenticated username. When using Siteminder, the setting
SiteminderHeader is read in order to determine which HTTP_HEADERS contain the username of the user
trying to connect to Retain Web.

querystring
The user is authenticated by passing URL parameter in the format ?USER=username appended to the
URL used to access Retain Web.

· CmpLogo
The name of the file containing the company logo displayed at the top-right of every Retain Web page. The
file should be located in the Files\static\images folder.

· PrintCmpLogo
Logo used for print pages.

· MaxDropDownSize
The maximum number of entries which are retrieved and displayed in the drop down controls within Retain
Web.

· SessionTimeout
The number of minutes Retain Web will wait before closing the session of an inactive user.

44 44
 Appendices

· SendKeepAlive
If set, the browser will send a keep alive message to the server to keep the user logged on, when the user
is inactive for a long period of time.

· InitOnStartup
This setting should be left to its default value. It determines whether all the pages are initialised upon
connection to Retain Web (1), or only when a user clicks on a page for the first time (0).

· UseJAS
If set to 0, the assignment field will not be visible. If set to 1, it will be shown.

· UseTeams
This setting should be left to its default value.

· PWCMode
This setting should be left to its default value.

· ShowMessages
The value for this setting should be 1 for all non-debugging instances of the application server.

· UseFullWinWidth
This setting should be left to its default value of 1.

· CVLinkDownload
This setting should be left to its default value of 0.

· FloatDecimalDigits
This value determines the number of decimal places to use when displaying floating point numbers.

· FloatDecimalSymbol
Decimal symbol used for decimal numbers.

· FloatThouSeparator
Thousand separator used to display large numbers.

· TblHistFields
Comma separated list of tables that use specific drop down values based on the linked table.

· DownLoadFileExts
The list of file extensions that will be downloaded rather than displayed in the browser.
Example: .doc.xls.csv.ppt.zip.XLS.DOC.CSV.PPT.ZIP

· RememberLastPage
When set to 1, the user is directed to the last opened page when logging in the next time.

· CharCodePage
This setting is used when translating Unicode characters sent from the browser. The default is -1.

· XMLEncoding
This setting defines the encoding used when processing xml documents.

· LogoutText
The label of the 'log out' button in the browser.

· LogoutAction
The page to open when the 'log out' button is clicked on.

· ExcelExportExt
Sets the file extension for generated excel files that can be downloaded in the browser (e.g. xls).

45
 Appendices

· ShowWeekNumbers
If set to 1, week numbers are shown in Wallchart and Forecast (12 week) views within Retain Web. If set to
0, week numbers are not shown.
To make the week numbers visible, you need to also set the following values in the RtnConsts.js file
(located in 'WebPortal'-> 'Files'-> 'Static'-> 'js'
folder):
ShowWeekNumbers=true;
If set to 'False', the showing of week numbers is disabled.
RtnDateOffSet =1;
This specifies the day of the week your locale starts its week. Users in the U.S. would want to use 0,
while European users and those who
want to use the ISO 8601 standard, would use 1.

· AllowDefaultUser
If set to 1, default user profile can be used for logging in (allowing anonymous users to log on).

· UseMultiTabSelectionDropDown
If set to 1, displays the new selection drop-down within Retain Wallchart. The default value is 1.

[Demo]
· Demo
If set to 1, uses the demo mode. If set to 0 (which is the default value), the normal behavior is applied.

[TabNames]
This section contains the names of the main navigation pages in Retain Web.

JOBS_LINK=Jobs
RES_LINK=Individuals

[StartupSettings]
· LogonUserN
This setting shows the list of users that can be connected at startup and left open. This will save time for
users of the same type by keeping cached data open.

[PlannerComp]
This section contains the setting applicable to the Wallchart component within Retain Web.

· UseIsSelectable
When set to 1, adds the IsViewable calculated field condition to the booking query for the main view. So for
Jobs page it adds the IsViewable calculated field condition against the JOB table. The default value is 0.

· UseIsSelectableForProj
When set to 1, adds the IsViewable calculated field condition to the booking query against the project view.
Typically, for the job view this would be the RES table and for the resource view it would be the JOB table.

· MarkNonWorkStart=10 and MarkNonWorkEnd=16

Defines the threshold for non working time (in hours). Used to decide for what times non working time
should be marked.

· MarkNonWorkTimeMinRange=15
The interval used to check non working time (in minutes).

· EditMasterTbl

46 46
 Appendices

Defines the tables that will be listed in the 'Edit' and 'Actions' menus in the Wallchart view within Retain
Web. For example: EditMasterTbl1=RES, EditMasterTbl2=JOB, etc. Tbl1 will appear as the first row in the
drop down list, Tbl2 the second and so on. Note that only tables with _DESCR can be used.

· UseSingleId
Determines whether the name drop-down list is used as the view filter. If set to 0, the drop-down behaves
as the look-up menu.

· TemplatesVisible
Determines whether the view templates menu is visible.

· EditMenuVisible
Determines whether the 'Edit' menu is visible. It is called the 'Action' menu when the user does not have the
rights to edit 'master' records.

· AutoPersistState
When set to 1, the Wallchart settings are saved and applied automatically.

· HideMarkNonWorkNonRes
When set to 1, the option of marking non-working regions is hidden for the Job view.

· AlwaysSetSelectionOnSetTemplate
If set to 1, the default selection for the template is always applied when you switch to that template. If set to
0, the last applied selection will be used.

[BkgBarResource]
This section lists the fields which are displayed in the booking bars of the Wallchart component within Retain
Web.

· TableN
Defines the table from the Retain repository where the data is taken to populate the n-th field of the booking
bar.

· FieldN
Defines the field of the n-th table where the data is taken to populate the n-th field of the booking bar.

[BkgEditRule]
The settings in this section should be left to their default values.

[Jobs]
This section defines the Jobs page settings within Retain Web.

· ExtFieldN
The n-th additional field displayed in the Wallchart component in the Jobs page.
Example: ExtField1=JOB_CODE

· PlnSearchIncludeAll
When set to 1, makes all the selections visible for all the views. The default value is 0.

· AllowSetSelectionForTemplate
When set to 0, the users cannot define a custom selection as default for a view template.

[AvailJobs]

47
 Appendices

This section is currently not used but should be available in one of the following releases of Retain Web.

[Team]
· EscFieldN
The n-th field used in the key criteria section of a search.
Example: RES_INDUSTRY

· EscLookupN
The field used to retrieve the currently logged on resource's value of the n-th key criteria. This value will
differ from EscField, especially for linked fields where EscField could be a history field such as 'department';
while lookup could be CurrDep, a calculated field which returns the current department a resource belongs
to.
Example: RES_INDUSTRY

· EscSetOwnN
Determines whether the n-th field is set to the value of the currently logged on user or left blank. Can
assume the value of either 1 (for true) or 0 (false).

· EscAllowBlankN
Determines whether the n-th key criteria can be left blank, including all possible values in the search. Can
assume the value of either 1 (for true) or 0 (for false).

· EscAllowEditN
When set, the key attribute field can be edited by the user.

· EscIsMultiValN
When set, the key attribute field is a multi-value field.

[PrintableTabs]
Sets which pages that have a printable version, and sets the default js function to use to open them. Example:
JOBS_LINK=jobsPrintPlanner().

[JobSel_n] and [PeopleSel_n]

You can specify a default selection within the URL: http://hostname:Port/Files/static/html/webPortal.html?
selection=ressel1 where 'ressel1' is a selection that matches the 'Code' value in JobSel and PeopleSel
settings.

These sections define the default selection that will be applied to both Jobs and Individuals pages. For
example, if you want to have a default selection on London office for both pages, set the following values:

[JobsSel_1]
Name=London Office
Code=jobsel1
CalcField=JOB_OFFICE = 'London'
IsDefault=1

[PeopleSel_1]
Name=London Office
Code=ressel1
CalcField=RES_OFFICE = 'London'
IsDefault=1

· AlwaysRefreshIdList
When set to 1, refreshes the ID list on date range changes.

48 48
 Appendices

· IsDefault
When set to 1, this selection becomes the default selection for that view (unless otherwise specified in the
view template). If set to 0, the selection is not the default one.

You can add more selection filters on any other field by simply changing the selection number (and code
value). For example, if you want to have a second selection filter on Bristol office, you should add the
following settings:

[JobsSel_2]
Name=Bristol Office
Code=jobsel2
CalcField=JOB_OFFICE = 'Bristol'
IsDefault=1

[PeopleSel_2]
Name=Bristol Office
Code=ressel2
CalcField=RES_OFFICE = 'Bristol'
IsDefault=1

To apply a selection filter on one page only, define the appropriate setting (as well as the Code value): for
Jobs page, add a [JobsSel_n] setting and for Individuals page add the [PeopleSel_n] setting, where n is the
selection number.

[Testing]
· JSTest
JavaScript debug information flag. The value should be left as 0.

[DetailsExtLinks]
This section defines the settings for external links within Retain Web.

· count
The number of external links.

· LinkCaptionN
The caption for the n-th link.
Example: External Link

· LinkAddressN
The URL of the n-th link.
Example: www.extlnk.com

· LinkOpenInNewWindowN
Determines whether the n-th link will be opened in a new browser window.

· LinkVisibilityJsFuncN
The javascript Boolean expression that will determine if the n-th link is visible or not.

49
 Appendices

RetainHelpGlobal.ini

RetainHelpGlobal.ini contains file name mappings of help files. Help files are located in Files\static\help.

[help]
Jobs=jobs2.htm
People=jobs2.htm

RetainServersService.Ini

RetainServersService.Ini defines settings for RetainServersService.exe that will install Retain server as a
Windows service. This configuration file is located in the 'RetainServersService' folder.

[Settings]
· DisplayName
The display name of the Windows service that will be installed.
Example: RetainService

[General]
· CloseHung
If set to 1, closes down Retain Server when it is not responding.

· AppLocaleExe
Defines the path of the Applocale executable.
Example: C:\WINDOWS\AppPatch\AppLoc.exe

[Programs]
· p1
The path of the Retain server executable that you want running as a service.
Example: C:\ProgramFiles\RetainWebPortal\RetainServer\RetainServer.exe

[Language]
· p1
Defines the hexadecimal equivalent of the language parameter that is passed to Retain Server with
Applocale.
Example: 2057 for English (UK).

RetainStaticFileMappingGlobal.ini

RetainStaticFileMappingGlobal.ini contains file name mappings of javascript (located in Files\static\js) and css
files (located in Files\static\css).

[extfiles]
ContextMenu=ContextMenu.js
DateConvertions=DateConvertions.js
Details=Details.js
EventManager=EventManager.js

50 50
 Appendices

Forecast=Forecast.js
Jobs=Jobs.js
ListPlanner=ListPlanner.js
Lists=Lists.js
PrintSearch=PrintSearch.js
PrintView=PrintView.js
Prototype=prototype.js
Rico=rico.js
Reports=Reports.js
RetainJS=RetainJS.js
RtnActionBar=RtnActionBar.js
RtnContextMenu=RtnContextMenu.js
RtnDatePicker=RtnDatePickerClass.js
RtnDialogs=RtnDialogs.js
RtnHistCombo=RtnHistCombo.js
RtnMenu=RtnMenu.js
RtnSelections=RtnSelections.js
RtnWebGrid=RtnWebGrid.js
RtnWebPlanner=RtnWebPlanner.js
Schedule=Schedule.js
Search=Search.js
Summary=Summary.js
Teams=Teams.js
TeamSched=TeamSched.js
RtnSkills=RtnSkills.js
BookingDialogs=BookingDialogs.js
RtnControls=RtnControls.js
RtnDatePickerClass=RtnDatePickerClass.js
RtnSearchHighlight=RtnSearchHighlight.js
RtnConsts=RtnConsts.js
RtnEditDialog=RtnEditDialog.js
RtnBrqFuncs=RtnBrqFuncs.js
PrintLists=PrintLists.js
XmlSax=xmlSax.js
XmlSaxEventHander=preMadeSaxEventHandler.js
RtnExtWebGrid=RtnExtWebGrid.js
RtnReportGrid=RtnReportGrid.js
RtnPlannerPageFuncs=RtnPlannerPageFuncs.js
PrintPlanner=PrintPlanner.js
ListenerManager=ListenerManager.js
RtnCore=RtnCore.js

[cssfiles]
RetainSS=RetainSS.css
summary=summary.css
RetainSSPrint=RetainSSPrint.css

Rwplog.ini

Rwplog.ini contains different configuration options for logging on to Retain Web. The location of this file
should be the same as the global configuration file (RetainGlobal.ini). The settings include the location of the
log file and detail levels of the log.

The settings in this file should not be changed.

The output log file for Retain Web is Logs\RetainIWLog.log when using the standard Rwplog.ini file.

51
 Appendices

SvrCnfg.ini

Basic settings

For the first installation of Retain server you will only need to adjust the [Global] settings in SvrCnfg.ini. The
following example shows an Oracle database setting:

[Global]
DBDriver=DOA
DBName=Retain.World
DefaultUser=Retain
DefaultPassword=Retain

DBDriver
This will be the driver used for your database system. The Microsoft SQL Server driver is ADO_SQL and the
Oracle driver is DOA.

DBName
This will be one of the following:

· If you are using Oracle, this can be the name set up in the TNSNAMES.ORA file, e.g. Retain.World.

· If you are using SQL Server, this can be the name of the server machine. It can be the string
produced by server configuration tools which eliminate the need to specify the user and database
(you can then comment out the DefaultUser and DefaultPassword settings). Otherwise, the
DefaultUser and DefaultPassword are used.

DefaultUser
The user name assigned to database, e.g. Retain. If you are using SQL Server and
ADOConnectionString.exe/ServerCnfg.exe does not include the connection information, then this user must
have the Retain database set up as its default database.

DefaultPassword
The password assigned to the database, e.g. Retain.

Note: The DefaultUser and DefaultPassword entries must be commented out if you have used integrated
security in setting up your login to the database.

You should now be able to run Retain server and to test the connection to the database.

Further settings

· LogClientConnection=1
This setting records the user connections in the ULG table when set to 1.

· MaxStackTraceLength=0
Represents the stack trace level in the log table: 0 = No stack trace; 10 = 10 Lines; -1 = Unlimited.

· UpdateDiarySum
It is false by default. If false, does not populate the table and instead the user would probably want to run the
Update scripts. If true, the DGD_SUM table is populated by the Retain Server whenever a diary changes, and
also on start up. In larger deployments with multiple servers, it is recommended that this setting is applied to a
server that is used by administrators who could potentially change the diaries.

· UpdateDiaryDetail
It is false by default. If true, populates the DGD table when Retain Server is first started.

· CompressionThreshold
Sets the minimum threshold in bytes above which data packets are compressed. Compression does involve
extra server processing so there is a trade off between performance and bandwidth usage.

52 52
 Appendices

· MaxUsers
The maximum number of users allowed on to the database through Retain server at any one time.

· ThreadPoolCount
Maximum number of threads that Retain server will use to process concurrent requests. The default is 32
which will almost certainly be more than enough.

· ServerPort
The port number of the database server. The server will only run on the designated port and will not
automatically try the next port. It will fail to run if there is a server already running on the port.

Note the above information should be available from your database administrator. None of these settings
should require alteration after the initial set-up.

· BypassClientCalcPresence=1
By default, Retain performs a check for certain calculated fields before start up (the value is 0). You can
bypass this check by setting the value to 1, although it is recommended to leave it unchanged.

· ShowErrorMessages=0
The default vale is 0 and it means that errors will only be written to the log file. If set to '1', they will also
appear in a dialog.

· USEPWHTABLE=1
This setting encrypts passwords (which are then stored in the PWH table).

· FFASTRING=1=1
If set to 1=1, this setting grants full functional access to the users (within licencing restrictions), regardless the
set up in Security Manager. If set to 1=0, the users will be limited to the settings defined in Security Manager.
You can also specify certain IP addresses that will be allowed full functional access. For example:
FFASTRING=IPADDRESS='127.0.0.1'.

· AcceptDifferentCP
If set to 1, Retain does not perform a check whether Retain Wallchart has a different codepage to Retain
Server. The default value is 1.

[Compression]
Compression allows large amounts of data to be compacted before being sent across a network connection,
therefore reducing latency times.

· Threshold=100
To alter the compression level, change the number that follows 'Level=' to the desired setting (1 being the
minimum amount of compression and 9 being the maximum). This setting can vastly improve the speed of
Retain and should be left on its default of 1.

Additional settings

[DBConnect]
· MaxTries=5
This setting specifies the number of times Retain server will try to connect to the database (for Oracle only).
Five is the default value.

· RetryAfter=3000
This setting determines the time delay in minutes between the connections. The default is 3000.

[DATABASE]

53
 Appendices

· ForceRetrieveAll=1
This setting is for SQL Server database connections only. It reduces the SQL Server lock conflicts.

Note that Retain server can also be run with command line parameters which will override any settings in the
ini file.

· PORT
Specify the port that Retain server will run on.

· CONFIG
The full path of the configuration file (default is SvrCnfg.ini).

· ORACLEHOME
Oracle home directory, only required for multiple Oracle installations.

· OCIDLL
Oracle OCI dll. It defines the interface dll and should not be required in normal circumstances.

[Views]
· ShowAll=0
ShowAll will accept all views as tables. The default value is 0 (i.e. the setting is off). If ShowAll=0 then you
need to list all views you want the server to treat as tables. For example, RES=View

[Security]
· AcceptUserLogon=0
Determines whether you can accept a user name different to the network logon or not. The default is 0 (can
not accept). You would normally only enable this (by setting to 1) where passwords are implemented.

[Locale]
· SizeToNumCharsDivider=4
Defines how many bytes a character can represent for Retain Server. In this case, it will be four bytes.

Advanced settings

The settings below should not be changed without consulting with your Retain support provider.

Each Retain server reserves IDs for each table in blocks of 500 (by default) and uses them sequentially.You
can change this default (to 50 for example) but also override this default for specific tables, e.g. BKG:

[TableReserveBatch]
Default=50
BKG=100

Note that Retain does not recommend setting the default to 1.

[ScenarioClrSchMappings]
· Default=DefaultScenario
This setting changes the currently selected colour scheme but only if it corresponds to the name in the
mapping (e.g. 'Default'). If another colour scheme is selected, the setting will not be used. On the left
hand-side of the equation is the colour scheme used when scenario bookings are hidden and on the
right-hand side is the scheme that is used when scenario bookings are visible.

54 54
 Appendices

[ORACLE_SESSION]
· NLS_SORT=BINARY_CI
This setting is not enabled by default. If used, allows ‘Alter session’ commands to be sent to Oracle on
initialisation.

Servers.ini

This configuration file resides on the client machines. It contains information required by the Retain client to
connect to one or more Retain Servers. The syntax for this file is as follows:

[SERVER_ALIAS]
London=Server
Paris=Server

This section contains the list of servers that will be visible in the drop down list when users connect to the
database through any Retain client application.

For each server listed above, the connection information is provided. Each entry can have several servers
linked to it:

[London_1]
;Main server
Server1 = 10.20.30.8:8880

[London_2]
;Backup server
Server1 = 10.44.236.184:8760

[Paris_1]
;Multiple servers selected at random to spread the load
Server1 = 54.263.156.98:8880
Server2 = 10.144.36.14:8960
Server3 = 246.23.164.87:8900

Each group requires a minimum of one server and one port number. There are two different ways of defining
multiple alternative servers for a particular site.

In the example above, the London site has a main server and a backup server that should be used in the
order displayed. The order is defined by numbering the groups using the above syntax. In other words,
10.20.30.8:8880 will always be tried first but if it fails, the client will try 10.44.236.184:8760 next.

If more than one server is specified on a given number for a given site, Retain will randomly select one of the
servers to connect to and if unsuccessful, try the subsequent ones. This random selection balances the load if
there are multiple Windows NT servers pointing to the same database.

55
 Appendices

5.2 Hardware Specification

Introduction

This chapter outlines three examples of hardware configurations suitable for the deployment of Retain Web
for different levels of usage and fail-over safety.

The software and hardware required for the web application servers and the load balancer modules of a
deployment are described. It is assumed that a suitably sized and specified back-end database server is
available and in place.

· The first section illustrates the high level architecture of Retain Web and how this translates in a
deployment in terms of hardware required.
· The second section lists the database platforms supported.
· The third section presents the software and hardware specifications for a low-end deployment of Retain
Web with the end level usage of up to 100 concurrent users.
· The fourth section describes specifications for a medium-end deployment with the an end level usage of up
to 500 concurrent users.
· The last section presents specifications for a high-end deployment with the end level usage of up to 1,000
concurrent users.

The number of users registered within the deployment will usually be at least 5 times the level of concurrent
usage.

56 56
 Appendices

Retain Web Architecture

The following diagram illustrates the high level architecture of Retain Web and it is implemented in terms of
the final executable artifacts:

57
 Appendices

The three basic elements needed in a deployment are:

1. A database back end where the Retain Data Repository is stored.

2. A web application server which implements both the data access logic and the creation of the web content
presented to the end user.
3. A load balancer module which distributes the load of user sessions among a pool of application server
instances.

The application server module, composed by RetainWeb.exe and DllServer.dll binary artifacts can and should
be replicated on several running instances in order to shield the end user from one or more of them
encountering software or hardware failures.

The load balancing module can also be replicated on multiple server machines so that if one machine
encounters a hardware or software failure, the other one can guarantee a continued service to the end users.

How many instances of every module are deployed on a server machine and how many server machines per
module will be available in the deployment are variables that can be determined based on the end level of
usage and the level of fail-over safety required.

The three configurations presented in this document are intended as a guidance and not as the only possible
solution for the final deployment.

Database Requirements

The database platforms supported are:

· Oracle 9i
· Oracle 10g
· SQL Server 2005

As mentioned in the introduction section, the hardware specification and configuration for these database
servers need to match the end level of usage desired.

58 58
 Appendices

Deployment with up to 100 concurrent users

Description

This kind of deployment is intended to offer performance at a reasonable cost in terms of hardware and
software required.

The target concurrent usage should be at around 100 users and 500-800 resources registered against the
Retain repository.

The configuration for this kind of deployment is illustrated in the following diagram:

A single server PC hosts both the load balancer and application server modules which connect to the back-
end database server.

This deployment is simple to deploy, but it has a major defect in the lack of any fail-over strategy should a
hardware failure occur on the server.

Hardware and Software Specification

The single application server machine needed for this configuration should meet at least the following
specifications:

HARDWARE
SPECIFICATIONS
CPU Intel Pentium D 2.80 Ghz or higher specification
RAM 2 GB or higher specification
Hard Disk 80GB hard disk. No RAID technology advised or necessary, since persistence is
performed at the database level

59
 Appendices

SOFTWARE
SPECIFICATIONS
Operating System Windows Server 2003 Standard Edition (SP1, SP2 or R2)
Web Server Internet Information Services 6.0, No Extensions
XML Parsing MsXML 4.0 SP2, Microsoft XML Core Services
Database Connectivity Oracle client software for deployments based on a Oracle database back-end

Deployment with up to 500 concurrent users

Description

This kind of deployment is for both a higher number of concurrent users and an improved fail-over safety on
the application server side.

The target concurrent usage for this configuration is at around 500 users, with 2,000-3,000 resources
registered against the Retain repository.

The configuration for this kind of deployment is illustrated in the following diagram:

This deployment ensures that the deployment will continue to work even if one of the two servers hosting
RetainWeb application servers should have a software or hardware failure.

The single points of failure in this deployment are the load balancer module and the database server.

60 60
 Appendices

Hardware and Software Specification

This type of deployment requires 3 server machines, 2 of which host the web application server and 1 hosts
the load balancer.

Load Balancer Server Requirements (1 server required):

HARDWARE
SPECIFICATIONS
CPU Intel Pentium D 2.80 Ghz or higher specification
RAM 2 GB or higher specification
Hard Disk 60GB hard disk. No RAID technology advised or necessary, since persistence
is performed at the database level

SOFTWARE
SPECIFICATIONS
Operating System Windows Server 2003 Standard or Enterprise Editions (SP1, SP2 or R2)
Web Server Internet Information Services 6.0, No Extensions

Application Servers Requirements (2 servers required):

HARDWARE
SPECIFICATIONS
CPU 2 Intel Core Duo Processor at least 2.80 Ghz
RAM 4 GB or higher specification
Hard Disk 80GB hard disk. No RAID technology advised or necessary, since persistence
is performed at the database level

SOFTWARE
SPECIFICATIONS
Operating System Windows Server 2003 Standard or Enterprise Edition (SP1, SP2 or R2)
XML Parsing MsXML 4.0 SP2, Microsoft XML Core Services
Database Connectivity Oracle client software for deployments based on a Oracle database back-end

61
 Appendices

Deployment with up to 1000 concurrent users

Description

This kind of deployment offers the ability to serve a large user base and minimizes the downtime of the entire
deployment by replicating both the web application server and load balancing functionalities.

The target concurrent usage for this configuration is at around 1,000 users with 5,000 or more resources
registered against the Retain repository.

The configuration for this kind of deployment is illustrated in the following diagram:

This deployment configuration duplicates the functionality of the load balancing module as well. A prerequisite
for this functionality is to configure a round robin scheme on a DNS entry which points alternatively to the two
load balancers.

The only single point of failure in this deployment becomes the database server.

62 62
 Appendices

Hardware and Software Specifcation

This type of deployment requires six server machines:

· Four will host the web application server instances
· Two will host two separate instances of the load balancing module

Load Balancer Server Requirements (2 servers required):

HARDWARE
SPECIFICATIONS
CPU Intel Pentium Core Duo Processor at least 2.80 Ghz
RAM 2 GB or higher specification
Hard Disk 60GB hard disk. No RAID technology advised or necessary, since persistence is
performed at the database level

SOFTWARE
SPECIFICATIONS
Operating System Windows Server 2003 Enterprise Edition (SP1, SP2 or R2)
Web Server Internet Information Services 6.0, No Extensions

Application Servers Requirements (4 servers required):

HARDWARE
SPECIFICATIONS
CPU 4 Intel Core Duo Processor at least 2.80 Ghz
RAM 4 GB or higher specification
Hard Disk 80GB hard disk. No RAID technology advised or necessary, since persistence is
performed at the database level

SOFTWARE
SPECIFICATIONS
Operating System Windows Server 2003 Enterprise Edition (SP1, SP2 or R2)
XML Parsing MsXML 4.0 SP2, Microsoft XML Core Services
Database Connectivity Oracle client software for deployments based on a Oracle database back-end

5.3 Installation Checklists

This section of the administration guide is an aid to the technicians who will perform the deployment of Retain
Web in their organisation.

It provides a chronological list of the tasks which should be carried out before, during and after the
deployment in order to minimise the risks of faulty or incomplete configuration.

Hardware and File Locations Configuration

This should be a form that clients can fill in which describes which server machines they will use, their
specifications, hostname and ipaddress and what they will contain.

A first summary table should be provided to list the physical servers and their purpose; also possibly offer a
template to write for each server its specification, operating system and network data.

63
 Appendices

Deployment Checklist

Global Deployment Configuration

· Make sure the user that has access to the global archive from all instances used in the deployment, exists.
· All instances need to be able to see the location of the global archive.
· Edit the global deployment ini file:

[LOAD_BALANCER_SERVER]
- Correct machine count and host names in [LOAD_BALANCER_SERVER].
[APP_SERVER]
- Valid GlobalConfFile and GlobalConfFileBackup location.
- Correct host names.
[REPORT_SERVER]
- Valid host names and port numbers.

Database Configuration
· Create a new user/schema for the Retain Web deployment.
· Run the database creation script(s), logging the output and double checking no errors were detected.

Configuration Files Editing

SvrCnfg.ini
· Is the connection string and other database settings valid in SvrCnfg.ini?
· Is the CalculatedFields setting in SvrCnfg.ini valid?
· (SQL Server only) Verify that USEDBFUNCTIONS is set to 1 in SvrCnfg.ini?

RetainGlobal.ini
· Is the URLBase setting in the Global Configuration file correct (RetainGlobal.ini)?
· Are the calculated fields in the [CalcFields] section the required ones?
· Are the javascript files in the [ExtFiles] section the ones which are being deployed?

Application Servers Deployment

· Copy from the global archive and run the RWPDeployment.exe tool, which copies all the needed files to the
PC.
· Is only one Retain Web instance running the Report Scheduler as defined in Retain.ini?
· Is the location of the global archive valid in Retain.ini?
· Can all the application server machines access the global archive?
· Is Server.ini setup with a valid list of Retain Servers for Retain Enterprise Reports?
· Are the services for the RetainWeb.exe instances created? (One per instance is recommended as a single
instance can be restarted if needed).
· Are the services for the RetainServer.exe instances created?

Retain Security Manager Deployment

· Choose a server machine and folder where to copy Retain Security Manager and perform the operation.
· Does the Servers.ini file for Retain Security Manager contain a valid list of Retain Servers with port
numbers?
· Can you connect using Retain Security Manager to one of the Retain Server instances?
· Configure at least one user who can connect to Retain Web:
- Assign Functional Access.
- Assign Role Level or Logical Access.

64 64
 Appendices

Load Balancer Deployment

· Copy from the global archive and run the RWPDeployment.exe tool which copies all the needed files to the
PC.
· Is the registry setting needed for the shared memory manager correct?
· Is IIS configured correctly with a virtual folder and application pool?
· Is the load balancer dll added as an ISAPI extension in IIS?
· Are the static files loaded by the load balancer the correct version?
· Is the list of application servers and port numbers in Retainweb.ini valid?
· Is the httpuser header setting in Retainweb.ini set, if using a single sign on tool?
· Is the location of the log file correct in hclog.ini?

Startup/Shutdown Scripts Editing

· Are all the host names listed in ServiceStopStartGeneric.bat?
· Are all instances per host listed in startEntServers.bat and stopEntServers.bat?
· Has the startEntServers.bat file been scheduled to run after the stopEntServers.bat file?
· Has the stopEntServers.bat file been scheduled to run before the startEntServers.bat file?
· Are the two scheduled tasks, which run the start and stop batch files, running as a valid windows domain
user with access to the remote machines?

Startup Procedure
· Run the startup script, or follow the manual procedure:
- Start up all the RetainServer.exe instances.
- Start up all the RetainWeb.exe instances.
- Start up the RWPHCM service(s) of the load balancer module.
- Start up the IIS instance(s) which hosts the load balancer module.

Note: when a shutdown/startup procedure involves a hard shutdown or reboot of the hosting operating
system, make sure that the server machine hosting the global archive is up and running before you perform
any of the previously listed operations.

Shutdown Procedure
· Run the stopEntServer.bat file or follow the manual procedure:
- Stop the IIS instance(s).
- Stop the RWPHCM instance(s).
- Stop the RetainWeb instance(s).
- Stop the Retain Server instance(s).

Batch Processes Setup

· Make sure the required database tools are installed on the machine running the external database
processes.
· Has the RetainDataBuilder.exe process been scheduled to run once a day with the correct parameters?
· Has the UpdateSQL.bat file been scheduled to run once a day?
· (SQL Server only) Has the HTBFormat.exe process been scheduled to run?
· Are the scheduled tasks running as windows domain user who has access to the database utilities and
configuration files?

Checking the Deployment

· For each RetainWeb.exe in your deployment, double check the correctness of the following settings:
- SvrCnfg.ini: database connection and calculated field settings.
- Servers.ini: verify in the Cltcnfg.ini file which server alias the reports executable will user in order to
connect to the RetainServer.exe instances. Verify that the alias exists in the servers.ini file and that the server
entries correspond to instances of Retain Server which you have deployed and which are up and running.
- Retain.ini: check that only 1 instance has WorkerThread more than 0. Verify that the port numbers
are different for different instances of RetainWeb on the same computer.

65
 Appendices

· For Each RetainServer.exe listed in the servers.ini file present in the RetainWeb folders, check the Svrcnfg.
ini for its port number, database connection settings and calculated fields.

Running the installation

· Are all the application servers running after starting the services?
· Can you connect to the system using Retain Security Manager?
· Can you access the health check page of the Load balancer (http://serverip/IWRetainWeb/
IWISAPIRedirect.dll/healthcheck)?
· Can you connect to Retain Web with a web browser (http://serverip/IWRetainWeb/IWISAPIRedirect.dll/
Files/static/html/webportal.html)?
· Can you run reports from the Reports page in Retain Web?

Deployment Update Checklist

This checklist should be for occasions when one or more files of the deployment needs to be changed.

It might be useful to actually draw different checklists for different update scopes:

1. An update of static files only that needs no restart (images, js, html, rvs files).
2. An update of configuration files.
3. An update of executable files and files which will need a restart for the updates to be picked up.

66 66
 Support Services

6 Support Services
Support for Retain is available worldwide. This topic is linked to your support provider's information: Support
Service Provider.

retaininternational
USA phone: 1 646 688 4496
UK phone: 0845 458 8660
World phone: +44 20 7538 4774

USA fax: 1 646 478 9475

World fax: +44 845 458 8661

General E-mail: [email protected]

Support E-mail: [email protected]

Postal Address: Retain International Ltd

33 Beaufort Court
Admirals Way
London, E14 9XL
United Kingdom

67
 Index

hardware and file locations configuration

63
Index installation overview 6
-C-
Introduction 5
calculated fields
adding calculated fields 32
-L-
booking conflicts 34 load balancer
built-in calculated fields 33 installing load balancer 23
calcFields.cff 32 outage notification 25
calculated fields files 34 web authentication methods 26
calculated fields for diaries 34 -M-
company constants 35
multiple instances setup 17
companyConsts.cff 33
editing deployment settings 18
constants 32
file distribution 26
customisation 29
installing application servers 21
database independence 34
load balancer 23
define company 34
startup procedure 27
defineCompany.cff 32
fast time 34 -O-
introduction 29 outage notification 25
phonetics 35
-R-
pre-calculated fields 35
request economics 35 Retain Data Builder 36
rules for designing calculated fields 29 command line usage 36
scenarios 35 logging configuration file 40
security 35 setting the configuration file 38
team 35 Retain.ini 42
triggers 35 RetainCalcFieldsGlobal.ini 43
variance 36 RetainGlobal.ini 43
wallchart 36
RetainHelpGlobal.ini 50
ClntCnfg.ini 41
RetainServersService.ini 50
configuration files
RetainStaticFileMappingGlobal.ini 50
Retain.ini 42
RetainCalcFieldsGlobal.ini 43 Rwplog.ini 51
RetainGlobal.ini 43 -S-
RetainHelpGlobal.ini 50 Servers.ini 55
RetainServersService.ini 50
single instance setup 8
RetainStaticFileMappingGlobal.ini 50
database setup 8
Rwplog.ini 51
deployment tool 10
SvrCnfg.ini 52
installing application server 14
Contact information 67 installing services and external
processes 15
-G-
retain reports configuration 16
global deployment archive 7 security configuration 16
file categories 7
startup 16
folder structure 7
troubleshooting 17
-H- startup procedure
hardware specification troubleshooting 27
database requirements 58 Support
introduction 56 contact information 67
Retain Web architecture 57
SvrCnfg.ini 52
up to 100 concurrent users 59
up to 1000 concurrent users 62, 63 -V-
up to 500 concurrent users 60, 61 view templates 28
Help 67

-I-
installation checklists 63
deployment checklist 64
deployment update checklist 66

68