Documentation index · Catalog editor guide · Earth Sensor URI map · Operations and limitations
This reference follows the repository's sensorsearch.toml.
The file is an example deployment configuration, so backend URLs and catalog
scope should be reviewed before using it in production.
The configuration source and request timeout use consistently prefixed Django settings. The two configuration settings can also be supplied as environment variables with the same names.
| Setting | Meaning |
|---|---|
SENSORSEARCH_CONFIG_FILE_PATH |
Complete path to the TOML configuration. Takes precedence over the file name. |
SENSORSEARCH_CONFIG_FILE_NAME |
Configuration file name. Defaults to sensorsearch.toml. |
SENSORSEARCH_REQUEST_TIMEOUT |
Timeout in seconds for backend HTTP requests. Defaults to 10. |
Without an override, the repository-level sensorsearch.toml is used during
development and the identical packaged rdmo_sensorsearch/sensorsearch.toml
resource is used after installation.
The plugin parses the TOML into immutable standard-library dataclasses before constructing providers or handlers. An invalid configuration therefore fails early instead of silently turning a misspelled setting into an unused keyword argument. The exception includes the path to the failing table or setting, for example:
handlers.SensorManagementSystemConfigurationHandler.defaults: unknown setting(s): selected_device_attribute_uri
Validation currently covers:
- known sections, provider and handler class names, and settings;
- string, integer, boolean, and string-array value types;
- required SMS URLs, labels, prefixes, and handler backends;
- unique option ID prefixes and provider-to-handler prefix relationships;
- SMS configuration-to-device and O2A mission-to-item prefix relationships;
- paired and explicitly enabled SMS membership-filter start/end attributes;
- required search and configuration-membership attributes;
- explicit catalog scope for data-collection variable synchronization.
Configuration is loaded once and cached for the process lifetime. Restart the
RDMO application processes after editing the file. Tests can call
rdmo_sensorsearch.config.clear_config_cache() when switching configuration
files within one Python process.
Only the repository-level sensorsearch.toml is maintained. The wheel build
copies that exact file to rdmo_sensorsearch/sensorsearch.toml; do not maintain
a second package-local source copy.
testing/fixtures/sensorsearch-plugin-dev.toml is deliberately different: it is
a complete, generated test/example-only profile for the independently
namespaced testing/catalogs/example_catalog_sensorsearch.xml. It is not packaged or loaded
by production. Regenerate both assets with
python testing/tools/generate_plugin_dev_assets.py after changing the original
catalog or the production baseline.
| Setting | Meaning |
|---|---|
min_search_len |
Minimum number of typed characters before remote device providers are queried. |
filter_sms_devices_by_selected_configuration |
When true, SMS device search is restricted to the SMS backend matching a selected configuration. Leave false when manual searches should cover all SMS instances. |
Each [[DeviceSearchProvider.providers.<ProviderClass>]] entry enables one device
source. Multiple entries of the same class are allowed. Common provider fields
are id_prefix, text_prefix, and base_url; provider-specific URL templates
can be overridden when required.
The example enables:
O2ARegistryItemProvider;- three
SensorManagementSystemDeviceProviderinstances for GFZ, KIT, and UFZ; GIPPInstrumentProvider.
Prefixes must be unique across the aggregate provider because they are used to route a selected option to its handler.
min_search_len has the same meaning for configuration and mission search.
Each [[ConfigurationSearchProvider.providers.<ProviderClass>]] entry enables a
configuration source. The example uses three SMS configuration providers and
one O2A mission provider.
For SMS, keep configuration and device prefixes paired:
| Configuration prefix | Device prefix | Backend |
|---|---|---|
gfzcfg |
gfzsms |
GFZ SMS |
kitcfg |
kitsms |
KIT SMS |
ufzcfg |
ufzsms |
UFZ SMS |
Each [[ProjectConfigurationDevicesProvider.catalogs]] entry selects an
attribute whose project values become device options. In the Earth Sensor
catalog it is the selected-devices attribute. Use catalog_uri for one catalog,
catalog_uris for several, or omit both for a wildcard mapping.
This section has the same catalog scoping and source_attribute_uri setting,
but supplies the data-collection device optionset. It can reuse the same source
as ProjectConfigurationDevicesProvider.
[[DataCollectionVariableSync.catalogs]] enables automatic variable and unit
rows for selected data-collection devices. catalog_uri selects one catalog;
catalog_uris selects several. Do not add a wildcard entry unless every catalog
using the plugin has compatible data-collection attributes and collection
layout.
Each catalog entry can override these attributes; otherwise the built-in Earth Sensor defaults are used:
| Setting | Purpose |
|---|---|
devices_attribute_uri |
Selected devices in the data-collection section. |
device_collection_attribute_uri |
Device-detail collection used to find the selected device's parameters. |
parameter_name_attribute_uri |
Parameter name inside a device detail block. |
parameter_unit_attribute_uri |
Parameter unit inside a device detail block. |
variable_attribute_uri |
Generated data-collection variable target. |
unit_attribute_uri |
Generated data-collection unit target. |
The concrete Earth Sensor elements are listed in the catalog map.
[[DeviceDetailSync.catalogs]] controls the URIs that identify repeated device
detail blocks and SMS mount metadata. It uses catalog_uri/catalog_uris like
other scoped tables; an exact match wins over a wildcard entry. The packaged
profile is the Earth Sensor baseline, whose concrete elements are in the
catalog map. All fields are required per profile:
| Setting | Purpose |
|---|---|
device_details_page_uri, device_optional_info_page_uri |
Pages whose values make up a device detail collection and its optional detail page. |
configuration_collection_attribute_uri |
Repeated configuration root used to associate device blocks with their configuration. |
device_link_attribute_uri, usage_technology_attribute_uri |
Fields used to detect stale device metadata. |
instrument_start_attribute_uri, instrument_end_attribute_uri |
Scoped deployment-period fields. |
instrument_location_amsl_attribute_uri, surface_offset_z_attribute_uri, site_name_attribute_uri |
SMS-derived mount-location fields. |
serial_number_attribute_uri |
Device serial-number field used when selecting an SMS mount action. |
configuration_search_attribute_uri and device_search_attribute_uri tell
refresh actions where the selected backend IDs are stored.
Each [[MetadataRefresh.actions]] supports:
| Setting | Meaning |
|---|---|
kind |
One of configuration, device, all_configurations, or all_devices. |
trigger_attribute_uri |
Attribute whose saved answer invokes the action. |
status_attribute_uri |
Optional target for machine-readable or concise status text. |
message_attribute_uri |
Optional target for user-facing details and errors. |
timestamp_attribute_uri |
Optional target for the refresh time. |
replace_existing_collections |
Rebuild configuration device membership instead of preserving existing collections. Used by an optional explicit SMS membership-filter action. |
require_configuration_period |
Request a validated period from a handler that supports optional membership filtering. |
input_attribute_uris |
User-owned input fields that affect this action. Changes clear stale feedback but do not execute the action. |
The authoritative deployment configuration has no period-filter action. A
future SMS catalog extension must define a separate apply trigger, list its
separate filter input attributes in input_attribute_uris, set both flags
above, and explicitly enable the matching handler settings. Catalog presence
alone never changes selection behavior.
Handlers turn a selected provider option into RDMO answers. Their common layout is:
[handlers.SomeHandler]
[[handlers.SomeHandler.backends]]
id_prefix = "example"
base_url = "https://api.example.org"
[handlers.SomeHandler.defaults]
# settings shared by all catalog mappings
[[handlers.SomeHandler.catalogs]]
catalog_uri = "https://example.org/catalog"
search_attribute_uri = "https://example.org/attributes/search"
managed_attribute_uris = ["https://example.org/attributes/output"]
[handlers.SomeHandler.catalogs.attribute_mapping]
"backend.path" = "https://example.org/attributes/output"defaults are merged into each catalog entry. A catalog entry can override a
default. Omitting catalog_uri and catalog_uris creates a wildcard catalog
mapping. Prefer explicit scope when two catalogs use different attribute
semantics.
The optional backend_defaults table is merged into every entry in the
handler's backends array. Likewise, provider provider_defaults is merged
into its providers entries. Both avoid repeating shared backend URL or label
settings while still allowing a later entry to override a value.
Common handler settings are:
| Setting | Meaning |
|---|---|
search_attribute_uri |
Search attribute monitored for a selected backend option. |
attribute_mapping |
JMESPath-to-RDMO-attribute mapping. Array results create indexed values. |
managed_attribute_uris |
Additional fields authoritatively owned by the handler. |
materialize_device_details |
Allows selected devices to be materialized into repeated detail collections. |
device_link_attribute_uri |
Target for a backend or frontend record link. |
catalog_uri, catalog_uris |
Catalog scope; omitted means wildcard. |
This handler fetches one O2A item. Its mapping can read names, type,
manufacturer, model, serial number, citation, parameters, units, and contacts.
item_api_link_template and item_frontend_link_template configure record
links.
This handler fetches one SMS device. Multiple backends associate SMS
id_prefix values with base URLs. Important settings are:
| Setting | Meaning |
|---|---|
backend_link_marker |
Recognizes and normalizes SMS backend links. |
device_mount_actions_url |
Endpoint template used for device deployment periods and mount context. |
supports_mount_period_lookup |
Enables SMS mount-action enrichment for device detail blocks. |
static_location_end_tolerance_seconds |
Maximum accepted end-time difference between an overlapping static-location action and a device mount. The library default is 0 (strict). |
incomplete_mount_chain_policy |
Controls question 2.53 when a parent action is unavailable: strict leaves it empty; direct_device_offset uses only the direct device action's numeric offset_z. |
SMS mount enrichment can derive a device's active period, site name, and vertical position. See Operations and limitations.
This handler fetches one SMS configuration and its mounted devices.
| Setting | Meaning |
|---|---|
configuration_collection_attribute_uri |
Repeated configuration collection root. |
selected_devices_attribute_uri |
Attribute storing selected or mounted devices. |
selected_devices_page_uri |
Page containing the selected device set. |
device_collection_attribute_uri |
Repeated device-detail collection root. |
frontend_link_attribute_uri |
Configuration link target. |
latitude_attribute_uri, longitude_attribute_uri |
Configuration static-location targets. |
membership_filter_enabled |
Explicit opt-in for a future SMS-only historical membership-filter extension. Omit for baseline catalogs. |
membership_filter_start_attribute_uri, membership_filter_end_attribute_uri |
Separate user-owned filter inputs. They must be configured together when the extension is enabled and must not reuse question set 2.1.4. |
device_id_prefix, device_text_prefix |
Converts a mounted SMS device into an option understood by the matching device handler. |
static_location_end_tolerance_seconds |
Same bounded static-location fallback used by the SMS device handler. Configure both handlers identically. |
incomplete_mount_chain_policy |
Same strict or direct_device_offset policy used by the SMS device handler. |
The configuration provider's id_prefix must match the handler backend entry,
and device_id_prefix must match a configured SMS device provider and handler.
The supplied sensorsearch.toml enables a 120-second location tolerance and
the direct_device_offset fallback for both handlers. Invalid policies and
negative or non-integer tolerance values are rejected while loading the
configuration.
This handler treats an O2A mission as a configuration and its items as member devices. The configuration collection, selected-devices attribute and page, device collection, and frontend link settings have the same catalog meaning as for SMS.
mission_url, mission_items_url, and item_url control API requests.
mission_item_page_size limits the page size. item_id_prefix must match the
O2A device provider. mission_start_date_path, mission_end_date_path, and
date_mapping_paths describe dates present in the mission API. Their mapped
targets are the backend-owned question set 2.1.4 answers, and materialized
mission items inherit that mission period. O2A membership-filter settings are
rejected because the Registry has no comparable historical mount model.
This handler maps GIPP records, including instrument code, category, manufacturer, serial number, PID, and contact. It participates in device search and detail synchronization but not configuration or mission membership.
The example configuration contains wildcard catalog entries so the same Earth
Sensor attribute scheme can be reused by compatible catalogs. This is
convenient but broad: a handler can run in any catalog containing its search
attribute. To isolate behavior, add catalog_uri or catalog_uris to every
handler and project-local provider mapping.
When two matching catalog entries could apply, avoid relying on file order. Give each catalog one unambiguous mapping for a handler.
This index is exhaustive for the validated TOML schema. catalog_uri and
catalog_uris are allowed on every catalogs entry. attribute_mapping is a
table of JMESPath source expressions to RDMO attribute URI strings. URL fields
are templates where documented placeholders such as {base_url} and {id}
are substituted by the handler.
| Settings | Accepted by | Purpose |
|---|---|---|
id_prefix, text_prefix, base_url, max_hits |
provider entries | Stable option ID namespace, displayed backend label, backend origin, and optional result cap. |
query_url, option_id, option_text |
O2A/SMS search providers | Search endpoint and expressions selecting an option's ID and label. |
where_template, sorts, offset |
O2A mission provider | Registry query filter, ordering, and result offset. |
instruments_url |
GIPP provider | GIPP instruments endpoint. |
item_url, contacts_url, parameters_url, units_url |
O2A item handler | Endpoints used to enrich one Registry item. |
item_api_link_template, item_frontend_link_template |
O2A item handler | API and browser link templates for an item. |
device_url, contact_url |
SMS device handler | Endpoints for one SMS device and its contacts. |
device_mount_actions_url |
SMS device handler | Device mount-action endpoint used for period enrichment. |
configuration_device_mount_actions_url, configuration_platform_mount_actions_url, configuration_static_location_actions_url |
SMS device handler | Configuration-scoped endpoints used to resolve mount location. |
backend_link_marker |
SMS device/configuration handler | API path fragment replaced when forming a browser link. |
configuration_url, device_mount_action_url, platform_mount_actions_url, mounting_action_timepoints_url, static_location_actions_url |
SMS configuration handler | Endpoints used to fetch a configuration, members, time points, and locations. |
device_mount_actions_url |
SMS configuration handler | Endpoint for a configuration's device mount actions. |
device_mount_action_page_size, platform_mount_action_page_size, static_location_action_page_size, max_collection_pages |
SMS configuration handler | Remote pagination limits. |
configuration_self_link_path, configuration_start_date_path, configuration_end_date_path, frontend_link_suffix |
SMS configuration handler | Response paths and browser-link suffix used to map configuration metadata. |
device_id_prefix, device_text_prefix |
SMS configuration handler backend | Device option namespace and label when materializing configuration members. |
location_attribute_uri, latitude_attribute_uri, longitude_attribute_uri |
SMS configuration handler | Optional location target and latitude/longitude targets. |
mission_url, mission_items_url, item_url |
O2A mission handler | Endpoints for a mission, its items, and one item. |
mission_item_page_size, max_collection_pages |
O2A mission handler | Mission-member page size and maximum pages. |
item_id_prefix, item_text_prefix, item_text_template |
O2A mission handler | Namespace and display text for mission-member options. |
mission_start_date_path, mission_end_date_path, date_mapping_paths, datetime_output_format |
O2A mission handler | Mission period source paths, alternate date paths, and output formatting. |
api_link_template, frontend_link_template |
O2A mission handler | API and browser link templates for a mission. |
json_url |
GIPP handler | Endpoint returning an instrument record. |
materialize_device_details, device_collection_attribute_uri, device_link_attribute_uri |
device handlers | Enable repeated device blocks, choose their root attribute, and choose the link output. |
supports_mount_location_lookup, supports_mount_period_lookup |
device handlers | Explicitly enable SMS mount-location or deployment-period enrichment. |
static_location_end_tolerance_seconds, incomplete_mount_chain_policy |
SMS device/configuration handlers | Bound static-location matching; use strict or direct_device_offset for incomplete mount chains. |
configuration_collection_attribute_uri, selected_devices_attribute_uri, selected_devices_page_uri, frontend_link_attribute_uri, api_link_attribute_uri |
configuration/mission handlers | Repeated configuration root, member devices, their page, and configuration link targets. |
membership_filter_enabled, membership_filter_start_attribute_uri, membership_filter_end_attribute_uri |
SMS configuration handler | Explicit opt-in and paired user-owned historical-membership inputs. |