O2A Documentation

Product Configuration ​

AuthorPeter Konopatzky
Technical ContactsPeter Konopatzky, Andreas Walter
Version0.2

This document formerly lived on AWI Confluence and has been migrated here with only minor changes.

Preface ​

All GeoServer-based data products within die O2A SDI consist of three parts: input (data exchange), output (GeoServer-based OGC Web Services) and VEF integration. This specification covers how output and VEF integration can be configured by the use of the O2A SDI Data Product Configuration GitLab repository. It will contain all GeoServer-hosted layers at AWI but externally hosted OGC web services can also added to have them properly integrated into VEF-based viewers.

After having an initial talk (see SOP), we'll set up your data product within the public Data Product Configuration repository and you'll get access to directly edit it.

Parts of the configuration should only be touched by O2A SDI admins – usually indicated by filenames beginning with admin. – but some parts are designed to be directly maintained by product owners (this could be you!) – usually indicated by filenames beginning with owner. – via Git merge requests.

Multiple filetypes will be used/mentioned here. You will use TOML to configure the metadata (e.g. title and abstract) of your layers and services, SLD for styling your data on the map, Markdown and JSON to configure filter behaviour and metadata presentation in VEF-based viewers.

Repository Schema ​

The repository consists of three "levels" of folders. The first level is the "label" level, holding one folder per public GeoServer instance/label of the O2A SDI (currently: common, platforms, basemaps, projects) and one folder (_other/) for OWS hosted differently (O2A SDI ArcGIS Server, external servers). One level down in the folder structure is "workspace/service" level, where each folder represents one OWS (e.g. common/marehub/, common/media/, common/bathymetry/, platforms/expedition/). One more level down is "layer" level, where each folder represents one OWS layer or layer bundle (e.g. common/media/photos/, platforms/expedition/events/). A layer bundle usually is a set of layers with similar configuration, for example offering the same data in a different eference system.

Additionally, there are some fixed folders: _styles/ within each GeoServer instance/label folder and _resources/ which may be found on root, label, workspace/service and layer level.

_styles/ folders hold all SLD files for their associated GeoServer instance/label. SLD files are used to define how data gets rendered for WMS GetMap requests.

_resources/ folders hold files configuring a layer's filter behaviour and metadata appearance in VEF-based viewers (e.g. on Marine/Earth Data).

bash
. <repo>/configs
|-- admin.*
|
|-- <label>
|   |-- admin.*
|   |
|   |-- _styles/<SLD files>
|   |-- _resources/<resource files>
|   |
|   `-- <service/workspace>
|       |-- owner.workspace.toml
|       |-- admin.*
|       |
|       |-- _resources/<resource files>
|       |
|       `-- <layer>
|           |-- owner.layer.toml
|           |-- admin.*
|           |
|           `-- _resources
|               |-- popup.md
|               |-- sidebar.md
|               |-- gallery.mapping.json
|               `-- filter.mapping.json
|
|-- _resources/<resource files> 
|
`-- _other
    |
    `-- <arbitrary-service-id>
        |-- owner.urls
        |
        |-- _resources/<resource files>
        |
        `-- <layer>/_resources/<resource files>

_resources folders (on all levels) ​

A _recources/ subfolder, independent of its location (root level, label level, service/workspace level, layer level), contains files to influence the presentation and behaviour in VEF-based viewers (like the Marine Data viewer). There will be no effect when loading the OWS in any other client (like ArcGIS, QGIS, other mapping apps).

There are three sorts of files supported. VEF Metadata Template files take care of metadata presentation in VEF popups and the VEF sidebar. They are recommended for each and every layer. VEF Mapping files take care of frontend-side filter harmonization and media gallery behaviour. These files are only used in special cases. Specific documentation can be found here:

  • VEF Metadata Template files (*.md), to configure presentation of your data in popups and sidebar → see VEF Metadata Templates
  • VEF Filter Mapping files (*.mapping.json) → see VEF Mapping
  • VEF Gallery Mapping files (*.mapping.json) → see VEF Mapping

In general files with specific names inside _resources/ folders will get used automatically. These names are:

  • popup.md (VEF Metadata Template for popups)
  • sidebar.md (VEF Metadata Template for the sidebar)
  • filter.mapping.json (VEF Filter Mapping)
  • gallery.mapping.json (VEF Gallery Mapping)

For each layer used in VEF-based viewers, the file within its own _recources/ folder is prioritised over that in its workspace-level _resources/ folder and so on. This boils down to this priority list:

  1. <label>/<workspace>/<layer>/_resources/<file-by-convention>
  2. <label>/<workspace>/_resources/<file-by-convention>
  3. <label>/_resources/<file-by-convention>
  4. _resources/<file-by-convention>

However, the resources section of the owner.layer.toml (see subsection) file can be used to overwrite this convention with specific filenames (not filepaths) overwriting the convention, resulting in this final priority list:

  1. <label>/<workspace>/<layer>/_resources/<file-from-layer-configuration-if-existing>
  2. <label>/<workspace>/_resources/<file-from-layer-configuration-if-existing>
  3. <label>/_resources/<file-from-layer-configuration-if-existing>
  4. _resources/<file-from-layer-configuration-if-existing>
  5. <label>/<workspace>/<layer>/_resources/<file-by-convention>
  6. <label>/<workspace>/_resources/<file-by-convention>
  7. <label>/_resources/<file-by-convention>
  8. _resources/<file-by-convention>

File Specs ​

Admin vs. Owner Files ​

On any level there might be files prefixed with admin. or owner., like common/media/photos/admin.layer.toml or common/media/owner.workspace.toml.

The admin. files are only to be created and edited by SDI admins. All owner. files are to be created by admins and can be edited by data product owners to change some parts of the configuration themselves. How to do this is described here.

SLD files in _styles/ folders and files in _recources/ folders can be created and edited by data product owners.

Label Level ​

A label is a GeoServer instance within the O2A SDI. Currently there are four labels: common, platforms, basemaps amd projects. There's also a <label>/_styles/ subfolder – used to store all SLD files used for all layers of all services within this GeoServer label/instance – and a <label>/_resources/ subfolder which can be used to provide resources for representation in VEF-based viewers which should be shared among multiple services and layers of this label/instance to avoid placing copies in each layer's subfolders.

_styles/*.sld ​

Put your SLD files here. Take care, that the filename matches the actual name of the XML-defined style.

owner.workspace.toml ​

A service/workspace folder refers to a workspace within a GeoServer instance/label and results in a WMS of the same name (and possibly other services like WFS and WPS). Additionally an OWS has a human-readable title, an abstract and optional keywords – just like a scientific paper. These metadata can be specified in <label>/<workspace>/owner.workspace.toml. There's also a <workspace>/_resources/ subfolder which can be used to provide resources which should be shared among multiple layers of this service (see section on resource handling).

sectionkeyvalue typerequiredvalue description
titlestringyesHuman-readable title of the workspace (used as title for all contained OWS: WMS, WFS, WCS).
abstractstringyesAbstract, describing the service's content. VEF (Marine Data Viewer) supports Markdown URL representation (<http://www.marine-data.de> or [Marine Data](http://www.marine-data.de>)) and HTML (like <br><br>, <a></a>).
keywordsstring listno

owner.layer.toml ​

A layer folder results in one or more layers within the OWS represented by its parent service/workspace-level folder.

A layer has a human-readable title, an abstract and optional keywords – just like a scientific paper. These metadata can be specified in <label>/<workspace>/<layer>/owner.layer.toml. Additionally default and alternative styles (referencing SLD files in <label>/_styles/) and VEF resources can be specified. If desired the default mechanism of auto-deploying changes to the GeoServer (styles, metadata) and/or VEF (resources) can be deactivated.

The following table is for single-layer folders. In case of a layer-bundle folder, put its content either in [main] or [<layer name>] sections, e.g. main.title or photos_3031.settings.style_default. See the example.

sectionkeyvalue typerequired/defaultvalue description
roottitlestringyesHuman-readable title of the layer.
rootabstractstringyesAbstract, describing the layer's content. VEF (Marine Data Viewer) supports Markdown URL representation (<http://www.marine-data.de> or [Marine Data](http://www.marine-data.de>)) and HTML (like <br><br>, <a></a>).
rootkeywordsstring listno
settingsstyle_defaultstringyesName of the SLD file (including file extension) to use as default style. The filename needs to match the actual style name. SLD files need to go here: <label>/_styles/*.sld.
settingsstyle_alternativesstring listnoNames of SLD files (including file extension) to use as alternative styles. The filenames need to match the actual style name. SLD files need to go here: <label>/_styles/*.sld.
resourcesgallery_mappingstringno (defaults to gallery.mapping.json)Name of gallery mapping file. Only required if deviating from gallery.mapping.json.
resourcesfilter_mappingstringno (defaults tofilter.mapping.json)Name of gallery mapping file. Only required if deviating from filter.mapping.json.
resourcespopupstringno (defaults to
popup.md)		Name of popup metadata template file. Only required if deviating from popup.md.
resourcessidebarstringno (defaults to
sidebar.md )		Name of sidebar metadata template file. Only required if deviating from sidebar.md.

Layer Bundles ​

If a layer folder should define more than one layer, all configuration that should apply to all specific layers should go into the top-level section [main] (instead of on root level) and layer-specific configuration below the top-level section holding that layer's name. See the common/media/photos example.

_other Folder ​

The _other subfolder is the place to store resources for services/layers which are not hosted in the GeoServer part of the O2A SDI to be used within VEF-based viewers. This subtree only contains resource files (see above for specs), owner.urls files but neither SLD nor any other configuration files.

Within the _other subfolder each folder refers to one OWS endpoint (which could contain multiple services like WMS/WFS/WCS). The name of the subfolder (_other/<arbitrary-service-id>/) can be choosen arbitrarily but should be kind-of human-readable. Inside, there needs to be one file named owner.urls (_other/<arbitrary-service-id>/owner.urls), specifying service URLs – one per line – to which this folder's resources are dedicated. There can be subfolders like on <label>/<workspace>/ folders and the same resolve priorities apply.

Examples ​

common/media/photos ​

Taken from here: de.awi.sdi.o2a_spatial.dataproducts:configs/common/media/photos

bash
# Directory Structure
. https://gitlab.awi.de/software-engineering/sdi/de.awi.sdi.o2a_spatial.dataproducts:configs/
|
`-- common
    |
    |-- _styles
    |   |-- marehubPhotosOrange.sld  
    |   |-- marehubMediaBlueStroke.sld  
    |   `-- marehubPhotosOrangeIcon.sld 
    |
    `-- media
        |-- owner.workspace.toml
        |-- admin.workspace.toml
        |
        `-- photos
            |-- owner.layer.toml
            |-- admin.layer.toml
            |-- admin.store.toml
            |
            `-- _resources
                |-- popup.md
                |-- sidebar.md
                |-- gallery.mapping.json
                `-- filter.mapping.json
ini
title = "Media OWS"
abstract = '''
Media service with photo and video data provided by AWI, Geomar and Hereon. Curated metadata is extracted from image FAIR Digital Objects (iFDOs) (<https://marine-imaging.com/fair/>) or automatically harvested from data products in Pangaea (<https://pangaea.de/>).
'''
keywords = [ "WMS", "WFS", "MareHUB", "videos", "photos", "image", "iFDO", "PANGAEA" ]
ini
[main]

abstract = "The layer presents marine images published by various research institutes. [...]"
keywords = [ "MareHUB", "photos", "image", "PANGAEA" ]
settings.style_default = "marehubPhotosOrange"
settings.style_alternatives = [ "marehubMediaBlueStroke", "marehubPhotosOrangeIcon" ]

[photos_3031]

title = "Photos [antarctic]"

[photos_3995]

title = "Photos [arctic]"

[photos_4326]

title = "Photos"

_other/hcdc-hereon-marehub ​

This is how resources – here: metadata templates (*.md) – for an externally hosted WMS could be added. There are no layer subfolders (hence no <layer>/_resources/*.md files) so that all layers of this service would use the the metadata templates provided in _other/hcdc-hereon-marehub/_resources/.

Taken from here: de.awi.sdi.o2a_spatial.dataproducts:configs/_other/hereon_marehub

bash
# Directory Structure

. https://gitlab.awi.de/software-engineering/sdi/de.awi.sdi.o2a_spatial.dataproducts
|
`-- _other
    |
    `-- hcdc-hereon-marehub
        |-- owner.urls
        `-- _resources
            |-- popup.md
            `-- sidebar.md
tsv
# _other/hcdc-hereon-marehub/owner.urls

https://hcdc.hereon.de/geoserver/MareHub/ows
https://hcdc.hereon.de/geoserver/MareHub/wms
https://hcdc.hereon.de/geoserver/MareHub/wfs