Migration auf Solr – Unify Metadata

Solr benötigt einheitliche Datentypen bei den Metadaten, dadurch sind vor dem Umstieg von Lucene auf Solr eine Prüfung und folgende Anpassungen notwendig:

• Metadaten mit demselben Namen müssen denselben Typ haben (Datentyp, Array / kein Array).
• Sie müssen Konflikte beheben, wenn die Suche nach Umstellung auf Solr zuverlässig funktionieren soll. (Konfliktbehebung durch Konvertieren, Entfernen / Neu setzen oder durch komplettes Entfernen der betroffenen Objekte, etwa Testdaten.)

Unter Lucene waren verschiedene Datentypen kein Problem, weshalb in einigen Konfigurationen nicht auf eine Vereinheitlichung der Metadaten geachtet wurde.

Diese Dokumentation beschreibt die Vereinheitlichung der Metadaten und ermöglicht dadurch den Umstieg.

Die Migration vorbereiten

Die Hardware prüfen

• Solr benötigt mehr Ressourcen. Richten Sie ca. 30 % mehr Speicherplatz ein als normal verwendet.
  • Beispiel: 100 GB agorum core + bisheriger Index
  • ca. 30 GB mehr für Solr
• Auch benötigt Solr mehr Arbeitsspeicher

1. Metadaten auf Konflikte analysieren
2. Konflikte beheben
3. Fehlerquellen beheben
4. Solr installieren und Indexes umstellen
5. Prüfung und Anwendung auf dem Produktivsystem

Die Metadaten auf Konflikte analysieren

1. Öffnen Sie auf der Startseite von agorum core desk4web Tools.
2. Klicken Sie im Abschnitt Search Engine/Index/Preview auf Recreate search index/switch index engine.
3. Klicken Sie auf Unify Metadata.
    
   

   Unify Metadata anklicken
4. Setzen Sie den Haken bei Simulate, um zuerst eine Simulation durchzuführen, die zeigt, ob und welche Konflikte es bei Metadaten gibt.
5. Klicken Sie auf Submit.
   
    
   

   Simulation durchführen
   
   
   Ergebnis:
   
   • Unter Conflicts stehen Metadaten, zu denen Konflikte existieren.
   • Unter Unified stehen Metadaten, die keiner Vereinheitlichung bedürfen.

/roiwebui/roiwebui_module/tools/UnifyMetadata.jsp

Beispiel: keine Konflikte

Beispiel: keine Konflikte

In obiger Abbildung sehen Sie, dass es keine Konflikte gibt, in diesem Fall können Sie den Umstieg ohne Weiteres durchführen.

Beispiel: Konflikte

Das System listet vorhandene Konflikte auf:

Beispiel: Konflikte

• Die Zahlen in den Klammern hinter den Typen zeigen an, wie viele Sätze von diesem Typ existieren (SENDER etwa gibt es 21007 Mal als STRING).
• Fahren Sie mit dem Mauszeiger auf eine Zahl, sehen Sie die ersten 5 Objekt-IDs, an denen das Metadatum dieses Typs gesetzt ist.
• Prüfen Sie mithilfe dieser Daten die vorliegenden Konflikte.

Konflikte beheben

Vorhandene Konflikte beheben Sie:

• durch manuelle Konvertierung
• über das JavaScript „UnifyMetadata.js“

Konflikte durch manuelle Konvertierung beheben

• Ein Metadatum ändern Sie manuell über die Liste per Klick auf den entsprechenden Typ oder / und über das JavaScript.
• Bestehen mehrere Konflikte, lösen Sie diese einzeln (nacheinander).
• Direkt rechts von den Metadaten stehen Optionen, um die Metadaten zu sehen und zu beheben. Hierüber können Sie einfache Konflikte beheben.
• Beheben Sie die Konflikte über das JavaScript „UnifyMetadata.js“, wenn Sie eine genauere Definition wünschen und wenn etwa mehrere Konflikte in einem Konflikt vorhanden sind (vererbt, nicht vererbt, falscher Name).

Hinweise zur Konvertierung

• Vererbte Metadaten sind grundsätzlich vom Typ String.
• Mischen Sie Attribute nicht.
• Ungültige Formate oder zusätzliche Zeichen führen zu Konflikten: 
  • Strings können nicht in ein Datum konvertiert werden, wenn sie nicht ISO 8601 entsprechen.
  • Strings können nicht in einen Zahlentyp konvertiert werden, wenn sie ungültige Zeichen enthalten (Komma statt Punkt, Fragezeichen).
• Sie können die Metadaten iterativ konvertieren.

Konflikte über das JavaScript „UnifyMetadata.js“ beheben

1. Öffnen Sie auf der Startseite von agorum core desk4web Tools.
2. Klicken Sie im Abschnitt Search Engine/Index/Preview auf Recreate search index/switch index engine.
3. Klicken Sie auf Unify Metadata.
   
   Ergebnis: Sie finden das Skript rechts unter Sample-JS-File: Unify Metadata.js.
   
   • Das JavaScript Unify Metadata.js dient als Vorlage. Es enthält alle möglichen Beispiele, um bekannte Probleme zu beheben.
   • Sie können eigene Definitionen erstellen und dort komplexere Konvertierungen vornehmen, etwa, wenn ein Metadatum mehr als 2 Datentypen hat.
   • Verändern Sie ein Metadatum im JavaScript, sehen Sie es nicht mehr unter Conflicts.
   • Die Konvertierung können Sie per undefined>JavaScript durchführen.

Fehlerquellen beheben

Falsche Datentypen

Falsche Datentypen können entstehen durch:

• docform-Dokumententypen
• Workflows
• eigene JavaScripte (etwa aus dem agorum core smart assistant, agocum core fileworkflow oder Aktive Ordner)
• Schnittstellen-Dateien (XML)
• Das Setzen von Metadaten über die agorum core-REST API.

Korrekte und neue Metadaten definieren

Prüfen Sie vor dem Ändern von Metadaten, wie falsche Metadaten zustande kommen und wie das neue Metadatum definiert sein soll. Dazu prüfen Sie in der export.yml und im Metadata Designer, ob und wie die bisherigen Metadaten definiert sind.

Beispiele falscher Metadaten

• Die beiden Metadaten MwStBetrag oder Nettobetrag besitzen etwa den Datentyp string oder integer (korrekt wäre der Datentyp double, da alle Beträge auch Nachkommastellen haben).
• Metadaten sind doppelt vorhanden und besitzen einmal den Datentyp double und einmal den Datentyp integer. Nach Stichproben fällt etwa auf, dass der Wert 12 als integer gespeichert wurde, da die 0 in der Zahl 12,0 ohne Typangabe automatisch weggekürzt wurde.
• Ist das Metadatum ein String, stellen Sie sicher, dass es auch ein konvertierbarer String ist, etwa der String 17.

Interne Attribute

• Interne Attribute können Sie nur manuell umbenennen, um einen Konflikt zu lösen. Den neuen Namen geben Sie links im nebenstehenden Textfeld ein.
• Nach dem Umbenennen können Sie das neue Metadatum definieren, um die bestehenden Konflikte aufzulösen.
• Ein alleiniges Umbenennen behebt nicht die Konflikte, sondern ermöglicht nur, mit diesem neu benannten Metadatum eine neue, korrekte Definition zu starten.
• Verwenden Sie grundsätzlich ein kundenspezifisches Präfix, das Sie mit einem Unterstrich vom eigentlichen Namen trennen, etwa kundenname_rechungs_betrag. Dadurch stellen Sie sicher, dass derartige Kollisionen unmöglich sind.

Metadaten nicht definiert

Definieren Sie stets alle oder die betroffenen Metadaten über den Metadaten Designer oder über die export.yml.

Die Migration analysieren

In diesem Abschnitt finden Sie eine (unvollständige) Liste mit möglichen Fehlerquellen bei der Migration. Verwenden Sie eines der Module oder die Funktion, stehen darunter die möglichen / üblichen Fehler, die entstehen können.

Solr installieren und Indexe umstellen

In diesem Schritt stellen Sie auf Solr um und indizieren den Index neu.

Nachdem Sie die Prozesse überprüft und alle Konflikte behoben haben, führen Sie die eigentliche Umstellung durch.

1. Öffnen Sie auf der Startseite von agorum core desk4web Tools.
2. Klicken Sie im Abschnitt Search Engine/Index/Preview auf Recreate search index/switch index engine.
3. Stellen Sie die Index-Engine auf Apache Solr.
    
   

   Index-Engine und weitere Einstellungen vornehmen
4. Aktivieren Sie die Option Verification.
5. Geben Sie die Zugangsdaten des Super-Administrators roi ein.
6. Klicken Sie auf Submit.
7. Installieren Sie das Solr-Modul.
8. Starten Sie den agorum core-Server neu, um das Löschen des bisherigen und Erstellen des neuen Indexes anzustoßen. 

   Hinweis: Sie können den Fortschritt der Indizierung über das agorum core support tool unter Search/Indexing > Sub Statistics > Index verfolgen.

Nachbereitung

Falls der Lucene-Index ausgelagert ist, müssen Sie diesen manuell löschen.

Die Migration auf das Produktivsystem übertragen

Bevor Sie die Migration auf das Produktsystem übertragen:

• beheben Sie alle gefundenen Konflikte auf dem Testsystem
• prüfen Sie alle Prozesse auf dem Testsystem und spielen Sie diese durch

So übertragen Sie die Migration auf das Produktivsystem:

1. Erstellen Sie eine Datensicherung.
2. Führen Sie ein Update auf die aktuellste agorum core-Version durch, damit die aktuellsten Skripte und das Unify verwendet werden können.

   Hinweise:
   • Nötig bei agorum core-Versionen unter 8.2.
   • Bei agorum core-Versionen unter 9.1 installieren Sie für das Unify ein getrenntes ZIP.

3. Sperren Sie das System, sodass keine Benutzerzugriffe mehr stattfinden.
4. Deaktivieren Sie E-Mail-Adapter oder fremde Systeme, damit die Datensicherung gültig bleibt.
5. Installieren Sie die Konfigurations-ZIP, die Sie auf dem Testsystem erstellt haben.
   
   • Enthalten sind etwa alle Änderungen bei den Skripten.
   • Ebenfalls enthalten ist das ausgearbeitete UnifyMetadata.js des Projekts, falls vorhanden.
6. Lassen Sie UnifyMetadata laufen / führen Sie eine Simulation aus.
   
   Wenn die Ausführung auf dem Testsystem nicht zu lange her ist, ist eine Simulation nicht nötig.
7. Warten Sie.
8. Beurteilen Sie das Ergebnis des Unify. Wurden alle Konflikte gelöst, fahren Sie fort.
9. Installieren Sie Solr. 
   
   Ergebnis: Solr erzeugt einen neuen Index. Warten Sie je nach Größe auf den kompletten Neuaufbau des Indexes.
10. Testen Sie ausführlich.
    
    Ergebnis: Die Benutzer können wieder mit dem System arbeiten, wenn es keine Fehlermeldungen oder Konflikte mehr gibt.