IdMaps

IdMaps are defined to map internal location and parameter ID's to external location and parameter ID's. The configuration of these can be done in two ways. In the first separate mappings can be defined for the locations and for the parameters. Although this is the most efficient method, it is not suitable in all cases, as specific locations may require a different mapping. A second definition can be created where the mapping is done on the basis of the unique combination of location/parameter. Each IdMap configuration may only use one method of defining mappings to avoid ambiguity.

In older FEWS versions each IdMap configured must be registered in the IdMapsDescriptors configuration (see Regional Configuration). The Id used in registering the IdMap is the same as the name of the configuration. In more recent versions of FEWS (2010 and later) this is no longer necessary.

When available on the file system, the name of the XML file for configuring an IdMap called for example ImportNWP may be:

ImportNWP 1.00 default.xml

ImportNWP

Fixed file name for the ImportNWP IdMap.

1.00

Version number

default

Unit to indicate the version is the default configuration (otherwise omitted).


Figure 155 Root element of the IdMaps configuration

parameter

Mapping of internal to external parameters. Multiple entries may exist.

Attributes;

  • internal : Internal parameter Id (must be in the parameters configuration)
  • external : External parameter Id (free format string)

externalQualifier : Optional additional qualifier to uniquely identify a parameter (for use in conjunction with EA-XML schema only.

location

Mapping of internal to external location Id's. Multiple entries may exist.

Attributes;

  • internal : internal location Id (must be in the location configuration )
  • external : external location Id (free format string)

map

Parameter/location mapping using unique combination. Multiple entries may exist.

Attributes;

  • internalModuleInstance  : Since 2020.01. Internal module instance Id (must be in the module instance descriptors configuration)
  • internalParameter : Internal parameter Id (must be in the parameters configuration)
  • internalLocation : internal location Id (must be in the location configuration )
  • internalQualifier : Optional internal qualifier
  • internalQualifierN (N=1..4) : Optional additional internal qualifier
  • internalEnsembleId : Optional internal ensemble id
  • internalEnsembleMemberIndex : Optional internal ensemble member index
  • internalEnsembleMemberId : Optional. Can be used instead of the internalEnsembleMemberIndex when the id is not an integer.
  • externalParameter : External parameter Id (free format string)
  • externalLocation : external location Id (free format string)
  • externalQualifier : Optional external qualifier. The file format must support qualifiers for this (e.g. EA-XML).
  • externalQualifierN (N=1..4) : Optional additional external qualifiers.
  • externalEnsemble : Optional external ensemble id.
  • externalEnsembleMemberIndex : Optional external member
  • externalEnsembleMemberId : Optional. Can be used instead of the externalEnsembleMemberIndex when the id is not an integer. Only works when non integer member ids are supported by the file format.

Qualifier and ensemble member and index can be specified only for external or internal.
e.g. You can map different external parameters to one internal parameter and different ensemble members.

options

enableOneToOneMapping

When one to one mapping is enabled the internal id's are used as external ids when not mapped explicitly. When this option is not enabled the id map also acts as a filter when at least one location is mapped explicitly (using for example <location>). In that case, everything that is not mapped is not imported or exported. When not one location is mapped explicitly, enableOneToOneMapping is enabled by default but is good practice to explicitly configure the xml element. Note that the filtering option for exporting does not work in combination with the export option to write separate files per location through the data export option <useExternalLocationIdAsName>.

When FEWS imports timeseries with enableOneToOneMapping, it uses quite some flexibility for mapping. First it tries to match exactly on location, parameter, qualifiers, ensembleId, ensembleMemberId and timeStep. But if that does not result in a match it tries to match with fewer keys, by ignoring first ensembleId, then ensembleMemberId, then timeStep, and at last qualifiers. This could cause different timeseries to be imported to the same timeSeriesSet, for instance when two timeseries are imported that only differ based on a qualifier and one of the timeseries does not have an exact match on a configured timeSeries Set. A warning will then be logged: "Multiple time series sets found for XXX" and it may be in unclear from which time series the data will be imported. This can be prevented by adding a configured timeSeriesSet that does match exactly, but that is only imported as a temporary series (and thereafter ignored). This can be done by defining <timeSeriesType>temporary</timeSeriesType>, the preferred way, or setting <synchLevel>9</synchLevel>.

enableCaseInsensitivity

When case insensitivity is enabled the mapping of external to internal ID's will be case insensitive during imports.

ignoreExternalQualifiersWhenMappingToInternal

Allow mapping of external id's with qualifiers to internal id's where the external qualifiers are optional. See the following example where the parameter P.meting is mapped to the external NEERSG parameter with some external qualifiers. When the ignoreExternalQualifiersWhenMappingToInternal is used in the idMapping configuration, the external parameter NEERSG will be mapped to P.meting.

    <parameter internal="P.meting" external="NEERSG" externalQualifier="mm" externalQualifier1="NVT" externalQualifier2="LT"/>

A typical use case is using the FEWS PI Service with the EXPORT_ID_MAP_ID configured in the FEWS Web Services Configuration FewsPiService.properties (deprecated since 2022.02).


  • No labels

Disclaimer