3. What You Write
Prev   Chapter 14. Migrating Zenoss Code   Next

3. What You Write

As noted, your migration code will subclass migrate.Migrate.Step. You can stub your migration file out like this:


__doc__='''My migration code'''

__version__ = "$Revision$"[11:-2]

from Acquisition import aq_base

import Migrate

class MyMigrateCode(Migrate.Step):
version = Migrate.Version(1, 1, 0) # this needs to be updated to the appropriate version

def cutover(self, dmd):
pass

MyMigrateCode()

You will need to do the following to this code:

  1. Fill in the doc string

  2. Update the version passed to Migrate.Version

  3. Update the cutover() method with actual code

  4. Add any supporting code you might need that doesn't strictly belong in cutover()

3.1. Implement cutover()

Implementation is very straight-forward: you get the dmd object passed into the cutover() method, thus giving you access to nearly every part of Zenoss. The only thing you don't have direct access to is the portal object. But you can easily get that by calling dmd.getPhysicalRoot().

Implementation details are 100% dependent upon what part of Zenoss you are migrating -- if you look at the current migration scripts (in trunk), you will get a good sense of the diversity as well as many examples from which to work.

Changes made to the zeo database (dmd and associated objects hierarchies) are not committed back to the database unless the --commit flag is passed to zenmigrate. This lets the developer repeatedly run a script and debug without making permanent changes to the database. If your migrate script makes changes outside of the zope database it should probably implement Step.revert() to undo any changes it has made.

3.2. Supporting Code

Supporting code is just modularization. If you're going to be using a funtion (or method) more than once, just break it out of the cutover() method. This will make maintenance easier and will allow those who come after you to see the intent of the migration code more quickly.

3.3. Testing and Deployment

Once your code meets with your approval (and that of the Zenoss development team), you are free to name it something appropriate and save it to Products/ZenModel/migrate . Upon adding your migration module, you must now edit Products/ZenModel/migrate/__init__.py so that it gets imported when zenmigrate.py is run.

After adding your script (and after every change you make to your new script), be sure to run zenmigrate run. Here are some things you can do to help ensure quality:

  1. Load Zenoss in a web browser, and navigate to the part of the application that was impacted by your migration script

  2. Look at the log files for error output

  3. Load up zendmd from the command line and make sure that no errors are generated when using the part of the API impacted by the change

After someone reviews the changes, your migration code is ready for deployment.

Prev   Up   Next
2. How It Works  Home  Chapter 15. Testing