Counterscript Application
Technische Dokumentation der Counterscript Application für die Wellcome Library London
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.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.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:
Die Counterscript Server Application wird unter folgendem Pfad installiert:
/var/lib/tomcat7/webapps/Counterscript.war
Damit auf diese Applikation zugegriffen werden kann, muss sie zusätzlich im Apache Webserver freigegeben werden. Diese Freigabe erfolgt in der hier angegebenen Datei:
/etc/apache2/sites-enabled/000-default
In dieser müssen folgende Konfigurationszeilen eingefügt werden.
redirect /Counterscript http://pl-winslow/Counterscript/
<Location /Counterscript/>
Order allow,deny
Allow from all
ProxyPass http://localhost:8080/Counterscript/ timeout=6000 retry=0
ProxyPassReverse http://localhost:8080/Counterscript/
</Location>
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:
/etc/cron.d/intranda-triggerCounterscript
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:
create database counterscript;
GRANT ALL PRIVILEGES ON counterscript.* TO 'goobi'@'%' WITH GRANT OPTION;
CREATE TABLE `counterscript`.`files` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`filename` varchar(255) DEFAULT NULL,
`bnumber` varchar(255) DEFAULT NULL,
`material` varchar(255) DEFAULT NULL,
`access_status` varchar(255) DEFAULT NULL,
`access_licence` varchar(255) DEFAULT NULL,
`player_permission` varchar(255) DEFAULT NULL,
`status` varchar(255) DEFAULT NULL,
`creation_date` datetime DEFAULT NULL,
`modification_date` datetime DEFAULT NULL,
`deletion_date` datetime DEFAULT NULL,
`current` boolean DEFAULT false,
PRIMARY KEY (`id`)
) ENGINE = InnoDB DEFAULT CHARACTER SET = utf8;
In folgender Datei muss im Anschluss diese Datenbank noch im Apache-Tomcat bekannt gemacht werden:
/var/lib/tomcat7/conf/context.xml
Hierfür müssen die hier nachfolgenden Einträge eingefügt werden:
<Resource auth="Container"
driverClassName="org.mariadb.jdbc.Driver"
removeAbandoned="true"
logAbandoned="true"
maxActive="100"
maxIdle="30"
maxWait="10000"
name="counterscript"
password="PASSWORD"
type="javax.sql.DataSource"
url="jdbc:mariadb://localhost/counterscript?characterEncoding=UTF-8&autoReconnect=true&autoReconnectForPools=true"
username="goobi" />
Weitere Einstellungen sind für die Apache-Tomcat-Konfiguration nicht notwendig.
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:wt-winnipeg/Counterscript/api/run
wt-winnipeg/Counterscript/api/run/{date}
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:
wt-winnipeg/Counterscript/api/{format}
wt-winnipeg/Counterscript/api/{format}/withincative
wt-winnipeg/Counterscript/api/{format}/{start date}/{end date}
wt-winnipeg/Counterscript/api/{format}/withincative/{start date}/{end date}
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:
wt-winnipeg/Counterscript/api/xml/bnumber/{number}
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:
mysql
Anschließend kann man die Datenbank counterscript auswählen:
use counterscript;
Dort lassen sich alle Tabellen ausgeben:
show tables;
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:
describe files;
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:
select * from files;
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 |
Beispielhaft wurden SQL Queries für folgende Anfragen vorbereitet.
Recently created (‘New’) open access records, selectable by date range:
select * from files where status = 'newly' and creation_date > '2015-11-01' and creation_date < '2015-12-01';
Amended records, selectable by date range, where Access conditions (Status, Licence, and Player) have been changed or deleted:
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';
Deleted records, selectable by ‘Deleted date’ range:
select bnumber from files where status = 'deleted' and deletion_date > '2015-11-01' and deletion_date < '2015-12-01';
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.
Das Goobi Plugin besteht aus folgenden drei Teilen:
/opt/digiverso/goobi/plugins/administration/plugin_intranda_administration_Wellcome.jar
/opt/digiverso/goobi/plugins/GUI/plugin_intranda_administration_Wellcome-GUI.jar
/opt/digiverso/goobi/config/plugin_CounterscriptPlugin.xml
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
<config_plugin>
<rest_url>http://localhost:8080/Counterscript/api/</rest_url>
</config_plugin>
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
Last modified 2yr ago