WissKI Authority Document¶

wisski_authority_document lets editors link a WissKI entity to an entry in an external authority file, such as GND, Getty or GeoNames, instead of typing the reference by hand. The editor chooses a provider, types a few letters, picks a suggestion, and the module fills in both the label and the authority URI.

Every authority service is a provider: its URL, its request parameters and the way its answer is read are configuration, not code. You can change the shipped providers and add new ones, for example another TS4NFDI database or a vocabulary server of your own, without programming.

Shipped providers¶

Provider	Machine name	Service	Format	Field the editor fills
GND	`gnd`	lobid-gnd	JSON	GND entity type
GND (DNB SRU)	`gnd_sru`	DNB SRU	GND SRU	GND entity type
Getty	`getty`	Getty reconciliation service	Reconciliation Service API	Getty vocabulary
GeoNames	`geonames`	GeoNames (username needed)	JSON	GeoNames feature class
Wikidata	`wikidata`	`wbsearchentities`	JSON	–
Iconclass	`iconclass`	TS4NFDI API Gateway, parents from the Iconclass API	JSON with Iconclass parents	–
DANTE	`dante`	TS4NFDI API Gateway	JSON	–
DANTE (vocabularies)	`dante_vocabularies`	DANTE API, disabled until you add vocabularies	JSON	DANTE vocabulary
Own terms	`custom`	WissKI autocomplete of this site	Own WissKI terms	–

The machine name is what the provider field of each entity stores. Do not change it once entities use it.

Install¶

drush en wisski_authority_document

The module needs wisski_core and wisski_autocomplete, which are part of WissKI.

If you update from an earlier version, run the database updates afterwards:

drush updb

The update turns the old settings into providers, see Updating from older versions.

Providers¶

Open Configuration → WissKI → Authority Document (/admin/config/wisski/authority-document). You need the Administer site configuration permission.

The page lists all providers with format, request URL, the fields they need and their defaults. Drag the rows to change the order of the provider list in the entity form. Add provider creates a new one; Edit opens the form described below.

Defaults¶

Each provider has its own defaults; they apply to every form that offers the provider.

Setting	Meaning
Maximum results	How many suggestions are shown (1–50).
Timeout	Seconds to wait for the service.
Minimum characters	Shorter search texts are not sent.
Cache lifetime	How long identical searches are answered from the cache. `0` turns the cache off. Saving the provider empties its cache.

Request¶

Base URL and Endpoint path together form the request URL, for example https://secure.geonames.org and /searchJSON. A {name} in the endpoint path is replaced by the path parameter of that name.

Each parameter has a name, a location (query string or path) and a value template:

Placeholder	Becomes
`{term}`	The search text. With Escape {term}: Lucene, query syntax such as `:` or `(` is matched literally.
`{max_results}`	The provider's maximum results.
`{values}`	The values of the options the editor selected, see below.

A value without placeholders is sent as it is, for example format = json. Mark a parameter Required when the service cannot search without it, such as the GeoNames username. While it is empty, editors get a hint instead of suggestions ("GeoNames cannot search: the setting username is empty."), and a warning is logged.

Parameters filled from the entity form¶

Give a parameter a field key, such as gnd_type, when its value depends on what the editor selects. The widget then asks for a list field of the form for that key, see Widget settings.

Setting	Meaning
Field key	Lowercase name. Providers that share a key share one field, like `gnd` and `gnd_sru` with `gnd_type`.
Field label	Name of the field in the widget settings, for example "GND entity type".
Options	One per line: `key\\|label\\|value`. The key is stored in the field and shown to editors with its label; the value is sent. Without a value, the key is sent. A value may contain `{term}`.
Join several values with	Separator for several selected options, for example `\\|` or `OR`. Empty: the parameter is repeated once per option.
Value when nothing is selected	Template used instead; empty leaves the parameter out.
Nothing selected means all options	Sends every option when the editor selected none.

The options are also the choices editors see: a list field mapped in the widget takes its allowed values from the providers.

GND (lobid)GND (SRU)GeoNamesGettyDANTE (vocabularies)

filter = {values}, joined with OR, options such as

Tp|Person|type:DifferentiatedPerson
Tb|Corporate body|type:CorporateBody

Selecting both sends filter=type:DifferentiatedPerson OR type:CorporateBody; nothing selected leaves the filter out.

query = {values}, joined with or, empty value WOE={term}; each option is a whole CQL clause:

Tp|Person|(PER={term} and BBG=Tp*)
Tg|Place or geographic name|(GEO={term} and BBG=Tg*)

featureClass = {values} without separator, so it repeats: featureClass=A&featureClass=P. Keys are the feature class letters.

type = {values}, options aat|…|/aat, tgn|…|/tgn, ulan|…|/ulan, nothing selected means all options. Each type becomes its own reconciliation query.

voc = {values}, joined with |, required. Add the vocabulary notations editors should offer, from GET https://api.dante.gbv.de/voc, for example bk|Basisklassifikation, then enable the provider.

Answer formats¶

The format decides how the request is sent and how the answer is read.

JSONJSON with Iconclass parentsGND SRU (RDF/XML)Reconciliation Service APIOwn WissKI terms

One GET request. Paths walk the JSON answer: response.docs, prefLabel.de, inScheme.0.prefLabel; * takes every child. In templates, {path} is replaced by its value and {a|b} uses the first path that has one.

Setting	Example (GeoNames)
Result list path	`geonames` (empty when the answer itself is the list)
Error message path	`status.message`
Label template	`{toponymName\\|name}`
URI template	`https://www.geonames.org/{geonameId}/`
Description lines	`{adminName1}` and `{countryName}`, shown in brackets
Tooltip lines	`Type: {fcodeName\\|fclName}`; a line whose values are all missing is left out
Variant labels path	When only a variant matches, the tooltip reads "label (via variant)"

Results with the same URI appear once.

Like JSON, and the parent of each Iconclass notation is added to the result as broader, so templates can show it: the shipped Iconclass provider uses {broader.txt.en} as description. Settings: the notation template ({short_form} for the gateway) and the Iconclass JSON API (https://iconclass.org/json). The parents cost two batch requests per search; when they fail, the results show without them and are not cached.

One GET request to DNB SRU with recordSchema=RDFxml. A record is kept only when the search text occurs in its preferred or a variant name, ignoring case and accents, because SRU also matches fields the editor never sees. Exact matches come first. Birth and death dates are shown in brackets.

Speaks the W3C Reconciliation Service API. The module reads the service manifest once a day: when its versions list contains 1.0-draft, queries go as JSON to /match and /extend; otherwise the older form-encoded protocol is used, which Getty speaks today.

It uses the parameters query, type (one query per value) and limit. Settings: a URI template (http://vocab.getty.edu/{id}), a prefix of names to skip (< for Getty guide terms, which must not be used for indexing), languages for Accept-Language, tooltip properties loaded with data extension, one per line as type|property|label|number of values, for example /tgn|/tgn_hier|Parent|3, and description properties, shown in brackets after the name, as type|property|number of values; the shipped /aat|/aat_hier|1 shows the nearest broader term. Getty returns English preferred names only.

Searches entities of the bundle of own terms (empty: all bundles) whose preferred name contains the search text; the alternative name is searched only when the preferred name has no match. Both fields are chosen from a list grouped by bundle and must belong to that bundle. Base URL, endpoint and parameters are not used. Editors can also enter new terms, see New own terms.

Links are permalinks: the entity URI behind a resolver, as the WissKI permalink formatter builds them. Empty uses this site, e.g. http://localhost:3600/wisski/get?uri=…; a host such as example.org becomes https://example.org/wisski/get?uri=…; a URL is used as prefix of the encoded URI.

Example request¶

At the bottom of the form, Show request prints the complete request the current settings would send, for a search text you choose; fields use their first option. Run test search sends it and shows the first results with their tooltips. Both use the values in the form, also before you save.

GET https://services.dnb.de/sru/authorities?version=1.1&operation=searchRetrieve&query=%28PER%3DGoethe%20and%20BBG%3DTp%2A%29&maximumRecords=100&recordSchema=RDFxml

Add a TS4NFDI database¶

Open the Iconclass provider and note its settings, or start with Add provider.
Base URL https://terminology.services.base4nfdi.de/api-gateway, endpoint /ols/api/search, format JSON.
Parameters q = {term} (escape: Lucene), rows = {max_results}, ontology = the database id, e.g. agrovoc; several ids separated by commas are searched together.
JSON settings: result list path response.docs, label {label}, URI {iri}, description {description}, tooltip {synonym}, variant labels path synonym.
Check it with Run test search.

The gateway's database ids are listed at /api-gateway/config/databases.

Build the input form¶

The autocomplete works together with other fields of the same form. Add them in the pathbuilder to the group that describes the authority link:

Field	Type	Widget	Required
Provider	List (text), cardinality 1	Select list or radio buttons	Yes
Search term	Text (plain)	Authority Document Autocomplete	Yes
Link	Link, link text disabled	Link	Yes
One list field per field key	List (text)	Check boxes or select list	As the providers need them

You do not enter allowed values for the provider field or the field-key fields: once the widget settings are saved, these fields list the providers and the options from the provider settings.

Stored values stay valid

Editors are offered the enabled providers and their options only. Values of disabled providers, and the values a field had before it was mapped, stay valid: an entity that uses one still shows it and keeps it when saved. Uninstalling the module writes the current options into the fields as their own allowed values.

Open the form display of the bundle and choose Authority Document Autocomplete for the search-term field. Its settings list what the enabled providers need, for example "The configured providers need 4 fields from this form: the provider choice and GND entity type, Getty vocabulary, GeoNames feature class":

Setting	Points to
Provider field	The provider list field
Link field	The link field that receives the URI
One select per field key	The list field for that key; the description names the providers that use it

All settings are required, and each field can serve one purpose only. Disable providers you do not offer, and their fields are no longer asked for; the mapping is kept for when you enable them again. The widget also works inside nested forms such as inline entity forms: it looks for the other fields next to the search-term field.

Broader terms in suggestions¶

The shipped providers show the nearest broader term in brackets, for example Vase (Gefäß) - https://d-nb.info/gnd/4126533-6:

Provider	Comes from
GND	lobid's `broaderTermGeneric`, `broaderTermInstantial`, `broaderTermPartitive` or `broaderTermGeneral`, in the JSON description template
Getty	the first entry of the AAT or TGN hierarchy, in the description properties
Iconclass	the parent notation's label, `{broader.txt.en}`

GND (DNB SRU) shows none: its records name broader terms only by URI.

Use the autocomplete¶

Open the entity form and choose the provider.
Optionally tick entity types, vocabularies or feature classes.
Type at least the provider's minimum number of characters into the search-term field.
Hover over a suggestion to see details such as type, hierarchy, description or the variant name that matched.
Click a suggestion. The search-term field gets the preferred label, and the link field gets the authority URI.

New own terms¶

When the provider is Own terms, the link field is greyed out with the placeholder Set when the entity is saved:

Choose a suggestion, and the link field gets the permalink of that existing term right away.
Or type a new preferred term. The entity you are editing is then the term itself: on save, its link field gets its own permalink.

Changing the text after choosing a suggestion empties the link again, so the link always belongs to the term in the search field. WissKI assigns the URI of a new entity during its first save, so a new entity is saved a second time to store the link. If the permalink cannot be built, the entity is saved without a link and the reason is logged.

URIs and permalinks

WissKI builds new URIs from the adapter's default graph (WISSKI_DEFAULT_GRAPH, for example https://my.wiss-ki.eu/). Unless that domain redirects to the site, the bare URI does not open anything; the permalink goes through the resolver and opens the entity.

Updating from older versions¶

drush updb runs update 8004, which

creates the shipped providers that do not exist yet; a site that searched GND directly, or never saved the old settings, keeps DNB SRU under the machine name gnd,
copies maximum results, timeouts, minimum characters, a changed gateway base URL, the cache lifetime, custom endpoint URLs, the GeoNames username, the Wikidata language, the Getty languages and the own-terms fields,
turns further gateway authorities into providers (hyphens in their machine names become underscores, which is logged),
rewrites the widget settings to the new mapping; the old fallback Entity type field becomes the GND field,
gives each mapped field the options it had before, with the same keys and labels, sending what the old module sent (GeoNames p sends P, GND differentiatedperson sends the person type),
enables DANTE (vocabularies) when a DANTE vocabulary field was mapped; a custom DANTE API URL moves to DANTE (vocabularies),
deletes the old wisski_authority_document.settings configuration.

Getty's old SPARQL endpoint rejects anonymous requests and is not migrated; Getty now uses the reconciliation service. Values that update 8002 of the development branch added to the provider field (all TS4NFDI databases) get no provider; they stay valid but are no longer offered. Add a provider for every database you use.

Troubleshooting¶

No suggestions appear at all

Check that a provider is selected and that at least its minimum number of characters is typed.
Open the provider and use Run test search.
Look under Reports → Recent log messages, filtered by wisski_authority_document.

GeoNames only shows "GeoNames cannot search: the setting username is empty."

Enter your GeoNames username as the value of the username parameter, and enable the web services in your geonames.org account. The log names the provider too: "Authority provider geonames cannot search: Required parameter username has no value."

DANTE (vocabularies) finds nothing

The provider searches only when the editor ticked a vocabulary. Check that the provider has options and is enabled, and that the widget maps its field.

DANTE is slow or times out

DANTE answers in 5 to 20 seconds. Raise the provider's Timeout (default 20 seconds) or Minimum characters (default 4).

Iconclass finds nothing for German terms

Iconclass labels come in English through the gateway. Search for crucifix, not the German word for it.

Getty shows suggestions without details on hover

The details come from a second request. When it fails, the log names the vocabulary, and the suggestions are not cached, so the next search tries again.

Suggestions are outdated

Results are cached for the provider's Cache lifetime. Save the provider to empty its cache, lower the lifetime, or run drush cr.

Link to repository