|
IPT2ManualNotes
The GBIF Integrated Publishing Toolkit User ManualIPT Version: 2.0.3 For the IPT Version 2.0.2 User Manual, please go here
IntroductionAbout the GBIF Integrated Publishing ToolkitThe GBIF Integrated Publishing Toolkit (IPT) is a freely available open source web application that makes it easy to share three types of biodiversity-related information: primary taxon occurrence data, taxon checklists, and general metadata about data sources. An IPT instance as well as the data and metadata registered through the IPT are connected to the Global Biodiversity Resources Discovery System (GBRDS - also known as the GBIF Registry), are indexed for consultation via the GBIF network and portal, and are made accessible for public use. More information about the GBIF IPT can be found at http://www.gbif.org/informatics/infrastructure/publishing/. Founded and funded by governments in 2001, The Global Biodiversity Information Facility (GBIF) is the world's largest multi-lateral initiative for enabling free access to biodiversity data via the Internet. GBIF's diverse Participants include primarily countries and international organisations. GBIF also has formal partnerships with relevant international treaty bodies. GBIF's mission is to promote and enable free and open access to biodiversity data worldwide via the Internet to underpin science, conservation and sustainable development. More information about GBIF can be found at http://www.gbif.org/. Several factors have provided motivation for GBIF to lead the development of the IPT:
How to Use this ManualThis manual has three main components: an introduction with background information, a number of step-by-step tutorials and a complete reference guide including a "getting started" section and sections describing in detail the different elements of the tool. All users are encouraged to review this introductory part and then refer to the different specific sections depending on their role(s) regarding the IPT installation. The IPT (and this manual) differentiates three type of users:
Getting Started GuideThis Getting Started Guide is meant for those wishing to install and run an IPT instance for the first time. If you would like to see a functional installation of the IPT in action, you may use the public test instance of the latest general release version at http://ipt.gbif.org/. If you do so, refer to Quick Reference Guide for details on how to use the screens you will see. Developers who wish to work with the latest revision of the source code should consult the "Developers" section of the GBIF IPT Google Code site wiki (http://code.google.com/p/gbif-providertoolkit/wiki/HowToContribute). RequirementsInternet ConnectivityThe IPT is designed under the assumption that the server on which it is run has consistent Internet connectivity. Though many functions of the IPT work even when offline, some aspects of the IPT (GBIF registration, extension installation, controlled vocabularies, and external databases for source data), require communication with external Internet resources. From the perspective of IPT administration and management, the speed of the Internet connection affects only such communications. Access to the IPT web application and its services from beyond a local intranet also requires consistent connectivity, and slow connectivity may have an adverse affect on these aspects, especially when transferring large data sets. Stable URLThough it can be used simply as a tool to generate Darwin Core Archives (see http://rs.tdwg.org/dwc/terms/guides/text/), the IPT is meant to be a discoverable and accessible Internet-based application and service. To support this functionality, the server on which the IPT is installed must be able to support access to the application and services through a stable URL. MemoryThe server hosting the IPT installation must make at least 256 MB RAM memory available to the application. Disk spaceThe space required by the IPT application is less then 20MB. The contents of the IPT data directory after installation require less than 1MB of disk storage, writable by the IPT. However, the content of the data directory will grow as resources are created, and will require space roughly equal to the size of the files or tables containing the imported data sets. A reasonable estimate for the size of a relatively rich occurrence data set is one kilobyte per record. Normal usage of the IPT appends information to the log files, which will grow over time, but which generally require minimal disk space. JavaThe server hosting the IPT must have a version no less than Java 5 installed and functional prior to the installation of the IPT. Servlet containerThe IPT application comes packaged with Jetty and therefore requires no further servlet container. Nevertheless, the IPT can be deployed in another servlet container (e.g., Tomcat) that is already in use. Information about how to use various servlet containers with the IPT can be found at http://code.google.com/p/gbif-providertoolkit/wiki/IPTServerPreparation. Install the IPTPrepare the serverBefore installing the IPT, be sure that the intended hosting server meets the minimum specifications described in the sections under "Requirements", above. Download the IPTThe latest release of the IPT software is available for download as a file named ipt.war from http://code.google.com/p/gbif-providertoolkit/downloads/list. Download this file to the server on which the IPT will run. Developers or those wishing to use the latest revision of the source code should consult the "Developers" section of the GBIF IPT Google Code site wiki at http://code.google.com/p/gbif-providertoolkit/wiki/HowToContribute. Deploy the IPT to the servlet containerFollow the normal process for deploying a web application to a servlet container. A wiki page with further information about specific installations can be found at http://code.google.com/p/gbif-providertoolkit/wiki/IPTServerPreparation. Run the IPT applicationSuccessful deployment of the IPT to the servlet container will make the IPT accessible through a web browser at a URL determined by the servlet's base URL followed by /ipt (e.g., http://localhost:8080/ipt). If the installation was successful, the initial IPT setup page will appear in a web browser using the IPT's URL. Set up the IPT for the first timeIPT setupThe first time the IPT is run, you will be presented with a few simple steps to prepare the IPT for use. The IPT setup page (see screen image, below) is the first of two setup pages and requires a location where the data for the IPT installation can be stored. The format of the location entered on the page must conform with the standard for an absolute path to a directory on the operating system where the IPT is installed; relative paths are not supported. For example, use a path such as "c:\datadir" for Windows environments or "/usr/datadir" for Unix and MacOSX environments. The IPT must have write permission to the selected location. If it does, the path can be entered in the text box provided and then click on the button labeled "Save" - the directory will be created if it doesn't already exist. It is permissible to create the data directory first with the appropriate write permissions, then enter the absolute path to the directory in the text box and click on the "Save" button. Note 1: Do not select a data directory that is vulnerable to inadvertent changes or removal. Do not use /tmp, for example, on systems where this folder may be emptied on a system restart. The data directory should be backed up regularly in keeping with an appropriate disaster recovery plan. Loss of the contents of the data directory will result in the loss of resource, user, and other configuration information and customizations to the IPT installation. Note 2: If you have a data directory from a previously running IPT of the same version and want to use that previous configuration (including users and resources), you can enter the absolute path of that data directory in this first step of the IPT setup (see also the "Starting Over" section of this Getting Started Guide). Clicking on "Save" in this case will bypass the page titled IPT setup II and present the IPT Administration page (see the screen image in the "Administration Menu" section of the Quick Reference Guide). Note 3: Click on the flag in the upper right hand corner to see whether your preferred language is available to use the IPT in.
IPT setup IIIf the initial data directory assignment step was successful, the IPT will present a second setup page (see screen image, below) on which the information about the default administrator of the IPT must be entered, along with the information about how the IPT will be accessed from the Internet. The default administrator will have a distinct login and the authority to make changes to all aspects of the IPT installation. The default administrator will be able to make additional user accounts, including other administrators having the same authority to make changes. Though administrators can be added and removed, the IPT must always have at least one. Following are explanations of the fields encountered on the second setup page:
When all of the information on the page is complete and correct, click on the button labeled "Save" to complete the IPT setup process. If a problem occurs, an error message will appear at the top of the page with recommendations about how to resolve the issue. If the setup is successful, a page confirming the success of the setup will appear.
Click on the button labeled "Continue" to open the IPT Administration page (see the screen image, below), from which further configuration of the IPT can be accomplished. Please review the explanations of all of the Administration functions before continuing. Details about the options presented on this screen are given in the "Administration Menu" section of the Quick Reference Guide. Before adding data resources to the IPT, the administrator must, at a minimum, verify the IPT settings, set the GBIF registration options, and associate the IPT with an organisation. The Organisations button is disabled by default until the GBIF registration options have been set.
Once you have completed the steps in this Getting Started Guide, your IPT is ready to add resources (data sets and metadata). You may want to complete one or more of the tutorials to understand how common IPT tasks are accomplished. For detailed explanations of any further aspects of the IPT, consult the Quick Reference Guide of this user manual. Starting OverIt is relatively easy to re-initiate the IPT and begin again with the first setup page by doing the following:
Quick Reference GuideIntroductionThis Quick Reference Guide explains in detail the capabilities of an IPT instance that has been installed, run for the first time, and tested to be functional as explained in the Getting Started Guide. The details of this guide are presented in four sections corresponding to the four "menus" available in the IPT user interface. Some tabs are only visible when a user having the appropriate rights to see them is logged in. Common featuresUser interface controlsMost user interface controls have both enabled and disabled modes. If the control is enabled, it will either commit an action when clicked (a button, for example), or it will allow changes to be made to the value bound to the control (a text, check, or select box, for example). In the latter case the changes will be saved, if possible, when the form on which they appear is saved, which is generally accomplished on a given page by clicking on a button labeled "Save". Disabled controls show the value of the associated information, but do not allow that information to be saved under the conditions in effect at the time they appear. The purpose for most user interface controls is indicated by an associated label that appears above and/or to the left of the control. Sometimes supplemental information is also accessible from an associated information icon. Menus - in the IPT, a menu bar appears below the GBIF logo on nearly every page. The menu bar is populated with menus that guide users to fundamental topics. Menu items appear only for the pages that are authorized to be seen based on the current user's role. The currently active menu is colored brightly, while inactive menus are grey. Click on a menu to open and activate the page for that topic. Menu bar before login or after a user having no special role logs in, with the Home menu active:
Menu after a user having a Manager role logs in, with the Manage Resources menu active:
Menu after a user having the Admin role logs in, with the Administration menu active:
Text boxes - allow textual information to be viewed or entered. Example text box and label for an email address:
Check boxes - allow a value to viewed or set to true (when checked) or false (when unchecked). Example check box and label to indicate that the IPT can publish resources:
Select boxes - allows a value to be viewed or selected from a list of predefined values. A select box may contain explanatory text about the selection in place of a selectable value. In this case the selection will begin with "Select " (e.g., "Select a country, territory, or island"). Click on the select box to open it and see the list of possible values. Click on one of the choices to set that value. Example select box and label for the user role, with Admin selected:
Links - opens a page other than the one on which the link occurs. Links may open the new page in the same browser window (or tab) or in a separate window (or tab). Example link to the account information page for the logged in user:
Information icon - shows a message explaining the intention of the control next to which it appears. Click on the icon next to any field to see a help message about that control. Click on it again to make the message disappear. Some information messages include a link, which, if selected, will populate the control with the appropriate value for the selection. Example information icon for character encoding after the UTF-8 link was selected:
Documentation icon Trash icon Calendar icon Example calendar associated with an text box labeled "End Date" in which 31 Dec 2010 is the current date but not yet selected:
Sortable Table - a table that allows the rows to be sorted by the values of a selected column in ascending or descending order. The column headers are the labels for the columns, which appear as links. Click on a column header to sort the table using the values in that column. Click again on the same column header to sort the the table in the opposite direction. Example table sorted in ascending order by the column labeled "Name". Example table sorted in descending order by the column labeled "Type". Controls that appear on all pagesThis section describes several features that are accessible in the header and footer of most of the pages of the IPT. HeaderThe header section of the IPT appears in the upper right of most pages and allows basic control over the IPT, including the who is using it, and in what language. Following are two screen images showing the two possible states in which the header may be found - logged in, and not logged in. Header, not logged in, English language chosen for the user interface:
Header, logged in, English language chosen for the user interface:
Login - A user who has already been created in this IPT instance can log in by entering the email address and password in the upper right-hand corner of the page, and then click on the "Login" link. New users can be created only by an existing user having the Admin role. The process for creating new users is explained under the "Configure User accounts" heading in the "Administration Menu" section. The process of initializing the IPT creates the first user having the Admin role. FooterThe footer section of the IPT appears along the bottom of most pages and contains information about the IPT version and links to important resources.
Version - At the left of the footer at bottom of the page is the version of the IPT that is currently running. The version information can be used to determine which features are included in the IPT and what bugs are known to exist. This is the version information that is requested when making bug reports. Home Menu (visible to all users)This page allows users to view a list of public resources, if any, and to look at the detailed metadata of any resource on the list.
Public Resources TableIf there are any public resources, they will appear in a table having the following columns: Logo - the resource logo (configurable in Additional Metadata page of the resource metadata) RSS feedThe IPT supports syndication via RSS for those who wish to monitor resource configuration changes. The RSS feed is accessible by clicking on the link provided below the list of public hosted resources. The RSS feed can be read in any standard RSS client. Metadata Overview pageClicking on the Name link in the list of resources on the Home page shows a new page having all of the metadata about the selected resource. This is the one page where you can easily review all of the metadata for a resource. A user having the Admin role or one of the Manager roles can edit the metadata. Refer to the information under the "Edit an existing resource" heading in the "Manage Resources Menu" section.
Manage Resources Menu (visible to users with an Admin or Manager role)This page allows users having the appropriate role (managers and administrators) to make changes to existing resources or to create new resources.
Manage Resources TableWhen the Manage Resources page is first opened, it shows a table of existing resources that the current user has permission to change, including those created by this user and those which this user has been invited to manage by others. Refer to the information under the "Public Resources Table" heading in the "Home Menu" section for detailed explanations of the Name, Organisation, Type, Subtype, Records, Last Modified, and Last publication columns. In addition, the Manage Resources Table includes the following column of basic information about the resources: Visibility - a category stating who has access to view the resource. If the resource is "Public", all users will be able to see it on the Public Resources table on the Home page. If the resource is "Private", it will be visible in the Manage Resources table only to the user who created it, to those who have been invited to manage it, and to users having the Admin role. Details about inviting others to manage a resource are given in the "Resource Managers" section under the "Resource Overview" heading in the "Manage Resources" section. Author - the IPT user who created the resource. Create New ResourceBelow the Manage Resource table is a form that can be used to create a new resource. First, a unique "shortname" must be provided for the resource. This short name will be used to uniquely identify the resource within the IPT instance, and will be used within the URL to access the resource via the Internet. The shortname must be at least three characters in length, may contain alphanumeric characters, but must not contain white space or punctuation other than hyphens or underscores (e.g., "firstresource" or "first_resource", but not "first resource" or "firstresource!"). There are several ways to create a new resource in the IPT as described in the following sections. Upload a Darwin Core ArchiveThe IPT is able to import and export valid Darwin Core Archive files up to 100MB in size. Information about Darwin Core Archives can be found on the Darwin Core web site (http://rs.tdwg.org/dwc/terms/guides/text/), with further information about the IPT's use of them on the GBIF IPT Google Code site wiki (http://code.google.com/p/gbif-providertoolkit/wiki/DarwinCore ). To import a Darwin Core Archive, click on the button labeled "Choose File", then navigate to and select the intended archive file. After selecting the file, its name will appear next to the "Choose File" button. Click on the button labeled "Create". If there is a problem importing the selected file, an error message will alert the user. If the import is successful, a Resource Overview page will appear with an informational message at the top describing the results of the import process.
Integrate an existing resource configuration folder (advanced users only)It is possible to integrate a resource from a configuration folder created under a compatible version of the IPT. To do so requires that the IPT be restarted during the process. First enter a new resource shortname as described in the introduction under the "Create New Resource" heading in the "Manage Resource Menu" section and then click on the button labeled "Create". This will open the Resource Overview page and create a folder having the same name as the shortname within the resources folder of the IPT data directory. Shut down the IPT using the method appropriate to the servlet container in which it is installed. See the IPT server preparation page (http://code.google.com/p/gbif-providertoolkit/wiki/IPTServerPreparation) for more information on restarting the IPT. With the IPT shut down, copy the contents of the resource folder you wish to integrate into the folder that was just created for the new resource, making sure to replace the newer resource.xml file with the original from the resource being integrated. After the files have been copied, restart the IPT. The new resource will be available in the IPT with the same settings that it had in the previous IPT installation. Create an entirely new resourceWith this option the resource configuration will have to be created in its entirety through the IPT forms, including loading a source data file (100MB limit) or database and mapping the fields therein to terms in the appropriate extension or extensions. Begin by entering a new resource shortname as described in the introduction under the "Create New Resource" heading above and then click on the button labeled "Create". This will open the Resource Overview page. Proceed by completing the various sections of the page based on the descriptions under the "Resource Overview" heading of the "Manage Resources Menu" section. Edit an existing resourceThe table of existing resources shows only those resources that can be edited by the current user. To edit a resource, click on the name of the resource in the table of resources. The link will open the Resource Overview page for the selected resource. Refer to the descriptions under the "Resource Overview" heading of the "Manage Resources Menu" section for details on how to edit various aspects of the resource. Resource OverviewThis page allows users having managerial permission to make changes to various aspects of a resource's configuration. The name of the resource is given at the top of the page under the menu bar. If the resource has not been given a title, the resource shortname will appear at the top of the page and will act as a title instead. Below the resource name is a table showing categories of the resource configuration on the left with corresponding summary information on the right. Each of these categories is configured separately as explained in detail in the following sections.
MetadataThis area of the Resource Overview page allows a user to see basic information about the resource metadata in the panel to the right, and to view and edit these and other metadata in detail by clicking on the button labeled "Edit" in the panel to the left. For more information about resource metadata in the GBIF context, see http://www.gbif.org/informatics/discoverymetadata/. Every resource requires a minimal set of descriptive metadata in order to be published in the GBIF network. If any of the required metadata are missing, the Resource Overview page will open with a warning message in the Metadata area of the page.
Clicking on the "Edit" button opens the Basic Metadata page, the first of a series of metadata pages. Each page will appear in sequence as the button labeled "Save" is clicked upon finishing entering data on any given metadata page. Saving the metadata on the last of the metadata pages will transition back to the Basic Metadata page. Clicking on the button labeled "Cancel" on an given metadata page will disregard any changes made on that page and return to the Resource Overview page. In a column at the right of each metadata page is a list of links to all of the metadata pages for easy reference and navigation. Click on any of the links to open the metadata page for that topic.
Following is a list of the metadata pages and their contents: Basic MetadataThis is the only metadata page that has fields that are required to be entered by the IPT. The resource title and description are required. The resource's three main contact's must also be described here: Resource contact, resource creator and metadata provider. For each contact you must supply at least a last name, a position or an organisation before you can make the resource public. The person(s) or organisation(s) responsible for the creation of the resource as it appears in the IPT and for effectively publishing the resource should add themselves as an associated party with role 'publisher'.
Geographic CoverageThis metadata page contains information about the geographic area covered by the resource. The page contains a map and associated controls that allow the user to set the geographic coverage. Below is a screen image showing the contents of the Geographic Coverage page, followed by explanations of the controls.
Taxonomic CoverageThis metadata page allows the user to enter information about one of more groups of taxa covered by the resource, each of which is called a taxonomic coverage. Each coverage consists of a description and list of taxa, where each taxon consists of a taxon name (either scientific or common) and a taxon rank. Before any taxonomic coverages are created, the page shows only a link labeled "Add new taxonomic coverage". Clicking on this link will show a text box for the description and several links. Below is a screen image showing the Taxonomic Coverage page before any data have been entered, followed by explanations of the controls seen on the page in this state.
Temporal CoverageThis metadata page contains information about one of more dates, date ranges, or named periods of time covered by the resource, each of which is called a temporal coverage. Coverages may refer to the times during which the collection or data set was assembled (Single Date, Date Range, and Formation Period), or to times during which the subjects of the data set or collection were alive (Living Time Period). Before the first temporal coverage for the resource is created, the page shows only a link labeled "Add new temporal coverage". Clicking on this link will show the default temporal coverage type "Single Date" in a select box, a text box labeled "Start Date", a calendar icon, and two links. Below is a screen image showing the default Temporal Coverage page before any data have been entered, followed by explanations of the controls seen on the page in this state.
KeywordsThis metadata page allows the user to create one or more sets of keywords about the resource. Each set of keywords can be be associated with a thesaurus that governs the terms in the list.
Associated PartiesThis metadata pages contains information about one or more people or organisations associated with the resource in addition to those already covered on the Basic Metadata page. Many of the controls on this page are in common with those for the Resource Contact on the Basic Metadata page. Explanations for the remainder of the controls are given below.
Project DataThis metadata page contains information about a project under which the data in the resource were produced. Appropriate only if the data were produced under a single project.
Sampling MethodsThis metadata page contains information about sampling methods in general, and about specific sampling steps. if appropriate. Before any Sampling Method data are entered for the resource, the page will show text boxes for three aspects of the sampling methods (Study Extent, Sampling Description, and Quality Control) and a link labeled "Add new method step".
CitationsThis metadata page contains information about how to cite the resource as well as a bibliography of citations related to the data set, such as publications that were used in or resulted from the production of the data. Each Citation, whether for the resource or in the bibliography, consists of an optional unique Citation Identifier allowing the citation to be found among digital sources and a traditional textual citation. Before any Citation data are entered, the page will show a text box for the Citation Identifier for the resource, a text box for the Resource Citation, a heading labeled "Bibliography", and a link labeled "Add new citation".
Collection DataThis metadata page contains information about the physical natural history collection associated with the resource (if any) as well as lists of types objects in the collection, called Curatorial Units, and summary information about them. Before any Collection data are entered, the page will show text and select boxes for four aspects of the collection (Name, Identifier, Parent Collection Identifier, and Specimen Preservation Type), a header for the section for Curatorial Units, and a link labeled "Add new curatorial unit".
External LinksThis metadata page contains links to the home page for the resource as well as links to the resource in alternate forms (database files, spreadsheets, linked data, etc.) and the information about them. Before any external links are entered, the page will show a text box for the Resource Homepage and a link labeled "Add new external link".
Additional MetadataThis metadata page contains information about other aspects of the resource not captured on one of the other metadata pages, including alternative identifiers for the resource. Before any alternative identifiers are entered, the page will show text boxes for the additional metadata, a header for the Alternative Identifiers area, and a link labeled "Add new alternative identifier".
Source DataThis area of the Resource Overview page allows a user to import primary data from files or databases into the IPT. If a resource has no source data it is considered a metadata-only resource, with information about a data set or collection, but without any primary data. It is possible to connect a resource to more than one data source if the sources are related to each other. More about relating multiple data sources is explained in the Implementation Guide section of the Darwin Core Text Guide. Following are explanations for the preliminary step of choosing the source data either from text files or from database sources: File as data source
After selecting the file, its name will appear to the right of the "Choose File" button.
Click on the button labeled "Clear" to remove the choice of selected file and return to the previous state before any data source was selected. Or, click on the button labeled "Add" to open the Source Data File detail page (if there is the risk of overwriting a file with the same name, a dialog opens that asks the user to confirm they actually want to overwrite it). This page shows the name of the resource along with a summary of the file characteristics (readability, number of columns detected, absolute path to the file, the file size, the number of rows detected, and the date the file was last loaded into the IPT). The Source Data File detail page allows the user to view and edit the parameters that describe the content of the selected file, and to use these settings to analyze and preview the file.
After the parameters for the data source have been set so that the file is interpreted correctly, click on the button labeled "Save" to store this configuration. If the save is successful, the Resource Overview page will appear, with summary information about the file in the right-hand column of the Source Data area. A button labeled "Edit" will also appear with the source data file summary information in the right-hand column, allowing the user to reopen the Source Data File detail page.
Should the user want to delete this source, they can reopen the Source Data File detail page and press the "Delete source file" button. Be aware though, that any mappings associated to this file will also be deleted. If the source data are contained in multiple text files, the process described in this section can be repeated for each of the files to import. A zipped folder with multiple text files can also be imported to add multiple source files in one go. Database as data source
The Source Database Detail page shows the name of the resource along with a summary of the database characteristics (readability, number of columns detected) and allows the user to view and edit the parameters that describe how to access the data from the database, and to use these settings to analyze and preview the data.
After the parameters for the data source have been set so that the data are accessed correctly, click on the button labeled "Save" to store this configuration. If the save is successful, the Resource Overview page will appear, with summary information about the data in the right-hand column of the Source Data area. A button labeled "Edit" will also appear with the source data summary information, allowing the user to reopen the Source Database detail page. Darwin Core MappingsThis area of the Resource Overview page allows a user to map the fields in the incoming data to fields in installed extensions and to see which fields from the sources have not been mapped. This option is not available until at least one data source has been successfully added and at least one extension has been installed. Once these conditions have been met, the left-hand column of the Darwin Core Mappings area will contain a select box with a list of Core Types and Extensions that have been installed. Select a Core Type and map that before selecting an extension to map. Select the appropriate extension that has fields matching the ones to map in the data source. If the appropriate core type or extension does not appear in the select box, it will have to be installed first. Refer to the information under the "Configure Core Types and Extensions" heading in the "Administration Menu" section for an explanation of how to install extensions.
After the desired core type or extension is selected, click on the button labeled "Add" to open the Data Source selection page. This page gives an explanation of the type of data the extension is meant to support, and shows a select box containing a list of all of the configured data sources.
Select the data source to map, and then click on the button labeled "Save". This will open the Data Mapping detail page and display a status message showing how many fields from the data source were automatically mapped to the fields in the extensions. Fields are automatically mapped if the field names, converted to all lower case, match each other. The Data Mapping page allows a user to specify exactly how the data accessible through this IPT resource are to be configured based on the selected extension. At the top of the page is the name of the extension to which the source data are being mapped, along with a description of the purpose of the extension. Below the extension description are two columns of information, potentially with labels separating sets of related fields in the extension and links to jump to specific labeled sets of fields on the page. The left-hand column contains the names of fields in the extension as well as a special row labeled Filter. The right-hand column contains information icons and controls (select boxes, text boxes) to set the value the extension field is supposed to contain. Under the select and text boxes there may be explanatory text about the extension field. In addition, if a field name has been chosen in the source data field select box, text labeled "Source Sample" and a button labeled "Translate" will appear below it. Descriptions of the controls that may appear in the right-hand column of the data mapping table are given below the screen image.
In addition to the explanatory information about the extension at the top of the page and the two columns described above, the Data Mapping page may have following sections, links, and buttons:
Published Release
This area of the Resource Overview page allows a user to publish a release (version) of the resource by simply clicking on the button labeled "Publish". This action does several things: First, the current metadata are written to the file eml.xml in the directory matching the resource's Shortname within the directory named "resources" in the IPT data directory. The current metadata are also saved in the same location as an incremental version of the EML file named eml-n.xml, where n is the incremental version number reflecting the number of times the EML file has been published. Second, the current primary resource data as configured through mapping (see the "Darwin Core Mappings" section under the "Resource Overview" heading in the "Manage Resources Menu" section) are written to the Darwin Core Archive file named dwca.zip in the same resource directory within the IPT data directory. Third, a data publication document in Rich Text Format (RTF) is generated. Finally, the information about the resource is updated in the GBIF Registry if the resource is registered.
VisibilityThe Visibility area of the Manage Resources page allows users having manager rights for the resource to change its visibility state. The visibility of a resource determines who will be able to view it, whether viewing is limited (private), open (public), or discoverable through the GBIF Registry (registered). By default, each resource is visible only to the user who created it and any other users who have the Admin role on the IPT where the resource is created.
If the attempt to register is successful, a message will appear at the top of the page saying that the status has been changed to "Registered".
Resource Managers
Each resource has one or more explicitly assigned managers who are allowed to view, change, and remove the resource. The user who creates a resource automatically has these capabilities. Additional managers can be associated with a resource and given these same capabilities by selecting them by name from the select box in this area of the Resource Overview page, then clicking on the button labeled "Add". Any manager associated with a resource and having the role "Manager with registration rights" may also register the resource and update it in the GBIF registry. All users having the Admin role automatically have complete managerial roles for all resources in the IPT instance. The right-hand column of this area shows the name and email address of the creator of the resource. If any managers have been added, their names and email addresses will be listed under the creator. Any added manager can have the managerial role for the resource removed by clicking on the button labeled "Delete" to the right of the email address in the manager listing.
Delete a ResourceClicking on the button labeled "Delete" on the Resource Overview page will remove the resource from the IPT and all of the related documents from the file system. If you intend to remove a resource that has been registered with GBIF, you should also inform the GBIF Help Desk (helpdesk@gbif.org) that you would like it to be unregistered. If you want to preserve the resource information but remove the resource from the IPT, make a copy of the folder for the resource to a safe location outside of the IPT directory structure. The name of the folder for the resource is the same as the resource Shortname, and can be found under the folder named "resources" in the IPT data directory. A resource saved in this way can be re-integrated into the IPT, or integrated with a distinct IPT instance by following the procedure described in the "Integrate an existing resource configuration folder" section under the "Create New Resource" heading in the "Manage Resources Menu" section. Administration Menu (visible only to users having the Admin role)This section describes each of the functions that are accessible from the Administration menu. Clicking on the Administration menu opens a page (see screen image, below) from which each of these specific administrative tasks can be accessed by clicking on the appropriate button. Note that the button labeled "Organisations" will remain disabled by default until the GBIF registration options have been set.
Configure IPT settingsThis page allows a user having the Admin role to make and change settings for the characteristics of this IPT instance.
Base URL - This is the URL that points to the root of this IPT installation. The URL is set automatically during the installation of the IPT. The Base URL must be accessible via the Internet in order for the IPT to function fully. Configuring the IPT Base URL to use localhost, for example, will not allow the instance of the IPT to be registered with GBIF, will not allow the IPT to be associated with an organisation and will not allow the resources to be publicly accessible.
Google Analytics key - If you would like to track the use of your instance of the IPT with Google Analytics, you can enable it to do so by entering your Google Analytics key in this text box. This is distinct from enabling GBIF to track the use of this instance of the IPT, which can be enabled using the check box described below. For more information about Google Analytics, see http://www.google.com/intl/en/analytics/index.html. Enable GBIF Analytics - Check this box if you would like to enable GBIF to track this instance of the IPT with Google Analytics. Debugging Mode - Check this box if you would like the IPT to begin logging in the verbose debugging mode. Debugging mode is generally unnecessary unless you are trying to track a problem with the IPT. The IPT log file is located in the file debug.log in the IPT's data directory. The data directory is set during the first step in the installation process (see the Getting Started Guide). Refer to the information under the "View IPT logs" heading of the "Administration Menus" section for an easy way for users having the Admin role to view the debug.log file. IPT Server Location - This area of the page allows the Admin to set the geographic coordinates (latitude and longitude) of the location of the server on which the IPT is installed. Setting these coordinates allows GBIF to map the location of this among other registered IPT installations around the world. Publish all resourcesThis option is an administrative action just like the Publish button, only it publishes ALL resources. Therefore for each resource, it creates a new DwC-A, EML, and RTF, and broadcasts the update to the Registry and via RSS. In addition, it also updates the IPTs metadata in the Registry. If any of the following conditions have been met since the last time the resources were updated, click on this button to make the necessary updates:
Configure User accountsThis page allows users having the Admin role to create, modify, and delete user accounts. When the page is opened, it shows a table of existing users and basic information about them including their names, email addresses, roles, and the date and time of their last logins.
Create a new userA new user can be created by clicking on the button labeled "Create" below the list of existing users. This will open a page on which the information about the user can be entered, after which the new user can be created by clicking on the button labeled "Save".
Email - The current email address of the user is used as an identifier to log in within the IPT and can not be changed. Modify an existing userInformation about users can be changed in the user details page after selecting the name of the user you wish to modify from the list of existing users. The user detail page shows all of the information about that user. The first name, last name, and role for the user can be changed by entering the new values and clicking on the button labeled "Save". Details of the information to be entered on this page can be found in the explanations in the "Create a new user" section, above.
Reset password - If a user forgets a password, a new one can be generated by clicking on the button labeled "Reset Password", after which a new password is given in an information message at the top of the page. Delete a userUsers accounts that are no longer necessary can be deleted using the user detail page accessed by selecting the name of the user you wish to delete from the list of existing users. On the bottom of the user detail page, click on the button labeled "Delete" to remove this user account. There are several conditions under which a user cannot be deleted. A user cannot delete an account while logged in to that account. It must be deleted from another account having the Admin role. Also, the IPT installation must always have at least one user having the Admin role, so the last remaining Admin can not be deleted. To remove that user, first create a new user having the Admin role and log in with that new user to delete the other Admin account. Finally, each resource must have at least one associated user having either the Admin or one of the Manager roles, so the last remaining Manager of a resource can not be deleted. To remove that user, first associate another user having the Admin or one of the Manager roles with any resources for which the user you wish to delete is the last remaining manager. Refer to the information under "Resource Managers" in the "Edit an existing resource" section above to see how new managers can be assigned. Configure GBIF registration optionsThis page allows a user to register the IPT instance in the GBIF Registry if this has not already been done. The IPT must be registered before any of the IPTs resources can be associated with an organisation (see the information under the "Configure Organisations" heading in the "Administration Menu" section) or published (see the Published Release section under the heading "Resource Overview" in the "Manage Resource Menu" section). Information about a registered IPT and its public resources become searchable through the Registry's services, and the data from the public resources published on the IPT can be indexed for searching via the GBIF portal. If the IPT has already been registered, the registered information for the IPT can be edited opening the "Edit GBIF registration" page. The first step to register with GBIF is to test that the IPT has a valid URL that can be reached by the GBIF services. To run this test, click on the button labeled "Validate". If the validation test is unsuccessful, an error message will suggest the nature of the problem with the communication between the GBIF Registry and the IPT. Causes for an error include: No Internet connectivity - The IPT requires an active Internet connection to function properly. An error will occur if connectivity to the Internet is lost when the button labeled "Validate" button is clicked. Restore Internet connectivity before trying to proceed with registration. Incorrect Base or Proxy URL - The Base URL is automatically detected and configured during the IPT setup process (see the "IPT Setup II" section). Changes in the configuration of the server on which the IPT is installed could require a change in the Base URL or the Proxy URL. The Base and Proxy URLs can be changed on the Configure IPT Settings page (see the explanations for Base URL and Proxy URL in the "Configure IPT Settings" section). Firewall - If the Internet connection is live, a firewall may be preventing connections to the Base URL or Proxy. Change the firewall or proxy settings to all outside connections. GBIF Registry inaccessible - If an error message suggests that none of the previous errors has occurred and yet there is a failure to communicate with the GBIF Registry, please report that there are problems connecting to the GBIF registry to the GBIF help desk (helpdesk@gbif.org).
If the IPT passes the validation step above, a form showing additional information required for registration is presented. In this step, the IPT instance is associated to an organization. The organization must already be registered in the GBIF Registry, and its password must be known. For explanations of the fields and selections on this form, refer to the information below.
Following are explanations of the specific information to select or enter: Edit GBIF registrationThis page allows a user to edit the title, description, contact name, and contact email of the IPT instance once it has been registered in the GBIF Registry. Changing the associated (host) organisation is not possible. For help changing other fields displayed in the GBIF Registry, the administrator can ontact the GBIF Help Desk (helpdesk@gbif.org).
Configure OrganisationsThis page is unavailable until the IPT instance has been successfully registered in the GBIF Registry (see the information under the "Configure GBIF registration" heading of the "Administration Menu" section). Once registered, this page shows a list of organisations that can be associated with resources in this IPT instance. An IPT that hosts data for organisations other than the one to which it is associated must have the additional organisations configured before they can be used. The list shows columns for "Organisation Name", "Alias", and "Can publish resources?" The Organisation Name is the title of the organisation as registered in the GBIF Registry. The Alias is a name given to the organisation for convenience within the IPT instance; aliases, rather then the full Organisation Name, appear in Organisation selection lists in the IPT. The checkbox under the column labeled "Can publish resources?" indicates whether the organisation can be associated with resources in the IPT. Only those organisations having this box checked will appear in lists to be associated with resources.
Edit organisationClick on the button labeled "Edit" to open the page containing the details of the selected organisation. On this page a user having the Admin role can change the Alias and select or de-select the checkbox labeled "Can publish resources? The Organisation name, Alias, and "Can publish resources?" are explained in the introduction to the "Configure Organisations" section, above, and under the "Configure GBIF registration" heading in the "Administration Menu" section.
Add organisationOrganisations are not available to be associated with resources until they are added by a user having the Admin role. Click on the button labeled "Add" to open a page on which an additional organisation can be selected from the GBIF Registry to be used in this instance of the IPT. For explanations of the fields and selections on this page, refer to the information under the "Configure GBIF registration" heading in the "Administration Menu" section of this user manual. After the desired organisation is selected and all other data entered, including the password for the organisation, click on the button labeled "Save" to add the selected organisation to the list.
Configure Core Types and ExtensionsThis page allows a user having the Admin role to enable the instance of the IPT to import and share various pre-defined types of data from the GBIF Registry. Each type includes properties (fields, terms) that support a specific purpose. For example, the Darwin Core Taxon Core Type supports information pertaining to taxonomic names, taxon name usages, and taxon concepts and allows the IPT to host resources for taxonomic and nomenclatural checklists. A distinction is made between Core Types and extensions. Core types provide the basis for data records, (Occurrence and Taxon, for example) while extensions provide the means to associate additional data with a record of the Core Type. Only one Core Type can be selected for a given resource as explained under the "Darwin Core Mappings" heading of the "Resource Overview" section. Vocabularies contain lists of valid values that a particular term in an Core Type or Extension can take. For example, the BasisOfRecord vocabulary contains all of the standard values allowed in the Darwin Core term BasisOfRecord. Before any extensions have been installed, the Core Types and Extensions page begins with a section labeled "Vocabularies" having a single button labeled "Update". Core Types and Extensions that exist in the GBIF Registry but have not yet been installed are listed below the Vocabularies section. When an extension is successfully installed, it will appear above the Vocabularies section.
The lists of extensions (installed and not installed) each have two columns. The left-hand column shows the name of the extension as a link and a button labeled either "Install" or "Remove". In the right-had column is a summary of the information about the extension, including a brief description of the type of data the extension is meant to accommodate, a link to more information about the extension if it exists, the number of properties (fields, terms) in the extension, the name of the extension, it's namespace, RowType, and keywords. For more information about these attributes of an extension, see the documentation on Darwin Core Archives at http://rs.tdwg.org/dwc/terms/guides/text/. Following are the actions that can be taken with respect to extensions: Update vocabulariesAn extension can make use of lists of terms of predefined values, known as controlled vocabularies. Periodically these vocabularies may also change and require updating the in the IPT. Click on the button labeled "Update" in the Vocabularies section to communicate with the GBIF Registry to retrieve new controlled vocabularies and updates to existing ones. After the update is complete, one or more messages will indicate how many updates were made and if there were any errors. View extension detailsThe title of each extension in the first column is a link to a detail page for that extension. The detail page shows all of the summary information that can be seen in the the right-hand column of the extensions list as well as the detailed description, references, and examples for each of the properties in the extension.
For properties that have controlled vocabularies, the property information in the right-hand column will contain the name of the vocabulary as a link next to the label "Vocabulary:". Clicking on the link will open a detail page for the vocabulary, with a summary of the vocabulary at the top and a table of the valid values with further detailed information such as preferred and alternate terms and identifiers.
Install extensionFor any of the extensions that have not yet been installed in the IPT, there is a button labeled "Install" under the extension name in the left-hand column. Click on this button to retrieve the extension from the GBIF registry and install it in the IPT. Remove extensionFor any extension that has already been installed in the IPT, it can be removed by clicking the button labeled "Remove". Extensions that are in use to map data for any resource in the IPT cannot be removed. Any attempt to do so will show an error message and a list of resources that use the extension in a mapping. View IPT logsMessages generated from actions taken while running the IPT are logged to files for reference in the directory called "logs" within the IPT data directory (see the information under the "IPT Settings" heading in the "Administration Menu" section). The View IPT logs page shows messages from the file called admin.log, which contains only those log messages that have a severity of WARNING or greater (such as errors). The complete log of messages (contained in the file called debug.log) can be opened and viewed by clicking on the link labeled "complete log file". The contents of the complete log file may be useful when reporting an apparent bug.
About Menu (visible to all users)The default About page gives information about the current IPT installation, including information about the hosting organisation, if that has been registered. This page is meant to be customized for the individual IPT instance by editing the file called about.ftl in the directory called "config" within the IPT data directory (see the information under the "IPT Settings" heading in the "Administration Menu" section). The about.ftl file is a Freemarker template that can contain a combination of HTML and variable references of the form ${host.variable!"alternate value if null"}. After making changes to the about.ftl file, the About page will have to be restarted to show the changes. Look at the default about.ftl file for examples of variables that can be included.
Here is the content of the about.ftl file resulting in the page as viewed above. <h1>About this IPT installation</h1>
<#if host.name??>
<p>This is a default IPT hosted by ${host.name}</p>
<p>You can use the following variables about the hosting organisation:</p>
<ul>
<li>description = ${host.description!}</li>
<li>name = ${host.name!}</li>
<li>alias = ${host.alias!}</li>
<li>homepageURL = ${host.homepageURL!}</li>
<li>primaryContactType = ${host.primaryContactType!}</li>
<li>primaryContactName = ${host.primaryContactName!}</li>
<li>primaryContactDescription = ${host.primaryContactDescription!}</li>
<li>primaryContactAddress = ${host.primaryContactAddress!}</li>
<li>primaryContactEmail = ${host.primaryContactEmail!}</li>
<li>primaryContactPhone = ${host.primaryContactPhone!}</li>
<li>nodeKey = ${host.nodeKey!}</li>
<li>nodeName = ${host.nodeName!}</li>
<li>nodeContactEmail = ${host.nodeContactEmail!}</li>
</ul>
<#else>
This IPT installation has not been registered yet.
</#if>About the IPTCitationThis user manual adapts and builds upon the previous IPT User Manual (Réveillon 2009). The recommended citation for this user Manual is as follows: Wieczorek, J. 2011. The GBIF Integrated Publishing Toolkit User Manual, version 2.0. Copenhagen: Global Biodiversity Information Facility. CopyrightThe GBIF Integrated Publishing Toolkit and this user manual are Copyright 2011 by the Global Biodiversity Information Facility Secretariat. LicenseThe GBIF Integrated Publishing Toolkit is open source software released under the Apache License Version 2.0. You may obtain a copy of this License at http://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, software distributed under this License is distributed on an "as is" basis, without warranties of conditions of any kind, either express or implied. See the License for the specific language governing rights and limitations under the License. This user manual is released under the Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. You may obtain a copy of this license at http://creativecommons.org/licenses/by-nc-sa/3.0/. Though you should consult the actual license document for details, in general terms the license states that you are free to copy, distribute, transmit, remix and adapt the work, under the following conditions:
ResourcesDarwin Core Archive documentationDetails about the structure of a Darwin Core Archive, abbreviated DWCA, can be found in the "Text Guide" section of the Darwin Core web site: http://rs.tdwg.org/dwc/terms/guides/text/. Further information about the IPT's use of DWCAs can be found on the GBIF IPT Google Code site wiki: (http://code.google.com/p/gbif-providertoolkit/wiki/DarwinCore ). GBIF Help DeskSend email messages to helpdesk@gbif.org to report problems with GBIF services, such as the GBIF Registry. Do not send IPT-specific help question to the Help Desk. Instead send them to the IPT mailing list (see below). GBIF RegistryUse this online application to find information about organisations, IPT instances, and resources registered with GBIF: http://gbrds.gbif.org. IPT code siteThe code site is the project repository for all of the open source code, management, and documentation of the IPT: http://code.google.com/p/gbif-providertoolkit/source/checkout/. IPT contributors mailing listSubscribe to the IPT contributors mailing list to receive messages generated by contributions to the GBIF IPT Google Code site. This group is for contributors to the IPT and those who would keep track of the changes to the code site as they occur: http://groups.google.com/group/gbif-ipt-contributors/. IPT developer documentationDevelopers who wish to contribute, or to use the latest revision of the source code for their installation should consult the "Developers" section of the GBIF IPT Google Code site wiki: http://code.google.com/p/gbif-providertoolkit/wiki/HowToContribute. IPT experts group in the GBIF Community SiteThe GBIF Community Site hosts a group for those interested in participating in helpdesk, promotion, and training activities related to the GBIF IPT. This is a place to exchange experiences, ask for help, and post opportunities, with the objective of a wider uptake of the tool inside and outside of the GBIF Network: http://community.gbif.org/pg/groups/3529/gbif-ipt-helpdesk-and-training-experts/. IPT issue trackerThe issue tracker is the bug report and feature request management system for the IPT software and documentation: http://code.google.com/p/gbif-providertoolkit/issues/list/. IPT mailing listSubscribe to the IPT mailing list to send and receive messages related to the use of the Integrated Publishing Toolkit. This group is for users to support each other in the use of the IPT: http://lists.gbif.org/mailman/listinfo/ipt/. IPT server preparationThis wiki page gives details about preparing a server to run the IPT and can be found on the IPT project code site wiki at http://code.google.com/p/gbif-providertoolkit/wiki/IPTServerPreparation. IPT software updatesThis wiki page gives details about updating aspects of the IPT, including upgrading an older installation of the IPT to a new version: http://code.google.com/p/gbif-providertoolkit/wiki/IPTUpdates. IPT supported databasesThis wiki page gives details about the database management systems to which the IPT can connect for a data source. The page can be found on the IPT project code site at http://code.google.com/p/gbif-providertoolkit/wiki/IPT2DatabaseConnection. IPT test installationGBIF provides a functional installation of the IPT for evaluation and testing purposes. The test installation of the latest release can be found at http://ipt.gbif.org. ReferencesRéveillon, A. 2009. The GBIF Integrated Publishing Toolkit User Manual, version 1.0. Copenhagen: Global Biodiversity Information Facility. 37 pp. GlossaryChecklist Resource - a resource having information about one of many types of taxon-related lists. | |
- this icon indicates that there is a detailed information page about the subject with which the icon is associated. Click on the icon to open the page in a new browser window. 
- this icon is associated with other controls on the page. Clicking on the icon will delete the associated data. 
- this icon is associated with a text field meant to contain a date. Clicking on the icon opens a small calendar with controls that allow the user to scroll forward and backward from the currently selected month and year, select boxes to choose a different month or year, and days of the week arranged in a standard New Era calendar. Selecting a specific day will place the date in the correct format into the associated text box. 
► Sign in to add a comment