Ability to provide detailed historical information on orders (for both voluntary and involuntary changes).
Ability to request detailed historical information on orders
Update Links: Capability: Historical information on Orders
Concepts: Offers & Orders: https://guides.developer.iata.org/v213/docs/offers-orders-1
Worked Examples: Offers & Orders: https://guides.developer.iata.org/v213/docs/offers-orders-use-cases
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:
The last snapshot of the Order
Any changes made to the Order following its creation:
Seller-initiated changes including those made by secondary agents for certain operations against an order.
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:
Adding information to an Order:
Include new data elements only in the “New” structure. “Old” should remain empty.
Removing information from an Order:
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.
Replacing information in an Order:
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.
Any one of the following message pairs
Any one of the following message pairs