Technical/Edu-Sharing-API.md

 ## Ansprechpartner: 
-  - Julia Schindler, julia.schindler@uibk.ac.at
-  - Michael Breu, Michael.Breu@uibk.ac.at
+  - Julia Schindler, julia.schindler@uibk.ac.at (ZID)
+  - Stefan Probst, stefan.probst@uibk.ac.at (ZID)
+  - Michael Breu, Michael.Breu@uibk.ac.at (IFI)
+  - Philipp Gritsch, philipp.gritsch@uibk.ac.at (IFI)
 
-Die Universität Innsbruck plant einen Edu-Sharing Server (https://docs.edu-sharing.com/) zu betreiben.
-Die Sharing Plattform wird Metadaten dafür liefern. Mittelfristig ist geplant, die Daten aus dem Edu-Sharing Server an den OERHub weiterzugeben.
 
+## Übersicht
 
-- Das Metadatenschema orientiert sich am „LOM for higher education” hier: https://dini-ag-kim.github.io/hs-oer-lom-profil/ (bzw. https://dini-ag-kim.github.io/hs-oer-lom-profil/draft/)
+Die **EduSharing-Integration** ist eine entwickelte Funktion, die es Verlegern auf der Codeability Sharing Plattform ermöglicht, ihre Aufgaben und Kurse in das Edu-Sharing-Repository der Universität Innsbruck zu exportieren. Diese Integration ermöglicht den Zugang zu diesen Ressourcen über den **OERHub**, wodurch sie in Bildungsrepositorien in ganz Österreich durchsuchbar sind.
+
+## Involvierte Technologien
+
+- **Codeability Sharing Plattform**: Eine Plattform, auf der Bildungsressourcen von Verlegern geteilt und verwaltet werden.
+- **Edu-Sharing Repository**: Ein Repository der Universität Innsbruck, in dem Bildungsressourcen gespeichert und indexiert werden, damit sie öffentlich zugänglich sind.
+- **OERHub**: Eine zentrale Suchplattform für Bildungsressourcen aus verschiedenen Repositorien in Österreich (u.a. das Edu-Sharing Repo der UIBK)
 
-- Fächertaxonomie nach Taxonomie [ÖFOS](https://vocabs.acdh.oeaw.ac.at/oefos/de/)
-- [STG17](https://sdgs.un.org/goals) als zusätzliches Metadatenfeld
 
 ## Grundablauf (to be refined)
 
-1. Jeder commit in einem GitLab-Projekt stößt eine Prüfung der Metadaten
-2. Wenn die Metadaten korrekt sind, werden die Metadaten indiziert, der Projektinhalt ist auffindbar
+1. Ein Publisher einer Exercise stößt den Export-Prozess manuell an
+2. Wenn die Metadaten laut uns korrekt sind wird der Export Prozess fortgesetzt (siehe weiter)
 3. Die Metadaten werden an edu-sharing weitergeleitet und der Publikationsworkflow angestoßen
-4. Die Inhalte werden ggf. nochmals manuell geprüft
-5. Im positiven Fall werden die Metdaten auf edu-sharing publiziert
+4. Die Inhalte werden manuell geprüft
+5. Im positiven Fall werden die Metdaten auf edu-sharing publiziert / Im negativen Fall erhält die Sharing Plattform eine Mail und muss die Publisher der Exercise über die notwendige Änderung informieren
+
+## Vorraussetzungen & Wichtiges
+
+Übungen müssen ```CC0``` oder ```CC-BY-SA 4.0``` lizensiert sein. 
+Der OER Hub und die Repos sind als frei zugängliche Resourcen gedacht. 
+
+Eine wichtige Grundlage dabei: 
+
+Was veröffentlicht ist, bleibt veröffentlicht und wird nur im äußersten Ausnahmefall zurückgezogen.
+
+Das bedeutet dass Überarbeitungen einer Übung exportiert werden können, diese aber in einer zusätzlichen veröffentlichten Version resultieren. 
+
+## Konfiguration
+
+```yaml
+edu-sharing-integration:
+  enabled: true # determines if exercise will be exported, otherwise the feature is disabled
+  base-url: 'https://xyz.uibk.ac.at/edu-sharing/' # the url of the repo
+  auth: # imagine the repo as filesystem with enhanced metadata
+    username: ${EDU_SHARING_USER} # the user of whom the filesystem is going to be used
+    password: ${EDU_SHARING_PASSWORD} # the password of the respective user
+  content:
+    repository: 'oer-repo.uibk.ac.at' # this stays the same and is defined by zid
+    base-node: '0000000-0000-0000-0000-00000000' # this is the 'id' of the home directory of the user 
+    editorial:
+      group-authority-name: 'GROUP_oer-repo-curator' # defined by zid
+      status-to-check: '200_tocheck' # defined by zid
+      permission: 'Coordinator' # defined by zid
+```
+## Architektur
+
+### Interne API
+Die Anbindung der Funktion an das Frontend erfolgt über die Schnittstelle ```/api/exerciseEduSharingStatus``` mit dem Requestparameter ```exerciseId``` (welcher der ```projectId``` entspricht). 
+
+Der Endpunkt steht für ```GET``` und ```PUT``` zur Verfügung, wobei ```GET``` zurückgibt, ob eine Exercise bereits an Edu-Sharing übergeben wurde (```200 OK```), oder noch nicht (```404 NOT FOUND```). 
+Im Ausnahmefall, dass die Edu-Sharing-Integration in der Konfiguration deaktiviert wurde, returnen die Endpunkte ```405 NOT ALLOWED```.
+
+Die ```PUT``` Anfrage ist idempotent und erstellt oder updated die Metadaten im Edu-Sharing Repo auf Basis der Übung auf unserer Plattform. 
+Diese kann zusätzlich ```403 FORBIDDEN``` returnen falls der aktuelle Nutzer nicht über die Berechtigung verfügt die Exercise auf Edu-Sharing zu pushen.
+
+
+### Workflow
+
+Das exportieren einer Übung auf Edu-Sharing folgt folgender Logik: 
+
+```python
+if not exists(eduSharingProject): 
+  createEduSharingProjectsMetadata() # stmt 1
+else:
+  updateEduSharingProjectsMetadata() # stmt 2
+
+setContentOfEduSharingProject(zipOfExercise) # stmt 3
+setPreviewImageOfEduSharingProject(programmingLanguage) # stmt 4
+setWorkflowStatus(UPDATED) # stmt 5
+addRequiredPermissionsForReviewers() # stmt 6
+
+if something_failed and not update:
+  rollback() # stmt 7
+```
+
+#### Ausnahmefälle: 
+Der User ist weder Admin noch Publisher dieser Exercise (```IllegalAccessException```). 
+Die Metadaten sind ungültig (see ```MetaDataComplianceException.Reason```)
+Edu-Sharing ist deaktiviert (```EduSharingDisabledException```). 
+
+
+### Externe API
+
+Um diesen Prozess korrekt darzustellen werden folgende Edu-Sharing Endpunkte verwendet (Vergleich mit Workflow): 
+- ```POST /rest/node/v1/nodes/{repository}/{node}/children``` (stmt 1)
+- ```POST /rest/node/v1/nodes/{repository}/{node}/metadata``` (stmt 2)
+- ```POST /rest/node/v1/nodes/{repository}/{node}/content ``` (stmt 3)
+- ```POST /rest/node/v1/nodes/{repository}/{node}/preview ``` (stmt 4)
+- ```PUT /rest/node/v1/nodes/{repository}/{node}/workflow``` (stmt 5)
+- ```GET /rest/node/v1/nodes/{repository}/{node}/permissions``` (stmt 6)
+- ```POST /rest/node/v1/nodes/{repository}/{node}/permissions ``` (stmt 6)
+- ```DELETE /rest/node/v1/nodes/{repository}/{node}``` (stmt 7)
 
-Alternativen:
+Um die Einzelheiten des Prozess in der UI anzuzeigen werden zudem folgende Endpunkte verwendet:
+- ```GET /rest/node/v1/nodes/{repository}/{node}/metadata``` (Anzeige des Edu-Sharing Pendants)
+- ```GET /rest/node/v1/nodes/{repository}/{node}/publish``` (Anzeigen der veröffentlichten Kopien)
+- ```GET /rest/node/v1/nodes/{repository}/{node}/workflow``` (Anzeigen der Workflow Updates)
 
-2. 
-  - a. Falls der Commit ein Löschen der Metadaten bzw. das Löschen des gesamten Projekts ist, werden die Metadaten aus dem Index gelöscht.
-  - b. Die Löschung wird an edu-sharing weitergeleitet.
-  - c. Edu-Sharing veröffentlicht einen "tomb stone"
 
 
-5. a. Im negativen Fall wird der Autor informiert.
+### Verlinkung
+Um einen Export zu vermerken speichert unser System ein ```LinkedEduSharingProject``` das eine Sharing-Plattform-Exercise ID und eine Edu-Sharing ID miteinander verbindet. 
 
-## Edu-sharing Dokumentation:
+Verwaisungsproblem: Für den Fall dass eine Exercise aus Edu-Sharing gelöscht wird, kommt es zu einer Verwaisung in unserem System, da der DB-Eintrag ungültig wird. Der umgekehrte Fall, dass eine Sharing-Plattform Exercise gelöscht wird, führt dazu dass Edu-Sharing eine verwaiste Übung mit sich führt und der Rücklink ungültig ist. 
 
-Basis: edu-sharing 6.0 oder 6.1 in preproduction gehen, die Doku gibts hier: https://docs.edu-sharing.com/confluence/edp/de
+Beide Fälle sollten im Produktivsystem nicht auftreten, aber vor allem in Testsystemen mit unterschiedlichen Datenständen und Exercises sollte darauf geachtet werden, dass die nötigen Objekte bereinigt werden, wenn ein inkonsistenter Zustand herbeigeführt wurde.
    
-Doku zur API hier: https://docs.edu-sharing.com/confluence/edp/de/configuration-en/rest-api
 
-Anmerkung: wir werden, bis die Schnittstelle umgesetzt wird, vermutlich auf Version 7 sein, bei der größere Veränderungen beim alfresco Unterbau anstehen. Das sollten wir nicht aus dem Blick verlieren. Es gibt dazu allerdings noch keine Roadmap der Entwicklerfirma
+## Edu-sharing API-Dokumentation:
+https://oer-repo.uibk.ac.at/edu-sharing/swagger/
+https://github.com/edu-sharing/edu-sharing-community-repository
+https://oer-repo.uibk.ac.at/lom/latest/ (Metadaten-Felder, für Mapping bitte ZID nachfragen, da dieser in der DEBUG Ansicht eines Nodes das entsprechende Feld suchen kann)
  
 
-## Sonstiges     
--   Die Sharing Plattform vergibt/verwaltet persistent Identifier (siehe [wiki page](https://sharing-codeability.uibk.ac.at/sharing/codeability-sharing-platform/-/wikis/technical/MetaData-V0.2:-Extensions-for-Collections#the-exercise-id))
--   Sharing Plattform mappt von ihrem Metadata Schema auf ES Metadaten Schema
--   Sharing Plattform legt reine Metadatennodes über ES API an
--   Der Publikationsworkflow wird manuell in ES angestoßen
--   Metadatencheck bzw. Korrekturworkflow wenn fehlerhaft
--   Publikation
\ No newline at end of file