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.
The first step consists in choosing the export format.
The options highlighted in the figure above represent two complementary export approaches:
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.
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:
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.
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.
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.