IR and Optimizely <<product-name>> 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 <<product-name>> to pick up and transcribe.

Both IR and <<product-name>> 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.

<<product-name>> will pull Products (including Items and SKUs discussed later), Channel Nodes (category hierarchy in <<product-name>> 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/<<product-name>> customers so that we can use a standardized strategy to map IR data to <<product-name>> 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 <<product-name>>.

**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).

## <<product-name>> entities

**Product**

<<product-name>> 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 <<product-name>>.

**Attribute Value**

This is the actual value of the attributes. Attributes in <<product-name>> 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 <<product-name>> 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 <<product-name>> or IR implementer to create the mappings during implementation.

### Required fields

<table class="TableStyle-Borders" data-cellspacing="0"> <colgroup> <col style="width: 33%" /> <col style="width: 33%" /> <col style="width: 33%" /> </colgroup> <thead> <tr class="header TableStyle-Borders-Head-Header1"> <th class="TableStyle-Borders-HeadE-Regular-Header1"><p>Target Table</p></th> <th class="TableStyle-Borders-HeadE-Regular-Header1"><p>Target Field</p></th> <th class="TableStyle-Borders-HeadD-Regular-Header1"><p>Usage/Notes</p></th> </tr> </thead> <tbody> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>ChannelName</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Name</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>We need to ensure that the channel name in IR matches the website name in <<product-name>> for things to match up - there is a workaround to this shown below by using a website configuration.</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Product</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>ERPNumber</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p><<product-name>> requires a unique field to identify each product and, if this is a purchasable product, then it must also conform to the product identifier within the ERP system - this is often thought of as the SKU.</p> <p>For a product that is not directly orderable (styled product), there still needs to be some unique identifier.</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Product</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>URLSegment/Name</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>These can be the same as the ERP Number or different but are required for all products in <<product-name>></p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Item</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>ERPNumber</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>We will still require a unique field here since items and products will both have the same target table. If the final ERP numbers are represented within the SKUs field, then that will become the ERP number and nothing more specific is required on the item itself.</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Item</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>URLSegment/Name</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>These can be the same as the ERP Number or different but are required for all products in <<product-name>></p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>StyleClass</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Name</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>We will need something to anchor to in order to set up a style class. We will used a mapped field for this instead of the fieldset.</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyB-Regular-Row1"><p>AttributeType</p></td> <td class="TableStyle-Borders-BodyB-Regular-Row1"><p> </p></td> <td class="TableStyle-Borders-BodyA-Regular-Row1"><p>CVLs must be named either the same in the entity or prefixed with the entity name in order to be resolved.</p> <p>For example, if we have a CVL called Color, the field mapped to it in IR must be either Color or ProductColor (or ItemColor) or it cannot be mapped. The XML export does not provide enough detail to map it back to the source data element so this convention-based approach must be used.</p></td> </tr> </tbody> </table>

## 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 <<product-name>> 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 <<product-name>> 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 <<product-name>>. The system will create an entry called <span class="span_2">inRiver Channel EntityId</span> 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 <<product-name>>)

### 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 <<product-name>>. 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

<table class="TableStyle-Borders" data-cellspacing="0"> <colgroup> <col style="width: 33%" /> <col style="width: 33%" /> <col style="width: 33%" /> </colgroup> <thead> <tr class="header TableStyle-Borders-Head-Header1"> <th class="TableStyle-Borders-HeadE-Regular-Header1"><p>Name/Step</p></th> <th class="TableStyle-Borders-HeadE-Regular-Header1"><p>Processors (prefixed with 'InRiver') or Object</p></th> <th class="TableStyle-Borders-HeadD-Regular-Header1"><p>What it does/Notes</p></th> </tr> </thead> <tbody> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Common Vocabulary Refresh</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Pre: LookupInformation</p> <p>WIS:CommonVocabulary</p> <p>Post:CommonVocabulary</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>Reads all CVLs and creates the internal table, creates/updates AttributeTypes, Attribute Values and all translations of them</p> <p>This pulls from files that are masked with *CVLS/*.xml.</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Step 1 - Attribute Types</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>AttributeType</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This job should not be altered.</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Step 2 - Attribute Values</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>AttributeValue</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This job should not be altered</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Step 3 - Translation Dictionary</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>TranslationDictionary</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This job should not be altered</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Product Refresh</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Pre: LookupInformation</p> <p>WIS: Product</p> <p>Post: FieldMap</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This job will populate the style classes, traits, values and create/update the product record for product entities</p> <p>This pulls from files that are masked with *_Product_*.xml</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Style Class</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>StyleClass</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>Pick a product field to use as the name of the style class - if you don't have one, you will likely need to add one.</p> <p>The field map should only need to list the fields that define the style class code/name and description (which can be the same as the name field). The sample set uses a field called <strong>ProductGroup</strong> which may or may not exist in your dataset.</p> <p>The field map is to the object <strong>StyleClass</strong> and is used to create the actual classes</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Product Initializer</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>StyleProductInfo</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>The intent of this step is simply to establish the existence of the parent/styled product in the database and then relate it to the style class it belongs to. The rest of the relationships happen in the Item refresh.</p> <p><strong>Note:</strong> You must populate the <strong>ERPNumber</strong>, <strong>Name</strong> and <strong>URLSegment</strong> from the data. <strong>ProductGroup</strong> and <strong>ProductNumber</strong> are proxies for the fields you would use in your specific implementation of inRiver.</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Product Finalizer</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Product</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This is the step that will fill out all of your information for a product including the basic content. We recommend that you have a short description field specifically available.</p> <p>Only the fields listed in the Columns tab will be pulled over and they must exist in the <strong>ProductFields</strong> section of the XML. Then you can map them to product content, product custom properties or directly to product fields.</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Product Attributes</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Product</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>While this does not need to be a separate step, it is separated out for clarity only.</p> <p>For this to work, you select the product fields you want mapped as attributes - these are limited to <strong>CVL</strong> fields in IR.</p> <p>For each value selected, you set up a <strong>ChildCollection</strong> where the <strong>From</strong> Property is the field from IR and the <strong>ToProperty</strong> is AttributeValues.</p> <p><strong>Note:</strong>These will only map if the attribute types are named specifically the same as the field name or the field name with the entity prepended. The attribute types must already be mapped to one of the categories associated with the product or it also cannot be successfully mapped.</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Item Refresh</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Pre: LookupInformation</p> <p>WIS: StyleClass</p> <p>Post: FieldMap</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This job will create the products for the child products and then update the style traits and values.</p> <p>This pulls from files that are masked with *_Item_*.xml</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Style Trait Refresh</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>StyleTrait</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>The values you must pull out of the Item entity need to be prefixed with 'Variant' to identify the actual style trait being used. For example, <strong>VariantColor</strong> will map to style trait Color.</p> <p>Note that in <<product-name>>, style traits are not the same as attributes - they are similar and may actually be the same values but are used in different ways.</p> <p>The column list only needs to be a list of the variant values to map. <strong>StyleClass</strong> is a "free" column that will map the item to the parent item's style class.</p> <p>The mapping should not be altered - we need the <strong>StyleTrait Name</strong> and <strong>Class</strong> only - description is optional and is typically set to the same as the name.</p> <p>This step will create all of the unique combinations of style traits associated with the style class based on the items sent from IR.</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Style Trait Value Refresh</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>StyleTraitValue</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>The column list here should be the same as for the style trait step.</p> <p>This steps will create the actual valid values within each style trait based on the items sent from IR.</p> <p>The mapping should not be altered.</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Item Refresh</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>StyleProductInfo</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This is a bit more constrained object - not all properties are available to it.</p> <p>This step will create/update the products that are styled children in B2B and set up the associated style trait values to that product. This step must set the <strong>ERPNumber</strong>, <strong>Name</strong> and <strong>URLSegment</strong> fields. The query must contain all of the variant fields.</p> <p>Additional fields like short description or any other <strong>ItemField</strong> would be mapped into this step as well.</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Category Refresh</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Pre: LookupInformation</p> <p>WIS: Channel</p> <p>Post: FieldMap</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This pulls from files that are masked with *_Channel_*.xml</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Channel Refresh</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>WebSiteConfiguration</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>All this step does is establish the <strong>WebsiteConfiguration</strong> entry "inRiver Channel Entity" to implant the unique identity in order to tie the website to the channel. This mapping should not be altered.</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Channel Node Refresh</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Category</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This step creates/updates categories and their hierarchy and assigns products to the categories. It is unlikely this will require much change in the mapping.</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Resource Refresh</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Pre: LookupInformation</p> <p>WIS: Resource</p> <p>Post: FieldMap</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This pulls from files that are masked with *_Resource_*.xml</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Resource Refresh</p></td> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Product</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>This step will embed the path of the resources (images) into the product for <strong>SmallImagePath</strong>, <strong>MediumImagePath</strong>, and <strong>LargeImagePath</strong>. The mapping should not be changed.</p> <p>There is a step parameter called <strong>inRiverResourceLocation</strong> that is used to identify the prefix to the actual name of the file. The default in the job is <strong>/UserFiles/Images/inRiver</strong>.</p> <p>The original images are of any type and the full name is provided in the interface from inRiver, however the smaller images are automatically resized and renamed using configuration within inRiver. To accommodate this we have the <strong>PreviewExtension</strong> and <strong>ThumbnailExtension</strong> parameters that will define the extension with a default of <span class="span_2">jpg</span>.</p> <p>The plug-in will map the Thumbnail image to <strong>SmallImagePath, Preview</strong> image to <strong>MediumImagePath</strong> and Original to <strong>LargeImagePath</strong>.</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyB-Regular-Row1"><p>FileTransfer</p></td> <td class="TableStyle-Borders-BodyB-Regular-Row1"><p>Pre: None</p> <p>WIS: FileUpload</p> <p>Post: None</p></td> <td class="TableStyle-Borders-BodyA-Regular-Row1"><p>This is a special purpose job that is used to physically copy the files from the source location into the target location. The WIS uses a web service to move the images. This is an execution job which uses no steps but has to have at least 1 step in order for the WIS processor to pick it up.</p> <p>The presumption is that the publishing process in inRiver will populate the resource files with the images based on changes made to the entities.</p> <p>The following parameters control the process:</p> <p><strong>SourceDirectory</strong> - the location on the inRiver server where the resources are located</p> <p><strong>SourceMask</strong> - the mask used to define the files to select and send and can include multiple masks separated by a pipe (|)</p> <p><strong>Destination Directory</strong> - the relative location on the B2B server to place the images - default value is images/inriver.</p> <p><strong>DeleteSourceFilesOnCopy</strong> - true or false - once copied up, indicates if the files should be deleted on the IR server</p></td> </tr> </tbody> </table>