Einführung

Die vorliegende Dokumentation beschreibt die Installation, Konfiguration und den Einsatz des Plugins. Mit Hilfe dieses Plugins können Daten aus einem externen System abgefragt und in Goobi übernommen werden. Der Katalog muss eine API haben, über die Datensätze als JSON ausgeliefert werden können.

Installation

Das Plugin besteht aus drei Dateien:

plugin_intranda_opac_json.jar
plugin_intranda_opac_json-GUI.jar
plugin_intranda_opac_json.xml

Die Datei plugin_intranda_opac_json.jar enthält die Programmlogik und muss für den Nutzer tomcat8 lesbar an folgendem Pfad installiert werden:

/opt/digiverso/goobi/plugins/opac/plugin_intranda_opac_json.jar

Die Datei plugin_intranda_opac_json-GUI.jar enthält die Nutzeroberfläche und muss für den Nutzer tomcat8 lesbar an folgendem Pfad installiert werden:

/opt/digiverso/goobi/plugins/GUI/plugin_intranda_opac_json-GUI.jar

Die Datei plugin_intranda_opac_json.xml muss ebenfalls für den Nutzer tomcat8 lesbar sein und unter folgendem Pfad liegen:

/opt/digiverso/goobi/config/plugin_intranda_opac_json.xml

Konfiguration

Die Konfiguration des Plugins erfolgt in den folgenden Dateien, die sich im Verzeichnis /opt/digiverso/goobi/config/ befinden.

goobi_opac.xml
plugin_intranda_opac_json.xml

In der Datei goobi_opac.xml muss die Schnittstelle zum gewünschten Katalogsystem bekannt gemacht werden. Dies geschieht durch einen Eintrag, der wie folgt aussieht:

<catalogue title="JSON">
    <config description="JSON OPAC" address="x"
    port="443" database="x" iktlist="x" ucnf="x" opacType="intranda_opac_json" />
</catalogue>

The title attribute contains a unique name. The plugin to be used is determined by opacType, which in this case must be intranda_opac_json. The other fields are not required.

The mapping of the JSON dataset to Goobi metadata is determined by the plugin_intranda_opac_json.xml file. The fields within the JSON dataset are referenced using JSONPath, the XPath equivalent for JSON.

<config_plugin>
    <config name="Opac Name">
​
        <field id="repository">
            <label>Repository</label>
            <select>1</select>
            <select>2</select>
            <select>3</select>
            <type>select</type>
            <defaultText>1</defaultText>
            <url></url>
        </field>
​
        <field id="id">
            <label>Identifier</label>
            <type>text</type>
            <defaultText></defaultText>
            <url></url>
        </field>
​
        <field id="type">
            <label></label>
            <type>select+text</type>
            <select>barcode</select>
            <select>holding</select>
            <select>item</select>
            <defaultText></defaultText>
            <url>https://example.com/repository/{repository.select}/}{type.select}/{type.text}?id={id.text}</url>
        </field>
​
        <authentication>
            <username>user</username>
            <password>password</password>
        </authentication>
​
        <defaultPublicationType>Monograph</defaultPublicationType>
​
        <metadata metadata="PublicationYear" field="$.date" />
        <metadata metadata="DocLanguage" field="$.language" />
        <metadata metadata="CatalogIDDigital" field="$.identifier" docType="volume" />
        <metadata metadata="CatalogIDDigital" field="$.children[?(@.itemCount > 1)].children[0].itemId" docType="volume" />
        <metadata metadata="CatalogIDDigital" field="$.uri" regularExpression="s/\/some-prefix\/(.+)/$1/g" docType="anchor" />
        <metadata metadata="shelfmarksource" field="$.identifierShelfMark" docType="volume" />
        <metadata metadata="TitleDocMain" field="$.title" docType="volume" />
        <metadata metadata="OtherTitle" field="$.alternativeTitle" docType="volume" />
        <metadata metadata="CurrentNo" field="$..children[0].children[0].sequenceNumber" docType="volume" />
        <metadata metadata="CurrentNoSorting" field="$..children[0].children[0].sequenceNumber" docType="volume" />
​
        <person metadata="Author" field="creator" firstname="s/^(.+?)\, (.+?)$/$2/g" lastname="s/^(.+?)\, (.+?)$/$1/g" validationExpression="/^.+?\, .+?\, .+$/" regularExpression="s/^(.+?)\, (.+?)\, .+/$1\, $2/g"/>
    </config>
​
    <config>
        <field id="id">
            <label>Identifier</label>
            <type>text</type>
            <defaultText></defaultText>
            <url>http://example.com/repositories/2/archival_objects/{id.text}</url>
        </field>
        <authentication>
            <username>user</username>
            <password>password</password>
            <loginUrl>http://example.com/users/{username}/login</loginUrl>
            <sessionid>session</sessionid>
            <headerParameter>Token</headerParameter>
        </authentication>
        <recordType field="[?(@.jsonmodel_type=='archival_object')]" docType="ArchivalObject" />
        <metadata metadata="TitleDocMain" field="$.title" />
​
        <metadata metadata="PublicationStart" field="$.dates.begin" />
        <metadata metadata="PublicationEnd" field="$.dates.end" />
        <metadata metadata="PublicationRun" field="$.dates.expression" />
        <person metadata="Author" field="$.linked_agents[?(@.role=='creator')].ref" followLink="true" templateName="Person" basisUrl="http://example.com"/>
        <metadata metadata="DocLanguage" field="$.notes[?(@.type=='langmaterial')].content[*]" />
        <metadata metadata="Note" field="$.notes[?(@.label=='Writing')].subnotes[*].content" />
        <metadata metadata="Illustration" field="$.notes[?(@.label=='Illumination')].subnotes[*].content" />
        <metadata metadata="Provenience" field="$.notes[?(@.type=='custodhist')].subnotes[*].content" />
        <metadata metadata="CatalogIDDigital" field="$.uri" regularExpression="s/.*\/(.+)$/$1/" />
    </config>
​
    <config>
        <template>Person</template>
        <person metadata="Author" field="$.title" firstname="s/^(.*?)\,(.*?)\,.*/$2/g" lastname="s/^(.*?)\,(.*?)\,.*$/$1/g" identifier="$.uri"/>
    </config>
</config_plugin>

Die zur Verfügung stehenden Kataloge werden in einzelnen <config name="XYZ"> Blöcken definiert. Das Attribut name enthält den Namen, unter den der Katalog ausgewählt werden kann.

Innerhalb des Katalogs können verschiedene Feldtypen genutzt werden:

Feldtyp: field

Das Element <field> wird über das Attribut id identifiziert. Innerhalb der Einträge kann im Element <type> definiert werden, welche Felder in der Eingabemaske zur Verfügung stehen. Dabei gibt es die verschiedenen Typen text, select und select+text. Der Type text erzeugt ein einfaches Eingabefeld, select eine Auswahlliste und select+text beides. Das Element <label> enthält den Namen, unter dem das Feld in der Oberfläche angezeigt wird und die Einträge in <select> defininieren, welche Inhalte in der Auswahlliste enthalten sind. Optional lässt sich eine Vorbelegung angeben. Dies geschieht mit dem Element <defaultText>.

Das Element ist wiederholbar, so dass die Eingabemaske auch mehrere Eingabefelder enthalten kann.

Eines der Felder muss dabei die URL zum Katalog enthalten. Dieser wird innerhalb des Elements <url> definiert. Um auf die Nutzereingaben zugreifen zu können, stehen die Variablen {id.select} und {id.text} zur Verfügung, wobei id durch den gewünschten field-Identifier ersetzt werden muss.

Feldtyp: authentication

Mittels <authentication> kann definiert werden, wie die Authentifizierung gegenüber dem Katalog erfolgen soll. Das Element kann fehlen oder frei bleiben, wenn der Katalog anonyme Zugriffe erlaubt.

Ansonsten stehen zwei Arten zur Verfügung. Sind nur <username> und <password> angegeben, findet eine Basic-Authentifizierung statt.

Als zweite Möglichkeit steht ein Login zur Verfügung. Hierbei wird die im Feld <loginUrl> definierte API aufgerufen, um eine gültige Session-ID zu bekommen. Dabei wird die Session-ID in dem Feld gesucht, das in <sessionid> konfiguriert wird. Die Session-ID wird dann beim eigentlichen Request als Header-Parameter genutzt. Der Parameter wird in <headerParameter> festgelegt.

Feldtyp: recordType

Das Element <recordType> enthält die Attribute field, docType und anchorType. In field wird ein JSONPath-Ausdruck angegeben, der auf den Datensatz angewendet wird. Falls es sich bei dem Typ um ein mehrbändiges Werk oder eine Zeitung/Zeitschrift handelt, muss der zu nutzende anchor Typ im Feld anchorType angegeben werden. Existiert ein Feld mit so einem Ausdruck, wird der in docType definierte Dokumententyp erstellt. Wenn nicht, wird der nächste konfigurierte recordType überprüft.

Dabei gibt es eine Reihe von Zeichen, die in dieser Datei maskiert sind. Das betrifft zum einen Zeichen wie < > & ", die in XML eine besondere Bedeutung haben und daher als < > & " angegeben werden müssen. Daneben ist noch das Komma betroffen, das mittels Backslash ebenfalls als \, maskiert werden muss.

Feldtyp: defaultPublicationType

Wenn keine der Definitionen zutreffen, kann ein Dokument mit dem Typ aus <defaultPublicationType> erzeugt werden. Wenn dieses Feld fehlt oder leer ist, wird stattdessen kein Datensatz angelegt.

Feldtypen: metadata & person

Die beiden Element <metadata> und <person> dienen zum Import einzelner Inhalte aus dem JSON-Datensatz in in die jeweiligen Metadaten. Dazu stehen eine Reihe von Attributen zur Verfügung:

Nutzung

Wenn in Goobi nach einem Identifier gesucht wird, wird im Hintergrund eine Anfrage an die konfigurierte URL gestellt.

Passend zur oben beschriebenen Konfiguration entspricht dies etwa der folgenden URL:

https://example.com/opac?id=[IDENTIFIER]

Sind weitere Felder für die Katalogabfrage definiert, so werden diese ebenfalls in der Nutzeroberfläche angezeigt:

Sofern unter dieser URL ein gültiger Datensatz gefunden wird, wird dieser nach den innerhalb von recordType definierten Feldern durchsucht, in dem der Dokumententyp stehen soll. Wenn keine Felder definiert wurden oder sie nicht gefunden wurden, wird stattdessen der Typ aus dem konfigurierten Element defaultPublicationType genutzt. Mit dem ermittelten Typ wird dann das gewünschte Strukturelement erzeugt.

Im Anschluß daran werden die konfigurierten Ausdrücke der metadata und person der Reihe nach ausgewertet. Sofern mit einem Ausdruck Daten gefunden werden, wird das entsprechend angegebene Metadatum erzeugt.

Nützliche Links

Für die Installation bzw. insbesondere für die Konfiguration des Plugins könnten die folgenden URLs eine weiterführende Hilfe sein:

JSONPath Online Evaluator: https://jsonpath.com/​

JSONPath Description: https://support.smartbear.com/alertsite/docs/monitors/api/endpoint/jsonpath.html​