This chapter provides detailed reference information for the following Discoverer Web Services API.
This API is used to establish a secure connection to Discoverer Web Services for Oracle E-Business Suite (EBS) users.
This API call accepts the APP_SECURE ticket, Connection string, name of the EUL, and LocaleBean information and returns a unique SessionKey, which is then passed to all other API calls.
| API | Details |
|---|---|
| Method |
Public SessionKey AppsConnect(ticket,ConnectStr,eul,locale) { }
|
| Input: |
|
| Output |
|
| Exceptions |
|
The following table lists the fields of the structures.
| Structure | Fields |
|---|---|
| Ticket |
|
| ConnectString |
|
| DiscoEulName |
|
| LocaleBean |
|
This API call obtains a list of connections. It accepts SessionKey and returns the Connection list object. In single sign-on mode the list of public connections and private connections is returned. The connection can be of type Relational, OLAP, or APPS.
| API | Details |
|---|---|
| Method |
Public ConnectionList getConnectionList(SessionKey aSessionKey) { }
|
| Input: |
|
| Output |
|
| Exceptions |
|
The following table lists the fields of the structures.
| Structure | Fields |
|---|---|
| ConnectionList |
|
| Connection |
|
| ConnectionName |
|
| ConnectionKey |
|
| ConnectionDescription |
|
| ConnectionEUL |
|
| ConnectionDBIdentifier |
|
| ConnectionAccessType |
|
This API call uses a connection to obtain the list of non-scheduled workbooks and FolderEntries. It accepts SessionKey, ConnectionKey, and FolderEntrypath and provides a list of non-scheduled workbooks and FolderEntries data that is accessible from the connection for the FolderEntrypath. The list of non-scheduled workbooks includes all of the shared workbooks for the database user that was used in the connection.
When the connection is to relational data, workbooks are stored in a single level in the EUL. The only valid value for FolderEntrypath is “”. An empty string specifies the root folder entry in both Discoverer Plus Relational and Discoverer Plus OLAP.
When the connection is to OLAP data, FolderEntries and Workbooks are stored in the Discoverer Catalog. There can be multiple levels of FolderEntries, which can be queried by providing the appropriate FolderEntryPath. Clients must make successive calls to this method to browse FolderEntries.
| API | Details |
|---|---|
| Method |
Public FolderEntryList getFolderEntryList(SessionKey aSessionKey,
ConnectionKey aCkey, FolderEntrypath fpath ) { }
|
| Input: |
|
| Output |
|
| Exceptions |
|
The following table lists the fields of the structures.
| Structure | Fields |
|---|---|
| FolderEntryList |
|
| FolderEntry |
|
| FolderEntryName |
|
| FolderEntryPath |
|
| FolderEntryDescription |
|
| FolderEntryType |
|
| WorkbookKey |
|
This API call obtains the layout metadata for a selected worksheet. It accepts SessionKey and WorksheetKey, and it provides the Layout information for the worksheet that is identified by WorksheetKey.
| API | Details |
|---|---|
| Method |
Public Layout getLayoutMetaData(SessionKey aSessionKey,
WorksheetKey aWorksheetKey ) {}
|
| Input: |
|
| Output |
|
| Exceptions |
|
The following table lists the fields of the structures.
| Structure | Fields |
|---|---|
| Layout |
|
| Dimension |
|
| Measure |
|
This API call obtains the parameter metadata for a selected worksheet. It accepts SessionKey and WorksheetKey and provides the list of parameters for the specified worksheet that is identified by WorksheetKey
| API | Details |
|---|---|
| Method |
Public ParameterList getParameterMetaData(SessionKey aSessionKey,
WorksheetKey aWorksheetKey ) {}
|
| Input: |
|
| Output |
|
| Exceptions |
|
The following table lists the fields of the structures.
| Structure | Fields |
|---|---|
| ParameterList |
|
This API call obtains the parameter LOVs using a ParameterKey. It accepts SessionKey, ParameterKey, and numValues and provides the list of values (LOVs). You call this method for parameters that have LOVs. The LOVs are retrieved in chunks (the size is specified by numValues), and you can page through from start to finish in one direction only; there is no bi-directional paging support of parameters. The client application is responsible for caching the parameters.
| API | Details |
|---|---|
| Method |
Public ParameterValueList getParameterValueList(SessionKey
aSessionKey, ParameterKey aParamKey, int numValues){ }
|
| Input: |
|
| Output |
|
| Exceptions |
|
| Notes |
|
The following table lists the fields of the structures.
| Structure | Fields |
|---|---|
| ParameterValueList |
|
This API call obtains the parameter LOVs using a ParameterKey and ParameterSelectList. It accepts SessionKey, ParameterKey, numValues, and ParameterSelectList and provides the list of values (LOVs) in the cascading style. In cascading parameters, the LOVs of one parameter depends on the value selected for the preceding parameter in the worksheet. The LOVs are retrieved in chunks (the size is specified by numValues), and you can page through from start to finish in one direction only; there is no bi-directional paging support of parameters. The client application is responsible for caching the parameters.
| API | Details |
|---|---|
| Method |
Public ParameterValueList getCascadeParameterValueList(SessionKey
aSessionKey, ParameterKey aParamKey, int numValues, ParameterSelectList pselectList){ }
|
| Input: |
|
| Output | ParameterValueList |
| Exceptions |
|
The following table lists the fields of the structures.
| Structure | Fields |
|---|---|
| ParameterValueList |
|
This API call returns the status of the query, such as executing or canceled. It accepts SessionKey and QueryKey.
| API | Details |
|---|---|
| Method |
Public QueryStatus getQueryStatus(SessionKey aSessionKey,
QueryKey aQueryKey){ }
|
| Input: |
|
| Output |
|
| Exceptions |
|
The following table lists the fields of the structures.
| Structure | Fields |
|---|---|
| QueryStatus |
Status is one of the following:
|
This API call provides the web service component version. Any change in the web service interface or API causes the version number to change. Use the version number to assist you in determining the functionality that is available for the web service.
| API | Details |
|---|---|
| Method |
Public String getVersion( ) { }
|
| Input: |
|
| Output |
A version of 1.0 implies support for integration with Oracle BI Publisher. A version of 2.0 implies support for integration with Oracle BI Publisher and interoperability with Oracle BI Enterprise Edition. |
| Exceptions |
|
This API call provides the URL of the Discoverer Viewer instance that is hosted on the same machine as the web service. This URL can be used by clients to launch Discoverer Viewer from within their application.
| API | Details |
|---|---|
| Method |
Public String getViewerURL(SessionKey aSessionKey,
WorksheetKey aWorksheetkey, List aParameteSelectList){ }
|
| Input: |
|
| Output |
|
| Exceptions |
|
This API call accepts SessionKey and QueryKey and provides the worksheet data in the format type that is specified in QueryOption in the submitWorksheetQuery method. If the result set is large and is Rowset XML, then by default, 25 rows of data are returned. For other format types, 1MB of data is returned. You can page through the remaining data by calling this method repeatedly. If the finished flag in QueryResults is false , then call the method again to continue paging through the data. You can page through from start to finish in one direction only; there is no bi-directional paging support.
| API | Details |
|---|---|
| Method |
Public QueryResult getWorksheetData(SessionKey aSessionKey,
QueryKey aQueryKey){ }
|
| Input: |
|
| Output |
|
| Exceptions |
|
The following table lists the fields of the structures.
| Structure | Fields |
|---|---|
| QueryResult |
|
The following table describes the export types.
| Export type | Relational | OLAP |
|---|---|---|
| HTML | HTML file is zipped and base64 encoded before transfer. | HTML file is zipped and base64 encoded before transfer. |
| PDF file is base64 encoded before transfer. | PDF file is base64 encoded before transfer. | |
| XLS | XLS file is base64 encoded before transfer. Similar to Discoverer Viewer, graphs are not exported. | XLS file is zipped in base64 encoded before transfer. Graphs are exported. |
For HTML, PDF, and XLS export types
If the worksheet does not have page items, then all the data is exported.
If the worksheet has page items, the output is different for OLAP and Relational connections as follows:
For Relational connections:
HTML, PDF, and XLS export types - Returns worksheet data for the page items selected in the worksheet.
For OLAP connections:
XLS export types - Returns worksheet data for all combination of page item values.
HTML or PDF export types - Returns worksheet data for the selected page item.
This export behavior is similar to Viewer with the exception that the "isCurrentPageItemsExportForOLAP" setting in the configuration.xml file is not respected.
<BIData>
<Query id="1">
<PAGE>
<ROWSET>
<ROW>
<Dimension L="Time Dimension Values">1996</D>
< Dimension L="Product Dimension Values">TOTALPROD</D>
< Dimension L="Geography Dimension Values">WORLD</D>
< Dimension L="Channel Dimension Values">TOTALCHANNEL</D>
<Measure L="Dollar Sales">1.18247112042864E8</M>
<Measure L="Quota">5475441.87541972</M>
</ROW>
<ROW>
< Dimension L="Time Dimension Values">1997</D>
< Dimension L="Product Dimension Values">TOTALPROD</D>
< Dimension L="Geography Dimension Values">WORLD</D>
< Dimension L="Channel Dimension Values">TOTALCHANNEL</D>
<Measure L="Dollar Sales">4.64121127850704E7</M>
<Measure L="Quota">2917189.84519184</M>
</ROW>
</ROWSET>
</PAGE>
</Query>
</BIData>
This API call accepts SessionKey and WorkbookKey and provides the list of worksheets within a workbook that is specified in WorkbookKey.
| API | Details |
|---|---|
| Method |
Public WorksheetList getWorkSheetList(SessionKey aSessionKey, WorkbookKey aWorkbookKey ) {}
|
| Input: |
|
| Output |
|
| Exceptions |
|
The following table lists the fields of the structures.
| Structure | Fields |
|---|---|
| WorksheetList |
|
| Worksheet |
|
| WorksheetName |
|
| WorksheetKey |
|
This API call accepts a SessionKey and returns a Boolean value that indicates whether the specified session is valid.
| API | Details |
|---|---|
| Method |
Public boolean isSessionValid( SessionKey sKey ) { }
|
| Input: |
|
| Output |
|
| Exceptions |
|
This API call provides a mechanism for user identity propagation between the client application and the Discoverer Web Services. Authentication occurs during every invocation of the Discoverer Web Services. For more information, see "About authentication and authorization".For every login made by a client application, the Discoverer Web Services create a new Discoverer user session and allocate it to the user.This API call accepts UserCredential and LocaleBean information and returns a unique SessionKey, which is then passed to all other API calls. This API call does not create a new HTTP session if a session exists between the client application instance and the Discoverer Web Services.
| API | Details |
|---|---|
| Method |
Public SessionKey login(UserCredential aUserCredential, LocaleBean aLocale) { }
|
| Input: |
|
| Output |
|
| Exceptions |
|
The following table lists the fields of the structures.
| Structure | Fields |
|---|---|
| LocaleBean |
|
| UserCredential |
|
| Identifier |
|
| DisplayName |
|
| SessionKey |
|
This API call informs the Discoverer Web Services API about the completion of the user session. This call frees the dedicated Discoverer session that was associated with the user session and returns the Discoverer session to the session pool.
| API | Details |
|---|---|
| Method |
Public void logout(SessionKey aSessionKey ) { }
|
| Input: |
|
| Output |
|
| Exceptions |
|
This API call cancels a query request and removes the resources that are associated with that request. Call this method for queries that have been submitted but whose data has not yet been fetched. If the query data has been fetched, then the resources are removed. This asynchronous API call returns immediately.
| API | Details |
|---|---|
| Method |
Public Void requestQueryCancel(SessionKey aSessionKey, QueryKey){ }
|
| Input: |
|
| Output |
|
| Exceptions |
|
This API call submits the query for the specified worksheet for execution. This asynchoronous API call returns immediately, without waiting for the query execution to complete.
| API | Details |
|---|---|
| Method |
Public QueryKey submitWorksheetQuery(SessionKey aSessionKey, WorksheetKey aWorksheetkey, List aParameteSelectList, QueryOption aQueryOption){ }
|
| Input: |
|
| Output |
|
| Exceptions |
|
The following table lists the fields of the structures.
| Structure | Fields |
|---|---|
| QueryKey |
|
| ParameterSelect |
|
| QueryOption |
|
| LocaleBean |
Valid types are:
|