Mit dem agorum core migration tool arbeiten

Mit dem agorum core migration tool exportieren Sie als Administrator Ihre Daten aus agorum core und importieren sie in ein anderes agorum core-System. Gleiches gilt für Daten, die Sie exportieren und in ein Fremdsystem importieren.

Unterstützte Objekte und Regeln beim Import/Export

Unterstützte Objekte

• Ordner
• Dateien
  • Historien
• E-Mails
• Metadaten
• Notizen
• Benutzer
• Benutzergruppen
• ACLs

Unterstütze Regeln

• Verlinkungen
  • Wenn die Objekte im Exportbereich mehrfach durch Verlinkung vorkommen, verlinkt das System diese beim Import.
• Verknüpfungen
  • Wenn Verknüpfungen innerhalb des exportierten Bereichs vorkommen, stellt das System diese Verknüpfungen beim Import wieder her.

Regeln beim Import

• Die UUID eines Objekts bleibt gleich. Beim Import in ein anderes agorum core-System werden die UUIDs der Objekte beibehalten. Damit ist sichergestellt, dass interne Verlinkungen oder auch Links innerhalb von HTML-Dateien auf agorum core-Objekte wieder funktionieren.
• Historien werden wiederhergestellt.
• Verlinkungen werden wiederhergestellt.
• Verknüpfungen werden wiederhergestellt.
• Der Import prüft zuerst, ob die UUID bereits im Zielsystem vorhanden ist. Wenn ja, wird das Objekt lediglich in den Ordner verlinkt und nicht mehr weiterverarbeitet und auch Ordner nicht weiterverfolgt. Auf diese Art funktioniert das Verlinken innerhalb des Imports.
• Wenn dieselben ACLs (Namen) auf dem Zielsystem vorhanden sind, werden diese wieder auf die Objekte gesetzt.
  • Wenn eine ACL nicht vorhanden ist, gelten die normalen Regeln der ACL-Setzung. (Die ACLs werden vererbt.)
• Wenn dieselben Benutzer (Namen) auf dem Zielsystem vorhanden sind, werden diese wieder gesetzt (owner, lastModifier).
  • Wenn der Benutzer nicht vorhanden ist, wird der Benutzer gesetzt, mit dem Sie den Import durchführen.
• Bricht der Import ab, können Sie diesen nochmals starten. Objekte, die im System schon vorhanden sind, werden übersprungen. Dies bedeutet auch, dass Sie mit dem Import nicht mehrmals dieselben Objekte importieren können.

Sie können auch Benutzer, Benutzergruppe und ACLs importieren (sofern Sie diese zuvor exportiert haben). Wenn noch keine Benutzergruppen / Benutzer / ACLs mit dem jeweiligen Namen existieren, legt das System diese an. Nur dann setzt das System auch etwa Mitglieder einer Benutzergruppe oder übernimmt ACL-Einträge. Existiert jedoch die Benutzergruppe, der Benutzer oder die ACL bereits, ignoriert das System sie und verändert sie nicht.

Exportdaten

Das System exportiert die Daten auf das lokale Dateisystem des agorum core-Servers. Auf diesem Server können Sie einen Pfad anlegen, in den der Export die exportierten Objekte schreibt.

• Der Pfad muss in einem Bereich liegen, der vom agorum core-Server aus erreichbar ist.
• Wenn Sie dort nicht genügend Speicher haben, können Sie eine weitere Platte anhängen, auf die der Export die Daten schreibt.

Beispiel Linux

/opt/agorum/export

Beispiel Windows

d:\agorum\export

Wenn Sie die Daten nicht auf einer transportierbaren Platte abgelegt haben, müssen Sie diese auf den Importbereich des Zielsystems kopieren.

Importdaten

• Die zu importierenden Daten müssen auf dem Server liegen, auf dem das agorum core-System (Zielsystem) installiert ist.
• Die Daten müssen in einem Bereich liegen, der vom agorum core-Server aus erreichbar ist.
• Sie können auch in diesen Bereich eine Platte anhängen, auf der die Daten für den Import liegen.

Beispiel Linux

/opt/agorum/export 

Beispiel Windows

d:\agorum\export

Den Export durchführen

Voraussetzung

Sie haben das Plug-in installiert.

1. Öffnen Sie links in der Seitenleiste Explorer.
2. Optional: Wenn Sie den Export auf einen bestimmten Zeitraum beschränken wollen, können Sie diesen Zeitraum mit den Konstanten FROM_DATE und TO_DATE angeben. Öffnen Sie dazu folgende Datei:

   Eigene Dateien/Administration/customers/acmigrationtool/js/export.js
   

   Entfernen Sie die Kommentarzeichen und ersetzen Sie jeweils das Beispieldatum durch den angegebenen Wert. In diesem Beispiel würden die Daten aus den Jahren 2022 und 2023 exportiert.

   // define from date, if you want to export only from this date.
   let FROM_DATE;
   FROM_DATE = new Date('2022-01-01T00:00:00');
   
   // define to date, if you want to export to this date
   let TO_DATE;
   TO_DATE = new Date('2024-01-01T00:00:00');

3. Öffnen Sie den Pfad:

   Eigene Dateien/Administration/customers/acmigrationtool/js/aguila/export.js

   
   Ergebnis: Sie finden in diesem Verzeichnis 2 Skripte:
   
   • export.js
   • import.js
4. Doppelklicken Sie auf die Datei export.js.
   
   ​​​​​​Ergebnis: Der Skripteditor startet.
5. Klicken Sie auf Run.
   
   ​​​​​​Ergebnis: Ein Dialog öffnet sich.
6. Klicken Sie Start, um den Export durchzuführen.

Den Export durchführen

Eigene Dateien/Administration/customers/acmigrationtool/samples/id-filter-sample.csv

Aktiver Export

• Läuft der Export bereits und stoppen Sie ihn, können Sie den Export nicht mehr fortsetzen.
• Starten Sie einen neuen Export, beginnt er wieder von vorn.
• Wenn Sie den Export derselben Daten neu starten, löschen Sie damit die zuvor exportierten Daten. Sollten diese noch vorhanden sein, benennt der Exporter diesen Pfad automatisch um in ASF_<Datum>. Alternativ können Sie den zweiten Export auch einfach in einen neuen Output-Pfad schreiben lassen.

Die Exportdateien übertragen

Wenn Sie den Export beendet haben:

1. Kopieren Sie die Daten auf den anderen agorum core-Server, indem Sie die Daten in eine .zip- oder .tar- Datei packen. Diese Datei können Sie von einem Server auf den anderen spielen.
2. Entpacken Sie die Datei.
   
   Ergebnis: Sie haben die Vorbereitungen zum Import abgeschlossen.

.tar-Datei unter Linux entpacken

Output-Verzeichnis (etwa /opt/agorum/export)

cd /opt/agorum
tar cfv export.tar export/

Ergebnis: Die Datei export.tar liegt in dem angegebenen Verzeichnis.

.tar gepacktes Verzeichnis (Beispiel mit der Datei export.tar)

cd /opt/agorum
tar xfv export.tar

Ergebnis: Das System legt das Verzeichnis /opt/agorum/export wird mit allen Unterverzeichnissen an.

Den Import durchführen

1. Öffnen Sie links in der Seitenleiste Explorer.
2. Öffnen Sie den Pfad:

   Eigene Dateien//Administration/customers/acmigrationtool/js/aguila

   
   Ergebnis: Sie finden in diesem Verzeichnis 2 Skripte:
   
   • export.js
   • import.js
3. Doppelklicken Sie auf die Datei import.js.
   
   ​​​​​​Ergebnis: Der Skripteditor startet.
4. Klicken Sie auf Run.
   
   ​​​​​​Ergebnis: Ein Dialog öffnet sich.
5. Wählen Sie für agorum core import folder das Verzeichnis aus, in das Sie die exportierten Daten entpackt haben.
6. Optional: Geben Sie einen eigenen Handler an, siehe Optionaler JavaScript-Handler.
7. Klicken Sie Start, um die Daten in die neue Installation zu überführen.

Den Import durchführen

• Informationen während des Imports finden Sie unterhalb der Schaltfläche Start.
• Den Import können Sie abbrechen und danach nochmals aufsetzen, ohne dass das System Objekte mehrfach importiert.
• Falls es beim Import und dort bei einem Commit zu einem Deadlock kommt, wird der Commit bis zu fünfmal erneut versucht.

Optionaler JavaScript-Handler beim Importieren

Sie können beim Importieren der Objekte einen optionalen JavaScript-Handler mitgeben.

• Das System ruft diesen Handler immer auf, nachdem der Import die Verarbeitungen für dieses Objekt abgeschlossen hat (after insert).
• Mit dem Handler können Sie die importierten Objekte und Metadaten weiter nach Ihren eigenen Regeln anpassen und erweitern.
• Der mitgelieferte Handler hat keine Funktion.

/**
 * localFolder: the local folder on the local file system (type: java.io.File)
 * localFile: the local file on the the local file system (JSON file, type: java.io.File)
 * parent: the agorum core folder object, where the object will be placed in (may be undefined, for objects without path)
 * data: the data from the json file (a map, containing attributes like name, className, description, ...)
 */
function pre(localFolder, localFile, parent, data) {
  // here you can do something to manipulate the object before import
  // console.log('pre: ', localFolder, localFile, data);
  
  // return false, to ignore the object and not to create it
  return true;
}

/**
 * object: the created agorum core object
 * localFolder: the local folder on the local file system (type: java.io.File)
 * localFile: the local file on the the local file system (JSON file, type: java.io.File)
 * parent: the agorum core folder object, where the object is placed in (may be undefined, for objects without path)
 * data: the data from the json file (a map, containing attributes like name, className, description, ...)
 */
function handle(object, localFolder, localFile, parent, data) {
  // here you can do something to manipulate the object after import
  // console.log('handler: ' + object, localFolder, localFile, data);
}

module.exports = {
  handle: handle,
  pre: pre
};

Funktion „pre“

Manipuliert Daten vor Anlage des Objekts. Zudem können Sie steuern, ob das System ein Objekt überhaupt importiert, indem Sie false zurückgeben.

Aufbau der exportierten Daten im Outputverzeichnis

Wenn Sie etwa unter Dateien den Ordner export exportieren und Ihr Output-Folder c:\aa\e1\ lautet, baut das System folgende Struktur unter Export auf:

• c:\aa\e1\
  • export
    • Direkt unter diesem ersten Ordner stehen 2 Dateien:
      • ref-table.json
        • Hier sind Strukturen abgelegt
      • user-table.json
        • Hier sind Benutzer abgelegt
      • id-mapping.json
        • Hier sind die UUIDs mit ihrer zugehörigen ID hinterlegt
      • id-mapping.csv (nur nach dem Import)
        • Hierin sind nach dem erfolgreichen Import alle importierten Alt-IDs, die neuen IDs sowie die UUIDs hinterlegt. Diese Datei können Sie etwa verwenden, um Verweise in einem Fremdsystem, die noch auf die numerische ID zeigen, zu korrigieren.
      • ac_users (Ordner)
        • Hierunter sind die Benutzerinformationen exportiert worden.
      • ac_groups (Ordner)
        • Hierunter sind die Gruppeninformationen exportiert worden.
      • ac_acls (Ordner)
        • Hierunter sind Informationen zu ACLs exportiert worden.
      • ac_systemacls (Ordner)
        • Hierunter sind Informationen zu System-ACLs exportiert worden.
      • Weiter folgen ab hier alle Daten. Diese Daten werden grundsätzlich mit ihrer UUID benannt. Eine UUID hat immer einen solchen Aufbau: '019ca740-6e89-11ea-8106-080027223377'
      • Jedes Objekt ist entweder ein Ordner oder eine Datei mit dem Inhalt der Daten.
      • Jeder Objektname kann mehrfach vorkommen. Diese können sein:
        • <UUID>
          • Das Objekt selbst
        • <UUID>.json
          • Hier stehen die Datenbankattribute des Objekts.
          • Hier können auch Verlinkungen und Anhänge enthalten sein.
        • <UUID>.axo
          • Hier stehen die Metadaten des Objekts als XML-Struktur.
        • <UUID>.axoinheritable
          • Hier stehen die Metadaten des Objekts, die ab hier vererbt werden.
        • <UUID>.versions
          • Darunter stehen die Versionen des Objekts.
        • <UUID>.notes
          • Hier stehen die Notizen, die an einem Objekt angehängt sind.