URN Mapper Configuration#
Configuration#
System configuration is changed via the provided values.yaml file. The
datapools section defines mapping rules for each external data source the
system can connect to. By default, no rules are active except for any predefined
examples provided as part of the installation.
Note
The default example rules cannot be disabled (even if removed from configuration) and are only part of the configuration as examples.
# Set data pools for external data sources. These define how data is accessed or
# how inputs should be rewritten. The system will attempt to download data from
# the given URLTemplate and use the data as input for transcoding.
#
# Either URN or regex must be set. URN provides a more simplified way to define
# abstract identifiers for data sources. Regex allows for more complex matching
# of URLs.
#
# For URN templates, ${n} is the n-th value in the URN separated after
# urn:namespace:specifier:xxx
# e.g.: urn:x-i3d:shape:sphere (${1} == sphere)
#
# For regex templates, ${n} is the n-th capture group value in the regex.
# Capture groups are defined by parentheses in the regex.
datapools:
- urn: urn:x-i3d:shape
urlContentType: # optional
- "x3d-xml"
urlTemplate: http://i3dhub-entrygw:8080/repo/shapes/${1}.x3d
To define a new rule, you can add a new custom entry in the datapools section:
datapools:
- urn: urn:customer:document-uuid
urlContentType: # optional
- "openjt"
urlTemplate: https://download.example.com/documents/${1}.jt
authUrlTemplate: https://auth.example.com/documents/${1}.jt # optional
This will create a new URN in the form of urn:customer:document-uuid:12345 which will then internally resolve to https://download.example.com/documents/12345.jt.
Below is an example that uses a regex pattern instead of a URN for the datapools
configuration:
datapools:
- regex: "https://example.com/(.*)"
urlContentType: # optional
- "openjt"
urlTemplate: https://example.com/rewritten/${1}.jt # optional
authUrlTemplate: https://auth.example.com/${1}.jt # optional
This will match URLs in the form of https://example.com/somepath and internally
resolve them to https://example.com/rewritten/somepath.jt. Allowed syntax can
be found here. The examples above include
a separate authUrlTemplate. This is optional. Please see the values.yaml
for further information how to set forwardCookies and forwardHeaders
to pass information required for your authorization implementation.
Mapping Logic#
Note
The mapping logic was simplified and extended in version 3.10. The previous versions used an order independent implementation. The newer version uses a first-match approach, regardless of URN or regex match.
The mapper itself applies very simple logic to resolve a URN or regex to a URL:
Iterate over the datapool configration, picking the first matching rule. A match is defined as either a URN prefix match or regex match.
If the match is a regex-based rule:
The regex pattern is matched against the incoming URL, and capture groups are assigned to
${1},${2},${3}…If a
urlTemplateis provided, replace any${n}values in the givenurlTemplateby their values parsed from the regex match.If the
urlTemplateis not provided, the incoming URL is used as the result.If an
authUrlTemplateis provided, replace any${n}values in the givenauthUrlTemplateby their values parsed from the regex match.If the
authUrlTemplateis not provided, theurlTemplateis used for the auth URL as well.If
forwardHeadersorforwardCookiesis set, the headers or cookies from the incoming request are forwarded to the auth URL.
If the match is a URN-based rule:
Arguments are split (separated by
:) following the matched prefix and assigning to${1},${2},${3}…${n}values in the requiredurlTemplateare replaced by their values parsed from the URN.If an
authUrlTemplateis provided, replace any${n}values in the givenauthUrlTemplateby their values parsed from the URN.If the
authUrlTemplateis not provided, theurlTemplateis used for the auth URL as well.If
forwardHeadersorforwardCookiesis set, the headers or cookies from the incoming request are forwarded to the auth URL.