DataAccess concepts and terminology

These concepts and terminology are central to working with the DataAccess API.

Informational Query

DataAccess lets you execute informational queries called InfoQs. An InfoQ processes a request and returns information, called datasets, that is not visible on the portal to the end user. The InfoQ could retrieve data sets from several RDBMS, from a file, from RMI calls, and so on. You can then determine how you want to use or display this information.

For example, you could use InfoQs to create customized, value-added datasets to display on the portal or to populate spreadsheets.

Requests

Requests are in the form of an HTTP GET operation. Unless otherwise directed, use the following URL syntax when making InfoQ requests:

XML Request (returns datasets in XML format)
http://host[:port]/database/PROVISO/DataView/Query.xml
CSV Request (returns line-separated data for export to an application like an Excel spreadsheet)
http://host[:port]/database/PROVISO/DataView/Query.csv

The InfoQ and it arguments are added to the URL after the query type. For example, the following XML request calls the DVRuserDesc InfoQ with one argument, userNames=SSSW\\Miguel:
http://host[:port]/database/PROVISO/DataView/Query.xml?queryType=DVRuserDesc&userNames=SSSW\\Miguel

Security

The DataView component provides security through the authentication of a user and through authorization of the request. Either a session login through the portal or server login is required before using Tivoli® Netcool® Performance Manager DataAccess. After authentication occurs, subsequent requests to Tivoli Netcool Performance Manager DataAccess do not require authentication as long as the session timeout has not occurred.

Most requests are authorized based on the user's authorization to view the group or groups specified in the request. However, some queries do not require a group identifier and are therefore not checked for the user's authorization. The user authorization to run a request is always checked as part of the HTML Report request.

The authorization of DataAccess requests was introduced in Tivoli Netcool/Proviso Version 4.3.1. If you have upgraded from an earlier release, you may need to authorize the user, used to access DataAccess, to access all of the groups in your deployment. For more information, contact your Tivoli Netcool Performance Manager representative.

Date and Time

By default, date and time specifications are in GMT, unless another time zone is defined. The date/time format for URL strings must be given in the following format: yyyy.MM.dd.HH.mm.ss

The dateFormat InfoQ parameter can overwrite the default date format.

The value of the dateFormat parameter is a string that conforms to the java.text.SimpleDateFormat formatting specifications. If, for example, you specify dateFormat=e, the date/times since January 1, 1970 are specified as milliseconds.

Return Codes

Return codes are text and numeric messages that indicate the exit status of the request. This table shows the supported return codes.

Return Code	Description
`SC_OK (200)`	The request was successful and XML was returned. Note that if the dataset is empty, no rows are returned.
`SC_BADREQUEST (400)`	No XML is generated, because the server did not understand the request.
`SC_UNAUTHORIZED (401)`	No XML is generated, because the requester does not have the appropriate privileges.
`SC_FORBIDDEN (403)`	No XML is generated. User does not have a DataAccess license or is not logged in.