inRiver (IR) and Configured Commerce integration strategy

IR and Optimizely Configured Commerce have worked together to understand the data structures within IR and have arrived at the strategy for integration which will leverage the out of the box XML Schema exports provided by IR to create a data feed for Configured Commerce to pick up and transcribe.

Both IR and Configured Commerce have ETL mapping tools and the ability to write code specific to a connector (IR) or plug-in. Optimizely has taken on the responsibility to write IR-specific plug-ins and leveraging the standard schema export from IR.

Configured Commerce will pull Products (including Items and SKUs discussed later), Channel Nodes (category hierarchy in Configured Commerce parlance), and Resources (digital assets) as part of the initial, standard integration.

This document will address some schema standards we wish to impose for any IR/Configured Commerce customers so that we can use a standardized strategy to map IR data to Configured Commerce structures.

IR entity setup

We request that the following entities be required and statically named.

Channel

This is the typical publication channel that would be established for inRiver. It can represent print or other recipient. Each targeted website that would have a catalog hierarchy should be set up as a separate channel.

Channel Node

This entity represents a hierarchical representation of products within categories for a given channel/web site. This will be used to create the category hierarchy in Configured Commerce.

Products

We will expect a Product entity to be established that can act as the end item to be created or as a placeholder for a product that is merchandised but has variants. If there are no variants, the product record itself can be set up with the SKU number or a singular item can be set up that holds the SKU number.

Items

These are variants for the product. It will hold information specific to the variant (that is color images or specific attributes). Attribution will mostly come from the Product entity. Within Items, we will have an optional XML field called SKUs which can hold additional information about sub-level skus with their variant-specific data.

General Reasoning

inRiver will want entities that represent saleable items that capture relevant merchandising information. For example, if we have a specific shirt - we merchandise all the information about fabric, care instructions, and so on at the Product entity. We create Items for the different colors but these are not specific SKUs. At the SKU level, we have the actual sku and the size so that, together, the shirt is ultimately defined by the Product (shirt), Item (color) and SKU (size).

Configured Commerce entities

Product

Configured Commerce has a product table that can hold generic products (the same as the IR product), specific SKU's tied to a product (Items), services, add-ons, and so on. This is the master holding entity for anything that is sold or merchandised on the platform. Products that have children are termed "Styled Products".

Style Class

This entity represents a type of product with a predefined set of attributes that define it for purchasing purposes (not merchandising purposes). For example, a T-Shirt may always have a size and color but nothing else. Any number of styled products can use the same style class. This is not unlike the fieldset construct in IR.

Style Trait

This entity holds the specific traits within a style class.

Style Trait Value

These are the individual values available for the trait associated to the class.

Attribute Type

This is a more generic set of attributes and is used for product comparisons and faceting. Attribute Types are global in nature and can be assigned by category. Products then are assigned specific values for any attribute type that is associated with all of the categories the product is assigned to. CVLs in IR will be mapped to attributes in Configured Commerce.

Attribute Value

This is the actual value of the attributes. Attributes in Configured Commerce look a lot like CVLs in IR.

General Note

Currently, there is a distinction between Style Trait Values and Attribute Values even though they could be repeated within a single product. Style Traits are used to narrow down the selections of a product to the orderable SKU, while attributes are used for merchandising, searching, and comparing.

Field mapping

Rather than impose any specific naming conventions (other than entity naming conventions), there are some fields that Configured Commerce will require in order for the integration to be effective. The tables below will describe these requirements. The assumption is that these data will be provided in the schema and it will be up to the Configured Commerce or IR implementer to create the mappings during implementation.

Required fields

How it is put together

We have established a series of predefined integration jobs and plug-ins to handle the integration. Each of these will be explained below along with supporting technical information regarding settings.

Because we wanted to keep this integration as standard as possible, we are using the out of the box inRiver.Connectors.Schema.Output.Files connector with a single file per entity export from inRiver. Developers can further enhance or extend this as desired - the provided code will definitely allow for a solid and deep integration but may not accommodate every circumstance given the highly configurable nature of a product information management solution.

Keep in mind that in inRiver, there are Product and Item entities where in Configured Commerce they are all considered products and if there is an item related to a product, those are considered styled children. The steps involved in the integration are laid out intentionally to optimally fill out all of these relationships in a particular order to complete the structures.

Warnings/Known Issues

1. The system does not handle multi-value fields out of the box
2. The system does not handle locale strings - most data fields in Configured Commerce are not enabled for multi-language support. The system will pull out the entry that matches the default language identified for the site. This means that we could import multi-language to language-specific sites but not to multiple languages on the same site.
3. While the system will create the entire category structure from the channel node feed from IR, the attributes associated with those channels is not mapped by the integration. In order for attributes to be assigned to products, the product must be assigned to a category that has those attributes assigned to it. Nothing in the integration will create that particular relationship. We suggest that the users set up the taxonomy in IR, import just the taxonomy and CVLs and then manually map the attributes to the categories before importing products and items - that way the attributes for the products will have the ability to be mapped in.
4. As data is changed in IR, it automatically creates XML files in the export directory. Oftentimes it will create multiple versions of the same data. The system is built to pick up these files in time-sequenced order so that the most current version will be transmitted. If an entire set of files is missing, however, the integration job will register that job as CompletedWithWarnings and you will notice in the job log that there will be warnings such as "No files found matching 'xxxxxxx' - this is a standard feature of flat file imports.
5. The FileUpload job is an Execution job but it still must have at least 1 step as a dummy step in order to trigger the integration processor.
6. If an item is modified after initial load, it generates its XML file as 'Updated' vs. 'New' and does not include the links to the parent - this breaks the integration for that item. We are working with inriver to have them fix that behavior.

Technical extensions

Other than the integration plug-ins defined below, the following are some special constructs used to support the integration.

• WebsiteConfiguration. There is only one special configuration entry that is generated automatically provided that the channel name in IR matches the website name in Configured Commerce. The system will create an entry called inRiver Channel EntityId which contains the IR internal entity id # which is a simple identity/integer field. This is used in different places in the system to tie data together from the
• InRiverCommonVocabulary table. Since CVL-linked data in products and items don't resolve to their value but only send up their entity id, we are persisting that data directly on the server in a special table built by the custom post processor.

Integration jobs and plugIns

Things to understand

• In general, there are a number of fields that come back from the integration processors that are "free". There are other fields, primary the ones in the Product and Item entities that only come back for mapping if they are included in the select statement. All fields within the XML structure "ProductFields" or "ItemFields" are available in this manner.
• The UniqueId field is a special field and is assigned and should be mapped to the ERPNumber field (natural key in Configured Commerce)

PlugIns

Integration jobs

Below are the details of the various jobs that we created to help enable and streamline a given integration from InRiver to Configured Commerce. These are starting points for the most part and will need to be adjusted to meet any client's specific needs.

We build these jobs where possible to implement the standard field mapper so that the implementation consultant would be able to add new fields and put them where they way when integration with IR.

Some of the integrations have some fields available as "free fields" to use that do not need to be included in the selection column list. These are as follows:

• Channel
• UniqueIdentifier
• ChannelNode
• UniqueIdentifier
• CategoryName
• ProductEntityId
• Item
• UniqueIdentifier
• Active
• ParentProductId
• Product
• UniqueIdentifier
• Active
• Resource
• UniqueIdentifier
• SmallImagePath
• MediumImagePath
• LargeImagePath
• StyleClass
• StyleClass
• StyleTrait
• StyleTraitValue

Job definitions