Order: Historical Information on Orders [ORDHIS]

Guidance for Schema Version:

21.3

Definition of Capability

Airline

Ability to provide detailed historical information on orders. This should include both changes initiated by the Seller and by the Airline.

Seller

Ability to request detailed historical information on orders.

NOTE: System Providers will use the above definition that pertains to their customers for Capabilities Verification.

Links to EASD Implementation Guidance

Capability: Historical information on Orders: https://standards.atlassian.net/wiki/spaces/EASD/pages/574816364

Concept: Order History: https://standards.atlassian.net/wiki/spaces/EASD/pages/574652557

Concept: Order Versioning: https://standards.atlassian.net/wiki/spaces/EASD/pages/574259659

Related Concepts, Capabilities and Worked Examples:

NOTE: Retailing Capabilities Verification Guidance will align to the published EASD Implementation Guidance at all times. From time to time when new guidance is published this will be updated and supersede any Retailing Capabilities Verification Guidance listed below.

Retailing Capabilities Verification Guidance

For all capabilities, please also consult the list of general guidelines for adherence to best practices that span across several capabilities and messages: https://standards.atlassian.net/wiki/spaces/ARMI/pages/584318980/General+Guidance

The history of an Order is managed and tracked by the Airline in their Order Management System from the time of Order creation. Tracked changes can be comprised of Seller- and Airline-initiated changes. These details can be retrieved at any time by the Seller.

Technically, the Order history attempts to capture all the information that differs between one version of an Order and the next, following a change requested by the Seller or made by an Airline. It returns an accumulation of all changes within the lifecycle of an Order in sequential/chronological order starting from the most recent all the way to the initial version. The data involved in each tracked change follows a similar principle used when an Airline notifies a Seller of a change (OrderChangeNotifRQ). Therefore, the only information that is needed in each group of changes is the specific data elements that have actually changed, as well as the related IDs necessary to indicate where those elements are located within the Order. Data that has not changed should not be included in the ChangeOperation.

The structure of historical details of an Order in OrderHistoryRS is composed primarily of two parts:

  1. The last snapshot of the Order

  2. Any changes made to the Order following its creation:

    1. Seller-initiated changes including those made by secondary agents for certain operations against an order.

    2. Airline-initiated changes

These changes are grouped together, where each group of changes collectively decreases the version of the Order by one. These groups are represented within a “ChangeOperationGroup”, which can in turn consist of one or multiple “ChangeOperation” elements. Below is a representation of the hierarchy of information in OrderHistoryRS:

  • ChangeOperationGroup - [each ChangeOperationGroup can contain as many ChangeOperations needed to collectively decrease the version of the Order. OrderVersion is defined at this level, i.e. the resulting version of the Order incurred after having applied the changes specified in this group of ChangeOperations].

    • ChangeOperation - [contains add/delete/replace type operations on any changes applied to an Order]

      • ChangeDateTime - [Timestamp for when this change is effective from in the OMS]

      • ChangeTypeCode - [The type of change being made to the Order – see ATSB Codeset Directory “CHT”]

      • ReasonCode - [The reason behind the change being made to the Order – see ATSB Codeset Directory “CHR”]

      • New - [data elements to be appended to Order structure or to replace elements defined in “Old”]

      • Old - [data elements to be physically removed from Order structure or replaced by elements defined in “New”]

The first version of the Order should be presented in the “New” structure in its entirety (with nothing in “Old”), be placed in a single ChangeOperation, and with “OrderVersionNumber” set to “1”.

Once an Order has been created, if a Seller requests the history if an Order before any Seller- or Airline-initiated changes have occurred, they should simply see the equivalent of an entire snapshot of the Order, as it would appear if retrieving it through OrderRetrieveRQ.

Subsequently, change can be structure as defined in the sections above, depending on the type of change.

This allows the Seller system to interpret and reconstruct the state of an Order at any point in its lifecycle simply by using the initial Order (version 1) as a baseline, and applying subsequent changes onto this baseline.

Three basic types of operations can affect the information of an Order: addition, removal, and replacement of information. To capture these, the “New” and “Old” structures need to be used in the following combinations:

  1. Adding information to an Order:

    1. Include new data elements only in the “New” structure. “Old” should remain empty.

  2. Removing information from an Order:

    1. Inversely to adding information above, the removal makes use of only the “Old” structure, which includes the data that should no longer appear in the Order.

  3. Replacing information in an Order:

    1. Make use of both “New” and “Old” by defining the data in “Old” that is intended to be replaced by the data in “New”.

The decision of how and when to use New, Old or both depends on each Airline’s implementation, acknowledging that the schemas provide flexibility in this regard. For example, replacing data (i.e. making use of New and Old together) could also be achieved by two consecutive ChangeOperations of New followed by Old, or vice versa.

The important thing to consider is that all changes defined within one group of ChangeOperations (i.e. all occurrences of ChangeOperation within each ChangeOperationGroup) are to be interpreted atomically. This means that when the Seller parses through changes within the group, all changes are to be interpreted together and in their intended sequence, or not at all. This similar design principle is also, and to a greater extent, important for the functioning of OrderChangeNotifRQ, which works very similarly to OrderHistoryRS in this regard.

Airline

Provide OrderHistoryRS containing at least one change. i.e. the message should reflect at least two versions of the Order (e.g. OrderVersion 1, as the full/initial snapshot of the OrderView, as it was presented to the Seller upon order creation, and OrderVersion 2 containing whichever change has affected the Order subsequently, whether voluntary or involuntary).

Any one of the following message pairs

OrderHistoryRQ/OrderHistoryRS

Seller

Any one of the following message pairs

OrderHistoryRQ/OrderHistoryRS

NOTE: For all versions prior to that listed above (generally the most recent), the verification will be based on the guidance available for that version. In the case that no guidance is available, verification will be at IATA’s discretion.