Overview:
- What is a PIM solution?
- inriver ecosystem
- inriver - under the hood
- inriver API configuration and access
- Integrating Umbraco CMS and inriver
But first …
What is a PIM solution?
Product information in the form of catalogs, with their distinct history, has always been an integral part of the shopping experience, helping people to analyze and make buying decisions easier.
The idea of Product Information Management (PIM) emerged in the early 90s, when companies relied heavily on printed catalogs for selling their products. With the emergence of the internet, every industry underwent a paradigm shift - products were not available only physically in shops or other merchandising areas, they started being bought and sold online. And like a snowball effect, as it started going downhill, it gained more mass, surface and picked up momentum. Paraphrasing this, once it gained traction … the concept of Product Information Management came into being, satisfying the need of a centralized repository that provided a single view of information. Soon it became obvious that managing product information effectively is pivotal to multiple channel marketing and omnichannel selling.
So when you think of old catalogs of products and services this image might pop up in your head:
PIM systems let users store, enrich and manage complex product information. PIM tools centralize product-related data, streamlining the process of updating and managing accurate information throughout multiple sales and marketing channels.
The popularity of PIM systems is growing rapidly because of the strong growth in sales and increasing levels of professionalism in e-commerce. A PIM system helps retailers, wholesalers and manufacturers control their products in a central place. It provides one single point of truth about the product and all its data.
inriver is a Swedish PIM provider with a focus on user interface, providing a cloud-based PIM solution built on Microsoft technologies. All solution data is automatically stored in the cloud, using Microsoft Azure to ensure minimal administration while maintaining high scalability.
inriver is at the forefront of PIM solutions. Purpose built for marketers and secure enough for IT teams, inriver helps companies build better product stories and create great e-commerce experiences. inriver PIM empowers marketers, merchandisers and e-commerce professionals to create personalized, relevant omnichannel content.
If you want to find out more about inriver, feel free to check out some of their use cases or details on the solution they offer.
To help you out choose the best solution for your business, you can use this free ebook, a buyer’s guide, to make your decisions easier.
inriver ecosystem
inriver consists of the following two main components:
1. Control Center: back-end part of the PIM solution, accessed by admins and super users. From here you can easily create, configure and manage system-related functionalities.
2. Web Portal: front-end part of the PIM solution, where users start telling the product story by enriching data.
There are four inriver stages in the PIM process:
To get started with inriver, you will need to fill out this form and someone from inriver will help choose the best solution and set up your environment.
inriver - under the hood
The most fundamental concept of inriver is the Elastic Data Model - an organization of data into Entities and links between them. If we break down the naming, we can distinguish between model and data, where the model is the way of structuring data, and the data is the actual content. Technically, an Elastic Data Model is a database representation of a set of predefined building blocks.
All communication with the database is done through the inriver server, which secures the model’s integrity and data. The server supports various APIs by which you can provide the end-user with a customized enrichment experience based on the data model.
An Entity is the main information unit in inriver. When you create your elastic data model, you organize the data in different types of entities and define relations (links) between them. In the core inriver elastic data model, the three most common types of entities are Product, Item, and Resource.
Another powerful tool to help the enrichment process is the Query Editor, that can be used to search, create work areas and tasks, and other tasks in the web portal.
You can find all the necessary documentation here and if you want to start modeling you can use this basic model which will be imported in the Control Center.
inriver API configuration and access
Communication with inriver is managed through their REST API, by including the API key with the header: X-InRiver-APIKey.
To retrieve your API key and the API instance of your environment, you need to go in the Users section of the Control Center and generate your key.
In this section you will be able to view and test the structure of the inriver API using the Swagger documentation: https://[API_instance].productmarketingcloud.com/swagger
The Umbraco CMS integration uses the following resources from inriver:
- api/v1.0.0/model/entitytypes - get the list of entity types and their fields. This is used when you set up the product picker data type, pick the entity type you want to query entities for, and the fields that will be displayed in the property editor and the rendering component.
- api/v1.0.0/query - minimal implementation of the Query Editor detailed above, that is used to retrieve the entities of a specific type.
This means that this Query Editor search:
translates into this JSON request body:
- api/v1.0.1/entities:fetchdata - retrieve entity summary and field values for an array of entity IDs.
One important observation is that for fetching the data, I am using a patch version of the API, released recently, that reduces the number of requests required to retrieve the data for a set of entities.
Query endpoint returns an array of entity IDs, which we use for fetching the data. With patch version 1.0.1 this is achieved in one go, whereas version v1.0.0 returns an array of entity IDs. Using this array subsequent requests had to be made for each ID to retrieve the data.
If you want to compare versions of the Query method use this Swagger representation: https://apieuw.productmarketingcloud.com/swagger/ui/index#/Query
Integrating Umbraco CMS and inriver
Installation and Configuration
To start using the current integration you would first need to install the latest version of the NuGet package.
With the package installed, you will have access to a custom product picker that can be used as a property editor for content, a value converter providing a strongly typed model for rendering and a sample rendering component for the selected product.
To properly configure the inriver connector, the following settings need to be added to your website (the API instance and key can be found using the specifications of the previous section of this blog post):
- API instance
- API key
Property Editor set up
A new data type to define the configuration of the property editor needs to be created.
If you’re not familiar with Umbraco data types, this resource comes to your aid.
You just need to look for the inriver property editor:
If your configuration is not valid, an error message will be displayed:
Otherwise, you will be able to toggle between the inriver entity types of your environment and pick which columns you want displayed.
The property editor configuration is in direct correlation with these sections of the entity from the Control Center:
You select the entity type you want to fetch data for (Product in this case) and you get the list of fields and the linked entities for the selected type (the items under Includes section, our Outbound objects as they can be retrieved from the rendering view model).
Add your property editor to the content type and you are all set to pick products from inriver.
Two noticeable points can be observed:
1. Multicultural support - you can have your model with multiple languages. Therefore the values of the fields can have a different structure:
-
- A string value, if the field is using a single language.
- A dictionary with values for each language filled in the inriver Control Center.
This use case is handled with two properties of FieldValue object: ValueDictionary will pick the deserialized Value and build a dictionary, otherwise will return a null value; Display renders a friendly string value to UI depending on the structure of the field.
2. Columns duplication
Your inriver entity has two sections we use to display data: Display and Fields. You can assign which fields are used for display name and description and pick the other fields to display in the rendering component.
For example, this Task Picker:
Name and description are left unselected.
The property editor will look like this:
In addition, since the Display Name property is a static one, I am also using it for filtering the records. So I would highly recommend you take advantage of this.
We have also included a rendering component with the package, but feel free to extend it to one of your own, that is best suited for your inriver Elastic Data Model, the view model contains the entire data payload for the selected product.
Conclusions
With the last two integrations we have released, Algolia and inriver, we have been using the new Umbraco UI library and it’s been a great experience! If you’re interested in seeing how we use it - follow the GitHub link below.
Please follow along with us as we explore new ground in our initiative to provide the best cDXP solution to the world.
As usual, the integration is open-sourced and available on GitHub, your input and contributions are welcome.
Inriver integration is available for versions of Umbraco 10.3+.