| Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Analytics 10g Release 4 (10.3.0.2.0) Part Number E14113-02 |
|
|
View PDF |
| Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Analytics 10g Release 4 (10.3.0.2.0) Part Number E14113-02 |
|
|
View PDF |
This chapter describes how to use the Oracle WebCenter Analytics Query API to access the Oracle WebCenter Analytics database in custom applications.
Using the Oracle WebCenter Analytics Query API is a tutorial that teaches you the basics of using the Query API through a series of example queries.
The Anatomy of the Oracle WebCenter Analytics Query API describes the Query API service and provides a detailed reference for creating SOAP requests for the Query API service and processing the SOAP responses.
Events and Dimensions is a reference of the events and dimensions that are defined for Oracle WebCenter Interaction products.
Generating and Using a Query API Client describes how to generate a Java Query API client using JAX-WS.
This section introduces you to the Oracle WebCenter Analytics Query API through a series of example queries.
To use the SOAP messages in this tutorial, you must have the following software installed:
Oracle WebCenter Analytics 10.3 or AquaLogic Analytics 2.5
Oracle WebCenter Interaction 10.3 or AquaLogic Interaction 6.5
In addition, the (optional) Java example code requires one of the following environments:
Java SE 5 and Glassfish 9.0
Java EE 5
This tutorial describes how to query data using SOAP and the Oracle WebCenter Analytics Query API. In addition to the SOAP messages, a Java example application is provided to send and receive SOAP messages. The Java example is not necessary to understand the tutorial. A developer who is proficient in working with SOAP on any development platform can easily adapt this tutorial. The following steps are covered in this tutorial:
Communicating With the Query API Service illustrates how to create an application to send, receive, and process SOAP messages from the Query API service.
Viewing Portlet Usage shows how to create SOAP queries to view which portlets are being used in your portal.
Filtering Portlet Usage by Community shows how to use filters to refine your queries.
Tracking Portlet Usage provides an example of how to view events based on periods of time.
Configuring the Oracle WebCenter Analytics Query API, explains how to manually enable the Query API and configure the SOAP connection to the API service.
This section leads you through the creation of a simple application that sends a SOAP message to the Query API Service and processes the response.
The application you create takes an XML file containing a SOAP message as input, sends the message to the Query API service, and outputs the results to standard output (the console). This application, or an application like it, is necessary to process the SOAP messages in the remainder of this tutorial. The code in this section requires Java SE 5 or greater and JAX-WS 2.0. These concepts should be familiar to any developer proficient in working with SOAP and can be implemented in the language of your choice.
Create a console-based application and write code necessary for a connection to the Query API service.
The Query API is located on the Oracle WebCenter Analytics server at http://analytics_server:port_number/analytics/QueryService. The default port_number is 11944. The following details are used to configure the SOAP connection to the Query API service:
| Element | Detail |
|---|---|
|
WSDL Location |
|
|
Namespace |
|
|
Service Name |
|
|
Port Name |
|
The following Java code establishes objects necessary for a SOAP connection to the Query API service on the Oracle WebCenter Analytics server named analytics:
import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.soap.SOAPMessage;
import javax.xml.ws.Dispatch;
import javax.xml.ws.Service;
class QueryAPIExample {
public static void main(String[] args) {
try
{
QName serviceName = new QName(
"http://www.bea.com/analytics/AnalyticsQueryService",
"AnalyticsQueryService");
URL serviceURL = new URL(
"http://analytics:11944/analytics/QueryService?wsdl");
Service service = Service.create(serviceURL, serviceName);
QName portName = new QName(
"http://www.bea.com/analytics/AnalyticsQueryService",
"AnalyticsQueryServicePort");
Dispatch<SOAPMessage> dispatch = service.createDispatch(
portName, SOAPMessage.class, Service.Mode.MESSAGE);
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
Load the SOAP message from a file (query.xml) and send it to the Query API service.
In the following Java example, the SOAP message is loaded from query.xml and then sent using the Dispatch object.
import java.io.FileInputStream;
import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.soap.MessageFactory;
import javax.xml.soap.SOAPMessage;
import javax.xml.ws.Dispatch;
import javax.xml.ws.Service;
class QueryAPIExample {
public static void main(String[] args) {
try
{
QName serviceName = new QName(
"http://www.bea.com/analytics/AnalyticsQueryService",
"AnalyticsQueryService");
URL serviceURL = new URL(
"http://analytics:11944/analytics/QueryService?wsdl");
Service service = Service.create(serviceURL, serviceName);
QName portName = new QName(
"http://www.bea.com/analytics/AnalyticsQueryService",
"AnalyticsQueryServicePort");
Dispatch<SOAPMessage> dispatch = service.createDispatch(
portName, SOAPMessage.class, Service.Mode.MESSAGE);
SOAPMessage request = MessageFactory.newInstance().createMessage(null,
new FileInputStream("query.xml"));
// Send the request and get the response
SOAPMessage response = dispatch.invoke(request);
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
Process the SOAP response and output the data you are interested in to the console.
The elements contained in the <return> element of the SOAP response are described in the following table:
| Element | Description |
|---|---|
|
|
One |
|
|
In each |
|
|
The |
The following is an example of a response from the Query API service:
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Header/>
<S:Body>
<ns2:executeResultSetQueryResponse
xmlns:ns2="http://www.bea.com/analytics/AnalyticsQueryService">
<return>
<results>
<values xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:string">Report
</values>
<count>0</count>
</results>
<columns>portlet.name</columns>
</return>
</ns2:executeResultSetQueryResponse>
</S:Body>
</S:Envelope>
In this response the result of the query has one column, described as portlet.name (the name property of the portlet dimension of the event). The query has generated one row of data, and the name of the portlet returned is Report.
In the following code, the Java example is updated to process a response with any number of <results> and <columns>, and output the data to standard output.
import java.io.FileInputStream;
import java.net.URL;
import java.util.Iterator;
import javax.xml.namespace.QName;
import javax.xml.soap.MessageFactory;
import javax.xml.soap.Name;
import javax.xml.soap.SOAPBody;
import javax.xml.soap.SOAPBodyElement;
import javax.xml.soap.SOAPElement;
import javax.xml.soap.SOAPFactory;
import javax.xml.soap.SOAPMessage;
import javax.xml.ws.Dispatch;
import javax.xml.ws.Service;
class QueryAPIExample {
public static void main(String[] args) {
try
{
QName serviceName = new QName(
"http://www.bea.com/analytics/AnalyticsQueryService",
"AnalyticsQueryService");
URL serviceURL = new URL(
"http://analytics:11944/analytics/QueryService?wsdl");
Service service = Service.create(serviceURL, serviceName);
QName portName = new QName(
"http://www.bea.com/analytics/AnalyticsQueryService",
"AnalyticsQueryServicePort");
Dispatch<SOAPMessage> dispatch = service.createDispatch(
portName, SOAPMessage.class, Service.Mode.MESSAGE);
SOAPMessage request = MessageFactory.newInstance().createMessage(null,
new FileInputStream("query.xml"));
// Send the request and get the response
SOAPMessage response = dispatch.invoke(request);
// Process the request and print the result
SOAPBody resBody = response.getSOAPBody();
SOAPFactory soapFactory = SOAPFactory.newInstance();
Name name;
name = soapFactory.createName(
"executeResultSetQueryResponse",
"ns2",
"http://www.bea.com/analytics/AnalyticsQueryService");
SOAPElement resResultSet =
(SOAPElement)resBody.getChildElements(name).next();
name = soapFactory.createName("return");
SOAPElement resReturn =
(SOAPElement)resResultSet.getChildElements(name).next();
name = soapFactory.createName("results");
Iterator results = resReturn.getChildElements(name);
System.out.println("Analytics Query API Results:");
System.out.println("----------------------------\n\n");
name = soapFactory.createName("values");
SOAPElement value;
while(results.hasNext())
{
Iterator values = ((SOAPElement)results.next()).getChildElements(name);
while (values.hasNext())
{
value = (SOAPElement)values.next();
System.out.print(value.getValue() + "\t\t");
}
System.out.print("\n");
}
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
This section describes how to use SOAP messages to report on portlet usage in the Oracle WebCenter Interaction portal.
Each time a portlet is accessed on the portal, a portletUses event is captured by Oracle WebCenter Analytics. This section describes how to:
Determine how many times any portlet has been used in the portal.
View the name of the portlet associated with each portletUses event.
View how many different portlets have been used in the portal.
Group the results and see which portlets have been used in 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 Oracle WebCenter Analytics database. To query for the number of times the portletUses event has been captured by Oracle WebCenter Analytics, follow the steps below:
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>
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 this example, the namespace is http://www.bea.com/analytics/ali and the event is portletUses. 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>
</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 returned from the query. Each event has one or more associated dimensions, and each dimension has one or more properties. This example uses the name property of the portlet dimension (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 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.
This step uses 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, each portlet's name is 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.
This section describes how to use the <filters> element to narrow queries of the Query API service to specific portal communities.
The previous section, Viewing Portlet Usage, explained how to build queries to see which portlets are being used in the portal. In this section, filters are used to refine these queries. This section explains how to restrict queries to a single portal community or to multiple portal communities.
The <filters> element describes a property, a value for that property, and an operator to perform a check to see if any given event belongs in the result set. For more details on the <filters> element, see The <filters> Element.
This example builds on the final SOAP message from the previous section:
<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>
This query returns the name of each portlet that has been used in the portal. To see only the portlets that are accessed from the Oracle WebCenter Analytics Console community, add the following <filters> element:
<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>
<filters
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<dimension>community</dimension>
<property>name</property>
<operator>1</operator>
<values xsi:type="xs:string">Analytics Console</values>
</filters>
</arg0>
</Q:executeResultSetQuery>
</S:Body>
</S:Envelope>
The <operator>1</operator> corresponds to the operator equals. For a list of all valid values for <operator>, see The <filters> Element.
The type of the <values> element must be defined. You must include the XMLSchema and XMLSchema-instance namespaces.
When this SOAP message is sent with the example application, a list of the names of portlets that have been used in the Oracle WebCenter Analytics Console community is output to the console. In a test environment, this was a list of six portlet names:
Analytics Query API Results: ---------------------------- Community Metrics Other Metrics Portlet Metrics Publisher Administration Report Summary Metrics
To create a filter where more than one value of a property is accepted, you must use the in operator, <operator>9</operator> and create a <values> element for each acceptable value.
To list portlets used in both the Publisher Community and Oracle WebCenter Analytics Console communities, change the <operator> to in and add a <values> for the Publisher Community community:
<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>
<filters
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<dimension>community</dimension>
<property>name</property>
<operator>9</operator>
<values xsi:type="xs:string">Analytics Console</values>
<values xsi:type="xs:string">Publisher Community</values>
</filters>
</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 both the Publisher Community and Oracle WebCenter Analytics Console communities is output to the console. In a test environment, this was a list of eight portlet names:
Analytics Query API Results: ---------------------------- Community Metrics FCC News Portlet Other Metrics Portlet Metrics Publisher Administration Publisher Community Directory Portlet Report Summary Metrics
This section describes how to use the <groups> element to track portlet usage based on periods of time.
This section describes how to view how many times each portlet was used in the portal and how many times a specific portlet was used each day.
To view how many times each portlet was used in the portal, follow the steps below:
Create a <views> element that counts events.
A <views> element that uses the COUNT aggregate and <property>*</property> will return a count of events.
When the following SOAP message is sent with the application, a count of every time a portlet has been used in the portal is output to the console.
<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>
Note:
This query returns the same results as he first query in Viewing Portlet Usage, where there was simply the <eventName> element and no <views>. The difference is essential in the next step, when other parameters are added to the query. This <views> element causes the Query API service to return a count of events that meet the criteria of the query.
Create a <groups> element to list the portlets used in 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 above will give you a count of events that match each distinct value of the grouped property.
When the following 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.
<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>
In a test environment, the response 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
To group results by time, 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.
This example groups results by day, or <timeGrouping>3</timeGrouping>, and then uses a filter to view data only for the Summary Metrics portlet.
When the following SOAP message is sent with the example application, a list of portlet usage statistics by date is output to the console.
<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>
In a test environment, the response 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
To use the Oracle WebCenter Analytics Query API, you must manually enable the Query API and configure the SOAP connection to the API service.
To manually enable the Query API, follow the directions below.
Stop the Oracle WebCenter Analytics UI Service.
Go to <AnalyticsInstallationFolder>\10.3.0\webapps.
UnJar analytics.war.
Open web.xml in a text editor and remove all the comments “Uncomment this to enable QueryAPI“.
Jar analytics.war.
Start the Oracle WebCenter Analytics UI Service.
To configure the SOAP connection to the API service, use the settings in the table below.
Table 2-1 SOAP Configuration Details
| Element | Detail |
|---|---|
|
Service Location |
|
|
WSDL Location |
|
|
Namespace |
|
|
Service Name |
|
|
Port Name |
|
This section provides an overview of the Oracle WebCenter Analytics Query API.
The following topics are covered in this section:
The Query API SOAP Request provides a description of a Query API SOAP request, including specific details about query parameters.
The Query API SOAP Response provides a description of a Query API SOAP response.
This section provides a description of the components of a Query API SOAP request.
Every valid Query API SOAP request must contain the following elements in the <Body> element of a standard SOAP envelope:
<executeResultSetQuery> which contains
<arg0> which contains the query elements, covered in the next section, Query Elements.
These elements form the basic request body for every Query API request, as shown in the example below.
<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>
The query elements for each request are contained within the <arg0> element.
Table 2-2 Query Elements
| Element | Description |
|---|---|
|
|
This element describes the event being queried. There must be one and only one of this element. The content of the <eventName>{namespace}event</eventName>
For more details on events and event namespaces, see Events and Dimensions. |
|
|
This element describes the event being queried. There must be one and only one of this element. The content of the <eventName>{namespace}event</eventName>
For more details on events and event namespaces, see Events and Dimensions. |
|
|
This element defines a view on a property or dimension property of the event, or on an aggregate of either. For details, see The <views> Element. |
|
|
This element defines grouping on a property or dimension property of the event. Grouping may also be done by period of time. For details, see The <groups> Element. |
|
|
This element defines a filter to be placed on a property or a dimension property of the event. For details, see The <filters> Element. |
|
|
This element defines how you want the results to be ordered. The property used to order the results must be also represented in a For details, see The <orders> Element. |
The following is a complete example of a Query API SOAP request. This request returns the name and ID of all portlets that have been used in the Oracle WebCenter Analytics Console community, ordered by portlet ID, along with a count of how many times each portlet was used.
<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>
<groups>
<dimension>portlet</dimension>
<property>id</property>
</groups>
<filters
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<dimension>community</dimension>
<property>name</property>
<values xsi:type="xs:string" >Analytics Console</values>
<operator>1</operator>
</filters>
<orders>
<dimension>portlet</dimension>
<property>id</property>
<isAscending>1</isAscending>
</orders>
</arg0>
</q:executeResultSetQuery>
</S:Body></S:Envelope>
This section provides the syntax for the <views> element of a Query API SOAP request.
The <views> element defines a view on a property or dimension property of an event, or on an aggregate of either. For each <views> element there is a column added to the result set. There may be multiple <views> elements.
There are three elements contained by the <views> element:
Table 2-3 Elements Contained by <views> Element
| Element | Description |
|---|---|
|
|
The name of a dimension associated with the event. Each |
|
|
The name of a property associated with the dimension. Each Note: There is a special case usage of the <views>
<property>*</property>
<aggregate>1</aggregate>
</views>
This special case results in a count of events that meet the criteria of the rest of the query. |
|
|
The method of aggregation for this view. This is an optional element and takes an integer value. For details on the values used by the |
Table 2-4 Aggregation Types
| Value | Description |
|---|---|
|
0 |
No aggregation. This is the same as omitting the |
|
1 |
Count. A count of all distinct properties in the view. |
|
2 |
Min. The property with the minimum value in the view. For string values, this is the alphabetically earliest property. |
|
3 |
Max. The property with the maximum value in the view. For string values, this is the alphabetically latest property. |
|
4 |
Average. An arithmetic average of the properties in the view. This only applies to numeric properties. |
|
5 |
Sum. The sum total of the properties in the view. This only applies to numeric properties. |
This section provides the syntax for the <groups> element of a Query API SOAP request.
The <groups> element defines a grouping on a property or dimension property of an event, or on a grouping based on a period of time. For each <groups> element there is a column added to the result set. There may be multiple <groups> elements.
There are three elements contained by the <groups> element:
Table 2-5 Elements Contained by <groups> Element
| Element | Description |
|---|---|
|
|
The name of a dimension associated with the event. Each |
|
|
The name of a property associated with the dimension. Each |
|
|
The period of time for this grouping. This is an optional element and takes an integer value. For details on the values used by the Note: When grouping by time, you must set <groups>
<dimension>time</dimension>
<property />
<timeGrouping>2</timeGrouping>
</groups>
|
This section provides the syntax for the <filters> element of a Query API SOAP request.
The <filters> element defines a filter to be placed on a property or dimension property of an event. When a <filters> element is defined for a property, only events that meet the criteria of the <filters> element will be returned. There may be multiple <filters> elements.
There are six elements contained by the <filters> element:
Table 2-7 Elements Contained by <filters> Element
| Element | Description |
|---|---|
|
|
The name of a dimension to be filtered. Each |
|
|
The name of a property associated with the dimension. Each |
|
|
The method of comparison to use between the |
|
|
The values to which each event will be compared to, as dictated by the <values xmlns:xs= "http://www.w3.org/2001/XMLSchema" xmlns:xsi= "http://www.w3.org/ 2001/XMLSchema-instance" xsi:type="xs:string"> Reports </values> |
|
|
The ranking method to use. This element is optional. The values for this element are:
|
|
|
The number of top or bottom values to return. This element is only required when you use the |
Table 2-8 Operator Types
| Value | Description |
|---|---|
|
1 |
Equals. The event is included in the results if the |
|
2 |
Not equals. The event is included in the results if the |
|
3 |
Greater than. The event is included in the results if the |
|
4 |
Greater than or equal to. The event is included in the results if the |
|
5 |
Less than. The event is included in the results if the |
|
6 |
Less than or equal to. The event is included in the results if the |
|
7 |
Contains. The event is included in the results if the |
|
8 |
Does not contain. The event is included in the results if the |
|
9 |
In. The event is included in the results if the |
|
10 |
Not in. The event is included in the results if the |
|
11 |
Starts with. The event is included in the results if the |
|
12 |
Ends with. The event is included in the results if the |
This section provides the syntax for the <orders> element of a Query API SOAP request.
The <orders> element defines how the results are ordered based on a property or dimension property of an event. There may be multiple <orders> elements.
When using multiple <orders> elements, the primary order of the result set is determined by the first <orders> element. Subsequent <orders> elements further refine the order within the rules of all previous <orders> elements.
There are three elements contained by the <views> element:
Table 2-9 Elements Contained by <orders> Element
| Element | Description |
|---|---|
|
|
The name of a dimension associated with the event. Each |
|
|
The name of a property associated with the dimension. Each |
|
|
How to order the rows. This is an optional element and takes an integer value: A value of |
This section provides a description of the components of a Query API SOAP response.
Every Query API SOAP response contains the following static elements in the <Body> element of a standard SOAP envelope:
<executeResultSetQueryResponse>, which contains
<return>, which contains the query results, detailed in the next section, Query Results.
All query results from the Query API service will be contained in the response body, as shown in the example below.
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Header/> <S:Body> <ns2:executeResultSetQueryResponse xmlns:ns2="http://www.bea.com/analytics/AnalyticsQueryService"> <return> </return> </ns2:executeResultSetQueryResponse> </S:Body> </S:Envelope>
The results of the query are contained within the <return> element.
Table 2-10 Query Results Elements
| Element | Description |
|---|---|
|
|
This element represents one row of the result set. It contains a |
|
|
This element describes one column of the result set. |
The following is an example Query API SOAP response. This is a possible response to the request in the request example in The Query API SOAP Request
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Header/>
<S:Body>
<ns2:executeResultSetQueryResponse xmlns:ns2="http://www.bea.com/analytics/AnalyticsQueryService">
<return>
<results>
<values
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:int">7</values>
<values
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:string">Publisher Administration</values>
<values
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:int">246</values>
<count>0</count>
</results>
<columns>count(*)</columns>
<columns>portlet.name</columns>
<columns>portlet.id</columns>
</return>
</ns2:executeResultSetQueryResponse>
</S:Body>
</S:Envelope>
This section provides an overview of the events and dimensions in Oracle WebCenter Analytics.
An event is a record of an action, typically a user action, that has been captured by the Oracle WebCenter Analytics Collector Service. For example, portletUses is an event that is captured every time a portlet is used on the Oracle WebCenter Interaction portal.
Each event includes associated data, grouped into dimensions based on the related component. For example, the portletUses event has data about the portlet, the portal community the portlet was accessed from, and the user's browser. Each dimension includes specific properties, for example, the portlet name and the browser version.
For details on specific events, see Events in the Oracle WebCenter Interaction Namespace
For details on different dimensions and their related properties, see the following sections:
This section describes the Oracle WebCenter Analytics events defined in the Oracle WebCenter Interaction namespace, http://www.bea.com/analytics/ali.
The following tables list the dimensions and properties associated with each event. For a listing of the properties associated with a dimension, see the referenced table in the sections that follow.
Table 2-11 documentViews Event
| Dimension / Property | Description |
|---|---|
|
document |
|
|
host |
|
|
browser |
|
|
searchFactId |
|
|
documentTypeId |
|
Table 2-13 pageViews Event
| Dimension / Property | Description |
|---|---|
|
community |
|
|
page |
Table 2-22, "communityPages Dimension (WebCenter Interaction)" |
|
host |
|
|
browser |
|
|
pageType |
|
|
responseTime |
|
|
isEntryPage |
|
|
isExitPage |
|
Table 2-14 portletUses Event
| Dimension / Property | Description |
|---|---|
|
portlet |
|
|
host |
|
|
community |
|
|
page |
Table 2-22, "communityPages Dimension (WebCenter Interaction)" |
|
browser |
Table 2-15 portletViews Event
| Dimension / Property | Description |
|---|---|
|
portlet |
|
|
host |
|
|
community |
|
|
browser |
|
|
responseTime |
|
Table 2-16 se arches Event
| Dimension / Property | Description |
|---|---|
|
searchTerm |
|
|
portlet |
|
|
community |
|
|
page |
Table 2-22, "communityPages Dimension (WebCenter Interaction)" |
|
responseTime |
|
|
abandoned |
|
|
totalMatches |
|
This section describes the Oracle WebCenter Analytics dimensions and their related properties. These dimensions are defined in the Oracle WebCenter Analytics namespace, http://www.bea.com/analytics.
Table 2-17 users Dimension (Analytics)
| Property | Description | Type | Length |
|---|---|---|---|
|
userID |
ID of the user object |
string |
255 |
|
name |
Name of the user object |
string |
255 |
|
description |
Description of the user object |
string |
255 |
|
loginName |
Login name of the user object |
string |
255 |
Table 2-18 userProperties Dimension (Analytics)
| Property | Description | Type | Length |
|---|---|---|---|
|
name |
Name of the property object |
string |
255 |
|
propertyId |
ID of the associated Oracle WebCenter Interaction object |
string |
255 |
|
isDisplayed |
Flag representing the visibility of the property object in both the Oracle WebCenter Analytics Console and Administration |
boolean |
This section describes the Oracle WebCenter Analytics dimensions and their related properties. These dimensions are defined in the Oracle WebCenter Interaction namespace, http://www.bea.com/analytics/ali.
Table 2-20 authSources Dimension (WebCenter Interaction)
| Property | Description | Type | Length |
|---|---|---|---|
|
name |
Name of the authentication source object |
string |
255 |
Table 2-21 browsers Dimension (WebCenter Interaction)
| Property | Description | Type | Length |
|---|---|---|---|
|
name |
Name of the browser (if found) |
string |
255 |
|
version |
Version of the browser (if found) |
string |
255 |
|
os |
Operating system (if found) |
string |
100 |
Table 2-22 communityPages Dimension (WebCenter Interaction)
| Property | Description | Type | Length |
|---|---|---|---|
|
name |
Name of the authentication source object |
string |
255 |
|
communityId |
ID of the associated community |
string |
255 |
Table 2-23 communities Dimension (WebCenter Interaction)
| Property | Description | Type | Length |
|---|---|---|---|
|
name |
Name of the authentication source object |
string |
255 |
Table 2-24 documents Dimension (WebCenter Interaction)
| Property | Description | Type | Length |
|---|---|---|---|
|
name |
Name of the document object |
string |
255 |
|
title |
Title of the document object |
string |
255 |
|
docDataSourceId |
ID of the associated data source |
integer |
8 |
Table 2-25 groups Dimension (WebCenter Interaction)
| Property | Description | Type | Length |
|---|---|---|---|
|
name |
Name of the user group object |
string |
255 |
|
description |
Description of the user group object |
string |
255 |
|
authSourceId |
ID of the associated authentication source object |
integer |
8 |
Table 2-26 hosts Dimension (WebCenter Interaction)
| Property | Description | Type | Length |
|---|---|---|---|
|
ipAddress |
IP address of client triggering event |
string |
24 |
|
hostName |
Resolved name of the associated IP address (if an IP can not be resolved, HOSTNAME is marked as “Unknown”) |
string |
255 |
This section describes the Oracle WebCenter Analytics dimensions and their related properties. These dimensions are defined in the Knowledge Directory namespace, http://www.bea.com/analytics/knowledgeDirectory.
Table 2-29 dataSources Dimension (Knowledge Directory)
| Property | Description | Type | Length |
|---|---|---|---|
|
name |
Name of the data source object |
string |
255 |
This section describes the Oracle WebCenter Analytics dimensions and their related properties. These dimensions are defined in the Publisher namespace, http://www.bea.com/analytics/publisher.
Table 2-32 folders Dimension (Publisher)
| Property | Description | Type | Length |
|---|---|---|---|
|
name |
Name of the Publisher folder object |
string |
255 |
|
parentId |
ID of the parent Publisher folder object (if the folder is the root folder, the PARENTID column contains a NULL value) |
integer |
8 |
Table 2-33 publishedItems Dimension (Publisher)
| Property | Description | Type | Length |
|---|---|---|---|
|
name |
Name of the Publisher content item object |
string |
255 |
|
folderId |
ID of the associated Publisher folder object |
integer |
8 |
|
url1 |
Chunked string representing the Publisher content item's published URL |
string |
450 |
|
url2 |
Chunked string representing the Publisher content item's published URL |
string |
450 |
|
url3 |
Chunked string representing the Publisher content item's published URL |
string |
450 |
|
url4 |
Chunked string representing the Publisher content item's published URL |
string |
450 |
|
url5 |
Chunked string representing the Publisher content item's published URL |
string |
450 |
This section describes how to generate a Java client using JAX-WS, and provides code samples for using the generated client.
You can generate platform-specific client code using the Oracle WebCenter Analytics Query API WSDL file. The following steps describe how to generate a Java client using JAX-WS.
Note:
To generate a .NET client, use Visual Studio. For more information, see the Microsoft Developers Network.
Download and install the latest version of JAX-WS.
JAX-WS can be found at https://jax-ws.dev.java.net/.
Use the wsimport utility to generate the client code from the Query API WSDL.
The command is wsimport –keep http://analytics_server:11944/analytics/QueryService?wsdlwhere analytics_server is the host of your Oracle WebCenter Analytics installation.
Copy the client code to your Java query project.
The client is generated to the bin directory.
Add javxws-ri/lib to the classpath of your project.
The following code snippet is an example of how to use the JAX-WS generated Java client.
import java.util.Calendar;
import java.util.GregorianCalendar;
import com.bea.analytics.analyticsqueryservice.*;
. . .
AnalyticsQueryService service = new AnalyticsQueryService();
AnalyticsQueryServicePortType port = service.getAnalyticsQueryServicePort();
. . .
//show the top 10 pages by page view, grouped by day, since 1/1/05, ignoring a page
//set the event type to be queried
QueryParameters param = new QueryParameters();
param.setEventName("{http://www.bea.com/analytics/ali}pageViews");
//define what information to return, in this case page view count and page id
View view = new View();
view.setProperty("*");
view.setAggregate(1); // aggregate count
param.getViews().add(view);
View idView = new View();
idView.setDimension("page");
idView.setProperty("id");
param.getViews().add(idView);
//filter the results
//in this case ignore a specific page
Filter filter = new Filter();
filter.setDimension("page");
filter.setProperty("id");
filter.setOperator(2); // operator not equals
filter.getValues().add(new Integer(518));
param.getFilters().add(filter);
//in this case ignore pageviews before a certain date
Filter timefilter = new Filter();
timefilter.setDimension("time");
timefilter.setOperator(3); // operator greater than
Calendar date = new GregorianCalendar();
date.set(2005, 1, 1);
timefilter.getValues().add(date.getTime());
param.getFilters().add(timefilter);
//only show the top 10 pages
Filter rankingFilter = new Filter();
rankingFilter.setDimension("page");
rankingFilter.setRanking(1); // ranking top
rankingFilter.setRankingCount(10);
param.getFilters().add(rankingFilter);
//now, group the results
GroupBy group = new GroupBy();
group.setDimension("page");
group.setProperty("name");
//note: unique "page name" = name + id
param.getGroups().add(group);
//note: auto adds name to view
GroupBy group1 = new GroupBy();
group1.setDimension("time");
group1.setTimeGrouping(3); // group by day
param.getGroups().add(group1);
QueryResults result = port.executeResultSetQuery(param);
printOutput(result);
|
 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|