View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Chris Winters > OpenInteract-1.99_06 > OpenInteract2::Manual::Conversion


Annotate this POD

View/Report Bugs


OpenInteract2::Manual::Conversion - Moving your site and custom packages from OI 1.x to 2.x


This part of the manual will describe how to migrate your website and packages from OpenInteract 1.x to OpenInteract 2.x.


There is no more base repository! (The crowd cheers.) Every website stands on its own, every package's classes sit in the 'OpenInteract2::' namespace. This makes for much simpler development and deployment.


All this should require is translating your server configuration and any database schema changes.

Server Configuration

First off, OI 2.x exclusively uses the INI file format for the server configuration. OI 1.x allowed you to use either the serialized Perl data structure or the INI format. Hopefully you will see this as a good thing.

There are no automatic conversion utilities for your server configuration. The best thing to do is open both configuration files in parallel editing windows and compare, copying relevant information from your old file into the new one. ('C-x 3' in emacs is good for this sort of thing...)

The basic structure of the configuration files is the same. New information has been added -- datasources are unified, some names have changed, etc. -- but generally you'll find information in the same general location.

(TODO: Create a utility to pull information out of an existing INI format and update the default one with it? Not all of the information, just the highlights...)


Every package should be able to migrate itself from OI 1.x to OI 2.x. If there is no change in the schema then it's very easy for the package author to hook this up in the OpenInteract2::SQLInstall subclass.

When you're the one doing the converting you'll need to setup a datasource in your server configuration conf/server.ini for your old installation:

 [datasource old_ds]
 type          = DBI
 spops         = SPOPS::DBI::Pg
 driver_name   = Pg
 dsn           = dbname=oi_old
 username      = oi
 password      = oi
 db_owner      =
 sql_install   =
 long_read_len = 65536
 long_trunc_ok = 0

When you migrate data for a package you'll need to refer to this old datasource by name:

 oi2_manage migrate_data --package=foo --old_datasource=old_ds

There's more for package authors on migrating package data below.


Upgrading packages is undoubtedly the most resource intensive part of the upgrade. It will definitely require some work, but your work will be justly rewarded. And there are a few utilities packaged with OI2 to do at least some of the grunt work for you.

We'll break the process into pieces roughly mirroring the package directory structure.

Package Metadata (.)

This consists of the files:

Except for package.conf there is no structural change necessary for these files to work. However, depending on your scenario you may wish to upgrade your package by a whole version number to indicate that it will only work with OI2. This also allows you to maintain two source trees for a particular package, just in case you need to support both of them.


This has been replaced by package.ini; the script scripts/ shipped with OI2 will do this for you.

Additionally, you'll need to change:


There will be a few file name changes throughout the process. But rather than list them all here, just remember that any renamings/removals will have to be reflected here. Running:

 oi2_manage check_package

from your package's root directory will still let you know of any discrepancies between your MANIFEST and the files in the directory.

You can also use the ExtUtils::Manifest trick:

 $ perl -MExtUtils::Manifest -e 'ExtUtils::Manifest::mkmanifest()'

Configuration (conf/)

OpenInteract2 has abandoned the Perl data structure as configuration file. It's too difficult to edit and when generated isn't formatted for humans to read. Instead we're using the INI file format for both the action configuration and the SPOPS configurations.

Two scripts are included with the OI2 source distribution to help with this task:

Note that they're not installed anyplace special when you do a make install or ./Build install.

Both are just wrappers around a class found under OpenInteract2::Conversion. They work on STDIN and STDOUT:

 $ cd /path/to/OpenInteract-2.00-source/script
 $ perl < ~/pkg/mypkg/conf/action.perl > action.ini
 $ perl < ~/pkg/mypkg/conf/spops.perl > spops.ini

In addition to doing the fairly simple conversion from the Perl data structure to INI, it also does a few modifications to your data. Some of these are key renamings (e.g., the 'security' key in your action configuration should now be 'is_secure') while others remove now unnecessary data (e.g., most items in your 'isa' are now unnecessary, as OI2 creates it properly at startup).

After running the script you should still check the configuration to ensure everything worked and make any additional modifications. In particular, the keys of the 'links_to' and 'has_a' configuration items are not yet modified from OpenInteract::Foo to OpenInteract2::Foo.

Finally, in the packages shipped with OpenInteract2 we've kept all the action configuration entries in a single file (action.ini) but moved the configuration for each SPOPS object into its own file (e.g., spops_news.ini, spops_news_section.ini). There's nothing wrong with keeping all your SPOPS configurations in a single file, but they're probably easier to edit if they're in multiple files. It's up to you.

NOTE: Each SPOPS configuration file should begin with spops so the OI2 startup procedure can find it. You may also list your SPOPS configuration files in your package.conf file under the key spops_file.

Documentation (doc/)

Documenation has moved to the OpenInteract2::App subclass. And because OI no longer has error handlers you can delete the ERRORS section from your POD. (Packages generated with OI had this by default.)

To change:

Package data (data/)

While the data installation process has been completely rewritten (see OpenInteract2::SQLInstall, the data declarations have only small changes. Two of the conversion declarations were removed since they're no longer necessary with the elimination of the base repository:

And the remaining two conversion declarations were renamed:

SQL Structures (struct/)

These should remain the same.

Template (template/)

These should remain the same.

Examples (eg/)

No changes.

HTML files/images (html/)

No changes.

Standalone scripts (script/)

No changes, besides needing to rewrite them to use the new OI2 features. You should also look into making these management tasks so you can hook into the oi2_manage framework. It takes care of a lot for you.



Once your structures have been re-created you'll want to fill them with your existing data. The OpenInteract2::SQLInstall framework has hooks for you to use to do this. It's also got complete documentation on how to declare the migration parameters to make the whole process fairly simple. You can also look at the core OpenInteract packages for examples on how this is done.


This is where you'll likely spend the bulk of your conversion time.

Request vs. Context

In OpenInteract 1.x the omnipresent object was $R. In OpenInteract 2.x it's CTX, imported from OpenInteract2::Context. The main difference is that we now have a clear separation of concerns -- the context holds data that lives from request to request; per-request data are held in the objects returned by the request() and response() methods, represented by OpenInteract2::Request and OpenInteract2::Response classes.


We now use the Log::Log4perl package from CPAN -- see OpenInteract2::Manual::Logging for more information.

Libraries (OpenInteract/)

These get moved to OpenInteract2/

Handlers (OpenInteract/Handler)

These get moved to OpenInteract2/Action.


Copyright (c) 2002-2005 Chris Winters. All rights reserved.


Chris Winters <>

syntax highlighting: