Avaya™ Operational Analyst
Release 7.2
Data API Developer Guide
© Avaya Inc. 2005-2009 All rights reserved.
Table of Contents
1.
Introduction................................................................................................................. 3
1.1
What is the Data API .......................................................................................... 3
1.2
Who should use this document ........................................................................... 3
1.3
Acronyms............................................................................................................ 3
1.4
Reference to other documentation ...................................................................... 4
2. High Level description................................................................................................ 4
2.1
Requirements ...................................................................................................... 4
2.2
Component description ....................................................................................... 4
3. Detailed description .................................................................................................... 6
3.1
The API described............................................................................................... 6
SnapshotExport description ........................................................................................ 6
SnapshotExport API.................................................................................................... 7
RealTimeUpdateExport description............................................................................ 9
RealTimeUpdateExport API....................................................................................... 9
3.2
XML data format .............................................................................................. 11
Exported XML data format....................................................................................... 11
SQL to XML type mapping ...................................................................................... 12
3.3
Security ............................................................................................................. 13
User authentication ................................................................................................... 13
Using the request handler.......................................................................................... 13
Database security ...................................................................................................... 13
SSL Support for Data API Reference Client ............................................................ 13
3.4
Query limitations .............................................................................................. 15
OA real-time SQL limitations................................................................................... 15
OA historical data ..................................................................................................... 17
3.5
Performance notes............................................................................................. 18
Specifying the maximum number of rows returned ................................................. 18
3.6
Data Model........................................................................................................ 19
4. Real world example – Building your Data API client .............................................. 19
4.1
Components needed for compilation ................................................................ 19
4.2
Sequence diagrams............................................................................................ 20
SnapshotExport sequence diagram ........................................................................... 20
RealTimeUpdateExport sequence diagram............................................................... 21
4.3
Code examples .................................................................................................. 22
4.4
Code compilation .............................................................................................. 26
5. Real world example – Testing your Data API client ................................................ 27
5.1
Components needed for runtime....................................................................... 27
5.2
Expected results ................................................................................................ 28
5.3
Troubleshooting the API and your client.......................................................... 29
1. Introduction
1.1 What is the Data API
The Data Application Programming Interface (Data API) supports retrieval of OA realtime or historical data from the Stumbras Real-Time or Database Connection Pool
services, through a SOAP interface. The data is retrieved in response to SQL SELECT
statements. The results are returned as either XML formatted text, or delimiter-separated
text. The delimiter for the delimiter-separated format can also be specified. In both cases,
the results are returned inside a SOAP response message, which is itself XML. Note that
only SELECT statements are allowed, the data cannot be modified via the Data API.
Avaya OA 7.2 supports SSL functionality. You can allow the Data API Reference Client
to connect to a Data Export Web Server over SSL (https). See SSL Support for Data API
Reference Client.
1.2 Who should use this document
This document is intended for software developers and integrators (internal to Avaya,
business partners or customers). These users of the API must have good understanding of
and experience with:
• Java 2 Enterprise Edition (J2EE version 1.4 or greater)
They must also be knowledgeable in these topics:
• Java Web Services (JWSDP version 2.0)
• Operating System and associated web server
o Tomcat (version 3.2.2) for Windows platforms
o SunOne version 6 update 10 for Solaris platforms
o Tomcat (version 6.0.18) for AIX platform
• Avaya Operational Analyst (version 7.2 or greater)
1.3 Acronyms
Term
Data API
HTTPS
JAXP
JAX-RPC
JSSE
Definition
Data Application Programming Interface
Secure HTTP. A protocol for exchanging HTTP packets securely
through the use of public key encryption and certification. Implemented
on top of SSL or TLS.
Java API for XML Processing. An API that provides parsing,
transformation and serialization utilities for XML documents and
schemas.
Java API for XML-RPC. The Java implementation of XML-RPC, which
is a synchronous protocol for communication between systems. XMLRPC is implemented on top of SOAP. JAX-RPC is implemented on top
of SAAJ.
Java Secure Sockets Extension. An implementation of SSL and TLS for
3
Java.
SAAJ
SOAP with Attachments API for Java. The Java implementation of
SOAP with Attachments, which is a way of sending more than SOAP
envelopes over the transport protocol. SAAJ is implemented on top of
JAXP.
SOAP
Simple Object Access Protocol. An asynchronous protocol for
communication between systems. Typically implemented on top of
HTTP or HTTPS, where the packets exchanged are XML messages,
made up of parts containing envelopes or attachments.
SSL
Secure Sockets Layer. A protocol for encryption over various standard
protocols, including HTTP.
TLS
Transport Layer Security. A replacement protocol for SSL that is more
extensible and adaptive.
Web service
A protocol stack for synchronous or asynchronous communication
between systems. Web services typically use technologies such as
SOAP, XML-RPC, WSDL, HTTP/HTTPS and XML.
WSDL
Web Services Description Language. An XML language that describes
the name, arguments, return value and location of any SOAP or XMLRPC interface.
XML Schema An XML language for describing XML documents.
1.4 Reference to other documentation
•
•
•
•
•
•
•
•
•
Report Framework is described in the Architecture for Operational
Analyst 6.1, Compas ID 92577
OA real-time and historical database schemas. The data models are available at
doc/Data_Models/index.html
Sun’s J2EE documentation (http://java.sun.com/j2ee/docs.html)
Sun’s JWSDP 2.0 online documentation
(http://java.sun.com/webservices/downloads/previous/webservicespack.jsp)
XML online documentation ( http://www.xml.org/)
Avaya Operational Analyst Release 7.2 Installation and Configuration guide,
Compas ID 140313
Avaya Operational Analyst Release 7.2 Installation Planning and Prerequisites
guide, Compas ID 140312
Avaya Operational Analyst 7.2 Maintenance and Troubleshooting guide, Compas
ID 141298
2. High Level description
The Data API is implemented as a Web Service. The interface is described in detail in
chapter 3.1.
4
2.1 Requirements
The Data API software runs within the Report Framework. It is started automatically
when the Report Framework is started. The Avaya OA software and all its dependencies
must be installed and configured.
JRE Endorsing
Perform the following steps on Windows \ Solaris \ AIX after installing JRE for Client
Application.
1. Create folder endorsed under $JreHome\lib\
Note: $JreHome\lib\ is normally C:\Program Files\Java\jre1.6.0_07\lib\
Note:
2. Copy the following files from $PABASE\jars to $JreHome\lib\endorsed
• saaj-api.jar
• saaj-impl.jar
• xercesImpl.jar
2.2 Component description
The API utilizes the Report Framework services to access the real-time and historical
databases. The implementation and connection details are abstracted from the Data API
user. The picture below shows the components involved in the API data flow. This
information is only given as background as the implementation details are transparent to
the user of the API.
The main components involved in a Data API call are:
Real-Time Database This is a third party in-memory database that is used to store realtime data. The database is accessed via the RDS.
Report Data Server The RDS is a Java process that maintains connections to the realtime database. It publishes a CORBA interface that is called by the
Report Framework.
Web Server
The Web Server is a 3rd party software where the Report
Framework and the API run. We currently support Tomcat on
Windows, Sun ONE (iPlanet) on Solaris and Tomcat on AIX.
Report Framework The Report Framework is a Java-based servlet that offers services
to the API. The framework handles security, logging, historical
database connection pool and connections to the RDS for real-time
queries. It runs within the Web server.
Data API
The component described in this document. It runs within the
Report Framework and is accessed through the Request Handler.
RequestHandler
Part of the Report Framework, the request handler is a gateway to
the API. It provides authentication services and redirects requests
5
Report Host
Real-Time Host
Historical Host
Web
Report
Framework
Real-Time
Database
Report Data
Server (RDS)
Historical
Database
Data API
Request Handler
Client Host
Data API Client
Data API Client
Historical Database
to the API. Access is rejected if the request gets to the API other
than from this handler.
A Java component that makes requests to the Data API. It can be
an application, another servlet or any other type of J2EE
component.
This is a third party database used to store historical information.
The database vendor and specifics are abstracted from the Report
Framework via ODBC.
Picture 1 – Components surrounding the Data API
3. Detailed description
3.1 The API described
SnapshotExport description
This object allows the user to retrieve a snapshot of the data on the server for a given
SQL query. If you wish to receive several updates for real-time data from the same query,
use RealTimeUpdateExport instead.
This object provides four methods; two methods to retrieve real-time data, and two
methods for historical data. Each pair includes one method to specify the results should
be XML formatted, and the other to specify that the results should be delimiter-separated.
All four methods take as a parameter a SQL SELECT statement, represented as String
objects. If the SQL is not a valid SELECT statement, an IllegalArgumentException is
thrown. An SQL query for real-time data is further restricted as per 3.4
6
Query limitations.
Where delimiter-separated format is used, any data in the results will be escaped to avoid
conflicting with the given delimiter. This escape sequence will involve prefixing the
delimiter with a ‘\’ character, replacing any newlines with “\n” and any ‘\’ characters in
the results will be prefixed with another ‘\’. For example, the string “word (noun):
something that is said”, if delimited with a ‘:’ character, would be escaped as “word
(noun)\: something that is said”. To avoid any complications that could arise, the API
does not accept ‘n’ or ‘\’ as the delimiter. Each cell of data is separated by the delimiter,
and each row is separated by a newline.
The service expects connections to use HTTP Basic Authentication. The username and
password will be passed using Base 64 encoding (and encrypted if HTTPS is used).
Connections that do not have a valid username and password will be returned a 401
unauthorized HTTP error code. The username and password will be validated against the
OA Authserver, through the authentication mechanisms implemented in
ServletRequestHandler.
SnapshotExport API
//////////////////////////////////////////////////////////////////////////////
// Copyright (C) 2003, Avaya. All Rights Reserved.
// THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF AVAYA.
// The copyright notice above does not evidence any actual or intended
// publication of such source code.
//////////////////////////////////////////////////////////////////////////////
package com.avaya.stumbras.export;
import java.rmi.Remote;
import java.rmi.RemoteException;
import javax.xml.transform.Source;
/**
* This interface allows the user to retrieve a snapshot of the data
* on the server for a given SQL query. If the user wishes to receive
* several updats for real-time data from the same query, they should
* use RealTimeUpdateExport instead.
*
* @author Richard Atkins
* @version 1.0
**/
public interface SnapshotExport extends Remote
{
/**
* Returns an XML formatted result set from the data in the RDS
* server, for the given interval, matching the given SQL query.
*
* @param aSql the SQL query to run.
* @param aTimeWindow the update interval to query.
* @param aSchemaHolder a holder for a Source containing the schema
*
of the results.
* @param aExtraColumns true to get time window columns, false otherwise
* @return the XML formatted results.
* @throws BadArgumentException if the given SQL, time window or schema
*
holder are not valid. The SQL is valid if it is a valid select
*
statement. The time window is valid if it is the ID of a
*
time window configured on the RDS server. The schema holder is
*
valid if it is not null.
* @throws MethodUnavailableException if the RDS server is unavailable.
* @throws TooManyResultsException if too many results would be retrieved
*
by this method.
7
* @throws RemoteException if something went wrong while processing the
*
query.
*/
public String getRealTimeXML(String aSql,
String aTimeWindow,
String aSchemaHolder,
boolean aExtraColumns)
throws BadArgumentException,
MethodUnavailableException,
TooManyResultsException,
RemoteException;
/**
* Returns a delimiter formatted result set from the data in the RDS
* server, for the given interval, matching the given SQL query.
*
* @param aSql the SQL query to run.
* @param aTimeWindow the update interval to query.
* @param aDelimiter the delimiter to use when formatting the results.
* @param aExtraColumns true to get time window columns, false otherwise
* @return the XML formatted results.
* @throws BadArgumentException if the given SQL, time window or delimiter
*
are not valid. The SQL is valid if it is a valid select
*
statement. The time window is valid if it is the ID of a
*
time window configured on the RDS server. The delimiter is
*
valid if it does not start with "\\" or "\n".
* @throws MethodUnavailableException if the RDS server is unavailable.
* @throws TooManyResultsException if too many results would be retrieved
*
by this method.
* @throws RemoteException if something went wrong while processing the
*
query.
*/
public String getRealTimeDelimitedText(String aSql,
String aTimeWindow,
String aDelimiter,
boolean aExtraColumns)
throws BadArgumentException,
MethodUnavailableException,
TooManyResultsException,
RemoteException;
/**
* Returns an XML formatted result set from the data in the historical
* server, matching the given SQL query.
*
* @param aSql the SQL query to run.
* @param aSchemaHolder a holder for a Source containing the schema
*
of the results.
* @return the XML formatted string results.
* @throws BadArgumentException if the given SQL or schema
*
holder are not valid. The SQL is valid if it is a valid select
*
statement. The schema holder is valid if it is not null.
* @throws MethodUnavailableException if the RDS server is unavailable.
* @throws TooManyResultsException if too many results would be retrieved
*
by this method (too many rows as specified in aMaxNumRow).
* @throws RemoteException if something went wrong while processing the
*
query.
*/
public String getHistoricalXML(String aSql,
String aSchemaHolder)
throws BadArgumentException,
MethodUnavailableException,
TooManyResultsException,
RemoteException;
/**
* Returns a delimiter formatted result set from the data in the
* historical server, matching the given SQL query.
*
* @param aSql the SQL query to run.
* @param aDelimiter the delimiter to use when formatting the results.
8
* @return the delimiter formatted results.
* @throws BadArgumentException if the given SQL or delimiter
*
are not valid. The SQL is valid if it is a valid select
*
statement. The delimiter is valid if it does not start
*
with "\\" or "\n".
* @throws MethodUnavailableException if the RDS server is unavailable.
* @throws TooManyResultsException if too many results would be retrieved
*
by this method (too many rows as specified in aMaxNumRow).
* @throws RemoteException if something went wrong while processing the
*
query.
*/
public String getHistoricalDelimitedText(String aSql,
String aDelimiter)
throws BadArgumentException,
MethodUnavailableException,
TooManyResultsException,
RemoteException;
}
RealTimeUpdateExport description
This object allows you to set up a request, and query for updates to that request at regular
intervals. If the you wish to receive only one update for a request, or wish to query
historical data, use SnapshotExport instead.
This object provides four methods: one mothod to create a DataSet; two methods to
retrieve the next results currently available for a DataSet and format them as either XML
or delimiter-separated; and one method to delete a DataSet. The XML and delimited
formats are the same as those documented for the SnapshotExport API.
RealTimeUpdateExport API
//////////////////////////////////////////////////////////////////////////////
// Copyright (C) 2003, Avaya. All Rights Reserved.
// THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF AVAYA.
// The copyright notice above does not evidence any actual or intended
// publication of such source code.
//////////////////////////////////////////////////////////////////////////////
package com.avaya.stumbras.export;
import java.rmi.Remote;
import java.rmi.RemoteException;
import javax.xml.transform.Source;
/**
* This interface allows the user to set up a request, and query for
* updates to that request at regular intervals. If the user wishes to
* receive only one update for a request, or wishes to query
* historical data, they should use SnapshotExport instead.
*
* @author Richard Atkins
* @version 1.0
**/
public interface RealTimeUpdateExport extends Remote
{
/**
* Creates a data set with the given SQL query, update period and interval.
* @param aSql the SQL query to run.
* @param aPeriod how often to update the query results.
* @param aTimeWindow the name of the interval to query.
* @param aExtraColumns true to get time window columns, false otherwise
* @return the id of the created data set.
* @throws BadArgumentException if the given SQL, update period or time
*
window are not valid. The SQL is valid if it is a valid select
*
statement. The update period is valid if it is one of the
9
*
values supported by the RDS server. The time window is valid
*
if it is the ID of a time window configured on the RDS server.
* @throws MethodUnavailableException if the RDS server is unavailable.
* @throws RemoteException if something went wrong while processing the
*
query.
**/
public String createDataSet(String aSql,
int aPeriod,
String aTimeWindow,
boolean aExtraColumns)
throws BadArgumentException,
MethodUnavailableException,
RemoteException;
/**
* Gets an update to the results for the data set, and formats it as XML.
* Also returns the schema for the data in the given schema holder.
* @param aDataSetID the id of the data set to update.
* @param aSchemaHolder the holder for the XML schema.
* @return the XML formatted string results.
* @throws BadArgumentException if the given data set id or schema
*
holder are not valid. The data set id is valid if it is an
*
id that was returned by createDataSet(), and has not yet been
*
deleted. The schema holder is valid if it is not null.
* @throws MethodUnavailableException if the RDS server is unavailable.
* @throws TooManyResultsException if too many results would be retrieved
*
by this method.
* @throws RemoteException if something went wrong while processing the
*
query.
**/
public String getUpdateXML(String aDataSetID, String aSchemaHolder)
throws BadArgumentException,
MethodUnavailableException,
TooManyResultsException,
RemoteException;
/**
* Gets an update to the results for the data set, and formats it with
* the given delimiter.
* @param aDataSetID the id of the data set to update.
* @param aDelimiter the delimiter to use.
* @return the delimiter formatted results.
* @throws BadArgumentException if the given data set id or delimiter
*
are not valid. The data set id is valid if it is an
*
id that was returned by createDataSet(), and has not yet been
*
deleted. The delimiter is valid if it does not start with "\\"
*
or "\n".
* @throws MethodUnavailableException if the RDS server is unavailable.
* @throws TooManyResultsException if too many results would be retrieved
*
by this method.
* @throws RemoteException if something went wrong while processing the
*
query.
**/
public String getUpdateDelimitedText(String aDataSetID, String aDelimiter)
throws BadArgumentException,
MethodUnavailableException,
TooManyResultsException,
RemoteException;
/**
* Deletes the given data set.
* @param aDataSetID the id of the data set to delete.
* @throws BadArgumentException if the given data set id
*
is not valid. The data set id is valid if it is an
*
id that was returned by createDataSet(), and has not yet been
*
deleted.
* @throws MethodUnavailableException if the RDS server is unavailable.
* @throws RemoteException if something went wrong while processing the
*
query.
**/
public void deleteDataSet(String aDataSetID)
10
throws BadArgumentException,
MethodUnavailableException,
RemoteException;
}
3.2 XML data format
Exported XML data format
XML formatted data that is exported by this API will be as follows:
• Any data in the results will be escaped to avoid conflicting with the ‘&’ and ‘<’
characters (as per the W3C XML recommendation).
o ‘&’ will be replaced by “&amp;”.
o ‘<’ will be replaced by “&lt;”.
• If the data is binary, then the string will be base64 encoded.
The XML data format returned will be a table-based mapping, with meta-data for the
columns in a separate schema document, specifying the column names and their SQL
type. For real-time data, there will be an attribute of the table indicating the when the
table was last updated. The namespace of this schema will be
http://xml.avaya.com/BI/OA/export. For example, given results containing two rows with
an integer ID and a string Path, the schema would be:
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns="http://xml.avaya.com/BI/OA/export"
targetNamespace="http://xml.avaya.com/BI/OA/export"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xsd:element name="table" type="tableType"/>
<xsd:complexType name="tableType">
<xsd:sequence>
<xsd:element ref="row" minOccurs="0" maxOccurs"unbounded">
</xsd:sequence>
<xsd:attribute name="lastUpdate" type="xsd:dateTime" use="optional"/>
</xsd:complexType>
<xsd:element name="row" type="rowType"/>
<xsd:complexType name="rowType">
<xsd:sequence>
<xsd:element ref="ID"/>
<xsd:element ref="Path"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="ID" type="xsd:integer"/>
<xsd:element name="Path" type="xsd:string"/>
</xsd:schema>
The table would be:
<?xml version="1.0" encoding="UTF-8"?>
<table xmlns="http://xml.avaya.com/BI/OA/export"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<row>
<ID>1</ID>
<Path>this is a path to some location</Path>
</row>
<row>
<ID>123</ID>
<Path>this is a much longer path, with complex characters like &lt; and &amp;</Path>
</row>
</table>
11
Note that this XML example has been formatted for readability. The XML data returned
by the DataExport service may not be indented. In the example, <table> represents the
result set returned for the SQL query, not necessarily a persistent table of the database.
This is based on the format documented in the next section. The schema for the XML is
returned at the same time as the data because it contains information that is only known
once the results for the SQL query have been generated. The elements of the rows have
the names of the columns in the returned data, and the types of the text in the elements
are mapped from the types of the data in the database.
SQL to XML type mapping
The SQL to XML type mapping is based on the work of the SQLX group and is
documented below. When their SQL/XML specification becomes standard, this mapping
should be updated to use the standardized mapping.
SQL column names will be used as the XML element names, where the column name has
been fully-escaped:
• Any ‘:’ will be replaced by “_x003A_”,
• Any ‘_’ with “_x005F_”.
• Any column name beginning with “xml” or “XML” or any combination will
be prefixed with “_xFFFF_”.
• All other characters that are valid in SQL identifiers but are not valid in XML
names will be replaced by their 4 (or 8) digit hexadecimal Unicode string of
the form “_xHHHH_” (or “_xHHHHHHHH_”).
The following SQL types will be mapped to the closest matching XML Schema datatype.
For simplicity, no further restrictions will be placed upon the type to ensure that the XML
does not accept values that are not valid SQL values, nor shall any annotations be added
to document the SQL type the XML represents. Any types not listed below are not
supported by this interface.
• If the SQL type is CHAR, VARCHAR or CLOB, then the XML Schema
datatype is xsd:string.
• If the SQL type is BLOB, BIT or BIT VARYING, then the XML Schema
datatype is xsd:base64Binary, where the data will be base64 encoded.
• If the SQL type is NUMERIC or DECIMAL, then the XML Schema dataype
is xsd:decimal.
• If the SQL type is INTEGER or SMALLINT, then the XML Schema datatype
is xsd:integer.
• If the SQL type is REAL, FLOAT or DOUBLE PRECISION, then the XML
Schema datatype is xsd:double.
• If the SQL type is BOOLEAN, then the XML Schema datatype is
xsd:boolean.
• If the SQL type is DATE, then the XML Schema datatype is xsd:date.
• If the SQL type is TIME WITH TIMEZONE or TIME WITHOUT
TIMEZONE, then the XML Schema datatype is xsd:time.
12
•
If the SQL type is TIMESTAMP WITHOUT TIMEZONE or TIMESTAMP
WITH TIMEZONE, then the XML Schema datatype is xsd:dateTime.
3.3 Security
User authentication
The user is required to be authenticated to access the Data API. Your client must pass
property values as described in the code examples of section 4.3. The userid and
password are authenticated against the authentication mechanism on OA’s historical
server. The report framework takes care of forwarding the authentication request to the
historical host if they do not reside on the same machine.
Once the authentication request reaches the historical host, it is processed against the
operating system’s authentication mechanism. On Windows, you may use domain users.
On Solaris and AIX, you may use nfs users. To specify the domain name on Windows
platform, the username string should be <domain>\<username>. Simply pass the nfs
username to use nfs users on Unix platforms.
Using the request handler
The Data API request handler is a gateway to the Data API web service. You must go
through it so the Report Framework authenticates the user and forwards the HTTP
request to the web service. If requests are sent directly to the web service, they will fail
with an HTTP 401 error. The URL of the code examples points to the appropriate Data
API request handler.
Database security
The Report Framework handles database security. An authenticated Data API user has
access to all tables that the OA application can access on both real-time and historical
databases.
SSL Support for Data API Reference Client
Avaya OA 7.2 supports SSL functionality. This section contains information for allowing
the Data API Reference Client to connect to a Data Export Web Server over SSL (https).
This section contains information for the Windows platform. Same procedure is
applicable for Solaris and AIX.
Prerequisites
•
•
•
•
The client must use jdk/jre version 1.6.0_07 or higher.
The OA Web Server that hosts the Data Export web services is configured to
support SSL, That is, it contains the self signed certificates in the respective trust
store.
JWSDP 2.0 is installed and pre-configured.
All the environment variables have set as per the pre-requisites.
13
1. Unpack the DE SDK. Make appropriate changes to the code to use
SECURE_PROTOCOL (https) instead of PROTOCOL variable (http).
2. Change the PORT variable to use the configured secure port (default https port is
443).
3. Enter the appropriate HOSTNAME attribute value to be that of secure server IP.
4. Build the client (build.bat).
Importing the certificates
The Data Export Client being a non browser client requires a different way to import and
trust the server certificates. This section describes the procedure to import these server
certificates on to the client and is a prerequisite before running the Data API Reference
Client.
Perform the following only once for a particular certificate on a server.
To import the certificates:
1. On the command prompt, go to <DE_SDK_install_directory>\InstallCertSSL.
2. Run the following command on the command prompt:
Java –cp SunInstallCertDeApi.jar InstallCert <Server Host Name>:<Secure Port>
Note: The Server Host Name should coincide with the HOSTNAME entered in step 3 in the
previous procedure.
You may get an exception, specifically the javax.net.ssl.SSLHandshakeException.
This is the normal behavior of this utility. Successive imports against the same server
and the same certificate will not produce this error. The utility opens a connection to
the specified host and starts an SSL handshake. It prints the exception stack trace of
the error that occurred and also shows the certificates used by the server.
For Example, If the server sends one certificate, the following information appears.
Server sent 1 certificate(s):
1 Subject CN=punoasolsr007, OU=avaya.com, C=US
Issuer CN=punoasolsr007, OU=avaya.com, C=US
sha1
e4 18 49 8e 48 0c 35 ee a0 52 d8 50 50 b6 de 3d f4 fc 2f ff
md5
2f e1 9a 9a 9e a2 3f 59 c9 9e 5e dc eb 72 fc 46
3. Enter the certificate to add to trusted keystore.
For Example, 1
The server adds the certificate with a unique alias to the trusted keystore.
Note: Import the certificates for all the secure servers to which the Data API
Reference Client needs to connect. It will store the certificates for those servers in the
same trust store by the name jssecacerts, but with a different alias name for every
unique secure server.
To export data from OA data stores over https, you need to perform the following steps.
1. Copy the trust store created by name jssecacerts to <jdk_home>\jre\lib\security
directory along with other files.
14
2. Run the Data API Reference client by running the run.bat file and connect to the
secure server.
15
3.4 Query limitations
Access to data in OA is provided using the SQL query language. The limits of the SQL
support will be discussed below as they relate to both the real-time and the historical data
store.
From 7.2 going forward a new feature was added to provide a consolidated view of data
in the event that a system is configured with multiple real-time subsystems. This means
that if an single agent or service class exists in more than one real-time data store, the
result set returned from a query will have already consolidated the view of the data from
the separate data stores. For example, imagine that there is an installation with two realtime subsystems, subsystem “A” and subsystem “B”. There is work going on in both A
and B for service class “Gold”. In real-time subsystem “A” there were 40 workitems
forwarded and in subsystem “B” there were 60 workitems forwarded. Say that a query
was written to get the wkforwardedCnt for the “Gold” service class from the
svcClassSummary table:
SELECT wkForwardedcnt from svcClassSummary where svcclassid = 'Gold';
The result of this query would return a wkForwardedCnt of 100.
OA real-time SQL limitations
The spirit behind the Sql support for OA real-time subsystem is to do the following:
1. prevent destructive types of queries. Eg. DELETE, UPDATE, INSERT, DROP
TABLE, CREATE TABLE on any rows, columns or tables. The SQL support that is
provided allows for READ-ONLY access to data.
2. prevent queries that are computationally intensive and performance hindering. Eg.
ORDER BY, GROUP BY, aggregates (SUM, AVG, COUNT, MAX, MIN), sorting:
UPPER,LOWER and nested queries.
Real time data can be accessed using a basic SELECT statement with a WHERE clause.
The following are not supported: the “AS” keyword, and “SELECT *”. There is support
for table joins, as well as support for using table aliases. Whenever there are multiple
tables in the FROM clause, all columns in the SELECT statement must be qualified with
a table alias.
Example – the table schema below is only documented here as an example, it is not
intended to represent the table schema of an actual table in the product.
Student table schema
StudentId (PK)
StudentName
Enrollment table schema
CourseId (PK)
StudentId (PK)
16
Incorrect:
Select a.StudentId, StudentName, CourseId from Student a, Enrollment b where
a.StudentId = b.StudentId;
Correct:
Select a.StudentId, a.StudentName, b.CourseId from Student a, Enrollment b where
a.StudentId = b.StudentId;
Even though the CourseId and StudentName columns are not present in both tables, the
table alias still needs to be used in the Select statement.
Data Set Characteristics
A SQL query written against the real-time data store is represented as a DataSet. A
unique DataSet is defined by three different characteristics.
1. The SQL query statement – this can be any SQL SELECT statement that adheres
to the rules mentioned above.
2. The Time Window – this refers to one of the five different time windows that
have been administered for the real-time subsystem. There are five different time
windows, which are B, D1, D2, D3, and D4. B refers to the Base interval. The
base interval represents data that is accumulated for the current half hour. At the
end of each half hour interval, the data is sent to the Historical subsystem and
reset to zero in the real-time subsystem. D1 – D4 represent four different daily
intervals that can be administered to represent any twenty-four hour period of
time. Just as the Base interval data is cleared every half hour, the daily intervals
are cleared every twenty-four hours. The daily interval data is not sent to
historical at the end of each interval.
When a Time window is selected, the real-time subsystem will automatically
append the appropriate prefix to each of the interval columns specified in the
SELECT statement. The user should not append the Time Window prefix on any
column in the “Select” query statement as this will be done automatically. Here is
an example of how the SQL SELECT statement would be internally modified by
the real-time subsystem to return data for the correct Time Window.
SQL SELECT statement
Select agentlogin, onbreakdur from agentstate
TimeWindow
D4
Modified Statement
Select agentlogin, D4_onbreakdur from agentstate
The SELECT statement above only had one interval column, the “onbreakdur”.
The statement has been modified to get the data for the correct Time Window, the
D4 daily interval column. Since the “agentlogin” is not an interval column the
17
prefix is not appended to the column name. Notice that the initial SQL statement
did not have the Time Window prefix on the “onbreakdur” column. The Time
Window prefix should never be put on any column that is submitted to real-time
in a SQL query.
3. The Update Period – this represents the frequency with which the query should be
refreshed against the real-time data store.
OA historical data
The OA historical data store can contain data from multiple real-time sources. The data
within the store will be partitioned by sourceID. Data within the store can be viewed in
two different manners.
1. SQL queries can be written to provide a historical view of data in the historical
“h” tables from a single source. The “h” tables are tables that contain interval
data. An example of an “h” table would be the hSvcClassSummary table.
Getting data from a single sourceID can be accomplished by including a valid
sourceID in the where clause of the SQL statement.
2. SQL queries can also be written to provide a consolidated view of data in the
historical “h” tables across all real-time sources. Getting a consolidated view of
the data can be accomplished by including a sourceID of “0” (zero) in the where
clause of the SQL statement. The sourceID of “0” is a reserved sourceID that will
never be used to represent an actual real-time source; it will always represent the
consolidated view as it relates to historical data in the “h” tables.
Examples:
To get data from the hSvcClassSummary table that represents data for a single source
with a SourceID of 1:
SELECT SvcClassID, AbandAheadCnt FROM hSvcClassSummary WHERE ContainerID = 1
AND RowDate = 2003051412
AND StartTime = 0
AND SvcClassID = ‘12’
AND ResourceMgrID = N’2’
AND SourceID = 1;
To get data from the hSvcClassSummary table that represents a consolidated view of the
data across all sources:
SELECT SvcClassID, AbandAheadCnt FROM hSvcClassSummary WHERE ContainerID = 1
AND RowDate = 2003051412
AND StartTime = 0
AND SvcClassID = ‘12’
AND ResourceMgrID = N’2’
AND SourceID = 0;
Notice that the only difference between the two SQL statements shown above is the value
used to represent the SourceID. The fist example has a SourceID of 1; therefore the data
18
will only be for the real-time source that has a SourceID equal to 1. The second
statement has a SourceID of 0; therefore the data will be consolidated across all of the
real-time sources.
The historical store does not have any SQL limitations outside those imposed by the
chosen database vendor (eg Oracle, DB2, SQL Server).
3.5 Performance notes
The data API is intended to support only a few simultaneous data-extracting applications
due to OA system performance degradation caused by many simultaneous extractions.
This is particularly true when those applications access the real-time database.
For these reasons, this API would not be suitable for supporting an agent desktop display
since it would subject the system to a high volume of extractions. Displaying
dashboards/statistics on agent desktops could use a similar, but differently optimized,
API. The API described here would need to be modified/extended to pool the requests
from multiple agents together before sending them to the database. This API would also
be limited to extracting data from a small subset of the OA real-time database. These
changes would significantly reduce the load on the OA real-time databases and allow OA
to scale to the large number of agent desktops that are required.
The software doesn’t limit or control the number of accesses through the API. Customers
must apply judgment and may need to adjust or limit their accesses via the API to get
acceptable performance for API extractions and reports.
Performance testing will verify that:
• Historical data: the API shall be able to export 8 database items for each of 5000
service classes every 30 minutes with a response time no greater than 5 minutes
• Real-time data: Avaya OA 7.2 shall be able to export 9 database items for each
of 5000 agents every 30 seconds with a response time no greater than 10 seconds
Specifying the maximum number of rows returned
It is possible to configure the maximum number of rows that the Utility will return. This
is to prevent that very large queries affect performance of a live OA system. The default
maximum number of rows for both the real-time and historical databases is set to 5000
rows. They are both configurable by editing properties files as described below.
For real-time queries:
File: PABASE/data/admin/realtime/rt.properties
Entry: DATASET_ROW_LIMIT
Component that needs to be restarted: DataServer
How to restart: pa off dsvr, pa on dsvr.
Warning: Real-time reports will be interrupted when the DataServer is turned off
For historical queries:
19
File on Windows platforms: PABASE\stumbras\webapp\WEBINF\config\DataExport\DataExportService_Config.properties
File on Solaris: /usr/iplanet/servers/https-stumbras/webapp/WEBINF/config/DataExport/DataExportService_Config.properties
File on AIX:
/usr/WebSphere/AppServer/installedApps/BISCOTTI/OAReports.ear/stumbras.w
ar/WEB-INF/config/DataExportDataExportService_Config.properties
Entry: MaxNumberOfRows
Component that needs to be restarted: Report Framework (Stumbras)
How to restart: Follow instructions to start/stop the report framework in the
Installation and troubleshooting guide.
Warning: All reports will be interrupted when restarting the Report Framework
3.6 Data Model
The data model is available on the product DVD. Please refer to
PABASE/doc/DataModels/index.html on the OA host for details of real-time and
historical data models . PABASE is where the OA software is installed, typically /opt/BI
on Unix platforms, c:\Program Files\Avaya\BI on Windows platforms.
4. Real world example – Building your Data API client
4.1 Components needed for compilation
This is the list of files that you need to build your client
File(s)
Jwswp-2.0 directory
Build.bat
DataExportClient.xml
DataExportService.wsdl
DETestClient.java
Run.bat
Description
This is a 3rd party library that can be
obtained at java.sun.com.
Example build commands used to compile
this sample client.
This is a sample client XML configuration
file that is provided to demonstrate the
configuration needed to compile the clientside stubs.
This is the interface definition file provided
by Avaya. This is what the xrpcc uses to
generate the client-side stubs.
This is the sample client code.
This is the batch file used to run the sample
client.
20
4.2 Sequence diagrams
SnapshotExport sequence diagram
The diagrams below illustrate the sequence of events for a client that is using the
SnapshotExport interface.
Picture 2 is a diagram that represents the historical code from section 4.3. Picture 3
represents a one-time query of the real-time database. Note that the only difference
between Picture 2 and Picture 3 is the signature of the call to the SnapshotExport object.
: ClientMain
: DataExport
Service_Impl
: Snapshot
Export
St ub getSnaps hotE xportPort( )
Set URL and userid/password
properties on Stub
Narrow generic Stub into
a SnapshotExport Stub
String getHistoricalDelimitedText(String, String)
We now have the full string result. The client can
use it for specific processing, such as writing to
file or parsing for calculations.
21
Picture 2 – Initializing and getting historical data
: ClientMain
: DataExport
Service_Impl
: Snapshot
Export
Stub getSnapshotExportPort( )
Set URL and userid/password
properties on Stub
Narrow generic Stub into
a SnapshotExport Stub
String getRealTimeDelimitedText(String, String, String)
We now have the full string result. The client can
use it for specific processing, such as writing to
file or parsing for calculations.
Picture 3 – Initializing and getting real-time data snapshot
RealTimeUpdateExport sequence diagram
Picture 4 illustrates the sequence of events for a client that is using the
RealTimeEpdateExport interface.
22
: ClientMain
: DataExport
Service_Impl
: RealTime
UpdateExport
Stub getRealTimeUpdateExportPort( )
Set URL and userid/password
property on Stub
Narrow generic stub into a Real
TimeUpdateExport st ub
createDataSet(String, int, String)
getUpdateDelimitedText(String, String)
Loop this statement as
much as t he application
needs . Note that t he first
parameter is the dataset ID
t hat was obtained in the
createDataSet call.
deleteDataSet(String)
Picture 4 – Initializing and getting real-time data updates
4.3 Code examples
This simple java program illustrates how to initialize and call the snapshot and update
interfaces. The constants in the section titled “MUST CHANGE THOSE VALUES FOR YOUR
ENVIRONMENT” must be changed for the client to run properly.
//////////////////////////////////////////////////////////////////////////////
// Copyright (C) 2003, Avaya. All Rights Reserved.
// THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF AVAYA.
// The copyright notice above does not evidence any actual or intended
// publication of such source code.
//////////////////////////////////////////////////////////////////////////////
23
// Data API package imports
// These classes are generated by the xrpcc tool.
// The package name (rpcstubs in this case) is configured in the
// DataExportClient.xml file. It can be changed to fit your needs as
// long as the xml and these import statements use the same package name.
import rpcstubs.DataExportService_Impl;
import rpcstubs.BadArgumentException;
import rpcstubs.MethodUnavailableException;
import rpcstubs.RealTimeUpdateExport;
import rpcstubs.SnapshotExport;
import rpcstubs.TooManyResultsException;
// JAX-RPC imports
// These are the third party imports that you need for the client.
import javax.xml.rpc.Stub;
import javax.xml.transform.Result;
import javax.xml.transform.Source;
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerException;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.stream.StreamResult;
/**
* The DETestClient class is a sample client application that
* demonstrates calling the Data API Web Service. This is a simple
* application where many parameters are hardcoded. Typical client
* applications will use dynamic values for most of those constants.
* @author Christian Long
* @version 1.0
**/
class DETestClient
{
////////////////////////////////////////////////////////////////////////////
// These are constants that you do not want to change.
////////////////////////////////////////////////////////////////////////////
/* This is the non-secure http protocol. When using this, the data is
transmitted in the clear */
private final String PROTOCOL
= "http:";
/* Specifying the secure SSL protocol requires that your client uses
the web server certificate */
private final String SECURE_PROTOCOL
= "https:";
/* This constant is the path of the Data API service. Do not change that
value, otherwise the client application will not be able to
find the web service */
private final String DE_API_URL_PATH
= "/stumbras/dataexport/";
/* The name of the historical interface published by the web service */
private final String SNAPSHOT_SUFFIX
= "SnapshotExport";
/* The name of the real-time interface published by the web service */
private final String UPDATE_SUFFIX
= "RealTimeUpdateExport";
////////////////////////////////////////////////////////////////////////////
// MUST CHANGE THE VALUES FOR YOUR ENVIRONMENT
// These are constants that your program will need to set dynamically.
// They are fixed in this sample application to make the code easy to
// read. You must change them to realistic values for your environment
////////////////////////////////////////////////////////////////////////////
/* The host name of where the web service is published. You can specify
the IP address or any name that can be resolved to the IP of the
report framework. You can also use "localhost" if this client runs
on the same host as the report framework */
private final String HOSTNAME
= "YourReportServerHost";
/* This is the web server port number. It is set to 8999 on
Windows platforms for non-secure channels (non-SSL). SSL usually uses
port 443. These are decided when you install the web server */
private final String PORT
= "8999";
/* This string is the URL of the web service root. The resulting string is
"http://montreal:8999/stumbras/dataexport/".
The final URL, with the name of the interface, is constructed dynamically
in the code based on whether the user makes a historical or real-time
query */
24
private final String DE_API_URL_PREFIX = PROTOCOL
+ "//"
+ HOSTNAME
+ ":"
+ PORT
+ DE_API_URL_PATH;
/* This is a sample query against the historical database */
private final String HISTORICAL_QUERY = "select * from dcProperty";
/* This is a sample query against the real-time database */
private final String REALTIME_QUERY
=
"select agentname, agentstatename from agentstate";
/* This is the username used to authenticate this client. The users are
defined and verified on the report framework host. The example below
shows a user id "joe" that is defined on a domain "mydomain" */
private final String WINDOWS_USERNAME = "biadmin";
/* This is where you dynamically put the user password. Obviously, the
userid and the passwords should not be hardcoded like this. A command-line
parameter or an encrypted file may be used to specify the userid and
password */
private final String WINDOWS_PASSWORD = "biadmin";
/* The delimiter is used to separate columns in the result string */
private final String DELIMITER
= ":";
/* This time window can be one of "B", "D1", "D2", "D3" or "D4". They
are used for the real-time query */
private final String TIME_WINDOW
= "D1";
/* The update period of the real-time query is the time that will elapse
between real-time data updates */
private final int
UPDATE_PERIOD
= 5;
/* This is how many times the real-time updates will be pulled from
the server */
private final int
NUMBER_OF_UPDATES = 5;
/**
* Typical main method for this sample application. It instantiates
* an instance of this class and calls the real-time or historical
* methods based on the command-line parameter.
* Usage: run <h|r>
*
where run is the batch file that starts this application
*
h specifies that a historical query will be performed
*
r specified that a real-time query will be performed
* @param aArgs is a string array that contains the command-line parameters
* @return void
**/
public static void main(String[] aArgs)
{
System.out.println("Starting Data Export Example Client");
// Instantiate the class
DETestClient client = new DETestClient();
// Must have an argument, just make sure of it
if (aArgs.length==0)
{
System.out.println("Usage: run <h|r>");
System.exit(-1);
}
// Parse the arguments
if (aArgs[0].equals("h"))
{
System.out.println("Running historical example");
client.runHistoricalExample();
}
else if (aArgs[0].equals("r"))
{
System.out.println("Running real-time example");
client.runRealTimeExample();
}
else
{
System.out.println("Usage: run <h|r>");
System.exit(-1);
}
25
System.out.println("Exiting Data Export Example Client");
}
/**
* Default constructor that really doesn't do much
**/
DETestClient()
{
}
/**
* This method initializes the historical client side stubs, makes
* the remote SOAP call and flushes the result to stdout.
**/
private void runHistoricalExample()
{
// Our generic XML RPC stub.
Stub stub = null;
try
{
// Instantiate the Data API snapshot stub
stub = (Stub) (new DataExportService_Impl().getSnapshotExportPort());
// Set the URL and userid/password. Note that the URL contains the
// base path described in the constants and the name of the
// historical interface. The snapshot suffix can also be used
// to get real-time information if you only need it once. If you
// need real-time updates, you need to use the other interface
// sampled in runRealTimeExample()
String webServiceURL = DE_API_URL_PREFIX + SNAPSHOT_SUFFIX;
System.out.println("Setting properties for URL " + webServiceURL);
stub._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY,
webServiceURL);
stub._setProperty(Stub.USERNAME_PROPERTY, WINDOWS_USERNAME);
stub._setProperty(Stub.PASSWORD_PROPERTY, WINDOWS_PASSWORD);
// This narrows the generic stub into the SnapshotExport stub that
// was generated by the xrpcc tool. Then the remote call is made
// to get a delimited text result. The result contains the column
// names and all the rows that satisfy HISTORICAL_QUERY. Note that
// you could call getHistoricalXML to get results encoded in a
// string with XML tags
System.out.println("Making call to API");
String response = "";
response =
((rpcstubs.SnapshotExport) stub).
getHistoricalDelimitedText(HISTORICAL_QUERY,
DELIMITER);
// Send the result to stdout
System.out.println("Query result:");
System.out.println(response);
}
catch (Exception e)
{
// This is very simplistic exception handling. You should refer
// to the interface definition to handle specific exceptions.
System.out.println("Exception getting historical data: "
+ e
+ ". \nMessage: "
+ e.getMessage());
}
}
/**
* This method initializes the real-time update client side stubs, makes
* the remote SOAP call and flushes the result to stdout.
**/
private void runRealTimeExample()
{
// Our generic XML RPC stub.
26
Stub stub = null;
try
{
// Instantiate the Data API update stub
stub = (Stub)
(new DataExportService_Impl().getRealTimeUpdateExportPort());
// Set the URL and userid/password. Note that the URL contains the
// base path described in the constants and the name of the
// real-time update interface.
String webServiceURL = DE_API_URL_PREFIX + UPDATE_SUFFIX;
System.out.println("Setting properties for URL " + webServiceURL);
stub._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY,
webServiceURL);
stub._setProperty(Stub.USERNAME_PROPERTY, WINDOWS_USERNAME);
stub._setProperty(Stub.PASSWORD_PROPERTY, WINDOWS_PASSWORD);
// This narrows the generic stub into the RealTimeUpdateExport stub
// that was generated by the xrpcc tool. Then the remote call is made
// to create a dataset in the report framework.
// The result is a dataset ID that will be used later to pull the
// updated data from the web service.
String response = "";
String dataSetID =
((rpcstubs.RealTimeUpdateExport) stub).
createDataSet(REALTIME_QUERY, UPDATE_PERIOD, TIME_WINDOW, false);
// This loop retrieves the data from the web service. The dataset ID
// obtained earlier is used to identify the data to retrieve.
System.out.println("Getting " + NUMBER_OF_UPDATES + " updates");
for (int i = 0; i < NUMBER_OF_UPDATES; i++)
{
response =
((rpcstubs.RealTimeUpdateExport) stub).
getUpdateDelimitedText(dataSetID,
DELIMITER);
System.out.println("Query result(" + i + "):");
System.out.println(response);
Thread.sleep(UPDATE_PERIOD * 1000);
}
// We are done with the dataset. Cleanup so the web service knows
// that it doesn't need to maintain that information anymore.
((rpcstubs.RealTimeUpdateExport) stub).deleteDataSet(dataSetID);
}
catch (Exception e)
{
// This is very simplistic exception handling. You should refer
// to the interface definition to handle specific exceptions.
System.out.println("Exception getting real-time data: "
+ e
+ ". \nMessage: "
+ e.getMessage());
}
}
}
4.4 Code compilation
The batch file build.bat is provided to compile the client code. To compile, set the
environment variables described in the batch file below and type build.bat in a
Command Prompt, in the directory where you copied the SDK files.
@echo off
REM //////////////////////////////////////////////////////////////////////////////
REM // Copyright (C) 2003, Avaya. All Rights Reserved.
REM // THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF AVAYA.
27
REM // The copyright notice above does not evidence any actual or intended
REM // publication of such source code.
REM //////////////////////////////////////////////////////////////////////////////
REM
REM
REM
REM
REM
REM
REM
REM
REM
Must set OA_JARS first. This is the directory where the report framework
jars are located. Typical location on a Windows report server is
C:\Program Files\Avaya\BI\stumbras\webapp\WEB-INF\lib
The Java Web Service Developer Pack must also be installed in
order to compile a java web client. That library can be downloaded
from java.sun.com.
Example of JWSDP_HOME: D:\Sun\jwsdp-2.0
Example of OA_JARS: c:\Program Files\Avaya\BI\jars
if "%OA_JARS%"=="" GOTO ERROR
if "%JWSDP_HOME%"=="" GOTO ERROR
REM
SET
SET
SET
SET
SET
REM
Set the classpath
CP=.
CP=%CP%;%OA_JARS%\jaxrpc-api.jar
CP=%CP%;%OA_JARS%\jaxrpc-impl.jar
CP=%CP%;%OA_JARS%\jaxp-api.jar
CP=%CP%;%OA_JARS%\xalan.jar
SET CP=%CP%;./demo
REM first call wscompile to generate the client-side stubs that we need. The xml file
REM describes the WSDL file name (provided by AVAYA) and the package name that
REM you want to use for the client stubs. In this example, they will go under ./rpcstubs.
REM An example client XML (DataExportCLient.xml) file is provided by Avaya.
REM After the stubs are generated and compiled, use javac to compile your client.
echo on
call %JWSDP_HOME%/jaxrpc/bin/wscompile.bat -classpath "%CP%" -d . –gen:client -keep
DataExportClient.xml
call javac -classpath "%CP%" DETestClient.java
goto EXIT
:ERROR
ECHO Environment variable not set.
:EXIT
5. Real world example – Testing your Data API client
5.1 Components needed for runtime
You need the code compiled in the previous section and a working installation of OA to
run the sample client.
The batch file run.bat is provided to assist you in running the sample client. To run, set
the environment variable described in the batch file below and type run.bat h or run.bat
r in a Command Prompt, in the directory where you copied the SDK files.
@echo off
REM
REM
REM
REM
REM
REM
//////////////////////////////////////////////////////////////////////////////
// Copyright (C) 2003, Avaya. All Rights Reserved.
// THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF AVAYA.
// The copyright notice above does not evidence any actual or intended
// publication of such source code.
//////////////////////////////////////////////////////////////////////////////
REM OA 3rd party jar files need to be in the classpath. If you install OA, the
REM jar files needed to run the client will be located under this directory:
REM c:\Program Files\Avaya\BI\jars
28
if "%OA_JARS%"=="" GOTO ERROR
REM
SET
SET
SET
SET
SET
SET
SET
SET
SET
SET
SET
All these jars are needed for the JAX-RPC calls.
CP=.
CP=%CP%;%OA_JARS%\jaxrpc-api.jar
CP=%CP%;%OA_JARS%\jaxrpc-impl.jar
CP=%CP%;%OA_JARS%\saaj-api.jar
CP=%CP%;%OA_JARS%\saaj-impl.jar
CP=%CP%;%OA_JARS%\jaxp-api.jar
CP=%CP%;%OA_JARS%\sax.jar
CP=%CP%;%OA_JARS%\dom.jar
CP=%CP%;%OA_JARS%\mail.jar
CP=%CP%;%OA_JARS%\activation.jar
CP=%CP%;%OA_JARS%\jsr173_api.jar
REM This starts your client application. It also passes the first
REM command-line parameter that can be one of "r" or "h".
echo on
"java" -classpath "%CP%" DETestClient %1
5.2 Expected results
Running the example historical query, you should get a result similar to this. The data
will be different but the rest should be the same:
run h
Starting Data Export Example Client
Running historical example
Setting properties for URL http://montreal:8999/stumbras/dataexport/SnapshotExport
Making call to API
Query result:
dcservice_id:service_name:name:value
2:fwdagent
2:fwdagent
2:fwdagent
2:fwdagent
2:fwdagent
2:fwdagent
2:fwdagent
2:fwdagent
11:dm
11:dm
:direct:true
:fwdbuff:1
:ksize:2000000
:maxsize:2000000
:minsize:500
:recorderhosts:montreal
:sources:1
:storage:data/forwarder
:CONTEXT:0
:SOURCE_ID:1
Exiting Data Export Example Client
Running the real-time example, you will get a result similar to this:
run r
Starting Data Export Example Client
Running real-time example
Setting properties for URL http://montreal:8999/stumbras/dataexport/RealTimeUpdateExport
Getting 5 updates
Query result(0):
AGENTNAME:AGENTSTATENAME:B:D1
Query result(1):
AGENTNAME:AGENTSTATENAME:B:D1
Query result(2):
AGENTNAME:AGENTSTATENAME:B:D1
Query result(3):
AGENTNAME:AGENTSTATENAME:B:D1
Query result(4):
AGENTNAME:AGENTSTATENAME:B:D1
29
Exiting Data Export Example Client
5.3 Troubleshooting the API and your client
[todo: This section is not complete]
Symptom
Service not responding to browser
Authentication failing
Interface not available
Potential cause/solution
Report framework not started
Wrong address
Bad user/password
Historical OA processes not running
RTPA, Dbpool didn’t initialize properly
30