Export the App-Schema mapping configuration

The core functionality of the plug-in comes into play when the alignment is exported as an App-Schema mapping configuration.

A complete App-Schema mapping configuration requires a number of files, the most important being the mapping file.
A mapping file defines, for all mapped feature types, the data source and the mappings from the source data to XPaths in the output XML. The plug-in may split the mapping file in two: a main mapping file, named after the target schema, where the definitions of top level feature types (i.e. types actually derived from gml:AbstractFeatureType, which will be individually queryable via WFS) are stored, and a secondary file, always called includedTypes.xml, containing the mappings for non-feature types and alternative mappings for the feature types configured in the main file.

Additional details on the files required by an App-Schema configuration can be found here and here.

The export wizard comprises several steps, which will be described in this section.

Choosing an export format

The first step consists in choosing the export format.

The options highlighted in the figure above represent two complementary export approaches:

  1. App-Schema Configuration: the configuration is saved to one or more files, which must be manually copied / extracted to the right place in the GeoServer data directory. This approach may be preferred during testing, or when a live GeoServer instance is not available or not accessible.
    This option can be further differentiated based on the type of the generated file(s):
  2. App-Schema Configuration [Direct Upload]: the configuration is generated and immediately uploaded to GeoServer via its REST API. This approach is more convenient and should generally be preferred. If this option is chosen, the wizard will also ask the user to specify the URL of the GeoServer instance to target (e.g. http://localhost:8080/geoserver) and credentials to access its REST services.

Including the target schema

If the Include target schema in the archive option is checked, the imported target schema, including all its dependencies, will be added to the exported archive and uploaded to GeoServer along with the mapping configuration.

This option may be useful when GeoServer is running on a server with no internet connectivity and is thus unable to download the required schemas from the web. However, in general it should be left unchecked, to maximize schema reuse among App-Schema datastores via GeoServer's centralized App-Schema cache.

Configuring Feature Chaining

If the alignment defines at least one Join relation, the wizard will ask the user to configure Feature Chaining. Feature Chaining is the mechanism by which App-Schema builds up complex types by composing simpler components. For example, a gsml:GeologicUnit contains one or more gsml:CompositionPart instances, which are nested in its multi-valued gsml:composition property.

To chain components, App-Schema needs to know:

  1. which field in the container and nested source types refer to each other (similar to a foreing key in a relational database)
  2. which (often multi-valued) property of the container target type will hold the instance(s) of the nested target type

The HALE Join relation does provide for 1., but not for 2. This is the reason why a additional configuration is required to make Feature Chaining function properly.

The user will be presented with one configuration dialog for each join condition that was defined (even if the Join involves more than two types, Feature Chaining is always configured pair-wise). The figure below shows a sample chaining configuration dialog.

The upper part of the dialog contains a read-only table displaying the current configuration, while the bottom part contains a schema explorer view, showing all the properties of the target type of the whole Join relation, and, further down, a checkbox.

The table is composed of four columns:

As the dialog is opened the first time, all cells in the table are filled automatically, except the nested type's target: that is what must be selected in the schema explorer view. In this example, the user navigated to the gsml:GeologicUnit/gsml:composition/gsml:CompositionPart property and clicked on it: the Target Type column in the second table row was populated with the value gsml:CompositionPart, as shown in the figure above. This configuration is telling GeoServer both that the gsml_CompositionPart source type should be mapped to the gsml:CompositionPart type, and that gsml:CompositionPart instances should be nested under the gsml:composition attribute of the gsml:GeologicUnit type.
It is worth noting that the selection is restricted to the mapping relevant target types. To learn how to edit the set of mapping relevant types, see the this section in the user guide.

The Generate unique mapping for nested target type checkbox should be checked if one wants to provide alternative mappings for a target feature type (e.g. different source types that should map to the same target type).

Real world examples of complex Feature Chaining configurations can be found in the Complex Features Training by GeoSolutions.

Configuring the source data store

The App-Schema mapping file requires that data sources be specified in the sourceDataStores section. Although the GeoServer App-Schema extension supports a variety of data store types and multiple data store configurations, the HALE App-Schema plug-in only allows to configure a single PostGIS data store. This limitation will likely be removed (or at least alleviated) in future releases of the plugin.

A sample data store configuration dialog is depicted in the figure below.

The configuration settings should be pretty straight forward. However, it is worth mentioning that the Expose primary keys option must be checked if primary key columns are used in attribute mappings.

Providing REST credentials

If App-Schema Configuration [Direct Upload] was chosen as export format, the last configuration dialog in the export wizard will ask the user to provide credentials to access GeoServer's REST services.