Partner Filesystem Theory

Overview

The Partner installation filesystem is designed to rigorously separate files by their role in the system. This simplifies troubleshooting and updates, and guides placement of new files as the need arises.

See Partner Filesystem Contents for an outline view of the filesystem and its contents. This section describes the theory and design.

Portions marked (v5) are associated with the version 5 implementation of the filesystem, introduced with Update v5. Similarly, portions marked (v3) are associated with legacy v3x code in the Field Designer.

Categorizing Files

Files are grouped according to the following major characteristics:

  • role - the type of file it is, and the role it plays in the system
  • config level - who owns the file, and is allowed to change it
  • module - which module a file is included in, or is associated with
  • mapset - since much of the system is driven by map set definitions

role

A file’s role is considered its most important characteristic. It is one of the following:

  • archive - archive and backup files
  • config - configuration or customization file; modifies the system’s appearance or behavior
  • data - data generated during use of the software, containing the actual business information of the system
  • extensions (v5) - third-party and customer extensions (proposed)
  • input - input files, generally for the Map Publisher
  • log - log files are generated by all parts of the software, and are critical for troubleshooting
  • maintenance (v5) - maintenance companion installations
  • maps - published map set data, generated by the Map Publisher
  • modules - pluggable modules
  • os - operating system-specific files such as native libraries or launch files
  • programs (v5) - executable program launcher files
  • system - generic files that define the actual software product
  • temp - temporary files, generally deleted on startup or shutdown
  • update - update system files
  • v3x (v3) - FieldDesigner legacy files

These roles are represented as top-level directories in the filesystem.

config level

The Partner Update system establishes a top-down hierarchy of installations, where each install is updated from a more general and authoritative source. The topmost level of this is the Partner distribution itself, which resides on our web site. The bottommost level is an individual end-user install. This hierarchy is represented in the filesystem as “Config Levels”.

Here are the config levels from top to bottom:

  • distribution - the official Partner release, completely generic
  • provider - adds extensions and product-specific components for a distributor or integrator of the software
  • customer - adds customer-specific configuration and extensions
  • hub - works the same as customer, but only applies to server-type installations
  • site - adds configuration and extensions specific to a district, local office or other subgroup
  • seat - configuration, data, preferences, and other things specific to a single installation

These roles are represented as subdirectories of the top-level directories config/, modules/, and (in v5) maps/.

Distribution is a special case: distribution files are stored in the top-level directories os/ and system/.

module

Since version 4.4, much of the functionality of the Partner System has migrated from the core platform to pluggable modules.

Modules must have a unique, computer-friendly name, and this is used to identify the module throughout the software and filesystem.

mapset

Mapsets are a critical part of Partner system configuration. A customer may have one or more mapsets, containing dynamic or static map data or map imagery. Most of the behavior of the Map Viewer is driven by these mapsets.

Mapsets must have a unique, computer-friendly name, and this is used to identify the mapset throughout the software and filesystem.

Principles

Most specific

The principle of “most specific” means that, where files may be placed in system, config/provider, config/customer, etc., the most specific one should be used. In other words, if you have two mapset definitions with the same name “Turtle”, one in config/customer/mapsets/Turtle/ and one in config/seat/mapsets/Turtle/, the one in config/seat/ should take precedence. This allows customization and testing of new configurations at a local level before they are posted to the rest of the users on the system.

Some files are merged as well. For example, any host name in config/site/misc/hosts.xml will take precedence over the same host name listed in config/customer/site/misc/hosts.xml. This is useful to e.g. define “PartnerHub” to point to a specific district hub, rather than to the central office hub.

However, you shouldn’t assume a particular merging behavior without understanding the way that file or portion of the filesystem is handled.

Configure-test-post

A common pattern in the system is that new configurations or changes can be configured and tested locally before posting to the Central Hub. The principle of “most specific” allows this behavior.

Mapset maintenance is done at a specific seat of the software. The person running this installation is the designated maintainer of that map set. Each map set may have a different maintenance seat and maintainer, however.

Maintenance and testing is done within the config/seat/ part of the filesystem. Once the results are satisfactory, they are posted to the Central Hub into the config/customer/ (or config/site/) part of the filesystem.

This work flow prevents problems in updating. The maintenance seat can still be updated (e.g. to get a new version of the software), but that won’t affect the config/seat/ hierarchy.

The publisher uses this model. All configuration is done in config/seat, and publisher modules live in modules/seat. The results of a publish are placed in maps/, and then posted to the Central Hub for distribution to other users.

Consistency

Wherever possible, the directory names used will be the same in different sections of the filesystem. For example, config/provider/, config/customer/, config/site/, and config/seat/ can all have the same directories underneath them. And the operating-system-specific directories os/linux/, os/mac/, os/windows/, os/palm/, and os/pocketpc/ all have the same directories under them as well.

This can be confusing if you get lost in the filesystem, but in general is a Good Thing.

Distinguishing built-in files and directories from custom ones

As a general convention, the predefined files and directories are named in lower case, while user-named or module-named ones use bicapitalization.

So, for example, config/customer/mapsets/ is a system-defined directory, but “config/customer/mapsets/Tracing/” is the tracing mapset from the Tracing module.

Only Create It If You Need It

Empty directories or unnecessary files are left out in the interest of simplicity and to save storage space. If you need certain directories in order to place a new file, go ahead and create them.