Custom Adaptors

Custom Tree Adaptor - Monitoring Non-SharePoint Websites

CardioLog Analytics uses a logical tree to represent the hierarchical structure of the monitored website. Whenever a usage event is sent to CardioLog it maps to the relevant item in the website hierarchy. This allows CardioLog to create reports for any level of the website hierarchy.

The Portal Tree Updates service component is responsible for retrieving the hierarchical data from your website. If you wish to retrieve the structure of a non-SharePoint website, you can specify an external web service to provide the hierarchical (logical) structure of your website.

In order to monitor a non-SharePoint web site you need to do the following:

Install the Tracking Agent, which monitors visitor behavior for non-SharePoint web sites. The tracking code is added to a common page component, like master pages.
Configure the Website tree adaptor to a create tree structure automatically by crawling the website pages, or develop a Custom Tree Web Service that will return a logical tree structure that represents the hierarchy of your website.

Install the Tracking Agent

Note: The Tracking Agent installation does NOT require reboot or downtime.

If the Tracking Agent web application, named CardioLogAgent and installed on your CardioLog application server, is inaccessible from the website server install the CardioLogAgent web application on the web site server. You can verify if CardioLogAgent is accessible by opening http://[web site root]/CardioLogAgent/ca.aspx

Create a CardioLogAgent folder on the web site machine.
Copy the installation files into the new folder from [CardioLog Installation Folder]\CardioLogAgent\.
Open IIS Manager on the web site machine, create a new virtual directory named CardioLogAgent under the website, which points to the copied CardioLogAgent folder.
Set the following properties for the new virtual directory: "ASP.NET 2.0, Integrated Windows Authentication" and then verify that the folder permissions allow "Everyone" read access.
Verify that you can open http://[web site root]/CardioLogAgent/ca.aspx (Enter your website server name)
Open the copied CardioLogAgent directory, open the web.config file and edit the following key, located in the <appSettings> section:
<add key="CardioLogAgentRoot" value="http://[web site root]/"/>
Copy the tracking code from Administration > System Configuration > Usage Tracking Code > Select Non-SharePoint Website.

System Configuration - Usage Tracking Code
Edit the all URLs contained in the tracking code that redirect to the CardioLog application server, to redirect to the web site root URL.
Either add the edited tracking code into every page you want to track immediately after the opening <head> tag, or you can also use a common JavaScript file. Alternatively you can add it to a non-JavaScript common page component. In this case you need to add the opening and closing <script> tags. If you add the code to a master page, insert it before the closing </head> tag, and use opening and closing <script> tags.
Verify event collection by clicking Ctrl+F12 and wait for several seconds. The tracking agent console should pop-up, displaying the ID number for the most recent monitored action (event). To close the console, press Ctrl+F12.

Develop the Custom Tree Web Service

Using the Custom Tree Adaptor you can specify a web service which provides the hierarchical (logical) structure of your website.
In order to load your custom hierarchical structure to CardioLog from which the CardioLog Portal Tree Updates service component will obtain it, perform the following steps:

Develop the custom tree web service for your web site.
Verify that the custom tree web service returns a valid XML response according to the XML schema, and that the CardioLog Scheduling Service user account has sufficient permissions to access (request) the web service.
From the navigation pane in CardioLog go to Administration > System Configuration > Custom Tree Adaptor > Click Add.

System Configuration - Custom Tree Adaptor
Enter the custom tree web service URL in the Website URL textbox. (Acceptable file extensions are "aspx", "asmx" or "xml") and enter the name of your website in the Website Name textbox.
Click Save and restart the CardioLog Scheduling Service.
After the next run of Portal Tree Updates, the tree structure will be displayed in the Analysis Center (Object Explorer) and will be available for reports that allow content drilldown.

Custom Tree Web Service Schema

The Custom Tree web service should be exposed by a web page which provides an XML string response according to the following schema:

XML Schema

<?xml version="1.0" encoding="utf-8" ?>

<xs:schema id="OMTreeXmlSchema" elementFormDefault="qualified"

xmlns:mstns="http://tempuri.org/OMTreeXmlSchema.xsd"

xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:element name="tree">

<xs:complexType>

<xs:sequence>

<xs:element name="item" type="XmlNode" />

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:complexType name="XmlNode">

<xs:all>

<xs:element name="url" type="xs:string" />

<xs:element name="title" type="xs:string" />

<xs:element name="entitytype" type="xs:string" minOccurs="0" maxOccurs="1" />

<xs:element name="owner" type="xs:string" minOccurs="0" maxOccurs="1" />

<xs:element name="version" type="xs:string" minOccurs="0" maxOccurs="1" />

<xs:element name="template" type="xs:string" minOccurs="0" maxOccurs="1" />

<xs:element name="created" type="xs:string" minOccurs="0" maxOccurs="1" />

<xs:element name="modified" type="xs:string" minOccurs="0" maxOccurs="1" />

<xs:element name="permissions" minOccurs="0" maxOccurs="1">

<xs:complexType>

<xs:sequence>

<xs:element name="user" type="UserNode" minOccurs="0" maxOccurs="unbounded"/>

<xs:element name="group" type="GroupNode" minOccurs="0" maxOccurs="unbounded"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="items" minOccurs="0" maxOccurs="1">

<xs:complexType>

<xs:sequence>

<xs:element name="item" type="XmlNode" minOccurs="0" maxOccurs="unbounded" />

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:all>

</xs:complexType>

<xs:complexType name="UserNode">

<xs:sequence>

<xs:element name="username" type="xs:string" minOccurs="1" maxOccurs="1"/>

<xs:element name="permission" type="PermissionEnum" minOccurs="1" maxOccurs="1"/>

</xs:sequence>

</xs:complexType>

<xs:complexType name="GroupNode">

<xs:sequence>

<xs:element name="groupname" type="xs:string" minOccurs="1" maxOccurs="1"/>

<xs:element name="permission" type="PermissionEnum" minOccurs="1" maxOccurs="1"/>

</xs:sequence>

</xs:complexType>

<xs:simpleType name="PermissionEnum">

<xs:restriction base="xs:string">

<xs:enumeration value="R"/>

<xs:enumeration value="W"/>

</xs:restriction>

</xs:simpleType>

</xs:schema>

Field Definitions:

item - any specific item in the custom tree hierarchy.
URL - the item's full URL path
title - the item's title as you would like it to be displayed in CardioLog reports
entitytype - the item's content type
template - the item's content type template, for displaying related icons in the tree structure

Examples:

Entity type 5 - Folder
Available templates:
Website Folder -

Entity type 12 - Page
Available templates:
Website Page -
Website Folder Page -
Website Document -
Website Media -
Website Other -

You can also define your own custom content types in coordination with Intlock.

owner - item's owner/creator
version - item version, for tracking updates
created- the item's creation date
modified - the item's most recent modification date

Sample Data

<item>

<url>http://www.intlock.com</url>

<title>Intlock</title>

<owner>INTLOCK\James</owner>

<template>Website Folder</template>

<items>

<item>

<url>http://www.intlock.com/en-us/</url>

<owner>INTLOCK\James</owner>

<template>Website Folder Page</template>

</item>

<item>

<url>http://www.intlock.com/home.aspx</url>

<owner>INTLOCK\James</owner>

<template>Website Page</template>

</item>

</items>

</item>

Custom Users and Groups Adaptor - Importing Users and Groups from External Sources

CardioLog Analytics provides the ability to segment authenticated visitors by their user names and the groups they belong to. The organizational hierarchy of users and groups is monitored by the Active Directory Updates service, which retrieves the data directly from Active Directory by default.

The Active Directory Updates service can also retrieve the data from a custom source, using a designated web service which supplies the desired organizational structure of users and groups.

Develop the Custom Users and Groups Web Service

In order to load your user and group organization structure to CardioLog, you are required to specify a web service that the Active Directory Updates service will gather the organization's data from. This is done through the CardioLog Administration user interface:

Develop the custom organization structure web service for your organization.
Verify that your custom organization structure web service returns a valid XML response, according to the XML schema,
Confirm the CardioLog Scheduling Service user account has sufficient read request permissions to access the web service.
From the navigation pane in CardioLog go to Administration > System Configuration > Users and Groups Management.
Click Add Source > Custom.

System Configuration - Users and Groups Management - Custom
Enter the custom web service URL in the Web Service URL text box (acceptable file extensions: "aspx", "asmx", "xml").
Confirm all other details are accurate.
Click Save and restart the CardioLog Scheduling Service.
After the next Active Directory update, your users and groups will be added to the relevant Users and Groups filter of each report.

Custom Users and Groups Web Service Schema

The Users and Groups web service should be exposed by a web page which provides a XML string response according to the following schema:

XML Schema

<?xmlversion="1.0"encoding="utf-8" ?>

<xs:schema

elementFormDefault="qualified"

xmlns:mstns="http://tempuri.org/ADXmlSchema.xsd"

xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:element name="tree">

<xs:complexType>

<xs:sequence>

<xs:element name="users">

<xs:complexType>

<xs:sequence>

<xs:element maxOccurs="unbounded" name="user">

<xs:complexType>

<xs:sequence>

<xs:element name="accountName" type="xs:string" />

<xs:element name="displayName" type="xs:string" />

<xs:element name="userMail" type="xs:string" />

<xs:element name="memberOf" type="xs:string" />

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="groups">

<xs:complexType>

<xs:sequence>

<xs:element maxOccurs="unbounded" name="group">

<xs:complexType>

<xs:sequence>

<xs:element name="groupName" type="xs:string" />

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

Field Definitions:

User accountName: the user account name (a unique user ID).
User displayName: the user display name.
User userMail: the user email address.
User memberOf: a semicolon separated list of group names associated with the user.

Sample Data

<tree>

<users>

<user>

<accountName>MyCompany\james</accountName>

<displayName>James Wright</displayName>

<userMail>james.wright@mycompany.com</userMail>

<memberOf>Administrators;Marketing</memberOf>

</user>

<user>

<accountName>MyCompany\dana</accountName>

<displayName>Dana Cohen</displayName>

<userMail>dana.cohen@mycompany.com</userMail>

<memberOf>Sales</memberOf>

</user>

</users>

</tree>

Custom User Categories Adaptor - Importing User Attributes from External Sources

CardioLog Analytics provides advanced visitor segmentation capabilities by integrating both external and internal personal user data into reports.

Retrieval of additional user information, such as department, gender, and other profile data is performed by the User Categories Updates service, which retrieves the data from Active Directory attributes or SharePoint User Profiles by default. The User Categories Updates service can also retrieve the data from a custom source, using a designated web service that supplies the user information.

Develop the Custom User Categories Web Service

In order to load additional user information from a web service, specify a web service from which the User Categories Updates service will extract the user data. This is done through the CardioLog Administration user interface:

Create the custom user information web service for your organization.
Verify that the custom user information web service returns a valid XML response, according to the XML schema, and that the CardioLog Scheduling Service user account has sufficient permissions to access (request) the web service.
In the navigation pane in CardioLog go to Administration > System Configuration > User Category Management.
Click Add Categories Source > Custom.

System Configuration - User Category Management - Custom
Enter the web service URL in the URL field (acceptable file extensions: "aspx", "asmx", "xml").
Click Save and restart the CardioLog Scheduling Service.
After the next run of the User Categories Updates service, your user categories will be added to the Visitor Segments filter of each report, under User Categories.

Custom User Categories Web Service Schema

The user information web service should be exposed by a web page which provides an XML string response, according to the following format:

XML Schema

<?xml version="1.0" encoding="utf-8" ?>

<xs:schema id="CategoryXmlSchema"

elementFormDefault="qualified"

xmlns:mstns="http://tempuri.org/CategoryXmlSchema.xsd"

xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:element name="tree">

<xs:complexType>

<xs:sequence>

<xs:element name="item" type="UserCategoryXmlNode" minOccurs="0" maxOccurs="unbounded" />

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:complexType name="UserCategoryXmlNode">

<xs:sequence>

<xs:element name="userName" type="xs:string" />

<xs:element name="categories" minOccurs="0" maxOccurs="1">

<xs:complexType>

<xs:sequence>

<xs:element name="categoryValue" type="categoryNode" minOccurs="0" maxOccurs="unbounded" />

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:sequence>

</xs:complexType>

<xs:complexType name="categoryNode">

<xs:sequence>

<xs:element name="categoryName" type="xs:string" minOccurs="1" maxOccurs="1" />

<xs:element name="categoryValue" type="xs:string" minOccurs="1" maxOccurs="1" />

</xs:sequence>

</xs:complexType>

</xs:schema>

Field Definitions:

username: the user account name (should match the accountName field in the organization structure)
categoryName: the designated category name.
categoryValue: the assigned category value.

Sample Data

<tree>

<item>

<userName>MyCompany\james</userName>

<categoryName>Region</categoryName>

</categoryValue>

<categoryName>Gender</categoryName>

</categoryValue>

</categories>

</item>

<item>

<userName>MyCompany\taylor</userName>

<categoryName>Region</categoryName>

<categoryValue>North</categoryValue>

</categoryValue>

<categoryName>Gender</categoryName>

<categoryValue>Female</categoryValue>

</categoryValue>

</categories>

</item>

</tree>

Content

Space Tools

Custom Tree Adaptor - Monitoring Non-SharePoint Websites

Install the Tracking Agent

Develop the Custom Tree Web Service

Custom Tree Web Service Schema

Custom Users and Groups Adaptor - Importing Users and Groups from External Sources

Develop the Custom Users and Groups Web Service

Custom Users and Groups Web Service Schema

Custom User Categories Adaptor - Importing User Attributes from External Sources

Custom User Categories Web Service Schema