Ignore:
Timestamp:
2012-08-13T19:04:47+12:00 (12 years ago)
Author:
ak19
Message:
  1. Updated tutorial Downloading over OAI for GS3 after testing it again against today's binary (to make sure Friday's updates were sufficient). Also validated the OAI server after Friday's changes to get this tutorial to work for GS3, to make sure nothing on the OAI server side broke. 2. Minor change to the tutorial Setting up your GS server for GS3, since the GS3 baseURL is now automatically written into the OAIConfig.xml file and the user no longer needs to manually write this in.
File:
1 edited

Legend:

Unmodified
Added
Removed

  • documentation/trunk/tutorials/xml-source/tutorial_en.xml

    r26081 r26097  
    36543654<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>
    36553655</Comment>
    3656 <MajorVersion number="3">
    3657 <NumberedItem>
    3658 <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>
    3659 </NumberedItem>
    3660 </MajorVersion>
    36613656<MajorVersion number="2">
    36623657<NumberedItem>
    … …  
    36783673</MajorVersion>
    36793674<NumberedItem>
    3680 <Text id="oaiserver-9">You are now ready to visit your oaiserver home page to check that it's all looking good. </Text>
    36813675<MajorVersion number="2">
    3682 <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>
     3676<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>
    36833677</MajorVersion>
    36843678<MajorVersion number="3">
    … …  
    36883682<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>
    36893683<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>
    3690 <Format>http://&lt;domain&gt;/greenstone/cgi-bin/oaiserver.cgi?verb=Identify</Format>
     3684<Format>
     3685<MajorVersion number="2">http://&lt;domain&gt;/greenstone/cgi-bin/oaiserver.cgi?verb=Identify</MajorVersion>
     3686<MajorVersion number="3">http://&lt;domain:port&gt;/greenstone3/oaiserver?verb=Identify</MajorVersion>
     3687</Format>
    36913688<Text id="oaiserver-13">Visiting this page now gives some information about your Greenstone OAI repository.</Text>
    36923689</NumberedItem>
    … …  
    37143711<Format>oaimapping dls.Title oai_dc.title</Format>
    37153712<Text id="oaiserver-24">Because the backdrop collection uses DC metadata already, no mapping is required.</Text>
     3713</MajorVersion>
     3714<MajorVersion number="3">
     3715<Text id="oaiserver-22">Greenstone 3's OAI implementation uses the OAI standard for Dublin Core, <AutoText text="oai_dc" type="italics"/>, metadata format. By default, it maps all Dublin Core metadata you may have assigned to your collections into <AutoText text="oai_dc" type="italics"/>. This default mapping is specified in the <Path>web\WEB-INF\classes\OAIConfig.xml</Path> file. If all (or most) of your collections will be using a different metadata format, you can edit the OAIConfig.xml file's <Format>mappingList</Format> section to create mappings from the metadata fields you're using to those in <AutoText text="oai_dc" type="italics"/>. You can also specify mappings at a collection-level, overriding the mappings in OAIConfig.xml for that collection. So if a collection specifies metadata for a different metadata set format from the default mappings in OAIConfig.xml, adjust the collection's <Path>web\sites\localsite\collect\&lt;collection-name&gt;\etc\collectionConfig.xml</Path> file to tell Greenstone how to map the metadata fields of your chosen metadata set format into the <AutoText text="oai_dc" type="italics"/> Dublin Core metadata set supported by the Greenstone OAI server.</Text>
     3716<Text id="oaiserver-23">For instance, look in the <b>demo</b> collection's collectionConfig.xml file (<Path>web\sites\localsite\collect\lucene-jdbm-demo\etc\collectionConfig.xml</Path>) and scroll down to the definition for the <Format>OAIPMH</Format> ServiceRack. Look in its <Format>mappingList</Format> which will explain and provide examples for how to specify such oai mappings from the <AutoText text="DLS" type="italics"/> metadata format that the <b>demo</b> collection uses, to the Dublin Core (<AutoText text="oai_dc" type="italics"/>) metadata used by Greenstone's OAI server. Its <AutoText key="metadata::dls.Title"/> metadata is mapped to <AutoText text="oai_dc.title"/> using the following line in the collectionConfig.xml configuration file (note the use of case):</Text>
     3717<Format>&lt;mapping&gt;dc:title,dls.Title&lt;/mapping&gt;</Format>
     3718<Text id="oaiserver-24">Because the <AutoText text="backdrop"/> collection uses DC metadata, no mapping is required, as the default mappings from DC metadata to <AutoText text="oai_dc" type="italics"/> are already specified in OAIConfig.xml.</Text>
    37163719</MajorVersion>
    37173720</NumberedItem>
    … …  
    37763779<Content>
    37773780<Comment>
    3778 <Text id="0734">GLI can serve as an OAI client application: it can connect to a remote OAI server and retrieve metadata, even download documents. The tutorial <TutorialRef id="OAI_collection"/> did not obtain the data from an external OAI-PMH server. This missing step is accomplished either by running a command-line program or by using the <AutoText key="glidict::GUI.Download"/> panel in the Librarian Interface. This exercise explains you would do this using both methods. In the previous exercise, we set up the Greenstone server to serve the <b>Simple image collection (backdrop)</b> over OAI. In this tutorial, we will use GLI to connect to that OAI server and download OAI metadata for the <b>Simple image collection</b> and even download its documents. The principle is the same if you wish to connect to other OAI servers.</Text>
     3781<Text id="0734">GLI can serve as an OAI client application: it can connect to a remote OAI server and retrieve metadata, even download documents. The tutorial <TutorialRef id="OAI_collection"/> did not obtain the data from an external OAI-PMH server. This missing step is accomplished either by running a command-line program or by using the <AutoText key="glidict::GUI.Download"/> panel in the Librarian Interface. This exercise explains how you would do this using both methods. In the previous exercise, we set up the Greenstone server to serve the <b>Simple image collection (backdrop)</b> over OAI. In this tutorial, we will use GLI to connect to that OAI server and download OAI metadata for the <b>Simple image collection</b> and even download its documents. The principle is the same if you wish to connect to other OAI servers.</Text>
    37793782</Comment>
    37803783<Heading>
    … …  
    37823785</Heading>
    37833786<NumberedItem>
    3784 <Text id="gli-oai-2">Launch GLI. This should launch the Greenstone server as well, if this is not already running, so that the OAI server is also up and running.</Text>
     3787<Text id="gli-oai-2"><MajorVersion number="3">Quit any running Greenstone installations. </MajorVersion>Launch GLI. This should launch the Greenstone server as well,<MajorVersion number="2"> if this is not already running,</MajorVersion> so that the OAI server is also up and running.</Text>
    37853788</NumberedItem>
    37863789<NumberedItem>
    … …  
    37893792<NumberedItem>
    37903793<Text id="gli-oai-4">On the right, set the <AutoText text="Source URL"/> field to contain the URL to your Greenstone OAI server. It would be of the form</Text>
    3791 <Format>http://&lt;hostname:portnumber&gt;/greenstone/cgi-bin/oaiserver.cgi</Format>
     3794<Format>
     3795<MajorVersion number="2">http://&lt;hostname:portnumber&gt;/greenstone/cgi-bin/oaiserver.cgi</MajorVersion>
     3796<MajorVersion number="3">http://&lt;hostname:portnumber&gt;/greenstone3/oaiserver</MajorVersion>
     3797</Format>
    37923798<Text id="gli-oai-5">Make sure that you can generally access this URL from your browser.</Text>
    37933799</NumberedItem>
    … …  
    37963802</NumberedItem>
    37973803<NumberedItem>
    3798 <Text id="gli-oai-7">If at this stage you were to press the <AutoText key="glidict::Download.ServerInformation"/> button (in the central row of buttons), a dialog will pop up with basic details about the OAI server. At the end, it will diplay the names of the sets available via that OAI Server. In our example, <AutoText text="backdrop" type="italics"/> (the Simple Image collection) would be listed as one of the setNames.</Text>
    3799 </NumberedItem>
    3800 <NumberedItem>
    3801 <Text id="gli-oai-8">Tick the <AutoText key="perlmodules::OAIDownload.metadata_prefix_disp"/> checkbox as well as the <AutoText key="perlmodules::OAIDownload.set_disp"/> checkbox. For the latter, type <AutoText text="backdrop" type="italics"/> for the <AutoText text="set"/> name. Then tick <AutoText key="perlmodules::OAIDownload.get_doc_disp"/>, <AutoText key="perlmodules::OAIDownload.get_doc_exts_disp"/> and add <AutoText text="jpg" type="italics"/> to the list of comma separated values for it so that it becomes</Text>
     3804<Text id="gli-oai-7">If at this stage you were to press the <AutoText key="glidict::Download.ServerInformation" type="button" /> (in the central row of buttons), a dialog will pop up with basic details about the OAI server. At the end, it will diplay the names of the sets available via that OAI Server. <MajorVersion number="3">A <Format>setSpec</Format> and a <Format>setName</Format> property will be defined for each available set. </MajorVersion>In our example, <AutoText text="backdrop" type="italics"/> (the Simple Image collection) would be listed as one of the setNames<MajorVersion number="3"> with its <Format>setSpec</Format> as <Format>localsite:backdrop</Format></MajorVersion>. Press the <AutoText text="close" type="button" /> to close the <AutoText key="glidict::Download.ServerInformation"/> dialog.</Text>
     3805</NumberedItem>
     3806<NumberedItem>
     3807<Text id="gli-oai-8">Tick the <AutoText key="perlmodules::OAIDownload.metadata_prefix_disp"/> checkbox as well as the <AutoText key="perlmodules::OAIDownload.set_disp"/> checkbox. For the latter, type <MajorVersion number="2"><AutoText text="backdrop" type="italics"/> for the <AutoText text="set"/> name</MajorVersion><MajorVersion number="3">the setSpec value of <AutoText text="localsite:backdrop" type="italics"/></MajorVersion>. Then tick <AutoText key="perlmodules::OAIDownload.get_doc_disp"/>. Also tick <AutoText key="perlmodules::OAIDownload.get_doc_exts_disp"/> and include <AutoText text="jpg" type="italics"/> in the list of comma separated values for it so that it becomes</Text>
    38023808<Format>jpg,doc,pdf,ppt</Format>
    38033809<Text id="gli-oai-9">Next, tick <AutoText key="perlmodules::OAIDownload.max_records_disp"/> and set it to 10. There will be 9 images in the collection, so we don't really need to set the Max records value, but this is a helpful feature that you can use when downloading from an OAI server.</Text>
    … …  
    38193825</NumberedItem>
    38203826<NumberedItem>
     3827<Text id="oai-11a">Start up the Greenstone server again.</Text>
     3828</NumberedItem>
     3829<NumberedItem>
    38213830<Text id="0739">Open a DOS window to access the command-line prompt. This facility should be located somewhere within your <Menu>Start &rarr; Programs</Menu> menu, but details vary between different Windows systems. If you cannot locate it, select <Menu>Start &rarr; Run</Menu> and enter <i>cmd</i> in the popup window that appears.</Text>
    38223831</NumberedItem>
    … …  
    38273836<NumberedItem>
    38283837<Text id="0741">Type:</Text>
    3829 <Command>setup.bat</Command>
    3830 <Text id="0742">to set up the ability to run Greenstone command-line programs. On Linux/Mac, you would run <Command>source setup.bash</Command>.</Text>
     3838<Command>
     3839<MajorVersion number="2">setup.bat</MajorVersion>
     3840<MajorVersion number="3">gs3-setup.bat</MajorVersion>
     3841</Command>
     3842<Text id="0742">to set up the ability to run Greenstone command-line programs. On Linux/Mac, you would run <Command>source <MajorVersion number="2">setup.bash</MajorVersion><MajorVersion number="3">gs3-setup.sh</MajorVersion></Command>.</Text>
    38313843</NumberedItem>
    38323844<Comment>
    … …  
    38343846</Comment>
    38353847<Comment>
    3836 <Text id="0744">The <AutoText text="downloadfrom.pl"/> script can download using several different protocols. These are specified using the <AutoText text="-mode"/> option. To see the available options for download mode, run <Format>perl -S downloadfrom.pl -h</Format>. This shows that the current options are: <AutoText text="Web, MediaWiki, OAI, Z3950, SRW"/>. For OAI downloading, use <b>-mode OAI</b></Text>
     3848<Text id="0744">The <AutoText text="downloadfrom.pl"/> script can download using several different protocols. These are specified using the <AutoText text="-download_mode"/> option. To see the available options for download mode, run <Format>perl -S downloadfrom.pl -h</Format>. This shows that the current options are: <AutoText text="Web, MediaWiki, OAI, Z3950, SRW"/>. For OAI downloading, use <b>-download_mode OAI</b>.</Text>
    38373849</Comment>
    38383850<Comment>
    … …  
    38403852</Comment>
    38413853<NumberedItem>
    3842 <Text id="0746">We'll use the <Format>set</Format> and <Format>max_records</Format> OAI Download options to download a maximum of 5 OAI records from the <b>backdrop</b> collection at your Greenstone's OAI server, which was made available over OAI as a <AutoText text="set" type="italics"/> in the previous tutorial:</Text>
    3843 <Format>perl -S downloadfrom.pl -mode OAI -url http://&lt;hostname:portnumber&gt;/greenstone/cgi-bin/oaiserver.cgi -set backdrop -max_records 5</Format>
    3844 <Text id="0747">The records (and optionally documents) will be downloaded into the folder where the downloadfrom.pl script is run from. To change this, use the <Format>-cache_dir <i>full-path-to-folder</i></Format> option and set its value to the full path of the destination folder you choose.</Text>
     3854<Text id="0746">We'll use the <Format>set</Format> and <Format>max_records</Format> OAI Download options to download a maximum of 5 OAI records from the <b>backdrop</b> collection at your Greenstone's OAI server<MajorVersion number="2">, which was made available over OAI as a <AutoText text="set" type="italics"/> in the previous tutorial</MajorVersion><MajorVersion number="3"> again</MajorVersion>:</Text>
     3855<Format>
     3856<MajorVersion number="2">perl -S downloadfrom.pl -download_mode OAI -url http://&lt;hostname:portnumber&gt;/greenstone/cgi-bin/oaiserver.cgi -set backdrop -max_records 5</MajorVersion>
     3857<MajorVersion number="3">perl -S downloadfrom.pl -download_mode OAI -url http://&lt;hostname:portnumber&gt;/greenstone3/oaiserver -set localsite:backdrop -max_records 5</MajorVersion>
     3858</Format>
     3859<Text id="0747">The records (and optionally documents, if you additionally pass in the <Format>-get_doc</Format> flag to the above command) will be downloaded into the folder where the downloadfrom.pl script is run from. To change this, use the <Format>-cache_dir <i>full-path-to-folder</i></Format> option and set its value to the full path of the destination folder you choose.</Text>
    38453860</NumberedItem>
    38463861<Comment><Text id="0748">You can import the downloaded documents into a new Greenstone collection and build them in the usual manner.</Text></Comment>
    … …  
    38533868</NumberedItem>
    38543869<NumberedItem>
    3855 <Text id="gli-oai-15">Open GLI, locate files you downloaded over OAI and drag and drop these into a new Greenstone collection called <AutoText text="OAI Collection" />. Because there are <Format>*.oai</Format> files among those downloaded, GLI will offer to add the <AutoText text="OAIPlugin"/>.</Text>
     3870<Text id="gli-oai-15">Open GLI, locate files you downloaded over OAI and drag and drop these into a new Greenstone collection called <AutoText text="OAI Collection" />.<MajorVersion number="2"> Because there are <Format>*.oai</Format> files among those downloaded, GLI will offer to add the <AutoText text="OAIPlugin"/>. You may wish to go to the <AutoText key="glidict::GUI.Design"/> panel and remove the <AutoText text="EmbeddedMetadataPlugin"/> from the list of <AutoText key="glidict::CDM.GUI.Plugins"/> to speed up building.</MajorVersion></Text>
    38563871</NumberedItem>
    38573872<NumberedItem>
Note: See TracChangeset for help on using the changeset viewer.