Service Optimization
Spectrum GIS Adapter
Product ClickApp by ClickSoftware
For use with ClickSchedule
ClickSoftware Confidential
[DO NOT DELETE THIS NOTE: The following Legal Notice paragraph is formatted in white. It is invisible in the book and PDF editions, but it is converted to black in the online help.]
Legal Notice
The software with this guide is furnished under a license agreement and may be used only according to the terms of that agreement.
Copyright
Copyright © ClickSoftware Technologies Ltd. All rights reserved.
No part of this publication may be copied without the express written permission of ClickSoftware Technologies Ltd.
Patent and Trademark
US Patent Number 6,985,872 B2
ClickAnalyze, ClickFix, ClickForecast, ClickMobile, ClickPlan, ClickRoster, ClickSchedule, and ClickSoftware are registered trademarks of ClickSoftware Technologies Ltd.
Contact Information
Contact information is available from the ClickSoftware web site: http://www.clicksoftware.com.
For general information, email to .
For ClickSoftware Worldwide Support, email to or see the support page on the ClickSoftware web site.
For Partner Enablement, email to .
Publication Notice
This guide has been carefully compiled. The information in this guide does not constitute a warranty of performance. Furthermore, ClickSoftware reserves the right to revise this publication and make changes from time to time in the content thereof, without obligation to notify any person of such revisions or changes. ClickSoftware assumes no liability for losses incurred as a result of out-of-date or incorrect information in this guide.
Version
[DO NOT DELETE THIS NOTE: Add the app number when available.]
Spectrum GIS Adapter
App number: 1204
App version: 1.0
Date: April 2015
Spectrum GIS Adapter 3
Contents
Spectrum GIS Adapter 4
Use 5
Prerequisites 6
Hardware Sizing 6
Installation 7
Installing the Spectrum Technology Platform Server 7
Installing the Spectrum Client Tools 11
Installing the Geocoding Database 15
Installing the Mapping Data and Publishing the Maps 18
Installing the Routing Database 30
Installing the Spectrum GIS Adapter Runtime Files 32
Installing Cross-Domain Policy Component for Narrative Service 33
Configuration 36
Configuring Geocoding Options 36
Configuring the GIS Provider in Service Optimization 41
Comments 50
Spectrum GIS Adapter 49
Spectrum GIS Adapter
Spectrum GIS Adapter is a ClickSoftware app that integrates the Service Optimization server with the Pitney Bowes geographic information services running on the Pitney Bowes Spectrum Technology Platform. The app enables ClickSchedule to obtain geocoding, routing, narrative, and map services from Spectrum.
ClickSchedule web client displaying a Spectrum map
Zoomed view of the Spectrum map
Use
From Spectrum, ClickSchedule can obtain the following geographic services:
Geocoding
Determining the latitude-longitude coordinates of an address. ClickSchedule uses this service to determine the locations of tasks and engineers.
The Spectrum geocoding module provides the geocoding service to ClickSchedule.
Routing
Estimating the travel distance and time between two locations. ClickSchedule uses this service to minimize the travel between the engineer assignments.
The Spectrum routing module provides the travel estimates to ClickSchedule.
Narrative
Retrieving the driving directions between two locations, for example, between an engineer's current location and the next assignment.
The Spectrum mapping module provides the narrative to ClickSchedule.
Map
Displaying locations and routes on a map. The ClickSchedule web client displays assignments, tasks, and the engineer locations on the map.
The Spectrum mapping module supplies the maps to ClickSchedule.
The Spectrum services are equivalent to the services that ClickSchedule can obtain from other geographic providers, such as Pitney Bowes Envinsa or PTV xServer. For a comprehensive discussion of these services and of the geographic provider concepts, see the ClickSchedule GIS Configuration Guide.
Prerequisites
The Spectrum geographic information services are part of the Pitney Bowes Spectrum Technology Platform. To obtain the Spectrum and the geographic datasets, contact the ClickSoftware sales department.
[DO NOT DELETE THIS NOTE: Update for each release. The note is because we might forget.]
The Spectrum GIS Adapter is currently certified with Spectrum version 9.0 SP3.
Note: Before installing the Platform, consult with ClickSoftware Worldwide Support for updated version and patch information.
Hardware Sizing
For the system requirements of the Spectrum hosts, see the Pitney Bowes Spectrum Technology Platform Installation Guide.
The hardware requirements for Spectrum depend heavily on your ClickSchedule usage, for example, the number of tasks that you plan to process, and whether you require street-level routing for all the tasks. You might need a single Spectrum host, or you might need multiple hosts behind a network load balancer.
Before purchasing the host computers, consult with ClickSoftware for:
· An estimate of the GIS request rates, for example, the volume of map, route, and geocode requests
· The recommended number of Spectrum hosts
· The recommended host capabilities such as the number and type of CPUs, RAM, and disk space
Installation
The following sections explain how to install Spectrum.
Installing the Spectrum Technology Platform Server
For production use, you must install the Spectrum Technology Platform server on one or more dedicated hosts (not on the Service Optimization server host), or on the cloud.
The installation procedure is described in the Pitney Bowes Spectrum Technology Platform Installation Guide. The following steps are a summary.
1. Unzip the Platform installation file. The file has a name such as
CDQvvvrrr.zip
where vvv and rrr are version and release identifiers.
2. Double-click and run install.exe.
3. At the prompt, select the installation language.
This is the language of the setup program, not necessarily the language of the maps and narratives.
4. Click Next on the introductory pages until you are prompted for an installation location. The default location is:
C;\Program Files\Pitney Bowes\Spectrum
5. Select the modules to install:
Pitney Bowes Spectrum Technology Platform
You must select this component.
Enterprise Geocoding Module
This option installs the server software that is required for geocoding. In a later step, you will install the geocoding datasets.
To enable US geocoding, select Unites States of America. To enable geocoding in any other countries, select Global. Do not select the other options such as specific country names or World.
Location Intelligence and Routing Module
This option installs the server software that is required for routing, mapping, and narratives. In a later step, you will install the routing and map datasets.
6. If the host has Internet connectivity, do not install the online help.
Optionally, if the host is not connected to the Internet, install the online help for the benefit of Spectrum client users. Spectrum starts up more slowly if the online help is installed.
7. Accept the license agreement.
8. Designate the server port. The default value is 8080.
9. On the Access Keys page, make no entries and click Next.
ClickSoftware supplies Spectrum with a license key rather than access keys.
10. On the following pages, review the installation summary. Click Next to run the installation.
11. When the installation is complete, click Done.
This starts the Spectrum server. When the server is running, the notification area on the Windows task bar displays the following icon:
12. Copy the Spectrum license key (*.key) file that you received from ClickSoftware to the following location:
C:\Program Files\Pitney Bowes\Spectrum\server\app\import
If the import succeeds, Spectrum copies the *.key file to the following directory:
C:\Program Files\Pitney Bowes\Spectrum\server\app\import\archive
If the import fails, Spectrum copies the key file to the following directory. Contact ClickSoftware to resolve the problem.
C:\Program Files\Pitney Bowes\Spectrum\server\app\import\error
13. Stop and start the server.
You can do this by right-clicking the Spectrum icon in the notification area.
Installing the Spectrum Client Tools
The Spectrum client tools enable you to administer the Spectrum Technology Platform server. You need the client tools to install and configure the server and the geographic databases.
You can install the client tools on the same computer as the Spectrum server, on another computer, or on the cloud. Perform the following steps.
1. In a web browser, open the Spectrum Technology Platform Welcome Page:
http://SpectrumServerName:port
Replace the emphasized text with the host and port where you installed the Spectrum Technology Platform. By default, the port number is 8080.
2. In the left column, click the link to Platform Client Tools.
3. In the center pane click Platform Clients.
4. Click Download Installer.
5. Enter the Windows user name and password of a user that is authorized on the Spectrum host, and click Log In.
The client installer is downloaded.
6. Run the client installer by double-clicking setup.exe.
7. Enter the location in which to install the client. The default is:
C:\Program Files (x86)\Pitney Bowes\Spectrum Client Tools
8. Select all three clients.
9. Review the pre-installation summary, and click Install.
10. When the installation is complete click Done.
The setup places the following shortcuts on the desktop:
- Enterprise Designer
- Interactive Driver
- Management Console
Installing the Geocoding Database
You must install the geocoding data on the Spectrum server, and you must create one or more database resources containing the data for the countries you need. For example, a single database resource might contain the data for Mexico and Canada.
You can combine the data for up to approximately ten countries in a single database resource, with the following exceptions:
· The United States must be in a database resource by itself. Do not combine the United States with other countries in the same database resource.
· For Australia, Canada, France, Germany, and Japan, you should limit the database resource to two countries.
If you need more countries than this, you can create additional database resources.
To create a database resource, perform these steps:
1. On the Spectrum server host, unzip the database ZIP file that you received from ClickSoftware.
2. Run the *.exe file, and select the database to install.
This copies the data to the server.
3. On the host where you installed the Spectrum clients, click the icon to run the Management Console:
4. In the left pane, expand the tree and display the following node:
Modules/Tools
5. Under this node, select a set of resources.
In the illustrated example, we have selected the Global Database Resource, which contains data for the entire world except the United States.
6. Click the Add button.
This opens an Add Database Resource window.
7. Enter a name for the database resource, for example, Europe Geocoding.
8. Click Add and select the data for a single country. Configure the options as follows:
Name
A name for the database path, for example, United Kingdom.
Path
Click the browse button and select the folder that contains the country data. The path has the following format:
DatabaseLocation\IGEO-CountryCode\Version\data
DatabaseLocation is the path where you installed the database, CountryCode is a two-letter country code, and Version is the database version number.
9. Click OK.
10. Repeat steps 8 and 9 for each country that you want to add to the database resource, up to the limit described above.
Note: For more information about database resources, see the chapter Configuring Database Resources in the Spectrum Technology Platform Administration Guide.
Installing the Mapping Data and Publishing the Maps
To enable the map service, you must:
1. Install the mapping data on the Spectrum server.
2. Publish the maps.
3. Test the maps.
4. Publish the map tiles
5. Test the map tiles.
The following paragraphs provide the details of each step.
Note: Optionally, you can also install the maps on the client tools host. You can then use Pitney Bowes MapInfo Professional to edit the maps. For more information about this option, contact ClickSoftware.
Installing the Mapping Data
1. Copy the map files that you received from ClickSoftware to a folder on the Spectrum server.
The files include the map data for specific countries.
2. Open the folder, and run the start.bat file.
This opens a StreetPro window.
3. In the left pane, click Install.
4. At the prompt, specify the installation directory on the server.
The map data is installed in the indicated location.
5. The installed files include one or more *.mws files that define the maps. If you received any additional or updated *.mws files from ClickSoftware, copy them to the same installation directory.
Publishing the Maps
You must publish one or more maps based on the map data that you installed. For each map, perform the following steps:
1. On the host where you installed the Spectrum clients, open the Management Console.
2. In the left pane, expand the tree and select:
Location Intelligence/Tools/Named Maps
3. Click the Add button.
4. In the Add Named Map window, configure the following options:
MWS source
Click the browse button, browse to the directory where you installed the map data, and select the appropriate *.mws file, for example:
C:\PBBI\db\Maps\USA\us_seamless2015_adjusted.mws
Named map name
Enter a folder path and name for the map, for example, /Maps/US_Map.
Enter the path with forward slashes (/). The folder path is for display purposes in the Management Console.
Use inline tables
Select this option.
Local data path
Server data path
In both of these options, enter the directory path where you installed the map data. Copy the path from the MWS source, for example:
C:\PBBI\db\Maps\USA
5. Click OK.
This publishes the map.
Testing a Map
To test that a map has been installed and published correctly:
1. In a web browser, browse to the Spectrum Technology Platform:
http://SpectrumServerName:port
2. In the left pane, click the link to Spectrum Spatial.
3. Click the link to Sample Applications.
4. Under Web Application Samples, click Run Javascript Sample.
5. On the bottom left of the JavaScript Samples window, display the Credential tab, enter your Windows user name and password, and click Save.
6. At the top of the window, display the Mapping Service tab, and enter the following options:
Select Map
Select the map from the dropdown list.
Zoom Level (in miles)
Enter the map width in miles. The maximum value is 15000, meaning that the map spans a width of 15000 miles. Lower values zoom the map to display a smaller geographical area.
Projection
Enter the value epsg.4326.
Center(X), Center (Y)
Enter the latitude and longitude of the map center, in degrees. The coordinates must be a valid location on the map.
7. Click Render Map.
The right pane displays the map.
Publishing Map Tiles
After you install the map data and test the map, you must publish the map tiles. The procedure divides a map into small pieces that display quickly. The system combines the tiles as required to enable pan and zoom behavior.
For each map that you published, perform the following steps:
1. You must examine the file paths that are recorded in the *.mws file. Open the *.mws file in a text editor such as Notepad, and find the FileName elements. Verify the file path on the Spectrum server. For example, you might find the following path:
<FileName>C:\PBBI\db\Maps\USA\BonusData\canada.TAB</FileName>
If you installed the map data on disk D:, you must change the path to:
<FileName>D:\PBBI\db\Maps\USA\BonusData\canada.TAB</FileName>
2. On the computer where you installed the Spectrum clients, open the Management Console.