Customize Migration Packets

General

Information

• Migration packets are written in Python and are 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 included in the delivery of PLANTA are mentioned in the Releases and Downloads topic of the respective release.
• The status of the migration packets can be checked in the respective module of the Migration Packets panel.

Details

• The migration packet is executed in the following sequence:
  • 1) server version
  • 2) category (e.g. "mandatory packet")
  • 3) file name

Note

• The start_migration.py (under /py/planta_de/ppms and /py/system/ppms) files 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 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()

Note

• done_after_success = False is recommended for (auxiliary) packets that check the customizing, so that they are further on displayed in the Packets to be executed area after execution.

Special Functions

Information

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

Best Practice

Information

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

Information

• 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

Overview of the Different Basic Classes

BasePacket

Information

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

Class attributes

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

Information

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

Class attributes

Methods

DeprecatedPythonPacket

Information

• 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

Information

• 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, an 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

Information

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

Methods