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.

XML is a widely used standard for data exchange. The standard is maintained by the World Wide Web consortium. Many tools are available that allow software to read and exchange data in XML files.

Why XML

The eLandings system is focused on creating and receiving reports. It is primarily a rule based system, applying rules to reports to let the user know whether or not they are correct, rather than a workflow based system where documents are built up through many operations.

The use of XML provides both the eLandings development team and 3rd parties with many options in terms of tools. XML is language agnostic, and provides good interoperatability.

How XML is used in eLandings

The eLandings system uses XML documents as its primary data aggregate. The same XML format used by third parties to transmit landing reports to the system is used internally to pass reports between system components. This greatly increases the reliability of the XML rendering process. Data extracted from the database and rendered as an XML document is rendered correctly, because the entire system uses those XML documents and any bug introduced into this process is found and fixed quickly.

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,

<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.

XML Usage Documentation

The eLandings documentation on the Confluence website includes a system interface guide that describes