Converting Greenstone 2 collections to Greenstone 3

While the indexes and databases of a Greenstone 3 collection are the same as for a Greenstone 2 version, the configuration files are very different.

A Greenstone 2 collection doesn't need to be rebuilt to work in Greenstone 3, but the two configuration files, etc/collect.cfg and index/build.cfg need to be converted to their Greenstone 3 equivalents etc/collectionConfig.xml and index/buildConfig.xml.

The easiest way to achieve this is to copy the Greenstone 2 collection into the Greenstone 3 collect folder, then open it in Greenstone 3's GLI. (The Greenstone 2 collection will need to have both a etc/collect.cfg file and an index/build.cfg file.) GLI will notice that it is a greenstone 2 collection and will create the Greenstone 3 versions of the configuration files.

The tricky part of the conversion process is converting the format statements. For Greenstone versions 3.06 and later a Format Conversion Wizard is provided to help you with this process.

The Format Conversion wizard tries to automatically do the conversions itself, then presents you with the tentative Greenstone 3 format statements generated from the Greenstone 2 ones, one format statement at a time, so that you can adjust them within the Wizard itself, or accept the suggestions for now and adjust them in GLI's Format Features later.

Once you have adjusted or accepted the format statements, you can go to the Create panel and preview the collection. It does not need to be rebuilt at this stage. Depending on how the collection looks, you may need to go back to the Format panel and modify the format statements manually.

A complex example

Sometimes, the Greenstone 3 format statements generated are accurate but can be simplified further. For example, if you were to open the Small Beatles collection from the Greenstone 2 Multimedia tutorial in Greenstone 3.06 GLI, then the Format Conversion wizard will produce the following format statement for the documentNode template, and something similar for the VList classifier.

				<td valign="top">
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Lyrics">
							<gsf:link type="document">_iconlyrics_</gsf:link>
						</gsf:when>
					</gsf:switch>
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Discography">
							<gsf:link type="document">_icondisc_</gsf:link>
						</gsf:when>
					</gsf:switch>
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Tablature">
							<gsf:link type="document">_icontab_</gsf:link>
						</gsf:when>
					</gsf:switch>
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="MARC">
							<gsf:link type="document">_iconmarc_</gsf:link>
						</gsf:when>
					</gsf:switch>
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Images">
							<gsf:link type="source">
								<gsf:metadata name="thumbicon"/>
							</gsf:link>
						</gsf:when>
					</gsf:switch>
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Supplementary">
							<gsf:link type="source">
								<gsf:metadata name="srcicon"/>
							</gsf:link>
						</gsf:when>
					</gsf:switch>
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Audio">
							<gsf:link type="source">
								<gsf:switch>
									<gsf:metadata name="FileFormat"/>
									<gsf:when test="equals" test-value="MIDI">_iconmidi_</gsf:when>
									<gsf:otherwise>_iconmp3_</gsf:otherwise>
								</gsf:switch>
							</gsf:link>
						</gsf:when>
					</gsf:switch>
				</td>

Compare this format statement with the equivalent documentNode template in the manually-created collectionConfig.xml for the same collection in the Greenstone 3 Multimedia tutorial:

<td valign="top">
					<gsf:switch>
						<gsf:metadata name="dc.Format"/>
						<gsf:when test="equals" test-value="Lyrics">
							<gsf:link type="document">
								<gsf:icon file="lyrics.gif" select="collection"/>
							</gsf:link>
						</gsf:when>
						<gsf:when test="equals" test-value="Discography">
							<gsf:link type="document">
								<gsf:icon file="disc.gif" select="collection"/>
							</gsf:link>
						</gsf:when>
						<gsf:when test="equals" test-value="Tablature">
							<gsf:link type="document">
								<gsf:icon file="tab.gif" select="collection"/>
							</gsf:link>
						</gsf:when>
						<gsf:when test="equals" test-value="MARC">
							<gsf:link type="document">
								<gsf:icon file="marc.gif" select="collection"/>
							</gsf:link>
						</gsf:when>
						<gsf:when test="equals" test-value="Images">
							<gsf:link type="source">
								<gsf:metadata name="thumbicon"/>
							</gsf:link>
						</gsf:when>
						<gsf:when test="equals" test-value="Supplementary">
							<gsf:link type="source">
								<gsf:metadata name="srcicon"/>
							</gsf:link>
						</gsf:when>
						<gsf:when test="equals" test-value="Audio">
							<gsf:link type="source">
								<gsf:switch>
									<gsf:metadata name="FileFormat"/>
									<gsf:when test="equals" test-value="MIDI">
										<gsf:icon file="midi.gif" select="collection"/>
									</gsf:when>
									<gsf:otherwise>
										<gsf:metadata name="srcicon"/>
									</gsf:otherwise>
								</gsf:switch>
							</gsf:link>
						</gsf:when>
					</gsf:switch>
				</td>
				<td valign="top">
					<gsf:link type="document">
<!--
Defined in the global format statement
-->
						<xsl:call-template name="choose-title"/>
					</gsf:link>
				</td>

There are two significant differences between the two.

1. First, the automatically generated format statements refer to macros like _icondisc_, _icontab_, whereas the hand-written format statements make mention of icons using the form <gsf:icon file="tab.gif" select="collection"/>. You could manually type these out in the Format Features section of the Greenstone 3 GLI.

2. The other thing to notice is that there are many individual <gsf:switch/> statements in the automatically generated format statement, all testing the value of dc.Format field and deciding what to do based on that, whereas the manually generated one has simplified this into a single <gsf:switch/>. This simplification is only possible because all the individual switch statements are on the same variable, the dc.Format.

Automatically generated format statement:

	<gsf:switch>
		<gsf:metadata name="dc.Format"/>
		<gsf:when test="equals" test-value="SOMETHING-1">
			do something 1
		</gsf:when>
	</gsf:switch>

	<gsf:switch>
		<gsf:metadata name="dc.Format"/>
		<gsf:when test="equals" test-value="SOMETHING-2">
			do something 2
		</gsf:when>
	</gsf:switch>

	...

The hand-written version looks like:

	<gsf:switch>
		<gsf:metadata name="dc.Format"/>

		<gsf:when test="equals" test-value="Something-1">
			do something 1
		</gsf:when>

		<gsf:when test="equals" test-value="Something-2">
			do something 2
		</gsf:when>

		...
	</gsf:switch>

Using a remote Greenstone server

The new Format Conversion Wizard only appears when you're working with GLI, not client-GLI. The client-GLI for GS3 will only perform the most basic initial step in the conversion process, which is to preserve the GS2 format statements in inactive XML tags in the new collection's collectionConfig.xml.

However, if you have a local Greenstone 3 installed, you can still manage to convert a remote collection's collect.cfg file to its GS3 equivalent.

  1. Open the GS2 collection on the remote GS3 server with client-GLI. Doing so for the first time will perform the preliminary conversion step of the GS2 collect.cfg into collectionConfig.xml.
  2. Download the remote collection's etc/collectionConfig.xml file. If you open a remote collection, it is likely to download a zipped up a copy of the collection's etc folder and its contents into your client machine's .gli folder in the user area.
  3. Open regular GLI of a GS3 installation on the client machine. Create a new empty collection. Quit GLI.
  4. Go to the local GS3 installation's web/site/localsite/collection/<new-collection-name>/etc folder and place the downloaded collectionConfig.xml in here.
  5. Start regular GLI again. Re-open the newly created collection and now it should present you with the Format Conversion Wizard to lead you through inspecting the automatic conversion of the GS2 format statements to GS3.
  6. Once you're finished with the Wizard, go to the Format > Format features tab and copy all the format statements into a temporary text file.
  7. Restart client-GLI and connect to the remote GS3 server.
  8. Re-open the remote collection whose format statements need updating from GS2 to GS3.
  9. Go to the Format Features tab.
  10. Back in your temporary text file, copy over the format statement of each format feature into its correct section in the Format Features tab, replacing the text already there.
  11. The collection including its updated collectionConfig.xml file is automatically saved.