Copyright Notice: http://www.ncbi.nlm.nih.gov/books/about/copyright/
NCBI Bookshelf. A service of the National Library of Medicine, National Institutes of Health.
LinkOut Help [Internet]. Bethesda (MD): National Center for Biotechnology Information (US); 2006-.
LinkOut is a service of NCBI that allows third parties to link specific NCBI database records to relevant web-accessible resources. Typically, publishers and other full-text providers use LinkOut to provide links from PubMed records to their online full-text journals.
An FAQ for Link Providers is available.
How It Works
LinkOut provides links from PubMed and other NCBI database records to online resources external to the NCBI system. All linking information is submitted by LinkOut providers - the owner or agent for the owner of the online resource. LinkOut providers are responsible for maintaining their links.
To submit links to your resource, you will need to upload two XML files, an identity file and a resource file. The identity file contains the information about your organization needed to list your resource(s) in LinkOut. The resource file describes the PubMed records you will link from and contains the information that LinkOut needs to generate the links.
All links can be viewed in the LinkOut Display. In PubMed, links can also be viewed as icons.
If your organization has a subscriber base for online full text, the links that you submit may also be used as the basis for library links. LinkOut allows libraries to display their own icon on PubMed records available through their online subscriptions. The icon links to the online full text from the provider selected by the institution. For your subscribers to link to full text at your site via PubMed, you must submit links to LinkOut (more about the use of links submitted to LinkOut).
Prerequisites for Participation
1. Journals must be included in PubMed for links to be made. To be included in PubMed, a journal must go through the MEDLINE selection process. Please see the details at:
2. Publishers of journals included in PubMed should submit their citation data electronically BEFORE submitting links to online full text. See PubMed’s Information for Publishers for details on submitting electronic data to PubMed.
When a publisher submits links without sending electronic citation data, links will be shown in the LinkOut display only. The publisher’s icon will not appear by default in PubMed’s Abstract and Records displays, unless full text is freely available (more about default icons).
3. Full-text providers that restrict access to full text may provide links to summary pages, provided that a link to the full text is prominently displayed on the summary page. In this case, providers should use one of the full-text attributes to inform users that full text is available.
For more information, see the Guidelines for Evaluation of Resources.
Apply for Inclusion in LinkOut
To apply for inclusion in LinkOut, send an email to linkout/at/ncbi.nlm.nih.gov with the following information included:
Name, email address, and phone number of a contact person in your organization.
Your account name, if your organization currently provides electronic citation data to NCBI.
The scope of your resource. Publishers should provide journal titles and ISSNs; journal aggregators may provide a description of their collection.
Describe any restrictions on access to full text.
A LinkOut team member will email the contact person within 1 week regarding your request.
File Preparation: Identity File
To create links to your resource, NCBI needs two XML files, an identity file and a resource file.
The identity file contains the information needed to list a provider in LinkOut. This file must be named providerinfo.xml; the file name is case sensitive. This file should be composed in a text editor, such as NotePad, not in a word processing program.
For complete file specifications and description of elements, see LinkOut Technical Information: Identity File or the LinkOut DTD.
The following is an example providerinfo.xml file for the LinkOut participant, Good Publisher, Inc. with Provider Id 8888 and NameAbbr GoodPublisher.
<?xml version="1.0"?>
<!DOCTYPE Provider PUBLIC "-//NLM//DTD LinkOut 1.0//EN"
"http://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd">
<Provider>
<!-- ProviderId is assigned by NCBI -->
<ProviderId>8888</ProviderId>
<Name>Good Publisher, Inc.</Name>
<NameAbbr>GoodPublisher</NameAbbr>
<SubjectType>publishers/providers</SubjectType>
<Attribute>publisher of information in URL</Attribute>
<Attribute>subscription/membership/fee required</Attribute>
<!-- Url is used in My NCBI and the LinkOut Journals and Providers lists -->
<Url>http://www.goodpublisher.com</Url>
<!-- Brief is used in My NCBI -->
<Brief>
An international publisher of biomedical journals and books
</Brief>
</Provider><SubjectType> and <Attribute> elements included in the providerinfo.xml file will apply to all links submitted by the provider. In the example above, a subscription is required to access all full text at the provider’s site, therefore <Attribute>subscription/membership/fee required</Attribute> has been included in the providerinfo.xml file.
File Preparation: Resource File
Section Contents
To create links to your resource, NCBI needs two XML files, an identity file and a resource file.
The resource file describes the PubMed records to which your links will be applied and contains the information that LinkOut needs to generate the links. Links described in the resource file must link directly to the full text, requiring no additional searching after a user clicks on the provider’s link.
Resource files must have a file extension .xml; the file extension is case sensitive. File names may contain alpha-numeric characters and underscores only. Special characters and spaces are not allowed. Typically, files are named journals.xml, or journaltitle.xml. To help with file management, a provider may submit more than one resource file.
This file should be composed in a text editor, such as NotePad, not in a word processing program.
Resource File Format
For complete file specifications and description of elements, see LinkOut Technical Information: Resource File or the LinkOut DTD.
The resource file below describes links to web-accessible full text for the journal J Cell Biol. Full text is provided by Good Publisher, Inc., ProviderId 8888.
<?xml version="1.0" ?>
<!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut 1.0//EN"
"http://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd"
[<!ENTITY icon.url "http://www.goodpublisher.com/icon/goodpublisher.jpg">
<!ENTITY base.url "http://www.goodmedical.org/cgi/content/" > ]>
<LinkSet>
<Link>
<LinkId>1</LinkId>
<ProviderId>8888</ProviderId>
<IconUrl>&icon.url;</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<Query> "J Cell Biol" [ta] AND 1997/06/15:2010[dp]</Query>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>&base.url;</Base>
<Rule>&lo.issn;/&lo.vol;/&lo.page;</Rule>
<Attribute>full-text online</Attribute>
</ObjectUrl>
</Link>
</LinkSet><ObjectList>: Selecting Records in a Resource File
The <ObjectList> element is used to select the NCBI database records to which links will be applied. <ObjectList> contains one or more <Query> elements OR one or more <ObjId> elements. <Query> elements contain a valid PubMed search that will retrieve the records to which the link described in <ObjectUrl> will be applied. <ObjId> elements contain the Unique Identifier (PMID) for records to which the link described in <ObjectUrl> will be applied.
Selecting Records Using <ObjId>
<ObjId> contains the PubMed ID (PMID) for a single PubMed record.
| Example: Select record with PMID 9679140 |
|---|
| <ObjectList> <ObjId>9679140</ObjId> </ObjectList> |
More than one <ObjId> can be used in an <ObjectList>.
| Example: Select records with PMIDs 9679140 and 12589072 |
|---|
| <ObjectList> <ObjId>9679140</ObjId> <ObjId>12589072</ObjId> </ObjectList> |
Because <ObjId> requires more maintenance than <Query>, NCBI recommends using <Query> whenever possible. When <ObjId> is used, the provider is responsible for updating the resource file as new records are submitted to PubMed.
Selecting Records Using <Query>
The <Query> element must contain a valid PubMed search. Please see Searching PubMed for information on constructing PubMed searches. Note that all components of a query would need to be valid for links to be created.
Tips for using <Query>
- 1.
Use either NLM’s Title Abbreviations [ta] or ISSN numbers in journal searches. Title Abbreviations must be entered in double quotes, e.g., “J Mol Dis” [ta].
- 2.
Include the date range for full text. Use this format: startyear:endyear[dp]. Dates should be notated as YYYY/MM/DD. Month and Day are optional.
- 3.
Ranging is not allowed in Volume, Issue, Page, or PMID searches.
- 4.
Truncation is not allowed in search statements.
- 5.
Search field tags must be enclosed in square brackets.
- 6.
To apply a rolling embargo to records included in or excluded from a query, use “last x (day|weeks|months|years)”[dp] to select records based on the time period indicated. Dates are calculated as follows: 1 week = 7 days, 1 month = 30 days, 1 year = 365 days.
- 7.
Do not use the search field tags [sb] of [filter]. The only exception is future [sb]. Future [sb] will include or exclude all citations with a publication date after today.
- 8.
Boolean operators AND, OR, NOT must be in uppercase.
| Example: Select records for the journal “J Mol Dis” starting from the publication date, June 15, 1997. As new records are submitted to PubMed, links will be applied automatically. |
|---|
| <ObjectList> <Query> “J Mol Dis” [ta] AND 1997/06/15:2010 [dp]</Query> </ObjectList> |
| Example: Select records for the journal “J Mol Dis” written by J Smith. As new records are submitted to PubMed, links will be applied automatically. |
|---|
| <ObjectList> <Query> “J Mol Dis” [ta] AND Smith J [au] </Query> </ObjectList> |
More than one <Query> can be listed within the <ObjectList>, as shown in the Example below.
| Example: Select records for the journal “J Mol Dis” with a publication date from June 15, 1997 and records for the journal “J Feet” starting from January 1, 2000. As new records are submitted to PubMed, links will be applied automatically. |
|---|
| <ObjectList> <Query> “J Mol Dis” [ta] AND 1997/06/15:2010 [dp]</Query> <Query>”J Feet”[ta] AND 2000:2010[dp]</Query> </ObjectList> |
To apply a rolling embargo to records included in or excluded from a query, use “last x (weeks|months|year)”[dp] to select records based on the time period indicated.
| Example: Select records for the journal “J Mol Dis” with publication date June 15, 1997 to the date 6 months earlier than today. Links will not be applied to records published in the last 6 months. |
|---|
| <ObjectList> <Query> “J Mol Dis” [ta] AND 1997/06/15:2010 [dp] NOT “last 6 months”[dp]</Query> </ObjectList> |
Citation providers sometimes submit records for articles that have not yet been published. “last x (weeks|months|year)”[dp] is very literal and will only select or exclude records from the past. To exclude records with a publication date in the future, use future[sb].
| Example: Select records for the journal “J Mol Dis” with publication date 1997 to the present. Links will not be applied to records published in the last six months or with a future publication date. |
|---|
| <ObjectList> <Query> “J Mol Dis” [ta] AND 1997:2010 [dp] NOT “last 6 months”[dp] NOT future[sb]</Query> </ObjectList> |
Records may also be submitted to PubMed for “ahead of print” articles (articles that are available online before they are available in print). To select these records, use pubstatusaheadofprint.
| Example: Select ahead of print records for the journal “J Mol Dis”. |
|---|
| <ObjectList> <Query> “J Mol Dis” [ta] AND pubstatusaheadofprint</Query> </ObjectList> |
<ObjectUrl>: Specifying the Link to Access Online Full Text
The <ObjectURL> element is used to describe the link to the online resource. <ObjectURL> contains the sub-elements, <Base>, <Rule>, <SubjectType>, and <Attribute>. <Base> and <Rule> are concatenated to form the URL for the link. <SubjectType> and <Attribute> describe the resource to which the record is being linked.
For definitions of SubjectType and Attribute elements, see Special Elements: SubjectType and Special Elements: Attribute.
Creating the URL for the Link
<Base> is the stable portion of the URL for the full text of the selected records. This is usually the URL of the provider’s web site or CGI program.
<Rule> is the remainder of the URL needed to access the online full text.
| Example: Create the URL http://www.goodmedical.com/articles.asp?AID=1988 |
|---|
| <Base>http://www.goodmedical.com/articles.asp?</Base> <Rule>AID=1988</Rule> |
If the URL for the full text follows a pattern using variable values that are found in the PubMed record, the pattern can be described in the <Rule> element and LinkOut can insert the appropriate values for each citation. This allows many links to be generated from the information in a single <ObjectUrl>.
URL patterns are described using LinkOut’s XML entities. An XML entity is a short text string that represents a type of value. During LinkOut processing, the text string is replaced in the URL by the appropriate value for each citation. Supported entities can be found in the list of LinkOut Entities and in the LinkOut DTD.
| Example: Create URLs following the pattern: http://www.goodmedical.org/cgi/full/id=[PMID] |
|---|
| <Base>http://www.goodmedical.org/cgi/full/</Base> <Rule>&lo.id;</Rule> |
| Example: Create URLs following the pattern: http://www.goodmedical.org/cgi/full/[ISSN]/[volume number]/[start page] |
|---|
| <Base>http://www.goodmedical.org/cgi/full/</Base> <Rule>&lo.issn;/&lo.vol;/&lo.page;</Rule> |
Entities can be combined with other information in the <Rule>.
| Example: Create URLs following the pattern: http://www.goodmedical.org/links/record/pmidlookup?view=reprint&pmid=[PMID of the record] |
|---|
| <Base>http://www.goodmedical.org/links/record/</Base> <Rule>pmidlookup?view=reprint&pmid=&lo.id;</Rule> |
LinkOut does not support Unicode (UTF-8) and requires that certain special characters be encoded in files. See Special Characters for a list of these characters and their encodings.
Describing the Resource
The elements <SubjectType> and <Attribute> are used in the <ObjectUrl> to describe the resource to which records are being linked. Available SubjectTypes can be found in Special Elements: SubjectType. Available Attributes can be found in Special Elements: Attribute.
If the available SubjectTypes and Attributes do not suffice to describe the resource, UrlName can be used as well. If no SubjectType is given, the SubjectType “miscellaneous” will be assigned automatically.
As the availability and format of resources linked from NCBI database records should be readily apparent to users, links to online full text must be described using one of the following Resource Form Attributes:
<Attribute>full-text online</Attribute>
<Attribute>full-text PDF</Attribute>
<Attribute>full-text PostScript</Attribute>
In addition, if there are any barriers to accessing the full text, one of the following Barrier Attributes must be used:
<Attribute>registration required</Attribute>
<Attribute>subscription/membership/fee required</Attribute>
Continuing with the example above, if Good Medical, Inc. requires a subscription to access HTML full text, the <ObjectUrl> element might look like this:
<ObjectUrl> <Base>http://www.goodmedical.org/cgi/full/</Base> <Rule>&lo.issn;/&lo.vol;/&lo.page;</Rule> <Attribute>subscription/membership/fee required</Attribute> <Attribute>full-text online</Attribute> </ObjectUrl>
Resource File Examples
Example 1: Dental Publications, Inc., Provider Id 1234, provides links from the PubMed records with PMIDs 98765432 and 87654321. URLs for the full text in PDF format are created using an internal identification number that is not included in PubMed, so links are created individually for each record. To minimize the repetition of textual data, the Icon URL and the Base URL have been defined as Entities in the Prolog of the file.
<?xml version="1.0"?>
<!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut 1.0//EN"
"http://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd"
[<!ENTITY icon.url "http://www.dentalpub.com/images/fulltext.gif">
<!ENTITY base.url "http://www.dentalpub.com/Articles.asp?">]>
<LinkSet>
<Link>
<LinkId>1</LinkId>
<ProviderId>1234</ProviderId>
<IconUrl>&icon.url;</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<ObjId>98765432</ObjId>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>&base.url;</Base>
<Rule>AID=1988</Rule>
<Attribute>subscription/membership/fee required</Attribute>
<Attribute>full-text PDF</Attribute>
</ObjectUrl>
</Link>
<Link>
<LinkId>2</LinkId>
<ProviderId>1234</ProviderId>
<IconUrl>&icon.url;</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<ObjId>87654321</ObjId>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>&base.url;</Base>
<Rule>AID=1989</Rule>
<Attribute>subscription/membership/fee required</Attribute>
<Attribute>full-text PDF</Attribute>
</ObjectUrl>
</Link>
</LinkSet>Example 2: Good Medical, Inc., Provider Id 4321, provides free online access to the publications Journal of Feet [ISSN 1234-5678] and Skin Graft International [ISSN 8765-4321] in HTML format. The URL to access online full text at their site follows this pattern for each article: http://www.goodmedical.org/cgi/full/[ISSN]/[volume number]/[start page]
<?xml version="1.0" ?>
<!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut 1.0//EN"
"http://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd">
<LinkSet>
<Link>
<LinkId>1</LinkId>
<ProviderId>8888</ProviderId>
<IconUrl>http://www.goodmedical.org/icon/goodmedical.jpg</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<Query>"J Feet" [ta] AND 1997/06/15:2010[dp]</Query>
<Query>"Skin Graft Int" [ta]</Query>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>http://www.goodmedical.org/cgi/full/</Base>
<Rule>&lo.issn;/&lo.vol;/&lo.page;</Rule>
<Attribute>full-text online</Attribute>
</ObjectUrl>
</Link>
</LinkSet>Example 3: A record may be retrieved by more than one <Query>. When this happens, link assignment will be handled as described in Duplicate Links and Multiple Links.
If these queries are in different Link elements, <Attribute>preference</Attribute> can be used to indicate which <Link> element should be applied to the record. This is generally used in situations where the links for a subset of a range have a different URL pattern or different access restrictions. See Duplicate Links and Multiple Links for more information.
In the example below, an article by J Smith in “J Mol Dis” published in 1998 will be retrieved by the <Query> statements in both LinkId 2 and LinkId 3.
The LinkOut provider Good Publisher, Inc. provides links to the full text of two of their journals, J Mol Dis and J Biol Chem.
LinkId 1 selects articles for PMID 9679140 and 9679141, a special case. The records are selected using <ObjId> and have a special <Rule>. They are available online in PostScript format; a subscription is required to access the full text. Because these records are also included in LinkId 3, <Attribute>preference</Attribute> is used to indicate that only this link should be applied to these citations.
LinkId 2 is for all articles authored by J Smith published in the journal J Mol Dis. These are freely available in PFD format. A special icon is used for these articles. Because these records are also included in LinkId 3, <Attribute>preference</Attribute> is used to indicate that only this link should be applied to these citations.
LinkId 3 applies to the remainder of the J Mol Dis articles and all J Biol Chem articles supplied by Good Publisher, Inc., where a subscription is required to access the full text. They are available in HTML format. This link will not be applied to the citations included in LinkId 1 and LinkId 2.
As both LinkId 1 and LinkId 2 describe specific requirements, they are listed before the general LinkId 3.
<?xml version="1.0"?>
<!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut 1.0//EN"
"http://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd"
[ <!ENTITY icon.url "http://www.goodpublisher.com/icon/goodpublisher.jpg">
<!ENTITY base.url "http://www.goodmedical.org/cgi/content/" > ]>
<LinkSet>
<Link>
<LinkId>1</LinkId>
<ProviderId>8888</ProviderId>
<IconUrl>&icon.url;</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<ObjId>9679140</ObjId>
<ObjId>9679141</ObjId>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>&base.url;</Base>
<Rule>pmidlookup?view=reprint&pmid=&lo.id;</Rule>
<Attribute>full-text PostScript</Attribute>
<Attribute>subscription/membership/fee required</Attribute>
<Attribute>preference</Attribute>
</ObjectUrl>
</Link>
<Link>
<LinkId>2</LinkId>
<ProviderId>8888</ProviderId>
<IconUrl>http://www.goodpublisher.com/pubmed/smith.gif</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<Query>"J Mol Dis" [ta] AND Smith J [auth]</Query>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>&base.url;</Base>
<Rule>&lo.issn;/&lo.vol;/&lo.page;</Rule>
<Attribute>full-text PDF</Attribute>
<Attribute>preference</Attribute>
</ObjectUrl>
</Link>
<Link>
<LinkId>3</LinkId>
<ProviderId>8888</ProviderId>
<IconUrl>&icon.url;</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<Query>"J Mol Dis" [ta] AND 1997:2010 [dp]</Query>
<Query>"J Biol Chem" [ta] AND 1996:2010[dp]</Query>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>&base.url;</Base>
<Rule>&lo.issn;/&lo.vol;/&lo.page;</Rule>
<Attribute>full-text online</Attribute>
<Attribute>subscription/membership/fee required</Attribute>
</ObjectUrl>
</Link>
</LinkSet>Linking with PII/DOI
PII and DOI are identifiers supplied by the publisher. PII is a Publisher Item Identification, assigned by the publisher for internal use. DOI is a Digital Object Identifier (more about DOI).
Links can be created using DOI or PII. Links will appear on all records in the <ObjectList> for which PII or DOI has been submitted by the publisher. NCBI does not input DOI or PII in PubMed records; to create links using PII or DOI, these values must be included when the record is submitted electronically. Publishers should submit PII/DOI for records ONLY if they will be used for linking.
To link using DOI/PII, identify a resolver that can locate the full text in the <Base> element and use the appropriate entity in the <Rule> element.
| Example |
|---|
| Retrieved record: Journal [ISSN 1234-5678]. 2004 Sep; 27(1):3-10 PMID: 98765432 DOI:10.1096/ajs59-5497 PII:12345678/2713 |
| Link using DOI: <Base>http://dx.doi.org/</Base> <Rule>&lo.doi;<Rule> Resulting URL: http://dx.doi.org/10.1096/ajs59-5497 |
| Link using PII: <Base>http://www.goodmedical.org/links/record/</Base> <Rule>&lo.pii;.php<Rule> Resulting URL: http://www.goodmedical.org/links/record/12345678/2713.php |
File Evaluation
After your application for inclusion in LinkOut has been accepted, prepare an identity file and a sample resource file. Resource files should contain links to at least five PubMed records.
Validate the files using the LinkOut http://www.ncbi.nlm.nih.gov/projects/linkout/doc/validate.shtml. Email the files to linkout/at/ncbi.nlm.nih.gov.
Your files will be evaluated by the LinkOut team, and you will be contacted regarding any corrections. The evaluation process will continue until your files are substantially error free.
Account Assignment
When the submitted files are substantially error free, you will be assigned a ProviderId (PrId) and an approved name abbreviation (NameAbbr), and you will be given a password for an NCBI FTP account.
Please note that each provider will be given only one FTP account at NCBI. A single provider may submit links on behalf of multiple publishers; different icons may be used in PubMed to establish the identity for each journal.
File Transfer
When you receive your account information, validate the files using the LinkOut http://www.ncbi.nlm.nih.gov/projects/linkout/doc/validate.shtml and transfer all files via FTP to the host FTP-private.ncbi.nlm.nih.gov. Place the files in the “holdings” directory of your account. No subdirectories may be created in the holdings directory.
When files have been submitted, inform the LinkOut team at linkout/at/ncbi.nlm.nih.gov. Your files will be given a final evaluation before being placed in the production queue. From this point on, files will be processed automatically every day.
Links should appear in PubMed within 2 days of file submission. For instructions on viewing your links, see Using LinkOut. If 2 days have passed and you do not see your links in PubMed, please write to linkout/at/ncbi.nlm.nih.gov.
File Maintenance
Provider Responsibilities
Link providers are responsible for:
maintaining their LinkOut files
transferring any additions, changes, or deletions of their links to NCBI
updating files and informing NCBI when access rights are changed
correcting broken or incorrect links in a timely manner
Providers may transfer new versions of current files or add new resource files at any time. It is the responsibility of the provider to keep files current and valid. Links in PubMed are regenerated every day based on the resource files in each provider’s directory; therefore, providers must delete obsolete files from their holdings directory.
Additional provider responsibilities are described in LinkOut Policies: Provider Responsibilities.
Confirmation and Error Messages
Upon processing an updated file, NCBI will send an acknowledgement to the designated LinkOut contact. If you prefer not to receive this acknowledgement, please notify the LinkOut Team at linkout@ncbi.nlm.nih.gov.
If files cannot be processed because of errors, a message with the subject line “LinkOut files uploaded to NCBI - Critical ERRORS!” will be sent to the LinkOut contact. The files should be corrected and resubmitted. If you have any questions about the errors, contact LinkOut at linkout/at/ncbi.nlm.nih.gov.
Provider Statistics
LinkOut collects statistics on the number of clicks on each publisher’s icons in PubMed’s Abstract display, and clicks on the publisher’s links in the LinkOut list of resources.
Statistics can be emailed to the LinkOut contact monthly. If you would like to receive statistics, please notify the LinkOut Team at linkout/at/ncbi.nlm.nih.gov
Statistics send via email include the yearly and monthly totals for clicks on a provider’s links, which are sorted by journal (a CSV file with the same information is provided as an attachment as well).
Statistics may change for the first 2 weeks that they are available. After 2 weeks, statistics will be stable.
A sample statistics report is shown below:

Submit Links on Behalf of Libraries
Section Contents
Introduction
Full-text providers and other library vendors may submit resource file(s) (library holdings information) on behalf of libraries. This is generally done by aggregators who submit links to LinkOut.
Vendors that supply OpenURL-based services to libraries can help libraries generate holdings information so libraries can link from PubMed citations to the service. This is usually done by including an export function that allows libraries to generate the necessary LinkOut files, although vendors may create files on behalf of the library.
For more information about supplying holdings information to create links to an OpenURL-based service, see Managing Library Holdings Using a Link Resolver.
Before Submitting Links
Before a provider can submit links on behalf of libraries, the provider must send a message to linkout/at/ncbi.nlm.nih.gov expressing their interest in submitting library holdings information. This message should include the following information:
the provider’s LinkOut account name (if applicable)
the name, email address, and telephone number of a contact person at your organization
A member of the LinkOut team will respond to contact person within 1 week.
Submitting Links
After receiving approval to submit library holdings information, please take the following steps for each library:
- 1.
The library must participate in LinkOut. If the library does not participate in LinkOut, they should register for an account. A library cannot ask a third party to register for LinkOut.
- 2.
Libraries must send a message to lib-linkout@ncbi.nlm.nih.gov giving permission for the provider to submit holdings on their behalf. If a library is registering for the first time, they may include this permission in the registration email. Please use the following format for the authorization message:
Subject: [provider name] will send LinkOut files for GoodLibrary
I authorize [provider] to send LinkOut files on behalf of GoodLibrary. We understand that the holdings information in this file will not appear in the submission utility and that we are responsible for keeping the holdings information current. I have informed all library staff about this change.
My contact information is: janesmith/at/goodlib.edu
Phone: 123-456-7890- 3.
The library will receive account information from LinkOut within one week. The library then sends their LinkOut User Name and PrId to the provider.
- 4.
The provider generates a resource file(s), described below, for the library, and submits the file(s) to the “users” directory of the provider’s FTP account.
- 5.
The library signs in to the Library Submission Utility and supplies a library icon. If the library does not provide an icon in the Submission Utility, LinkOut’s default library icon will display. Icons supplied in the resource file submitted by a provider will not be displayed. For more information about library icons, see Provide Full Text and Print Icons in the Library Submission Utility chapter.
Resource files are either submitted as a one-time load or updated regularly. When resource files are submitted as a one-time load, the provider submits the resource file(s) for the library once. The library then maintains the holdings information using the Library Submission Utility.
When resource files are updated regularly, the provider maintains the library’s resource file, providing updated files on a regular basis. The holdings maintained by the provider do not appear in the Library Submission Utility. Users may choose to maintain other holdings information using the Library Submission Utility.
File Preparation
To submit links on behalf of a library, the provider must send a resource file(s) describing the resources (library holdings) to which the library has access. A resource file may contain resources from a single provider (i.e., the publisher or aggregator’s own resources) or resources available from multiple providers (i.e., services that manage librarys’ online holdings information may want to submit links to resources available to the library from a variety of publishers or aggregators).
For a journal to be included in the resource file, the full-text provider must submit links to NCBI for that journal AND the library must have a pre-existing access agreement with the full-text provider. See http://www.ncbi.nlm.nih.gov/projects/linkout/journals/jourlists.cgi?typeid=1&type=providers&operation=Show for a list of journals and associated full-text providers available for linking. In constructing the resource file, you may find the text versions of the http://www.ncbi.nlm.nih.gov/projects/linkout/journals/jourlists.cgi?typeid=1&type=journals&format=text&operation=Show (sorted by title) and the http://www.ncbi.nlm.nih.gov/projects/linkout/journals/jourlists.cgi?typeid=1&type=providers&format=text&operation=Show (journals sorted by provider) helpful.
The resource file must be named {library NameAbbr}-{provider abbreviation supplied by NCBI}-holdings.xml. For example, the resource file for the library with NameAbbr testlib, supplied by provider Good Publisher (provider abbreviation gp) would be named testlib-gp-holdings.xml.
A list of all LinkOut Libraries NameAbbr and Provider Id can be found here.
Resource File Format
For complete file specifications, see LinkOut Technical Information: Resource File or the LinkOut DTD.
The following is an example resource file for University Library, ProviderId 9999. The library has access to three online journals from the provider Good Publisher.
<?xml version="1.0"?>
<!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut 1.0//EN" "LinkOut.dtd"
[
<!ENTITY icon "http://www.universitylibrary.edu/images/linkout.gif">
]>
<LinkSet>
<Link>
<LinkId>1</LinkId>
<ProviderId>9999</ProviderId>
<IconUrl>&icon;</IconUrl>
<SubObjectSelector>
<Database>PubMed</Database>
<SubProvider>
<NameAbbr>GoodPublisher</NameAbbr>
<InclQuery>"J Cell Biol"[ta] AND 1996:2010[pd]</InclQuery>
<InclQuery>"J Teeth"[ta] AND 1995:1999[pd]</InclQuery>
<InclQuery>"J Feet"[ta] AND 1998:2010[pd]</InclQuery>
</SubProvider>
</SubObjectSelector>
<ObjectUrl>
<Rule>/entrez/utils/pmliblink.cgi?id=&lo.id;&lib=unilib</Rule>
<Attribute>Electronic Full-text</Attribute>
</ObjectUrl>
</Link>
</LinkSet>The Resource file submitted for libraries follows the same format as the Resource file described above. The only difference is that library holdings are described in the <SubProvider> element, rather than in <ObjectList>, and that the <ObjectUrl> contains a link to the LinkOut program, rather than to the provider’s site.
<IconUrl>: The Library’s Icon
In holdings files submitted on behalf of a library, the ENTITY icon must be used. The URL for the icon cannot be entered directly into the <IconUrl> element.
Icons submitted on behalf of a library will be overwritten by icons submitted via the Library Submission Utility.
<SubProvider>: Describing the Library’s Online Holdings
<SubProvider> contains one required sub-element, <NameAbbr>, and one optional sub-element, <InclQuery>.
<NameAbbr> contains the LinkOut User Name of the full-text provider. LinkOut User Names are available in the list of http://www.ncbi.nlm.nih.gov/projects/journals/active_providers.html.
<InclQuery> lists the journals to which the library subscribes from the provider in <NameAbbr>. Typically, <InclQuery> follows this format:
<InclQuery>”{Journal ISSN}” AND {start year}:{end year}[dp]</InclQuery>
There are two ways to describe a library’s online journal holdings:
1) The library subscribes to all of a full-text provider’s LinkOut journals:
Include only the valid NameAbbr for the provider in the <NameAbbr> element within <SubProvider>. In the example below, all of provider XYZ’s journals are included in the library’s holdings.
<SubProvider>
<NameAbbr>XYZ</NameAbbr>
</SubProvider>2) The library does not subscribe to all of a full-text provider’s LinkOut journals:
Use <InclQuery> within <SubProvider> to list the journals to which the library subscribes. In the example below, the journals "J Teeth" beginning in 1996 and the journal “J Feet” beginning in 2000 from provider XYZ are included in the library’s holdings. <InclQuery> can be repeated to include multiple journals.
<SubProvider>
<NameAbbr>XYZ</NameAbbr>
<InclQuery>"J Teeth"[ta] AND 1996:2010[pd]</InclQuery>
<InclQuery>"J Feet"[ta] AND 2000:2010[pd]</InclQuery>
</SubProvider><ObjectUrl>: Specifying the Link to Access Online Full Text
The <ObjectUrl> must contain the URL of LinkOut’s library linking program. The <ObjectUrl> element must always be:
<ObjectUrl>
<Rule>/entrez/utils/pmliblink.cgi?id=&lo.id;&lib=unilib</Rule>
</ObjectUrl>Replace unilib with the library’s LinkOut NameAbbr. A list of all LinkOut Libraries NameAbbr and Provider Id can be found here.
Library Resource File Examples
Example 1: This example shows a resource file containing library holdings from one provider. Most files submitted by providers will follow this format.
The following resource file describes the LinkOut holdings for University Library, ProviderId 9999. University Library subscribes to four journals from the provider Good Publisher.
<?xml version="1.0"?>
<!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut 1.0//EN" "LinkOut.dtd"
[
<!ENTITY icon " http://www.universitylibrary.edu/images/linkout.gif">
]>
<LinkSet>
<Link>
<LinkId>1</LinkId>
<ProviderId>9999</ProviderId>
<IconUrl>&icon;</IconUrl>
<SubObjectSelector>
<Database>PubMed</Database>
<SubProvider>
<NameAbbr>GoodPublisher</NameAbbr>
<InclQuery>"J Cell Biol"[ta] AND 2004:2010[dp]</InclQuery>
<InclQuery>"J Teeth"[ta] AND 1999:2010[dp]</InclQuery>
<InclQuery>"J Feet"[ta] AND 2000:2004[dp]</InclQuery>
<InclQuery>"J Mol Biol"[ta] AND 1996:2010[dp]</InclQuery>
</SubProvider>
</SubObjectSelector>
<ObjectUrl>
<Rule>/entrez/utils/pmliblink.cgi?id=&lo.id;&lib=unilib</Rule>
<Attribute>Electronic Full-text</Attribute>
</ObjectUrl>
</Link>
</LinkSet>Example 2: This example shows a resource file containing library holdings information from multiple providers. This type of file would be submitted by a service that had access to all of a library’s holdings information, including full-text providers, or by a library that has chosen to submit library holdings as a file, rather than managing holdings through the Library Submission Utility or by using a local service.
The following resource file describes the LinkOut holdings for University Library, ProviderId 9999. University Library subscribes to:
all LinkOut journals offered by the provider "Springer"
two LinkOut journals, "J Cell Biol" and "J Biol Chem" (ISSN:0021-9258) offered by the provider "HighWire"
all LinkOut journals except the journal "Cancer" offered by the provider "Wiley"
one LinkOut journal "J Mol Biol" offered by the provider "AcadPres". “AcadPres” offers links to this journal from 1990 to the present, but University Library’s online access starts in 1996.
<?xml version="1.0"?>
<!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut 1.0//EN" "LinkOut.dtd"
[
<!ENTITY icon "http://www.universitylibrary.edu/images/linkout.gif">
]>
<LinkSet>
<Link>
<LinkId>1</LinkId>
<ProviderId>9999</ProviderId>
<IconUrl>&icon;</IconUrl>
<SubObjectSelector>
<Database>Medline</Database>
<SubProvider>
<NameAbbr>Springer</NameAbbr>
</SubProvider>
</SubObjectSelector>
<ObjectUrl>
<Rule>
/entrez/utils/pmliblink.cgi?id=&lo.id;&lib=unilib
</Rule>
<Attribute>Electronic Full-text</Attribute>
</ObjectUrl>
</Link>
<Link>
<LinkId>2</LinkId>
<ProviderId>9999</ProviderId>
<IconUrl>&icon;</IconUrl>
<SubObjectSelector>
<Database>Medline</Database>
<SubProvider>
<NameAbbr>HighWire</NameAbbr>
<InclQuery>"J Cell Biol"[ta]</InclQuery>
<InclQuery>"0021-9258"[ta]</InclQuery>
</SubProvider>
</SubObjectSelector>
<ObjectUrl>
<Rule>
/entrez/utils/pmliblink.cgi?id=&lo.id;&lib=unilib
</Rule>
<Attribute>Electronic Full-text</Attribute>
</ObjectUrl>
</Link>
<Link>
<LinkId>3</LinkId>
<ProviderId>9999</ProviderId>
<IconUrl>&icon;</IconUrl>
<SubObjectSelector>
<Database>Medline</Database>
<SubProvider>
<NameAbbr>Wiley</NameAbbr>
<ExclQuery>"Cancer"[ta]</ExclQuery>
</SubProvider>
</SubObjectSelector>
<ObjectUrl>
<Rule>
/entrez/utils/pmliblink.cgi?id=&lo.id;&lib=unilib
</Rule>
<Attribute>Electronic Full-text</Attribute>
</ObjectUrl>
</Link>
<Link>
<LinkId>4</LinkId>
<ProviderId>9999</ProviderId>
<IconUrl>&icon;</IconUrl>
<SubObjectSelector>
<Database>Medline</Database>
<SubProvider>
<NameAbbr>AcadPres</NameAbbr>
<InclQuery>"J Mol Biol"[ta] AND 1996:2010[dp]</InclQuery>
</SubProvider>
</SubObjectSelector>
<ObjectUrl>
<Rule>
/entrez/utils/pmliblink.cgi?id=&lo.id;&lib=unilib
</Rule>
<Attribute>Electronic Full-text</Attribute>
</ObjectUrl>
</Link>
</LinkSet>File Transfer
Use the http://www.ncbi.nlm.nih.gov/projects/linkout/doc/validate.shtml utility to validate LinkOut files against the LinkOut DTD before submitting them to NCBI.
Transfer the resource file(s) via FTP to the host FTP-private.ncbi.nlm.nih.gov. Place the files in the “users” directory of your FTP account. No subdirectories should be created in the “users” directory.
Additional Information about Linking
Section Contents
Deleted PMIDs
From time to time, records are deleted from the PubMed database. Please see the publisher journal submission FAQ for details.
If you provide links using PMIDs in LinkOut files and the PMIDs are deleted, your links will disappear from PubMed. If you use these PMIDs to link to PubMed from your system, these links will be broken.
A list of all PMIDs that have been deleted since October 2004 is available at:
ftp://ftp.ncbi.nlm.nih.gov/pubmed/deleted_pmids.txt
This plain text file is updated every night at 10:00 p.m. Eastern Time. Please consult this list frequently to synchronize your linking system with PubMed to ensure proper functioning of your links.
Adding/Changing DOI/PII in PubMed Records (for Linking Purposes Only)
NLM and NCBI do not input DOI or PII in PubMed records; this information must be submitted by the provider that is submitting electronic citation data for the journal. For citations that are already in PubMed, DOI/PII information can be added or updated by submitting the new or updated information to NCBI. DOI/PII can only be changed by the provider that is currently submitting electronic citation data for the journal. Similarly, only the current provider of a journal title would be able to submit DOI/PII information for backfiles.
There are two ways to submit updated DOI/PII for PubMed records. You can submit a text file containing PMID and DOI/PII pairs, or you can send citation data for back issues with DOI/PII included.
To submit a text file:
Locate the PMIDs of the citations for which DOI/PII will be assigned or updated. LinkOut can assist in finding PMIDs.
Create a text file of PMID</tab>DOI or PMID</tab>PII pairs. Each pair should appear on one line of the file.
DOI files must have the extension .doi.
PII files must have the extension .pii.
Each file may contain up to 10,000 pairs. You may submit multiple files.
Alternatively, send citations for back issues with DOI/PII included.
This cannot be done for pubstatusaheadofprint citations.
Send one journal issue or volume per file.
Citations will be matched to PubMed records. Citations that cannot be matched with be rejected.
Place files in the pid directory of your FTP account. If you don’t have a pid directory, write to linkout/at/ncbi.nlm.nih.gov to request a pid directory in your FTP account. Text files will be processed in about 24 hours, citation files will be processed in about 48 hours.
Transferring Journals Between Publishers
When a journal is transferred to a new publisher, LinkOut needs to be informed so that the default icon can be changed (more about the default icon), and to ensure that links continue to function properly. To do this, please send the following information to linkout/at/ncbi.nlm.nih.gov.
Is the journal being added or deleted?
Journal title and ISSN.
Publisher name and LinkOut account name.
If the journal is being added to your collection, please also include the following:
Name of previous publisher
When will change take place?
When will you start submitting citation data?
When will you submit links for the journal? (This should be done after citation files are submitted for the first time.)
Will back content of the journal be hosted on your site?
Will libraries that subscribe to the journal have access to all content available for the journal at your site?
Should your icons appear on back content in PubMed? (This can be done only if the previous publisher’s links are not working, or if the copyright holder approves the change.)
If the journal is being removed from your collection, please also include the following:
Is the journal being transferred to a new publisher? Which?
When will the change take place?
When will you stop submitting links for the journal or update your LinkOut files to stop links from being generated for new content?
Will back content continue to be hosted at your site?
Should your icons appear on back content in PubMed? (If links are not working, they will be removed. Icon can continue to appear on back content if copyright holder approves it.)
Will the libraries that subscribed to the journal continue to have access to back content at your site?
Both old and new provider links should be working during the transition
- PDF version of this page (149K)
-
Information for Full-Text Providers - LinkOut Help
Information for Full-Text Providers - LinkOut HelpBookshelf
-
Management of Eating Disorders
Management of Eating DisordersBookshelf
-
Information for Libraries - LinkOut Help
Information for Libraries - LinkOut HelpBookshelf
-
Management of Menopause-Related Symptoms
Management of Menopause-Related SymptomsBookshelf
-
Effects of Omega-3 Fatty Acids on Cognitive Function with Aging, Dementia, and N...
Effects of Omega-3 Fatty Acids on Cognitive Function with Aging, Dementia, and Neurological DiseasesBookshelf
Your browsing activity is empty.
Activity recording is turned off.
See more...