Migrationspakete customizen

Allgemein

Informationen

• Migrationspakete werden in Python geschrieben und vom Server aufgerufen. Dadurch hat man vollen Zugriff auf die Funktionen der Python API.
• Pakete sollten immer prüfen, ob der Zustand des Systems den Erwartungen entspricht, bevor Änderungen übernommen werden .
  Dadurch soll gewährleistet werden, dass kundenindividuelles Customizing nicht durch Pakete überschrieben wird.
• Um korrekt als Migrationspaket erkannt zu werden, müssen Pakete von der BasePacket Basisklasse erben.
• Für einige häufig auftauchende Fälle gibt es spezialisierte Basisklassen, die hilfreiche Methoden mitbringen.
• Sämtliche hier aufgelisteten Klassen können von ppms.migration importiert werden.
• Ein Paket teilt seinen Zustand über die Methoden success(), fail() und skip() an das Framework mit.
  • Diese Methoden setzen einen internen Flag. Nachdem sie aufgerufen wurden, darf kein weiterer Paketcode ausgeführt werden .
• Mehrere Pakete können problemlos in einem Modul definiert werden.
• Die von PLANTA mitgelieferten Migrationspakete sind in den Releases und Downloads des jeweiligen Releases aufgeführt.
• Der Status der Migrationspakete kann im jeweiligen Modul des Panels Migrationspakete überprüft werden.

Details

• Die Ausführungsreihenfolge ist wie folgt:
  • 1. Server-Version
  • 2. Kategorie (z.B. "Pflichtpaket")
  • 3. Dateinname

Hinweis

• An den Dateien start_migration.py (unter /py/planta_de/ppms und /py/system/ppms) dürfen keine Änderungen vorgenommen werden.

Template

# -*- coding: utf-8 -*-
from ppms import ppms
from ppms.migration.packet import *

class ExamplePacket(BasePacket):
    '''Short 80 character line summarizing what this packet does


    A longer description that goes into more detail and explains
    what corner cases one could run into
    '''
    wi_number = None  # The workitem number this packet belongs to. Only relevant for packets by PLANTA
    version = 1
    done_after_success = True  # Sets the "Erledigt" flag after running successfully
    run_on_startup = True  # Runs this migration packet when the server is started in migration mode
    category = PacketCategory.CATEGORY_MANDATORY  # Categorizes the packet

    def fix(self, runner):
        # do something useful
        if errors:
           return self.fail('Encountered errors')

        return self.success()

Hinweis

• done_after_success = False wird bei (Hilfs-)Paketen, die das Customizing prüfen, empfohlen, sodass diese auch nach der Ausführung weiterhin im Bereich Auszuführende Pakete angezeigt werden.

Sonderfunktionen

Informationen

• Von ppms.migration kann die StopMigrationProcessException Klasse importiert werden. Wird diese Exception von einem Paket geraised, werden danach keine weiteren Pakete ausgeführt.
• Das ppms.migration package bringt auch zwei decorators mit, um Pakete einfach zu überspringen: skipIf und skipUnless.

@skipIf(dbms_name == 'Oracle', 'Not necessary on a Oracle db')
def fix(self, packet_runner):
    ...

@skipUnless(dbms_name == 'Oracle', 'Only necessary with a Oracle db')
def fix(self, packet_runner):
    ...

• Standardmäßig schreiben Pakete ihr Logfile als simplen Text. Dies kann jedoch bei Bedarf auch individualisiert werden. Geändert werden müssen hierzu zwei propertys in der Paketklasse:

Best Practice

Informationen

• Hat ein Paket mehrere Zwischenschritte, die unabhängig davon, ob sie erfolgreich oder fehlerhaft abgeschlossen wurden, problemlos wiederholt werden könnten, empfiehlt es sich die Fehler zu sammeln und am Ende der fix() Methode je nach Fehleranzahl success() oder fail() aufzurufen.
• Führt ein Paket DML Statements aus, die nicht mit einem simplen rollback rückgängig gemacht werden können, dann sollte die rollback() Methode des Pakets implementiert werden um die Änderungen ggf. rückgängig zu machen.

Pakete ausführen (Framework)

Informationen

• Migrationspakete werden über ein Framework vom Server ausgeführt.
• Dieses Framework bestimmt, welche Pakete ausgeführt werden, führt diese aus und speichert ggf. das Logfile in der Datenbank.
• Die Instanz des Frameworks, welches das Paket ausführt, wird an die fix() Methode übergeben.
• Die Basisklasse des Frameworks ist der AbstractPacketRunner unter ppms.migration.framework.

Spezialisierte Frameworkklassen, die PLANTA mitliefert

Übersicht über die verschiedenen Basisklassen

BasePacket

Informationen

• Alle Migrationspakete erben von dieser Klasse
• Eignet sich als Basis für jede Art von Migrationsschritt

Klassenattribute

Abstrakte Methoden

Nützliche Methoden

try:
    ... # do something that might raise an error
except Exception as err:
    self.log(err) # Call log() from the except clause to get the correct stack frame!

SQLPacket

Information

• Die SQLPacket Basisklasse bietet einige Attribute und Methoden für das Ausführen von SQL Statements

Klassenattribute

Methoden

DeprecatedPythonPacket

Informationen

• Die DeprecatedPythonPacket Klasse ist nützlich wenn man obsoleten Pythoncode im System finden will.
• Die fix() Methode wird bei dieser Klasse nicht implementiert!

Abstrakte Methoden

Propertys

MigratePythonPacket

Informationen

• Eine Klasse um Felder mit Pythoncode auf einen neueren Stand zu migrieren
• Die Klasse nimmt es dem Customizer ab zu prüfen, ob das System einen bestimmten Zustand hat und ob die Änderung korrekt angewandt wurde
• Um diese Funktion zu nutzen muss ein md5-Hash vom Ausgangszustand sowie dem Zielzustand generiert werden

Attribute
Die folgenden Attribute sind Konstanten die als Parameter an die migrate_python Methode gegeben werden.

Methoden

Werte für keys Parameter

ChangeDTPPacket

Information

• Klasse mit Methoden, um beliebige Attribute von DTP Records zu ändern

Methoden