Note: prior to installing ServicePlanner on Microsoft Vista it is recommended that the reader refer to the appropriate section of the ServiceManager Administration Guide.

Integrating with ServiceManager

Whenever a ServiceManager module is installed, upgraded or uninstalled, the appropriate process must be followed as described in the following sections. The ServiceManager application will then need to be redeployed and restarted twice, see section 5.3 of [6], to ensure that the correct ServiceManager modules are fully installed and initialised.

Windows MSI Deployment

The MSI installation is a Windows only application. It presents the user with a standard Windows Installation User Interface providing the means for the user to configure the ServicePlanner installation to the needs on an individual customer/deployment.
The MSI installation is instigated by running the serviceplanner.msi application. The following section presents the key MSI dialogs presented to the user during installation, their meaning and expected user response.

Target Location

The ServicePlanner module must be placed in ServiceManager's modules directory. This will have been configured with ServiceManager's installation. If not, then ServiceManager's installer must be re-run first to establish the module directory.

Installation Process

The configuration of ServicePlanner is done through a single dialog: all other dialogs are for information only. The installer configures sufficiently to get a working system. However, ServicePlanner has a number of configuration parameters that are only defaulted in this process. These are described under section 4.2. In particular, if ServicePlanner is to be set-up with multiple geographies then FRU-geography mapping is required as described in section 4.2.2.3.

Currently the only configurable is the data directory. This is the directory in which data that describes each licensed geography dataset is placed. By default it is a directory called data that is placed under sm_properties. Accept the default unless the size of the data means that the geographic data must be placed somewhere else.

Ready to Install the Application

Upon completion of ServicePlanner's configuration details the application bundle can be installed. This final dialog presents an opportunity to either completely cancel the installation, or to return to some preceding dialog and update some of the information presented. Pressing the "Next" button here will automatically install ServicePlanner.

In order for the new files to be properly detected by ServiceManager the application will need to be redeployed and restarted twice, see section 5.3 of [6].

Registry Settings

The ServicePlanner installer places a number of entries in the registry under HKEY_LOCAL_MACHINE.SOFTWARE.ServicePower.ServiceManager.ServicePlanner.

Reconfiguring ServicePlanner Parameters after Installation

From within the MSI application it is possible to modify any/all of the installation parameters specified previously during the installation process.
Systems installed using the MSI application should use the MSI application to modify that system's parameters. Changes entered by any other means could lead to inconsistent behaviour of ServiceManager or ServicePlanner.

ZIP-Based Manual Deployment

ZIP-Bundle Contents

The ServicePlanner release comprises of a compressed (ZIP format) file containing the files that are needed to activate the ServicePlanner functionality of ServiceManager. This release is supplemented by a compressed (ZIP format) file for each purchased geography dataset. For each compressed file there is also, on Windows only, a corresponding MSI installer that provides an alternative means of installation.
Whether installing from the MSI application or from one of the provided ZIP files the resulting directory and file structure on the target machine will be the same. The main difference in installation of ServicePlanner between the MSI application and manual (ZIP) extraction is the requirement for the user to update individual configuration files after the extraction. The MSI applications use information that was supplied during the MSI installation of ServiceManager and requires no subsequent manual editing of these files.

Regardless of the installation method (MSI or ZIP file extraction) or target platform the following diagram represents the directory structure installed on the target machine. The top directory in this diagram must be placed in ServiceManager's modules directory.

Figure 2: ServicePlanner release contents

Where:

1. This is ServiceManager's modules directory which is called modules by default, although it is configurable.
2. This directory should be directly under ServiceManager's modules directory.
3. Geographic data is placed in this directory. There is typically one directory for each geography dataset that has been licensed. It should be noted that this directory is a ServicePlanner configurable and as such the person installing could place it somewhere else.
4. The existence of this file tells ServiceManager that the directory it is under, in this case geo, and all its contents and sub-directories are not to be copied into its deployment directory, as would otherwise happen.
5. The directory contains only a file called nocopy and exists only for the convenience of creating MSI installers.
6. This directory contains MapXtreme-licensed jar files that ServiceManager will copy to its web container deployment directory at run-time.

Manual Deployment Process

As described in the previous subsection, ServicePlanner release includes a ZIP file archive that contains the file necessary to activate the ServicePlanner functionality within ServiceManager. Whilst the software will require a degree of manual configuration the first step is straightforward - simply extract the contents into ServiceManager's modules directory. Once extracted, the ServicePlanner module needs configuring in order for it to operate correctly. Mostly this is setting properties in service_planner.properties. This file can be found alongside ServiceManager's properties file, service_manager.properties.
In order for the new files to be properly detected by ServiceManager the application will need to be redeployed and restarted twice, see section 5.3 of [6].

Geographic Data

The ServicePlanner release bundle has the directory ServicePlanner/data. Release bundles for each licensed geography dataset are placed in this directory (see 4.3). As the release schedule for geography datasets is independent of ServicePlanner, manual installers may find it more convenient to move the data directory to a location outside the root ServicePlanner directory. By doing so, it means that an upgrade of the ServicePlanner module can be achieved by simply deleting the root ServicePlanner directory and unzipping the upgraded release bundle without then having to re-unzip each geography release bundle.
Each geographic dataset will have a sub-directory called "properties" that will contain two files:

• <geo>.properties (e.g. uk.properties for the UK) which configures this geography for use by ServicePlanner. It should not be edited.
• <geo>.mdf (e.g. uk.mdf for the UK), which is a "Map Definition Format" file.

The .mdf file contains absolute file paths. To avoid predefining where the map data is to be located the .mdf files are distributed with the keyword GEOGRAPHIC_DATA_DIR at the beginning of all paths. Each .mdf file must have all instances of the keyword GEOGRAPHIC_DATA_DIR replaced with the path to the geographic data (the property map.data.root as defined in service_planner.properties).
IMPORTANT: do not make any other changes to these files.

FRU-Geography Mapping

ServicePlanner needs geographic data in order to create map images. Customers that operate in multiple countries may require multiple geographic datasets. In this case ServicePlanner needs to know which FRUs are associated with which geographic dataset. Customers that have only one geographic dataset will not need to provide an FRU-geography mapping.
# map.data.<geo>.fru - comma-separated list of responsibility unit refs for all
# the FRUs whose regions lie in the geography <geo>. <geo> is the name of
# the sub-directory of the geographic data under the directory map.data.root
map.data.canada.fru=WPEG,QBEC
map.data.ndl.fru=NL-1,NL-2
map.data.uk.fru=ENG,SCOT,WAL,NIRL
map.data.us_cbg.fru=CAL,WASH,ORI,NYK

Other Configurable Properties

There are a number of properties in service_planner.properties that can be changed that configure ServicePlanner's functionality. These are given below with a description as given in the properties file.
# layer.unit is the linear unit used for mapping. Can be mile, miles, km, kms.
layer.unit=mile
# jobdensity.days - the number of days that planner will by default look over
# when collating jobs to plot the density of.
jobdensity.days=14
# download.image.width, download.image.height is the width and height of the map
# image when planner is asked to create a printable map
download.image.width=2378
download.image.height=1682
# map.scale.default – the default minimum width/height of the map when trying
# to map a single location. The map can subsequently be re-scaled to higher
# and lower magnifications.
map.scale.default=5
# map.shade - semi-colon list of rgb colours that are used by planner to shade
# map areas
# map.line - semi-colon list of rgb colours that are used by planner to shade
# lines and text on the map
map.shade=255,0,0; 0,255,0; 0,0,255; 255,255,0; 255,0,255; 255,128,64
map.line=128,128,255; 162,0,192; 0,128,255; 0,255,255; 0,205,98

Installing Geographic Data

ServicePlanner can only work for countries where appropriate geographic data has been installed. There will be a release bundle (ZIP-format file or Windows MSI installer) for each geography dataset that has been licensed by the customer.

• For the ZIP-file, simply unzip the file into ServicePlanner's data directory. If this is updated data, then it is prudent to remove the old data first.
• For the Windows MSI installer, simply run the installer and click next on every window. The installer takes all its information from the registry. As for the ZIP-file installation, it is prudent to uninstall old data first if the installer contains updated data.

Configuring GPS for use in ServicePlanner

If ServicePlanner has been installed with geographic data, and a GPS service provider solution is available, then the GPS components for ServicePlanner can be configured. To configure the GPS locate the service_manager.properties file, this file will be found in the sm_properties folder of the ServiceManager installation directory.

The following entry will need to be added to the properties file:

gps.implAs=SOAP