Background
XML
XML is the eXtensible Markup Language, a way of encoding data in a file with markup that explains to readers what the data represents.
...
Whenever the eLandings developers need to add a data element they modify the XML schema. They also increment the schema version number, and modify the eLandings codebase to add forward and backward compatibility logic to handle differences in documents made with different versions of the schema. In many cases end users and interfacing systems may not be affected by the new or changed XML elements.
Versioning Stability for Interfacing Systems
Systems that interface with eLandings can generally continue to use an outdated schema if they do not use data elements contained in a newer schema. While the eLandings development team recommends that all interfacing systems keep up to date on schema versions, we recognize that it can be difficult or inconvenient to update interface code in a timely manner. The eLandings system supports the use of legacy versions of the schema. The system automatically upgrades incoming data to the current version of the schema automatically.
| Warning | ||
|---|---|---|
| ||
If the schema is changed to add a new required field then that field will still be required, even if data is imported using an older version of the schema. The use of legacy versions of the schema does not relieve the user of the requirement to honor all current business rules in the system. |
For interfacing systems that export XML documents from eLandings, the user export feature on landing and production reports renders the XML document according to the current schema version. In the Spring of 2009 the eLandings system added a schema version preference to its user profile page. This allows users to specify a legacy schema version to use. This allows users to continue to export reports created with an older version of the schema while their system developers are enhancing their system to use the newer version of the reports.
The public web services have a similar capability. Each web method includes a version argument that specifies the schema version for returned XML documents. Input XML documents will automatically be made forward compatible to the current schema version.
| Note | ||
|---|---|---|
| ||
While the eLandings system provides backward compatibility to prior schema versions as a convenience to users and interfacing systems, support for prior versions is limited. Support for a particular schema version is limited to one year after it is superseded. While in many cases, older versions of the schema will still be usable, no support for issues with versions of the schema more than a year out of date should be expected. In particular, pre-existing bugs with older version of the schema will not necessarily be fixed if they are found and reported. Such bug fixes will almost always require upgrading to a currently supported version of the schema. While in most cases prior versions of the schema will be supported for a year, regulation changes imposed by the North Pacific Fishery Management Council or other agencies may have shorter implementation timeframes. In such cases, the regulatory timeframe will take precedence and interfacing systems will need to upgrade to the current schema version. Such occurrences are rare, but not unknown. |
XML Usage Documentation
The eLandings documentation on the Confluence website includes a system interface guide that describes the main XML documents, their elements, and how the elements are used.
XML Schema Change Notification
The user profile has been enhanced to include a schema change notification flag. Users who set this flag will be notified whenever the schema is being changed. This will also facilitate the dissemination of useful information about interfacing with eLandings.
XML Interface Tools
XML is very much an IT standard, and many tools are available for reading and writing XML documents, and for extracting from XML documents the component data.
JAXB
The eLandings development team uses JAXB from Sun Microsystems for working with XML documents in Java.
Visual Studio
The Visual Studio integrated development environment from Microsoft includes tools to read an XML schema and provide programatic access to documents created from that schema.