Changeset 26012 for documentation

Show
Ignore:
Timestamp:
24.07.2012 12:53:20 (7 years ago)
Author:
ak19
Message:

1. Adjusted the tutorial for setting up and validating the GS OAI server for GS3. 2. Minor changes

Files:
1 modified

Legend:

Unmodified
Added
Removed
  • documentation/trunk/tutorials/xml-source/tutorial_en.xml

    r26000 r26012  
    627627<Text id="0352a">First, set each file's <AutoText key="metadata::dc.Title"/> field to be the same as its filename but without the filename extension.</Text> 
    628628<Text id="0353">Click on <Path>Bear.jpg</Path> so its metadata fields are available, then click on its <AutoText key="metadata::dc.Title"/> field on the right-hand side. Type in <b>Bear</b>.</Text> 
    629 <Text id="0355">Repeat the process for <Path>Cat.jpg</Path> and <Path>Cheetah.jpg</Path>.</Text> 
     629<Text id="0355">Repeat the process for <Path>Cat.jpg</Path>, <Path>Cheetah.jpg</Path> and so on.</Text> 
    630630</NumberedItem> 
    631631<NumberedItem> 
     
    647647<MajorVersion number="3"><Text id="0359d">Click on the <b>browse</b> Format Feature. Find the section under <b>documentNode</b> where it says</Text> 
    648648<Format> 
    649   &lt;td valign=&quot;top&quot;&gt;<br/> 
    650   <Tab n="1"/>&lt;gsf:displayText name=&quot;ImageName&quot;&#47;&gt;:&lt;gsf:metadata name=&quot;Image&quot;&#47;&gt;&lt;br&#47;&gt;<br/> 
    651   <Tab n="1"/>&lt;gsf:displayText name=&quot;Width&quot;&#47;&gt;:&lt;gsf:metadata name=&quot;ImageWidth&quot;&#47;&gt;&lt;br&#47;&gt;<br/> 
    652   <Tab n="1"/>&lt;gsf:displayText name=&quot;Height&quot;&#47;&gt;:&lt;gsf:metadata name=&quot;ImageHeight&quot;&#47;&gt;&lt;br&#47;&gt;<br/> 
    653   <Tab n="1"/>&lt;gsf:displayText name=&quot;Size&quot;&#47;&gt;:&lt;gsf:metadata name=&quot;ImageSize&quot;&#47;&gt;<br/> 
    654   &lt;&#47;td&gt;</Format> 
     649&lt;td valign=&quot;top&quot;&gt; 
     650<highlight>&lt;gsf:displayText name=&quot;ImageName&quot;&#47;&gt;:&lt;gsf:metadata name=&quot;Image&quot;&#47;&gt;&lt;br&#47;&gt;</highlight> 
     651&lt;gsf:displayText name=&quot;Width&quot;&#47;&gt;:&lt;gsf:metadata name=&quot;ImageWidth&quot;&#47;&gt;&lt;br&#47;&gt; 
     652&lt;gsf:displayText name=&quot;Height&quot;&#47;&gt;:&lt;gsf:metadata name=&quot;ImageHeight&quot;&#47;&gt;&lt;br&#47;&gt; 
     653&lt;gsf:displayText name=&quot;Size&quot;&#47;&gt;:&lt;gsf:metadata name=&quot;ImageSize&quot;&#47;&gt; 
     654&lt;&#47;td&gt;</Format> 
    655655<Text id="0395d">Edit the text as follows:</Text></MajorVersion> 
    656656<BulletList> 
     
    722722</NumberedItem> 
    723723<NumberedItem> 
    724 <Text id="0386">Switch to the <AutoText key="glidict::GUI.Create"/> panel, <b>build</b> the collection, then <b>preview</b> it. There is now a <AutoText key="coredm::_Global:labelSearch_"/> button in the navigation bar. As an example, search for the term "bear" in the <AutoText key="coredm::_Global:labelDescription_" type="italics"/> index (which is the only index at this point).</Text> 
    725 </NumberedItem> 
    726 <NumberedItem> 
    727 <Text id="0386a">To change the text that is displayed for the index (<AutoText key="coredm::_Global:labelDescription_" type="italics"/>), go to the <AutoText key="glidict::GUI.Format"/> panel back in the Librarian Interface. Select <AutoText key="glidict::CDM.GUI.SearchMetadata"/> from the left-hand list. This panel allows you to change the text that is displayed on the search form. Change the <AutoText key="glidict::CDM.SearchMetadataManager.Component_Name"/> for the "dc.Description" index to "image descriptions" (or other suitable text). Go back to the browser and reload the search page. Your new text will appear in the search form. </Text> 
     724<Text id="0386">Switch to the <AutoText key="glidict::GUI.Create"/> panel, <b>build</b> the collection, then <b>preview</b> it. There is now a <AutoText key="coredm::_Global:labelSearch_"/> button in the navigation bar. As an example, search for the term "bear" in the<MajorVersion number="2"> <AutoText key="coredm::_Global:labelDescription_" type="italics"/></MajorVersion><MajorVersion number="3"> <AutoText text="dc.Description" type="italics"/></MajorVersion> index (which is the only index at this point).</Text> 
     725</NumberedItem> 
     726<NumberedItem> 
     727<Text id="0386a">To change the text that is displayed for the index<MajorVersion number="2"> (<AutoText key="coredm::_Global:labelDescription_" type="italics"/>)</MajorVersion>, go to the <AutoText key="glidict::GUI.Format"/> panel back in the Librarian Interface. Select <AutoText key="glidict::CDM.GUI.SearchMetadata"/> from the left-hand list. This panel allows you to change the text that is displayed on the search form. Change the <AutoText key="glidict::CDM.SearchMetadataManager.Component_Name"/> for the "dc.Description" index to "image descriptions" (or other suitable text). Go back to the browser and reload the search page. Your new text will appear in the search form. </Text> 
    728728<Comment> 
    729729<Text id="0386b">Note that if you use text instead of macros in the search metadata display text, you will need to do any translations yourself.</Text> 
     
    32043204<Content> 
    32053205<Comment> 
    3206 <Text id="oaiserver-1">Greenstone 2 collections are not enabled for OAI out of the box. To make a collection available for serving up over OAI, some minor adjustments need to be made first. </Text> 
     3206<MajorVersion number="2"><Text id="oaiserver-1">Greenstone 2 collections are not enabled for OAI out of the box. To make a collection available for serving up over OAI, some minor adjustments need to be made first. </Text></MajorVersion> 
     3207<MajorVersion number="3"><Text id="oaiserver-1-3">Greenstone 3 collections are available over OAI by default. Their <Format>collectionConfig.xml</Format> files already specify that each collection is OAI enabled, through use of an <Format>OAIPMH</Format> element. If you want to disable a collection from being accessible over OAI, edit the <Format>OAIPMH</Format> element in that collection's collectionConfig.xml. </Text></MajorVersion> 
    32073208<Text id="oaiserver-2">This tutorial will look at how to make an existing collection available over OAI and testing its accessibility by getting it validated against the Open Archives validator.</Text> 
    32083209</Comment> 
     3210<MajorVersion number="3"> 
     3211<NumberedItem> 
     3212<Text id="oaiserver-2-3">To make your Greenstone 3 OAI server accessible to the outside world you may need to first set the <Format>baseURL</Format> property in OAIConfig.xml. Use a text editor to open the file <AutoText text="web/WEB-INF/classes/OAIConfig.xml" type="italics"/> located in your Greenstone installation folder. Find the <Format>baseURL</Format> element and set its value to your usual Greenstone library URL, but with the suffix <Format>library</Format> replaced by <Format>oaiserver</Format>.</Text> 
     3213</NumberedItem> 
     3214</MajorVersion> 
     3215<MajorVersion number="2"> 
    32093216<NumberedItem> 
    32103217<Text id="oaiserver-2">Use a text editor to open the file etc/oai.cfg located in your Greenstone installation folder. The oai.cfg configuration file contains properties that control the behaviour and features of your Greenstone OAI server.</Text>  
     
    32233230<Text id="oaiserver-8">If you're on Windows, it's best to be using the Apache web server. So if you're using the Local Library Server, stop the web server by exiting the little white dialog (the Greenstone Server Interface). Use a file browser to go into your Greenstone installation directory and rename the <AutoText text="server.exe" type="italics"/> there to <AutoText text="server.not" type="italics"/> to disable it. Now re-launch the Greenstone Server from the <AutoText text="Start"/> menu, so that this time, the included Apache web server will be used instead, launching its own little white dialog.</Text> 
    32243231</NumberedItem> 
    3225 <NumberedItem> 
    3226 <Text id="oaiserver-9">You are now ready to visit your oaiserver home page to check that it's all looking good. Start up the Greenstone Server by going to Windows <Path>Start &rarr; All Programs &rarr; Greenstone 2.85 &rarr; Greenstone Server</Path>.</Text> 
    3227 <Text id="oaiserver-10">Press the <AutoText text="Enter Library"/> button and you will end up on your Digital Library home page as usual. Adjust the URL so that instead of the <AutoText text="library.cgi" type="italics"/> suffix, it says <AutoText text="oaiserver.cgi" type="italics"/>.</Text> 
     3232</MajorVersion> 
     3233<NumberedItem> 
     3234<Text id="oaiserver-9">You are now ready to visit your oaiserver home page to check that it's all looking good. </Text> 
     3235<MajorVersion number="2"> 
     3236<Text id="oaiserver-9a">Start up the Greenstone Server by going to Windows <Path>Start &rarr; All Programs &rarr; Greenstone 2.85 &rarr; Greenstone Server</Path>.</Text> 
     3237</MajorVersion> 
     3238<MajorVersion number="3"> 
     3239<Text id="oaiserver-9a-3">Start up the Greenstone 3 Server by going to Windows <Path>Start &rarr; All Programs &rarr; Greenstone-3 &rarr; Greenstone3 Server</Path>.</Text> 
     3240</MajorVersion> 
     3241<Text id="oaiserver-10">Press the <AutoText text="Enter Library"/> button and you will end up on your Digital Library home page as usual. Adjust the URL so that instead of the <AutoText text="library" type="italics"/><MajorVersion number="2"><AutoText text=".cgi" type="italics"/></MajorVersion> suffix, it says <AutoText text="oaiserver" type="italics"/><MajorVersion number="2"><AutoText text=".cgi" type="italics"/></MajorVersion>.</Text> 
    32283242<Text id="oaiserver-11">The page that loads now will contain an error message (<AutoText text="badVerb" type="italics"/>) saying that you've provided an illegal OAI verb. This is because the OAI specification requires you to provide more instruction in the URL as to what you want. The specification defines verbs and possible arguments to them.</Text>  
    32293243<Text id="oaiserver-12">A basic verb is <AutoText text="Identify" type="italics"/>, which requests the OAI server to return some information about the OAI repository that it's serving. Adjust the URL once more by suffixing <AutoText text="?verb=Identify" type="italics"/>, so that your URL now looks like:</Text> 
     
    32413255</NumberedItem> 
    32423256<NumberedItem> 
    3243 <Text id="oaiserver-19">You will see a couple of buttons next to each collection (or <AutoText text="Set"/>) listed here. The first is <b>Identifiers</b> and the second <b>Records</b>. Click on the <b>Identifiers</b> button for the <b>backdrop</b> Set. This will list all the IDs of the documents contained in your OAI collection. If you look at the IDs, they look similar enough to Greenstone's internal document IDs, but with an additional prefix (<Format>oai:&lt;repositoryID&gt;:&lt;setname&gt;</Format>, where <Format>repositoryID</Format> was set by you in the <AutoText text="oai.cfg" type="italics"/> configuration file, and <Format>setname</Format> is the name of the collection).</Text> 
     3257<Text id="oaiserver-19">You will see a couple of buttons next to each collection (or <AutoText text="Set"/>) listed here. The first is <b>Identifiers</b> and the second <b>Records</b>. Click on the <b>Identifiers</b> button for the <b>backdrop</b> Set. This will list all the IDs of the documents contained in your OAI collection.</Text>  
     3258<MajorVersion number="2"> 
     3259<Text id="oaiserver-19b">If you look at the IDs, they look similar enough to Greenstone's internal document IDs, but with an additional prefix (<Format>oai:&lt;repositoryID&gt;:&lt;setname&gt;</Format>, where <Format>repositoryID</Format> was set by you in the <AutoText text="oai.cfg" type="italics"/> configuration file, and <Format>setname</Format> is the name of the collection).</Text> 
     3260</MajorVersion> 
    32443261</NumberedItem> 
    32453262<NumberedItem> 
    32463263<Text id="oaiserver-20">Click the browser Back button to get back to the ListSets page and press the <b>Records</b> button located next to the backdrop collection.</Text> 
    3247 <Text id="oaiserver-21">If you specified some Dublin Core (dc) metadata for each images in the <b>backdrop</b> collection, then the page that loads will display this information for each document in the collection (Set).</Text> 
     3264<Text id="oaiserver-21">If you had specified some Dublin Core (dc) metadata for each of the images in the <b>backdrop</b> collection, then the page that loads will display this information for each document in the collection (Set).</Text> 
     3265<MajorVersion number="2"> 
    32483266<Text id="oaiserver-22">Greenstone's OAI at present supports 3 metadata formats, as is explained in the instructive comments in the oai.cfg file. Of these three, the OAI standard for Dublin Core, <AutoText text="oai_dc" type="italics"/>, is the one pertinent to this tutorial. If your collection specifies metadata for a different metadata set format, you can use the oai.cfg file to tell Greenstone how to map the metadata fields of your chosen metadata set format into the Dublin Core metadata set supported by the Greenstone OAI server (or one of the other metadata sets it supports).</Text>  
    32493267<Text id="oaiserver-23">Look in the oai.cfg file again and scroll down to the section on <Format>oaimapping</Format>, which will explain and provide examples for how to specify such mappings from your metadata format to one that Greenstone's OAI server uses. For instance, the <b>demo</b> collection comes enabled for OAI upon installation, and specifies some mappings from its <AutoText text="DLS" type="italics"/> metadata format to <AutoText text="OAI DC" type="italics"/>. Its <AutoText key="metadata::dls.Title"/> metadata is mapped to <AutoText text="oai_dc.title"/> using the following line in the oai.cfg configuration file (note the use of case):</Text> 
    32503268<Format>oaimapping dls.Title oai_dc.title</Format> 
    32513269<Text id="oaiserver-24">Because the backdrop collection uses DC metadata already, no mapping is required.</Text> 
     3270</MajorVersion> 
    32523271</NumberedItem> 
    32533272<Heading> 
     
    32603279<Text id="gs-oai-2">We'll be using an external OAI client to access our up-and-running Greenstone OAI server. It's not just any OAI client either, but an OAI Server validator.</Text> 
    32613280</Comment> 
     3281<MajorVersion number="2"> 
    32623282<NumberedItem> 
    32633283<Text id="gs-oai-3">You will want to be running the included Apache web server. So if you're on Windows and using the Local Library Server, quit it and rename the <AutoText text="server.exe" type="italics"/> application in your Greenstone installation folder to <i>server.not</i>. Then use the <AutoText text="Start" type="italics"/> menu shortcut to the Greenstone Server once more, to now launch the Apache web server.</Text> 
     
    32873307<Text id="gs-oai-15">Press the button in the Greenstone Server Interface dialog that says <AutoText text="Enter Library"/> (or it may say <AutoText text="Restart Library"/>). Your Digital Library home page will open up in a browser tab. Adjust this URL to have a suffix of <Format>oaiserver.cgi</Format> in place of the terminating <Format>library.cgi</Format>, then copy the resulting URL and visit <Link>http://www.openarchives.org/Register/ValidateSite</Link>.</Text>  
    32883308</NumberedItem> 
     3309</MajorVersion> 
     3310<MajorVersion number="3"> 
     3311<NumberedItem> 
     3312<Text id="gs-oai-3-3">For this exercise, we will be visiting the <b>Open Archives Validator</b>, for which your OAIserver needs to provide a valid email address. In a text editor, open up your Greenstone installation's <AutoText text="web/WEB-INF/classes/OAIConfig.xml" type="italics"/> file again and set the value of the <Format>adminEmail</Format> element to your email address to which you would like to get the validation results sent. If testing the behaviour of the <Format>resumptionToken</Format>, set the <Format>resumeAfter</Format> element to a low value like 5.</Text>  
     3313</NumberedItem> 
     3314<NumberedItem> 
     3315<Text id="gs-oai-3-4">Restart the Greenstone 3 server if it was running. Otherwise, go to <Menu>Start &rarr; Greenstone &rarr; Greenstone3 Server</Menu> to start up the server. When the library home page opens in your browser, change the library suffix in the URL to oaiserver to visit the OAIServer page. Copy this URL.</Text> 
     3316</NumberedItem> 
     3317</MajorVersion> 
    32893318<NumberedItem> 
    32903319<Text id="gs-oai-16">The Open Archives Validator page will request the URL to your Greenstone OAI server. Paste the URL you have in your copy buffer into the field provided for this, and press the <b>Validate baseURL</b> button to start running the tests. You will be told to check your email to continue the remaining tests and get the validation report.</Text> 
    3291 <Text id="gs-oai-17">If the validator does not recognise the URL, make sure you have given the full domain of your host machine rather than just the host name. Alternatively, visit the <AutoText text="oaiserver.cgi?verb=Identify" type="italics"/> page again and check that works. If it doesn't, maybe your machine is not set up to be accessible to outside networks. Check your proxy settings, make sure you've set up port forwarding and that your firewall is not interfering.</Text> 
     3320<Text id="gs-oai-17">If the validator does not recognise the URL, make sure you have given the full domain of your host machine rather than just the host name. If the URL is still not accepted, visit the <AutoText text="oaiserver.cgi?verb=Identify" type="italics"/> page again and check that works. If it doesn't, maybe your machine is not set up to be accessible to outside networks. Check your proxy settings, make sure you've set up port forwarding and that your firewall is not interfering.</Text> 
    32923321</NumberedItem> 
    32933322</Content>