IEDB LinkOut

1.  Overview

The IEDB links to a wide variety of online resources such as full-text publications, research tools and other biological databases.  IEDB LinkOut is a mechanism to place links on IEDB web pages to other online external resources.  This topic describes how resource providers may submit LinkOut requests and information.  This topic also defines how those resources will be linked from the IEDB.  IEDB LinkOut is modeled after the Entrez LinkOut service.

2.  IEDB LinkOut Locations

IEDB database records can be linked to web based external resources via LinkOuts.  These LinkOuts will be provided on display pages for the following IEDB specific identifiers: IEDB Epitope ID, IEDB MHC Allele ID, IEDB Source Organism ID, and IEDB Reference ID.  The generated link will appear in the Links tab on the details page for the specific identifier (see Table 1).

Table 1. IEDB Page URLs

Users will be able to access the external resource via a URL or icon.  The URLs to LinkOut resources will be provided by the person or organization that owns or created the resource.  Links can be provided in any URL syntax and providers of these resource links may choose to provide as much or as little access to their resource as they wish.

LinkOuts will be maintained by the IEDB in a database that will contain all linking information for the external resources.  This will allow IEDB to manage linking in a flexible manner and allow resource providers to update their linking information as frequently as necessary.  

3.  Required LinkOut Elements

The IEDB must have specific LinkOut information in order to create links: a Resource file and a LinkSet file.  The LinkOut information will be stored by the IEDB and contains the relationship between a resource link and all of the applicable unique IEDB identifiers.  This information is supplied to the IEDB as two distinct files from the resource provider.  Note that the required files are submitted in XML and that file names are case sensitive.

3.1  Resource File

The Resource file contains information about the resource to which links are provided.  See Table 2 below for the Resource file elements and their definitions.  The resource identifier (Id) will be a unique resource identifier assigned by IEDB.  This unique resource identifier will link the resource file to the appropriate LinkSet file.  The only optional resource file element is the IconURL.  The LinkOut resource file must be supplied the first time a submission is made to the IEDB and must be maintained upon further submissions.  Resource files must end in a RF file extension (e.g., sample.rf).  The current version of the Resource file XML schema is available here and a sample Resource file can be found here.  Please note that the sample Resource file uses the XML file extension to allow browsers and text editors to recognize the file type, any submitted Resource files must use the RF file extension.

Table 2. Resource File Elements

3.1.1  Resource File - Icons

Icons are optional resource file elements and can be used in place of resource links when displayed on a page.  The icon file name should not use special characters or spaces. Examples of acceptable file names are:  tool.gif, analysis.jpg.

Icons themselves should be:

• Preferred size:  100 x 25 pixels. (Maximum size allowed is 150 x 35 pixels)
• Image format:  GIF, JPEG, or PNG
• Identification:  The icon should clearly identify the resource being linked to and should include the name of the resource.
• Button:  Should look like an actionable button.  The icon should have a border and/or a colored background.  Icons and text should be easy to read and should not blend in to the display.  Animated icons are not allowed.

3.2  LinkSet File

The second required file is the LinkSet file, which contains information about all links and the IEDB identifiers where they will be displayed.  Links described in this file should link directly to the resource; users should not have to perform any additional searching to access the resource after clicking the resource link.  The LinkSet file can be changed over time.  An important restriction is that the IEDB only accepts full link/resource files.  Incremental changes to links should not be supplied as they will replace existing LinkSet files.  Table 3 defines all of the LinkSet elements.  LinkSet files must end in a LSF file extension (e.g., sample.lsf).  The current version of the LinkSet file XML schema is available here and a sample LinkSet file can be found here.  Please note that the sample LinkSet file uses the XML file extension to allow browsers and text editors to recognize the file type, any submitted LinkSet files must use the LSF file extension.

Table 3. LinkSet File Elements

4.  Request for LinkOut Account

To obtain links from the IEDB to their external resource, users must first request to participate.  An e-mail should be sent to linkout@iedb.org requesting a LinkOut account and include the following information:

• Primary contact name, e-mail address and phone number
• The title of the resource
• The scope of the resource
• The URL of the resource
• Description of any access restrictions to the resource site

Resources eligible for linking must be directly relevant to the IEDB and useful to IEDB users.  Resources from professional societies, government agencies, educational institutions, or individuals and organizations that have received grants from major funding organizations are preferred.  Once approved to participate, users will be assigned an IEDB LinkOut account.  The user will be provided a resource ID, username, and password for an IEDB SSH File Transfer Protocol (SFTP) account.  Please note that each resource provider will only be given one SFTP account but a single provider may submit multiple LinkSet files.

5.  IEDB LinkOut Submission

After your application for IEDB LinkOut has been accepted, prepare a Resource file and LinkSet file following the appropriate XML schema.  A unique user name and password will be provided to you along with the SFTP connection information.  Using the login information you will be able to upload the XML files to the SFTP site.  The IEDB will process the XML files on a periodic basis, with a maximum frequency of once a week. This process is subject to potential revision in the future.

6.  LinkOut File Maintenance

Resource providers may upload new versions of existing files or add new files at any time.  IEDB links will be generated on a regular basis and will be dependant on the files in each resource provider's directory.  IEDB LinkOut staff will not maintain the resource files.  Resource providers must maintain their directories and are responsible for updating files, which includes: new link additions, changes to links, deleting obsolete links, and correcting broken or incorrect links in a timely manner.