Introduction
This document describes exposed APIs for a web service in EPiServer CMO to update
generic KPI values for online campaigns (not A/B testing). The following
campaign KPIs are used in EPiServer CMO:
- Conversion path KPI shows the value of reaching the last page
of a conversion path by the users
- Generic KPI is used in integration with external applications
With EPiServer CMO it is possible to create
KPIs for monitoring information related to a specific campaign page, for
example, the number of page views or form submits on the page. Unlike KPI for
page, campaign KPI represents the information about the whole campaign.
Generic KPIs
Briefly generic KPI can be used to integrate EPiServer CMO
with other applications in the following way:
- The CMO administrator registers
external application in CMO settings.
- The CMO user creates campaign and adds generic
KPI for that application.
- The application updates KPI value using web service.
- The 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: Imagine that you are
the owner of a web shop based on EPiServer CMS and Commerce, and 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.
In this case, the external application is your web shop system to integrate
EPiServer CMO with.
Administering External Applications for Integration
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 and 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 the KPI settings. Save and start your campaign.
Using the Generic KPI Service
After EPiServer 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:
XML
<location path="CmoWebServices">
...
<system.web>
<authorization>
<allow users="*" />
</authorization>
</system.web>
...
</location>
Of course you should not make services public in production.
Add a service reference in Visual Studio project, and point it to generic KPI service URL.
Define the required namespace and click OK to create the service proxy code
as follows:
Visual Studio will add corresponding WCF settings in your web.config file. Now you can update KPIs using the following code:
C#
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 this 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 you use the same approach as for CMS
web services as described in the following tech note:
http://world.episerver.com/Documentation/Items/Tech-Notes/EPiServer-CMS-6/EPiServer-CMS-60/Web-Services/.
Enabling Basic Authentication on the Website
By default you are recommended to use EPiServer basicAuthentication and provide access
to services for defined roles. Make sure that you have enabled basic authentication HTTP module in section
/configuration/system.webServer/modules.
XML
<system.webServer>
<modules runAllManagedModulesForAllRequests="true">
<add name="BasicAuthentication" type="EPiServer.Security.BasicAuthentication, EPiServer" preCondition="managedHandler" />
</modules>
</system.webServer>
Configuring Security Settings for CMO Services
Location settings for CMO web services should
contain a list of allowed roles and enabled basic authentication as follows:
XML
<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 as
follows:
XML
<system.serviceModel>
<bindings>
<basicHttpBinding>
<binding name="BasicHttpBinding_IGenericKpiService" ... >
...
<security mode="TransportCredentialOnly">
<transport clientCredentialType="Basic" proxyCredentialType="None" realm="" />
...
</security>
</binding>
</basicHttpBinding>
</bindings>
...
</system.serviceModel>
Configuring Security Settings in the Client Code
In the client code you need to provide user
name and password for authentication as follows:
C#
GenericKpiServiceClient serviceClient = new GenericKpiServiceClient();
serviceClient.ClientCredentials.UserName.UserName = "userName";
serviceClient.ClientCredentials.UserName.Password = "userPassword";
serviceClient.Open();
bool updated = serviceClient.Increase("OrderNumber", 1);
serviceClient.Close</a>();
Note Do not allow the users for service communication
to have any administrative permissions in your application.
Do you find this information helpful? Please log in to provide feedback.