Document Properties
Kbid2D3662
Last Modified04-Feb-2020
Added to KB03-Dec-2012
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks

Concept - Order Export (6.6 - 7.4 CI)

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, IS7 provides a full-featured order export out of the box. This implementation should be more considered as a blueprint of how customized export scenarios in real customer deployments may be realized. So the IS7 order export is referred to as an order export reference implementation in the further course of this document.

IS7 uses the following functional components for order export:

  1. Order data export is triggered synchronously by means of 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 Enfinity 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 this document mainly specifies how an order is transformed from Enfinity's internal representation to an external one.

With IS7 complete orders can be exported, but, in contrast to previous ES6.x versions, not (re-)imported in Enfinity 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 IS7 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 Enfinity 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 IS7 there is an export of complete order data and an import of status value updates.

If IS7 has to meet additional customer-related requirements, the extension concept described later in this document can be used to export additional data. Or a new, completely different order export implementation has to be developed to meet those additional requirements.

Both import and export functionality of the IS7 order export reference implementation use XML as source/target format. However, with the Data Push Services Framework and Order Export Framework mentioned above various export/import formats and targets can be implemented.

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

workflow of order export

The order export consists of the following steps (see above diagram):

  1. Order export will be triggered.
  2. An order export job starts by the Data Push Services Framework, see this configuration ac_order_export_xml...services.component.
  3. An order search query bc_order_impex...OrderExportSearch.query will search for orders. The configuration is stored at the export job.
  4. A list of orders is passed to the export service.
  5. The implementation of the order export service will use the OrderXMLWriter to serialize the order. The OrderXMLWriter will make use of JAXB to get this done. JAXB uses builders and binding classes to create XML. Builders are configured by the component framework. Builders will get relevant data from the order-related business objects and their extensions.
  6. The export service will use the serialized orders to write it to an OutputStream. This can be a file or a transport protocol to another system.
  7. Orders are exported.

3 Set Up an Order Export

3.1 Procedure

Enable the service in Operations:

  1. Log in to Operations.
  2. Select Sales Organizations | PrimeTech | Tab Services.
  3. Select Order Export Services.
  4. Enable Local XML File Order Export.

Create the service in Enterprise:

  1. Log in to the PrimeTech Enterprise.
  2. Select Services.
  3. Click New.
  4. Click Order Export Services | Local XML File Order Export | Next >>.
  5. Type Name and ID of your service, e.g. "OrderExportService".
  6. Type for configuration a valid file location, and prefix e.g. c:\temp\orders.
  7. Share and activate your service.

Create export to run:

  1. Go to Orders | Order Import & Export.
  2. Click New.
  3. Give your export scenario a name.
  4. Select your desired service configuration, e.g., OrderExportService.
  5. Have a look at the tabs to configure your export.
  6. Go back to Orders | Order Import & Export.
  7. Select your export and run it.

To repeat an export, only run is required.

Note

At the channel back office you can also create an export. Here only orders of this channel are exported.

3.2 Cartridges and Cartridge Elements

The following elements of the order export reference implementation have to be considered:

  • Business objects ( *BO) and their extensions ( *Extension) representing Enfinity's public domain API.
  • Annotated binding classes ( *XML) represent XML schema types.
  • Builder classes ( *Builder) act as link between business objects and XML binding classes by mapping information from business objects to XML binding classes.
  • XSD documents representing the external order format as XML schema. The XSD is directly created from XML schema types defined as javax.xml.bind.annotation.* annotations in XML binding classes. 
ConceptOrderExportRefImplCartridgeStructure2

4 Java-XML Binding

(Java->XSD) - Java classes, their attributes and methods are provided with annotations that control the transformation. A corresponding XML schema can be generated with the schemagen command line tool accompanied with J2SE. Please have a look at the Cookbook - Order Export (valid 7.0 to 7.4 CI) | Recipe: 3rd Party System Wants to Import Orders Exported by IS7.

5 Extending / Changing the Export

Here is described how to extend the export by adding an additional implementation.

Have a look at ac_order_export_xml\staticfiles\cartridge\components\instances.component. Here you can see that you can instantiate a builder that can have sub-builders by using the fulfill statement. In this way the XML export file is constructed.

For example: The OrderShippingDiscountsBuilderImpl was introduced later. It should be placed in order-summary -> order-pricing -> pricing -> shipping-discounts. The tags order-pricing -> pricing already exist. Therefore, inside the fulfill tag of OrderExportXML-OrderPricing-Pricing the new OrderShippingDiscountsBuilderImpl was placed. By linking to the parent builder, you can achieve that the outer XML is left out if  the inner XML is empty.

The OrderShippingDiscountsBuilderImpl class will get a BusinessObject from the parent handler. You should use OB classes to determine data you need for this export.

The XML will be represented in this case by the DiscountXML. The outer brace is the ShippingDiscountsXML class.

6 References

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
Support Tickets