1 Introduction to the BI Publisher Web Services

This chapter provides a brief introduction to Oracle BI Publisher Web services, and includes the following sections:

Section 1.1, "About BI Publisher Web Services"
Section 1.2, "About In-Session Methods"
Section 1.3, "Debugging Web Service Applications"

1.1 About BI Publisher Web Services

Oracle BI Publisher Web services provide data types and services. Data types include base data types and complex data types. Oracle BI Publisher Web services also support XML-to-Java data type mappings. For more information on supported data types and mappings, see Chapter 2, "Data Types in Oracle BI Publisher Web Services."

Oracle BI Publisher provides the following public Web services:

ScheduleService: Provides methods for executing scheduler tasks, such as to schedule report jobs, retrieve report outputs, and manage report history. See Chapter 3, "ScheduleService."
ReportService: Provides methods to interact with BI Publisher Report object, such as to run reports, get information about reports, define and modify reports, and upload report templates. See Chapter 4, "ReportService."
SecurityService: Provides methods for security operations, such as authentication, impersonation, login, logout, and account management. See Chapter 5, "SecurityService."
CatalogService: Provides methods to manage (create, copy, upload, download and delete) report catalog objects, such as folders, reports, data models, style templates, and sub-templates. See Chapter 6, "CatalogService."

Many of the methods in these services are provided in pairs. The first provides a stateless operation that requires login credentials. The second provides an "in session" operation that uses an existing user's session ID, which is obtained through the login() or impersonate() method of the SecurityService. For more information, see Section 1.2, "About In-Session Methods."

1.2 About In-Session Methods

Oracle BI Publisher Web services provide many "in session" methods, such as the deliveryServiceInSession() Method, createReportInSession() Method, and copyObjectInSession() Method. In-session methods enable your applications to perform a variety of operations for active user sessions. For this, these methods rely on the bipSessionToken string, which acts as a proprietary token and is generated at user login.

To leverage in-session methods, the user must log in through the SecurityService login() Method or impersonate() Method. Upon successful user authentication from SecurityService, BI Publisher server generates a bipSessionToken string. This bipSessionToken string can be used to perform all in-session operations in this guide.

1.3 Debugging Web Service Applications

As a Web services developer, you may need to see the SOAP request messages being used to invoke Web services along with the SOAP responses to those request messages. To do this, you can use the Apache Axis TCP Monitor utility. With this utility, you can monitor the SOAP message flow without requiring you to perform any special configuration, restarting the server, or gaining access to the computer where BI Publisher is running.

To install TCP Monitor, go to the Apache website (apache.org), and download axis.jar to your computer.

To start TCP Monitor, open a command window and cd to the directory where you downloaded axis.jar. Then, from the command line enter the following:

% java -classpath axis.jar org.apache.axis.utils.tcpmon

You should see the following screen:

Figure 1-1 Sample Axis TCP Monitor Window

To configure TCP Monitor:

In the Listen Port # field, enter an unused local port on your computer that TCP Monitor will use to listen for messages. For example, 7777.
In the Target Hostname field, enter the host name of the server that is running BI Publisher. For example, mypublisher.company.com.
In the Target Port # field, enter the port that is used for the BI Publisher server. For example, 9704.
Click the Add button. You will see a new tab with the new monitor listening on the listen port number of the local computer.

Now you can start a browser, SOAP utility, or your application, and run commands against your local computer using the listen port on the local computer (for example, localmachine:7777/xmlpserver). TCP Monitor will route those requests to the target host and port. From there, you will see the SOAP request and response messages, which facilitates debugging.