Quick Reference

Introduction

This 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 features

User interface controls

Most 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 based on the what the current user is authorized to see based on their 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.

IPTMenuBarHomeAbout
Figure 1. Menu bar before login or after a user having no special role logs in, with the Home menu active:
IPTMenuBarHomeManageAbout
Figure 2. Menu after a user having a Manager role logs in, with the Manage Resources menu active:
IPTMenuBarHomeManageAdminAbout
Figure 3. 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:

Control TextBoxExample

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: Control CheckboxExample

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: Control SelectBoxExample

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: Control LinkExample

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: Information CharacterEncoding

Documentation icon Control DocumentationIcon - 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.

Trash icon Control TrashIcon - this icon is associated with other controls on the page. Clicking on the icon will delete the associated data.

Calendar icon Control CalendarIcon - 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.

Example calendar associated with an text box labeled "End Date" in which 31 Dec 2010 is the current date but not yet selected:

Control TextBoxWithCalendarOpen

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 table in the opposite direction.

Example table sorted in ascending order by the column labeled "Name". Control TableSortedAscending

Example table sorted in descending order by the column labeled "Type". Control TableSortedDescending

File upload

Files can be uploaded in the IPT during two actions: when creating a new resource, or when adding new source data files.

Control UploadCreateResource

Control UploadSourceData

The IPT has an upload size limit of 100MB. There is no limit to the size of Darwin Core Archive the IPT can export/publish though. For loading datasets larger than 100MB in size into the IPT, the following work-arounds are recommended:

  • compressing the file (with zip or gzip)

  • loading the data into one of the many databases supported by the IPT

  • splitting the file up (when the dataset is published the IPT will concatenate the files in the order they are mapped)

Controls that appear on all pages

This section describes several features that are accessible in the header and footer of most of the pages of the IPT.

The header section of the IPT appears in the upper right of most pages and allows basic control over the IPT, including 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:

IPTHeaderNotLoggedIn

Header, logged in, English language chosen for the user interface:

IPTHeaderLoggedIn
  • 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. Only an existing user having the Admin role can create new users. 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.

  • Logout - If someone is logged in to the IPT, the email address of the person who is logged in is given in the upper right-hand corner of the page along with a "Logout" link.

  • Account - To see this link and the page to which it leads, you must be logged into the IPT. The page shows the details of the account information for the person who is logged in to the IPT and allows them to be changed. The details of the fields found on this page can be found under the "Configure User accounts" heading in the "Administration Menu" section.

  • Language selection - In the upper right-hand corner of the page is a name depicting the language in which the IPT is currently being presented. The default language for the IPT is English. The language of the user interface can be changed by selecting a name for the desired language, if available. GBIF actively seeks translations for the IPT into additional languages. For more information, consult the How to Translate page.

The footer section of the IPT appears along the bottom of most pages and contains information about the IPT version and links to important resources.

IPTFooter
  • 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.

  • About the IPT - This link leads to the IPT website, where further information about the IPT can be found, including the version history, roadmap, uptake statistics, and further related documentation.

  • User Manual - This link opens the most recently released online version of the IPT User Manual.

  • Report a bug - This link opens the list of known open issues for the IPT. If you think you have encountered a bug, look at the list of known issues first to see if the bug has already been reported. If it has, you may add new information as a comment to the existing bug report that might help engineers to diagnose the problem and get it fixed. If no bug similar to the one you have encountered in the IPT appears on the list, you can create a new bug report by clicking on the "New issues" link. When entering a bug report, it is useful to include the version of the IPT you are using (see the explanation for "Version", above).

  • Request new feature - This link opens a specific form in the IPT issue tracker that can be filled in to request a capability that the IPT does not currently have.

  • Copyright - The copyright for the IPT software is held by the Global Biodiversity Information Facility. A link to the home page for GBIF is provided. Details of the copyright and licensing can be seen in the "About the IPT" section of this user manual.

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.

IPTHome

Public Resources Table

If 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)

  • Name - the title of the resource as given in the Title entry of the resource metadata. The Name appears as a link, which will open the resource’s homepage (see below).

  • Organisation - the organisation under which the resource has been registered, if any. If the resource is not registered, the value in the Organisation column will be "Not registered". Review the information under the "Organisations" heading in the "Administration Menu" section for more information about registering organisations and registering a resource under an organisation.

  • Type - the type of the resource as given in the Type drop down on the Basic Metadata page of the resource metadata

  • Subtype - the subtype of the resource as given in the Subtype drop down on the Basic Metadata page of the resource metadata

  • Records - the number of rows of data in the core data file of the last published Darwin Core Archive for the resource. For resources having data in one or more extension files, the number links to the Data Records page on the resource homepage showing a breakdown of record counts by extension.

  • Last modified - either the date the resource was created or the date on which the data or metadata were last modified, whichever is more recent.

  • Last publication - the date the resource was last published.

  • Next publication - the date the resource will be published next.

RSS feed

The IPT supports syndication via RSS for those who wish to monitor when new resource versions get published, and how resources change over time. In fact each time a new resource version is broadcast, it will include a summary of what changed since the last version (assuming the publisher entered a change summary, otherwise it defaults to the resource description). 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.

Registered resource inventory

The IPT provides a simple JSON inventory of all registered resources. This feature isn’t shown on the user interface. To view simply append /inventory/dataset to the IPT public URL, e.g. https://ipt.gbif.org/inventory/dataset. GBIF uses this inventory to monitor whether it is properly indexing resources by comparing the target and indexed record counts.

Resource homepage

The resource homepage is aimed at external users of a resource. The homepage lists all the metadata about a selected version of a resource, provides links to download the version’s data/metadata, and displays the resource’s version history.

To view the resource homepage, user can click on the name link in the list of resources on the Home page. Another way to get to the resource’s homepage is using its DOI: when a resource is assigned a DOI via the IPT, it always resolves to its homepage.

Please note only a user having the Admin role or one of the Manager roles can edit a resource’s metadata. To learn more, please refer to the information under the "Edit an existing resource" heading in the "Manage Resources Menu" section.

IPTHomeMetadataOverview

Version history

The version history table lists all published versions of the resource, enabling users to track changes to the resource over time and download previous versions' data/metadata. Please note, the IPT’s Archival Mode must be turned on in order for old versions of DWCA to be stored (see the Configure IPT Settings section). Only versions that are publicly accessible can be viewed by external users, whereas admins and resource managers can see all versions. For explanations of the table columns, refer to the information below.

IPTVersionHistoryTable

Following are explanations of the table columns:

  • Version - the published version’s version number, which uses the major_version.minor_version format. The version of the resource homepage currently being viewed is clearly indicated. To open a specific version’s homepage, click on the version number. Note: A major version change compared to the last published version indicates that a scientifically significant change has taken place.

  • Published on - the date the published version was released.

  • Records - the number of records the published version contains.

  • Change summary - a summary of what has changed since the last published version.

  • DOI handle - the DOI handle assigned to the published version. Note: If the DOI is different from the DOI of the last published version, this indicates that a scientifically significant change has been done to the resource.

  • Last modified by - the IPT user that last modified the published version.

Manage Resources Menu

Section moved to Manage Resources.

Administration Menu

Section moved to Administration.

About Menu

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.

IPTAbout

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>