Tracking Portlet Usage

This topic describes how to use the <groups> element to track portlet usage based on periods of time.

In this topic you learn how to:

View how many times each portlet was used on the portal
View how many times a specific portlet was used each week

View how many times each portlet was used on the portal.
1. Create a <views> element that counts events. A <views> element that uses the COUNT aggregate and <property>*</property> will return a count of events.
  You have the following SOAP message:
```
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Header/>
<S:Body>
  <Q:executeResultSetQuery xmlns:Q="http://www.bea.com/analytics/AnalyticsQueryService">
    <arg0>
 
      <eventName>
        {http://www.bea.com/analytics/ali}portletUses
      </eventName>

      <views>
         <property>*</property>
         <aggregate>1</aggregate>      
      </views>

    </arg0> 
  </Q:executeResultSetQuery>
</S:Body>
</S:Envelope>
```
  When this SOAP message is sent with our application, a count of every time a portlet has been used on the portal is output to the console.
  
  Note: You might be wondering how this query is any different from the first query you made in Viewing Portlet Usage, where there was simply the <eventName> element and no <views>. As is, both queries do return the same results. Where you will see the difference is in the next step, when you start adding other parameters to the query. This <views> element causes the Query API service to return a count of events that meet the criteria of the query.
2. Create a <groups> element to list the portlets used on the portal. Each row returned by the <groups> query represents one or more events for each distinct value of the grouped property. Combining a <groups> element with the <views> element we just wrote will give us a count of events that match each distinct value of the grouped property. Our SOAP message:
```
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Header/>
<S:Body>
  <Q:executeResultSetQuery xmlns:Q="http://www.bea.com/analytics/AnalyticsQueryService">
    <arg0>
 
      <eventName>
        {http://www.bea.com/analytics/ali}portletUses
      </eventName>

      <views>
         <property>*</property>
         <aggregate>1</aggregate>      
      </views>
      <groups>
        <dimension>portlet</dimension>
      <property>name</property>
      </groups>

    </arg0> 
  </Q:executeResultSetQuery>
</S:Body>
</S:Envelope>
```
  When this SOAP message is sent with the example application, a list of portlet names, each with a corresponding number representing how many times the portlet was used, is output to the console. In a test environment, it looked like this:
```
Analytics Query API Results:
----------------------------

98              Community Metrics
35              FCC News Portlet
150             Other Metrics
219             Portlet Metrics
7               Publisher Administration
18              Publisher Community Directory Portlet
274             Report
427             Summary Metrics
```

View how many times a specific portlet was used each day.

To group results by time, you create a <groups> element with the dimension set to time and a <timeGrouping> element set to the period of time you want grouped. The <timeGrouping> element takes an integer value.

For details on the values used with <timeGrouping>, see The <groups> Element.

For the example you are going to group results by day, or <timeGrouping>3</timeGrouping>, and then create a filter so you only see data for the Summary Metrics portlet.

The SOAP message looks like this:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Header/>
<S:Body>
  <Q:executeResultSetQuery xmlns:Q="http://www.bea.com/analytics/AnalyticsQueryService">
    <arg0>
 
      <eventName>
        {http://www.bea.com/analytics/ali}portletUses
      </eventName>

      <views>
         <property>*</property>
         <aggregate>1</aggregate>      
      </views>

      <groups>
        <dimension>time</dimension>
        <property></property>
        <timeGrouping>3</timeGrouping>
      </groups>

      <groups>
        <dimension>portlet</dimension>
        <property>name</property>
      </groups>

      <filters 
        xmlns:xs="http://www.w3.org/2001/XMLSchema" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      >
        <dimension>portlet</dimension>
        <property>name</property>
        <values  xsi:type="xs:string" >Summary Metrics</values>
        <operator>1</operator>
    </filters>

    </arg0> 
  </Q:executeResultSetQuery>
</S:Body>
</S:Envelope>

When this SOAP message is sent with the example application, a list of portlet usage statistics by date is output to the console. In a test environment, it looked like this:

Analytics Query API Results:
----------------------------

173             Summary Metrics         3/21/08
15              Summary Metrics         3/24/08
35              Summary Metrics         3/27/08
14              Summary Metrics         3/28/08
8               Summary Metrics         3/31/08
93              Summary Metrics         4/1/08
89              Summary Metrics         4/2/08
24              Summary Metrics         4/4/08

Parent topic: Tutorial: Using the Analytics Query API

AquaLogic Analytics Query API Usage Guide

Tracking Portlet Usage