1 Introduction to Oracle Business Intelligence Web Services

This chapter provides an overview of the Oracle Business Intelligence web services and contains the following sections:

Section 1.1, "Overview of the Oracle Business Intelligence Web Services"
Section 1.2, "What are the Oracle Business Intelligence Session-Based Web Services?"
Section 1.3, "What are the Oracle Business Intelligence Web Services for SOA?"
Section 1.4, "Configuring and Securing the Oracle Business Intelligence Web Services for SOA"
Section 1.5, "Enabling SSL for Web Services Communication"
Section 1.6, "Invoking Oracle Business Intelligence Web Services Over HTTPS"

1.1 Overview of the Oracle Business Intelligence Web Services

Oracle Business Intelligence provides two types of web services: Oracle Business Intelligence Session-Based Web Services and Oracle Business Intelligence Web Services for SOA.

You can use Oracle Business Intelligence Session-Based Web Service to call Oracle Business Intelligence programmatically to invoke many different business intelligence items. For more detailed information about these types of web services, see "What are the Oracle Business Intelligence Session-Based Web Services?"

The Oracle Business Intelligence Web Services for SOA provide a web service unique to each analysis, condition, or agent saved to the Oracle BI Presentation Catalog. For more detailed information about this types of web service, see "What are the Oracle Business Intelligence Web Services for SOA?"

1.2 What are the Oracle Business Intelligence Session-Based Web Services?

The Oracle Business Intelligence Session-Based Web Services are an application programming interface (API) that implements SOAP. These web services are designed for programmatic use, where you use one web service for invoking many different business intelligence objects. These web services also provide functionality on a wide range of Presentation Services operations.

The Oracle Business Intelligence Session-Based Web Services allow you to perform three types of functions:

Extract results from Oracle Business Intelligence Presentation Services and deliver them to external applications and Web application environments.
Perform Oracle Business Intelligence Presentation Services management functions.
Execute Oracle BI EE alerts (known as Intelligent Agents).

Oracle Business Intelligence Session-Based Web Services allow external applications such as J2EE and .NET to use Oracle Business Intelligence as an analytical calculation and data integration engine. It provides a set of Presentation Services that allow external applications to communicate with Oracle Business Intelligence Presentation Services.

Oracle Business Intelligence Session-Based Web Services require a valid Oracle Business Intelligence session ID to be passed as a parameter. This means that the calling application first needs to make a call to get the session before calling the web service. A final call is made to log out.

The formal definition of services and methods in Oracle BI EE Web Services can be retrieved in WSDL format. You can use a proxy generation tool to create proxy/stub code to access the services. You can access the WSDL document at the following Oracle BI EE Web Services URL:

http://host:port/analytics/saw.dll/wsdl/v6

1.3 What are the Oracle Business Intelligence Web Services for SOA?

The Oracle Business Intelligence Web Services for SOA contains three Web services, ExecuteAgent, ExecuteAnalysis, and ExecuteCondition, which are hosted by the middleware J2EE application. These web services enable you to use third-party Web services clients (for example, Oracle SOA Suite) to browse for and include business intelligence objects in service oriented architecture components. These Web services are used to consume specific values or small sets of values to feed into conditional logic or subsequent steps. This approach allows end users to execute analyses, evaluate conditions, and to invoke Agents in their processes, event routing, and business rules. Note that the Oracle Business Intelligence Web Services for SOA will only return XML strings.

The Oracle Business Intelligence Web Services for SOA support calling agents, analyses, and conditions only. Prompted filters and presentation variables included in the business intelligence objects are supported. Oracle BI EE dynamically creates a dedicated Web Services Description Language (WSDL) document with its own name space for each agent, analysis, and condition that content designers save to the catalog.

The Oracle Business Intelligence Web Services for SOA dynamically provide WSIL documents to allow you to browse for and select agents, analyses, and conditions stored in the catalog. The WSIL lists each available business intelligence object as a WSDL document with a unique name. Since each object has a dedicated WSDL document, the WSDL explicitly lists prompted filters for you to complete. If the your SOA development tool does not support WSIL browsing, you can still access the WSIL from a Web browser user interface. You can access the WSIL by accessing the following URL on the Oracle Business Intelligence Presentation Server:

https://host:port/biservices/inspection?wsil

The WSIL is not available until it has been properly configured. For more information about this required configuration, see "Configuring and Securing the Oracle Business Intelligence Web Services for SOA". For specific instructions about adding the wsil.browsing key to the credential store, see "Adding and Maintaining Credentials for Use With the Action Framework".

1.4 Configuring and Securing the Oracle Business Intelligence Web Services for SOA

During installation, each Web service (executeAgent, executeAnalysis, and executeCondition) is assigned the "policy:oracle/wss_username_token_service_policy" security policy. This policy requires the calling SOAP message to include a user name and token (password) in the WS-Security header. The user credentials that are passed to Web services through the incoming SOAP message can be any valid business intelligence user who has the proper access to the target business intelligence object being invoked. This method of security means that Web services can be called in a single step without first retrieving a session ID. Note that if required, you can change the security policy used by the Web services to any security policy available in Oracle WebLogic Server.

Whereas invoking Web services uses the credentials passed in the calling SOAP message to invoke the target functionality, browsing the Web services using the WSIL uses a single user account. It is not currently possible to invoke the browsing mechanism using the credentials of the user performing the browsing using this mechanism.

To enable browsing for Web services, you must go to Oracle Enterprise Manager, access the oracle.bi.enterprise map, which is located on the bifoundation_domain, and manually add the "wsil.browsing" credential to the credential store. This key holds the user ID and password for the valid user defined in the identity store. For example, if you want to browse for target web services as the user "abell," you will add the credentials of "abell" to the wsil.browsing key in the credential store.

In practice, a special user should be created in the identity store specifically for browsing the catalog for use with this functionality. This user should not have any business intelligence objects in their personal folder (my folders), as other users will not be able to invoke this functionality.

For more information about setting up users and credentials, seeOracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

1.5 Enabling SSL for Web Services Communication

Oracle recommends that you enable HTTPS on the Managed Server that hosts the Analytics and BI middleare J2EE applications. Un-encrypted credentials that are passed to the target web service may be intercepted, and using SSL is a way to mitigate this risk. After you set up SSL, see "Invoking Oracle Business Intelligence Web Services Over HTTPS" for information about certificates.

1.6 Invoking Oracle Business Intelligence Web Services Over HTTPS

To invoke Oracle Business Intelligence Web Services when using HTTPS, the client calling the Web service on the server (for example, Oracle BPEL calling Oracle Business Intelligence Web Services for SOA) needs to trust the server certificate. The server may have an authentic certificate provided by a well-known certificate authority, in which case the client may trust the server certificate without further configuration. However, by default, this is not the case, and the root certificate used by the Weblogic Managed Servers that are hosting the web services should be imported into the appropriate keystore of the Web services client that is calling these Web services.

Oracle recommends that in a production environment you use a certificate signed by a well-know certificate authority.

Use the following procedure to confirm the location of the root certificate of the Managed Servers that the Web services client needs to trust.

To confirm the location of the root certificate:

Open the Weblogic console in a browser. By default, the location of the Weblogic console is: http://host:7001/console.
From the Oracle WebLogic Server Administration Console, select the SSL tab and go to the Identity area. By default, the Certificate location is from the Demo Identity Keystore. If this is the case, navigate to the Keystores tab and review the location of the Demo Identity Keystore.

Note that the Demo Identity Keystore's default location is:

<middleware_home>/wlserver_10.3_server/lib/DemoIdentity.jks
Use the Oracle Keytool utility to view and export the root certificate.