Tuesday, April 22, 2014

How to connect a PIM system to EPiServer Commerce 7.5 - part 2

In the first part I went through how to setup the inRiver Server and how to connect the Rich Client editor up against it. In this last part, I will describe how you setup the connection between the PIM solution, inRiver Server 5.3, and EPiServer Commerce 7.5. So here is a introduction to a inRiver solution with publishing products into your EPiServer commerce catalog.


There are several ways to create products and items in the PIM solution. You could of course create products manually or by import of an excel sheet.  But normally you would create these products through integration from an ERP system. You could either use inbound connection in inRiver or use a mapping through an integration platform, like BizTalk, from an ERP system to PIM’s service/API.

After the creation of the products, you could enrich them with more and better pictures and extend the content. Then create different channels you want to publish the products too. In this particular solution we want to publish it to the EPiServer commerce platform.

With inRiver Connect you will be able to export products and resources to EPiServer Commerce’s catalog. You will do that with an existing EPiServer Adapter. There are adapters for other CMS and software too.

This blog post requires that you already have installed inRiver Server 5.3 and EPiServer Commerce 7.5. If you haven’t installed Commerce or inRiver server yet, you can find an installation guide for both here:

inRiver: http://sveinaandahl.blogspot.no/2014/04/how-to-connect-pim-solution-to.html

Commerce: http://world.episerver.com/Documentation/Items/Installation-Instructions/EPiServer-Commerce/Installation-instructions-EPiServer-75-Commerce/

Before we start with installing inRiver Connect, there are a few administration tools you need to install on the inRiver server.
If you haven’t done it already I recommend you to install Internet Information Services (IIS) on the inRiver server, since you will need this for inRiver Administration, inRiver WebClient and inRiver Web Media Browser. Also install Microsoft .NET Framework 4.0 or 4.5 if running Windows 2012 Server.

Install Administration Web

The installation procedure is straight forward. Run installation file “Setup inRiver Rich Client.exe”.  Proceed forward by clicking "Next" until the installation is finished.

You can go to this URL http://localhost:80/Server/Default.aspx after you finished the installation. You can change the localhost with a DNS name or machine name, if you configurate it in IIS.
This is how it will look after you got it up:


The most important with the administration web for this scenario is the inRiver Connect tab, but we will come back to that.

Install Model tools

Model tools will be the most important configuration tool when you are going to shape the Meta data model of the PIM. You will also be able to define and create CVL (special drop down menus), types, field set, categories, and languages.

Another reason why you need to install this editor now, is because you need the model tool to get the adapter to work by turning on the integration.

The installation procedure is easy. Run installation file “Setup inRiver Model tools.exe”.  Proceed forward by clicking "Next" until the installation is finished.

After started up Model tools click on the tab “Server settings”. Here you will find INTEGRATION_ENABLED property. Set it to “true” to enable integration to inRiver Connect.

Setup inRiver Connect

Okey, then we are ready to install the inRiver Connect.

The installation procedure is straight forward. Run installation file “Setup inRiver Connect.exe”.  Proceed forward by clicking "Next" until the installation is finished.
Before you start the service make sure you have added an AD user to the service. Use the same AD user as you used for inRiver server.

After you have installed and finished the configuration, then you can start the service.

Check the trouble shooting for MSMQ in the first blog post, if you got problem with starting the service. (http://sveinaandahl.blogspot.no/2014/04/how-to-connect-pim-solution-to.html)
After you already have installed the Administration web you can navigate to the inRiver Connect or type following URL in the browser: http://localhost:80/Integration/Default.aspx

Install EPiServer Commerce Adapter

There are also some system dll file that are part of the web API installation. You need version 4.0.30506 or newer. You can download it from here: http://www.asp.net/mvc/mvc4 or you can add the Microsoft.AspNet.WebApi Nuget Package.

Installing on inRiver side
Place the following files in the .\Program Files\inRiver AB\inRiver Connect\ OutboundConnectors\ folder :
  • inRiver.EPiServerCommerce.CommerceAdapter.dll
  • inRiver.EPiServerCommerce.MediaPublisher.dll
  • inRiver.EPiServerCommerce.Interfaces.dll
  • System.Net.Http.Formatting.dll     (From the WEB API installation)

Installation on EPiServer side
In the bin folder in your EPiServer site you should copy the following files: 
  •  System.Web.Http.dll     (From the WEB API installation)
  •  System.Web.Http.WebHost.dll   (From the WEB API installation)
  •  System.Net.Http.Formatting.dll   (From the WEB API installation)
  •  inRiver.EPiServerCommerce.Import.dll
  •  inRiver.EPiServerCommerce.Interfaces.dll
Add the following app-settings in web.config in your episerver cms site:
  <add key="inRiver.apikey" value="yourApiKey" />   
  <add key="inRiver.RunICatalogImportHandlers" value="true" />   

inRiver.apikey is used to securing the communication, and the same apikey should be placed in the connector settings (look at EPI_APIKEY in the configuration picture below).

inRiver.RunICatalogImportHandlers should be set to true as default, but you have the option to disable your Handlers in runtime by changing this setting to false.

inRiver Adapter settings
Now go back to the web Adminstrator’s connect.

Here you can add a new Connector and a pop up window will give you a set of variables you will need to configure to create the connection to EPiServer Commerce.

Here is a set of important configuration settings to get this connection to work. But you can find more information about each element in the inRiver wiki.

PUBLISH_FOLDER & PUBLISH_FOLDER_RESOURCES - These two configurations field will set the path to where you want to publish the content from inRiver.

NOTE! Both inRiver Connect and EPiServer Commerce user accounts should have access rights to these folders, so add both the AD user you used for the Connect service and “IIS_IUSRS”  that’s used in the commerce site.

CHANNEL_ID - You will find this ID in inRiver Rich Client editor. Open the Channel you want to publish and click Details. Click on the Information icon in the right top view. A pop up view will arrive where you can see the System ID which you can use as the Channel ID.

NOTE! If you are still confused, check out the picture from the from inRiver Rich Client below. The Information icon is in the small red circle.

EPI_CONNECTIONSTRING – You’ll find this name in connectionstring.config in the EPiServer Commerce project.

EPI_APPLICATIONNAME – Is the same name that you installed the Commerce site with in IIS. Default, that’s usually “EPiServerCommerceManager”.

EPI_ENDPOINT_URL – This is the URL to the EPiServer site you installed. Rest of the URL is based on Restapi. So it should look something like this:  http://<EPiServer commerce site>:80/inriverapi/InriverDataImport

EPI_APIKEY - It’s the same Key that was added to the web.config in the EPiServer site.

EPI_RESTTIMEOUT - The timeout in hours for the calls to epi-server REST-API. Default set it to 1. If it doesn't exists you should create it by click on the "Add setting".

Testing of publishing products from the PIM to the Commerce

I would recommend to begin with setting up log files for both side to be able to trap errors.

Log files
If any error occurred in the Connector you would be able to look closer into it in this file:
C:\Program Files\inRiver AB\inRiver Connect\Log\inRiver.Connect.txt

For the import to EPiServer Commerce add the following code to EPiServerLog.config:

   <appender name="inRiverCommerceImportLogger"  
        type="log4net.Appender.FileAppender" >  
     <file value="App_Data\inRiverCommerceImportLogger.log" />  
     <encoding value="utf-8" />  
     <lockingModel type="log4net.Appender.FileAppender+MinimalLock" />  
     <layout type="log4net.Layout.PatternLayout">  
       <conversionPattern value="%date [%thread] %level %logger: %message%n" />  
   <logger name="inRiver" additivity="false">  
     <level value="Debug" />  
     <appender-ref ref="inRiverCommerceImportLogger" />  

Then you can watch information about the import of products to commerce in this file:
\EPiServerCommerce\wwwroot\App_Data\ inRiverCommerceImportLogger.txt

NOTE! All the metadata that exists in inRiver, but are missing in Commerce will be created by the adapter. But keep in mind that fields that exists both places with different types will assert an error. So the best result will be to have an empty Commerce database.

Setting up and publish a Channel in inRiver Rich Client
There are a few pitfalls which you could run into here.  From experience I would recommend to pay close attention to what type of languages, types and field set that are defined. These are things that can come back and haunt you later in the log files. All these elements are editable in the model tools editor. I won’t go into details on how you do that here. It would require another blog post.

First you have to defined the different types you need to create a channel tree including nodes and products, as the big red circle are marking in the picture below. When that’s in place you can publish the channel. If the adapter is setup correct, it would send the whole catalog and resources to EPiServer Commerce catalog. When a Channel is set to publish, all additions and updates will automatically be sent to EPiServer Commerce.

Retrieving published products in EPiServer Commerce
So when you log on to the EPiServer Commerce and go to the catalog you will see the all the updates that comes from inRiver. Really sweet!

If things don't show up as you expect, you should check out the log files.
Last comment
Using a PIM will change the way the editors work.  The editors will work in the rich client editor to create and publish for example products, campaign's, PDF's and so on, in stand of working with the commerce catalog in EPiServer.

That's it.

No comments:

Post a Comment