Migration Packet Customizing New from S 39.5.0

General

• Migration packets are written in Python and retrieved from the server. As a result, you have full access to the functions of the Python API.
• Before changes are applied, packets should always check whether the condition of the system meets the expectations.
  This is meant to guarantee that customer specific customizing is not overwritten by packets.
• In order to be correctly recognized as migration packets, packets must inherit from the BasePacket basic class.
• For some frequently occurring cases, there are specialized basic classes that come with helpful methods.
• All of the classes listed here can be imported by ppms.migration.
• A packet communicates its status to the framework via the success(), fail() and skip() methods.
  • These methods set an internal flag. After they have been opened, no other packet code must be executed.
• Several packets can easily be defined in a module.
• The migration packets delivered by PLANTA are described in the Release Notes.
• The status of the migration packets can be checked in the respective module of the Migration Packets panel.

Note

• The start_migration.py files (under /py/planta_de/ppms and /py/system/ppms) must not be changed.

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 more into 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 "completed" 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()

Note

• done_after_success = False is recommendable for (help)pakets that check the customizing, so that they will be displayed further on in the Packets to be executed area after execution.

Special Functions

• The StopMigrationProcessException class can be imported from ppms.migration. If this exception is raised by a packet, no more packets are executed afterwards.
• The ppms.migration package also comes with two decorators for simply skipping packets: skipIf and skipUnless.

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

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

• Packets write their logfiles as a simple text by default. This can, however, be individualized if necessary. For this purpose, two properties in the packet class must be changed:

property	Default value
logging_prefix	Returns a time stamp by default, which is written before every log entry
logfile_suffix	Sets the extension of the logfile to .log by default

Best Practice

• If a packet has multiple interim stages which can be repeated regardless of whether they have been completed successfully or have failed, it is recommended to collect the errors and open success() or fail() at the end of the fix() method, according to the number of errors.
• If a packet carries out DML statements which cannot be undone by a simple rollback, the rollback() method of the packet should be implemented in order to be able to undo the changes if necessary.

Execute Packets (Framework)

• Migration packets are executed by the server via a framework.
• This framework defines which packets are executed, executes them, and saves the logfile in the database if necessary.
• The instance of the framework which carries out the packet is handed over to the fix() method.
• The basic class of the framework is the AbstractPacketRunner under ppms.migration.framework.

Specialized framework classes included in the PLANTA delivery

Class	Use
StartupRunner	Reads all packets from the file system and carries them all out with Upon system start = and Completed =
DefaultRunner	Carries out all packets for which Completed =
SinglePacketRunner	Carries out an individual packet
RegtestRunner	Carries out an arbitrary number of packets but does not write entries in the history table
RegtestRunnerWithHistory	Modified version of the RegtestRunner, which also makes entries in the history table

Overview of the Different Basic Classes

BasePacket

• All migration packets inherit from this class.
• It can serve as a base for any type of migration step.

Class attributes

Attribute	Expected type	Function
done_after_success	Boolean	Sets the checkmark in the Completed field if the migration packet has run successfully
run_on_startup	Boolean	Carries out the packet when the server is started in migration mode
version	Integer	Specifies the version of the packet

Abstract methods

Useful methods

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

• The SQLPacket Basic Class offers several attributes and methods for running SQL statements

Class attributes

Methods

DeprecatedPythonPacket

• The DeprecatedPythonPacket class is useful if you want to find an obsolete Python code in the system.
• The fix() method is not implemented for this class!

Abstract methods

Properties

MigratePythonPacket

• A class for migrating fields with a Python code to a newer date.
• Instead of the customizer, the class checks whether the system has a particular condition and whether the changes have been made correctly.
• To use this function, a md5 hash of the initial condition as well as of the target condition must be generated.

Attributes
The following attributes are constants that are passed on as parameters to the migrate_python method.

Methods

Values for the keys parameter

ChangeDTPPacket

• Class with methods for changing arbitrary attributes of DTP records.