This chapter introduces the Oracle Business Intelligence Server Metadata Web Service, and describes configuring the web service connection to Oracle BI Server, the methods used to call the web service, securing the web service, and using Oracle BI Server XML procedures.
This chapter includes the following sections:
Section 4.1, "Overview of the Oracle BI Server Metadata Web Service"
Section 4.2, "Configuring the Oracle BI Server Metadata Web Service"
Section 4.3, "Calling the Oracle BI Server Metadata Web Service"
The Oracle BI Server uses 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 Business Intelligence, you would use the Administration Tool to access the information stored in the metadata repository. However, in this version of Oracle Business Intelligence, the Oracle BI Server 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, a developer who wants to update the server repository with new metadata, doesn't have to open Administration Tool or restart the server with a modified repository. The developer can use a stored procedure to directly apply the patch XML created from two different versions of the repository.
There are two techniques of calling the Oracle BI Server Metadata Web Service, synchronous and asynchronous. In cases where the response returns immediately, the synchronous technique might be adequate. However, because request processing can be delayed, it is often useful to utilize the asynchronous technique of calling the Web Service so the client application can continue its work and handle the response later on.
This topic contains the following sections:
Use this topic if you are not using the default installation of BI Server. By default the Oracle BI Server Metadata Web Service attempts to connect to an instance of BI Server running at the following URL:
jdbc:oraclebi://localhost:9703/
However, if the 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 Oracle Business Intelligence JDBC data source that you create in Oracle WebLogic Server Administration Console. The Oracle BI Server Metadata 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 an Oracle Business Intelligence 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 an Oracle Business Intelligence JDBC data source for use with the Oracle BI Server 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).
You secure the Oracle BI Server Metadata Web Service using Oracle Web Services Manager (WSM). To call the Oracle BI Server Metadata 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.
This topic contains the following sections:
You apply a security policy by choosing one from a predefined list that is appropriate for the security guidelines of your organization, then assign it to the web service.
An example of a web service security policy is:
oracle/wss11_saml_token_with_message_protection_service_policy
To successfully call the Oracle BI Server Metadata Web Service, the client code must set up a matching client side policy, and supply the required information. For example, the client side policy that matches the service policy above is:
oracle/wss11_saml_token_with_message_protection_client_policy
In this example, the client code would have to add a valid SAML token for a user with permission to call the stored procedures to the SOAP message headers. The security policy on the web service ensures that any SOAP messages without a valid token are rejected. If the token is valid, the web service connects to Oracle BI Server using the System user credentials and impersonates the user specified in the token.
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 Oracle BI Server Metadata Web Service. The configuration for the Oracle BI Server Metadata Web Service and the Action Framework are identical.
For information about configuring WSM to work with the Oracle BI Server Metadata Web Service, see "Configuring Oracle Web Services Manager".
You must provide the user who will run the Oracle BI Server Metadata 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.
This section contains information about calling the Oracle BI Server Metadata Web Service:
Section 4.3.1, "Calling the Oracle BI Server Metadata Web Service Synchronously"
Section 4.3.2, "Calling the Oracle BI Server Metadata Web Service Asynchronously"
The Oracle BI Server Metadata Web Service is normally deployed at the following location, for synchronous calls:
http://server:port/AdminService/AdminService
The WSDL can be found at the following location:
http://server:port/AdminService/AdminService?WSDL
Use the following methods to synchronously call any stored procedure on the Oracle BI Server:
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.
Procedures that return a result set are NQSModifyMetadata, NQSQueryMetadata, NQSExtractMetadataProject (returns record sets of binary data), NQSQueryProjects. These are all query type procedures where the results are interesting, except for NQSModifyMetadata that simply returns the error messages (if any), that occur during the execution of the procedure. You can call NQSModifyMetadata synchronously without callProcedureWithResults, you just wouldn't know what the error messages are.
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. |
The method is for internal use only, and calls the BI Server Extender utility that imports flex object changes from ADF sources and maps them to the Business Model and Mapping layer, and Presentation layer.
This method returns a string indicating that the startExtender command was started.
For more information, see "Automatically Mapping Flex Object Changes Using the biserverextender Utility" in Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.
The WSDL signature for the startExtender () method is:
<xsd:sequence>
<xsd:element name="adminBeanServerUrl" type="xsd:string"/>
<xsd:element name="biAdminUser" type="xsd:string"/>
<xsd:element name="biAdminPassword" type="xsd:string"/>
<xsd:element name="jobID" type="xsd:string"/>
<xsd:element name="connectionDetails" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="startExtender" type="tns:startExtender"/>
<xsd:complexType name="startExtenderResponse">
<xsd:sequence>
<xsd:element name="return" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
For example, a startExtender() call might be something like this:
startExtender(localhost:7001", "wlsuser", "wlspassword", "
<ConnectionDetails>
<ConnectionPool>
<ConnectionPoolName>"oracle.apps.fscm.model.analytics.
applicationModule.FscmTopModelAM_FscmTopModelAMLocal"."Connection Pool"
</ConnectionPoolName>
</ConnectionPool>
<NewEssbaseConnection>
<DatabaseName>computer.example.com:10215</DatabaseName>
<UserName>FUSION_APPS_GL_ESSBASE_APPID</UserName>
<Password>D7EDED84BC624A917F5B462A4DCA05
CDCE256EEEEEDC97D5575BA27BADBC24F0E7675
6D92C558D91CA53D63E2D7450E3FAEA57FA6B914D4D</Password>
<CubeNamesList>
<CubeName>BI_VF_USA_Accounting_Flexfie</CubeName>
</CubeNamesList>
</NewEssbaseConnection>
</ConnectionDetails>");
Table 4-3 contains information about this method's arguments.
Table 4-3 startExtender() 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 the following code to set up client-side security. You can use this code to set up a client-side instance 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 is passed automatically to the Oracle BI Server Metadata 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>
The Oracle BI Server Metadata Web Service is normally deployed at the following location for asynchronous calls:
http://server:port/AsyncAdminService/service
The WSDL can be found at the following locations for asynchronous web services:
http://server:port/AsyncAdminService/service?wsdl
From the client perspective, the asynchronous method call consists of two one-way message exchanges. Before initiating the asynchronous call, the client must deploy a callback service to listen for the response from the asynchronous web service.
This section contains the following topics:
Use the Create Web Service Proxy wizard in JDeveloper, select Generate As Async to generate an asynchronous proxy. For more information about creating web service clients using the wizard, see "Creating Web Service Proxies" in the JDeveloper Online Help. You can modify the generated callback service code to process the response. You must then deploy the callback service as a web service. Once deployed, add the URL of the callback service to the client code as the replyTo field.
For more information about creating the callback service, see "Defining Asynchronous Web Service Clients" in Oracle Fusion Middleware Developer's Guide for Oracle Infrastructure Web Services.
You can attach policies to the following asynchronous components:
Client calling asynchronous web service.
Asynchronous web service.
Asynchronous callback client.
Asynchronous callback service.
To attach policies to the components at runtime you can use Fusion Middleware Control. The asynchronous web service and client policies must comply with one another. Similarly, the asynchronous callback client and callback service policies must comply with one another.
For more information about configuring security for the callback service, see "Attaching Policies to Asynchronous Web Services and Clients" in Oracle Fusion Middleware Developer's Guide for Oracle Infrastructure Web Services.
The following code can be used to create and initialize client-side instance of the asynchronous metadata web service. The code includes an example of configuring the client-side instance to pass authentication information required for the oracle/wss_username_token_client_policy policy. You will have to generate client-side proxy classes to use code such as the example code.
/**
* Looks up an instance of the Asynchronous Admin Service and
* sets the correct authentication information on it.
* @return Asynchronous Admin Proxy to the admin service.
*/
protected AsyncAdmin getAsyncAdminService() throws Exception {
String SERVICE_NAMESPACE = "http://ws.admin.obiee.oracle/";
String SERVICE_NAME = "AsyncAdminService";
String SECURITY_POLICY = "oracle/wss_username_token_client_policy";
URL wsdlURL = new URL("http://localhost:7001/AsyncAdminService/service?wsdl");
QName serviceQname = new QName(SERVICE_NAMESPACE, SERVICE_NAME);
AsyncAdminService service = new AsyncAdminService(wsdlURL, serviceQname);
SecurityPoliciesFeature securityFeature =
new SecurityPoliciesFeature(new String[] { SECURITY_POLICY });
AsyncAdmin admin = service.getAsyncAdminPort(securityFeature);
Map<String, Object> requestContext = ((BindingProvider) admin).getRequestContext();
requestContext.put(BindingProvider.USERNAME_PROPERTY, "weblogic");
requestContext.put(BindingProvider.PASSWORD_PROPERTY, "welcome1");
return admin;
}
The following code shows how to specify callback information before calling methods of the asynchronous metadata web service:
String CALLBACK_URL = "http://localhost:7001/ClienCallback/AsyncAdminResponseImplPort"; AddressingVersion WS_ADDR_VER = AddressingVersion.W3C; WSEndpointReference replyTo = new WSEndpointReference(CALLBACK_URL, WS_ADDR_VER); Header replyToHeader = replyTo.createHeader(WS_ADDR_VER.replyToTag); String messageID = UUID.randomUUID().toString(); WSBindingProvider wsbp = (WSBindingProvider) getAsyncAdminService(); wsbp.setOutboundHeaders(new StringHeader(WS_ADDR_VER.messageIDTag, messageID), replyToHeader);
Oracle Business Intelligence 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-4 contains the Extract Project procedure's input and output parameters and their descriptions.
Table 4-4 Extract Projects Procedure Parameters and Descriptions
| Parameter | Description |
|---|---|
|
PROJECT_NAMES |
A delimited list of project names that is sent to the procedure for extraction. |
|
RPD_NAME |
(Optional) 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, biserverxmlexec, and biserverxmlcli, and by copying and pasting within the Administration Tool. For more information about biserverxmlgen, biserverxmlexec, 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) 4. IGNORE_XUDML_ERRORS (optional) Output 1. ERROR_MESSAGES
Table 4-5 contains the Modify Metadata procedure's input and output parameters and their descriptions.
Table 4-5 Modify Metadata Procedure Parameters and Descriptions
| Parameter | Description |
|---|---|
|
XUMDL_TEXT |
The full Oracle BI Server XML text that is applied to the server. In general, the metadata definitions is applied directly, overwriting existing definitions, unless the original repository is set in the input parameter. |
|
ORIGINAL_RPD |
(Optional) The name of the repository to which Oracle Business Intelligence compares the Oracle BI Server XML. Oracle Business Intelligence compares the Oracle BI Server XML fragment to the original RPD that you specify, and if Oracle Business Intelligence detects a conflict, it does not apply the Oracle BI Server XML. If no conflict is detected, Oracle Business Intelligence applies the Oracle BI Server XML. |
|
RPD_NAME |
(Optional) This parameter is currently not used. It is reserved for future use. |
|
IGNORE_XUDML_ERRORS |
(Optional) Ignore all non-fatal errors. Examples of non-fatal errors are unresolved objects, duplicated objects, and broken expressions. Set this parameter to true. Note that the value is case-insensitive. |
|
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. QNAME_QUERY_FLAG (optional) 6. RPD_NAME (optional) 7. CHILD_TYPE (optional) Output 1. XUDML_TEXT 2. ERROR_MESSAGES
Table 4-6 contains the Query Metadata procedure's input and output parameters and their descriptions.
Table 4-6 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_NAME cannot be empty when OBJECT_PARENT is being used. |
|
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. |
|
QNAME_QUERY_FLAG |
(Optional) If this parameter is set to true, then the query returns qualified names instead of XUDML fragments. If this parameter is not set, then the query returns XUDML fragments by default. |
|
RPD_NAME |
(Optional) This parameter is currently not used. It is reserved for future use. |
|
CHILD_TYPE |
(Optional) If this parameter is set to true, then the query filters the list of children by the types provided in the comma separated list of type IDs and returns only those types of children. If this parameter is left empty by default, then all types of children objects are returned. This parameter is applicable only when the CHILD_FLAG parameter is set to true. |
|
XUDML_TEXT |
Contains the returned XML representation of all the metadata. If the XML data is too large to fit in one row, it is 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 contain the list of projects defined in the repository.
This procedure has the following structure:
NQSQueryMetadataProjects Input 1. RPD_NAME (optional) Output 1. PROJECT_NAME
Table 4-7 contains the Query Projects procedure's input and output parameters and their descriptions.
Table 4-7 Query Projects Procedure Parameters and Descriptions
| Parameter | Description |
|---|---|
|
RPD_NAME |
(Optional) This parameter is currently not used. It is reserved for future use. |
|
PROJECT_NAME |
Contains a rowset for each project. Note that it is the responsibility of the caller to collect the entire rowset. |