Business Analytics API

The Business Analytics API consists of several static methods arranged into two groups:

those that save events to the database

those that retrieve the event data from the database for use in reports

The following illustration depicts saving event data to the database.

This illustration depicts retrieving that data into reports.

Note: The demonstration code in this document uses C# syntax.

Using the API

The API's namespace is Ektron.Cms.Framework.Analytics.BusinessAnalytics.

Saving Event Data

To save events, use the static class EventLogger, which exposes the following methods.

IAnalyticsEventData CreateAnalyticsEventData()

void Log(IAnalyticsEventData eventObject)

void Log(string eventName)

void Log(string eventName, string xml)

void Log(string eventName, string xml, int count)

The EventLogger class is illustrated below.

Saving an Event

As long as an event (myEvent) has been registered in the system, you can store an event like this:

using Ektron.Cms.Framework.Analytics.BusinessAnalytics;

…

EventLogger.Log(“myEvent”);

This code saves the event data with default values.

As shown above, the Log method has several overloaded versions. Each provides a different amount of control over the information saved to the database. The following table lists the Log method's parameters.

Parameter	Type	Description
eventName	string	A name that uniquely identifies the event. This name must be registered and enabled in the database for it to be recorded.
XML	string	This parameter is purely for customization. By default, its value is null. The API stack passes the string to the database, where the appropriate stored procedure can use it. For example, it can store additional values that are not part of the current event-object
count	int	Allows increments other than the default value of one. For example, you may want a specific event to increment the event counter by 5.

In addition to the parameters listed above, you can set other values by referencing the event object that carries the information to the database. A call to CreateAnalyticsEventData returns this object, and can be used as follows:

IAnalyticsEventData eventObject = CreateAnalyticsEventData();

Through the interface IAnalyticsEventData, the object provides the following additional parameters, which allow more control over what information is saved with the event.

Parameter	Type	Description
ObjectId	long	For a content related event, ObjectId should be set to a Content ID.
LanguageId	int	The content object's Language ID. If that is not available, the current request's Language ID.
SiteId	long	The current request's Site ID Note: A value of -1 means this value has not been set, and will be updated appropriately at a lower level.
UserId	long	The current request's User ID (if logged in)
VisitorId	string	The current request's Visitor ID (if not logged in)
EventDate	DateTime	Defaults to current date and time

Reading Event Data

Use the static class EventReporter to retrieve events stored in the database. This class exposes the following methods.

IList<string> GetReportNameList() - see GetReportNameList Method

IAnalyticsQueryRequest CreateQueryRequest() - see CreateQueryRequest Method

IContentQueryRequest CreateContentQueryRequest() - see CreateContentQueryRequest Method

IList<IAnalyticsEventItem> GetList(IAnalyticsQueryRequest queryRequest) - See GetList Method

IList<IContentEventItem> GetList(IContentQueryRequest queryRequest)- See GetList Method

void UpdateReportData(String eventName, DateTime eventDate) - see UpdateReportData Method

The Eventreporter classes are illustrated below.

GetReportNameList Method

Use the GetReportNameList method to obtain a list of recognized (e.g., registered) report names. You can extend this list by adding custom event types and their corresponding stored procedure handlers.

For example, to obtain a list of the allowed report names, use the following code.

using Ektron.Cms.Framework.Analytics.BusinessAnalytics;

...

IList<String> names = EventReporter.GetReportNameList();

CreateQueryRequest Method

Use the CreateQueryRequest method to specify an event data report of the base-level type. The method returns an object that implements the interface IAnalyticsQueryRequest, which has the following parameters.

Parameter	Description	Type
ReportName	Uniquely specifies the report, which is registered and corresponds to one or more stored procedures which, when run, generate the requested data.	string
SiteId	The Site ID of the data being returned.	long
UserId	The User ID of the data being returned.	long
EventStartDate	If desired, use to determine the earliest date for which report data is returned. By default, data from the earliest date is returned.	DateTime
EventEndDate	If desired, use to determine the latest date for which report data is returned. By default, data through the most recent date is returned.	DateTime
PagingInfo	Page size and number allow you to display a small portion of the report at a time. By setting page size and number, the report data is reduced, and performance will improve. Conversely, performance degrades as page size (RecordsPerPage) increases, especially if the amount of stored data is large.	Ektron.Cms.PagingInfo This type has the following fields: CurrentPage EndRow RecordsPerPage StartRow TotalPages TotalRecords
OrderByDirection	Descending or Ascending	EkEnumeration.OrderByDirection
XML	This parameter is purely for customization. By default, its value is null. While saving event data, the API stack passes the string to the database, where the appropriate stored procedure can use it. For example, it can store additional values that are not part of the current event-object. Within the CreateQueryRequest method, this parameter can returns that string.	string

CreateContentQueryRequest Method

Use the CreateContentQueryRequest method to specify a report of event data that is related to content. It returns an object that implements the interface IContentQueryRequest which, in addition to those provided by interface IAnalyticsQueryRequest (see CreateQueryRequest Method) has the following parameters.

Note: You can use either the FolderID or the TaxonomyID parameter but not both. Also, you can only use the IncludeChild parameter related to the selected parent parameter.

Parameter	Type	Description
LanguageId	int	The Language ID of the content that the report returns.
FolderId	long	The folder of the content being returned. All content in the folder is returned. It defaults to that of the current HTTP request.
IncludeChildFolders	boolean	Determines whether the report includes children of the folder specified in the FolderID parameter.
TaxonomyId	long	The taxonomy category of the content being returned. All content to which the category is applied the folder is returned. It defaults to that of the current HTTP request.
IncludeChildTaxonomy	boolean	Determines whether the report includes children of the folder specified in the FolderID parameter.

GetList Method

There are two versions of the GetList method.

One version takes an IAnalyticsQueryRequest object, and returns a list of objects that implement IAnalyticsEventItem. That version has the following parameters.

Parameter	Type	Description
ID	long	The object Id s supplied when the related events were saved.
XML	string	This parameter is purely for customization. By default, its value is null. While saving event data, the API stack passes the string to the database, where the appropriate stored procedure can use it. It can store additional values that are not part of the current event-object.

Parameter

Type

Description

long

The object Id s supplied when the related events were saved.

XML

string

This parameter is purely for customization. By default, its value is null.

While saving event data, the API stack passes the string to the database, where the appropriate stored procedure can use it. It can store additional values that are not part of the current event-object.

The other version of the GetList method takes an IContentQueryRequest object and returns a list of objects that implement the interface IContentEventItem . That provides the following parameters in addition to those of IAnalyticsEventItem (shown above).

Parameter	Type	Description
LanguageId	int	The Language ID of the content that the report returns.
Quicklink	string	The object's URL.
Title	string	Determines whether the report includes children of the folder specified in the FolderID parameter.
Teaser	string	The content summary. See Also: Working with Content Summary
Status	char	The content's status. See Also: Content Statuses
FolderID	long	The FolderID of the content being reported.
Count	int	The count of the object being reported. For example, if you are retrieving the most frequently emailed content item, the count is the number of times it was emailed. The count and average values may be used individually or together, depending on the report. For example, the rating report returns both the average (rating) and the count (the number of ratings), while the commented report uses only the count.
Average	decimal	The a numerical value divided by the count. For example, when Ektron CMS400.NET calculates average content rating, it divides the total number of rating points (on a scale of 1 thru 10) by the number of votes.

UpdateReportData Method

This method tells the database that an event's details should update that event's aggregated data. This method is only required if the database does not automatically do this, such as when the corresponding bit is disabled for that an type in the database. Disabling the corresponding bit generally improves performance, especially if the event logging rate is high. But, if you disable the corresponding bit, you must call this update method if you want the report to show current data.

The UpdateReportData method takes the following parameters.

Parameter	Type	Description
eventName	string	The event whose data will be updated.
eventDate	date time	The date of the event's occurrence. For example, if you pass 1/1/2009, one row in the aggregate table is updated. If the row doesn't exist, it gets created. If you do not pass an event date, this method updates the aggregate table with summary info for that event for all dates. For example, if today is February 1, the system has been in use since the beginning of the year, and you pass NULL for the date, 32 table rows are updated (31 days in January plus 2/1).

Parameter

Type

Description

eventName

string

The event whose data will be updated.

eventDate

date time

The date of the event's occurrence. For example, if you pass 1/1/2009, one row in the aggregate table is updated. If the row doesn't exist, it gets created.

If you do not pass an event date, this method updates the aggregate table with summary info for that event for all dates.

For example, if today is February 1, the system has been in use since the beginning of the year, and you pass NULL for the date, 32 table rows are updated (31 days in January plus 2/1).

Customizing the Saving and Reading Behavior

Disabling the Saving or Reading of Events

Using a Custom Provider

Disabling the Saving or Reading of Events

You can disable the saving or reading of all events or of individual events.

It is useful to disable events when you want to minimize database traffic. To disable all events, follow these steps.

1. Open siteroot/web.config.

2. Set the following parameters to false ( as shown below).

Note: These settings are set to enabled (true) by default.

You can also enable or disable individual events in the database itself, but this does require a call to travel through the full stack.

Using a Custom Provider

Below the service level are providers that read and write event data. The default providers simply pass calls through to the standard Ektron database-access-level code, which reads and writes from the database. But you can modify this behavior to almost any conceivable alternative. For example, you can

save the data to an alternate database on an alternate machine

call a web service to handle the reads and writes

filter the data and/or requests

process information on its way to or from the database

The SDK contains sample providers, as well as full source code for the Ektron-supplied providers. You can use this material as a basis for writing custom providers, which is the preferred technique for customizing the behavior of the Business Analytics API stack and subsystem.

The Default Providers

The default providers for saving and reading event data (respectively) are EktronEventProvider.cs and EktronQueryProvider.cs.

Example custom-provider source code has the following names for saving and reading event data (respectively): “DemoEventProvider.cs” and “DemoQueryProvider.cs”

For the default providers, the siteroot/web.config file must contain the following, inside <configuration><configSections>.

Additionally, the following must exist inside the <configuration> tags.

</providers>

</businessAnalyticsQueryProvider>

</providers>

</businessAnalyticsEventProvider

Creating Custom Providers

To override the default Ektron provider with the a custom provider, follow these steps.

1. Create a new solution with a project named CustomProviders.

2. Add the following references to your project.

Ektron.Cms.BusinessObjects.dll

Ektron.Cms.Common.dll

Ektron.Cms.ObjectFactory.dll

3. Add files DemoEventProvider.cs and DemoQueryProvider.cs (from the Ektron SDK).

4. Build.

5. Copy the CustomProviders.dll file to your Ektron CMS400.NET site's bin file.

6. Update web.config by modifying the <configuration> section. Specifically, add demo providers to the Business Analytics providers as shown below.

</providers>

</businessAnalyticsQueryProvider>

</providers>

</businessAnalyticsEventProvider>