MyCoRe-ORCID2

Allgemeines

Mit dem LTS 2022.06 stellt MyCoRe mit mycore-orcid2 den Nachfolger für mycore-orcid bereit. Das Modul bietet neben der Bereitstellung eines grundlegenden Autorisierung-Prozesses auch einen generischen Client sowie Work-spezifische Funktionalitäten. Konzeptionell basiert das Modul auf dem offiziellen orcid-model von ORCID. Die aktuelle Implementierung bezieht sich auf auf v3.

Autorisierung

ORCID kann zur Autorisierung genutzt werden und bietet dafür OAuth-Flows an. Für die Autorisierung steht eine Resource bereit, die eine 3-legged OAuth initiiert, siehe Abschnitt Prozess. Dafür muss die Anwendung zunächst bei ORCID registriert werden. Letztendlich müssen die Client ID und das Client Secret konfiguriert werden. Jene sind über MCR.ORCID2.OAuth.ClientID und MCR.ORCID2.OAuth.ClientSecret zu konfigurieren. ORCID bietet zusätzlich einen Sandbox-Endpunkt für die Autorisierung. Der jeweilige Endpunkt muss über MCR.ORCID2.BaseURL konfiguriert werden.

Bei der Autorisierung ist der sogeannte Scope entscheidend. Der Scope beschreibt den Grad der Autorisierung. Scopes können kombiniert werden, beispielsweise würde die Kombination aus read-limited, /activities/update und /person/update vollständigen Lese- und Schreibzugriff für ein ORCID-Profil bedeuten. Manche Scopes/Operationen sind nur in der Member API verfügbar.

Das Resultat einer erfolgreichen Autorisierung eines Nutzenden ist letztendlich ein Token, das 30 Jahre gültig ist. Jenes wird als Nutzerattribut gespeichert. Nutzende können sich theoretisch mehrmals gleichzeichtig über verschiedene ORCID iDs autorisieren.

Letztendlich kann die Konfiguration wie folgt aussehen:

1
2
3
4
5

MCR.ORCID2.BaseURL=https://orcid.org # Produktiv
# MCR.ORCID2.BaseURL=https://sandbox.orcid.org/ # Sandbox
MCR.ORCID2.OAuth.ClientID=bla
MCR.ORCID2.OAuth.ClientSecret=foo
MCR.ORCID2.OAuth.Scope=/read-limited /activities/update /person/update

Prozess

Die Autorisierung kann über /rsc/orcid/init?scope=‹scope› gestartet werden. Wichtig ist hier die Nennung des Scopes, der autorisiert werden soll. Über MCR.ORCID2.OAuth.Scope kann ein genereller Scope definiert werden. Sofern kein Scope als Parameter über bei der Anfrage übergeben wird, wird das Property als Fallback genommen. Wenn MCR.ORCID2.PreFillRegistrationForm=true, werden Nutzerinformation für die Autorisierung übergeben.

Generell wird seitens ORCID empfohlen, den Prozess in einem separaten Fenster laufen zu lassen. Für den Prozess der Autorisierung steht eine JavaScript-Bibliothek zur Verfügung.

Client

ORCID stellt zwei bzw. vier REST-Schnittstellen bereit. Unterschieden wird zwischen der Public API und der Member API. Zum Entwickeln stellt ORCID für bei APIs jeweils eine Sandbox-Version bereit. Fundamental ermöglicht die Member API das Schreiben von Informationen in ein ORCID-Profil sowie das Lesen von vetrauenswürdigen Information, sofern Nutzende dies für die Anwendung freigeben haben. Die Member API setzt für die Nutzung einen Autorisierungsprozess bzw. ein Token voraus, siehe Abschnitt Autorisierung. Die Nutzung der Member API setzt eine ORCID-Mitgliedschaft voraus, die mit Kosten verbunden ist. Die Public API kann frei genutzt werden, ermöglich aber hingegen höchstens das Lesen von öffentlichen Informationen. Hierfür sind speziell keine Credentials erforderlich.

Letztendlich sollte vor der ersten Nutzung geklärt werden, welche der API der Client nutzen soll, weil die Funktionalitäten ggf. darauf abgestimmt sind. Dafür existiert eine Factory, Clients können über MCR.ORCID2.Client.‹Version›. konfiguriert werden. Über APIMode=public|member wird der mode der API festgelegt. Mit public wird die Public API aktiviert, anlog mit member die Member API. Dazu muss der jeweilige Pfad für die API (in Sandbox oder produktiv) über PublicAPI bzw. MemberAPI festgelegt werden. Über ErrorHandler.Class lässt sich ein Error-Handler konfigurieren, um beispielweise Fehler des Clients zu behandeln oder zu loggen. ORCID empfiehlt für die Nutzung der Public API ein Read Public Token, um die Requests ggf. zuzuordnen zu können. Das Token bei ORCID generiert werden und über MCR.ORCID2.Client.ReadPublicToken konfiguriert werden.

Für die Nutzung der produktiven v3 APIs könnte die Konfiguration wie folgt aussehen:

1
2
3
4
5
6

MCR.ORCID2.Client.V3.PublicAPI=https://pub.orcid.org/v3.0 # Produktiv
MCR.ORCID2.Client.V3.MemberAPI=https://api.orcid.org/v3.0 # Produktiv
# MCR.ORCID2.Client.V3.PublicAPI=https://pub.sandbox.orcid.org/v3.0 # Sandbox
# MCR.ORCID2.Client.V3.MemberAPI=https://api.sandbox.orcid.org/v3.0 # Sandbox
MCR.ORCID2.Client.V3.APIMode=member
MCR.ORCID2.Client.V3.ErrorHandler.Class=org.mycore.orcid2.v3.client.MCRORCIDClientErrorHandlerImpl

ORCID-Servflag

Das Servflag dient zur Beschreibung der ORCID-Informationen für das Objekt. Unter userInfos werden ORCID-Profile beschrieben, die zum einen die Autoren betreffen und ggf. auch das Work auf ORCID-Seite. orcid beschreibt dabei die zugehörige ORCID iD. Unter works sind Informationen zum Objekt/Work auf ORCID-Seite des Profils angegeben:

• own beschreibt hierbei den PutCode des Work in dem ORCID-Profil, das von der Anwendung erstellt wurde. Der PutCode ist eindeutig.
  Der Wert -1 bedeutet, dass eine Work gelöscht wurde. Dies kann entweder durch die Anwendung selbst passieren oder wenn ein ORCID-Nutzer das Work aus dem Profil löscht.
• other beschreibt die PutCodes der Works in dem ORCID-Profil, die ggf. von anderen Anwendungen erstellt wurden. other wird nur gespeichert, sofern MCR.ORCID2.Metadata.WorkInfo.SaveOtherPutCodes=true.

Sobald eine Operation durchgeführt wurde, wird das Servflag von der Anwendung aktualisiert.

Beispiel

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

<servflag type="MyCoRe-ORCID" inherited="0" form="plain">
{
   "userInfos":[
      {
         "orcid":"0000-0003-4862-0666",
         "works":{
            "own":1736580,
            "other":[
              212123
            ]
         }
      }
   ]
}
</servflag>

WorkEventHandler

Für das automatische Schreiben/Aktualisieren von Publikationen in ORCID-Profile der Autoren kann der ORCIDWorkEventHandler genutzt werden. Der Handler kann für v3 mit MCR.EventHandler.MCRObject.019.Class=org.mycore.orcid2.v3.work.MCRORCIDWorkEventHandlerImpl aktiviert werden. Wenn keine Änderung in den Metadaten festgestellt wird, terminiert der Handler vorzeitig. Anderenfalls werden alle Autoren einer Publikation anhand von den Identifiers auf zugehörige ORICD-Credentials geprüft. Über MCR.ORCID2.User.TrustedNameIdentifierTypes kann die Bestimmung auf vertrauenswürdige Identifier eingeschränkt werden. Beispielsweise würde orcid bedeuten, dass nur die ORCID iDs der Autoren als Referenz zur Bestimmung genutzt werden. Letztendlich werden jene Token anschließend genutzt, um die Publikation in die jeweiligen ORCID-Profile zu schreiben/aktualisieren. Die Nutzer selbst haben die Möglichkeit, über ORCID-User-Properies bestimmte Verhalten zu beeinflussen. Standardmäßig werden die Verhalten der Anwendung als Fallback genutzt, siehe Verhalten.

Über MCR.ORCID2.Work.PublishStates ist es möglich, States für Publikationen zu definieren, die behandelt werden sollen. So kann etwa verhindert werden, dass beispielsweise frische Einreichungen eventuell direkt in die jeweiligen Profile geschrieben werden. Zudem gibt es mit MCR.ContentTransformer.ORCIDMODSFilter die Möglichkeit, Metadaten einer Publikationen vor einer Operation zu filtern. So kann ggf. verhindert werden, dass ungewünschte Metadaten zu ORCID gelangen. Der Filter bietet so zusätzlich auch die Möglichkeit, Metadaten zu ergänzen. Beispielsweise fordert ORCID, dass jedes Work mindestens einen Identifier besitzen muss. Dafür kann mit MCR.ORCID2.Work.SourceURL eine möglichst eindeutige ID für die Anwendung definiert werden.

Sofern MCR.ORCID2.WorkEventHandler.CollectExternalPutCodes=true werden zusätzlich auch PutCodes anderer Personen über die ORCID-Suche hinzugefügt. Voraussetzung dafür ist MCR.ORCID2.Metadata.WorkInfo.SaveOtherPutCodes=true, da es dabei um other handelt.

Verhalten

Folgende Verhalten können konfiguriert/beeinflusst werden:

• Mit MCR.ORCID2.WorkEventHandler.AlwaysUpdateWork=true werden Publikationen kontinuierlich aktualisiert, nachdem sie im ORCID-Profil erstellt wurden und Änderungen in der Anwendung vorgenommen wurden.
• Mit MCR.ORCID2.WorkEventHandler.CreateDuplicateWork=true werden Publikationen jedenfalls im ORCID-Profil erstellt, auch wenn bereits eine identische Publikation aus beispielsweise einer anderen Anwendung im Profil vorhanden ist (Duplikat).
• Mit MCR.ORCID2.WorkEventHandler.CreateFirstWork=true werden Publikationen initial im ORCID-Profil erstellt.
• Mit MCR.ORCID2.WorkEventHandler.RecreateDeletedWork=true werden Publikationen, die bereits aus dem ORCID-Profil gelöscht wurden, bei einer Aktualisierung erneut in das Profil geschrieben.

ORCID-User-Properties

Mit den ORCID-User-Properties können Nutzer das Verhalten der WorkEventHandlers für sich beeinflussen. Die Properties sind mächtiger als die Properties der Anwendung. Grundsätzlich beziehen sich die Properties auf eine ORCID iD und nicht allgemein auf den Nutzer und werden pro ORCID iD als Nutzerattribut gespeichert. Für die Verwaltung steht beispielsweise ein REST-Endpunkt zur Verfügung.

Beispiel

1
2
3
4
5
6

{
   "alwaysUpdateWork":false,
   "createDuplicateWork":false,
   "createFirstWork":false,
   "recreateDeletedWork":true
}

Weiteres

Konzeptionell werden die Identifier einer Publikation genutzt, um jene Publikation auf ORCID-Seite wiederzufinden. Die Identifier können über MCR.ORCID2.Object.TrustedIdentifierTypes eingeschränkt werden.

REST

Das Modul besitzt einen REST-Endpunkt, der hauptsächlich Nutzer-Methoden zur Verfügung stellt. Optional kann der Endpunkt um Work-Funktionalität erweitert werden.

Nutzer

Folgende nutzerspezifische Methoden stehen bereit:

Work

Die folgenden Endpunkte sind optional und liegen im package org.mycore.orcid2.v3.rest.resources.
Um sie zu aktivieren, muss das package zu MCR.ORCID2.API.Resource.Packages hinzugefügt werden.
Folgende Methoden stehen bereit: