Migrationspaket-Customizing Neu ab S 39.5.0

Allgemein

• 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 Release Notes beschrieben.
• Der Status der Migrationspakete kann im jeweiligen Modul des Panels Migrationspakete überprüft werden.

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

• 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:

property	Standardwert
logging_prefix	Gibt standardmäßig einen Zeitstempel zurück, der vor jeden Logeintrag geschrieben wird
logfile_suffix	Setzt die Endung der Logdatei standardmäßig auf .log

Best Practice

• 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)

• 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

Klasse	Verwendung
StartupRunner	Liest alle Pakete vom Dateisystem und führt alle aus mit Bei Systemstart = und Erledigt =
DefaultRunner	Führt alle Pakete aus bei denen Erledigt =
SinglePacketRunner	Führt ein einzelnes Paket aus
RegtestRunner	Führt eine beliebige Anzahl von Paketen aus, schreibt aber keine Einträge in die Historietabelle
RegtestRunnerWithHistory	Abgewandelte Version vom RegtestRunner, der auch Einträge in die Historietabelle macht

Übersicht über die verschiedenen Basisklassen

BasePacket

• 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

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

Klassenattribute

Methoden

DeprecatedPythonPacket

• 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

• 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

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