Skip Headers
Oracle® Fusion Middleware Integrator's Guide for Oracle Business Intelligence Enterprise Edition
11g Release 1 (11.1.1)

Part Number E16364-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

2 Description of Structures in Oracle BI EE Web Services

This chapter describes the structures used by the Oracle Business Intelligence session-based Web services.

This document uses JavaScript-like syntax to describes structures. The exact syntax and implementation depends on the SOAP code generation tool and the target language used by your application development environment.

This chapter includes the following sections:

This chapter contains the following sections:

2.1 AccessControlToken Structure

Use this structure to describe permissions granted to a specific account in the access control list. This structure is used in the"SecurityService Service".

Table 2-1 lists the fields in this structure.

Table 2-1 AccessControlToken Structure Fields

Fields Description

Account account

Specifies a reference to the Account structure.

int permissionMask

Specifies a combination of the following flags:

1 = Permission to read item content

2 = Permission to traverse directory

4 = Permission to change item content

8 = Permission to delete an item

16 = Permission to assign permissions to other accounts

32 = Permission to take ownership of the item

2048 = Permission to run an Oracle BI Publisher report live

4096 = Permission to schedule an Oracle BI Publisher report

8192 = Permission to view output from an Oracle BI Publisher report


2.2 Account Structure

Use this structure to hold user names or group names. It has a flag to indicate whether the name is a user or a group. This structure is used in the "SecurityService Service".

Table 2-2 lists the fields in this structure.

Table 2-2 Account Structure Fields

Fields Description

String accountName

Specifies an account name or group name.

int accountType

Specifies whether the account is a user or a group or both (0 = user, 1 = catalog group, 2 = app role, 3 = all).

Note the following information for advanced use of this field. If accountType is greater than or equal to 4, the system treats the Name or GUID as a pattern. Namely, accountType may be 4 for fetching users, 5 for fetching cat groups, 6 for fetching app roles, 7 all pattern. Using this field in this way can be expensive, slow, and result in the system returning many records. When receiving an Account, both Name and GUID are set. The accountType will be 0 for user, 1 for catalog group, 4 for application role.

String GUID

Specifies the unique ID which identifies the account.


2.3 ACL Structure

Use this structure to hold the access control list (ACL). This structure is used in the "SecurityService Service".

Table 2-3 list the fields in this structure.

Table 2-3 ACL Structure Fields

Fields Description

AccessControlToken[] accessControlTokens

Specifies the full list of permissions.

String dummy

For internal purposes.


2.4 ArrayofGUIDS Structure

Use this structure to specify a list of GUIDs representing a saved result set. This structure is used in the "SecurityService Service".

Table 2-4 lists the field in this structure.

Table 2-4 ArrayofGUIDS Structure Fields

Fields Description

String[] guid

Specifies a list of GUIDs representing the saved result set.


2.5 AuthResult Structure

Use this structure to specify authorization details during an authentication. This structure is used in the "SecurityService Service" (in the "impersonateex() Method" and "logonex() Method").

Table 2-5 lists the fields in this structure.

Table 2-5 AuthResult Structure Fields

Fields Description

String sessionID

Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

boolean authCompleted

If set to TRUE, then the authorization is complete. If set to FALSE, then the authorization process is in progress and the logonex or impersonatex process should be called again.


2.6 CatalogItemsFilter Structure

Use this structure to filter catalog items and changes based on the path and timestamp. This structure is used in the "ReplicationService Service".

Table 2-6 lists the fields in this structure.

Table 2-6 CatalogItemsFilter Structure Fields

Fields Description

String[] items

Specifies the list of folders and their descendants to include in the filter. If this value is null, then all nodes in the catalog are included.

Calendar from

Specifies the time period on which to filter. Only items and changes with timestamps within that period satisfy the filter. Either or both of those fields could be null, in which case corresponding bound is considered not set.

Calendar to

Specifies the time period on which to filter. Only items and changes with timestamps within that period satisfy the filter (from <= timestamp <= to). Either or both of those fields could be null, in which case the corresponding bound is considered not set.


2.7 CatalogObject Structure

Use this structure to retrieve or specify all information for a particular catalog object in a single method. This structure is used in the "WebCatalogService Service".

Table 2-7 lists the fields in this structure.

Table 2-7 CatalogObject Structure Fields

Fields Description

String catalogObject

Specifies an XML representation of the object.

catalogObjectBytes

Specifies the returned content of the catalog object as string or bytes. What you specify in this field is determined by the readObjects method.

ItemInfo itemInfo

Specifies catalog information about the object, supplied in the ItemInfo common structure.

For information about the ItemInfo structure, see Section 2.11, "ItemInfo Structure".

ErrorInfo errorInfo

Specifies the level of error information to be supplied as specified by the ErrorDetails argument in the readObjects method.


2.8 ErrorInfo Structure

Use this structure to retrieve error information during Presentation Catalog Service method invocations. This structure is used in the "WebCatalogService Service".

Table 2-8 lists the fields in this structure.

Table 2-8 ErrorInfo Structure Fields

Fields Description

String code

Specifies the error code to display.

String context

Specifies the service and method in which the error occurred.

String details

Specifies detailed information about the error.

String message

Specifies a human-readable description of the error.


2.9 GetSubItemsParams Structure

Use this structure to contain optional parameters used in a getSubItems method. This structure is used in the "WebCatalogService Service".

Table 2-9 lists the fields in this structure.

Table 2-9 GetSubItemsParams Structure Fields

Fields Descriptions

GetSubItemsFilter filter

For internal use only.

boolean includeACL

If set to TRUE, then ACL information is included in the resulting ItemInfo structures.

int withPermission and int withPermissionMask

Specifies that you want to filter the resulting items collection by access level. The only items included in the result are those for which the following expression is true:

(itemPermission & withPermissionMask) = (withPermission & withPermissionMask)

where itemPermission is a combination of permission flags for the current catalog item.

int withAttributes and

int withAttributesMask

Specifies that you want to filter the resulting items collection by attribute flags. The only items included in the result are those for which the following expression is true:

(itemAttributes & withAttributesMask) = (withAttributes & withAttributesMask)

where itemAttributes is a combination of attribute flags for the current catalog item.


2.10 ImportError Structure

Use this structure to describe the cause of a failure during an import. This structure is used in the "ReplicationService Service".

Table 2-10 lists the fields in this structure.

Table 2-10 ImportError Structure Fields

Fields Description

String item

Specifies the path to the changed item. For example, /users/jchan/analyses/.

String operation

For internal use only.

String catalogError

Specifies an error string, describing the reason for the failure.

String file

Specifies in which file the error occurred.

String line

Specifies the line in which the error occurred.


2.11 ItemInfo Structure

Use this structure to contain catalog information about an object. This structure is used in the "WebCatalogService Service".

Table 2-11 lists the fields in this structure.

Table 2-11 ItemInfo Structure Fields

Fields Description

String path

Specifies the path to the object in the catalog. For example, /users/jchan/analyses/.

ItemInfoType type

Specifies a character string that indicates the type. Valid values are:

  • Folder

  • Link

  • Missing

  • NoAccess

  • Object

String caption

Specifies the localized name of the object in the catalog. For example, in French, 'My Folders' is displayed as 'Mes Dossiers'.

int attributes

Specifies a combination of the following flags:

1 = read only 2 = archive 4 = hidden 8 = system

Calendar lastModified

Specifies the date and time that the object was last modified, in Calendar format.

Calendar created

Specifies the date and time that the object was created (saved) in the catalog, in Calendar format.

Calendar accessed

Specifies the data and time that the object was last accessed by a user, in Calendar format.

String signature

Specifies the signature of the catalog object.

NameValuePair[] itemProperties

Specifies an array of object properties.

ACL aclXX

Specifies the Access Control List for this catalog item.

Account owner

Specifies the owner of the object.

String targetPath

If the ItemInfoType field is set to "Link," this field specifies the target path for the object.


2.12 NameValuePair Structure

Use this structure to denote named properties, such as COLOR=RED. This structure is used in the "WebCatalogService Service".

Table 2-12 lists the fields in this structure.

Table 2-12 NameValuePair Structure Fields

Fields Description

String name

Specifies a character string that contains the name of the property, such as COLOR.

String value

Specifies a character string that contains the value, such as RED.


2.13 PathMap Structure

Use this structure to specify the location to which you want to copy the data included in the export method. This structure is used by the ReplicationService Service.

Table 2-13 lists the fields in this structure.

Table 2-13 PathMap Structure Fields

Fields Description

PathMapEntry pathMapEntries

Specifies the location to which you want to copy the data included in the export method.


2.14 Privilege Structure

Use this structure to represent global privileges. In Oracle BI EE, you configure these privileges using the Manage Privileges screen. This structure is used in Section 3.9, "SecurityService Service".

Table 2-14 lists the fields in this structure.

Table 2-14 Privilege Structure Fields

Fields Description

String name

Specifies the name of a privilege.

String description

Specifies the description of a privilege.


2.15 QueryResults Structure

Use this structure to specify query details during query execution.This structure is used in the Section 3.11, "XMLViewService Service" (in the executeXMLQuery method).

Table 2-15 lists the fields in this structure.

Table 2-15 QueryResults Structure Fields

Fields Description

String rowset

Specifies the rowset XML encoded in the string.

String queryID

Specifies the unique ID of the query, which can be used in fetchNext calls.

boolean finished

If set to TRUE, then there are no more rows to return. If set to FALSE, then another fetchNext call is needed to return more rows.


2.16 ReportHTMLOptions Structure

Use this structure to define options for displaying results on an HTML page. This structure is used in the Section 3.2, "HtmlViewService Service".

Table 2-16 lists the field in this structure.

Table 2-16 ReportHTMLOptions Structure Field

Field Description

boolean enableDelayLoading

Internal use only. This field is always set to 1, which means that Oracle Business Intelligence Web Services is never required to provide results immediately, and displays a message indicating that it is waiting for results.

String linkMode

Specifies whether to display drills or links in the current browser window or a new browser window. For more information about valid values, see Section 2.16.1, "ReportHTMLLinksMode Enumeration".


2.16.1 ReportHTMLLinksMode Enumeration

This enumeration specifies a list of valid values for the ReportHTMLLinksMode field in the "ReportHTMLOptions Structure".

Table 2-17 lists the values in this enumeration.

Table 2-17 ReportHTMLLinksMode Enumeration Values

Values Description

String InPlace

Specifies that drills or links should replace only the content of the current analysis without changing the rest of the page.

String NewPage

Specifies that drills or links should be displayed in a new browser window.

String SamePage

Specifies that drills or links should replace the current browser window.


2.17 ReportParams Structure

Use this structure to replace existing filters and variables in an analysis. This structure is common to all services in Oracle BI EE Web Services.

Table 2-18 lists the fields in this structure.

Table 2-18 ReportParams Structure Fields

Fields Description

String[] filterExpressions

Specifies an array of Oracle Business Intelligence Web Services filter expressions in the form Object[] filter_expression, filter_expression ...

Variable[] variables

Specifies an array of variable values to be set before method execution. This structure is used in Section 3.11.4, "executeXMLQuery() Method" and Section 3.7.3, "generateReportSQL() Method".

NameValuePair[] nameValues

Should be set to NULL. This field is for internal use only.

TemplateInfo[] templateInfos

Should be set to NULL. This field is for internal use only.

String viewName

Specifies which view to use when generating XML data for the analysis.


Table 2-19 shows how filter expressions are applied to an analysis.

Table 2-19 How Filter Expressions Are Applied to an Analysis in Oracle BI EE Web Services

Step Internal Processing

1

Obtains XML representations of the analysis and each filter expression.

2

For each expression element, locates the child node of the type sqlExpression (the type is determined by the value of the xsi:type attribute), and references its inner text.

3

In the analysis XML, locates all nodes that also have a child node of type sqlExpression where the inner text matches that located in the preceding step.

4

Replaces all nodes found in Step 3 with the expression from Step 2.


Table 2-20 shows how variables are applied to an analysis.

Table 2-20 How Variables Are Applied to an Analysis in Oracle BI EE Web Services

Step Internal Processing

1

Obtains XML representations of the analysis.

2

For each variable, locates all nodes in the analysis XML that have a type of variable, attribute scope equal to analysis, and inner text that matches the variable name.

3

Replaces each node located in Step 2 with the new variable value.


2.18 ReportRef Structure

Use this structure to reference an analysis in one of the following ways:

Table 2-21 lists the fields in this structure.

Table 2-21 ReportRef Structure Fields

Fields Description

String reportPath

Specifies a string value that provides the path to the analysis in the catalog. For example, /users/jchan/analyses/.

String reportXML

Specifies a string value that contains the XML that defines the analysis.


2.19 SAColumn Structure

Use this structure to represent the logical column in the Subject Area. This structure is used in Section 3.5, "MetadataService Service".

Table 2-22 lists the fields in this structure.

Table 2-22 SAColumn Structure Fields

Fields Description

String name

Specifies a column name used in SQL statements.

String displayName

Specifies a localized name, used in Oracle Business Intelligence Answers.

String description

Specifies a string to contain the description of the column name.

boolean nullable

If set to TRUE, then the column can be null.

String dataType

Specifies the type of data that a column contains. For more information, see Section 2.19.1, "SADataType Values".

boolean aggregateable

If set to TRUE, then the column can be aggregated.

String aggrRule

If the column contains aggregated data, this value specifies the type of aggregation used. For more information, see Section 2.19.2, "AggregationRule Values".


2.19.1 SADataType Values

The SADataType indicates the type of data that a column contains. The following list shows the data types available:

  • BigInt

  • Binary

  • Bit

  • Char

  • Coordinate

  • Date

  • Decimal

  • Double

  • Float

  • Integer

  • Invalid

  • LongVarBinary

  • LongVarChar

  • Numeric

  • Real

  • SmallInt

  • Time

  • TimeStamp

  • TinyInt

  • Unknown

  • VarBinary

  • VarChar

2.19.2 AggregationRule Values

The SADataType specifies the default aggregation rule for the column. The following list shows the aggregation functions available:

  • Avg

  • BottomN

  • Complex

  • Count

  • CountDistinct

  • CountStar

  • DimensionAggr

  • First

  • Last

  • Max

  • Min

  • None

  • Percentile

  • Rank

  • ServerDefault

  • SubTotal

  • Sum

  • TopN

2.20 SASubjectArea Structure

Use this structure to represent Subject Area attributes. This structure is used in Section 3.5, "MetadataService Service".

Table 2-23 lists the fields in this structure.

Table 2-23 SASubjectArea Structure Fields

Fields Description

String name

Specifies the table name that is used in SQL statements.

String displayName

Specifies the localized name, used in Oracle Business Intelligence Answers.

String description

Specifies the description of the subject area.

SATable[] tables

Specifies a collection of tables for this subject area. For information about the SATable structure, see Section 2.21, "SATable Structure".


2.21 SATable Structure

Use this structure to represent the logical table in the Subject Area. This structure is used in the Section 3.5, "MetadataService Service".

Table 2-24 lists the fields in this structure.

Table 2-24 SATable Structure Fields

Fields Description

String name

Specifies the table name that is used in SQL statements.

String displayName

Specifies the localized name, used in Oracle Business Intelligence Answers.

String description

Specifies the description of the table name.

SAColumn[] columns

Specifies an array of the table's columns. For information about the SAColumn structure, see Section 2.19, "SAColumn Structure".


2.22 SAWLocale Structure

Use this structure to define the locale for the current session. This structure is used in Section 3.8, "SAWSessionService Service".

Table 2-25 lists the fields in this structure.

Table 2-25 SAWLocale Structure Fields

Fields Description

String language

Specifies the language code. Values for language should conform to the ones used in Java, in the java.util.Locale class (ISO-639, ISO-3166).

String country

Specifies the country code. Values for country should conform to the ones used in Java, in the java.util.Locale class (ISO-639, ISO-3166).


2.23 SAWSessionParameters Structure

Use this structure to define optional parameters for the current session. This structure is used in Section 3.8, "SAWSessionService Service".

Table 2-26 lists the fields in this structure.

Table 2-26 SAWSessionParameters Structure Fields

Fields Description

SAWLocale locale

Specifies the locale to be used, supplied in the SAWLocale structure. For information about the SAWLocale structure, see Section 3.8, "SAWSessionService Service".

String userAgent

Specifies whether the HTMLView service will be used with current session. It specifies the userAgent string of the browser, where Oracle Business Intelligence Presentation Services HTML content is displayed. Oracle Business Intelligence Presentation Services uses this information to produce browser-specific HTML.

String syndicate

Internal use only.

LogonParameter logonParams

Specifies the parameters used for authentication.

boolean asyncLogon

If set to TRUE, then asynchronous login is enabled. If set to FALSE (default), then asynchronous login is not enabled.

String sessionID

Specifies the unique ID of the session. This field is used in Section 3.8.9, "logonex() Method" and Section 3.8.5, "impersonateex() Method".


2.24 SegmentationOptions Structure

Use this structure to define the segment or segment tree to override the defaults specified in the Oracle Marketing Analytics user interface. This structure is used in the Section 3.5, "MetadataService Service".

Table 2-27 lists the fields in this structure.

Table 2-27 SegmentationOptions Structure Fields

Fields Description

OverrideType cacheOverride

Specifies how you want to override the Oracle Marketing Analytics' "Cache the block for future update counts requests" user interface option.

If set to Default, then the cache override is not specified in the structure or the structure is not specified. The Default value specifies to use what is defined in the user interface option for each criteria block.

If set to None, the system overrides the user interface-defined values and sets all criteria blocks to disable the "Cache the block for future update counts requests" user interface option.

If set to All, the system overrides the user interface-defined values and sets all criteria blocks to enable the "Cache the block for future update counts requests" user interface option.

OverrideType countOverride

Specifies if the system should use the getCounts method to generate the count numbers.

If set to Default, then the count override is not specified in the structure or the structure is not specified.

If set to All, the system executes the getCounts method. When set to All, the system calculates count numbers for all criteria blocks.

NameValuePair
govRules

Specifies a value to enforce the corresponding contract planning rules for the segment or segment tree.

NameValuePair
prompts

Specifies the prompt values to apply to the columns in the segment or segment tree. This process filters data when generating counts.

If you do not provide a value in this field, then the system does not apply filter criteria to columns in segments.

Boolean removeCacheHits

Specifies that you want to clear cache entries that contain count information.

If set to True, the system queries against the most current data. To do this, the system removes all existing cache entries that contain count information for the target segment or segment tree. The system then repopulates the cache with new count number entries calculated by the getCounts method.

BigDecimal samplingFactor

Specifies the size of the data set for calculating counts. The getCounts method calculates the count number of all criteria blocks against a subset of the data determined by this value.

The default value is 100. The default value determines that the count number is calculated against the whole data set.


2.25 SessionEnvironment Structure

Use this structure to return environment information for the current session. This structure is used in Section 3.8, "SAWSessionService Service".

Table 2-28 lists the fields in this structure.

Table 2-28 SessionEnvironment Structure Fields

Fields Description

String userName

Specifies the name of the current user.

ItemInfo homeDirectory

Specifies the full path to the user's home directory in the catalog. For example, /users/<user login ID>.

ItemInfo[] SharedDirectories

Specifies the full paths to shared directories to which the current user has at least read access.

Note: By default, only administrators are allowed to list direct descendents of the "/shared" directory. Retrieving the SessionEnvironment object is the only way to enable users to navigate its shared area.


2.26 StartPageParams Structure

Use this structure to define options in startPage method invocations. This structure is used in Section 3.2, "HtmlViewService Service".

Table 2-29 lists the fields in this structure.

Table 2-29 StartPageParams Structure Fields

Fields Description

String idsPrefix

Specifies a prefix to be used with IDs and names of all HTML elements to avoid name conflicts on an HTML page.

boolean dontUseHttpCookies

If set to TRUE, thenOracle Business Intelligence Presentation Services cannot rely on cookies for passing the sessionID. Instead, the sessionID is included as a parameter in callback URLs.


2.27 TreeNodePath Structure

Use this structure to specify a segment tree path and branch Id number for a branch in the segment tree. This structure is used in the Section 3.4, "JobManagementService Service".

Table 2-30 lists the fields in this structure.

Table 2-30 TreeNodePath Structure Fields

Fields Description

String treeNode

Specifies the segment tree's branch Id number that contains the members to include in the list.

String treePath

Specifies the path to the segment tree.


2.28 UpdateACLParams Structure

Use this structure to set options in updateACL method invocations. This structure is used in Section 3.9, "SecurityService Service".

Table 2-31 lists the fields in this structure.

Table 2-31 UpdateACLParams Structure Fields

Fields Description

UpdateACLMode updateFlag

Specifies how to update the ACL mode. For more information, see Section 2.28.1, "UpdateACLMode Enumeration".


2.28.1 UpdateACLMode Enumeration

This enumeration specifies a list of valid values for the update flag in the UpdateACLParams Structure.

Table 2-32, "UpdateACLMode Enumeration Values" lists the values in this enumeration.

Table 2-32 UpdateACLMode Enumeration Values

Values Description

String ReplaceACL

Specifies the ACL value to update.

String ReplaceForSpecifiedAccounts

Specifies a list of accounts to update in the ACL.

String DeleteAccountsFromACL

Specifies a list of accounts to remove from the ACL.


2.29 UpdateCatalogItemACLParams Structure

Use this structure to provide additional parameters in Section 3.10.18, "updateCatalogItemACL() Method". This structure is used inSection 3.10, "WebCatalogService Service".

Table 2-33 lists the fields in this structure.

Table 2-33 UpdateCatalogItemACLParams Structure Fields

Fields Description

UpdateACLMode updateFlag

Specifies how to update the ACL mode. For more information, see Section 2.28.1, "UpdateACLMode Enumeration".

boolean recursive

If set to TRUE, then the method is applied to the catalog item and all descendents, which are identified by the path. If set to FALSE, then the method is only applied to the catalog item.


2.30 Variable Structure

Use this structure to reference a variable in the analysis and replace it with another variable. This structure is common to all services in Oracle BI EE Web Services.

Table 2-34 lists the fields in this structure.

Table 2-34 Variable Structure Fields

Fields Description

String name

Specifies a character string that contains the name of the variable to replace.

Object value

Specifies the value of the variable.


2.31 XMLQueryExecutionOptions Structure

Use this structure to specify optional parameters during a query. This structure is used in Section 3.11, "XMLViewService Service" (in the executeXMLQuery method).

Table 2-35 lists the fields in this structure.

Table 2-35 XMLQueryExecutionOptions Structure Fields

Fields Description

boolean async

If set to TRUE, then asynchronous query execution is enabled. If set to FALSE, then asynchronous query execution is disabled.

int maxRowsPerPage

Specifies the maximum number of rows to be returned by a executeXMLQuery or fetchNext method.

boolean refresh

If set to TRUE, then the server re-submits the query to refresh the data. If set to FALSE, then the Oracle Business Intelligence Server uses data in the cache.

boolean presentationInfo

If set to TRUE, then store localized presentation information in the metadata section of the record set XML.

Presentation information consists of the following:

  • Column heading information (stored in the columnHeading field).

  • Table heading information (stored in the tableHeading field).

String type

Specifies the query ID, which can be used in logs to diagnose errors.