Integrating CMO 2.0 with External Applications

Campaign KPIs

With previous EPiServer CMO versions it is possible to create KPIs for and monitor information related to a specific campaign page, for example, the number of page views or form submits on the page.

Campaign KPIs is a new feature in CMO 2.0. Unlike KPI for page, campaign KPI represents the information about the whole campaign.

Conversion path KPI is an example of campaign KPI, which shows the value of reaching the last page of a conversion path by the users.

Generic KPIs

Briefly generic KPI is another kind of campaign KPI that can be used to integrate CMO and other applications and systems as follows:

• CMO administrator registers external application in CMO settings.
• CMO user creates campaign and adds generic KPI for that application.
• Application updates KPI value using web service.
• KPI is being displayed on campaign report page or on dashboard gadget.

User case for generic KPI

A practical example of use of generic KPIs: Let’s say that you are the owner of a web shop based on EPiServer CMS and Commerce, and of course you use EPiServer CMO.

You spend a lot of money on different kind of ads to promote your shop and products. You have a number of ongoing campaigns, and want to see how effective they are. You want to see how many orders you have in your web shop today or last week.

The number of orders is an example of generic KPI. External application in this case is your web shop system.

Let’s integrate CMO and web shop.

Integrating CMO with External Applications

Administering External Applications

You need administrative permissions to register your web shop as an external application. Go to CMO > Settings > External Applications. Click Add, type the application name and the key. Save your settings.

Adding a Campaign

Add a campaign. Define campaign name, start and end dates, select required pages and go to KPI Settings tab.

Click Add new KPI in General Campaign KPI section to create new generic KPI for external application defined on first step.

Click Add to apply KPI settings. Save and start your campaign.

Using the Generic KPI Service

After CMO deployment you will have new web service on your site available at http://[Your Site URL]/CmoWebServices/GenericKpiService.svc.

Using this service external application can update value of generic KPI by corresponding key.

Service proxy code can be generated in Visual Studio. Turn authorization settings off in location section for CmoWebServices path to make web services public in development environment:

<location path="CmoWebServices">
…
  <system.web>
    <authorization>
     <allow users="*" />
   </authorization>
  </system.web>
…
</location>

Of course you should not make services public in production.

Add service reference in Visual Studio project and point it to generic KPI service URL, define the required namespace and click OK to create service proxy code:

Visual Studio will add corresponding WCF settings in your web.config file. That’s all, now you can update KPIs using code:

GenericKpiServiceClient serviceClient = new GenericKpiServiceClient();
serviceClient.Open();
bool updated = serviceClient.Increase("OrderNumber", 1);
serviceClient.Close();

OrderNumber here is the external application key which we have registered above. This code updates all generic KPIs created for that external application in all active campaigns. In our case it is generic KPI “Number of orders”.

Increase service method returns true if operation is completed successfully and at least one generic KPI for specified key was found and updated, otherwise the increase method will return false.

Monitoring Generic KPI

You can use this code into your web shop project and update KPIs after your customer have submitted new order. Add the CMO KPI Summary gadget for “Number of orders” and monitor your dings on dashboard:

Security configuration

You can make services public on development machine, but of course you need to limit access to CMO web services in production environment.

For CMO web services we use the same approach as for CMS web services. Please look at tech note for EPiServer CMS web services: http://world.episerver.com/Documentation/Items/Tech-Notes/EPiServer-CMS-6/EPiServer-CMS-60/Web-Services/

By default we suggest to use EPiServer basic authentication and provide access to services for defined roles.

Enabling Basic Authentication On Site

Make sure that you have enabled basic authentication HTTP module in section /configuration/system.webServer/modules.

<system.webServer>
  <modules runAllManagedModulesForAllRequests="true">
    <add name="BasicAuthentication" type="EPiServer.Security.BasicAuthentication, EPiServer" preCondition="managedHandler" />
  </modules>
</system.webServer>

Security Settings for CMO Services

Location settings for CMO web services should contain list of allowed roles and enabled basic authentication:

<location path="CmoWebServices">
…
  <episerver.basicAuthentication sendBasicChallenge="true" basicRealm="" />
  <system.web>
    <authorization>
      <allow roles="WebServices,Administrators" />
      <deny users="*" />
    </authorization>
  </system.web>
…
</location>

You also need to enable basic authentication in the client configuration. Update security mode and client credentials type in your binding settings:

<system.serviceModel>
  <bindings>
    <basicHttpBinding>
      <binding name="BasicHttpBinding_IGenericKpiService" … >
        …
        <security mode="TransportCredentialOnly">
          <transport clientCredentialType="Basic" proxyCredentialType="None" realm="" />
          …
        </security>
      </binding>
    </basicHttpBinding>
  </bindings>
  …
</system.serviceModel>

Security Settings in the Client Code

In the client code you need to provide user name and password for authentication:

GenericKpiServiceClient serviceClient = new GenericKpiServiceClient();
serviceClient.ClientCredentials.UserName.UserName = "userName";
serviceClient.ClientCredentials.UserName.Password = "userPassword";
serviceClient.Open();
bool updated = serviceClient.Increase("OrderNumber", 1);
serviceClient.Close();

Do not allow the users for service communication to have any administrative permissions in your application. It’s more safe that way.

More Information

• EPiServer CMO 2.0 WebHelp

Comments