This chapter describes the Oracle BI Metadata Web Service. Describes configuring the Web service connection to Oracle BI Server, the methods used to call the Web service, securing the Web service, and using the Oracle BI Server XML procedures.
This chapter includes the following sections:
Section 4.1, "Overview of the Oracle BI Metadata Web Service"
Section 4.2, "Configuring the Web Service Connection to Oracle BI Server"
Section 4.3, "Calling and Securing the Oracle BI Metadata Web Service"
The Oracle BI Server utilizes a semantic model to store and control behavior related to its operations. The semantic layer, called the Common Enterprise Information Model, is captured inside of metadata that is managed by the Oracle BI Administration Tool.
In previous versions of Oracle BI, you would use the Administration Tool to access the information stored in the metadata repository. However, in this version of Oracle BI, the Oracle BI Metadata Web Service allows you to use a Web service interface to call Oracle BI Server stored procedures. These procedures provide the ability to obtain information about the metadata and to modify the metadata.
For example, suppose that a Developer wants to build an analysis from an Essbase cube but does not have access to the Administration Tool and does not know how to create a metadata repository. The Developer can use a stored procedure to import the cube into Oracle BI Presentation Services and then query the cube to build the required analysis.
Use this topic if you are not using the default installation of Oracle BI Server. By default the Metadata Web Service attempts to connect to an instance of Oracle BI Server running at the following URL:
jdbc:oraclebi://localhost:9703/
However, if the Oracle BI server is deployed on a different machine, uses a different port, or if you want to configure an SSL connection between the Web service and the server, you should use a BI JDBC data source that you created in Oracle WebLogic Server Administration Console. The Web service will look for a data source with the following name, and if found, will use it to connect to the Oracle BI Server.
jdbc/bi/server
For instructions about how to create a BI JDBC data source, see "How to Create a BI JBDC Data Source in Oracle WebLogic" in Oracle Fusion Middleware Developer's Guide for Oracle Business Intelligence Enterprise Edition.
However, note the following requirements for setting up a BI JDBC data source for use with the Metadata Web Service. After you have finished setting up this data source, be sure to stop and start the Web service so that your preferences are applied.
In the URL field located on the Connection Properties page of the New JDBC Data Source wizard, specify the port that you configured for Oracle BI Server. The existing instructions state that you should specify "9703," but it is likely that "9703" will not be the correct port number.
After you created and saved the BI JDBC data source, you must modify the data source's settings. Access the Settings for the data source and click the Connections Pool tab. Modify the settings as follows:
In the Statement Cache Size field, enter 0. Specifying this value disables the statement cache.
In the Advanced tab, go to the Connection Creation Retry Frequency field and enter 10 (or any number larger than 0).
This section contains information about calling and securing the Web service.
The Web service is normally deployed at this location:
http://server:port/AdminService/AdminService
The WSDL can be found at this location:
http://server:port/AdminService/AdminService?WSDL
The Web service exposes two generic methods that you can use to call any stored procedure on the Oracle BI Server: callProcedure and callProcedureWithResults.
You can use this method to call procedures that are not expected to return a result set. Table 4-1 contains information about this method's arguments.
Table 4-1 callProcedure Method Arguments
| Argument | Data Type | Description |
|---|---|---|
|
procedureName |
String |
Name of the procedure to call. |
|
parameters |
List of parameters |
A sequence of parameter objects. Each parameter defines a type and value corresponding to the stored procedure arguments. Refer to the WSDL for the supported parameter types. |
Use this method to call procedures that are expected to return a result set.
This method returns an object that mimics the result set as a sequence of ResultsRow objects. Each ResultsRow contains one or more columns, and each column defines a type and value. If an error occurs, most stored procedures return at least one row with a single string column. Therefore, it is important to carefully check the returned results.
Table 4-2 contains information about this method's arguments.
Table 4-2 callProcedure Method Arguments
| Argument | Data Type | Description |
|---|---|---|
|
procedureName |
String |
Name of the procedure to call. |
|
parameters |
List of parameters |
A sequence of parameter objects. Each parameter defines a type and value corresponding to the stored procedure arguments. Refer to the WSDL for the supported parameter types. |
To properly secure the Web service, you must use Oracle Web Services Manager (WSM). To call the Web service, you must configure your client code with the correct client side policy and provide security credentials for a user with permission to call the stored procedures.
By default, the Web service is protected by the following predefined policy:
oracle/wss11_saml_token_with_message_protection_service_policy
To successfully call the Web service, you must apply the following predefined policy in your client code:
oracle/wss11_saml_token_with_message_protection_client_policy
For more information about WSM and how to apply and configure predefined policies, see Oracle Fusion Middleware Security and Administrator's Guide for Web Services.
You must configure WSM before you can successfully use the Web service. The configuration for the Oracle BI Metadata Web Service and the Action Framework are identical.
For information about configuring WSM to work with the Oracle BI Metadata Web Service, see "Configuring Oracle Web Services Manager".
The policies that you applied in the "Applying Policies" step require you to configure SAML. This configuration will ensure that the proper authentication is performed by inserting the SAML token into the request. When the Web service attempts to connect to the Oracle BI Server, it uses the system user credentials and then impersonates the user found in the request's SAML token.
For more information about configuring SAML, see Oracle Fusion Middleware Security and Administrator's Guide for Web Services.
You must provide the user who will run the Web service with the manageRepositories permission. For information about how to set up security and apply this permission, see Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.
Use the following code to set up client-side security. You can use this code to set up a client-side instances of the Admin Service configured to pass authentication information in a SAML token. This code must reside in an authenticated Web application. The authentication information in the session will be passed automatically to the Web service. You will have to generate client-side proxy classes to use code such as the example code.
In this example, the proxies have been generated in the package adminwebservice.client.
import adminwebservice.client.*;
/**
* Looks up an instance of the Admin Service and sets the correct
authentication information on it.
* @return Admin Proxy to the admin service.
*/
protected Admin getAdminService() throws Exception {
String SERVICE_NAMESPACE = "http://ws.admin.obiee.oracle/";
String SERVICE_NAME = "AdminService";
String PORT_NAME = "AdminPort";
String WSS_POLICY_CONFIG_FILE_SAML = "wss-policy-saml.xml";
URL wsdlURL = new URL
("http://localhost:7001/AdminService/AdminService?WSDL");
QName serviceQname = new QName(SERVICE_NAMESPACE, SERVICE_NAME);
QName portQname = new QName(SERVICE_NAMESPACE, PORT_NAME);
ServiceDelegateImpl serviceDelegate = new ServiceDelegateImpl
(wsdlURL, serviceQname, OracleService.class);
Admin admin = serviceDelegate.getPort( portQname, Admin.class);
((BindingProvider)admin).getRequestContext().put(ClientConstants.CLIENT_
CONFIG,toElement(this.getClass().getResourceAsStream(WSS_POLICY_CONFIG_
FILE_SAML)));
((BindingProvider)admin).getRequestContext().put(BindingProvider.
ENDPOINT_ADDRESS_PROPERTY, getServiceUrl());
return admin;
}
WSS_POLICY_CONFIG_FILE_SAML is the resource name of a file with the following content:
<?xml version="1.0" encoding="UTF-8"?>
<oracle-webservice-clients>
<webservice-client>
<port-info>
<policy-references>
<policy-reference uri="oracle/wss11_saml_token_with_
message_protection_client_
policy"category="security"/>
</policy-references>
</port-info>
</webservice-client>
</oracle-webservice-clients>
Oracle BI provides several Oracle BI Server XML procedures that you can use to call the Oracle BI Server via JDBC or ODBC. You can only use the Oracle BI Server XML procedures with repositories in binary (RPD) format.
This topic contains detailed information on the following procedures:
Use the Extract Project procedure to extract a project from the repository. The output results set contains a row for each project defined in the repository.
This procedure has the following structure:
NQSExtractMetadataProject Input 1. PROJECT_NAMES 2.RPD_NAME (optional) Output 1. RPD_OBJECT
Table 4-3 contains the Extract Project procedure's input and output parameters and their descriptions.
Table 4-3 Extract Projects Procedure Parameters and Descriptions
| Parameter | Description |
|---|---|
|
PROJECT_NAMES |
A delimited list of project names that will be sent to the procedure for extraction. |
|
RPD_NAME |
This parameter is currently not used. It is reserved for future use. |
|
RPD_OBJECT |
Contains a single BLOB object with the binary representation for the extracted repository. |
Use the Modify Metadata procedure to apply changes to the repository. The output result set will contain zero or one row. If the output returns one row, that row will contain error messages.
Note that you can modify metadata using other methods, such as command line XML utilities, for example, biserverxmlgen, biserverxmlexex, and biserverxmlcli, and by copying and pasting within the Administration Tool. For more information about biserverxmlgen, biserverxmlexex, and biserverxmlcli command-line tools, see "Generating and Executing XML" in Oracle Fusion Middleware XML Schema Reference for Oracle Business Intelligence Enterprise Edition
This procedure has the following structure:
NQSModifyMetadata Input 1. XUDML_TEXT 2. ORIGINAL_RPD (optional) 3. RPD_NAME (optional) Output 1. ERROR_MESSAGES
Table 4-4 contains the Modify Metadata procedure's input and output parameters and their descriptions.
Table 4-4 Modify Metadata Procedure Parameters and Descriptions
| Parameter | Description |
|---|---|
|
XUMDL_TEXT |
The full Oracle BI Server XML text that will be applied to the server. In general, the metadata definitions will be applied directly, overwriting existing definitions, unless the original repository is set in the input parameter. |
|
ORIGINAL_RPD |
The name of the repository to which Oracle BI compares the Oracle BI Server XML. Oracle BI compares the Oracle BI Server XML fragment to the original RPD that you specify, and if Oracle BI detects a conflict, it does not apply the Oracle BI Server XML. If no conflict is detected, Oracle BI applies the Oracle BI Server XML. |
|
RPD_NAME |
This parameter is currently not used. It is reserved for future use. |
|
ERROR_MESSAGES |
Contains any returned errors resulting from the query execution. |
Use the Query Metadata procedure to query the repository for metadata. The output result set will contain as many rows as there are object matches. You must concatenate the results to obtain the fully formed Oracle BI Server XML document.
This procedure has the following structure:
NQSQueryMetadataObjects Input 1. OBJECT_TYPES 2. OBJECT_NAME (optional) 3. OBJECT_PARENT (optional) 4. CHILD_FLAG (optional) 5. RPD_NAME (optional) Output 1. XUDML_TEXT 2. ERROR_MESSAGES
Table 4-5 contains the Query Metadata procedure's input and output parameters and their descriptions.
Table 4-5 Query Metadata Procedure Parameters and Descriptions
| Parameter | Description |
|---|---|
|
OBJECT_TYPES |
A list of object types for which to search. You can query for multiple object types by adding a comma between object types. For example, you can query for subject area and presentation catalog objects by setting the object_types to a value of '2000,4004'. In this example, the subject area object has a type ID value of 2000 and presentation catalog object has a type ID value of 4004. |
|
OBJECT_NAME |
(Optional) Filter the objects matched by a name. This name is not the fully qualified name. For example, to query for all subject area named "AtomicStar", you would set the OBJECT_TYPES parameter to "2000" and the OBJECT_NAME parameter to "AtomicStar". |
|
OBJECT_PARENT |
(Optional) Filter the objects based on the name of the parent object. Use this parameter to specify a fully qualified name. |
|
CHILD_FLAG |
(Optional) If this parameter is set to "true," then the query returns all the child objects of the queried objects. For example, if you specify the object type parameter as Business Model and set the child flag parameter to "true," then all objects under the Business Model in the tree are returned. |
|
RPD_NAME |
This parameter is currently not used. It is reserved for future use. |
|
XUDML_TEXT |
Contains the returned XML representation of all the metadata. If the XML data is too large to fit in one row, it will be split and passed back in multiple rows. You must concatenate the results to obtain the fully formed Oracle BI Server XML document. |
|
ERROR_MESSAGES |
Contains any returned errors resulting from the query execution. |
Use the Query Projects procedure to determine what projects are in the repository. The output results set contains one row with a single BLOB as the output.
This procedure has the following structure:
NQSQueryMetadataProjects Input 1. RPD_NAME (optional) Output 1. PROJECT_NAME
Table 4-6 contains the Query Projects procedure's input and output parameters and their descriptions.