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.

Architecture

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.
 

Services

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:

 

 .....  
 <appSettings>  
  ....  
  <add key="inRiver.apikey" value="yourApiKey" />   
  <add key="inRiver.RunICatalogImportHandlers" value="true" />   
 </appSettings>  
 ...  

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" />  
     </layout>  
   </appender>    
   <logger name="inRiver" additivity="false">  
     <level value="Debug" />  
     <appender-ref ref="inRiverCommerceImportLogger" />  
   </logger>  

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.

How to connect a PIM solution to EPiServer Commerce 7.5

Product Information Management, in short called PIM, is important for driving consistency product information across digital channels. A PIM solution will make all product information available from a central point in a reliable, meaningful, and timely way to people, processes and applications that rely on it.

There have been written several blog post and information about PIM, but there are very few, if any, with in depth information on how you setup a PIM solution with EPiServer Commerce 7.5. The PIM solution I have used is inRiver 5.3, which have a really nice “out of the box” adapter to EPiServer Commerce.

You can find a nice introduction to PIM here: http://nordicecommerceknowledge.se/PIM--en-viktig-del-i-en-multikanalstrategi/ (only in Swedish)
 

The blog post became quite long, so I have split it up in two. First blog post will contain how to setup InRiver and how to connect the Rich Client Editor to it. I have tried to document some of the pitfalls you may run into.
 

The second blog post will be about inRiver Connect and how you should configure it to be able to publish products to EPiServer Commerce.
 

Architecture

My solution is based on the same infrastructure setup as you see in the figure below. You could of course set it up on one single server, but it’s not recommended in a production environment. It is important to notice that inRiver can’t be setup with several servers in a load balancing environment. This is normally not a problem, but it’s advisable to stack the inRiver server with enough CPU power and memory to handle scaling and cropping of pictures, if you have a lot of channels to support.
 

Let's continue with the details on how to setup the SQL, inRiver server and Rich Client editor.

Necessary requirements when installing of Microsoft SQL

Let’s start with database first. You can install either Microsoft SQL 2012 R2 Server or SQL 2008 R2 Server. Remember to enable Filestream when you install it, since inRiver require it. Both inRiver and EPiServer Commerce requires you to use a full version of SQL, so using Web Edition of SQL Server is not suitable for any part of this solution.

 

If you already got an MS SQL database available, then here is how you enable Filestream. Go to “Sql Server Configuration Manager” and open properties for the SQL server and enable Filestream.

When you have clicked “OK” and then open “SQL Server Management Studio”. Copy following script and execute it:

EXEC sp_configure filestream_access_level, 2

RECONFIGURE

Go

 

Now you can stop and start the SQL Server.

You should now be able to perform a full restore of the database file inriver.bak that follows the install package for inRiver Server.
 

TIPS! http://www.mssqltips.com/sqlservertip/1838/different-ways-to-enable-filestream-feature-of-sql-server-2008/

Couple of notes before continuing
 

Note! SQL Server 2012
If you are running SQL Server 2012 integrated security it will not work "out of the box" like it does in SQL Server 2008, if you are running inRiver Server and SQL server on the same machine. You will then need to assign a specific user.

Note! User Account ID
In this solution it’s recommended to use an Active Directory User, since several servers are involved. If it’s on the same server you can use an administrator user.

Note! IIS on the inRiver server
Recommend 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.

Installation of inRiver Server

Finally ready for installing the inRiver Server.

The installation procedure is very straight forward. Run installation file “Setup inRiver Server 5.3.exe”.  Proceed forward by clicking "Next" until the installation is finished. This will install the program as a service.

After installation, open Windows Explorer and point it to the root directory of your inRiver Server installation and rename inRiver.Server.exe.config.sample to inRiver.Server.exe.config

When you open the file in an editor, modify the text that’s inside the red square with either one of the two lines below the picture depending of which sql you use.

 

Connection string for sql 2008

<add name="inriver" connectionString="Data Source=localhost\INRIVERSERVER;Initial Catalog=inriver_demo;Integrated Security=True;" providerName="System.Data.SqlClient">


<add name="inriverResources" connectionString="Data Source=localhost\INRIVERSERVER;Initial Catalog=inriver_demo;Integrated Security=True;" providerName="System.Data.SqlClient">

Connection string for sql 2012

Create a sql user that has DBO rights in the database first.

<add name="inriver" connectionString="Data Source= localhost\SQLSERVER2012;Initial Catalog=inriver;Integrated Security=SSPI;User ID=dbUserInriver;Password=xxxxxx" providerName="System.Data.SqlClient" />


<add name="inriverResources" connectionString="Data Source= localhost\SQLSERVER2012;Initial Catalog=inriver;Integrated Security=SSPI;User ID=dbUserInriver;Password= xxxxxx;" providerName="System.Data.SqlClient" />

Note that in large installations you can point "inriver" and "inriverResources" into two different instances.

MSMQ

The first pitfall coming up, MSMQ.

Make sure changes to the service Log On properties are made prior to the first start attempt of the service. Else MSMQ queue objects might be created with inappropriate credentials. Check trouble shooting below, if you run into trouble.

Installing MSMQ is easy enough. Go to Server Manager and add click on “Add a feature”, then add and install “Message Queuing Services”.

After installation you can open Computer Management. Under "Services and Applications" you will now have a "Message Queuing". All queues later on will be created under "Private Queues".

Trouble shooting MSMQ

If the MSMQ queue objects are created with inappropriate credentials, you would have to delete the queue. There are 2 ways of doing that.

1. In computer management, go to the security properties of the queue, take ownership through the advanced button, and set permissions to what you want. 
2. Find the queue config file in the system32\msmq\storage\lqs directory and delete the file; the queue name will be inside the file you want. When you restart the MSMQ service, the queue will have disappeared.

Services

Before you start the service make sure you have added an AD user to the Log On for the service.

 

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

 

If any trouble should occur you will be able to read more about the details in the Log. If the service doesn’t start and you don’t get any errors in the log it might be credential error. Then make sure you use the correct AD user and delete the “serverinternallog” instance in Private Queues, before restarting the service.

Testing out inRiver with the Rich Client editor

When the inRiver Server is up and running you can connect to it with the inRiver Rich client editor.
The installation procedure is very straight forward. Run installation file “Setup inRiver Rich Client”.  Proceed forward by clicking "Next" until the installation is finished. If you have installed this on the inRiver Server, you can use the “localhost:8080” to logon to the system. This require ofcourse that you have installed the Rich Client editor on the inRiver Server. 

 

If you want to access the inRiver Server from outside the server you most likely would have to set a new Inbound rule in the inRiver server. You will find that under Server Manager -> Configuration -> Windows Firewall -> Inbound rules. Choose Port and specify 8080.

You could then for example  use  <machinename or DNS: 8080> as the server address to be able to log on. Click on "Test Connection" to check if the connection work, if not, the inbound rule isn't setup correct.

 

 

When everything is in order you should be able to work inside the Rich Client editor.

 

Next blog post will go more into depth on how you setup a connect from the PIM solution to EPiServer Commerce:  http://sveinaandahl.blogspot.no/2014/04/how-to-connect-pim-system-to-episerver.html