Introduction
This document deals with the intentions and concepts behind the file based order export to the XML format. The XML files with the exported orders are transmitted to 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 content 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 concepts of the Order Export Framework to provide the file based XML export that is available out-of-the box.
If Intershop 7 has to meet additional customer-related requirements, the extension concept described later in this document can be used to export additional data. Alternatively a new, completely different order export implementation has to be developed to meet those additional requirements.
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.
References
General Workflow of Order Export
The order export consists of the following steps (see diagram above):
- Order export is triggered.
- The Data Push Services Framework starts an order export job.
See the configuration ac_order_export_xml...services.component for details. - An order search query bc_order_impex...OrderExportSearch.query searches for orders.
The configuration is stored at the export job. - A list of orders is passed to the export service.
- The order export service uses the OrderXMLWriter to serialize the order.
The OrderXMLWriter uses JAXB. JAXB uses builders and binding classes to create XML. Builders are configured by the Component framework. Builders get the relevant data from the order-related business objects and their extensions. - The export service writes the serialized orders to an OutputStream.
This can be a file or a transport protocol to another system. - Orders are exported.
Set Up an Order Export
Procedure
Enable the service in Organization Management Application:
- Log in to Commerce Management application of the organization.
- Select <Sales Organizations> | <Organization> | Services tab.
- Select the Service Group Order Export Services.
- Enable Local XML File Order Export.
Create the service for your organization in the ICM:
- Log in to your organization.
- Select Services.
- Click New.
- Click Order Export Services | Local XML File Order Export | Next >>.
- Type name and ID of your service, e.g., OrderExportService.
For configuration, type a valid file location, and prefix, e.g., c:\temp\orders.
The path should be provided as absolute path. A relative path will be interpreted as starting from the <server>\local\engine\nodemanager.
However, there is the possibility of using space holders. Therefore, these three ICM environment variables can be used: ${IS_HOME}, ${IS_SHARE} and ${IS_TEMP}, e.g. ${IS_TEMP}\export\orders.
- Share and activate your service.
Create export to run:
- Go to Orders | Import & Export.
- Click New.
- Give your export scenario a name.
Select your desired service configuration, e.g., OrderExportService which was created in the previous step.
- Have a look at the tabs to configure your export.
- Go back to Orders | Import & Export.
- Select your export and run it.
To repeat an export, only step 7 is required.
Note
In the Commerce Management application you can also create an export at the channel level. Here only orders of this channel are exported.
Cartridges and Cartridge Elements
The following elements of the order export reference implementation have to be considered:
- Business objects and their extensions representing Intershop 7's public domain API.
- Annotated binding classes represent XML schema types.
- Builder classes 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.
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 | Recipe: 3rd Party System Imports Orders Exported from IS7.
Extending / Changing the Export
This section outlines 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 how to 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 gets a BusinessObject from the parent handler.
Use BO classes to determine data you need for this export.
The XML is represented in this case by the DiscountXML. The outer brace is the ShippingDiscountsXML class.
Attachments
- Order export demo file ExampleOrderExport-Intershop 7.4.1.0.86.xml.