JMap Server Management

Table of contents

1. JMap Server Status
2. Exporting and Importing
3. User Data
4. JMap Server Settings
5. Usage Statistics
6. Log Files
7. Messages
8. JMap Server System Database
9. Backups
10. High Availability

---

The following sections cover JMap Server management tasks.

JMap Server Status

The Status section of JMap Admin provides a lot of useful information for monitoring JMap Server. Additionally, this section provides detailed information on your license agreement. Each part is explained below.

Exporting and Importing

Exporting and importing the JMap configuration

Your JMap Server configuration (spatial data sources, databases, projects, layers, etc.) is stored on a disk in binary format. This configuration is only accessible by JMap Server and is only compatible with your current version (main version, e.g. 7.X). Using the export tool, a text version of this configuration can be produced. This exported configuration can then be imported back into JMap Server, with the same settings or different ones. The configuration can even be exported to a newer version. Here are a few examples where exporting and importing your configuration can be useful:

• You installed a new version of JMap with major changes and you want to reuse your existing configuration. You can export the configuration from your older JMap version and then import it in the newer version.

• You manage many instances of JMap Server and you need to move a project from one instance to another. You can do a partial export to move only the project you need and then import it in the other instance.

• You need to replicate your development environment to the production environment. You can do a full export from your development server and then import it in the production server.

To access export and import tools, select Import / Export in the JMap Server section.

Exporting

When exporting a configuration, you must choose whether you want to export the complete configuration or some specific resources (partial exportation). If you choose to export specific resources, you must select if you want to export databases, spatial data sources, projects, style templates or metadata templates. There is a dependency relationship between these different resources: projects depend on spatial data sources and style templates while spatial data sources may depend on databases. Consequently, if you export a project, then spatial data sources, style templates, and possibly databases will also be exported.

The exportation process creates up to 4 files: the .properties file is the main exportation file and contains the configuration information. All files are necessary for the importation. You can determine the destination directory and file name.

Importing

When importing a configuration, you have the choice to import a complete configuration (complete importation) or only a portion of it (partial importation). You can only do a complete importation if the exportation files contain a complete exportation. When doing a complete importation, any existing configuration in JMap Server is deleted and replaced by the imported configuration. When a full importation is completed, you will automatically be sent back to the JMap Admin login page.

When doing a partial importation, there may be situations where the imported resources already exist (identical names). In these cases, you have to tell JMap Admin which action to take: replace the existing resource or create a new one with a different name. The file type data sources that you import are not ready to use and must be updated after the importation.

Exporting and importing JMap user data

JMap user data includes all data created or modified by users. This includes user preferences, contexts, personal layers, data from editable JMap layers, etc. If you change JMap Server instances and you wish to keep all existing user data, you must export it from the previous server and import it into the new server.

The configuration file for the export and import of user data is a .properties file. For a successful export / import, validate that this file contains the following line:

project.id.ID_OF_THE_PROJECT_BEFORE_EXPORT=ID_OF_THE_PROJECT_AFTER_EXPORT_SERVER_CONFIGURATION.

Exporting

When you export user data, you must decide whether to export all data, only the editable layers stored in JMap (including personal layers) or only the workspaces (including contexts, user preferences, etc.).

Importing

When you import user data, there may be situations where imported resources already existed (identical names). In these cases, you must indicate which action JMap Admin must take: replace the existing resource or create a new one under a different name.

User Data

JMap application users can generate certain data that will be stored in the JMap Server environment.

This can include various types of data, including user preferences (choice of units, print settings, etc.), map contexts (JMap Pro and JMap Web) and customized print layouts.

Map context data is stored in JSON format in the JMAP_CONTEXTS table of the System database.

Non-context data is stored in separate folders for each user. The parent folder of these user folders is

JMAP_HOME\workspaces<username>

Note that this folder can have a different location if you indicate a different folder in the server.workspaces.path line of the jmapserver.properties file and manually copy the files and subfolders.

In some cases, the administrator may have to copy certain files when a migration occurs or when these files need to be shared with other users. The following sections describe each of these situations in detail.

Note that the functions to export and import JMap configurations also handle user data.

Contexts

Map contexts are comprised of all the parameters that allow a JMap Pro or JMap Web user to recreate a geographic map. Contexts can be used to save maps and even share them between users. Existing contexts can be recalled easily to recreate a map environment. All layer parameters, annotations, thematics, selections, etc. are part of the context and are recreated when the context is opened.

A context is associated with the project in which it was created. It cannot be accessed in other projects.

Personal Layers

The Personal Layers section provides more information on managing personal layers and how to make them public. The data from personal layers is not stored in the workspaces folder; instead, it is saved directly in JMap Server’s System database (one table per personal layer).

Export and import tools can handle the data of personal layers.

JMap Spatial Tables

As with personal layers, the data from editable layers of JMap projects is stored directly in JMap Server’s System database, in tables that are called JMap Spatial tables.

Export and import tools can handle the data from JMap Spatial tables.

Print Layouts

The users of JMap Pro applications can create their own print layouts. The files are stored in the folder

JMAP_HOME\workspaces<username>\printLayouts

The print layouts created by users can be made public. To do this, you must copy the files in the following directory:

JMAP_HOME\workspaces\public\printLayouts.

Public print layouts can be accessed by all JMap Pro users.

JMap Server Settings

These parameters have an impact on the behaviour and performances of a JMap Server system. Press Save to save all modifications. Click on to reread parameters from configuration files if they have changed. The configuration files are located in JMAP_HOME/conf.

Usage Statistics

Usage statistics offer the JMap administrator information on the usage of projects, layers, and contexts. JMap Server records some of the users’ activity and allows you to generate reports, which contain statistics on the use of resources in JMap Pro and JMap Web applications. This data can be useful to assess the relevance of projects or layers that are seldom or never used.

In order for usage data to be recorded, you must select the Usage statistics option when creating or editing a project. For more details on this topic, refer to the Creating Projects section. When exporting or importing your project, your choice will be saved in the exported configuration.

Thus, whenever a user opens a project, views a layer, or views or creates a context in a JMap Pro or JMap Web application, this activity will be automatically recorded in a temporal table of the System database. Every night, at a set time, the data will be aggregated into two tables (JMAP_STATISTICS_MONTHLY and JMAP_STATISTICS_YEARLY), and it will then be displayed in this section of JMap Admin. The data aggregation frequency can be configured in JMap’s settings. To do so, you must modify the server.statistics.config.cron variable in the jmapserver.properties file that is found in the JMap_HOME/conf folder. This page http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html offers details about cron expressions. Information about the activity of users who were deleted is recorded in both tables. The details of the aggregation functions are found in JMap Admin’s REST API.

Information entered in the temporal table will differ slightly between JMap Pro and JMap Web applications. Usage data originating from JMap Pro will be saved when the JMap Pro application is closed, or when the project is closed because the user has switched to another project.

Calculating statistics

Click on Apply to generate the statistics by project. Click on Reset to delete the statistics.

Click on Apply to generate the statistics by layer. Click on Reset to delete the statistics.

Select the filter you wish to use and click on Apply to display the settings used to define the calculation. Once the settings have been completed, click on Apply again to produce the statistics. Click on Reset to delete the statistics.

Exporting reports

You can export the generated report in Excel or PDF format. To do so, once the statistics have been calculated, click on Excel or PDF to automatically download a file in the selected format.

Log Files

Log files contain information on the activities that are performed in JMap Server. The quantity of events written in the log files depends on the selected logging level. By default, a new log file is created every day but this parameter can be adjusted. By default, log files are located in the directory JMAP_HOME/logs. You may need to periodically check the volume of the log files and archive or delete old ones.

Viewing log files

Log files (and error files) can be viewed directly in JMap Admin. Select the name of a file from the list to open it. The content of the file is displayed. Note that error files are also listed along with log files. The error files contain only error messages that can sometimes complement the log files to help solve a problem.

The view window allows you to filter the content by event type, date, keyword, etc. You can also download the file by clicking on Download.

Analyzing log files

Log files can be analyzed in order to provide a summary of the activity of JMap Server. For instance, they can inform you of the number of sessions for each user, the number of server shutdowns, authentication failures, etc. To analyze log files, select one or more files in the list and click on .

Messages

As the administrator, you can send messages to JMap users from JMap Admin. The messages will be displayed in the user interface (JMap Pro applications only). Users who already have an active session will see the messages immediately. The other users will see the message the next time they log on. Messages can be used to inform users of service interruptions, for example. Messages will be displayed each time a user starts a new session, during the validity period of the message.

Sending messages

To create a new message to be sent to all users, press Create from the Messaging section.

Deleting messages

To delete a message before it expires, select it in the table and press Delete.

JMap Server System Database

JMap Server’s System database is a relational database that stores important data for JMap Server. User account and group data is stored in this database if you are using JMap Server’s built-in user manager. This is not the case if you are using another user manager (e.g.: LDAP/Active Directory). Also, when spatial data sources read their data from files (SHP, MIF, DWG, etc.), the geometry and descriptive data read from the files are inserted in tables of the System database. There is one data table per such data source, as well as spatial index tables that speed up data extraction. Personal layers created by the users as well as JMap Spatial tables are also stored in the System database.

The relational database management system (RDBMS) used by default for storing JMap Server’s System databases is Apache Derby. It is embedded in JMap Server and requires no maintenance. This system is suitable for publishing small to medium spatial data volumes or for test environments. For more robust and powerful systems, you should use another relational database management system. See the list of compatible systems below. By default, Derby’s database files are located under the directory JMAP_HOME/db/database. Never delete or alter any file located in this directory.

Moving the JMap Server System database to another environment

JMap Server’s System database can be moved to another RDBMS easily. You may want to do it for scalability or performance reasons or to take advantage of more advanced features such as backups. There are 4 other officially supported RDBMS for storing the JMap System database:

Note that other RDBMS and versions will also probably be supported because JMap Server uses mostly very common and simple database functions.

To store the System database, you should use a database or schema that is reserved exclusively for JMap. The user account that established the connection must have sufficient privileges to select, insert, create, and delete tables and indexes.

To move the System database towards another RDBMS, you must modify the database called System in JMap Admin. Select the database driver and connection parameters associated with the environment of the new System database. JMap Server will automatically create the required tables in the new database.

After the System database is moved, any spatial data source that reads vector data files will have a Not ready status. It will need to be updated before it can be used. Other types of data sources (raster, Oracle Spatial, SDE, etc.) will not be affected.

In addition, if you move the System database, all user data from the previous database must be moved using the data import and export tool. For more information, see the Exporting and Importing section.

Backups

It is strongly recommended to make backups of the JMap Server setup.

If the JMap Server System database was moved to another RDBMS, it must be included in the backup strategy. It contains very sensitive information like personal layers data.

The simpler backup strategy is to make copies of the JMap directory and all sub-directories.

Contents of the JMap directory

If you wish to make smaller backups, you can make copies of the specific directories listed below, which contain important information.

High Availability

You can configure clusters of JMap servers to create highly available environments. A highly available JMap environment offers the following benefits:

• Resistant to hardware and software failures.
• Improved performance.
• Improved scalability.
• No service interruptions during software updates.

Clusters of JMap servers (nodes) are peer-to-peer systems with active redundancy. This means that all nodes are equal and synchronized with each other in real time. Each change made to a node’s configuration (adding a layer, modifying a form, etc.) is immediately replicated on all of the cluster’s nodes.

Prerequisites for high availability

To configure a JMap installation in high availability mode, including the creation of server clusters, certain prerequisites must be met.

• JMap’s System database must be shared by all nodes (preferably in high availability mode).

• A file system must be shared by all nodes to store vector and raster data caches (preferably in high availability mode).

• All nodes must have a JMap license file with the same serial number.

• The IP address linked to JMap Server must be precisely defined. During the installation of JMap, you must enter the IP address of your server that will be linked to JMap Server and not use the default value 0.0.0.0. If necessary, you can run Setup again to change this value or change it manually in the JMap/conf/jmapserver.properties configuration file by editing the line starting with “server.address =”. For example server.address = 208.199.24.134.

A load balancer is usually present in a high availability architecture. This module is used to send requests to the various nodes in the cluster, in compliance with predetermined rules.

Creating a cluster of JMap servers

In order to create a cluster of JMap servers, you must have at least 2 instances of JMap Server 7 or higher, connected by a network.

When a new cluster is created, the node that creates the cluster (primary node) is the node whose configuration will be used and replicated on the other nodes when they join the cluster. Make sure you start by configuring the cluster on your server and that your server contains the proper configuration. Afterwards, when a new node will join the cluster, its configuration will be replaced by the cluster’s configuration.

The following steps describe how to create a cluster with 2 servers (A and B). Server A contains the proper JMap configuration.

1. The cluster is created on server A.

2. Server A is the primary node, and its configuration becomes the cluster’s configuration.

3. Server B becomes part of the cluster.

4. Server B’s configuration is replaced by the cluster’s configuration.

5. Servers A and B are synchronized in real time.

The primary node concept is only important when the cluster is created. Afterwards, all nodes become equal.

Clusters are configured in JMap Admin, in the Server cluster subsection of the JMap Server section.

When your configuration is complete, click on Save. A confirmation window displays, asking you to select one of the two following options. You can also cancel the operation by clicking on Cancel in the confirmation window.

Cluster status

To know the status of the cluster, you can view the list of remote nodes. These are the other nodes that are currently active in the cluster.

---