Changes from E-Link 1 to 2

Both E-Link 1 APIs rely on XML tags, often with varying and inconsistent names between types, e.g. <report_nos>, <doe_contract_nos> alongside <work_proposal_number>, sometimes <other_identifying_nos> or <other_identifying_numbers> and the like.

Author/creator information is also grouped awkwardly, using <authors> and <authors_detail> or <author> tags inconsistently. 241.1 XML submissions did not support the concept of contributors at all; 241.6 submissions grouped these under <contributors> in similar fashion to authors information. Similarly, organizations may be referenced in a number of ways; with <sponsor_org>, <originating_research_org>, and <contributing_organizations> in various locations in the XML.

E-Link 2 API consolidates various persons referred to in metadata under a common "persons" group, with "type" values indicating the role or responsibility, with consistent element names for all types. Similarly, organizations or institutions are grouped into "organizations", again with a "type" indicating their role. Contributors may be both "persons" or "organizations", organized into their respective groups, and designated consistently. Various identifiers, ranging from DOE contract numbers, award DOIs, report or product numbers, and other identifying numbers, are also grouped together as "identifiers", again with "type" for each (see the Mapping XML Fields and New Validation Rules for identifying the new names for all these fields). Should new roles or types be introduced in the future, rather than instigating a new tag element, these may simply be referred to as what they are, assigned a "type", and grouped accordingly.

It should be noted that many XML tags are retained mainly unchanged in JSON, such as "description", "title", and the like. The online API documentation details these under the POST operation to submit metadata to OSTI.

Structurally, the E-Link 2 API is more conformant to the REST API standards. Whereas the E-Link 1 API had separate POST endpoints for both new records and updates to existing ones, E-Link 2 API will utilize more standardized POST for new records and PUT for record updates. Additionally, effort has been made to improve and standardize HTTP response codes and status messages to facilitate and streamline user experiences. E-Link 2 also supports media (PDF or URL) document submission directly to the API, rather than through an FTP and siphon process, exposing more functionality for the lab systems to make complete record submissions through API.

E-Link REST 2 Migrator Service

Full Documentation

The XML Migration Service API is intended to provide a migration path from E-Link 1 XML-based API services known as "241.1 XML API" and "241.6 XML API" to continue submission of XML to this API, which submits each request to the E-Link 2 JSON API. This service will be temporarily supported while users adapt their systems and processes to the new E-Link API, but will be discontinued at some point.

XML Mapping and New Validation Rules

Submission Rules Page

As described above, E-Link 2 has changed a number of field names to be more consistent. Additionally, validation rules for E-Link 2 records have been expanded to include more fields. To facilitate understanding these changes, we have provided the Submission Rules page. Providing a product type and distribution limitation will display a mapping of the old XML names to the new JSON fields, as well as showing which fields are not allowed to be provided, those that are optional, and the required fields at each stage of the submission process.

E-Link 1 vs 2 Workflow Statuses

E-Link 1 Workflow Statuses:

  • SA - Saved
  • SR - Submitted to releasing official
  • SO - Submitted to OSTI (This legally satisfies STI requirement.)
  • REL - Fully Released (Can be shared with output products.)
  • X or NULL - Error condition.

E-Link 2 Workflow Statuses:

  • X - Error Status
  • SA - Saved
  • SR - Submitted to releasing official
  • SO - Submitted to OSTI awaiting validation
  • SV - Submitted to OSTI and validated
  • SF - Submitted to OSTI and failed validation
  • SX - Submitted to OSTI and failed to release
  • R - Fully released
  • D - Deleted

The four "Submitted to OSTI" statuses (SO, SV, SF, SX) in E-Link 2 are an expansion of the SO status from E-Link 1. Each of these statuses legally satisfies the STI requirement, which means there is no more action the user is required to take. OSTI uses these statuses to indicate where in our internal processing the record is currently at. In the vast majority of cases, a successfully submitted record should traverse from the SO -> SV -> R statuses almost immediately.

What if my record is stuck in a SO/SV/SF/SX status?

This indicates a problem within OSTI's internal processing pipeline, or an issue with the record metadata/media of your submission that was not immediately identified. In either case, OSTI personal will be notified and will address the problem internally, or get in contact with the submitter to fix the issue with the metadata/media.