OSTI'sAnnouncement Notice 241.1

Web Service for STI

Version 6.4, November 2023

Contents

1.0 About

1.1 Announcement Notice 241.1

1.2 OSTI's AN 241.1 Web Service

2.0 Using the AN 241.1 Web Service

2.1 Credentials and Authentication

2.2 POST (Create or Update) and GET (Retrieve)

2.3 Response and Notifications

2.4 Transmitting Full-Text Products to OSTI

3.0 AN 241.1 Web Service Metadata

3.1 AN 241.1 Required Fields

3.2 Required Fields (Cont): Access Limitation(s) Attributes and Values

3.3 AN 241.1 Optional Fields

4.0 Appendices

A.1 Related Identifiers

A.2 Examples of XML 241.1 Metadata Records

New in this revision:

1.0   About

1.1 Announcement Notice 241.1

Announcement Notice (AN) 241.1 provides the Office of Scientific and Technical Information (OSTI) with the information needed to identify, process, announce and disseminate the results of work funded by the Department of Energy (DOE) or performed in DOE facilities (see DOE Order 241.1B (link is external)).   When submitted, the AN 241.1 set of metadata creates a citation/record that is processed by E-Link and then transferred into the appropriate databases for access (see search tools Search Tools).

DOE sites can manually submit AN 241.1 metadata a single record at a time through a web interface on E-Link (www.osti.gov/elink) (link is external).  The AN 241.1 Web Service provides an additional option for submitting DOE's scientific and technical (STI) products to OSTI for dissemination.  The STI product will be a full text document, such as a technical report, thesis or dissertation, book, journal literature, conference literature, or a program document.  It could also be a multimedia file.

AN 241.1 metadata and products submitted to OSTI, whether through a manual process or an automated process, are subject to the same requirements.  A designated Releasing Official must ensure that each record has been reviewed for any content that would make it appropriate for release to the public.  The Releasing Official is also responsible to ensure that full text documents posted on site or transmitted to OSTI do not contain Personally Identifiable Information (PII) (see https://www.osti.gov/elink/faq.jsp#PII (link is external)).  Use of the AN 241.1 Web Service does not remove these responsibilities from the Releasing Official.

STI from DOE's research and development activities is disseminated through OSTI's databases such as OSTI.GOV, through multiagency databases such as Science.gov (link is external), through global databases such as WorldWideScience.org (link is external), and through arrangements with major Internet search engines such as Google. 

1.2 OSTI's AN 241.1 Web Service

OSTI's AN 241.1 Web Service allows a submitting site to send AN 241.1 information in a completely automated manner.  Metadata is generated at the submitting site per the programming set-up by the site's IT developers and POSTed as an output file to OSTI.  The schedule for the POST operation may be multiple times daily, once daily, once weekly, etc.

Records with unlimited access status and those with limited access can both be transmitted through the secure AN 241.1 Web Service. DOE organizations may establish a URL link to the unclassified, unlimited STI products on their websites and send the URL in the metadata or they may transmit the full text product to OSTI. All limited access (Controlled Unclassified Information or CUI) full text

are required to be transmitted to OSTI and cannot be posted on the sites public web.

The AN 241.1 Web Service provides the ability to submit new Announcement records, edit/update records, or retrieve a record for review. A user manipulates a record by performing HTTP operations on the web service URL and providing XML metadata. The POST command/request allows a submitter to create or edit/update AN 241.1 records. The GET command/request allows a submitter to retrieve a record for review.

Submitters must coordinate with OSTI and submit records to a test environment before POSTing their first XML file for dissemination. The URL for Test E-Link is https://www.osti.gov/elinktest/2411api. OSTIs production web service for announcing STI is available at https://www.osti.gov/elink/2411api.

2.0 Using the AN 241.1 Web Service

2.1 Credentials and Authentication

AN 241.1 transactions require an active E-Link user account. To request personal access to E-Link and obtain an active account, visit https://www.osti.gov/elink/register.jsp. To obtain an account for your client server to connect to OSTIs web service, contact E-Link Product Manager, Kim Buckner (bucknerk@osti.gov). Your web service account will be given a login name and password for Test E-Link. After testing is completed, you will be provided a login and password for production E-Link, as well as a separate password for your sites SFTP.

The AN 241.1 Web Service supports HTTP Basic authentication over SSL. With this method, the client connects to the HTTPS URL for either Test E-Link or, when testing is complete, for production E-Link. The POST and GET verb commands will pass along the standard Authentication HTTP header (base64 encoding).

2.2 POST (Create or Update) and GET (Retrieve) [Client to OSTI]

After successful authentication, the input body of the POST or GET request is read as an XML document, parsed, and loaded appropriately into E-Link. HTML status codes (200=OK, 401=Unauthorized, 500=System error, etc.) and an XML response, which includes certain metadata fields, are returned by OSTIs server to the client server to notify of either success in loading the record or failure.

The POST command/request is most often used to submit metadata for a new record that is being provided to OSTI for the first time, but it can also be used

to edit or update an existing record that has previously been submitted. Submitters must tell the system which of the two activities they intend for a record. The OSTI ID is key to this. How and why is explained below:

When POSTING to an existing record in order to update it, the OSTI ID must be included in the XML record. The updated information will then overwrite the previously submitted information. If the OSTI ID is not included when trying to POST to an existing record, the Web Service believes you are wanting to create rather than update. It will create a duplicate record, but with a new, different OSTI ID. This situation always requires correction by logging into E-Link manually and manually deleting the duplicate record.

Metadata can be retrieved for any record previously submitted by your organization by using a GET request and supplying the OSTI ID as a parameter in the request. Authentication is required and is handled in the same fashion as a Create/Update command. The requested OSTI ID returns that specific XML record. A GET operation will not update a record, however.

2.3 Response and Notifications [OSTI to Client]

OSTIs server makes an immediate response when the client-side server sends a POST or a GET request. The primary goal of the response is two-fold: to let the client server know if it connected successfully and to provide a status message about the record that was POSTed or retrieved. The status says SUCCESS if the record correctly transmitted and the metadata loaded into E-Link. The status says FAILURE if the record was unable to load for any reason. The FAILURE response includes a message indicating the error or problem that kept the record from loading. Errors leading to a FAILURE response occur when a required metadata field is missing, when a site URL cannot be validated by the automated validation process, when a value is too long for the field it must load into, etc.

Note that the successful record returns its newly assigned OSTI ID. The response for the failed record will not have an OSTI ID since IDs cannot be assigned to records that never actually make it into E-Link

E-Link also generates an email containing the SUCCESS or FAILURE information about each submitted record. The site will be asked to provide to OSTI the names of the people to whom these automated emails will be sent.

It is the submitting sites responsibility to review the results of the web service transactions and to correct, then resubmit those records that initially failed.

2.4 Transmitting Full-Text Products to OSTI

A secure FTP directory is set-up at OSTI for each site utilizing the AN 241.1

Web Service. A site cannot access any other sites SFTP directoryonly the one assigned specifically to it. The process for providing both a metadata record and its corresponding full text product is as follows:

1. Site submits an XML metadata record to OSTIs E-Link system via the AN 241.1 Web Service.
2. The AN 241.1 Web Service notifies the submitting site that the XML record loaded successfully into E-Link and includes the newly assigned OSTI ID in the notification message. Notification goes out via server-to-server messaging and via an email to a sites designated distribution list.
3. A script written by the sites (client) software developers adds the new OSTI ID to the sites (client) database (records publishing system, review and approval system, etc.).
4. The script also reaches out to rename the corresponding full-text product, changing its file name from whatever it was originally to the new OSTI ID number. Only the number is used as the name, not any part of the OSTI ID text that sometimes prefixes the number. Example: a file named DOELAB-27834.pdf would be renamed 114073.pdf (if OSTI ID 114073 had been assigned to the corresponding metadata XML record).
5. Another automated command in the submitting sites (client) programming then transmits the file named 114073.pdf to the sites assigned SFTP directory.
6. The metadata record was submitted first and has been waiting in E- Link. It will not complete processing until E-Link recognizes that a document with the same OSTI ID is now present in the sites assigned SFTP directory.
7. If, on the first night after the XML records submittal, E-Link does not detect a matching full-text product, the record stays in its Submitted state in E-Link. It will stay that way, as many days as it takes, until the full text product arrives from the site.
8. When E-Link recognizes that a full text product has arrived in the sites (client) directory and that the product has an OSTI ID matching a metadata record from the same site code, a siphon process takes place. The process attaches the product to the record.

After the marriage, the record and its full text go through a transfer process that makes them available in the appropriate database. CUI records and documents are transferred to Science Research Connection (SRC) (see www.osti.gov/src), a password-protected system available

8. only to DOE and DOE contractors. Unlimited records will be sent to OSTI.gov, Pages, or other databases.

3.0 AN 241.1 Web Service Metadata

3.1 AN 241.1 Required Fields

The following is a list of the required fields for the AN 241.1 Web Service. These fields are also designated by an asterisk (*). Records submitted without required fields will fail to load into E-Link for processing. The other fields available for your use are optional, though some, such as the Abstract/Description, are highly encouraged.

NOTE: The OSTI ID is a required field for all POST requests where the intent is to edit or update records. The GET request must also include the OSTI ID and will allow retrieval of a record previously submitted by your site.

REQUIRED

	Field Name	XML Tag Name	Additional Information
1	OSTI ID+	<osti_id></osti_id>	The OSTI ID is required in all requests intended to edit or update existing records. When POSTing new records to OSTI, no <osti_id> tag is needed in the XML. E-Link automatically assigns an OSTI ID to each new record successfully submitted.
2	Record Status*	<new/> <revdata/> <revprod/>	These tags are required to inform the system of the status of the record being submitted. For new records, only the <new/> is needed. For revised metadata <revdata/> or revised/replaced full text products (revprod/), the OSTI ID must be included as an attribute. See format below. Record Status Attributes are needed for revdata tag and revprod tag. <revdata osti_id='1053369'/> <revprod osti_id='1053370'/> (Note the single quote marks around the attribute value)

			Preferred format is MP4. (See https://www.osti.gov/stip/submit/product-types/audiovisual for more on formats.) In Format Other, <format_other></format_other>, please provide the length of the video as run time. Example:  <format_other>Run time: 00:50:25</format_other>
16	Released by Name*	<released_by></released_by>	The name of the designated releasing official responsible for approval of distribution/access limitation and for ensuring no PPI is contained in the metadata or the full text. OSTI admin field; does not display in output databases.
17	Released Date*	<released_date> </released_date>	Date that the record was released to OSTI by the releasing official.
18	Released by Email*     Released by Phone*	<released_by_email> </released_by_email>      <released_by_phone> </released_by_phone>	Both fields must be included in the metadata.  This is contact information only and will not display in the output databases.

3.2 Required Fields (Cont):  Access Limitation(s) Attributes and Values

Unclassified, unlimited information is available to the U.S and non-U.S. public, but certain types of information have restricted access whose publication or distribution is restricted by various laws, federal codes, executive orders, international agreements, etc.  Records describing STI products with access limitations are not released to OSTI's publicly available databases.  They are available to DOE and DOE contractors in Science Research Connection (SRC) (see www.osti.gov/src) with different levels of access based on the product and the requestor.

Records with access limitation codes other than Unlimited (<unl/> may require additional, different information formatted as "attributes" rather than "elements."  The following table provides this formatting guidance.  For more guidance on the actual restrictions, markings, and handling of STI with access limitations,

see the STIP home page athttp://www.osti.gov/stip/or contact OSTI staff atstip@osti.gov.

Access Limitation Codes	What the Code Means	Tags, examples, other information
<unl/>	Unlimited Announcement. Select this option if the STI Product should have unlimited and unrestricted distribution to the U.S. and non-U.S. public.	Example: <access_limitation> <unl/> </access_limitation>
	Required/Needed Attributes of <access_limitation></access_limitation> if value is <opn/>
	OpenNet Accession Number*	<opennet_accession_no>
	OpenNet Document Location	<opennet_doc_location>
	Applicable field office acronym	<opennet_fieldoffice_acronym>	Use the appropriate acronym provided in OpenNet DeClassified Information Database Data Input Specifications,' revised April 3, 1998.

		<access_limitation_other> other access lim </access_limitation_other>
<ouoprot/>	Protected Data CRADA or Other. Information produced in the performance of a CRADA that is marked as being Protected CRADA Information by a party to the agreement and that would have been proprietary information had it been obtained from a non- Federal entity. It may be protected for a period up to 5 years from the date it was produced, except as expressly provided for in the CRADA.	Example: <access_limitation> <ouoprot protected_data_crada='Y' access_limitation_rel_date=01/21/2011/> </access_limitation>
	Required Attributes of <access_limitation></access_limitation> if access limitation is <ouoprot/>
	Protected Data CRADA	protected_data_crada	Allowed Values: Y or N
	Protected Data Other	protected_data_desc	Required if Access Limitation equals <ouoprot/> and protected_data_crada='N'
	Access Limitation Release Data (mm/dd/yyyy0	access_limitation_release_date
<ouopat/>	Patent Pending. Federal agencies are authorized to withhold from public disclosure any invention in which the Government owns or may own a right, title, or interest, for a reasonable length of time so that a patent application can be filed.	<access_limitation> <ouopat/> </access_limitation>
<ouolrd/>	Limited Rights Data (Proprietary/Trade Secret) Information that embodies trade secrets or is commercial or financial and confidential or privileged, to the extent that such data pertain to items, components, or processes developed at private (not government) expense, including minor modifications.	<access_limitation> < ouolrd /> </access_limitation>
<ouopdouo/>	Program-Determined Official Use Only This type of OUO is based on approved guidance as reflected in DOE Order 471.3, Identifying and Protecting Official Use Only Information.	Examples: <access_limitation> <ouopdouo exemption_number='2'/> </access_limitation>

		<access_limitation> <ouopdouo exemption_number='7'/></access_limitation> <access_limitation_other>other access lim</access_limitation_other>
	Required/Needed Attributes of <access_limitation></access_limitation> if Access Limitation is <ouopdouo/> Access Limitation Release Date (mm/dd/yyy) -- access_limitation_rel_date pdouo Exemption Number Exemption_number -- ouopdouo exemption_number
<nnpi/>	Naval Nuclear Propulsion Information. Unclassified information related to any aspect of propulsion plants of naval nuclear-powered ships and prototypes, including the associated shipboard and shore-based nuclear support facilities. See Chief of Naval Operations Instruction N9210.3, Safeguarding of Naval Nuclear Propulsion Information.	Example: <access_limitation> <nnpi/> </access_limitation>

3.3 AN 241.1 Optional Fields

The following is a list of optional fields for the AN 241.1 STI Announcement Web Service. Inclusion of some of these fields, such as the Abstract/Description, is highly encouraged.

OPTIONAL

	Field	XML Tag	Comments
1	Author(s) Email Address(es)	<author_emails> </author_emails>	Admin info only; it will not be displayed in public databases. NOTE Use this field only when NOT using the <authors> block of fields.
2	Related Document Information	<related_doc_info> </related_doc_info>	Provide additional useful information related to the STI Product that should be

load and can help identify duplication of records.

0. Appendices
   1. Related Identifiers (definitions and usage notes)
      
      Note: Much of this table is copied directly from the DataCite 4.0 schema, Appendix, Table 9: Description of relation type. Some of the example values in the XML were then created from fictitious sources by OSTI staff. Do not expect those particular URLs or DOIs to work as active links.

Controlled Vocabulary Terms
IsCitedBy	Indicates that B includes A in a citation <related_identifier>10.4232/10.ASEAS-5.2-1</related_identifier> <related_identifier_type>DOI</related_identifier_type> <relation_type>IsCitedBy</relation_type>
Cites	Indicates that A includes B in a citation <related_identifier>10.2272/79348</related_identifier> <related_identifier_type>DOI</related_identifier_type> <relation_type>Cites</relation_type>
IsSupplementTo	Indicates that A is a supplement to B <related_identifier>10.5789/10.test-5.2-1</related_identifier> <related_identifier_type>DOI</related_identifier_type> <relation_type>IsSupplementTo</relation_type>
IsSupplementedBy	Indicates that B is a supplement to A <related_identifier> http://patents.gov/169113</related_identifier> <related_identifier_type>URL</related_identifier_type> <relation_type>IsSupplementedBy</relation_type>
IsContinuedBy	Indicates A is continued by the work B <related_identifier>http://restofthestory.com.I_love_science</related_identifier> <related_identifier_type>URL</related_identifier_type> <relation_type>IsContinuedBy</relation_type>
Continues	Indicates A is a continuation of work B <related_identifier>http://endthisstory.org/sciencehalts/</related_identifier> <related_identifier_type>URL</related_identifier_type> <relation_type>Continues</relation_type>

IsReviewedBy	Indicates that A is reviewed by B <related_identifier>10.5256/F1000RESEARCH.4288.R4745</related_identifier> <related_identifier_type>DOI</related_identifier_type> <relation_type>IsReviewedBy</relation_type>
Reviews	Indicates that A is a review of B <related_identifier>10.12688/f1000research.4001.12</related_identifier> <related_identifier_type>DOI</related_identifier_type> <relation_type>Reviews</relation_type>
IsDerivedFrom	Indicates B is a source upon which A is based <related_identifier>10.6078/M7DZ067C </related_identifier> <related_identifier_type>DOI</related_identifier_type> <relation_type>IsDerivedFrom</relation_type> IsDerivedFrom should be used for a resource that is a derivative of an original resource.
IsSourceOf	Indicates A is a source upon which B is based <related_identifier> http://opencontext.org/projects/81204AF8-127C-4686-E9B0- 1202C3A47959 </related_identifier> <related_identifier_type>URL</related_identifier_type> <relation_type>IsSourceOf</relation_type> IsSourceOf is the original resource from which a derivative resource was created.
IsObsoletedBy	Indicates A is obsoleted by B <related_identifier>10.6078/M7DZ067C </related_identifier> <related_identifier_type>DOI</related_identifier_type> <relation_type>IsObsoltetedBy</relation_type>
Obsoletes	Indicates A obsoletes B <related_identifier>10.12688/f1000research.4001.12</related_identifier> <related_identifier_type>DOI</related_identifier_type> <relation_type>Obsoletes</relation_type>

A.2 Examples of XML 241.1 Metadata Records

Here is an example of an XML file with two AN 241.1 records in it. The first is an announcement of a technical report as it would come to OSTIs 241.1 web service. Following it is an example of a 241.1 announcement of a journal article with full text noted as an accepted manuscript (AM) as required by the DOE Public Access Plan.

Both records use the preferred block format for author names and related information.

241.1 announcement of a technical report as it would come to OSTIs AN 241.1 web service

<?xml version="1.0" encoding="UTF-8"?>

<records>

<record>

<new/>

<site_input_code>MLNL</site_input_code>

<product_type>TR</product_type>

<title>This is a test record</title>

<authors>

<authors_detail>

<first_name>Thomas</first_name>

<middle_name>R.</middle_name>

<last_name>Testman</last_name>

<affiliation>Major Laboratory Name</affiliation>

<private_email></private_email>

<orcid_id>0000-0002-3765-8932</orcid_id>

</authors_detail>

</authors>

<report_nos>PNL-17991</report_nos><doe_contract_nos>AC00-76RL00000</doe_contract_nos>

<other_identifying_nos>248607</other_identifying_nos>

<originating_research_org>Pacific Northwest National Laboratory (PNNL), Richland, WA (United States)</originating_research_org>

<publication_date>10/31/2008</publication_date>

<language>English</language>
<country_publication_code>US</country_publication_code>

<sponsor_org>USDOE Office of Environmental Management (EM), Office of Soil/Ground Water Remediation (EM-12)</sponsor_org>

<keywords>Emergent Sandbar Habitat; Missouri River; Least Tern; Piping Plover; adaptive management; EIS</keywords>

<description>The goal of the Emergent Sandbar Habitat (ESH) program is to provide sufficient habitat throughout the Missouri River system to allow self-sustaining populations of Interior Least Tern (Sternula antillarum) and Piping Plover (Charadrius melodus). The adaptive management (AM) strategy described herein establishes the process, understanding and tools necessary to adaptively manage the ESH element of

the response to the 2003 Biological Opinion for the next 10-15 years. The AM strategy is intended to assist the Corps of Engineers, U.S. Fish and Wildlife Service and their stakeholders in making decisions regarding how to best improve populations of tern and plover through habitat creation. This AM strategy is guided by the framework and principles described in Adaptive Management, the U.S. Department of the Interior Technical Guide.</description>
<medium_code>ED</medium_code>
<access_limitation>
<unl/>
</access_limitation>
<site_url>http://www.test.gov/test/1234.pdf</site_url>
<released_by>Test Official</released_by>
<released_date>02/05/2009</released_date>
<released_by_email>tester@osti.gov</released_by_email>
<released_by_phone>(865)576-9999</released_by_phone>
</record></records>

241.1 announcement of a journal article with full text noted as an accepted manuscript (AM) as required by the DOE Public Access Plan)

<?xml version="1.0"?> <records>
<record>
<new />
<site_input_code>MLNL</site_input_code>
<product_type>JA</product_type>
<journal_type>AM</journal_type>
<title>Finding the Higgs Boson</title>
<authors>
<authors_detail><first_name>John</first_name>
<middle_name>James</middle_name> <last_name>Ruckus</last_name>
<affiliation>Major Lab National Laboratory</affiliation> <private_email>ruckusjj@mllb.gov</private_email>
<orcid_id>0000-0002-4398-2983</orcid_id> </authors_detail>
<authors_detail> <first_name>Mary</first_name> <middle_name>Lynn</middle_name>
<last_name>King</last_name>

the response to the 2003 Biological Opinion for the next 10-15 years. The AM strategy is intended to assist the Corps of Engineers, U.S. Fish and Wildlife Service and their stakeholders in making decisions regarding how to best improve populations of tern and plover through habitat creation. This AM strategy is guided by the framework and principles described in Adaptive Management, the U.S. Department of the Interior Technical Guide.</description>
<medium_code>ED</medium_code>
<access_limitation>
<unl/>
</access_limitation>
<site_url>http://www.test.gov/test/1234.pdf</site_url>
<released_by>Test Official</released_by>
<released_date>02/05/2009</released_date>
<released_by_email>tester@osti.gov</released_by_email>
<released_by_phone>(865)576-9999</released_by_phone>
</record></records>

241.1 announcement of a journal article with full text noted as an accepted manuscript (AM) as required by the DOE Public Access Plan)

<?xml version="1.0"?> <records>
<record>
<new />
<site_input_code>MLNL</site_input_code>
<product_type>JA</product_type>
<journal_type>AM</journal_type>
<title>Finding the Higgs Boson</title>
<authors>
<authors_detail><first_name>John</first_name>
<middle_name>James</middle_name> <last_name>Ruckus</last_name>
<affiliation>Major Lab National Laboratory</affiliation> <private_email>ruckusjj@mllb.gov</private_email>
<orcid_id>0000-0002-4398-2983</orcid_id> </authors_detail>
<authors_detail> <first_name>Mary</first_name> <middle_name>Lynn</middle_name>
<last_name>King</last_name>