Counterscript Application

1. Einleitung
Das vorliegende Dokument beschreibt die Installation, Konfiguration und den Einsatz der neuen Counterscript Application. Sie besteht aus zwei Teilen, dem Counterscript Application Server und dem als Goobi Plugin realisierten Counterscript Client.
2.  Counterscript Application Server
Der erste Teil der Entwicklungen ist der Counterscript Application Server. Bei ihm handelt es sich um eine eigenständige Java-Web-Applikation, die im bereits installierten Apache-Tomcat-Server installiert wird. Auf dessen Daten kann mit Hilfe der RESTful API zugegriffen werden.
2.1. Überblick
Mit dieser Applikation können Änderungen an den aus Goobi exportierten METS-Dateien nachvollzogen werden. Dazu wird das Netzlaufwerk des Wellcome Players mit den exportierten METS-Dateien regelmäßig nach neu hinzugekommenen, geänderten oder gelöschten METS-Dateien durchsucht und Informationen aus diesen in einer Datenbank gespeichert.
Diese Datenbank kann anschliessend durchsucht und das Ergebnis in den Formaten xml, csv oder json ausgegeben werden.
Zu jeder METS Datei werden innerhalb der Datenbank folgende Informationen gespeichert:
Pfad und Name der Datei
b-number
material code
access status
access licence
access player permission
date of creation
date of modification
date of deletion
status of the file
2.2. Installation
Die Counterscript Server Application wird unter folgendem Pfad installiert:
1
/var/lib/tomcat7/webapps/Counterscript.war
Copied!
Damit auf diese Applikation zugegriffen werden kann, muss sie zusätzlich im Apache Webserver freigegeben werden. Diese Freigabe erfolgt in der hier angegebenen Datei:
1
/etc/apache2/sites-enabled/000-default
Copied!
In dieser müssen folgende Konfigurationszeilen eingefügt werden.
1
redirect /Counterscript http://pl-winslow/Counterscript/
2
<Location /Counterscript/>
3
     Order allow,deny
4
     Allow from all
5
     ProxyPass http://localhost:8080/Counterscript/ timeout=6000 retry=0
6
     ProxyPassReverse http://localhost:8080/Counterscript/
7
</Location>
Copied!
Zusätzlich existiert neben der eigentlichen Applikation außerdem einen Cronjob, der täglich um 0:05 die Aktualisierung der Daten startet. Dieser befindet sich unter folgendem Pfad:
1
/etc/cron.d/intranda-triggerCounterscript
Copied!
2.3. Konfiguration
Damit die Daten der Counterscript Application gespeichert werden können, muss eine neue Mysql-Datenbank erzeugt werden. Dies geschieht mit folgenden SQL-Befehlen innerhalb einer geöffneten SQL-Verbindung:
1
create database counterscript;
2
GRANT ALL PRIVILEGES ON counterscript.* TO 'goobi'@'%' WITH GRANT OPTION;
3
​
4
CREATE TABLE `counterscript`.`files` (
5
    `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
6
    `filename` varchar(255) DEFAULT NULL,
7
    `bnumber` varchar(255) DEFAULT NULL,
8
    `material` varchar(255) DEFAULT NULL,
9
    `access_status` varchar(255) DEFAULT NULL,
10
    `access_licence` varchar(255) DEFAULT NULL,
11
    `player_permission` varchar(255) DEFAULT NULL,
12
    `status` varchar(255) DEFAULT NULL,
13
    `creation_date` datetime DEFAULT NULL,
14
    `modification_date` datetime DEFAULT NULL,
15
    `deletion_date` datetime DEFAULT NULL,
16
    `current` boolean DEFAULT false,
17
    PRIMARY KEY (`id`)
18
    ) ENGINE = InnoDB DEFAULT CHARACTER SET = utf8;
Copied!
In folgender Datei muss im Anschluss diese Datenbank noch im Apache-Tomcat bekannt gemacht werden:
1
/var/lib/tomcat7/conf/context.xml
Copied!
Hierfür müssen die hier nachfolgenden Einträge eingefügt werden:
1
<Resource auth="Container"
2
driverClassName="org.mariadb.jdbc.Driver"
3
removeAbandoned="true"
4
logAbandoned="true"
5
maxActive="100"
6
maxIdle="30"
7
maxWait="10000"
8
name="counterscript"
9
password="PASSWORD"
10
type="javax.sql.DataSource"
11
url="jdbc:mariadb://localhost/counterscript?characterEncoding=UTF-8&amp;autoReconnect=true&amp;autoReconnectForPools=true"
12
username="goobi" />
Copied!
Weitere Einstellungen sind für die Apache-Tomcat-Konfiguration nicht notwendig.
2.4. Nutzung
Nachdem der Counterscript Application Server installiert und konfiguriert wurde, steht dem Nutzer eine RESTful API zur Verfügung. Dabei ist im Folgenden zu beachten, dass Datumsangaben für den Zugriff auf die API stets in Form YYYY-MM-DD angegeben werden müssen.
Folgende Aufrufe dienen zur Aktualisierung des Datenbestandes:
1
wt-winnipeg/Counterscript/api/run
2
wt-winnipeg/Counterscript/api/run/{date}
Copied!
Wird die URL ohne ein Datum aufgerufen, wird der gesamte Datenbestand analysiert. Da dies sehr zeitaufwändig ist, kann man der URL ein Datum anhängen, um nur die Änderungen zu erfassen, die seit dem angegebenen Datum stattfanden.
In der Praxis werden die beiden Befehle nicht notwendig sein, da dies bereits automatisch durch Aufruf des Cronjobs täglich um 0:05 geschieht.
Wenn eine Analyse des Datenbestandes gestartet wurde, wird das Dateisystem nach neuen METS Dateien durchsucht. Wenn eine Datei gefunden wird, die einen neueren Zeitstempel lastModifiedTime hat, als der letzte Durchlauf her ist, handelt es sich um eine neue oder veränderte Datei.
In dem Fall wird mit der Datenbank abgeglichen, ob die b-Nummer bereits bekannt ist. Ist sie unbekannt, handelt es sich um einen neuen Datensatz, ansonsten um eine Modifikation. Die notwendigen Daten werden dann mittels XPATH-Anfragen aus der METS-Datei geholt und in die Datenbank geschrieben.
Anschließend werden die Datensätze der einzelnen Ordner mit den in der Datenbank bekannten Datensätzen verglichen. Fehlen im Ordner Dateien, die in der Datenbank noch bekannt sind, so handelt es sich um eine Löschung. Diese Information wird dann ebenfalls in der Datenbank hinzugefügt.
Folgende Aufrufe dienen zur Suche im Datenbestand:
1
wt-winnipeg/Counterscript/api/{format}
2
wt-winnipeg/Counterscript/api/{format}/withincative
3
wt-winnipeg/Counterscript/api/{format}/{start date}/{end date}
4
wt-winnipeg/Counterscript/api/{format}/withincative/{start date}/{end date}
Copied!
Es stehen drei verschiedene Formate zur Verfügung, in denen die Ergebnisse geliefert werden können: xml, csv und json.
Wird lediglich das Format angegeben, dann liefert die API alle aktiven Einträge, die in der Datenbank erfasst sind. Wird auch der Parameter withincative an die URL angehängt, so werden zusätzlich auch alle veralteten Einträge ausgeliefert.
Ist man nur an einer Teilmenge interessiert, kann mittels Start- und Enddatum ein Zeitraum angegeben werden. Das Ergebnis enthält dann nur die Datensätze, bei denen es Änderungen in diesem Zeitraum gab.
Ist man ausschließlich an einem einzelnen Datensatz interessiert, können diese Informationen über folgende URL abgefragt werden:
1
wt-winnipeg/Counterscript/api/xml/bnumber/{number}
Copied!
2.5.  Anbindung externer Tools
Externe Tools können am einfachsten über die RESTful API angebunden werden. Sie müssen dafür die Punkt 2.4 aufgelisteten Befehle implementieren. Alternativ steht der Weg über einen MySQL Client zur Verfügung. Dabei gilt es zu beachten, dass der MySQL-Server aus Sicherheitsgründen nur von localhost erreichbar ist.
Starten lässt sich der der Client mit dem folgenden Befehl auf dem Linux-Terminal:
1
mysql
Copied!
Anschließend kann man die Datenbank counterscript auswählen:
1
use counterscript;
Copied!
Dort lassen sich alle Tabellen ausgeben:
1
show tables;
Copied!
Dies resultiert in der folgenden Antwort des MySQL-Servers:
Tables_in_counterscript
files
Die Datenbank verfügt über eine Tabelle files, die die folgende Struktur aufweist:
1
describe files;
Copied!
Die Antwort der Datenbank lautet daraufhin folgendermaßen:
Field
Type
Null
Key
Default
Extra
id
int(10) unsigned
NO
PRI
NULL
auto_increment
filename
varchar(255)
YES
​
NULL
​
bnumber
varchar(255)
YES
​
NULL
​
material
varchar(255)
YES
​
NULL
​
access_status
varchar(255)
YES
​
NULL
​
access_licence
varchar(255)
YES
​
NULL
​
player_permission
varchar(255)
YES
​
NULL
​
status
varchar(255)
YES
​
NULL
​
creation_date
datetime
YES
​
NULL
​
modification_date
datetime
YES
​
NULL
​
deletion_date
datetime
YES
​
NULL
​
current
tinyint(1)
YES
​
0
​
Die Tabelle enthält folgenden Inhalt:
1
select * from files;
Copied!
Die Antwort der Datenbank lautet beispielhaft folgendermaßen:
id
filename
bnumber
material
access_status
access_licence
player_permission
status
creation_date
modification_date
deletion_date
current
97297
/mnt/export/7/4/7/6/b21286747_2.xml
b21286747_2
​
Open
PDM
63
deleted
2015-09-24 14:51:57
NULL
2015-11-26 00:16:54
1
98992
/mnt/export/9/6/7/5/b21355769.xml
b21355769
​
Open
CC-BY-NC
63
modified
2015-08-18 22:21:33
2015-12-02 16:18:40
NULL
1
99001
/mnt/export/x/4/9/4/b2265494x.xml
b2265494x
t
Open
CC-BY-NC
63
newly
2015-12-02 17:34:48
NULL
NULL
1
2.6. Beispielabfragen an die Datenbank
Beispielhaft wurden SQL Queries für folgende Anfragen vorbereitet.
2.6.1. Query 1: New records
Recently created (‘New’) open access records, selectable by date range:
1
select * from files where status = 'newly' and creation_date > '2015-11-01' and creation_date < '2015-12-01';
Copied!
2.6.2. Query 2: Modified records
Amended records, selectable by date range, where Access conditions (Status, Licence, and Player) have been changed or deleted:
1
select bnumber, access_status, access_licence, player_permission from files where status = 'modified' and modification_date > '2015-11-01' and modification_date < '2015-12-01';
Copied!
2.6.3. Query 3: Deleted records
Deleted records, selectable by ‘Deleted date’ range:
1
select bnumber from files where status = 'deleted' and deletion_date > '2015-11-01' and deletion_date < '2015-12-01';
Copied!
3. Goobi Counterscript Plugin
Der zweite Teil der Entwicklungen wurde als Goobi Administration Plugin realisiert. Auf die Weise konnte auf die bereits vorhandene Gestaltung der Oberfläche und die Authentifizierung zurück gegriffen werden.
3.1. Installation
Das Goobi Plugin besteht aus folgenden drei Teilen:
1
/opt/digiverso/goobi/plugins/administration/plugin_intranda_administration_Wellcome.jar
2
/opt/digiverso/goobi/plugins/GUI/plugin_intranda_administration_Wellcome-GUI.jar
3
/opt/digiverso/goobi/config/plugin_CounterscriptPlugin.xml
Copied!
Die ersten beiden Dateien enthalten die Programmlogik sowie die graphische Oberfläche. Die Datei plugin_CounterscriptPlugin.xml dient zur Konfiguration der RESTful URL und hat folgenden Inhalt:
plugin_CounterscriptPlugin.xml
1
<config_plugin>
2
    <rest_url>http://localhost:8080/Counterscript/api/</rest_url>
3
</config_plugin>
Copied!
3.2. Nutzung
Nachdem das Plugin installiert und eingerichtet wurde, steht es den Nutzern im Bereich des Menüs unter Administration zur Verfügung.
Abbildung 1: Zugang zu dem Plugin über die Nutzeroberfläche von Goobi
Nachdem die Oberfläche geladen wurde, können Startdatum und Enddatum ausgewählt oder direkt über den kompletten Zeitraum gefiltert werden. Optional lassen sich auch veraltete Einträge anzeigen.
Abbildung 2: Eingabe des Zeitraums innerhalb des Filterfomulars
Nach dem Filtern erhält man die Liste der gefundenen Datensätze für den gewählten Zeitraum.
Abbildung 3: Ansicht der gefilterten Datensätze in der Liste
Durch diese Liste kann man mit Hilfe des Paginators navigieren, oder die vollständige Trefferliste als CSV Datei speichern. Mittels des Buttons in der Spalte Details eines jeden Eintrags lässt sich der Verlauf jeder Datei im Details nachvollziehen. Hier können alle erfassten Revisionen einer Datei eingesehen werden.
Abbildung 4: Einblick in die Details eines ausgewählten Datensatzes