Upgrading Installations

Upgrading installations to MidCOM 2.4 is not that hard, especially if you use MidCOM template (which should be able to upgrade transparently).

General considerations

Several upgrades to the Framework make upgrading to the new version non-trivial. You will need to upgrade both the customizing code of your site and the content in your site.

Metadata Framework

As a major new feature the Metadata framework finally provides unified handling of object metadata. This mainly affects two properties of an object: Visibility and Metadata.

Visibility comes in several favors. First, there is approval. Depending on the current MidCOM configuration, NAP will hide unscheduled items. In addition, objects can be scheduling, allowing you to set a timeframe in which an object should be shown onsite. Finally, you can explicitly hide any item from the site, regardless of the other visibility settings.

Metadata on the other hand, is mainly a question for indexing and on-site HTML Metadata tags. Its integration into the Indexer framework is yet in progress. See the Metadata Interface technical notes for more information.

NAP upgrades

The main change here is, that the constant MIDCOM_NAV_VISIBLE has been deprecated. As a site user you don't have to think about checking for visibility anymore. NAP will remove all objects which are considered invisible from the resultsets for you. The exact bahvoir of NAP can be easily changed using global configuration options. See the midcom_config.php section in the MidCOM API documentation.

Another important fact is, that NAP now automatically filters against the ViewerGroups permissions, both in AIS and on-site. You cannot circumvent this in any way now.

As a component author, you have no longer to think about removing unapproved or hidden objects. The important new feature at this front is, that unapproved or hidden items (see Metadata above) are inaccessible onsite. This is an important difference to the preivious behavoir. If you want to have a leaf (this is not implemented for nodes yet) accessible normally on-site without having an entry in the navigation, you now need to use the NAP key MIDCOM_NAV_NOENTRY when returning Leaf-Data to the NAP layer.
More details about the new changes can be found at the technical notes article NAP changes.

Upgrading MidCOM Template installations

This should be, for a start, as easy as just importing the new MidCOM Template file into your database. This is true as long as you don't want to use any of the new features of MidCOM.

MidCOM template has been updated to use the new configuration system. So, under normal circumstances, you should be safe by just upgrading MidCOM Template to the new version shipping with 2.4 and its prereleases. You might check the configuration page of your site for any new settings added to the template.

Upgrading manual MidCOM installations

The startup procedure of MidCOM has changed significantly in 2.4. Actually things got easier with 2.4, but this does not safe you from modifying your startup code.

Before upgrading, read both the Unified MidCOM Configuration System technical note and the corresponding midcom_config.php section in the MidCOM API documentation.

Basically you should be able to convert all globals you have in your code-global element into suitable entries to the midcom_config global array. Several new configuration options have been added to the system while updating the configuration mechanism, especially in combination of the new NAP defaults.

Upgrading the content tree

MidCOM 2.4 is the first MidCOM version which requires you to upgrade existing content trees to the new version. Specifically, the new metadata framework requiers rewriting all the legacy metadata to be converted to the new data structures.

Important Note: If you have not been using any kind of metadata (approval, visibility) either from pre 2.4 compnents or Aegir, you do not need to execute the conversion script.

The conversion is done using the new exec handler, which is able to execute any script located in an exec folder of either a component or the midcom library directory.

Before you commence the upgrade, you should check the script file, which is located in $midcom_root/lib/midcom/exec/convert_legacy_metadata.php. You must comment out a the die line at the top of the script directly above the configuration settings, otherwise the script obviously won't run.

In addition you should skim over the configuration settings that influence the conversion code.

If you are satisfied with the settings, take you favourite browser, login to your midcom site with an admin-level account, and call http://your.site.com/midcom-exec-midcom/convet_legacy_metadata.php.

As always, with content upgrades, it is recommended that you backup your data before doing such kind of automated conversions.