Viewing Portlet Usage

This topic describes how to use SOAP messages to report on portlet usage in the AquaLogic Interaction portal.

Each time a portlet is accessed on the portal, a portletUses event is captured by Analytics. In this topic, you will learn how to:

Determine how many times any portlet has been used on the portal (the number of portletUses events)
View the name of the portlet associated with each portletUses event
View how many different portlets have been used on the portal
Group the results and see which portlets have been used on the portal

Determine the number of portletUses events.
This query is the simplest valid SOAP message that can be sent to the Query API service. In this message, you specify only the event you are interested in. In response, the Query API returns a count of that event in the Analytics database.

To query for the number of times the portletUses event has been captured by Analytics:
1. Create the basic SOAP framework for a Query API service request.
  Inside the SOAP Body element of every request made to the Query API service, the query must be contained within the <executeResultSetQuery> element. Within the <executeResultSetQuery> there must be en element <arg0>. The element <arg0> contains the actual parameters of the query.
  
  The following is the SOAP envelope and other elements that are the same for every Query API service SOAP request:
```
<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>
    </arg0> 
  </Q:executeResultSetQuery>
</S:Body>
</S:Envelope> 
```
2. Create an <eventName> element and populate it with the name of the event.
  In the SOAP request, event names take the form of {namespace}event.
  
  In our example, the namespace is http://www.bea.com/analytics/ali and the event is portletUses. Our 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>
    </arg0> 
  </Q:executeResultSetQuery>
</S:Body>
</S:Envelope> 
```
  When this SOAP message is sent with our application, the number of portletUses events is output to the console.
View the name of the portlet associated with each portletUses event.
The <views> element describes a specific property of the event that we are interested in seeing returned from the query. Each event has one or more associated dimensions, and each dimension has one or more properties. In this example, we are interested in the name property of the portlet dimension, or, in other words, the name of the portlet associated with the portletUses event.

For more details on the <views> element, see The <views> Element.

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>
        <dimension>portlet</dimension>
        <property>name</property>
      </views>

    </arg0> 
  </Q:executeResultSetQuery>
</S:Body>
</S:Envelope>
```
When this SOAP message is sent by the example application, the name of the portlet associated with each portletUses event is output to the console. In a test environment, this generated a list approximately 1350 portlet names long, with some names repeated hundreds of times.
View how many different portlets have been used on the portal.
Instead of seeing all of the portlet names for each portletUses event, use the <aggregate> element of the <views> query to count how many distinct portlets are represented in portletUses events.

The <aggregate> element takes an integer value. For a count aggregation, use the value 1. For a description of all aggregate types, see The <views> Element.

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>
        <dimension>portlet</dimension>
        <property>name</property>
        <aggregate>1</aggregate>
      </views>


    </arg0> 
  </Q:executeResultSetQuery>
</S:Body>
</S:Envelope>
```
When this SOAP message is sent with the example application, the number of portlets that have been used in the portal is output to the console. In a test environment, this was 12.
Group the results and see which portlets have been used on the portal.
For this step we use the <groups> element instead of the <views> element. The <groups> element groups the output by a given property. By grouping the output by portlet name, you see each portlet's name listed only once.

For more details on the <groups> element, see The <groups> Element.

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>

      <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 the names of portlets that have been used in the portal is output to the console. In a test environment, this was a list of twelve portlet names.

Parent topic: Tutorial: Using the Analytics Query API

AquaLogic Analytics Query API Usage Guide

Viewing Portlet Usage