Blog posts by Marcus Hoffmann

Integrate a CMP workflow step with CMS

Wed, 10 Jul 2024 13:14:39 GMT

As you might know Optimizely has an integration where you can create and edit pages in the CMS directly from the CMP. One of the benefits of this is that the marketing team can use the nice workflows in CMP for both the creation and approval process of new content to the CMS.

But what if you want to use the CMP workflows for work that are not directly related to creating or editing a new page in the CMS? Perhaps you want an editor who works in CMS, but who does not have access to CMP, to update a piece of content or change a setting that is not connected to a specific page.

CMP has a built-in feature for so-called external workflow steps. This means that you can integrate workflow steps in the CMP that are managed completely outside the CMP. For example, there are ready-made connections to Jira and to Adobe CC for this purpose.

This blog post describes how Kunal and I created the corresponding connection between CMP and CMS. The integration is not tied to working on a specific page or block in the CMS that is selected from CMP. The task can include any kind of instructions to update of one or more content items on the web site. The editor in CMS doesn't need to login to CMP to read the instructions or to mark the task as done, this is completely managed in CMS.

Features

The editor in CMP can create a task that will be be managed in CMS
When an external workflow step is triggered it is reflected under "Tasks" in the CMS
The CMS user can update the status of the task in the CMP
With this integration one CMP instance can connect to multiple instances of CMS

Configuration

1. CMP

You need administration permissions to configure the integration in CMP.

1.1 Create an App

Give your app a name ("My-CMS") and input the public url of your website. The callback url can be left empty or set to the same url.

Once you have created an App, you should get a ClientId and a ClientSecret. These will be required for the CMS configuration.

1.2 Register a Webhook

Create a new Webhook and give it a name ("My-CMS-Webhook"). As the Callback url enter the url to to your site and append the webhook: /api/cmp-cms-workflows/webhooks

https://my-site.com/api/cmp-cms-workflows/webhooks

Note: Your CMS instance needs to have a public facing url for the CMP to be able to send Webhook notifications.

For Secret, you can use the value you generated when creating the App or set a new value.

Select the below events. Make sure that you only check the "External Work Management" events.

1.3 Create a Workflow with External Step

Create a new workflow. One of the steps should be an external step. In this example we create a workflow with three steps: "Plan", "CMS Task", "Publish". The "CMS Task" step is created as an external step.

For the configuration of the External Step, click the "Manage External System" button and give your CMS system a unique name ("My-CMS)". This external system name will be needed when configuring the plugin on the CMS side.

Then select your external system in the "Select external system" dropdown list.

2. CMS

Install the nuget package. The nuget can be found here:

https://nuget.optimizely.com/package/?id=Research.CMP.CMS.Workflows

2.1 AppSettings.json

ClientId and ClientSecret corresponds to the values created in the App in CMP. ExternalSystemID is the name you created for your external system (i e "My-CMS" in the example in the screenshot). The WebhookSecret should match the value from the Webhook settings.

"EPiServer": {
"Cms": {
"CmpCmsWorkflow": {
"ClientId": "client-id",
"ClientSecret": "client-secret",
"ExternalSystemId": "external-system-id",
"WebhookSecret": "secret-from-cmp-webhook"
}
}
}

2.2 Startup.cs

In usings add:

using Research.CMP.CMS.Workflows;

In ConfigureServices(...) add:

services.AddCmpCmsWorkflows();

3. Example

3.1 Create task in CMP

Create a new task in CMP and select your new workflow.

Write the instructions of the task you want the CMS editor to perform as the description of the external step. In this case, the task is to update the company address in the footer of the website. Hit the Sync button.

3.2 Perform the task in CMS

The editor in CMS will now see the new task in the task pane.

Click the task to read the instructions. Perform the task, then come back to the task instructions, and update the status from "InProgress" to "Completed" and then click the Publish button.

The step in CMP will now be marked as Completed.

Note: The nuget package will create a new Block type called CMP Task, that are also stored in a folder called CMPTasks.

The integration is available on our nuget feed for installation (CMS 12 required):

https://nuget.optimizely.com/package/?id=Research.CMP.CMS.Workflows

Full source code is also available at Github together with Readme including the details of how to configure the integration.

https://github.com/episerver/Research.CMP.CMS.Workflows/

Do you think this integration should be available as a standard integration? Feel free to comment with any feedback.

Improved headless functionality in Customized Commerce

Thu, 25 May 2023 22:26:25 GMT

Did you know that with the release of Content Delivery Commerce API 3.7 we have massively improved the out of the box headless capabilities of Customized Commerce v14?

Since before the Content Delivery API were already supporting Catalog data, enabling you to fetch products using our Rest API. We also supported some of the basic commerce operations such getting markets, prices etc.

When it comes to Rest APIs for Customized Commerce, we also had the Service API since before. This API supports all commerce related features like getting products, customers, creating carts and orders etc. But the intention of this API is for integration purposes, even if it could be used for headless scenarios.
https://docs.developers.optimizely.com/customized-commerce/v1.3.0-service-api-developer-guide/docs

Feedback has been clear from you partners for a long time, and we understand your needs and where the market and trends are going. Today we need to be able to serve not only web, but also other channels, such as mobile apps. Also, the majority of new ecommerce sites on our platform are using Javascript frameworks, such as React, for their frontend. But you as a partner always needed to wrap much of our .Net APIs in your own Rest APIs for full ecommerce support.

The newly released Content Delivery Commerce API now adds all Commerce related headless APIs you need. Easy to use since it extends the the Content Delivery APIs we already got, and you already are familiar with.
https://nuget.optimizely.com/package/?id=EPiServer.ContentDeliveryApi.Commerce

API overview

Carts – create, modify, fetc, convert to purchase order
Customers – create, update, set password etc
Inventory – get status per SKU
Markets – get markets with all their settings such as languages, currencies, payments etc
Payments – fetch payment methods, assign to carts, process payments etc
Pricing – get different price options for a SKU
Warehouse – get available warehouses
Orders – search orders, update orders etc

Installation and configuration

1. Install the nuget package from:
https://nuget.optimizely.com/package/?id=EPiServer.ContentDeliveryApi.Commerce

2. Add the API configuration to your startup.cs:
You need to set services.AddCommerceApi<SiteUser>(...) and services.AddOpenIDConnect<SiteUser>(...).
Refer to Foundation code for example implementation (yes, the API is already installed in Foundation):
https://github.com/episerver/Foundation/blob/main/src/Foundation/Startup.cs

Test using Postman

Let's see this in action using Postman. We will use the Cart API in our demo together with the existing APIs for login and fetching a variant/SKU.

The scenario is to login as a customer
Find a product (SKU)
Add it to cart
And then convert the cart to a purchase order

API reference:

You can find the v3 API reference here:
https://docs.developers.optimizely.com/content-management-system/v1.5.0-content-delivery-api/reference/content-delivery-class-libraries-and-apis

1. Login and create token:

POST: https://{{siteurl}}/api/episerver/connect/token/
(See https://docs.developers.optimizely.com/content-management-system/v1.5.0-content-delivery-api/docs/api-authentication)
Body: grant_type, client_id, username, password
Response: access_token

2. Get variant to add to cart

To add a variant to cart you need the Guid for the variant/SKU.

GET: https://{{siteurl}}/api/episerver/v3.0/search/content/{{searchterm}}
(See https://docs.developers.optimizely.com/content-management-system/v1.5.0-content-delivery-api/docs/content-delivery-api-and-commerce)
Header: Authorization with value “Bearer <access_token>”
Response: The variant as Json

In this example we use the ID of first Variant/SKU of the Jodphur boot (50__CatalogContent), which is available in the Mosey Fashion Foundation site.
We get the Guid "8709E541-11F6-40D5-B488-800B961A1197" back.

3. Create cart with line item

When updating a cart, the full cart needs to be posted. In a future release we will hopefully be able to update just a single line item.
POST: https://{{siteurl}}/api/episerver/v3.0/me/carts
The /me/carts/ endpoint will create a cart for myself.
(See https://docs.developers.optimizely.com/content-management-system/v1.5.0-content-delivery-api/reference/cartapi_mepostby)
Header: Authorization with value “Bearer <access_token>”
Body: Cart Json, see image and code below. Name, market, currency and shippingMethodId are mandatory to create a cart, but to create an order from it we also need a shipment with a lineitem.
Response: Our new cart created

You now have a cart with ID 9 above.

Cart Json to post:
The contentId is from the Jodphur Boot and shippingMethodId is from the US standard shipping. Code belongs to the Jodphur Boot SKU as well.

{ 
    name: "Default", market: "US", currency: "USD", 
    
    "shipments": [
    {
        "lineItems": [
        {
          "quantity": 1,
          "code": "SKU-39813617",
          "contentId": "8709E541-11F6-40D5-B488-800B961A1197",
          "placedPrice": 100
        }
      ],
      "shippingMethodId": "72457670-c12d-4270-9b31-1ad06743b7c0"
    }
  ]
}

You can now find the cart in Order Management / CSR UI:

The shippingMethod used for the cart:

3b. Get cart

When you want to fetch this cart again for display or to modify. Set the cartid in the url.
GET: https://{{siteurl}}/api/episerver/v3.0/me/carts/9
(See https://docs.developers.optimizely.com/content-management-system/v1.5.0-content-delivery-api/reference/cartapi_megetbycartid)
Header: Authorization with value “Bearer <access_token>”
Response: The cart as Json

4. Convert cart to order

You now have a cart with ID 9, this can now be converted to a Purchase Order.
Set the cartId in the url.
POST: https://{{siteurl}}/api/episerver/v3.0/me/carts/9/converttoorder
(See https://docs.developers.optimizely.com/content-management-system/v1.5.0-content-delivery-api/reference/cartapi_meconverttoorderbycartid)
Header: Authorization with value “Bearer <access_token>”
Response: Our new order created

You now have a Purchase order with order number PO9122.

Summary

This was a short intro to the REST Cart API for Customized Commerce. Hope you found it useful and that it gives you some input and ideas of also how to use the other new APIs available.

Feedback?

Please leave a comment, or feel free to post any feedback and suggestions of improvements in our feedback portal:
https://feedback.optimizely.com/?project=COM

Get started with Episerver Perform for personalized product recommendations

Wed, 08 Nov 2017 12:12:02 GMT

This year, Episerver has released a new suite of personalization products combining machine learning, artificial intelligence, and statistical analysis. The suite includes Episerver Perform, Episerver Reach, Episerver Advance (beta out Q1 2018), Episerver Insight (beta out now) and Personalized Find. All of them are SaaS services.

Personalization has been around a long time in Episerver based on visitor groups. Now the personalization is brought to the individual level. As a visitor to an e-commerce site, you now get automatic product recommendations based on behaviour. This part of our new Personalization suite is called Episerver Perform and is covered in this blog post.

The product recommendations are based on machine learning and behavioural data. Reports today show that visitors want personalization as part of their shopping experience, and that this in turn increases the revenue of the site.

Create an account and get on-boarded

First of all, as a partner you can email personalization@episerver.com to get a free demo/test account. Pricing for Episerver Perform is based on traffic, just as our DXC Service, so you only pay for what you need. For a quote contact your partner or customer manager at Episerver.

There is an on-boarding process included before the implementation takes start where Episerver together with you review your site and set up strategies for the recommendations. Our team have deep knowledge of how to setup strategies based on your goals.

How does it work?

The personalization process can be described in three parts:

1. Capture - data is submitted to Episerver Perform by sending product data as well as behaviour data such as clicks, carts, orders

2. Analyse - our algorithms analyse product data and customer profiles

3. Visualize - relevant recommendations are sent to the right visitors

Installation and setup

There are different ways to integrate Episerver Perform on the site. If you are running Episerver Commerce v11.3 or later there is a native integration supported by adding a nuget package to the site. This gives many advantages and is fast to get started with as the basic job is already done.

If you use an older version of Episerver Commerce, there is a Javascript API and a server-based API to use, but requires more work than the native API. Below will focus on the native integration (a native version of the Javascript API will also be released).

Get the nuget packages from here:
http://nuget.episerver.com/en/?search=EPiServer.Personalization.Commerce

Note: the package was earlier called "EPiServer.Recommendations.Commerce" in the beta version, supported from Commerce v10.4. If you already are using this version you need to update to the new version. See Gustavs blog post for more details regarding the new nuget packages and their updates.
https://world.episerver.com/blogs/the-episerver-personalization-blog/dates/2017/11/new-nuget-packages-for-our-episerver-personalization-suite/

The package will add a couple of appsettings, where you need to configure your account details such as site url and security token.
http://world.episerver.com/documentation/developer-guides/commerce/personalization/recommendations/#Installingandconfiguring

It also creates the scheduled job which will export the product data from Episerver Commerce to Episerver Perform. If you want to customize the export, this is also possible using the new nuget package.
http://world.episerver.com/documentation/developer-guides/commerce/personalization/customizing-exported-product-information/

Start tracking

Then you need to add the recommendations to your templates and start tracking visitor behaviour and actions such as pages visited, adding to cart, creating orders etc.

By default, Episerver Perform comes with tracking types and widgets for the Home, Product, Search, Category, and Basket pages. Tracking types describe the various actions that visitors can track (more tracking types are available and can be added to the account).

Widgets describe how recommendations should be displayed. For the various recommendations, the on-boarding process sets out the strategies that apply to each widget. Usually you are working with different strategies on the different pages.

Strategies can for example for the Home page (Start page) be targeted on abandoned or visited products or cross sells on earlier orders. On the Category pages recommendations could for example be items linked to browsing in category or emerging and bestseller products in category. All strategies are based on a set of different algorithms built in to Episerver Perform.

On the Product page, there are two widgets included in the standard package. Strategies for the Product page are often setup as matching or alternative products. For a fashion site, it could also be popular cross sells. On the Basket or Checkout page recommendations are often setup as items linked to basket items or items of lower value to push the customer over the limit for free shipping.

Based on the strategies given the recommendation engine will give relevant suggestions for all visitors based on their individual behaviour!

As described above, the exact strategies are defined per site as part of the on-boarding process. The strategies can then be changed or updated as time goes on.

Tracking can be done both by adding a tracking attribute to the controller actions and by calling the tracking service directly. Tracking of specific actions needs to be done by calling the tracking service, for example adding to cart, or creating an order. Tracking of browsing a category or a product is easiest achieved by just adding the tracking attribute to the controller.

See examples for more details:
http://world.episerver.com/documentation/developer-guides/commerce/personalization/recommendations/#Trackingandrecommendations

Our demo site Quicksilver found on Github has all this functionality already included to start from.
https://github.com/episerver/Quicksilver

Reports and merchandizing capabilities

From the Personalization Portal (menu integration in CMS to be released soon) you get various types of reports on orders, revenue, products sold and much more based on the recommendations given from Episerver Perform.

There are statistics based on page types (tracking types) and widgets. You can for example see which products are high converting vs low converting based on their traffic, and take different actions based on this.

In Episerver Perform there is also a merchandizing functionality where you can override the recommendations given. For the different widgets, you can create rules that push specific products or products with specific attributes on the different positions of the recommendation widgets.

This is really functionality where Episerver Performs stands out from its competitors! You can combine the strength of the AI with the flexibility to also do merchandizing together with the recommendations.

Besides the Personalization Portal, as a Episerver Personalization customer, you will also get a monthly report with a summary of the result from your personalization.

Send an email to personalization@episerver.com today to start testing Episerver Perform! Or contact Episerver to find out more.

This was an introduction to Episerver Perform. Episerver Reach will give you the same functionality to use in your email marketing. That will be covered in another blog post.