Concept - Order Export Framework

Table of Contents

Product Version

7.5

Product To Version


Status

1 Introduction

This document deals with the intentions and concepts behind the order export. Orders can be exported in many ways regarding the export format as well as the technology. Exported orders are transmitted to or imported by 3rd party systems. Furthermore, the data that needs to be exported may differ among different customer deployments. This way, Intershop 7 provides a full-featured order export out of the box. An administrator should consider the contents of the present document rather as a blueprint of how customized export scenarios may be realized. So the Intershop 7 order export is referred to as an order export reference implementation in the further course of this document.

Intershop 7 uses the following functional components for order export:

  1. Order data export can be triggered synchronously by the Managed Services Framework and asynchronously by the Data Push Services Framework. The Data Push Services Framework is an extension of the Managed Services Framework tailored to the needs of asynchronous time-triggered exports. Both frameworks represent common functionality that can be used to trigger synchronous and asynchronous export of Intershop 7 data.
  2. Order and Packing Slip Export has two functions:
    • Filtering the orders and their line items that should be exported and
    • Changing status values of the order, their line items and applied payment methods during import/export.
  3. The order export reference implementation explained in the Concept - Order XML Export mainly specifies how an order is transformed from Intershop 7's internal representation to an external one.

With Intershop 7 complete orders can be exported, but, in contrast to previous ES6.x versions, not (re-)imported in Intershop 7 for the following reasons:

  • There are many new features, like extended promotions, gift wrapping and product configuration/customization, that have a direct impact on the structure of an order.
  • The new calculation framework introduced with Intershop 7 can handle complex cart calculation scenarios, with numerous intermediate calculation steps. So calculation of an order is only valid if it is done in the context of a running Intershop 7 instance with a specific configuration at a specific time (e.g., time-triggered promotions).
  • The legacy ES6.4 order import will import the order into legacy columns that still are available. This is not a competitive solution.

Therefore, in Intershop 7 there is an export of complete order data and an import of status value updates.

Using the Data Push Services Framework and Order Export Framework mentioned above, various export/import formats and targets can be implemented. Examples are the services Order XML Export and Order Submission.

Note

Basically, all data can be exported that are retrievable by accessing methods of related business objects and their extensions. It has to be noted that not all data, like certain product information of order line items, has to exist at the time the order export is triggered. Product information might be changed, or products might be removed in the meantime.

2 General Workflow of Order Export


The order export framework provided by the cartridge bc_order_impex consists of the following steps (see diagram above):

  1. Order export is triggered.
  2. The Data Push Services Framework starts an order export job.
  3. An order search query bc_order_impex...OrderExportSearch.query searches for orders.
    The configuration is stored at the export job.
  4. A list of orders is passed to the export service.
  5. The order export service uses data mapping to serialize the order.
  6. The export service writes the serialized orders to an OutputStream.
    This can be a file or a transport protocol to another system.
  7. Orders are exported.

3 Automatic State Changes and Failure Handling

Automatic status updates for orders and order line items can be configured to keep track of failed exports and completed or canceled orders which were exported. It can also be used to trigger a new order to become in progress.

Note

An updated status which was set during export does not refer to the exported data and will, therefore, only be visible in the system. If another export would be performed afterwards, the exported data would then contain the previous status updates.

The transition from new to exported upon export is enabled by default.

From ICM version 7.10.36.0 it is possible to deactivate the order status and line item status update during order export or order submission service, which is useful in scenarios where an order export should not influence the order status within the ICM.


Configure automatic state change for export action

In case of status updates being enabled, the order export job supports the storage of the reason for a failed export. A reason is comprised of a reason code and a more detailed description. Both are set together with the status when it changes to state EXPORTFAILED. The reason is only displayed in the order details page of the Intershop 7 Commerce Management.

In order to use the feature, the exception causing an export to fail must be wrapped by or inherit from com.intershop.component.orderimpex.capi.export.order.OrderExportServiceException. All other exceptions (e.g., invalid order, Input/Output exception) lead to a termination of the export of this order.

3.1 Configuration

The configuration of the reason codes and their localizations are stored in the database. The involved tables - these are STATEDEFINITION, STATEINFORMATION and STATEINFORMATION_AV - are initialized during the DBInit using the preparer com.intershop.beehive.bts.dbinit.preparer.state.PrepareStateDefinitions.

Note

After the installation and creation of the first orders the reason codes must not be changed (except localization) or removed, because they may be in use.

3.2 Example

dbinit.properties
Class1  = com.intershop.beehive.bts.dbinit.preparer.state.PrepareStateDefinitions  \
          sample.order.dbinit.data.StateDefinition \
          sample.order.dbinit.data.StateInformation
StateDefinition.properties
#################################################
# Order status reason codes                     #
#################################################
OrderStatusReason;1000=DUPLICATE
OrderStatusReason;1100=INVALID_ARTICLE
StateInformation_en.properties
#################################################
# Order status reason codes                     #
#################################################
OrderStatusReason;1000=due to a duplicate order ID
OrderStatusReason;1100=order contains invalid data

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets