Contents
Topic overview
The OXID adapter App extends the Multi-channel sales framework with capability to connect to the OXID webshops. With the OXID adapter it is possible to use exchange the data with the webshops using the functions found in the MCS framework.
For more information about the features supported by the OXID adapter, see General features.
For more information about the Multi-channel sales framework, see the document Introduction: Multi-Channel Sales.
Definition of terms
Sales channel
Depending on the context, the term might have one of the following meanings:
1. External system in which items are sold (e.g. web shop, call centre, shopping mall).
2. An ERP business entity which stores the configuration for connection with sales channel within the meaning of 1.
OXID webshop
An open source e-commerce platform providing the online shop functionality with support for B2B and B2C processes.
OXID adapter
An adapter dedicated to the MCS framework. The OXID adapter extends the MCS framework with capability to connect to the OXID webshops. The OXID adapter is provided in a separate App.
Processes
This chapter describes the business processes that are covered in the document Introduction: Multi-Channel Sales with respect to the OXID adapter.
Configuration of the sales channel
The OXID adapter introduces additional steps to the procedure of sales channel configuration, on top of the standard procedure that was described in Introduction: Multi-Channel Sales.
Sales channels
When defining a new sales channel, select the OXID adapter from the drop-down list of all available adapters found in the field Adapter.
Beside from the standard attributes and tabs found in the application, the OXID adapter introduces additional tab OXID. It is necessary to fill all the required attributes in this tab in order to properly define a new sales channel.
For more information regarding the OXID tab, see document Extension: Sales channels/OXID adapter.
Adapter-specific applications
The OXID adapter introduces a set of supplementary applications, which are used to configure the OXID-specific settings. The applications are:
- OXID partner template assignments
- Use this application to define country-specific partner templates to be used during the import of new customers from the OXID webshop.
HTTPS authentication
In case of connection over HTTPS, the SSL authentication requires that the client (the CEE) is provided with a valid server certificate by the server (the shop). The verification of the server certificate is based on the CEE keystore which can be accessed in CEE application System cockpit, category Certificate authority.
To ensure that the server certificate is valid, the server certificate must be imported in CEE using action Generate or import certificate. In case of certificate chain with more than one certificate, each certificate found in the certification path should be imported as well. The certificates should be imported in the order in which they appear on the certificate path, beginning from the root certificate. Attribute Logon should be set to Allow connection.
In test configurations, the SSL authentication may be disabled by setting following system property:
com.sem.ext.app.oxid.debug.ssl.trustAll=true
Note, this setting should not be used in production environment and is designed for test purpose only.
Data transfers
Exporting item data
The OXID adapter supports all batch application associated with the process of exporting item data:
- Export item characteristic classifications
- Export item categories
- Export items
- The characteristic classifications should be in sync between the systems before the item export is executed; this can be achieved by executing batch ‘Export item characteristic classifications’. When updating characteristic values for particular item, all previously existing values are removed.
- The category tree should be in sync between the systems before the item transfer is executed; this can be achieved e.g. by executing batch ‘Export item categories’. When updating category assignments for particular item, all previously existing assignments are removed
With each exported item, following information is transferred to the OXID webshop:
- Item master data
- Item characteristics
- Item logo
- Item media (PIM)
- Item relations
- Item-to-category assignments
- Item-to-distributor assignments
- Item-to-manufacturer assignments
- Item prices
Exporting price data
The OXID adapter supports the batch application Export sales price lists. With each exported price list, following item prices are transferred to the OXID webshop:
- Standard price
- Scale sale prices and discounts
- Group prices
For more regarding the determination of prices, see Calculation of prices.
Exporting availability data
The OXID adapter supports the batch application Export item availability. With each processed item, following availability data is transferred to the OXID webshop:
- Quantity available
- Calculated based on the item quantity on hand, quantity in transit and reservations.
- Stock flag
- Attribute found in application Items, view Base, tab OXID
- Availability date
- Determined only if the item is currently not available
For more information regarding the calculation and export of item availability, see document Introduction: Multi-Channel Sales.
Exporting customers
The OXID adapter supports the batch application Export customers and can be used to export B2C/B2B customers and B2B employees from CEE to the OXID webshop.
For more information regarding B2B processing, see section Business-to-business.
Exporting sales order changes
The OXID adapter supports the batch application Export sales order changes. The table below provides an overview of all changes that are detected by the system, together with the corresponding activity in the OXID webshop.
| Type of change | Activity in OXID webshop |
|---|---|
| Sales order status changed to Released | Move the order to folder New. |
| Sales order status changed to Completed | Move the order to folder Finished. |
| Sales order status changed to Cancelled | Cancel the order. Set the internal status to “Cancelled by Comarch ERP”. |
| Sales order delivery status changed to Incomplete | Clear the date of delivery. |
| Sales order invoicing status changed to Incomplete | Clear the date of payment and invoice number. |
| Picking status has changed | Set the internal status to “Processed by Comarch ERP”. |
| Delivery order was created | Update the date of shipping. Save the voucher PDF file. |
| Customer invoice was created | Update the invoice number. Save the voucher PDF file. |
| Customer invoice status changed to Completed | Update the date of payment. |
| Order confirmation was created | Save the voucher PDF file. |
| Receipt of goods status changed to Released | Set the internal status to “Customer return Save the voucher PDF file. |
In case of changes related to the creation of a voucher, the adapter can export the voucher PDF files to the webshop, if necessary. The function is described in section Transfer of vouchers.
Importing item data
The OXID adapter supports the batch application Import items. With each imported item, following information is transferred to the CEE:
- Item master data
- Item logo
- Item media (PIM)
- Item relations
Batch is also importing channel specific information which is stored in Item application, view Base, layout OXID – OXID tab is displayed.
More information can be found in document Extension: Item, View “Sales”/OXID.
Selective import
For OXID Sales Channel it is possible to set selective import of items by product number. After clicking on OXID eSales tab you can supplement the activated Prod. No. field with product number of the item that you want to import bypassing other items.
Import customers
With this batch application the customer data, which were created in the connected sales channel, are taken over in the partner master data. During this, only the data is taken over which has been newly created or changed since the last data transfer.
For each incoming customer the type is determined as follows:
If the sales channel is of type B2C, then the type of the customer is B2C.
If the sales channel is of type B2B, then the type of the customer depends on the configuration of the templates in application Sales channels, tab B2B.
If B2B employee template is specified, then the type of the customer is B2B employee.
If B2B organization template is specified, then the type of the customer is B2B organization.
Selective import
For OXID Sales Channel it is possible to set selective import of customers. After clicking on OXID eSales you can supplement the activated Emails field with email of the customer that you want to import bypassing other customers.
Importing sales orders
With this application you import the sales orders from the selected sales channels. Only those sales orders are taken into account that have been created or updated after the time point of the last order import. In doing so, the Time delay for sales ort acceptance specified in the sales channel is regarded. The application also considers sales orders that were not successfully accepted during the previous run.
The process of determining the type of the imported customer and sales orders depends on the configuration of the sales channel.
For each incoming sales order the type is determined based on the type of the sales channel. For example, if the sales channel is of type B2B, then all sales orders are imported as B2B.
Importing category trees
The OXID adapter uses the category trees in CEE to model three different kinds of tree-like structures in OXID:
- Categories
- Brands
- Manufacturers
All of the mentioned structures can be imported into CEE as category trees using the batch application Import item categories.
Calculation of prices
The OXID adapter supports prices and discounts on following price list views:
- Item
- Used for OXID standard price
- Used for OXID scale prices and discounts
- Customer price classification + Item
- Used for OXID group prices
Below is an overview of various kinds of OXID prices together with description on how are they converted to and from the CEE price lists.
OXID standard price
In OXID, a standard price of a product is displayed to the customer in two formats:
- Normal price (i.e. price per 1 unit of the item)
- Unit price
The normal price is based on the CEE’s price for 1 unit of the item from the view Item.
The unit price is displayed next to the normal price (e.g. 1,5 L | 3,33 EUR per Liter) and is based on the OXID-specific attributes found in application Items, view Base, tab OXID:
- Unit quanity
- Unit name
OXID scale prices and discounts
The scale prices and discounts are based on the CEE prices for scale quantities higher than 1 unit of the item, from view Item. It is required that each scale price of the item is lower than the standard price of that item.
OXID group prices
Each group price is based on the CEE’s price for 1 unit of the item from the view Customer price classification + Item. The customer price classification corresponds to one of the four distinct price groups in OXID (A/B/C/RRP). Each of the groups can be associated with the corresponding customer price classification in application Sales channels, tab OXID.
For more information regarding the sales price lists, see document Sales Price Listings.
General features
This chapter provides an overview of the OXID-adapter implementation of the general features provided by the MCS framework.
Business-to-business
With the OXID adapter you can specify whether your sales channel is used for B2B sales or B2C sales.
The behavior of following transfer batches is affected by the types of customers used in the sales channel:
For more information regarding the further processing of customers and sales orders in B2B context, see document Introduction: Multi-Channel Sales.
Multi-channel hierarchy
The OXID adapter supports following types of sales channels:
- Single channel
- Master sales channel in standard mode
- Sub sales channel
The single channel mode is recommended for the simplest OXID configurations in which the webshop consists of exactly one store.
If your OXID webshop consists of more than one store, you should define a multi-channel hierarchy when configuring the sales channels. The hierarchy should consist of following sales channels:
- One master sales channel with store ID set to the ID of the OXID’s master store (i.e. store without parent ID)
- One or more sub sales channels with store ID set to the respective IDs of the OXID’s sub stores (i.e. stores where parent ID is equal to the ID of the master store).
Each multi-channel hierarchy in OXID adapter must meet few conditions to be valid:
- All sales channels within hierarchy must use unique store IDs.
- All sales channels within hierarchy must use exactly the same Webshop URL.
- The Webshop URL used by any hierarchy must be unique (i.e. not used by other hierarchies).
For more information regarding the multi-channel hierarchies, see document Introduction: Multi-Channel Sales.
Customer type policy
The OXID adapter supports Mixed customer type policy, meaning that it is possible to define sales channels of different customer types within single hierarchy. The customer type of the sub channel is not restricted by the master channel.
Product Information Management
PIM functionality is spread across multiple applications in CEE. Below is a rundown of all PIM-specific applications and application extensions supported in the OXID adapter.
- Framework Base
- Application Items, view Sales
- Item media
- Media of type Image are transferred as product Pictures.
- Media of type Other are transferred as product Downloads
- FTP connection must be enabled in the Sales channel, tab OXID.
- Item media
- Application Items, view Sales
- Framework Multi-channel sales
- Application Sales channel item relations
- Item relations
- Supported relation types: Variant, Accessory, Cross-sell
- Item relations
- Application Sales channel item relations
For more information regarding each of the applications, see the respective online-help documentation.
Functional adapter scope
Although the functional scope of the MCS is very extensive, however, on the level of additional adapters responsible for communication there are differences that are associated with the business logic of individual platforms.
Another element are functional enhancements of sales channels, which are not covered in their official interfaces (plugins).
The aim of the chapter is to show the differences and limitations of OXID adapter in the context of the functionality of MCS.
Supported Multi Channel features
This chapter contains features supported by OXID adapter.
Sales channel management
| Functionality | Explanation |
|---|---|
| Multi store structure | Multi store structure can contain many stores, one of which being the master shop, and others the sub shops. For each of the shops, a respective sales channel is configured in the CEE system. |
| B2C | The adapter supports business-to-customer processes. |
| B2B | The adapter supports business-to-business processes. |
| B2B & B2C (mixed mode) | The adapter allows to use both B2B and B2C functionality simultaneously. |
| Sales channel partner assignments | Each sales channel partner represents an assignment between sales channel and a CEE partner. |
| Default currency | A company can declare a currency as its internal currency. If multiple internal currencies are used simultaneously, one must be designated as the primary currency. |
| Voucher transfer | The adapter can export all voucher PDF files generated in the CEE during the processing of sales channel orders. |
| Multilingual support for items | The adapter offers full support for multi-language (NLS) attributes. |
| Payment method assignments | The assignment is used to find the matching Payment method when importing the Sales order via MCS. |
| Payment terms assignments | The assignment is used to find the matching Payment terms when importing the Sales order via MCS. |
| Payment item assignments | The assignment is used to find the matching Billing item when importing the Sales order via MCS. |
| Shipping terms assignment | The assignment is used to find the matching Shipping terms when importing the Sales order via MCS. |
| Shipping item assignment | Assignment allow to define items that need specific shipment, for example large size items. |
| Country-based partner template assignments | Framework allows you to assign partner templates to sales channels, depending on the country of the partner. |
B2C Management
| Functionality | Explanation |
|---|---|
| Customer import (Batch) | Batch is importing customers from Sales Chanel to CEE. |
| Customer export (Batch) | Batch is exporting customers to the Sales Channel. |
| Pseudo partner (Guest purchase) | Pseudo partner is used as an ordering party for the sales orders from the sales channel. The Pseudo partner is always used when a customer of the sales channel is not registered as a customer or the customer in the ERP system is not yet available. |
| Adapter specific customer data | Contains customer data settings applied to particular adapter. |
| Customer acceptance | Due to B2C specific agreements and/or discounts for unique clients, it is required to manually validate that each imported customer organization or employee is indeed allowed to place orders. |
B2B Management
| Functionality | Explanation |
|---|---|
| Customer import (Batch) | With batch application it is possible to import customers from Sales Channel to CEE. |
| Customer export (Batch) | With batch application it is possible to export the B2B organizations and employees to Sales Channel. |
| B2B Partners as Organizations | You can assign a Partner template which should be used in case a partner will be created for this sales channel as organization. |
| B2B Partners as Contact Persons | You can assign a Partner template which should be used in case a partner will be created for this sales channel as employee. |
| Cockpit: Customer Approval | Application presents a quick view of any customers and employees that are awaiting for approval. The overview shows all partners which are currently in the status Blocked in the context of any sales channel. |
| Adapter specific customer data | Contains customer data settings applied to particular adapter. |
| Customer acceptance | Due to B2B specific agreements and/or discounts for unique clients, it is required to manually validate that each imported customer organization or employee is indeed allowed to place orders. |
Item management
| Functionality | Explanation |
|---|---|
| Item categories assignments | Item assignment is an element in the categories and represents an item-to category assignment. |
| Item categories import (Batch) | Import categories from the external system to the ERP. |
| Item categories export (Batch) | Export categories from the ERP to the external system. |
| Brands categories | Allows to assign brands categories to a sales channel. |
| Producer categories | Allows to assign producer categories to a sales channel. |
| Cockpit: Sales channel item categories | Application presents a quick view of all category trees that meet given conditions (e.g. properties of category and item nodes, use by sales channels). |
| Item acceptance (Batch) | With this batch the item data, which was created in CEE or imported from external sources, is accepted for sales channel processing. |
| Item import (Batch) | Batch allows to import item data from a Sales Channel to CEE. |
| Item export (Batch) | Batch allows to export item data to a Sales Channel. |
| Item characteristics | Item characteristics are used to describe specific features of items. |
| Cockpit: Item characteristics status | In this application the status of item characteristics for categories can be easily reviewed. Any missing mandatory or required characteristics are indicated, and for each item it is displayed how many characteristics are assigned. |
| Item characteristic settings | The configuration characteristics can be used in the production structure for analysis of substitute functions, conditions and formulae, for example for dispatching production orders or calculation, and in Planning. |
| Item relations: variant items | Allows to define relations of variant items type. |
| Item relations: cross selling | Allows to define relations of cross selling type. |
| Item relations: accessories | Allows to define relations of accessories type. |
| Item media assignments | An assignment between a Sales Item and Media. |
| Item media assignment acceptance (Batch) | Batch allows to accept item media assignments. |
| Adapter specific item data | Contains item data applied to particular adapter. |
| Exported Item types: material | Allows to export material type of item to a Sales Channel. |
| Exported Item types: service | Allows to export service items to a Sales Channel. |
| Exported Item types: billing items | Allows to export Billing items to a Sales Channel. They are used as an aid for clearing costs and allowances. |
Price management
| Functionality | Explanation |
|---|---|
| Single prices | The price is the exchange value of an item in monetary units. The price is expressed in a currency and per unit of measure. Prices can be recorded in the system for items and assigned in vouchers. |
| Customer Group prices | Allows to export Customer Group prices to a sales channel. |
| Scale prices | The scale indicates the lower limit above which the price component is used for price determination. |
| Item discounts | Allows to export item discounts to a sales channel. |
| Scale discounts | Allows to export scale discounts to a sales channel. |
| Price origin: Manual (from sales channel) | The price of each line item is provided by the sales channel (the external system). |
| Price origin: Price list (recalculation in ERP) | The price of each line item is determined according to the sales price listing of the sales channel. |
| Price list export (Batch) | Allows to export price list to a sales channel. |
Warehouse management
| Functionality | Explanation |
|---|---|
| Availability export | Allows to recalculate the availability of items for a sales channel. |
| Cockpit: Item availability | Application presents a quick view of all items in sales channels that meet given conditions (e.g. inventory management settings, warehouse organization and category). |
Sales order management
| Functionality | Explanation |
|---|---|
| Sales order import | Allows to import Sales orders from Sales Channel to CEE. |
| Sales order changes export | Allows to export changes on the Sales order to a Sales Channel. |
| Time delay for sales order import | You can set the time delay after which the sales order will be imported to a CEE. |
| Customer texts in sales order header | Allows to place customer text in sales order header. |
| Direct debit support (CFE) | Allows payment format of direct debit. |
Supplementary features
This chapter provides an overview of all OXID-specific features that are not part of the core Multi-channel sales framework.
Multilingual support
The OXID adapter offers full support for multi-language (NLS) attributes. In order to properly exchange the multi-language attributes between the systems, it is necessary to configure the Locale settings of the adapter. The settings can be found in application Sales channels, tab OXID, group Locale and comprise of following fields:
- Default language
- The default language that corresponds to OXID language with ID=0, the value is always fixed to the content language of the CEE user.
- Additional languages
- User-defined mapping between languages in CEE and OXID
Table below contains an example configuration of languages in the OXID adapter. Default language is set to DE. There are also two additional languages defined – EN and PL.
In the provided example, the source attribute contains text in four languages (DE, EN, PL, CZ), however only texts in languages DE, EN and PL are transferred (marked in green). Texts in languages CZ and IT are not transferred because there is no matching additional language in the OXID adapter settings (marked in red).
In case where the source attribute is single-language and target attribute is multi-language, the text is transferred only in the default language.
For more information regarding the language configuration, see document Extension: Sales channels/OXID adapter.
Country-based partner templates
With the OXID adapter it is possible to specify what partner templates should be used for importing customers from different countries. The templates can be specified using application OXID partner template assignments. These templates have higher priority than the default templates found in application Sales channels.
For more information about the application, see document OXID partner template assignments.
Transfer of vouchers
The OXID adapter provides support for the function Transfer vouchers which can be enabled in the identification pane of the Sales channels application.
With the function enabled, the OXID adapter will export all voucher PDF files generated in the CEE during the processing of sales channel orders. This applies to following vouchers:
- order confirmation,
- customer invoice,
- shipping order,
- customer return.
The PDF files are exported during the batch application Export sales order changes and stored in the webshop. Each file can be found in the Downloads section in the details of the associated order. The customer can download the file from the frontend when viewing the details of his order.
Extension: Item view Base
The extension of Items application in the Base view provides a new tab with fields that are specific for the Multi-Channel Sales framework and the OXID adapter. The extension allows to maintain the OXID-specific attributes of the item.
For more information about the application, see document Extension: Item view Base/OXID.
Customizing
The OXID adapter function allows to activate or deactivate the OXID adapter App on the OLTP database. If the function is deactivated, it is not possible to define new sales channels using the OXID adapter.