Update an Existing Exchange

The components of a data exchange, or flow, must occasionally be updated to maintain consistency with business rules and allow for enhanced functionality. The owners or stewards of each exchange are typically responsible for making these changes. Individual flow owners are identified on each Data Exchange.

Exchange Design Rules and Conventions (EDRC) contains important information for flow owners that are updating a data exchange. The document describes not only the documentation requirements for developing a new data exchange, but also outlines the versioning rules and required actions when updating an existing exchange. In addition, XML schema version rules are covered in the XML Design Rules and Conventions.  The following is a summary of these requirements:

  • Data Exchange Upgrade Scoping and Planning: When an exchange undergoes an upgrade, there are often two competing considerations.
    • The desire to implement potentially significant changes that increase the usefulness and versatility of the exchange.
    • The desire to minimize the effort required by existing exchange implementers to transition to the upgraded exchange.

If the exchange upgrade is too conservative, there is a risk of a missed opportunity to expand the exchange in new and useful ways. If changes are too complex, however, the cost and effort required by existing exchange implementers to upgrade may be onerous. Because each situation will be unique, there is no universal guidance on how much to change a an existing flow. The Exchange Design Rules allow for discretion on the part of the exchange designers to choose what upgrades to pursue, however, if the exchange is undergoing a significant redesign, all exchange components must be upgraded to meet the latest standards. “Significant redesign” may or may not correspond to a major version upgrade as defined in the EDRC’s Exchange Component Versioning principles. It is the discretion of the developer to whether the upgrade constitutes a significant redesign.

  • XML Schema Updates: If a data exchange update results in a change to the XML schema, they should be made in accordance with the XML Design Rules and Conventions. This documents the different versioning rules for minor (backward compatible) or major (not backward compatible) schema changes. Updates to an XML schema may require versioning changes to the XML namespace, schema file names, and W3C schema version.
  • Documentation Updates:
    • FCD: The Flow Configuration Document (FCD) is the central information resource for an exchange. Users should be able to identify the current version of all exchange components by reading the current version of the FCD. The FCD contains the change history for all exchange components in its initial pages, and information about the data exchange including a list of current and supported schema versions and Data Services. Any time any exchange component is changed the FCD must also be updated to reflect and document those changes. As the document of record for an exchange, users must always be able to refer to the change history tables in the FCD to determine the version of schema, DET, and other documentation. The FCD revision identifier must be incremented if an exchange adds a new data service or if there is a change to business rules.   
    • DET: The Data Exchange Template contains a listing of schema elements and additional information about their origin, use, and may include business rules. Since the DET serves as a data element dictionary for the schema, the major and minor version of the DET must align with the schema it describes. In the event of a correction or business rule change, the DET only requires an incremented revision identifier on the DET file name.
  • Document-Only Revisions: In cases when only the documentation for an exchange is updated and the modification is classified as a “revision” as described in the Exchange Component Versioning principles, the package may only include the updated FCD and any other revised documents.
  • Publishing Changes: When a new or modified exchange is ready for review, it must be bundled into a single Exchange Documentation Package and submitted to Network Governance for review, as outlined in Exchange Documentation Package Preparation and Review Process for the Exchange Network.

Developers who wish to publish a revised data exchange must prepare a flow documentation package and submit it to the E-Enterprise and Exchange Network Interoperability and Operations Team (IOT) for review. The package must include the following components:

This flow documentation package is designed to assist future implementers of the data exchange. The document Exchange Documentation Package Preparation and Review Process for the Exchange Network describes the process for developers to prepare and submit XML schema and exchange documentation for review and acceptance by the IOT. The document also describes the review process and outcomes.  (Note that on December 1, 2015, the IOT assumed the responsibilities of the sunsetted Network Technology Board or “NTB”.)

Questions and completed flow documentation packages should be submitted to the IOT Co-Chairs.