...
XML documents are not a system boundary, and don't require special boundary translation and testing.
XML data exchange for third parties
Import vs. Export
The eLandings system provides two options for third party interfacing systems. The third party system can collection and validate all the needed data, and create the XML document for import into eLandings. In this case the eLandings validation rules serve as a double check to insure that all data needed is present and valid. When creating documents for import the third party system can either use placeholder landing report IDs and fish ticket numbers, or can acquire real report IDs and fish ticket numbers from eLanding and use those. Importable numbers are a weak point in the system because they can be inadvertently reused. Third party systems that use this approach must handle numbers very carefully to avoid unintended results.
Alternately, seafood processors can enter reporting data into eLandings, then export it as an XML document for induction into their own business system. In that case, the third party system is assured that the data being inducted is valid and correctly formatted.
XML Data
XML documents produced by eLandings can be observed to contain many elements and attributes, documenting the entire landing report.
Elements are data items that provide information to eLandings. Attributes are information that eLandings provides as feedback that amplifies the data. For example,
| Code Block |
|---|
<port_of_landing ifq_port_code="168" name="Sitka">SIT</port_of_landing>
|
is the port_of_landing XML element. It provides the port code "SIT". The attributes associated tell any person or system reading the document (but not eLandings) that the code represents the port of Sitka, and that the NMFS IFQ port code for Sitka is 168. The eLandings system never reads attributes, and they should never be used to try to convey information to the system. The eLandings system reads only the element data, and is able to derive the attributes itself.
XML Data Structure
The data structure of each type of XML document in eLandings is unique, but the documents share some common features.
Schema Version
The eLandings XML documents include a schema version number that tells receiving systems what version of the schema was used in preparing the document. This allows receiving systems to appropriately downgrade documents if a newer schema is in use.
Messages
Most eLandings XML document include a messages section that contains messages about the actions of web services that created or processed the document.
Report Data
The various XML documents contain data appropriate to their type and function, for example landing report and fish ticket data in landing report documents and NMFS production report data in production report documents.
XML Schema
The XML schema is used to describe the format of XML documents in eLandings. Since the format can be enhanced over time the XML schema includes a version number that uniquely identifies that version of the schema, and that can be used to communicate to the system the version of the schema that was used to create any particular landing report file or XML document.
The XML schema can be used by a variety of tools to create code that will read and write XML documents.
XML Schema Versioning
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.