Exorcist

From OpenPSA Wiki

Exorcist is a command-line tool which was used to implement Staging/Live setups and more generally to replicate databases in Midgard 1.7 (and partially 1.8). It is written in Java an can, in contrast to it's predecessor Repligard, handle MgdSchema based objects and Multilang databases. It was deprecated when Midgard Replicator was integrated into the core. Replication management can now be handled in Asgard 2 with midcom.helper.replicator

Excorcist works by reading the content of a database with an exporter bean. They are serialized into XML format, then run through a XSLT Processor and are then written into a different database with the importer bean. This can even be done between different CMS Frameworks, thus allowing to migrate content from Midgard to other CMS frameworks and vice versa (of course, Exporter and/or Importer beans for these frameworks must exist).

Furthermore, Exorcist can import from zip files and export to them

[edit] Installation and Configuration

At the moment, Exorcist is not part of the Midgard distribution and has to be downloaded from the Sourceforge project page. It requires an operational Java installation. For scheduled approvals, you'll also need the DateFunctions.class from tigris.org.

To configure Exorcist, the path to JAVA_HOME must be set in staging2live.sh, and the database names as well as the path to the Blobs directories must be set in staging2live.xml.

In the file staging2live.xslt, one can configure which parts of the database should be replicated. This is done by defining XSLT templates which correspond with MgdSchema names.

[edit] Example

 <xsl:template match="mgd:site">
    <mgd:site>
      <xsl:apply-templates select="mgd:midgard_style"/>
    </mgd:site>
  </xsl:template>
 
  <xsl:template match="mgd:*">
    <xsl:copy><xsl:apply-templates/></xsl:copy>
  </xsl:template>

If you want you can add any number of xsl:apply-templates rules to selectively replicate parts of your database. For example:

  !-- Replicate all the topic trees (including articles, etc.) -->
  <xsl:apply-templates select="mgd:midgard_topic"/>
 
  !-- Replicate the identified topic subtree -->
  <xsl:apply-templates select=".//mgd:midgard_topic[mgd:guid='...']"/>
 
  !-- Replicate all snippets -->
  <xsl:apply-templates select="mgd:midgard_snippetdir"/>
 
  !-- Replicate all user accounts -->
  <xsl:apply-templates select="mgd:midgard_person"/>

The default <xsl:apply-templates/> rule replicates the entire database.

[edit] Common Problems / Version History

for Midgard 1.8 databases, a new schema.xml must be downloaded from tirgirs.org, because Topics are Multilang-enabled now.

In the first version of the default configuration, Exorcist replicates the entire database, including the Host records, which means that when the two databases contain different host names, they will be overwritten. In the second version, the DateFunctions class may not be found

when one limits the replication to a certain class of objects (like Styles) or to individual items, deletes are not replicated. To export deletes, add the following line to the XSLT:

 <xsl:apply-templates select="mgd:delete"/>

Caution: This exports all deletes, not just the ones from the classes you synchronise.

on real-life databases, Exorcist tends to fail with an outOutMemory exception. The memory limit for the JVM can be increased in bin/exorcist.sh

version-specific:

[edit] Exorcist 1.1.1.

in Midgard 1.8. databases, an error about an ambiguous column 'guid' in WHERE clause can occur when trying to replicate Attachments. This needs to be fixed in the source file MidgardImporter.java line 528 by changing it from guid to repligard.guid. Also, Exorcist 1.1.1. will not replicate new objects correctly for 1.8. databases. The CVS version holds the necessary fixes

[edit] Changes between Exorcist 1.1 and 1.1.1:

Fixed the line endings in exorcist.sh
Fixed the incorrect group parent link in the default schema
Added the DateFunctions class used in Midgard staging2live

[edit] exorcist 1.1.

in exorcist.sh, some line breaks contain ^M characters ausing replication to fail

[edit] Changes between Exorcist 1.0 and 1.1:

Improved performance in XML and Zip handling
More flexible configuration options
Support for attachment parameters in Midgard
Correct handling of timestamp metadata in Midgard
Improved performance in Midgard plugins

[edit] beta3:

Parameters without GUIDs will still be duplicated during replication, but in fewer cases than in the previous betas

replicating Snippet trees doesn't work (only Snippetdirs are replicated, Snippets are ignored)

[edit] beta2:

the content of Style Elements is sometimes not correctly exported

[edit] beta1:

Parameters without GUIDs will be duplicated during replication (this can cause malfunctioning of the site, if for example, a Topic's midcom component parameter is duplicated)

[edit] Debugging

By commenting out the importer bean definition in staging2live.xml, one can redirect the content XML file Exorcist produces to the logfile. There, it can be examined for debugging purposes.

[edit] Links

http://www.midgard-project.org/documentation/staging-live-setup-with-exorcist/

http://sourceforge.net/projects/exorcist/ Project site

http://midgard.tigris.org/source/browse/midgard/src/tools/staging2live/ scripts and sample configuration files

http://yukatan.fi/display/yukatan/2005/05/18/Using the Exorcist