1. No category

Spatial Fusion Enterprise 5.9 Viewer
Reference Guide
CARIS
CARIS EMEA
(Global Headquarters)
115 Waggoners Lane
Fredericton, NB
Canada
E3B 2L4
Bremvallei 1
5237 LV 's-Hertogenbosch
The Netherlands
Phone: 1 (506) 458-8533
(English/French/Spanish)
Fax: 1 (506) 459-3849
Email: [email protected]
Assistance: [email protected]
Web site: www.caris.com
Phone: +31 (0)73 648 8888
Fax: +31 (0)73 648 8889
Email: [email protected]
Assistance: [email protected]
CARIS USA
CARIS Asia Pacific
415 N. Alfred Street
Alexandria, VA
United States
22314
Level 3 Shell House, 172 North Terrace
Adelaide SA 5000
Australia
Phone: 1 (703) 299-9712
Fax: 1 (703) 299-9715
Email: [email protected]
Phone: +61.(0).8.8231.9474
Email: [email protected]
May 2015
Trademarks owned by CARIS
This is a listing of USPTO-registered trademarks and trademarks owned by Universal Systems Ltd.
doing business as CARIS ("CARIS") and might also be trademarks or registered trademarks in other
countries. Please note that laws concerning use and marking of trademarks or product names vary by
country. Consult a local attorney for additional guidance. CARIS permits the use of its trademarks and
registered trademarks only where they are used in reference to CARIS and its products, the markings
used are appropriate to the country or countries of publication, and CARIS is explicitly acknowledged
as the owner of the mark. CARIS reserves the right to withdraw this permission at its sole discretion
for any use it feels is inappropriate or adverse to its interests. CARIS otherwise prohibits the use of any
of its registered symbols, insignia, or other identifying marks without express written approval.
Violations are subject to liability for damages, injunctive relief, attorney's fees and other penalties.
Not all trademarks used by CARIS are listed in this document. Failure of a mark to appear on this page
does not mean that CARIS does not use the mark nor does it mean that the product is not actively
marketed or is not significant within its relevant market. The absence of a product or service name or
logo from this list or the absence of a TM or TM Reg. USPTO notation against a product or phrase listed
below does not constitute a waiver by CARIS of its trademark or other intellectual property rights
concerning that name or logo.
The following are trademarks or USPTO-registered trademarks of CARIS:
•
•
•
•
•
•
•
•
•
•
•
•
•
Article 76 Module
Bathy DataBASE
Bathy DataBASE Server
BASE Editor
BASE Manager
BDB
CARIS
CARIS and EIVA Survey Suite
CARIS GIS
CARIS Notebook
ChartServer
CPD
Core Production Database
•
•
•
•
•
•
•
•
•
•
•
Easy View
EAM
Engineering Analysis Module
HIPS
HPD
HPD Server
Hydrographic Production
Database
Limits and Boundaries
Module
LIN
LOTS
LOTS Browser
•
•
•
•
•
•
•
•
•
•
•
•
•
LOTS Limits and Boundaries
LOTS Article 76
One Feature, One Time
Paper Chart Composer
Paper Chart Editor
Ping-to-Chart
Product Editor
Publications Module
S-57 Composer
SIPS
Source Editor
Spatial Fusion
Spatial Fusion Enterprise
Those trademarks followed by or footnoted as TM Reg. USPTO later in this document are registered
trademarks of CARIS in the United States; those followed by or footnoted as TM Reg. CIPO are registered
trademarks of CARIS in Canada; those followed by or footnoted as either TM Reg. USPTO and CIPO or
TM Reg. USPTO, CIPO are registered trademarks of CARIS in both the United States and Canada; those
followed by or footnoted as TM are trademarks or common law marks of CARIS in Canada and the
United States, and in other countries.
The trademarks and names of other companies and products mentioned herein are the property of
their respective owners.
Copyright owned by CARIS
All written and image content in this document not protected by the copyrights of others is © Copyright
2004, CARIS. All rights reserved. All reproduction and redistribution is strictly prohibited without the
express prior written consent of CARIS.
Copyright © 2015 CARIS. All rights reserved.
Table of Contents
1
About the Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
What is the Viewer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Spatial Fusion Viewer Requirements . . . . . . . . . . . . . . . . . . . . .
Installation Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Standalone and Standard Deployments. . . . . . . . . . . . . . . . .
Configuration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initial Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Update an Existing Installation . . . . . . . . . . . . . . . . . . . . . . . .
Terms Used in this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JRE Installation Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SFV Data Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tomcat Installation Directory . . . . . . . . . . . . . . . . . . . . . . . . .
Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
13
14
16
16
17
17
18
18
19
19
19
2
Preparing for Installation . . . . . . . . . . . . . . . . . . . . . . . . . 21
3
Installing Third-Party Applications . . . . . . . . . . . . . . . . . 31
Backing up Existing Configuration Data . . . . . . . . . . . . . . . . . . .
Configuration Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Standalone Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Possible Data Locations. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Backing up Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring Data Locations. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying the Configuration Directory . . . . . . . . . . . . . . . . . .
Restoring existing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Install Java Runtime Environment 8.0 . . . . . . . . . . . . . . . . . . . .
JRE Releases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating JRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JRE Installation file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Existing data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JRE Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Install Apache Tomcat 8.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cautions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tomcat Installation file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data directories and backup. . . . . . . . . . . . . . . . . . . . . . . . . .
Update of an Existing Tomcat . . . . . . . . . . . . . . . . . . . . . . . .
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring Tomcat Java Properties . . . . . . . . . . . . . . . . . . .
Restore Configuration Data . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting and Stopping Tomcat . . . . . . . . . . . . . . . . . . . . . . . .
Robots (protection from indexing) . . . . . . . . . . . . . . . . . . . . .
22
22
22
22
26
27
27
28
32
32
32
33
33
33
34
34
34
34
35
35
35
45
49
49
50
5
4
Deploying CARIS Spatial Fusion Viewer . . . . . . . . . . . . 51
5
Basics of the Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
6
Map Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
7
6
Deploy Spatial Fusion Viewer 5.8 . . . . . . . . . . . . . . . . . . . . . . . . 52
Opening the Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . .
Forgot your password?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interface Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SFE Viewer Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SFE Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
58
64
66
66
68
70
Data Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Add Data Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Edit Data Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Delete Data Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
POI Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
What is a POI? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Creating a POI Connection . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Where and how to get POI connection URLs. . . . . . . . . . . . . 81
Using Photo and Video web feeds for POIs . . . . . . . . . . . . . . . . 83
Using a WFS to display POIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Mashup Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
What is a Mashup?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Creating a Web Services Mashup . . . . . . . . . . . . . . . . . . . . . 89
Creating a POI Mashup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Add Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Edit Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Delete Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Add/Edit Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Delete Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Add Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Edit Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Delete Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
104
104
107
108
109
111
113
8
A
General Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Default Language Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
English Map Examples (default). . . . . . . . . . . . . . . . . . . . . .
French Map Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Spanish Map Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Servlet Container Logs. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
116
116
117
117
118
120
121
121
121
122
123
125
Advanced Technical Notes . . . . . . . . . . . . . . . . . . . . . . 127
Configuration Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Apache Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Caching with Apache Web Server . . . . . . . . . . . . . . . . . . . .
HTTP Compression on Apache Web Server . . . . . . . . . . . .
Apache Tomcat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tomcat Deployment Option . . . . . . . . . . . . . . . . . . . . . . . . .
Change the Database Port. . . . . . . . . . . . . . . . . . . . . . . . . .
128
129
129
130
133
133
138
B
Authenticate with LDAP. . . . . . . . . . . . . . . . . . . . . . . . . 139
C
Working with a Standalone Deployment . . . . . . . . . . . 149
D
Web Services Optimization . . . . . . . . . . . . . . . . . . . . . . 157
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enable LDAP Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . .
Use LDAP Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Disable LDAP Authentication . . . . . . . . . . . . . . . . . . . . . . . . . .
TCP/IP and Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
References: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Standalone and Standard Deployments . . . . . . . . . . . . . . . . . .
Standalone Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuration for a Standalone Deployment . . . . . . . . . . . .
Migrating to a Standard Deployment . . . . . . . . . . . . . . . . . . . .
Backing up a Standalone Deployment . . . . . . . . . . . . . . . . .
Migrating the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Optimization Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring Data Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Minimize Calls to Data Source . . . . . . . . . . . . . . . . . . . . . . .
Configuring Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
140
142
144
148
150
150
151
152
152
153
153
154
158
159
160
160
162
7
8
E
Monitoring User Connections with Apache Server. . . 165
F
Secure Sockets Layer . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Tracking users in Apache HTTPD Server . . . . . . . . . . . . . . . . . 166
View active sessions using Apache Tomcat . . . . . . . . . . . . . . . 167
Secure Sockets Layer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Securing a Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Connecting to Secured Servers . . . . . . . . . . . . . . . . . . . . . . 171
1
About the Installation
In this chapter...
WHAT IS THE VIEWER? ................................................. 10
SPATIAL FUSION VIEWER REQUIREMENTS ......................... 13
INSTALLATION NOTES .................................................... 14
TERMS USED IN THIS GUIDE........................................... 18
About the Installation: What is the Viewer?
What is the Viewer?
CARIS1 Spatial Fusion2 Enterprise™ Viewer is a tool for
displaying geospatial data over the Internet or a local network
using standard Web browsers (such as Mozilla Firefox® or
Microsoft® Internet Explorer).
The the web application is controlled by the Viewer Manager.
With the Viewer Manager you can:
• Create data connections to the following services:
• Web Map Service (WMS),
• Web Map Tile Service (WMTS),
• Web Feature Service (WFS), and
•
Web Coverage Service (WCS).
• Create POIs using:
• Keyhole Markup Language (KML), or
• GeoRSS_SIMPLE.
• Create Themes using the layers in data connections.
• Create Users and Roles, and assign roles to users.
• Define settings for the web application.
• View application and service logs for the web application.
• Update the web application license.
1. This term is a trademark of CARIS (Universal Systems Ltd.), Reg. USPTO & CIPO.
2. This term is a trademark of CARIS (Universal Systems Ltd.), Reg. USPTO.
10
CARIS Spatial Fusion Viewer Reference Guide
About the Installation: What is the Viewer?
The following diagram shows the relationship between Spatial
Fusion Server and Spatial Fusion Viewer.
CARIS Spatial Fusion Viewer Reference Guide
11
About the Installation: What is the Viewer?
The following diagram shows the various data formats that can
be used in the web application.
12
CARIS Spatial Fusion Viewer Reference Guide
About the Installation: Spatial Fusion Viewer Requirements
Spatial Fusion Viewer Requirements
Before you install Spatial Fusion Viewer (the web application),
your computer must meet or exceed the following minimum
system requirements:
• Operating System: Windows Server® 2008 Release 2 or
Windows Server 2012.
• Processor: 1.4 GHz or better (x64 processor)
• Memory: 2 GB of RAM or more
• Software:
• Apache Tomcat 8.0 as of SFE Viewer version 5.8.12.
(Versions 5.8.0 to 5.8.11 require Apache Tomcat 7.0.)
• Java Runtime Environment 8.0
Geospatial data processing can be intensive. There are many
factors that can affect server response time. Some strategies for
improving response time include:
• Install Spatial Fusion Server, Spatial Fusion Viewer, Bathy
DataBASE™ and its database (Oracle or PostgreSQL)
separately on dedicated hardware to distribute the network
load.
• A network speed of 1 GBit/s or higher will reduce any input/
output constrictions and improve speed.
• Multiple instances of Tomcat can be effective in improving
response time. Further suggestions for improving response
time are described in “CONFIGURATION DATABASE” ON PAGE 128".
CARIS Spatial Fusion Viewer Reference Guide
13
About the Installation: Installation Notes
Installation Notes
If you have data connections configured, the configuration files should be
backed up before removing the applications, as described in “BACKING UP
EXISTING CONFIGURATION DATA” ON PAGE 22.
The web application can reside on the same computer on which Spatial Fusion
Server is installed. If server response time becomes an issue, the two
applications can also be installed on separate Java VM instances or even
separate systems.
If you have a previous version of the web application installed,
configuration data will need to be backed up to a safe location,
and restored where the new installation will find it. These
procedures are described in “BACKING UP EXISTING CONFIGURATION DATA”
ON PAGE 22.
The applications listed below are required for a complete
installation. It is important to select the correct 32 or 64 bit
version of the Java Runtime Environment (JRE bundle).
CARIS recommends that the applications are installed in the
sequence shown below:
Sequence
Software
Configuration Notes
1
Java Runtime
Environment
(Server JRE
bundle) 1.8
The Server JRE bundle can be used for 64 bit
operating systems. Version 1.8 is also known as
version 8.0.
2
Apache Tomcat
8.0
3
Spatial Fusion
Viewer
Each one of these applications is installed separately.
All three applications can be installed by downloading the
installation files from their respective web sites.
The web application is contained in a web application archive
file (WAR file).
There are two downloads available from CARIS:
• Spatial Fusion Viewer 5.8 WAR file
• Documentation zip file updated for the release (optional)
The downloads are available after logging in to this page:
http://support.caris.com
The web application can be installed by copying a downloaded
WAR file to the appBase directory. By default, the appBase
directory is the [Tomcat installation
14
CARIS Spatial Fusion Viewer Reference Guide
About the Installation: Installation Notes
directory]\webapps directory. See “TOMCAT INSTALLATION
DIRECTORY” ON PAGE 19 for more information.
There are special requirements for copying this file that must be
observed. For more information about these requirements see
“DEPLOY SPATIAL FUSION VIEWER 5.8” ON PAGE 52.
The web application WAR file must be given the file name
“spatialfusionviewer.war” unless you are configuring a standalone installation,
as described in “STANDALONE AND STANDARD DEPLOYMENTS” ON PAGE 16.
Please go to the web sites below to get the latest version of the
Java Runtime Environment and Apache Tomcat:
Software
Web link
JRE (Server JRE
bundle, 64 bit only)
http://www.oracle.com/technetwork/java/javase/downloads/serverjre8-downloads-2133154.html
Apache Tomcat
http://tomcat.apache.org/download-80.cgi
Spatial Fusion Viewer http://support.caris.com
The following minimum versions of Java Runtime and Apache Tomcat are
recommended:
• For 64 bit operating systems: JRE 8.0 or higher
• Tomcat 8.0 or higher
CARIS Spatial Fusion Viewer Reference Guide
15
About the Installation: Installation Notes
Standalone and Standard Deployments
The the web application WAR file is embedded with Tomcat.
This permits two methods of installation:
• Standalone: the web application can be installed without first
installing Tomcat. This type of installation is best suited to an
initial install without any pre-existing data connections. The
standalone installation procedure is described in CARIS SPATIAL
FUSION VIEWER QUICK START GUIDE.
• Standard: the web application can be installed after Apache
Tomcat.
Data from a standalone installation can be migrated to a
standard deployment, as described in “BACKING UP DATA FROM A
STANDALONE DEPLOYMENT” ON PAGE
28
If a standalone and a standard Tomcat have both been installed on the same
computer, only one Tomcat should be running at any time, unless the database
port number for one of the web application installations has been changed as
described in “CHANGE THE DATABASE PORT” ON PAGE 138.
Since the default database port is the same for both installations of the web
application, stopping one Tomcat will prevent confusion and problems in the
database access.
Most of the remaining content of this document applies to
standard deployments, except when indicated otherwise.
Configuration Options
If you are updating from an earlier version of the web
application, system administrators may wish to update the
installed version of Java Runtime Environment and Apache
Tomcat to take advantage of possible bug fixes or enhancements.
Reference to these web sites is made in the appropriate sections
of this guide.
Administrators may need to make configuration changes to
make the installation of the web application run effectively.
Factors such as other applications, connection speed, amount of
data, hardware limitations, and the number of instances of
Spatial Fusion Server and Viewer all affect how the software
should be configured.
Administrators are encouraged to use all the guides for the
software to optimize their installations.
16
CARIS Spatial Fusion Viewer Reference Guide
About the Installation: Installation Notes
Initial Installation
The installed location for the application has the following
structure:
http://localhost:8080/spatialfusionviewer/
Unless this value is modified during the installation, the default
Hypertext Transfer Protocol (HTTP) port to which Apache
Tomcat’s HTTP connector is bound is 8080.
The default account setup for the web application includes only
one account:
Module
Username
Password
Spatial Fusion Viewer
admin
password
Update an Existing Installation
In version 5.7.4 and higher, an option in the Tomcat Java
settings can be used to define a data directory specifically for the
web application. Defining a dedicated directory will make
backups and software updates simpler.
• Finding and backing up existing data is described in “BACKING
UP
EXISTING CONFIGURATION DATA” ON PAGE 22
• Instructions for defining a dedicated directory is described in
“CONFIGURING DATA LOCATIONS” ON PAGE 27.
• Restoring data is described in “CONFIGURING DATA LOCATIONS” ON
PAGE 27.
CARIS Spatial Fusion Viewer Reference Guide
17
About the Installation: Terms Used in this Guide
Terms Used in this Guide
JRE Installation Directory
The Java Runtime Environment (JRE) Installation Directory is
the location in which JRE is installed. The JRE Installation
Directory is the directory that contains the bin and lib
directories of the JRE distribution.
The use of a compressed archive distribution to install JRE is
described in this guide. If the JRE distribution is version 8
update 5 and the compressed archive is decompressed directly to
C:\JRE
The JRE Installation Directory would be similar to:
C:\JRE\jdk1.8.0_40\jre
If the JRE_HOME environment variable is set it should have
the same value as the JRE Installation Directory. See “SET
JRE_HOME VARIABLE” ON PAGE 133 for instructions on how to create
this environment variable.
18
CARIS Spatial Fusion Viewer Reference Guide
About the Installation: Terms Used in this Guide
SFV Data Directory
The SFV Data Directory is the location in which SFS will store
cached data, configuration data and files related to metadata.
The default location of the directory is the temporary directory
("temp") used by Tomcat. The location can be configured using
the com.caris.sfv.dir Java option, for example:
-Dcom.caris.sfv.dir=C:\Tomcat_SFViewer_data
See “CONFIGURING TOMCAT JAVA PROPERTIES” ON PAGE 45 for more
information.
Tomcat Installation Directory
The Tomcat Installation Directory is the location in which
Tomcat is installed. When using the Windows installer
distribution of Tomcat, the default location will be
C:\Program Files\Apache Software Foundation\Tomcat 8.0
This can be changed during installation. There are other
methods of installing Tomcat and different configurations that
can be used. The installation directory can vary as a result.
Web Application
"The web application" means Spatial Fusion Viewer in this
guide.
CARIS Spatial Fusion Viewer Reference Guide
19
About the Installation: Terms Used in this Guide
20
CARIS Spatial Fusion Viewer Reference Guide
2
Preparing for Installation
System administrators have options for specifying where data files should
be located. By knowing what these options are, existing data can be
located and backed up. Options for defining new data locations and
copying existing data to these locations can result in reduced effort in the
future for backups and software updates.
In this chapter...
BACKING UP EXISTING CONFIGURATION DATA ................... 22
CONFIGURATION DATA .................................................. 22
STANDALONE INSTALLATION ............................................ 22
POSSIBLE DATA LOCATIONS ........................................... 22
BACKING UP DATA ....................................................... 26
CONFIGURING DATA LOCATIONS ..................................... 27
SPECIFYING THE CONFIGURATION DIRECTORY ................... 27
RESTORING EXISTING DATA............................................ 28
Preparing for Installation: Backing up Existing Configuration Data
Backing up Existing Configuration Data
This section describes a number configuration changes that may
have affected where data for the web application are located on
your computer. This information may also be useful in helping
you to plan possible changes for data locations to simplify
backing up data and making software updates in the future.
Configuration Data
The web application uses a database to record configuration
settings such as:
• data connections,
• theme configurations,
• settings on the Settings page,
• role configurations, and
• user configurations, including any LDAP users if LDAP has
been configured. (The admin user is generated by the
program and is not contained in these files.)
In the case of an initial installation without any previous
connections, there will be no existing data to back up.
Standalone Installation
Backing up and migrating data from a standalone installation to
a standard deployment of the web application is described in
“BACKING UP DATA FROM A STANDALONE DEPLOYMENT” ON PAGE 28.
Possible Data Locations
The default location for the Spatial Fusion Viewer configuration
database (or "SFV data directory") is in “SFV DATA DIRECTORY” ON
PAGE 19.
Customized Service
Name
However, the location of both the Tomcat Installation directory
and the Tomcat "temp" directory may have been affected if you
customized the Windows Service Name during the installation
process. For example, if you named the service "Webserver", the
location of the data directory would be:
C:\Program Files\Apache Software Foundation\Tomcat
8.0_Webserver\temp
and the Tomcat Installation directory would be:
22
CARIS Spatial Fusion Viewer Reference Guide
Preparing for Installation: Backing up Existing Configuration Data
C:\Program Files\Apache Software Foundation\Tomcat
8.0_Webserver\
Viewing Java Properties
Some Java Properties set in Tomcat can affect the location of
data storage. The Java Properties can be viewed to determine
where your data is located. A description of how to view the Java
Properties is located in “CONFIGURING TOMCAT JAVA PROPERTIES” ON
PAGE 45. A description of the Java Properties that can affect data
location is included below.
Options available in
Versions 5.5.x to 5.7.3
In previous versions of the web application, one customization
may have been used. The java.io.tmpdir Java property may
have been set to define the default location for all Tomcat data.
If you did not use this setting, your data should be in the default
location, which is usually:
C:\Program Files\Apache Software Foundation\Tomcat 8.0\temp
If your data is not in this location you will need to check the
Tomcat Java settings to determine the directory location defined
by this setting. Options for this location are described below.
Directory options for
Versions 5.7.4 and
higher
The java.io.tmpdir Java property has been available for a
number of versions of Tomcat, but there is an additional option
available in version 5.7.4 and higher, for customizing the data
location.
The com.caris.sfv.dir property can be set in the Tomcat
Java properties. This setting affects the location of the
configuration database, and nothing else. If the
com.caris.sfv.dir property is not set, the configuration
database defaults to the location of the java.io.tmpdir
property described above. If the com.caris.sfv.dir property
is set, only the configuration database for Spatial Fusion Viewer
uses the directory defined by this Java property, and the
configuration database directory will be kept separate from any
other data. If it is located outside the Apache Tomcat
installation, the data will be unaffected by updates to Tomcat.
Apache Tomcat must have permissions to use the directory set in the
com.caris.sfv.dir property.
Setting the com.caris.sfv.dir property can affect the behaviour of other
applications deployed to the same Tomcat instance, so System Administrators
should be aware of this before making any modifications.
CARIS Spatial Fusion Viewer Reference Guide
23
Preparing for Installation: Backing up Existing Configuration Data
Determining the
directory locations
You can determine what the directory locations will be for the
configuration database once you determine the values for all the
relevant Java properties:
• the com.caris.sfv.dir Java property
• the java.io.tmpdir Java property
• the context name, which is the file name portion of the
WAR file.
In the directory locations that follow, placeholders are used to
represent the elements of the directory locations:
Placeholder
Meaning
<java.io.tmpdir>
The value of the java.io.tmpdir java setting.
The default value is often C:\Program
Files\Apache Software Foundation\Tomcat
8.0\temp
In version 5.5.0 and higher this value can be set in
the Java Properties. See “CONFIGURING TOMCAT JAVA
PROPERTIES” ON PAGE 45 for more information.
<com.caris.sfv.dir>
The value of the com.caris.sfv.dir java
setting. If this value is not set, or if this directory is not
created, it will take the value for the
java.io.tmpdir Java setting.
This Java property is only available in version 5.7.4
and higher. See “CONFIGURING TOMCAT JAVA
PROPERTIES” ON PAGE 45 for more information.
<context>
The file name of the WAR file
For example, "spatialfusionviewer" would be
the context with respect to the
spatialfusionviewer.war file.
If the file name of the WAR file is anything but
"spatialfusionviewer.war", you must use the
configuration techniques described in “ADVANCED
TECHNICAL NOTES” ON PAGE 127.
The configuration database location is indicated for different
versions of the web application below, with placeholders that you
can use to determine the directory location. The highest level
directory is indicated below, but the configuration database is
actually contained in a directory within the highest level
directory.
24
Version of Spatial Fusion Viewer
Configuration Database Directory
5.5.0 to 5.7.3
<java.io.tmpdir>\CARIS\<context>
5.7.4 or higher
<com.caris.sfv.dir>\database\<context>
CARIS Spatial Fusion Viewer Reference Guide
Preparing for Installation: Backing up Existing Configuration Data
Example of version
5.7.3 database location
For example, in a version 5.7.3 installation in which
java.io.tmpdir is set to the default value of
C:\Program Files\Apache Software Foundation\Tomcat 8.0\temp
the web application configuration database would have
placeholder values of:
<java.io.tmpdir> = C:\Program Files\Apache Software
Foundation\Tomcat 8.0\temp
<context> = spatialfusionviewer
and the resulting configuration database storage location would
be:
C:\Program Files\Apache Software Foundation\Tomcat
8.0\temp\CARIS\spatialfusionviewer
Example of aversion
5.7.4 database location
In a version 5.7.4 installation in which com.caris.sfv.dir is set
to C:\Tomcat_SFViewer_data, the configuration database
would have placeholder values of:
<com.caris.sfv.dir> = C:\Tomcat_SFViewer_data
<context> = spatialfusionviewer
and the resulting configuration database storage location would
be:
C:\Tomcat_SFViewer_data\database\spatialfusionviewer
CARIS Spatial Fusion Viewer Reference Guide
25
Preparing for Installation: Backing up Existing Configuration Data
Backing up Data
The only directory that needs to be backed up is the
configuration database directory as described above in
“CONFIGURATION DATA” ON PAGE 22 (see as well “SFV DATA DIRECTORY” ON
PAGE 19).
Before installing version 5.8, it is a good precaution to back up
this data directory by copying it to a safe location. You may wish
to back up data on a regular basis, or before making any system
changes, so that you can restore to an earlier point in time in the
event of a problem.
26
CARIS Spatial Fusion Viewer Reference Guide
Preparing for Installation: Configuring Data Locations
Configuring Data Locations
It is not necessary to apply custom values to change the location
where your data will be stored, but making such changes may
make future data backups and update installations easier. As
long as the existing data directory is backed up, it can be copied
to the new location.
Configuration for a
standalone WAR
The embedded Tomcat in a standalone WAR file is preconfigured. Migrating data from a standalone deployment to a
standard deployment of the web application is described in
“BACKING UP DATA FROM A STANDALONE DEPLOYMENT” ON PAGE 28.
Most of the remainder of this chapter discusses configuration for
a standard deployment of the web application.
Specifying the Configuration Directory
After installing Tomcat, the default Java Properties must be
edited to define a number of memory settings as described in
“CONFIGURING TOMCAT JAVA PROPERTIES” ON PAGE 45 (See also “SFV DATA
DIRECTORY” ON PAGE 19). In that section, there is a complete sample
set of Java Properties that may be appropriate for many
situations. The two lines in that sample file that define the
directory locations are included below:
-Djava.io.tmpdir=C:\Tomcat_Other_data
-Dcom.caris.sfv.dir=C:\Tomcat_SFViewer_data
The java.io.tmpdir property is applicable to the Java Virtual Machine
instance. Modifying this location will not have any negative side-effects on other
applications running within the same Tomcat. Whatever directory that is
specified will be used by all applications for working with temporary files.
Apache Tomcat will create the directory defined in the Java Properties if it does
not already exist.
Apache Tomcat must have permissions to use the directories set for these
properties.
If the above properties were set, the behaviour would be:
• Non-CARIS data will be stored in: C:\Tomcat_Other_data
(and this directory will become the Tomcat "temp" directory)
CARIS Spatial Fusion Viewer Reference Guide
27
Preparing for Installation: Configuring Data Locations
• Data will be stored in: C:\Tomcat_SFViewer_data
If these directories are not appropriate for your situation, you must delete or edit
these lines in the sample Tomcat properties provided in this guide.
The data you wish to use must be present in the directories specified by these
Java properties. If it is not present, an empty configuration database will be
created. To recover from an empty configuration database, see “RESTORING
EXISTING DATA” ON PAGE 28.
Restoring existing Data
Any data that you want the web application to use must be
present in the appropriate location defined in the Java
Properties.
If directory locations have been changed, the data should be
copied to the new location.
If it is not in the location that the web application expects to find
it, the web application will create an empty configuration
database and there will be no data connections, maps, or users
(other than admin). If that situation develops, you can correct
the problem using this sequence:
1. Log out of the web application.
2. Stop Tomcat.
3. Find and delete the empty configuration database directory.
4. Copy the previous data directory to the correct location.
5. Start Tomcat.
6. Start the web application.
Backing up data from a
standalone deployment
28
Backing up and migrating a standalone configuration is
discussed in “BACKING UP A STANDALONE DEPLOYMENT” ON PAGE 153.
CARIS Spatial Fusion Viewer Reference Guide
Preparing for Installation: Configuring Data Locations
CARIS Spatial Fusion Viewer Reference Guide
29
Preparing for Installation: Configuring Data Locations
30
CARIS Spatial Fusion Viewer Reference Guide
3
Installing Third-Party Applications
In this chapter...
INSTALL JAVA RUNTIME ENVIRONMENT 8.0....................... 32
INSTALL APACHE TOMCAT 8.0 ........................................ 34
Installing Third-Party Applications: Install Java Runtime Environment 8.0
Install Java Runtime Environment 8.0
This chapter assumes you are using a 64 bit operating system for your
installation.
JRE Releases
The correct version of the JRE that supports version 5.8 of the
web application is known as both 1.8 and 8.0. There may be a
number of updates, any of which should be compatible with
Spatial Fusion Viewer 5.8.
It is not important to install every update of the JRE. However,
system administrators should update whenever there are bug
fixes, security fixes or additional functionality that may enhance
performance. The web site documentation for the JRE may be
helpful in providing information to assist system administrators
in making that decision.
http://www.oracle.com/technetwork/java/javase/documentation/index.html
At time of writing, Java 8.0 release notes were available at this
location:
http://www.java.com/en/download/faq/release_changes.xml
or by searching the Oracle web site for release notes for the JRE
at:
www.oracle.com
Updating JRE
If Apache Tomcat has already been installed, it must be stopped before the JRE
is installed or updated. If this step is not taken, Apache Tomcat will frequently
fail to start properly. See “STARTING AND STOPPING TOMCAT” ON PAGE 49
If the JRE has already been installed with Tomcat running, see “CAUTIONS”
ON PAGE 34.
32
CARIS Spatial Fusion Viewer Reference Guide
Installing Third-Party Applications: Install Java Runtime Environment 8.0
JRE Installation file
The Server JRE bundle tar.gz file for Java Runtime Environment
can be found at this location:
http://www.oracle.com/technetwork/java/javase/downloads/server-jre8downloads-2133154.html
Existing data
The JRE installation will not affect existing data, but a backup
is always a good precaution. For further information See “DATA
DIRECTORIES AND BACKUP” ON PAGE 35.
It is a good precaution to check whether there are any other applications using
an installation of the JRE before removing it to complete an update.
JRE Installation
To install the Server JRE bundle follow the procedure described
below.
1. Obtain the Server JRE bundle tar.gz file. See “JRE INSTALLATION FILE” ON
PAGE 33 for more information.
2. Follow the instructions for unpacking the Server JRE bundle tar.gz file,
located at
http://docs.oracle.com/javase/8/docs/technotes/guides/install/
windows_server_jre.html#A1097054
You may need to unzip the tar.gz file twice on a Windows operating system to
unpack the files, first to create a .tar file, and then to extract the uncompressed
files and directories.
3. Make note of the JRE Installation Directory.
You will need it to install Apache Tomcat. For more
information about the JRE installation directory see “JRE
INSTALLATION DIRECTORY” ON PAGE 18.
After the Java installation process is complete you can install
the next support application, or the web application if all other
applications are installed.
• to install Apache Tomcat, see “INSTALL APACHE TOMCAT 8.0” ON
PAGE 34, or
• to install CARIS the web application, See “DEPLOY SPATIAL FUSION
VIEWER 5.8” ON PAGE 52.
CARIS Spatial Fusion Viewer Reference Guide
33
Installing Third-Party Applications: Install Apache Tomcat 8.0
Install Apache Tomcat 8.0
Prerequisites
The Java Runtime Environment 8.0 (Server JRE bundle) must
be installed before Apache Tomcat. There will be an installation
error if Tomcat cannot locate the JRE. See “INSTALL JAVA RUNTIME
ENVIRONMENT 8.0” ON PAGE 32 for more information.
Cautions
The default Port of 8080 is normally used for Apache Tomcat 8. If a different port
is required, the settings can be modified during or after installation.
If the JRE has already been uninstalled with Tomcat running, the JRE may not
have been cleanly removed. You may be able to resolve the situation by
following these steps:
1. Stop Tomcat.
2. Reboot.
3. Install the JRE.
4. Start Tomcat.
For further information on starting and stopping Tomcat, see “STARTING
STOPPING TOMCAT” ON PAGE 49.
AND
The Apache Tomcat documentation may be helpful in providing information
about configuring your installation. It is located at http://tomcat.apache.org/
tomcat-8.0-doc/index.html
Tomcat Installation file
The Apache Tomcat 8 installation program can be obtained by
downloading it from the following web site:
http://tomcat.apache.org/download-80.cgi
You will need to download the installation program before the
installation can proceed.
34
CARIS Spatial Fusion Viewer Reference Guide
Installing Third-Party Applications: Install Apache Tomcat 8.0
Data directories and backup
In the case of an initial installation without any previous data
connections, there will be no existing data to migrate.
You have the option of choosing a location for your configuration
data as described in “PREPARING FOR INSTALLATION” ON PAGE 21. This
chapter covers options available for configuring data directories
and backing them up.
Before installing version 5.8, it is a good precaution to back up existing data, as
described in “BACKING UP EXISTING CONFIGURATION DATA” ON PAGE 22.
Update of an Existing Tomcat
If other applications are using Tomcat they will become unavailable if Tomcat is
stopped. You should refer to their documentation with respect to updating
Tomcat before proceeding.
If you have an existing version of Apache Tomcat installed, and
you wish to update to Tomcat 8, follow these steps:
1. Stop Tomcat.
See “STARTING AND STOPPING TOMCAT” ON PAGE 49 for more
information.
2. Backup existing data.
See “DATA DIRECTORIES AND BACKUP” ON PAGE 35 for more information.
3. Navigate to the Windows Add or Remove Programs utility, and use it to
remove the existing installation of Apache Tomcat.
4. Follow the steps for installation of Apache Tomcat.
See “INSTALLATION” ON PAGE 35 for more information.
Installation
To install Apache Tomcat:
1. Click the installation program file for Apache Tomcat 8.0.
CARIS Spatial Fusion Viewer Reference Guide
35
Installing Third-Party Applications: Install Apache Tomcat 8.0
The following dialog box is displayed.
2. To start installing Tomcat, click Next.
36
CARIS Spatial Fusion Viewer Reference Guide
Installing Third-Party Applications: Install Apache Tomcat 8.0
The License Agreement dialog box is displayed.
3. Read the agreement carefully. If you accept the terms, click I Agree
and the installation will continue. If you do not accept the terms, click
Cancel and the installation will terminate.
CARIS Spatial Fusion Viewer Reference Guide
37
Installing Third-Party Applications: Install Apache Tomcat 8.0
The Component Selection dialog box is displayed.
4. If desired, expand the Tomcat section by clicking the + symbol.
38
CARIS Spatial Fusion Viewer Reference Guide
Installing Third-Party Applications: Install Apache Tomcat 8.0
The default values are normally acceptable:
• Adding the Service Startup component permits Tomcat to
start as a service automatically on startup. If you do not
check this item you will always need to start Tomcat
manually after the system is rebooted.
• The Manager item is not needed in most cases.
5. Check or uncheck the desired options.
6. Click Next.
Connector Port
The Configuration dialog box is displayed.
If you customize the Windows Service Name, the customized name results in
changes to the default names of directories containing data. See “CUSTOMIZED
SERVICE NAME” ON PAGE 22 for more information.
If you are restoring existing data during an upgrade of Tomcat, it is important to
check the location of data directories to ensure that the data will be placed
where Tomcat will recognize it. See “BACKING UP EXISTING CONFIGURATION
DATA” ON PAGE 22 and “CONFIGURING DATA LOCATIONS” ON PAGE 27 for more
information.
The new directory names may also affect the Java settings for Tomcat. See
“SPECIFYING THE CONFIGURATION DIRECTORY” ON PAGE 27 for more information.
CARIS Spatial Fusion Viewer Reference Guide
39
Installing Third-Party Applications: Install Apache Tomcat 8.0
Windows Service Name
7. Enter a customized service name if desired.
8. If the default port is not correct, enter the correct port number.
The default ports are shown. If they are not correct for your
installation you may need to change these values.
9. Enter your Tomcat user name and password.
If you have installed the Tomcat manager application, it is recommended that
you change the user name and password at this time for security reasons. If you
should happen to forget them, they can be discovered by looking at the
Tomcat\conf\tomcat-users.xml file.
10.Click Next.
40
CARIS Spatial Fusion Viewer Reference Guide
Installing Third-Party Applications: Install Apache Tomcat 8.0
The Java Virtual Machine dialog box is displayed.
11. Click the Browse (...) button and select the directory where JRE
Installation Directory .
See “INSTALL JAVA RUNTIME ENVIRONMENT 8.0” ON PAGE 32 or “JRE
INSTALLATION DIRECTORY” ON PAGE 18 for more information.
12.Click Next.
CARIS Spatial Fusion Viewer Reference Guide
41
Installing Third-Party Applications: Install Apache Tomcat 8.0
The Install Location dialog box is displayed.
13.[Optional] To select a different directory for the application, click
Browse, select the directory to use and click OK.
The directory in which Tomcat is installed is known as the Tomcat Installation
Directory, and you will need to know its location for the web application
installation process. See “TOMCAT INSTALLATION DIRECTORY” ON PAGE 19 for
more information.
14.Click Install.
42
CARIS Spatial Fusion Viewer Reference Guide
Installing Third-Party Applications: Install Apache Tomcat 8.0
The resulting dialog box shows the progress of the installation
process (as the application files are copied to your machine).
When the application files are copied, the buttons at the bottom
of the dialog box become active.
15.To continue after the files are installed, click Next.
CARIS Spatial Fusion Viewer Reference Guide
43
Installing Third-Party Applications: Install Apache Tomcat 8.0
The final dialog box of the Tomcat installation wizard is
displayed.
16.Uncheck the Run Tomcat check box.
You will need to modify the startup settings for Apache Tomcat to run the web
application. If Tomcat is running, it will need to be stopped and started before
the customized startup settings will take effect.
17.[Optional] To display Tomcat’s Readme file after closing the wizard,
leave the check box for this action selected.
18.To close the installation program for Apache Tomcat 8.0, click Finish.
If you are updating Tomcat in an existing installation, you will need to update the
Tomcat Java settings and redeploy the previous WAR file. See “SPECIFYING THE
CONFIGURATION DIRECTORY” ON PAGE 27, “CONFIGURING TOMCAT JAVA
PROPERTIES” ON PAGE 45 and “WEB ARCHIVE FILES” ON PAGE 53.
Depending on your configuration, you may also need to restore data to the
location that has been configured, as described in “RESTORING EXISTING DATA”
ON PAGE 28 and “CONFIGURING DATA LOCATIONS” ON PAGE 27.
44
CARIS Spatial Fusion Viewer Reference Guide
Installing Third-Party Applications: Install Apache Tomcat 8.0
Configuring Tomcat Java Properties
It is necessary to adjust the settings in Apache Tomcat so that the web
application will run properly. If Tomcat is not already stopped, you will need to
stop and start Tomcat, as described in “STARTING AND STOPPING TOMCAT” ON
PAGE 49 after editing the Tomcat Java Properties.
Data locations and Java Properties affecting them are described in “PREPARING
FOR INSTALLATION” ON PAGE 21. All other Java Properties are discussed in this
section.
As you review the Java Properties below you will need to ensure
that the correct directory locations are entered for the data
directory.
1. Open the Apache Tomcat Properties application by clicking the Start >
All programs > Apache Tomcat 8.0 > Configure Tomcat Menu
sequence.
The following interface will appear:
CARIS Spatial Fusion Viewer Reference Guide
45
Installing Third-Party Applications: Install Apache Tomcat 8.0
2. Click the Java tab.
46
CARIS Spatial Fusion Viewer Reference Guide
Installing Third-Party Applications: Install Apache Tomcat 8.0
3. Scroll to the bottom of the Java Properties
The addition of following Java Properties will probably work in
most situations. They will set up custom directories on C: drive
for both the web application, and default Tomcat data, which
you may need to edit. See “POSSIBLE DATA LOCATIONS” ON PAGE 22 and
“SPECIFYING THE CONFIGURATION DIRECTORY” ON PAGE 27 for more
information.
If the directories for Spatial Fusion Viewer, Spatial Fusion Server, or other
applications running on the same instance of Tomcat are different from your
previous installation, you will need to copy your existing data to the new
location(s) in order for the applications to use it.
-Xms128m
-Xmx256m
-Dcom.caris.sfv.dir=C:\Tomcat_SFViewer_data
Apache Tomcat will create the directories if they do not already exist.
The lines repeated below may help to optimize your installation:
-Xms128m
-Xmx256m
CARIS Spatial Fusion Viewer Reference Guide
47
Installing Third-Party Applications: Install Apache Tomcat 8.0
These settings are optional. They control the amount of memory
that is used by the JVM (Java Virtual Machine). The values are
provided to indicate an initial starting point. The appropriate
values for your system may differ and can be determined only
through a process of performance analysis.
Other settings for Tomcat may also be important for your configuration. See
“POSSIBLE DATA LOCATIONS” ON PAGE 22 and “SPECIFYING THE CONFIGURATION
DIRECTORY” ON PAGE 27.
The Apache Tomcat documentation may be helpful in providing information
about configuring your installation. It is located at http://tomcat.apache.org/
download-80.cgi
4. Edit the Tomcat Java Options appropriate for your installation in the
Java Options text box.
5. Click OK.
If Tomcat is running, you will need to stop Tomcat, as described in “STARTING
AND STOPPING TOMCAT” ON PAGE 49 before starting the web application. The new
settings will not take effect until Tomcat is started.
The Apache Tomcat installation process is complete. Unless
there are data files to restore, Tomcat can be started.
48
CARIS Spatial Fusion Viewer Reference Guide
Installing Third-Party Applications: Install Apache Tomcat 8.0
Restore Configuration Data
Configuration data should now be copied to the data directory
specified in the Tomcat Properties, if it is not already there. The
options for such configuration are described in “BACKING UP EXISTING
CONFIGURATION DATA” ON PAGE 22 and “CONFIGURING DATA LOCATIONS” ON
PAGE 27.
You can now install the web application if all other applications
are installed. For instructions, see “DEPLOY SPATIAL FUSION VIEWER 5.8”
ON PAGE 52.
Tomcat can now be started.
Starting and Stopping Tomcat
It is a good precaution to check whether there are any other applications using
an installation Apache Tomcat before stopping it.
You can test the Tomcat installation by starting and stopping
Apache Tomcat from Windows Services:
Start Tomcat
Stop Tomcat
1. Select Start > Control Panel > Administrative 1. Select Start > Control Panel > Administrative
Tools > Services > Apache Tomcat.
Tools > Services > Apache Tomcat.
2. Select Start—Tomcat becomes operational. 2. Select Stop—Tomcat closes.
If Tomcat is not listed in the Services menu, you may need to reboot your
computer or use the Start > All Programs > Apache Tomcat > Monitor Tomcat
menu sequence first.
You should wait until Tomcat has finished loading before
checking any applications, which may take several minutes,
depending on the speed of your computer.
If the JRE has already been uninstalled with Tomcat running,
the JRE may not have been cleanly removed. Tomcat will often
fail to start, and generate log entries such as these:
java/lang/NoClassDefFoundError
java/lang/Object
You may be able to resolve the situation by following these steps:
1. Stop Tomcat.
2. Reboot.
3. Install the JRE.
4. Start Tomcat.
CARIS Spatial Fusion Viewer Reference Guide
49
Installing Third-Party Applications: Install Apache Tomcat 8.0
For further information on starting and stopping Tomcat, see
“Starting and Stopping Tomcat” on page 46.
See “INSTALL JAVA RUNTIME ENVIRONMENT 8.0” ON PAGE 32 and “INSTALL APACHE
TOMCAT 8.0” ON PAGE 34 for more information.
Robots (protection from indexing)
If you are setting up the web application for use by internet
connection, you should block robot applications from indexing
your site.
1. Select the [Tomcat installation path]\webapps\ROOT directory or, if
using an Apache / Tomcat combination, the root pages directory.
2. In the current directory, create a file called robots.txt.
3. Add the following settings to the file:
User-agent: *
Disallow: /
4. Save the file.
Now, robot applications will not be allowed to index your site.
50
CARIS Spatial Fusion Viewer Reference Guide
4
Deploying CARIS Spatial Fusion Viewer
This chapter describes the steps for deploying the web application.
Deploying CARIS Spatial Fusion Viewer: Deploy Spatial Fusion Viewer 5.8
Deploy Spatial Fusion Viewer 5.8
Prerequisites
Before the web application can be deployed, the following
applications must be installed:
• Java Runtime Environment 8.0, and
• Apache Tomcat 8.
Both of these applications should be installed before proceeding
further with the installation of the web application. Failure to do
so will result in configuration problems.
Documentation files
A zip file of documentation to support the web application is
available from the CARIS Customer Services web page at:
http://support.caris.com/
The zip file contains:
• CARIS SPATIAL FUSION VIEWER 5.8 CHANGES LIST,
• CARIS SPATIAL FUSION VIEWER HELP GUIDE EN.PDF (English),
• CARIS SPATIAL FUSION VIEWER HELP GUIDE ES.PDF (Spanish),
• CARIS SPATIAL FUSION VIEWER HELP GUIDE FR.PDF (French).
CARIS SPATIAL FUSION VIEWER REFERENCE GUIDE (this document), and
•
CARIS SPATIAL FUSION VIEWER QUICK START GUIDE.
The CARIS SPATIAL FUSION VIEWER HELP GUIDE is also available from the
Help links of the application, depending on the language and
role you are logged in under.
• The CARIS SPATIAL FUSION VIEWER REFERENCE GUIDE opens from the
Help link if you are logged in as admin.
Sample data
No sample data is installed or configured as a part of this
deployment.
Deployment files
The file that contains the web application is called a “WAR” file,
described in “WEB ARCHIVE FILES” ON PAGE 53. The WAR file for the
web application can be downloaded from the CARIS Customer
Support web site after logging in to this page:
http://support.caris.com/
52
CARIS Spatial Fusion Viewer Reference Guide
Deploying CARIS Spatial Fusion Viewer: Deploy Spatial Fusion Viewer 5.8
Web Archive Files
A WAR file is a web application archive file with a file extension
of "war". It is used to provide the web application for Apache
Tomcat to deploy.
The the web application WAR file is normally renamed to
“spatialfusionviewer.war” unless you are configuring a standalone
deployment, as described in “STANDALONE AND STANDARD DEPLOYMENTS” ON
PAGE 16.
When a WAR file is placed in the Tomcat webapps directory
while Tomcat is running, Tomcat will expand the archive by
creating a directory that contains the expanded files. The high
level directory will have the same name as the WAR file. This
process starts immediately when the WAR file is deployed in the
Tomcat webapps directory. It can cause configuration problems
if Tomcat is stopped or the WAR file is deleted until the process
of creating the directory is complete, which can take several
minutes.
Tomcat can run multiple WAR files. The only restriction is the
same as an OS: the file names must be unique within a
directory. However, configuration of Tomcat and system
resources becomes very important with multiple instances of the
web application or Apache Tomcat on the same computer. For
example, it is important to configure the ports correctly at the
OS level.
For further information, see
• “CONFIGURING TOMCAT JAVA PROPERTIES” ON PAGE 45,
• “SPECIFYING THE CONFIGURATION DIRECTORY” ON PAGE 27,
• “ADVANCED TECHNICAL NOTES” ON PAGE 127, and
• Apache Tomcat documentation.
A WAR file can also be deleted by an administrator, and Tomcat
will respond by deleting the matching directory, a process that
can take several minutes depending on system resources and
loads. Stopping Tomcat while it is in the process of this deletion
can cause problems.
Deploying or deleting WARs while Tomcat is stopped can create problems. It is
safest to let Tomcat deploy or delete directories on its own.
• If Tomcat fails to delete or deploy directories automatically,
try stopping and restarting Tomcat.
• If Tomcat fails to delete directories, it may be necessary to
stop Tomcat, delete the directories manually, and restart
Tomcat.
If the WAR file is deployed while Tomcat is running it will create
the directory within a few minutes, but if Tomcat is stopped the
CARIS Spatial Fusion Viewer Reference Guide
53
Deploying CARIS Spatial Fusion Viewer: Deploy Spatial Fusion Viewer 5.8
process will begin when it is started. In either case, the web
application will not be accessible until Tomcat has finished the
deployment of the WAR file.
Use and backup of
existing data
Use and backup of data from previous releases of the web
application is a concern for installation of Apache Tomcat. For
further information See “BACKING UP EXISTING CONFIGURATION DATA” ON
PAGE 22.
Updating an existing
deployment
In updating an existing deployment of the web application, it is
not necessary to back up data, but it is a good precaution. See
“BACKING UP EXISTING CONFIGURATION DATA” ON PAGE 22 for more
information. It is not necessary to stop Tomcat. To deploy a new
WAR file:
1. Navigate to the webapps directory, located in the Tomcat Installation
Directory.
See “TOMCAT INSTALLATION DIRECTORY” ON PAGE 19 for more
information.
2. Change the file name of the WAR file supplied for this release to match
the file name as it was previously deployed in the webapps directory.
If the file name of the WAR is different from the previous deployment, the new
deployment will not use any data previously configured.
3. Delete the spatialfusionviewer.war file.
Wait until the spatialfusionviewer directory is deleted by
Tomcat.
4. Copy the new spatialfusionviewer.war file to the webapps
directory.
Tomcat will create a new spatialfusionviewer directory, by
deploying the contents of the new spatialfusionviewer.war
file.
The web application will not be functional until Tomcat deploys
the new WAR file, usually in a few minutes, depending on the
speed of the server and its load.
In unusual circumstances, the new WAR file will not deploy
correctly, and the new deployment of the web application will
not be operational. Stopping and starting Tomcat will often
resolve such a problem
To deploy the WAR file in this situation:
1. Stop Tomcat.
2. Delete the spatialfusionviewer directory.
3. Start Tomcat.
54
CARIS Spatial Fusion Viewer Reference Guide
Deploying CARIS Spatial Fusion Viewer: Deploy Spatial Fusion Viewer 5.8
Tomcat will create a new spatialfusionviewer directory, by
deploying the contents of the spatialfusionviewer.war
file. After Tomcat deploys the new WAR file, the web application
can be accessed as usual.
Accessing the Web
Application
If Tomcat has been stopped, it will need to be started before the web application
can be accessed. See “STARTING AND STOPPING TOMCAT” ON PAGE 49 for more
information.
To access program, it is necessary to use the following URL in a
web browser:
http://localhost:8080/spatialfusionviewer
"localhost" can be replaced with the name of the host machine on
which the web application is running. This is essential if you are
not invoking the web application on the host machine.
The default value for the HTTP port is "8080". If you are using
any other HTTP port you will need to change this value
accordingly. See “HTTP PORT” ON PAGE 154 for more information.
The following screen should appear:
Instructions for using the web application including Username, Password, and
entering a license can be found in the CARIS SPATIAL FUSION VIEWER
REFERENCE GUIDE.
CARIS Spatial Fusion Viewer Reference Guide
55
Deploying CARIS Spatial Fusion Viewer: Deploy Spatial Fusion Viewer 5.8
The web application may start slowly after deployment, especially when Spatial
Fusion Server or other web applications are running in the same instance of
Tomcat.
One possible solution is to stop and restart Tomcat manually, and wait for
Tomcat to start before attempting to open the web application. See “STARTING
AND STOPPING TOMCAT” ON PAGE 49 for more information.
56
CARIS Spatial Fusion Viewer Reference Guide
5
Basics of the Interface
This chapter introduces you to the web application, the log in process,
and the parts of the interface.
In this chapter...
OPENING THE WEB APPLICATION .................................... 58
INTERFACE COMPONENTS .............................................. 66
LOGGING OUT ............................................................. 70
Basics of the Interface: Opening the Web Application
Opening the Web Application
Opening the web application is done differently depending on
your user role. For installations with public access, the log in
screen (shown below) may not appear. For other users, a
password and a username are required. The privileges and
features available may be different if you are using a public role
compared to a more advanced role.
The configuration of users is affected by whether LDAP has been
enabled or not.
• If LDAP has not been enabled, the Viewer Manager allows
the system administrator to configure users and their roles.
See “SECURITY” ON PAGE 103 for more information.
• If LDAP has been enabled, LDAP users can be imported into
the web application. See “AUTHENTICATE WITH LDAP” ON PAGE 139 for
more details.
To access the Viewer or Viewer Manager:
1. Enter the following in the address bar of a browser window:
http://localhost:8080/spatialfusionviewer/
Instead of localhost, the actual name of the host computer can
be used.
58
CARIS Spatial Fusion Viewer Reference Guide
Basics of the Interface: Opening the Web Application
For users with public access, the web application opens directly
with a map view. An example of this view is shown below.
CARIS Spatial Fusion Viewer Reference Guide
59
Basics of the Interface: Opening the Web Application
For users who require the use of a password, the Login page is
displayed.
The default Username and Password for the Viewer Manager is
"admin" and "password". These can easily be updated through
the User Profile page by anyone with system administrator
privileges.
The language can be selected in the right corner of the banner.
Selecting a language on this page sets the language option only for the current
session.
A map viewer sample is also available. The Username and
Password for the sample are "demonstration" and
"password".
2. Type the Username and Password, and click Login.
If you forget your password, see “FORGOT YOUR
instructions on how to change your password.
60
PASSWORD?” ON PAGE
64 for
CARIS Spatial Fusion Viewer Reference Guide
Basics of the Interface: Opening the Web Application
When logging in for the first time using the admin
(administrator) account, the License page is displayed. The
Expiration Date field is displayed empty below it.
By entering the license string and clicking Save you are
indicating that you accept the terms of the license agreement.
3. If you agree with the license agreement, copy and paste your license
string into the License Number field and click Save.
CARIS Spatial Fusion Viewer Reference Guide
61
Basics of the Interface: Opening the Web Application
After it is saved, the Expiration Date is be displayed below the License
Number.
62
CARIS Spatial Fusion Viewer Reference Guide
Basics of the Interface: Opening the Web Application
The Viewer Manager or the Viewer is now accessible. An
example of the Viewer Manager interface is shown below.
More detail about the parts of the interface can be found in the
remainder of this document.
CARIS Spatial Fusion Viewer Reference Guide
63
Basics of the Interface: Opening the Web Application
Forgot your password?
If you forget the password assigned to your account, you can
often gain access to your account and update it with a different
password.
The Forgot your password link will not appear if LDAP authentication has
been enabled. In that situation you will need to use the password for admin, or
contact the system administrator for assistance.
1. From the login page, select Forgot your password?.
The Forgot your password message is displayed.
2. Type your Email address in the text field.
3. Click Submit.
The system sends an email with a temporary “confirm change”
password to your account. It may take a few moments for your
email server to finish sending the update information to your
email address.
4. [Optional] To return to the main login page without submitting your
email address, click Cancel.
An email with the subject line, "Reset your Password", is sent to
your email account.
5. From your email account, select the Reset your Password email.
6. Click the link within the email or copy and paste the link into the
Address (URL) field in your browser and press <Enter> to confirm you
want to change the password.
Another email with the subject line "Your New Password" is sent
to your email account. This email contains a system-generated
64
CARIS Spatial Fusion Viewer Reference Guide
Basics of the Interface: Opening the Web Application
password. This password is now recorded in your user profile as
the accepted password. If you wish to change it, you can update
it in the Users profile page.
Public users should be informed of this option any time their password is
changed by the application.
7. From the login page, type the Username and the new Password.
8. Click Login.
The Viewer Manager is displayed.
9. From the Security section, select Users.
The Users page is displayed.
10.From the User list, select your user profile.
The User Profile page for your account is displayed.
11. Type and confirm the new password for your account.
12.To confirm the change, select Save.
The User Profile page, with an “updated successfully” message,
is displayed.
Your user account is updated with the new password.
CARIS Spatial Fusion Viewer Reference Guide
65
Basics of the Interface: Interface Components
Interface Components
Except for an example of the Viewer interface, this document
examines the Viewer Manager interface components.
The Viewer Manager is only displayed for users with the necessary privileges.
Public users are taken directly to the Viewer.
SFE Viewer Manager
An example of the Viewer Manager interface is shown above.
66
CARIS Spatial Fusion Viewer Reference Guide
Basics of the Interface: Interface Components
Banner links
• Logout: This link logs you out of the application, ending your
current session.
• Viewer: This link opens the map view of the web application.
• Contact Us: This link opens the CARIS Web site, which allows
you to submit a question or request to CARIS Customer
Support.
• Help: This link opens the CARIS SPATIAL FUSION VIEWER REFERENCE
GUIDE if you are logged in as admin.
Menu tabs
When selected, the menu tabs take you to individual pages. Each
page contains the same links provided on the Home page.
Viewer Manager links
• Map Configuration: This menu/section provides links to the
Data Connections and Themes pages. These pages allow you
to define which maps can be displayed in the web application
and to create themes from the data in those maps. See “MAP
CONFIGURATION” ON PAGE 71 for more information.
• Security: This menu/section provides links to the Users and
Roles pages. These pages allow you to create user accounts
and roles, and assign roles to the users. See “SECURITY” ON
PAGE 103 for more information.
• General: This menu/section provides links to the Settings,
Support, Logs and License pages. These pages allow you to
define settings for the application, view application logs,
change your license string and request customer support. See
“GENERAL OPTIONS” ON PAGE 115 for more information.
Version of Web
Application
The version number of the application appears below the links in
the upper right corner of the banner:
The version number is useful information if you need to contact
CARIS regarding the software you are using.
CARIS Spatial Fusion Viewer Reference Guide
67
Basics of the Interface: Interface Components
SFE Viewer
The Viewer link in the banner at the top of the Viewer Manager
interface, opens the web application as it is currently configured.
For users with administrative rights, the Help link opens the CARIS SPATIAL
FUSION VIEWER REFERENCE GUIDE.PDF (this document).
For non-administrators, the CARIS SPATIAL FUSION VIEWER HELP GUIDE is
available in English, French and Spanish from the help menu link of the
interface.
68
CARIS Spatial Fusion Viewer Reference Guide
Basics of the Interface: Interface Components
Changing the Appearance of the Web Application
Display settings for the interface can be customized using the
map-custom.css style sheet provided. This file controls each of
the elements of the interface, such as the font style used for each
heading type.
Making changes in this file can cause your application to stop
performing correctly. For this reason, the .css file should only be
edited by an administrator with an advanced understanding of
style sheet development.
The map-custom.css file can be found in the following directory:
…\Apache Software Foundation\Tomcat 8.0\webapps\
spatialfusionviewer\styles\mapviewer
A number of .css files are present in the install folders, but only
the map-custom.css file should be edited. This file is included
last in the set of style sheets, and it will override the settings
from all other .css files.
Note that a copy of this file is placed in Tomcat's Temp folder
when Tomcat is started and the spatialfusionviewer.war file deployed.
The file is then run from the Temp folder, not the Styles folder.
Be sure to make your edits in the file in the Styles folder, to
prevent having your changes overwritten when you restart the
Tomcat service.
The customization of the file is performed using a combination of
web development tools and integrated development
environments (IDEs). These tools allow you to identify and
inspect the elements of the interface from within a browser. An
example of a modified .css file (map-custom-example.css) is provided
in the Styles folder.
CARIS Spatial Fusion Viewer Reference Guide
69
Basics of the Interface: Logging Out
Logging Out
When you select the Logout option in the top menu bar of either
Viewer or Viewer Manager, you are logged out of the system.
1. Select Logout.
The login screen is displayed.
2. To log back into the system, retype your username and password
values and click Login.
70
CARIS Spatial Fusion Viewer Reference Guide
6
Map Configuration
This chapter shows how to create data connections and themes.
In this chapter...
DATA CONNECTIONS ..................................................... 72
POI CONFIGURATION ................................................... 78
USING PHOTO AND VIDEO WEB FEEDS FOR POIS .............. 83
USING A WFS TO DISPLAY POIS ................................... 88
MASHUP CONFIGURATION .............................................. 89
THEMES ..................................................................... 90
Map Configuration: Data Connections
Data Connections
The Data Connections page in Spatial Fusion Manager allows
you to create and edit connections to registered map data
through a Web Map Service (WMS), Web Map Tile Service (WMTS),
Web Feature Service (WFS), or Web Coverage Service (WCS).
WCS services are only available for Bathy DataBASE™ data though a Bathy
DataBASE Server™ connection.
Add Data Connections
To create your own data connection:
1. Select Data Connections from the Map Configuration menu or from
the Map Configuration section of the Home page.
The Data Connections page is displayed.
Existing data connections are listed along with their status.
A data connection has a status of "Unavailable" when a connection cannot be
made to the server identified by the web service URL.
See “SECURE SOCKETS LAYER”
secured servers.
72
ON PAGE
169 for information on connecting to
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: Data Connections
2. Click Add.
3. Select a Type for the connection from the drop-down list: WMS, WMTS,
WFS, WCS or POI.
If POI is selected as the type, the fields on this page will change to allow POIspecific information to be entered. See “CREATING A POI CONNECTION” ON
PAGE 78 for more information on creating a POI data connection.
The Data Connection page is displayed.
If you are creating a WFS with Version 1.0, it will be necessary to set up a WFS
with a single Coordinate System as the WFS 1.0 specification does not permit
data reprojection.
4. Enter a Name for the data connection. This should be something that
clearly identifies the data in the map.
5. Enter the Version of the data type.
6. Enter the URL of the connection.
7. Click Save.
CARIS Spatial Fusion Viewer Reference Guide
73
Map Configuration: Data Connections
The data connection is created. The data connection details and
layers available in the new map are displayed.
8. Click Back to return to the Data Connections page.
Edit Data Connections
You can edit existing data connections, if necessary.
To edit a data connection:
1. Select a connection name from the list.
74
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: Data Connections
The Data Connection page is displayed.
2. [Optional] Enter a new name in the Name field.
3. [Optional] Update the Version for the connection, if a different version
is available.
4. Click Save.
The data connection is updated.
5. Click Back to return to the Data Connection page.
CARIS Spatial Fusion Viewer Reference Guide
75
Map Configuration: Data Connections
If the Web service for a data connection has been modified after
the connection has been created, the following dialog box is
displayed the next time you access the connection.
This dialog box allows you to automatically update the
connection with changes to the data source.
6. Click Apply Changes to update the data connection and close the
dialog box.
Changes will need to be applied the first time each connection is accessed in
the Manager after upgrading your installations of Viewer and Server from 5.5 to
5.6.
76
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: Data Connections
Delete Data Connections
If a data connection is no longer needed, it can be deleted from
the Data Connections list.
To delete a data connection:
1. Select the check box of each data connection you wish to remove. (To
delete all connections, select the check box at the top of the list.)
2. Click Delete.
A message is displayed warning that you are about to make a
permanent deletion.
3. Click Yes to continue.
The selected data connections are deleted from the list.
CARIS Spatial Fusion Viewer Reference Guide
77
Map Configuration: POI Configuration
POI Configuration
What is a POI?
A Point of Interest (POI) connection is a uniform resource locator
(URL) connection to a file that contains spatial data in either
one of the following formats:
• Keyhole Markup Language (KML), or
• GeoRSS_SIMPLE.
Each POI connection added to a theme becomes a map layer
with an image representing spatial data. The on-screen POIs are
determined by the data in the file as described below.
Point data is displayed as a point with the image displaying at
that location. When a line or a polygon geometry is converted to
a POI, the application determines the centroid of the feature and
the POI image is shown at the centre point of the line or the
polygon.
Creating a POI Connection
To create a POI connection in the Data Connection page, you
need to specify the URL to the file, the format of the file, the
Spatial Referencing System (SRS) the file uses, and an image for
the display.
POIs are supported only in EPSG:4326. This means all four POI formats must
support EPSG:4326 for the POIs to draw in the correct location on the map.
78
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: POI Configuration
To set up a POI Connection:
1. Select POI as the connection type on the Data Connections page.
2. Click Okay.
3. Enter a Name for the connection.
4. Enter the URL for the POI source.
5. Select the format of the POI data using the drop-down list.
6. Click the Icon link to select an icon to represent this POI connection.
CARIS Spatial Fusion Viewer Reference Guide
79
Map Configuration: POI Configuration
The screen shot below shows the icons that are available.
You can add your own icons to this collection. See “ADDING POI ICONS”
PAGE 81 for more details.
ON
7. Select an icon and click Okay to return to the Data Connection page.
8. Click Save.
The POI data connection is created. The POI layer associated to
the POI connection needs to be added to the themes in which the
POIs are displayed. POIs are always displayed on top of the
map. See “THEMES” ON PAGE 90 for more information.
80
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: POI Configuration
Adding POI Icons
An administrator can add POI icons by placing the graphic files
in this folder:
<drive>:\Program Files\Apache Software Foundation\Tomcat
8.0\webapps\spatialfusionviewer\images\configmanager\icons\P
OI
where <drive> represents the drive on which the web application
was installed.
Where and how to get POI connection URLs
POI data can be displayed in the web application in several
ways, depending on the available connections and data format.
KML
Export KML from
Google™ Earth
In Google™ Earth, you can save My Places to a KML file by rightclicking My Places and selecting "save places as" in the pop-up
menu. Select KML as the "save as type".
Deploy a KML file on a
web server
Next you need to place the KML file in a folder on a web server
and get the URL of the file. Ideally a static web server like
Apache should serve these files. Apache can serve static
documents faster than Apache Tomcat; however, if this is not an
option, you should create a sub-directory in the webapps
directory of Tomcat to serve these files. The URL should be:
http://your.server.name:port/kml/[static.file.name]
You can use this URL to create the POI connection in the web
application.
CARIS Spatial Fusion Viewer Reference Guide
81
Map Configuration: POI Configuration
GeoRSS_SIMPLE
You can use GeoRSS feeds (providing they follow the simple
format) and display them on the map as Points of Interest.
Some common feeds can be found at
http://www.fmepedia.com/index.php/GeoRSS_Feed
When creating a POI connection, be sure to use the URL of the
GeoRSS feed in combination with the GeoRSS_SIMPLE format.
For more information on GeoRSS Simple, please refer to the
following source:
http://www.georss.org/GeoRSS_Simple
82
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: Using Photo and Video web feeds for POIs
Using Photo and Video web feeds for POIs
The web application supports using photo and video web feeds
for Points of Interest (POIs). The association between the web
application and the web feeds is made with a POI Data
Connection. The web feed formats supported for the POI data
connection include:
• YouTube
• Picasa
• Flickr
Preconditions
There are some preconditions that must be met in order to link
photos or videos on external web sites to the web application
maps.
• The web application supports only Picasa, Flickr and
YouTube.
• The web application only links to active accounts.
• Accounts must contain at least one public photo or video.
• The photos or videos must be georeferenced.
• The URL of the source account must be available.
CARIS Spatial Fusion Viewer Reference Guide
83
Map Configuration: Using Photo and Video web feeds for POIs
Georeferencing
Georeferencing, in this context, is that act of assigning a location
to a photograph or video. It is performed via the user interface of
the photo or video service:
• Picasa: http://support.google.com/picasa/answer/161869?hl=en
• Flickr: http://www.flickr.com/help/map
• YouTube: http://www.youtube.com
Georeferencing is also known as geotagging and geolocating.
At time of writing, the following steps can be used to
georeference a video on YouTube:
1. Log into your YouTube Account
2. Click Account name in the upper right-hand corner and click Video
Manager.
A list of all your videos will now be visible.
3. Click the Edit button of the video you wish to georeference.
4. Click the Advanced Settings tab.
5. Click the Video Location text field.
A map window will now be visible.
6. Drag the marker to the location you wish to set for your video.
The result will be a georeferenced video.
Photo web feed
Grouping photos in albums provides a convenient way of
accessing all the photos as a POI layer.
Determining the web feed URL can be a very simple operation. If
you navigate to the image or album you wish to use as a POI,
there is often an RSS feed link with an appropriate icon, such as
this one.
The link may also be shown with a hyperlink.
To determine the location, right-click and select the Copy Link
Location option.
84
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: Using Photo and Video web feeds for POIs
It may be convenient to paste the location into a text editor until
it is needed. Later on, the link can be pasted into the URL text
box when the Data Connection is set up in the web application.
YouTube
At time of writing, the video web feed for YouTube videos must
be determined using the method described below.
Login to YouTube, and then navigate to the YouTube API Demo
interface:
http://gdata.youtube.com/demo/index.html
On the API page, enter the Author name and possibly other options
such as Output Format (Atom). This normally gives the API enough
information to determine the Resulting URL feed, which is listed in
its own text box on the web form.
By copying and pasting the URL feed into a browser, your RSS
feed reader is updated with all the new feeds from the author
you selected. (Your RSS feed reader may be set up in another
application, such as an email reader.) The appropriate URL can
usually be clicked to open the video in a browser. The link in the
feed reader can be copied and later pasted into the web
application to configure a POI, as described below.
CARIS Spatial Fusion Viewer Reference Guide
85
Map Configuration: Using Photo and Video web feeds for POIs
Configure a Photo or
Video POI
To Configure the web application for POIs with photo or video
web feeds:
1. Navigate to the Data Connections page and click the Add link.
2. Select the POI Data Connection.
3. Enter a suitable name for the POI data connection.
This name will become the name of a new POI Layer that can be
added to a Theme.
4. Copy the photo or video web feed to the URL text box.
5. Select the type of POI web feed you are using in the drop-down list of
formats.
The type of feed must match the format type you select from the drop-down list.
The data connection will fail if the format does not match.
Photo or video web feeds incorporate their own thumbnail image
as a POI icon, and as a result, the icon option is not available.
6. Click Save.
If the URL is working, the POI Data connection will be saved,
and a message will indicate that status.
7. Navigate to the list of Themes.
If you are creating a new Theme and Layers for the POIs, See “THEMES”
PAGE 90 for more information.
86
ON
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: Using Photo and Video web feeds for POIs
8. Select a Layer on which you would like to display the web feed POIs.
9. On the Theme page, configure the POI data sources that you wish to
display.
You can move all the items from one selection box to the
other by clicking the move buttons.
Each item can also be dragged from its current location to
a new location. The sequence of items in either box can be
changed by dragging items up or down within the same selection
box.
10.Move the layers to the desired locations by using the move buttons, or
dragging items.
11. Click save to save the changes to the POI Configuration.
12.If necessary, add the Theme to the desired Role or Roles, and save the
changes.
Navigate to the map with an appropriate login to view the POI
layer. Click on points in the map to view the video or photo.
CARIS Spatial Fusion Viewer Reference Guide
87
Map Configuration: Using a WFS to display POIs
Using a WFS to display POIs
A WFS service from a Spatial Fusion Server outputs the feature
data in KML format. You can create different POI connections to
the WFS service in the web application to get the feature data
displayed as POIs. The URL of a POI connection is the URL of a
GetFeature request to the WFS service with the outputFormat
parameter set to the values listed in the table below.
WFS Version
Format
Value of the OutputFormat Parameter
1.0.0
KML
kml
1.1.0
KML
text/xml; subtype=kml/2.2
When creating a WFS URL, you have the ability to retrieve
subsets to get the exact data you need by using parameters such
as the box or filter. The filter takes in an XML file that follows
the Open Geospatial Consortium, Inc.® (OGC) Filter Encoding
Specification.
An example URL is shown in the following table:
http://localhost:8080/sfs/
ogcAction?servicename=fredericton_wfs&service=WFS&request=GetFeature&ver
sion=1.1.0&typename=building,roads&srsName=EPSG:4326&outputFormat=text/
xml;%20subtype=kml/2.2
88
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: Mashup Configuration
Mashup Configuration
What is a Mashup?
A mashup involves combining data from a variety of different
sources for display as a single map.
Creating a Web Services Mashup
Combining data from different Web service sources (such as
WMS, WMTS, WCS and WFS) is done using Themes. Themes
allow you to create a single Maps list entry for the Viewer to
display multiple layers from multiple services at the same time.
See “THEMES” ON PAGE 90 for more information.
Creating a POI Mashup
It is possible to create tables of POI data from a number of
sources. By using Google™ Fusion Tables, the POI data can be
combined into a mashup in a single layer.
To create such a POI mashup, follow these steps:
1. If available, export data on hand into CSV format.
Other data tables from the same or different sources can be
imported into Google™ Fusion Tables.
2. Use Google™ Fusion Tables to create KML output.
3. Use the KML output to create a POI layer. See “POI CONFIGURATION” ON
PAGE 78 for more information.
The resulting POI layer will have the combined Points of
Interest from all the sources used.
CARIS Spatial Fusion Viewer Reference Guide
89
Map Configuration: Themes
Themes
The Themes page is used to create themes using the layers of
data from data connections. Themes are accessible to the end
user in the Map List in the web application.
Themes are generally used to group similar or related data
together. For example, you may wish to create a theme for data
relating to a particular project or geographic area.
There are no limits to the number of WMTS or WMS services
that can be configured. However, only one WCS and only one
WFS will be functional. More than one data source can be
configured to display in one theme.
Add Themes
To create a theme:
1. Select Themes from the Map Configuration menu or from the Map
Configuration section of the Home page.
The Themes page is displayed.
All existing themes are listed.
2. Click Add.
90
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: Themes
The Theme page is displayed.
3. Enter a Name for the theme.1
The Coordinate System for the Theme shows the location of the
cursor on the map. This can be a different coordinate system
from the data source, if desired. The web application will
recalculate the coordinates.
1. Fields with an asterisk are required.
CARIS Spatial Fusion Viewer Reference Guide
91
Map Configuration: Themes
4. Select a Coordinate System from the drop-down list.
If you are using Google™ Maps or OpenStreetMap as the Base Layer, you
must select EPSG:3857 or EPSG:900913. The officially registered EPSG code
3857 projection is identical to EPSG:900913, and is the recommended choice.
Only one Coordinate System can be used in a Theme and all its layers,
including the base layer. Use of different coordinate systems within a theme can
cause display problems.
If you wish to use a third-party base map, all of your layers must be in the same
coordinate system in Spatial Fusion Viewer.
5. Set the total number of zoom levels available for the map (the number
of times the map can be zoomed in or out) by entering a value in the
Number of Zoom Levels field.
The minimum number of zoom levels in the web application is 5,
and the maximum number 21. However, some external maps
override any setting made on the Theme page.
• OpenStreetMap has 19 zoom levels, and this setting will
override any zoom level setting.
• Google Physical gives black tile images past zoom level 16
• Google Streets allows up to zoom level 21
• Google Satellite and Hybrid gives a "We are sorry" tile past
zoom level 20.
92
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: Themes
6. Select a Base Layer to display in the background.
To have the web application work without Internet access, all Themes must use
the None base map option, as most base maps require Internet access. Other
layers will need data from a WMS within a closed network or system.
The Default World Map option links to the world map provided
on the CARIS Web site.
The Google™ Maps option applies a layer from your Google™
Maps files. This option is only enabled if you have a Google™
Maps API key and the key is entered in the Settings page.
7. [Optional] Click the link beside the Google™ Maps field to enter the API
key if one has not been entered.
When you return to this page, the field will be enabled and the
link will have been removed.
8. [Optional] If you chose Google™ Maps, select the layer type you want
to display from the drop-down list.
CARIS Spatial Fusion Viewer Reference Guide
93
Map Configuration: Themes
You can move all the items from one selection box to the
other by clicking the move buttons.
Each item can be dragged from its current location to a
new location. The sequence of items can be changed by dragging
items up or down within the same selection box.
9. Move the map layers to the desired locations by using the move
buttons, or dragging items.
Data from multiple data connections can be included in a single
theme, creating a mashup. However, layers for each connection
should be added consecutively to optimize draw speed. If you
have layer groups created for a selected data connection, avoid
adding both the individual layer and a group containing that
same layer. Having both selected will call to the same data
twice, slowing down your draw speed unnecessarily. See “WEB
94
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: Themes
SERVICES OPTIMIZATION” ON PAGE 157 for more information about
optimizing your data configurations.
10.Move the Selection Data layers to the desired locations by clicking the
move buttons, or dragging items.
If there are WFS or WCS data sources containing downloadable
data that you want included in the theme:
11. Click the Data Connection containing the desired data.
You can add a legend to the map. A legend is an image that you
create in a graphics package and save on the computer that
hosts the web application. The image is selected during the
CARIS Spatial Fusion Viewer Reference Guide
95
Map Configuration: Themes
configuration of the theme and is displayed in the map when the
theme has been selected.
12.Click the button to open the File Upload dialog.
This allows you to browse the file system of the computer that
hosts the web application.
13.Select the appropriate image and click Open to upload the file to the
web application.
96
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: Themes
The selected image will be displayed in the Theme
configuration page. Note that the image can be removed so
that a different image can be selected. The theme
configuration must be saved in order for the selected image to
be used as the legend in the map view.
14.Click Save.
The theme is created.
CARIS Spatial Fusion Viewer Reference Guide
97
Map Configuration: Themes
If you are not using EPSG:4326, EPSG:900913 or ESPG:3857 then you must
specify the Maximum Bounding Box for a Theme. Failing to do so will result in
drawing problems in the Viewer. See “BOUNDING BOXES” ON PAGE 98 for
instructions on how to make this setting.
Once a theme has been saved, links are added to the page for
Localize and Set Bounding Boxes. These links allow you to:
• Provide the appropriate theme name for each of the
application’s language options.
• Define the extents of the theme. If nothing is defined, it will
default to the extents of the selected Base layer.
Localization
15.[Optional] Select Localize if the theme is to be used in various
languages.
The Localizations dialog box is displayed.
16.Enter the name you would like displayed for each language.
17.Click Save.
18.Click the X (Close button) to return to the Theme page.
The localization has been defined.
Bounding Boxes
Unless the bounding box is set, users will need to navigate to the map
location each time a map is opened.
The default World Map, Google™ Maps and OpenStreetMap define their own
maximum bounding box settings. Any maximum bounding box settings in the
web application for these base maps will be ignored.
To set the Bounding Box limits:
19.Select the Set Bounding Boxes link.
98
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: Themes
The Bounding Boxes dialog box is displayed.
20.To define the default extents for this theme, enter coordinate values in
the Min and Max X and Y fields in the Default Bounding Box section.
21.To define the maximum possible extents for this theme, enter
coordinate values in the Min and Max X and Y fields in the Maximum
Bounding Box section. These extents will be used to configure data for
the Overview window.
22.Click Save.
CARIS Spatial Fusion Viewer Reference Guide
99
Map Configuration: Themes
A message is displayed stating that the extents were saved.
23.Click Back to return to the Theme page.
Edit Themes
You can edit the settings of an existing theme, if necessary.
To edit a theme:
1. Select a theme Name from the list.
The Theme page is displayed.
2. Make any necessary changes.
3. Click Save.
100
CARIS Spatial Fusion Viewer Reference Guide
Map Configuration: Themes
The theme is updated.
4. Click Back to return to the Themes page.
Delete Themes
If a theme is no longer needed, it can be deleted from the Themes
list.
To delete a theme:
1. Select the check box of each theme you wish to remove. To delete all
themes, select the check box at the top of the list.
2. Click Delete.
CARIS Spatial Fusion Viewer Reference Guide
101
Map Configuration: Themes
A message is displayed warning that you are about to make a
permanent deletion.
3. Click Yes to continue.
The selected themes are deleted from the list.
102
CARIS Spatial Fusion Viewer Reference Guide
7
Security
This chapter shows how an administrator can manage user configuration.
In this chapter...
USERS ..................................................................... 104
ROLES ..................................................................... 108
Security: Users
Users
The configuration of users is affected by whether LDAP has been
enabled or not.
• If LDAP has been enabled, see “AUTHENTICATE WITH LDAP” ON
PAGE 139 for more details on the configuration of users.
• If LDAP has not been enabled, the Viewer Manager allows
the system administrator to configure users and their roles.
The procedures are described in this section of the manual.
The remainder of this Users section describe the configuration of
users when LDAP has not been enabled.
Through the Security menu options, you can create and manage
user accounts.
The Users options allow you to add, edit, and delete user
accounts.
See:
• “ADD/EDIT USERS” ON PAGE 104
• “DELETE USERS” ON PAGE 107
Add/Edit Users
To add or edit users:
1. Select Users from the Security menu or from the Security section of
the Home page.
The Users page is displayed.
2. To add a new user, select Add.
OR
To edit an existing user, select a Username from the list.
104
CARIS Spatial Fusion Viewer Reference Guide
Security: Users
The User Profile page is displayed.
If you are creating a new user, the fields in the Required section will be blank.
3. For each field in the Required section, type a value1.
4. [Optional] Type or select any additional useful or available information
in the fields in the Optional section.
1. A value is required for any field, list or option with an asterisk.
CARIS Spatial Fusion Viewer Reference Guide
105
Security: Users
A role provides users with access to certain tools and themes,
based on the privileges associated with the role. See “ROLES” ON
PAGE 108 for more information.
In the Roles section, you will need to add or remove roles to
create the desired user access.
You can move all the items from one selection box to the
other by clicking the move buttons.
Each item can also be dragged from its current location to
a new location. The sequence of items in either box can be
changed by dragging items up or down within the same selection
box.
5. Move the roles to the desired locations by using the move buttons, or
dragging items.
6. To save the user account and information, click Save.
106
CARIS Spatial Fusion Viewer Reference Guide
Security: Users
The new user, or updates to an existing user, are saved.
7. To return to the Users page, click Back.
You can track and manage the activity of users using the Apache
Tomcat Manager. See “MONITORING USER CONNECTIONS WITH APACHE
SERVER” ON PAGE 165 for more information.
Delete Users
You can also delete users if necessary. To delete one or more
users from the list:
1. Select the check box of each user you wish to remove and select
Delete. To delete all users, select the check box at the top of the list
and select Delete.
A message is displayed warning that you are about to make a
permanent deletion.
2. Click OK to continue.
No check box is available for the administrator user; this user cannot be deleted.
The selected user accounts are deleted from the Users page.
CARIS Spatial Fusion Viewer Reference Guide
107
Security: Roles
Roles
Roles are collections of permissions that can be assigned to
users. The web application provides the administrator role and
the publicuser role.
The configuration of roles is not affected by whether LDAP has
been enabled or not. Whether new users are acquired through
LDAP or the web application, the administrator must assign
privileges to users before users can access Themes and map
data.
For more information about LDAP, see “AUTHENTICATE WITH LDAP” ON
PAGE 139.
The administrator role has access to all tools and options in the
Viewer Manager, as well as viewing data in the Viewer. This
includes:
• adding, editing and deleting user accounts,
• assigning privileges to users,
• creating data connections and themes,
• defining the settings for the application,
• accessing the application logs, and
• generating support requests.
The publicuser role is limited to viewing data in the Viewer. This
includes:
• Turning on and off the themes that they have permission to
view, and
• Adjusting the view with the zoom and pan tools.
Users with administrator privileges can create additional roles
as needed and edit existing roles.
The themes a user can view in the Viewer is controlled by the
themes associated with the role assigned to the user. Although a
role can be saved without a theme assigned to it, a theme is
necessary before the role can be used.
For further information see:
• “ADD ROLES” ON PAGE 109
• “EDIT ROLES” ON PAGE 111
• “DELETE ROLES” ON PAGE 113
108
CARIS Spatial Fusion Viewer Reference Guide
Security: Roles
Add Roles
To add a role:
1. Select Roles from the Security menu or from the Security section of the
Home page.
The Roles page is displayed.
2. Click Add.
The Role page is displayed.
3. Enter a name for the role in the Name field.
CARIS Spatial Fusion Viewer Reference Guide
109
Security: Roles
You now must add to the list of Selected Themes each theme you
want to assign to the role.
You can move all the items from one selection box to the
other by clicking the move buttons.
Each item can also be dragged from its current location to
a new location. The sequence of items in either box can be
changed by dragging items up or down within the same selection
box.
4. Move the themes to the desired list by using the move buttons, or
dragging items.
5. Click Save.
The role is saved and can now be assigned to users.
6. To return to the Roles page, select Back.
The role you created is added to the list.
One role in the list can be designated for public access. Users
with this role are not required to login to access the Viewer. You
can designate a different role as public access by clicking the
radio button for the role. If you do not wish to have public access
designated to any of the roles, click the Disable Public Access
option. None of the radio buttons will be selected.
110
CARIS Spatial Fusion Viewer Reference Guide
Security: Roles
Edit Roles
Existing roles can be edited if permissions require adjustment
after the role has been created. To edit a role:
1. Select the role Name in the list.
The selected role profile is displayed.
2. [Optional] Change the name of the role.
You can move the themes from one selection box to the
other by clicking the move buttons.
Each item can also be dragged from its current location to
a new location. The sequence of items in either box can be
changed by dragging items up or down within the same selection
box.
3. [Optional] Move the themes to the desired list by using the move
buttons, or dragging items.
4. Click Save.
CARIS Spatial Fusion Viewer Reference Guide
111
Security: Roles
The role is updated, and a confirmation message is displayed.
If you make changes to a role that is currently assigned to a
user, those changes will automatically be updated in the user’s
profile when you save the role. If the user is logged in to the
application at the time the changes are made, they will need to
log off and back in to see the difference.
5. To return to the Roles page, select Back.
112
CARIS Spatial Fusion Viewer Reference Guide
Security: Roles
Delete Roles
You can also delete roles if they are no longer necessary. To
delete one or more roles from the list:
1. Select the check box of each role you wish to remove and select
Delete. To delete all roles, select the check box at the top of the list and
select Delete.
A message is displayed warning that you are about to make a
permanent deletion.
2. Click OK to continue.
No check box is available for the administrator role; this role cannot be deleted.
3. To return to the Roles page, select Back.
CARIS Spatial Fusion Viewer Reference Guide
113
Security: Roles
114
CARIS Spatial Fusion Viewer Reference Guide
8
General Options
This chapter shows how to change settings, contact CARIS for support,
view the application logs, and register a license for the web application.
In this chapter...
DEFAULT LANGUAGE KEY ............................................ 116
SETTINGS ................................................................. 118
SUPPORT.................................................................. 120
LOGS ....................................................................... 121
LICENSE ................................................................... 125
General Options: Default Language Key
Default Language Key
The web application can be configured to use the locale provided
by the locale settings of the browser being used. If there is no
match, then the application has a default locale setting in the
Settings page that it would then use.
In effect, this permits the administrator to give the web
application a default language other than English.
The web application allows for the request_locale to be read from
the URL to render the page in the appropriate language. If the
given request_locale does not match one of the web application's
supported languages, then it will default to English.
• Setting the language preference in the User Profile will take
precedence over the default locale setting when a user is
logged in.
• Setting the language default locale will set only the language
preference on the login/public pages of the Viewer and Server.
• The user will still be able to select a different language on the
login or map viewer page (for public use) that will be
maintained throughout the session.
If you do not have a public role and the administrator would like
users to be able to choose their own default language, users can
make that selection on the User Profile page.
English Map Examples (default)
http://your.domain.com/spatialfusionviewer/mapViewer/map.action?request_locale=en
http://your.domain.com/spatialfusionviewer/mapViewer/
map.action?request_locale=en_US
http://your.domain.com/spatialfusionviewer/mapViewer/
map.action?request_locale=ja_JP
In the last example, the browser will use English, as Japanese is
not a supported language.
116
CARIS Spatial Fusion Viewer Reference Guide
General Options: Default Language Key
French Map Examples
http://your.domain.com/spatialfusionviewer/mapViewer/map.action?request_locale=fr
http://your.domain.com/spatialfusionviewer/mapViewer/
map.action?request_locale=fr_FR
Spanish Map Examples
http://your.domain.com/spatialfusionviewer/mapViewer/map.action?request_locale=es
http://your.domain.com/spatialfusionviewer/mapViewer/
map.action?request_locale=es_MX
http://your.domain.com/spatialfusionviewer/mapViewer/
map.action?request_locale=es_ES_EURO
CARIS Spatial Fusion Viewer Reference Guide
117
General Options: Settings
Settings
The Settings page is used to set environment variables for the
Viewer application. These settings can only be changed by a user
with the administrator role.
To change a variable:
1. From the General section, select Settings.
The Settings page is displayed.
2. To filter the settings listed by Name, type one or more characters in the
Filter by Name field.
3. To clear the filter and show all available settings, click Show All.
118
CARIS Spatial Fusion Viewer Reference Guide
General Options: Settings
All available settings are displayed.
4. [Optional] To sort the settings, in the settings table, click a column
heading.
By default, entries listed in the Settings table are sorted in
ascending (lowest-to-highest: 0-9, A-Z and a-z) order. When a
column heading is selected, an up arrow is displayed in the
heading cell. To have the values sorted in descending (highestto-lowest) order, click the heading again.
5. To change a setting value, select the table cell of the value to change.
An update dialog box is displayed.
6. Type the new value and click Save.
7. [Optional] To close the dialog box without changing the previous value,
click Cancel.
8. To change a setting back to its default value, select the Reset button
(
) for the desired setting.
The Settings Page is used to change the logging level. See “LOGGING LEVEL” ON
PAGE 123 for an explanation of the logging levels.
CARIS Spatial Fusion Viewer Reference Guide
119
General Options: Support
Support
The Support page allows you to submit support requests and
Viewer logs to the email address designated for support. By
default, this address is [email protected], however, it can be
changed in the Settings page if desired.
To use this page:
1. From the General section, select Support.
The Support page is displayed.
2. Type values for all required1 fields (Contact Name, Phone Number
and Email).
3. [Optional] Type the Service Request Number assigned to your
request (this number is provided, as needed, by CARIS Customer
Support after you have contacted CARIS for support).
Note: If the support.email value in the Settings page is not a CARIS email
address (e.g., [email protected]), the Service Request Number field is not
displayed.
4. [Optional] Type any additional information or comments in the Problem
Summary text box.
5. To submit the logs from your account to CARIS, select Send Logs.
The logs from your account (application and servlet container
logs) have been sent to the account specified for handling email
support service.
1. For any field, list or option with an asterisk, a value is required.
120
CARIS Spatial Fusion Viewer Reference Guide
General Options: Logs
Logs
The Logs page allows you to view the logs for the web
application. Log entries are generated whenever there is system
activity or an error occurs in the application. Logs are separated
into two categories, Application Logs and Servlet Container
Logs.
Application Logs
These logs record activity and errors that occurred in the
application.
The two main log files are the spatial fusion viewer.log
file and the spatial fusion server dependencies.log
file. Both will only log errors when a warning, error or fatal
event occurs. The spatial fusion server
dependencies.log file contains entries from non-CARIS code.
The spatial fusion viewer.log file records events
originating from CARIS code.
Servlet Container Logs
• The following log files record information, activities and
errors that occurred in the Apache Tomcat service:
• localhost.[date].log,
• host-manager.[date].log,
• catalina.[date].log, and
• those containing "stdout" in the file name.
For more information see:
http://tomcat.apache.org/tomcat-8.0-doc/logging.html
CARIS Spatial Fusion Viewer Reference Guide
121
General Options: Logs
Viewing Log Files
To view a log entry:
1. From the General section, select Logs.
The Logs page for your account is displayed.
2. From one of the log tables, select the name of the log file to view.
Example: Servlet container log file excerpt.
3. To go back to the Logs page, select Back.
Logs can be deleted if they’re not required.
The currently active log, spatialfusionviewer.log, cannot be selected or deleted
from the log table.
122
CARIS Spatial Fusion Viewer Reference Guide
General Options: Logs
To delete a log:
1. Select one or more application logs by checking the check boxes.
Select the check box at the top of the list to select all logs in the table.
2. Click Delete.
The selected application logs are deleted.
Logging Level
The number and types of logs can be set to five different levels.
The highest level, "FATAL", only reports fatal errors in the log
files, while the lowest level, "DEBUG" will report any and all
problems.
Amount of
Information
Logging Level
Description
Least
FATAL
Only reports fatal events.
ERROR
Reports fatal, and error events.
WARN
Reports fatal, error, and warning events.
INFO
Reports fatal, error, warning and info events.
DEBUG
Reports fatal, error, warning, info, and debug events.
Most
The default logging level is FATAL. Increasing the level of
logging is very useful if your installation of the web application
has any problems. By setting the logging level to record as much
information as possible, Customer Support at CARIS may be
able to use the log files to diagnose a problem quickly.
To set the logging level:
1. Navigate to the Settings Page.
The General > Settings menu sequence can be used.
CARIS Spatial Fusion Viewer Reference Guide
123
General Options: Logs
2. [Optional] To display the logging level field quickly, enter "log" in the
Filter by Name field.
3. Click on the value field.
4. Enter the desired logging levels from the list of five logging levels
above.
5. Click Save.
The logging level is set to the level you have entered. See
“SETTINGS” ON PAGE 118 for more information on changing Settings.
124
CARIS Spatial Fusion Viewer Reference Guide
General Options: License
License
The License page is used to update the web application license,
which is completely separate from the Server license.
In the case where the current license must be renewed, an email
notification is sent at least two weeks before the current license
for the service is set to expire.
1. From the General section, select License.
The License page is displayed.
2. To update the previous the web application license (e.g., the current
license is about to expire), paste the new license string, provided by
CARIS, in the License Number field.
3. To save the update, select Save.
CARIS Spatial Fusion Viewer Reference Guide
125
General Options: License
A confirmation message indicates that the license for the service
is updated.
126
CARIS Spatial Fusion Viewer Reference Guide
A
Advanced Technical Notes
This appendix has information on advanced configuration settings for one
or more of the applications included with the installation program for the
web application
In this chapter...
CONFIGURATION DATABASE ......................................... 128
APACHE WEB SERVER ................................................ 129
APACHE TOMCAT........................................................ 133
Advanced Technical Notes: Configuration Database
Configuration Database
Spatial Fusion Viewer (SFV) stores its configuration in an
HSQLDB database.
The location of the database is controlled by two Java options.
The default location is the directory identified by
java.io.tmpdir. However, if com.caris.sfv.dir is set
the database location will be the directory identified by this
option. The com.caris.sfv.dir option overrides
java.io.tmpdir in the case of SFV configuration data.
Database communication occurs on port 9001 by default. If more
than one instance of SFV is set up on a system they should be
configured to use different databases using the
com.caris.sfv.dir Java option and different ports for
database communication. See “CHANGE THE DATABASE PORT” ON
PAGE 138 for more information.
128
CARIS Spatial Fusion Viewer Reference Guide
Advanced Technical Notes: Apache Web Server
Apache Web Server
Apache HTTP Server can be used as a reverse proxy (or
gateway) server for back-end Tomcat server(s) running SFV and
other web applications.
This section shows how to configure Apache Web Server for
caching and HTTP compression.
Caching with Apache Web Server
This section refers to Apache Web Server 2.4. Refer to the
documentation for the version of Apache Web Server that you
are running.
Caching can be implemented using the mod_cache and the
mod_cache_disk modules. The online documentation for these
modules can be found here:
https://httpd.apache.org/docs/2.4/mod/mod_cache.html
https://httpd.apache.org/docs/2.4/mod/mod_cache_disk.html
The Apache documentation contains a guide to caching, which
can be found here:
http://httpd.apache.org/docs/2.4/caching.html
It is highly recommended that you read these documents before configuring
caching.
An application called htcacheclean can be used to keep a
disk cache within a given size limit. It is documented here:
http://httpd.apache.org/docs/2.4/programs/htcacheclean.html
The following is an example of a configuration for caching
WMTS responses. To enable caching for WMTS you must enable
the expiry date setting in the WMTS configuration. The changes
CARIS Spatial Fusion Viewer Reference Guide
129
Advanced Technical Notes: Apache Web Server
are made in the httpd.conf configuration file of Apache Web
Server:
# Load the mod_cache module and the mod_cache_disk module
LoadModule cache_module modules/mod_cache.so
LoadModule cache_disk_module modules/mod_cache_disk.so
<IfModule mod_cache.c>
# Avoiding the thundering herd
# Other parameters CacheLockPath and CacheLockMaxAge are defaulted
CacheLock on
<IfModule mod_cache_disk.c>
# Identify the root of the disk cache directory
CacheRoot c:/cache
# Enable the cache on the disk for WMTS requests.
CacheEnable disk /spatialfusionserver/services/ows/wmts
# Set the cache levels
CacheDirLevels 3
# Set the directory name length
CacheDirLength 1
</IfModule>
</IfModule>
HTTP Compression on Apache Web Server
This section refers to Apache Web Server 2.4. Refer to the
documentation for the version of Apache Web Server that you
are running.
Compression provides a way of reducing the size of HTTP
messages returned by Apache Web Server. This example
requires the following modules:
• mod_deflate
• mod_filter
• mod_headers
The online documentation for these modules can be found on
these web pages:
• http://httpd.apache.org/docs/2.4/mod/mod_deflate.html
• http://httpd.apache.org/docs/2.4/mod/mod_filter.html
• http://httpd.apache.org/docs/2.4/mod/mod_headers.html
130
CARIS Spatial Fusion Viewer Reference Guide
Advanced Technical Notes: Apache Web Server
Compression can be applied selectively depending on the content
type of the response. You can decide which types to compress
using the AddOutputFilterByType parameter. Variations in
performance as a result of implementing compression for a
particular type depend on:
• The type of data being transferred
• The volume of data being transferred
Determining the optimum configuration for the use of
compression requires analysis. The following internet media
types are used by SFV:
• application/gml+xml
• text/xml
• application/vnd.google-earth.kml+xml
• application/json
• application/vnd.ogc.se_xml
• application/xml
• application/vnd.ogc.gml
• application/vnd.ogc.wms_xml
• application/zip
• application/x-bag
• image/png
• image/jpeg
• image/gif
• image/tiff
• text/csv
• text/html
• text/css
• application/javascript
CARIS Spatial Fusion Viewer Reference Guide
131
Advanced Technical Notes: Apache Web Server
The following text shows the configuration in the httpd.conf file
of Apache Web Server that is needed to achieve HTTP
compression:
# Modules required
LoadModule deflate_module modules/mod_deflate.so
LoadModule filter_module modules/mod_filter.so
LoadModule headers_module modules/mod_headers.so
<Location />
<IfModule mod_deflate.c>
# Compress content with the following types
AddOutputFilterByType DEFLATE text/csv application/xml text/html
<IfModule mod_headers.c>
# Properly handle requests coming from behind proxies
Header append Vary User-Agent
</IfModule>
</IfModule>
</Location>
# Some old browsers do not handle compression
<IfModule mod_deflate.c>
BrowserMatch ^Mozilla/4 gzip-only-text/html
BrowserMatch ^Mozilla/4\.0[678] no-gzip
BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
</IfModule>
# The following lines are optional. They provide configuration
# to create a log called deflate.log. It can be used to check
# that responses are in fact being compressed. Uncomment the
# lines to create the log.
#<IfModule mod_deflate.c>
# DeflateFilterNote Input instream
# DeflateFilterNote Output outstream
# DeflateFilterNote Ratio ratio
# LogFormat '%r %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
# CustomLog logs/deflate.log deflate
#</IfModule>
132
CARIS Spatial Fusion Viewer Reference Guide
Advanced Technical Notes: Apache Tomcat
Apache Tomcat
This section refers to Tomcat 7.0. Refer to the documentation for
the version of Tomcat that you are running.
Tomcat Deployment Option
This section describes a way of deploying Tomcat so that it is
separated into what is known as CATALINA_HOME and
CATALINA_BASE. The configuration is useful primarily because
it simplifies upgrading Tomcat. The binary components of
Tomcat are separated from the web application specific
configuration. This means that the web application
configuration is untouched during an upgrade.
The benefit is increased if multiple instances of Tomcat are in
use. All CATALINA_BASE deployments of Tomcat will depend
on one CATALINA_HOME directory. In such multiple instances,
there would be one CATALINA_HOME directory and multiple
CATALINA_BASE directories, each with a different directory
name.
The install uses the .zip archive distribution of Tomcat rather
than the installer. The Windows .zip can be obtained from:
http://tomcat.apache.org/download-70.cgi
The JRE_HOME environment variable should be set before attempting to
deploy Tomcat in this way. See “SET JRE_HOME VARIABLE” ON PAGE 133
(below) for instructions on how to do this.
Set JRE_HOME Variable
1. Click Start...
2. Enter "Edit the system environment variables" in the Search program
and files text box and click Enter.
The System Properties dialog appears
3. Click the Environment Variables... button
The Environment Variables dialog appears
4. Click the New... button that is in the System Variables group box.
The New System Variable dialog appears
5. Enter "JRE_HOME" in the Variable name text box
6. Enter the path to JRE_HOME in the Variable value text box
CARIS Spatial Fusion Viewer Reference Guide
133
Advanced Technical Notes: Apache Tomcat
Configuration Data Directory
Create the following directory:
C:\CARIS\SFV\tomcat_8680
This directory will hold the configuration data. It is assigned to
the com.caris.sfv.dir Java option during the following
configuration steps.
CATALINA_HOME - apache-tomcat
Extract the contents of the Tomcat .zip distribution. The
extraction directory will be similar to apache-tomcat7.0.53. Rename this to apache-tomcat. This is not
essential but it will help ensure that scripts that point to files in
this location will always work. This directory will be replaced in
the future when Tomcat is upgraded.
This directory will be CATALINA_HOME. This is the root of the
Tomcat installation. It is similar to the Tomcat installation
directory.
CATALINA_BASE - tomcat_8680
A CATALINA_BASE is defined for each instance of Tomcat that
will be deployed. This is where web applications will be installed
and configuration changes are made. Create a directory named
"tomcat_8680" in the same location as the CATALINA_HOME
directory. Create the following sub-directories in it: bin, conf,
logs, temp, webapps and work. The directory structure will
now look like this:
Root
First level directory
Second level directory
Comments
C:
\apache-tomcat
This directory contains tomcat binary files,
and is the CATALINA_HOME directory.
\tomcat_8680
This directory contains tomcat_8680 web
application files. It is a CATALINA_BASE directory.
\bin
\conf
\logs
\temp
\webapps
\work
134
CARIS Spatial Fusion Viewer Reference Guide
Advanced Technical Notes: Apache Tomcat
CATALINA_BASE\conf
Copy the contents of the apache-tomcat\conf directory to
CATALINA_BASE\conf. Edit the server.xml so that the
connector port is set to 8680, as in the following example.
<Connector port="8680" protocol="HTTP/1.1"
connectionTimeout="20000" redirectPort="8443" />
CATALINA_BASE\webapps
Copy the web application (e.g. the SFV WAR) to the webapps
directory.
CATALINA_BASE\bin
Create an install.bat script in the bin directory with the
following contents:
set CATALINA_HOME=c:\apache-tomcat
set CATALINA_BASE=c:\tomcat_8680
C:\apache-tomcat\bin\service install tomcat_8680
Create an updateservice.bat script in the bin directory
with the content shown below. This script is used to set the Java
Options for the Tomcat service:
set CATALINA_BASE=c:\tomcat_8680
set CATALINA_HOME=c:\apache-tomcat
c:\apache-tomcat\bin\tomcat7.exe //US//tomcat_8680 --JvmMs "" --JvmMx "" -JvmOptions "-Dcatalina.base=%CATALINA_BASE%;-Dcatalina.home=%CATALINA_HOME%;Djava.endorsed.dirs=%CATALINA_HOME%\endorsed;Djava.io.tmpdir=%CATALINA_BASE%\temp;Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager;Djava.util.logging.config.file=%CATALINA_BASE%\conf\logging.properties;-Xmx256m;Xms256m;-Dcom.caris.sfv.dir=c:\CARIS\SFV\tomcat_8680;Dfusion.home=C:\CARIS\SpatialFusionRuntime"
Note that the updateservice.bat script contains the Java
options. These can be edited if a different configuration is
desired. The example can be used as a template.
Run the install.bat script to install the Windows Service.
Run the updateservice.bat script to change the Java
Options.
Optionally, to ensure that the Java Options have been
committed, navigate to the CATALINA_HOME\bin directory,
copy the tomcat7w.exe file and paste it in the directory.
CARIS Spatial Fusion Viewer Reference Guide
135
Advanced Technical Notes: Apache Tomcat
Rename it tomcat_8680.exe and open it. The Java Options
that have just been set should be visible on the Java Options tab.
Start and Stop the Tomcat Services
The Tomcat instance has been installed as a Windows service.
To start the service open the Windows Services console. Click
Start and type Services in the search box. The service will be
listed with the name Apache Tomcat tomcat_8680. Select it and
click the Start hyperlink. At this point the service can also be
configured to start automatically, which is appropriate for
production systems. Right click on them, select Properties and
change the Startup Type to Automatic (Delayed Start). This will
allow the service to restart automatically when the system
reboots.
The service can be stopped using the Windows Services console.
Upgrading Tomcat
In this configuration, the steps to upgrade Tomcat from one 7.0.x
release to a more recent version of 7.0.x (for example, 70.59 to
7.0.61) are as follows:
1. Obtain the latest version of Tomcat.
Use the Windows .zip distribution.
2. Stop the Tomcat services.
3. Remove the contents of the apache-tomcat directory.
4. Extract the contents of the .zip apache-tomcat-7.0.x directory to
the apache-tomcat directory
5. Start the Tomcat services.
All CATALINA_BASE deployments of Tomcat that depend on the
CATALINA_HOME, where the binary files are upgraded, will be
upgraded in this sequence of steps.
In this configuration, the steps to upgrade Tomcat from version
7.0.x to version 8.0.x are as follows:
1. Obtain the latest version of Tomcat
Use the Windows .zip distribution
2. Stop the Tomcat services
3. Remove the existing Tomcat Windows service
4. Remove the contents of the apache-tomcat directory
5. Extract the contents of the .zip apache-tomcat-8.0.x directory to the
apache-tomcat directory
6. Copy the contents of apache-tomcat\conf to CATALINA_BASE\conf
136
CARIS Spatial Fusion Viewer Reference Guide
Advanced Technical Notes: Apache Tomcat
7. Edit CATALINA_BASE\conf\server.xml to set the HTTP port
8. Start the Tomcat services
All CATALINA_BASE deployments of Tomcat that depend on the
CATALINA_HOME, where the binary files are upgraded, will be
upgraded in this sequence of steps.
CARIS Spatial Fusion Viewer Reference Guide
137
Advanced Technical Notes: Apache Tomcat
Change the Database Port
The default database port is 9001. It can be changed by editing
the Tomcat context file. The context file is created when a web
application is deployed (that is, a WAR has been deployed by
Tomcat in the webapps folder). The context file can be found in
this directory:
[Tomcat Installation Folder]\conf\Catalina\[hostname]
To change the database port to 2345:
1. Find the url command in the context.xml file, for example:
url="jdbc:hsqldb:hsql://localhost/sfv"
2. To this line, add :2345 immediately after localhost, for example:
url="jdbc:hsqldb:hsql://localhost:2345/sfv"
For further information, see Apache Tomcat documentation at:
http://tomcat.apache.org/migration.html#6.0.x_to_7.0.x
138
CARIS Spatial Fusion Viewer Reference Guide
B
Authenticate with LDAP
In this chapter...
INTRODUCTION ........................................................... 140
ENABLE LDAP AUTHENTICATION .................................. 142
USE LDAP AUTHENTICATION ...................................... 144
DISABLE LDAP AUTHENTICATION ................................. 148
Authenticate with LDAP: Introduction
Introduction
Lightweight Directory
Access Protocol
The web application supports access to a Lightweight Directory
Access Protocol (LDAP).
The web application can connect to an LDAP server to
authenticate users. When a successful connection is made to an
LDAP server, the user authentication is delegated to the server.
With LDAP authentication, administrators are no longer able to
create new users and passwords from the web application, and
users are no longer able to reset their own passwords.
Only users with email addresses entered in the LDAP server will be available for
import into the web application.
LDAPS
See “SECURE SOCKETS LAYER” ON PAGE 169 for information on
connecting to secured servers.
Restricted Role
When users are imported from the LDAP server, they are given
by default a “Restricted” role that gives no access to
administrative functions. Users are presented with a Restricted
Access page, which contains a message directing them to contact
their administrator to assign a role.
Once the users have been imported from the LDAP server to the
web application, the administrator can then assign roles to the
imported users as appropriate.
140
CARIS Spatial Fusion Viewer Reference Guide
Authenticate with LDAP: Introduction
User Management with
LDAP
Since the Username and Email fields are taken from the LDAP
server, these fields are now read-only in the web application.
The Password and Confirm Password fields are removed from the web
application, since the passwords are stored on the LDAP server.
Password changes made on the LDAP server do not require
importing users into the web application, and a password change
made in the LDAP server is effective immediately in the web
application.
If a user’s email or username changes on the LDAP server, the
user must be removed from the web application and then
imported again in the application using the Import LDAP Users
link. Only users who have an email address entered in the LDAP
server are available for import into the web application.
Users created in the web application before LDAP
authentication is enabled will be retained, but after LDAP is
enabled new users must be imported from LDAP. To prevent
duplicates, any request to import users through LDAP will only
list user names that do not exist in the web application.
Admin Account
When the web application is installed, one user is created,
admin. This user is special in that, even if LDAP authentication
is enabled, this user's information and password are still stored
in the web application database, and can still be edited on the
profile page. This ensures that the admin account is always
accessible even if the LDAP server is not running.
Turn LDAP ON/OFF
The web application is intended to be used either with or
without LDAP enabled. Switching back and forth between LDAP
and non-LDAP modes causes difficulty in user management and
is not recommended. Organizations with a large number of users
in particular should avoid switching back and forth between
LDAP and non-LDAP authentication.
If LDAP is turned off, any existing users are no longer
authenticated through the LDAP server. However, all of the
existing user accounts still exist in the application. Users are
assigned randomly-generated passwords. As a result, users must
use the now-enabled Forgot Password link to reset their own
passwords and regain access to the application.
CARIS Spatial Fusion Viewer Reference Guide
141
Authenticate with LDAP: Enable LDAP Authentication
Enable LDAP Authentication
To configure and activate LDAP authentication:
1. If necessary, create a new Organizational Unit (OU) in your LDAP server,
and assign it an appropriate name.
2. Inside the OU for Spatial Fusion Enterprise™ (SFE) users, add all users
that should have access to the web application, to record the selection
for later export.
3. Log in to the web application and navigate to the Settings page.
4. Enter ldap in the filter box. The filter selects the available settings for
LDAP.
5. Fill in the required settings for your specific LDAP server.
Setting
Description
Example
ldap.base.dn
LDAP root node from which to search for users. If you
have created a specific Organization Unit (“OU”) for the
web application use that value.
ou=People,dc=example,
dc=com
ldap.bind.dn
The user name of an account that has privileges to view
all users. This setting can be left blank if your LDAP
server has enabled anonymous read access.
cn=admin,dc=example,
dc=com
ldap.bind. password
The password of the account that has privileges to view
all users. This setting can be left blank if your LDAP
server has enabled anonymous read access.
The attribute in your LDAP server that stores the user's
email address. This value is imported into the web
application.
The default value is "mail"
ldap.email. attribute
ldap.external.
authentication. enabled
A value of "true" turns LDAP on, while "false" turns it off.
Trying to set this to any other value results in an error.
The default value is "false"
142
CARIS Spatial Fusion Viewer Reference Guide
Authenticate with LDAP: Enable LDAP Authentication
Setting
ldap.query
Description
Example
LDAP query run under the ldap.base.dn that identifies
users.
ldap.query=(objectcla
ss=person)
The default value is
(objectclass=person)
ldap.search. attribute
Name of the records in LDAP nodes that become the
user names in the web application.
ldap.url
The URL of the LDAP server.
ldap.search.attribute
=uid
6. After the settings have been updated, stop and restart Tomcat to
implement the changes.
CARIS Spatial Fusion Viewer Reference Guide
143
Authenticate with LDAP: Use LDAP Authentication
Use LDAP Authentication
After LDAP authentication has been enabled, the Add link on
the List Users page is replaced with an Import LDAP Users link.
Once user data is imported from the LDAP server to the web
application, users have Restricted Access, and cannot use the
web application, with one possible exception: if public access to
the web application has been enabled, the users imported into
the web application are assigned public access as soon as the
LDAP import has been completed. A user with Restricted access
and no public privileges sees a screen suggesting that they
contact their system administrator for more privileges.
To assign LDAP users a user name in the web application:
1. Navigate to the Users page.
2. Delete any Usernames that will be imported from the LDAP server (for
example, with an updated email address).
An LDAP user with the same Username as an existing user cannot be imported
from the LDAP server.
3. Click Import LDAP Users.
144
CARIS Spatial Fusion Viewer Reference Guide
Authenticate with LDAP: Use LDAP Authentication
A page with a list of users is presented. These users:
• belong to the LDAP base Distinguishing Name (DN),
• have an email address, and
• do not have the same user name as any existing user in the
web application.
4. Select which users to import by clicking on the check box beside the
desired name (or names).
The search box can be used to filter for names.
CARIS Spatial Fusion Viewer Reference Guide
145
Authenticate with LDAP: Use LDAP Authentication
5. Click Import LDAP Users to import the selected users.
After being imported, the users appear in the Users page of the
web application.
At this time the new users only have access to the Restricted role privileges until
they are assigned a role in the web application. After such a role has been
assigned, users still do not have access to the Reset Password link, as
passwords must be changed in the LDAP server.
To give users access to the application:
6. Click the user's name on the Users page.
146
CARIS Spatial Fusion Viewer Reference Guide
Authenticate with LDAP: Use LDAP Authentication
The User Profile page is displayed.
7. Add a new role to the user's existing roles (e.g, the administrator role, if
that is appropriate).
There is no need to remove the Restricted role from the user, but
doing so does not cause any adverse effects.
Many user details (such as Username and Email) can not be edited
in the web application. It is necessary to use the LDAP server to
make changes to these details.
CARIS Spatial Fusion Viewer Reference Guide
147
Authenticate with LDAP: Disable LDAP Authentication
Disable LDAP Authentication
After LDAP authentication has been enabled, it can be disabled
if desired.
Disabling LDAP authentication after users have been set up causes difficulties
in user management and is not recommended. See “TURN LDAP ON/OFF” ON
PAGE 141 for more information.
To disable LDAP authentication:
1. Log in to the web application and navigate to the Settings page.
2. [Optional] Enter ldap in the filter box. The filter selects the available
settings for LDAP.
3. Change the ldap.external.authentication.enabled field to "false".
LDAP Authentication is disabled.
148
CARIS Spatial Fusion Viewer Reference Guide
C
Working with a Standalone Deployment
This appendix describes the process of migrating a configuration of
Spatial Fusion Viewer from a standalone deployment to a standard
deployment.
In this chapter...
TCP/IP AND PORTS .................................................. 150
STANDALONE AND STANDARD DEPLOYMENTS................... 151
STANDALONE DEPLOYMENT .......................................... 152
MIGRATING TO A STANDARD DEPLOYMENT ...................... 153
Working with a Standalone Deployment: TCP/IP and Ports
TCP/IP and Ports
Using standalone data in a standard deployment often requires
a knowledge of the port values in use, especially the HTTP and
database ports.
Transmission Control Protocol / Internet Protocol (TCP/IP) is
used to define communication between servers, clients, and the
internet. Virtual ports are used as part of that protocol to group
transmissions of a similar type through one port, which enables
the software to respond to the transmissions appropriately.
For example, the web application communicates to its
configuration database through a default port. It also uses a
hypertext transfer protocol (HTTP) port to send and receive
transmissions intended for the internet.
It is important to know the ports being used, especially when
deploying a web application like Spatial Fusion Viewer.
Attempting to run multiple instances of the application on a
single system may result in cross-talk between the two
configurations if unique ports are not provided. One method of
preventing that problem is to only run one instance of the web
application at a time.
References:
http://compnetworking.about.com/od/basiccomputerarchitecture/g/
computer-ports.htm
http://compnetworking.about.com/od/networkprotocols/f/port-numbers.htm
150
CARIS Spatial Fusion Viewer Reference Guide
Working with a Standalone Deployment: Standalone and Standard Deployments
Standalone and Standard Deployments
Tomcat is embedded in the web application WAR file. This
permits two methods of deployment:
• Standalone: the web application can be installed without
installing Tomcat.
• This type of configuration is best suited to those who want
to try out the software quickly, on a system that does not
have the web application running on it.
• A standalone deployment is simpler than a standard
deployment, since the separate configuration of Tomcat
can be avoided.
• A standalone deployment can be converted to a standard
deployment if desired. The procedures for migrating a
configuration from a standalone deployment to a standard
deployment are described in “MIGRATING TO A STANDARD
DEPLOYMENT” ON PAGE 153.
• The standalone deployment procedure is described in
CARIS SPATIAL FUSION VIEWER QUICK START GUIDE.
• Standard: the web application can be deployed to Apache
Tomcat.
• In a standard deployment, it is possible to update Tomcat
with a new release because Tomcat is installed separately.
• Keeping Tomcat up-to-date can be important as new
releases may contain security or stability fixes.
The web application owns the port that its configuration database runs on. To to
avoid possible database cross-talk issues, run only one instance of Spatial
Fusion Viewer at a time, unless the database port number for one of the
deployments has been changed as described in “CHANGE THE DATABASE PORT”
ON PAGE 138.
CARIS Spatial Fusion Viewer Reference Guide
151
Working with a Standalone Deployment: Standalone Deployment
Standalone Deployment
The configuration for a standalone deployment is placed in a
directory that can be chosen by the system administrator.
Executing the standalone WAR file (without any configuration
property changes) will result in a hidden directory created at the
location where the application is run from.
The location of data in a standalone installation is described in
“BACKING UP DATA FROM A STANDALONE DEPLOYMENT” ON PAGE 28
Configuration for a Standalone Deployment
The embedded Tomcat in a standalone deployment is preconfigured, and configuration changes are usually unnecessary.
Migrating a from a standalone deployment to a standard
deployment of the web application is described in “MIGRATING TO A
STANDARD DEPLOYMENT” ON PAGE 153.
152
CARIS Spatial Fusion Viewer Reference Guide
Working with a Standalone Deployment: Migrating to a Standard Deployment
Migrating to a Standard Deployment
Backing up a Standalone Deployment
The configuration for a standalone deployment is placed in a
hidden directory. The following scenario will describe how to
migrate the configuration from a simple standalone deployment
to a slightly more advanced standard deployment. The
configurations suggested in the CARIS SPATIAL FUSION VIEWER QUICK
START GUIDE are used here.
If the com.caris.sfv.dir was set, the configuration database will be
located at the directory specified, not the default location under the Tomcat temp
directory.
If com.caris.sfv.dir was set and a migration were to occur, simply leave
the configuration where it is and ensure that the same property and value are
supplied to the Java Virtual Machine via the Tomcat Java Options in the new
deployment settings.
If a standalone deployment is located in C:\SFV, copy the
C:\SFV\.extract\temp\database
directory to a safe location as a backup.
The files can be viewed in the command line.
System administrators can set the file manager application to view hidden files.
Navigate to the Tools > Folder Options > View tab, click the folder for "Hidden
Files", and check the box labelled "Show hidden files and folders".
CARIS Spatial Fusion Viewer Reference Guide
153
Working with a Standalone Deployment: Migrating to a Standard Deployment
In this example, the configuration will now be visible in this
directory:
C:\SFV\.extract\temp\database\spatialfusionviewer
The hidden .extract directory will include a database
directory, and possibly others as well.
Only the database\spatialfusionviewer directory
needs to be migrated.
Migrating the Database
Tomcat should be stopped in both source and destination locations before the
migration begins.
To migrate the configuration from a standalone deployment to a
standard deployment, the contents of the
...\database\spatialfusionviewer directory would need
to be copied to the target deployment.
For example, if a standalone deployment has been placed in
C:\SFV
the source database is located in
C:\SFV\.extract\temp\database\spatialfusionviewer
If the standard (destination) deployment does not have any directories as
described below, you will need to create the directories manually.
In the standard deployment, the WAR file assumes that the
database exists at the same path, relative to the [Tomcat
Installation Directory]\temp.
See “TOMCAT INSTALLATION DIRECTORY” ON PAGE 19 for more information.
HTTP port
The standalone WAR file contains Apache Tomcat. This Tomcat
configuration only has the HTTP port enabled, and it runs at
9091. For a standard deployment, it is up to the System
Administrator to choose the ports that Tomcat uses. By default,
Tomcat uses three ports (one for shutdown, one for Apache JServ
Protocol (AJP) and one for HTTP), where HTTP is 8080.
To determine the HTTP port value:
1. Open [Tomcat Installation Directory]\conf\server.xml in a text editor.
The location of this file in a default deployment is usually
[Tomcat Installation Directory]\conf\server.xml
2. Search for the XML Connector tag for the HTTP protocol.
154
CARIS Spatial Fusion Viewer Reference Guide
Working with a Standalone Deployment: Migrating to a Standard Deployment
The text will be similar to this sample:
<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443" />
The default value is "8080". If you wish to continue using
HTTP port 9091 to access the web application, you will need to
change this value accordingly. However, this is not necessary.
If users are already accustomed to using the software at a given URL, it is
always wise to create a migration plan whenever the URL would be affected.
Please consult a system administrator on how to do so. If further assistance is
required, please contact CARIS Customer Support.
You should now be able to open the web application as described
in “ACCESSING THE WEB APPLICATION” ON PAGE 55.
CARIS Spatial Fusion Viewer Reference Guide
155
Working with a Standalone Deployment: Migrating to a Standard Deployment
156
CARIS Spatial Fusion Viewer Reference Guide
D
Web Services Optimization
This chapter describes how Spatial Fusion Server and Viewer process
WMS, WMTS, WFS, and WCS server calls, and provides some
guidelines for optimizing these data connections.
In this chapter...
INTRODUCTION ........................................................... 158
OPTIMIZATION GUIDELINES ........................................... 159
CONFIGURING DATA LAYERS ........................................ 160
Web Services Optimization: Introduction
Introduction
In addition to this appendix, Administrators may also find
useful optimization information in the WEB SERVICES OPTIMIZATION
appendix of the CARIS SPATIAL FUSION SERVER REFERENCE GUIDE.
Marine datasets can be very dense. The web application protects
users from unintentionally causing problems with certain
services because of this high data density.
CARIS has restricted the data selection for a WFS request in the
following ways:
• SFE does not support any attribute queries of BDB™ raster
data.
• The WFS GetFeature request must include a bounding box.
Based on the bounding box, the point closest to the centre of
the bounding box is used to return feature information at that
location.
This technique prevents a user from unintentionally making a
query that could result in an excessive processing response.
Web Coverage Service is well-suited to point data and cloud
data. Data from the BDB Server can be downloaded using a
WCS.
158
CARIS Spatial Fusion Viewer Reference Guide
Web Services Optimization: Optimization Guidelines
Optimization Guidelines
The speed and performance of the web application can be
maximized for the end user by having as few calls to a server as
possible. This can be accomplished by layers configured
according to the following principles:
• Combine all data source layers into a single WMS or WMTS
service that will be used in the creation of a Theme in the web
application. See for more information.
• When layers from more than one data source are desired in a
Theme in the web application, the layers from the same data
source should be arranged consecutively if possible. See
“MINIMIZE CALLS TO DATA SOURCE” ON PAGE 160 for more information.
• When using a WMTS service, related layers can be grouped
into a single layer. When this group layer is drawn in the
Viewer, the data from all layers is displayed as a single layer.
It is important to avoid creating an individual WMS or WMTS
for each data source whenever possible, as this will increase the
number of calls to the server and thus reduce the performance of
Spatial Fusion Viewer, or a third-party client.
Because a mashup is a combination of multiple sources, it is
important to follow this guideline for mashups whenever
possible.
The draw speed of a mashup is only as good as the slowest service.
CARIS Spatial Fusion Viewer Reference Guide
159
Web Services Optimization: Configuring Data Layers
Configuring Data Layers
Once the service is set up in Configuring Data Layers in Spatial
Fusion Server, the configuration can be completed in Spatial
Fusion Viewer Manager. The layers in the Themes should be
organized to reduce the number of calls to the same data source.
Minimize Calls to Data Source
Creating a theme in the web application with alternating layers
from two data sources is inefficient, for these reasons:
• Time is wasted by the server in making repeated calls to the
same data source.
• Draw times will increase dramatically as each data source is
drawn more than once.
Having a single service for all related data sources is
recommended, thereby only having to create one data connection
containing all of the layers from the various data sources. The
display of these layers can be configured using themes. This will
improve the efficiency of the draw.
When different layers from the same data source are contained
in one theme, the web application will minimize the number of
draw requests being sent back to the server. If layers from one
data source are consecutive in the theme, the web application
will send one request to the server that includes all the layers in
the draw, so that only one image would be returned.
If the layers for two different connections are added in
alternating order, the client application is forced to make
multiple requests, which increases the response time for the end
user.
Each request is actually more than 24 image requests per draw
because the maps are delivered from the server to the client in
tiles. Alternating layers can thus make a much larger number of
160
CARIS Spatial Fusion Viewer Reference Guide
Web Services Optimization: Configuring Data Layers
draw requests. See the image below for examples of a random
setup and an optomized setup.
If a single OGC® instance with consecutive layers is used, the
number of draws is greatly reduced, since each draw request
would include a list of all of the layers to be drawn at once, and
the server would combine the images together before they were
returned. This would be much more efficient, and would improve
draw speeds in comparison to the alternative.
CARIS Spatial Fusion Viewer Reference Guide
161
Web Services Optimization: Configuring Data Layers
Configuring Layers
To configure layers in the web application, follow this procedure:
1. Create a new data connection for the layers being configured in the
web application. The service created in the previous set of steps will be
used as the source. “”for instructions on configuring layers.
162
CARIS Spatial Fusion Viewer Reference Guide
Web Services Optimization: Configuring Data Layers
2. Create a theme for the new connection by selecting desired layers from
any data type already registered, and saved under a single WMS,
WMTS, WFS or WCS. See “” for instructions on how to do this.
A single Theme can have multiple types of data layers included. As much as
possible though, layers from the same data source should be arranged
consecutively in the Theme.
3. Save the layers.
CARIS Spatial Fusion Viewer Reference Guide
163
Web Services Optimization: Configuring Data Layers
4. Assign the new theme to a role. All users with this role will see the new
theme when they access Viewer. See “” for instructions on how to do
this.
The resulting themes will minimize the response time of the
application.
164
CARIS Spatial Fusion Viewer Reference Guide
E
Monitoring User Connections with Apache Server
This appendix describes how user connections can be monitored using
Apache Server.
In this chapter...
TRACKING USERS IN APACHE HTTPD SERVER ............... 166
VIEW ACTIVE SESSIONS USING APACHE TOMCAT............... 167
Monitoring User Connections with Apache Server: Tracking users in Apache HTTPD Server
Tracking users in Apache HTTPD Server
In scenarios where an Apache HTTPD Server is forwarding
requests to web applications running in servlet containers, such
as Tomcat, logging is best done at the level where all of the
requests are first received. This guarantees accuracy of
information in a single location.
The log of most interest for identifying who is accessing the
server is the access log. The access log can be found in the
Apache Server logs directory.
Apache HTTPD Server Log Directory: $APACHE_HOME/logs
Apache HTTPD Server Access Log: $APACHE_HOME/logs/access.log
Additional information on the access log and how to configure it
and perform log analysis can be found here:
http://httpd.apache.org/docs/2.2/logs.html
166
CARIS Spatial Fusion Viewer Reference Guide
Monitoring User Connections with Apache Server: View active sessions using Apache Tomcat
View active sessions using Apache Tomcat
Apache Tomcat Server comes with a manager web application
that allows the administrator to remotely manage the server's
web applications. As well, it provides basic functionality to view
the number of sessions open for a particular web application,
and terminate sessions if necessary.
Manager Web Application Directory: $CATALINA_HOME/webapps/
manager
URL: http://host:8080/manager/html
To authenticate, you need to ensure that your
$CATALINA_HOME/conf/tomcat-users.xml
is correctly set up. Below is a minimal example of what needs to
be set to authenticate to the manager web application:
<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
<role rolename="manager"/>
<user username="admin" password="s3cret" roles="manager"/>
</tomcat-users>
The basic syntax to see the sessions for a given web application
is as follows, where "myWebApplication" would be replaced with
the name of the web application you want to see the current
sessions for:
http://host:8080/manager/html/sessions?path=/
myWebApplication
Additional information on the manager web application and its
configuration can be found here:
http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html
CARIS Spatial Fusion Viewer Reference Guide
167
Monitoring User Connections with Apache Server: View active sessions using Apache Tomcat
168
CARIS Spatial Fusion Viewer Reference Guide
F
Secure Sockets Layer
This appendix describes how the Secure Sockets Layer can be enabled
as part of HTTPS.
In this chapter...
SECURE SOCKETS LAYER ............................................ 170
SECURING A SERVER .................................................. 170
CONNECTING TO SECURED SERVERS............................. 171
Secure Sockets Layer: Secure Sockets Layer
Secure Sockets Layer
This section considers two situations in the context of secured
connections using Secure Sockets Layer (SSL):
• Securing the server that serves the web application
• Connecting the web application to secured servers
Securing a Server
When a server is secured, an encrypted link can be established
between the server and clients that connect to it. In this context
the server is the application that serves the web application.
Examples of servers are Apache Web Server and Apache
Tomcat.
Please refer to the appropriate documentation for the server that
hosts the web application. Documentation for Apache Tomcat
can be found at:
http://tomcat.apache.org/tomcat-8.0-doc/ssl-howto.html
The Java keytool command interface is used in the context of
Apache Tomcat. This is distributed with JRE. If you are creating
a self-signed certificate and need to add this to the truststore of a
client application (see “SCENARIO 2” ON PAGE 172) the -exportcert
command is used. See the following link for more information:
http://tomcat.apache.org/tomcat-8.0-doc/ssl-howto.html
170
CARIS Spatial Fusion Viewer Reference Guide
Secure Sockets Layer: Secure Sockets Layer
Documentation for Apache Web Server can be found at:
http://httpd.apache.org/docs/2.4/ssl/ssl_howto.html
Connecting to Secured Servers
Introduction
This section discusses connecting the web application to a
secured server. This would occur if, for example, the web
application needed to communicate with an LDAP server that is
secured with SSL (LDAPS). In this context the web application
is acting as a client.
No configuration changes are made to the web application. The
changes, if necessary, are made to the configuration of the Java
Runtime Environment (JRE).
We consider two scenarios.
• Scenario 1 - the secured server has a certificate issued by a
Certificate Authority
• Scenario 2 - the secured server has a self-signed certificate
CARIS Spatial Fusion Viewer Reference Guide
171
Secure Sockets Layer: Secure Sockets Layer
Scenario 1
If the secured server has a public key certificate that is issued by
a Certificate Authority there should not be a need to make
configuration changes to the JRE.
Scenario 2
Certificates are needed to establish trust between two entities.
In some cases an organization may create its own certificates,
referred to as self-signed public key certificates. These
certificates will not be available to a client application by
default. A self-signed certificate will need to be explicitly
imported into the configuration of a client in order to establish
the trust and to allow secure communication between the client
and server. This will be done by the administrator of the client.
A public key certificate needs to be obtained for each of the
secured servers that the web application will be connected to.
You should contact the administrator of the secured servers and
ask for the self-signed public key certificates.
If you are the administrator of the server and the client you
should read the section about securing the server. You will find
information on how to create self-signed certificates at the links
provided.
The self-signed certificate needs to be imported into the Java
keystore. This is known as the truststore when used in the
client-side of the connection. This keystore will contain
certificates that the web application trusts. The import step is
accomplished using the -importcert command of the keytool
command interface. See the following link for more information:
http://docs.oracle.com/javase/8/docs/technotes/tools/windows/
keytool.html
It is not recommended to use the default keystore as the
truststore. The -file is used with the -importcert command to
specify the location of the truststore. If the file does not exist it is
created automatically during the import process.
It is not recommended that the location of the truststore is set
within the JRE deployment. This is to avoid a situation in which
the truststore might be inadvertently removed during an
upgrade of JRE. If the truststore is removed it can be recreated
by repeating the import process.
172
CARIS Spatial Fusion Viewer Reference Guide
Secure Sockets Layer: Secure Sockets Layer
The following Java options are used to configure the Java
environment of the web application so it can use the truststore.
These Java options must be set.
Java Option Name
Description
javax.net.ssl.trustStore
The value of this Java option is a path to the location of the
truststore containing self-signed certificates that are trusted by the
web application. Forward slashes must be used instead of
backslashes on a Windows environment.
javax.net.ssl.trustStorePassword
The value of this Java option is the password for the truststore that
is found in the location specified by the javax.net.ssl.trustStore Java
option.
The Java options must be set with the standard syntax.
-DjavaOptionName=Value
For example, to set the location of the truststore the following
syntax would be used:
-Djavax.net.ssl.trustStore=C:/truststore/trustedcerts.jks
The Java options can be set using the Tomcat GUI application
that is used to configure the Tomcat instance that hosts the web
application. The Java options are set in the Java Options text box
that is found on the Java tab. Tomcat must be restarted after
adding the Java options.
CARIS Spatial Fusion Viewer Reference Guide
173
Secure Sockets Layer: Secure Sockets Layer
174
CARIS Spatial Fusion Viewer Reference Guide