Order Versioning

Owned by Vanni Sanvincenti
Last updated: 15 Apr 2024
3 min read

Overview

This section describes the Order Versioning concept. It has close relations to:

Orders undergo changes during their lifetime, starting with order creation and up to their most recent status. A version number allows  reference to an order as it was at a given point in time.  The Order version should be incremented by the airline whenever a data element visible to the Seller is changed (i.e. OrderViewRS, OrderHistoryRS, OrderChangeNotifRQ).

Order Versioning principles

  1. The order version is an integer, starting at 1 for the first version of the order (i.e. the version created by an OrderCreateRQ message) and increasing over time by 1.

  2. The airline can decide that a set of changes leads to a single version increase. This is visible in OrderChangeNotifRQ message, where an order version number is attached to a ChangeOperationGroup (consisting of one or multiple ChangeOperation elements).

  3. The airline may maintain an internal versioning of the order that will typically be more granular than the external one. Only the external versioning is visible in NDC messages.

Usage of order versioning

  1. In OrderRetrieveRQ message: the seller can request a specific version of the order to be returned: if no specific version is requested, the airline should return the most recent (current) version of the order. This feature (retrieve a specific version of an order) is optional.

  2. In OrderViewRS message: whenever an order snapshot is returned by OrderViewRS  (as reply to an OrderCreateRQ, OrderRetrieveRQ or OrderChangeRQ), it is a recommended practice for the airline to return the order version (ifOCN and/or OrderHistory  are supported, as in both, version number is mandatory).

  3. In OrderChangeNotifRQ message: when an order change notification is sent by an airline, this should trigger at least one version increase. Each version increase is the consequence of one ChangeOperationGroup.

  4. In OrderHistoryRQ message: the seller can request the history of the order between a specified version and the most recent version (current order). If no version is specified, the airline should return the entire history of the order.

  5. In OrderHistoryRS message: OrderHisotryRS message contains the list of all the changes (or a subset of them, if a specific version number is requested in the OrderHistoryRQ message) of an order. Here the term “changes” is intended in the OrderChangeNotifRQ sense (i.e., a list of ChangeOperationGroup elements).

  6. In OrderChangeRQ message: whenever changes are to be applied (or committed) to an order, the seller can specify the version of the order that he/she assumes as being the current (most recent) one. This allows an airline to verify that no change of version has happened without the seller being aware of it. The best practice is:

    1. For the seller: to send the version number in any OrderChangeRQ message. The most recent version of the order can be obtained by the seller with any prior OrderViewRS message from the airline (e.g., as a reply to a prior OrderRetrieveRQ message).

    2. For the airline:

      1. If no version is passed in the OrderChangeRQ message, proceed assuming the seller is aware of the current version of the order.

      2. If a version is passed in the OrderChangeRQ message:

        1. If it matches the current order version, proceed as usual.

        2. If it doesn’t, then the airline should return an error.