Chapter 32 Using the Web Service’s SDK

In this chapter

The Next Generation of Web Services 826

BI Web Services in the Real World 831

Configuring the Unified Web Services (UWS) Server 832

Building UWS Client Applications 833

Building an UWS SDK Portal 835

Review 838

The Next Generation of Web Services

Crystal .NET developers have enjoyed the ability to publish a Crystal Report as a web service for several years. For small deployments of unmanaged reports, tightly integrated into custom .NET applications, this is an appropriate and terrific capability. For larger deployments with a separate business intelligence (BI) infrastructure and managed report repository, this approach is not satisfactory because it is not cross-platform, does not scale, is inherently insecure, and does not expose the full range of BI services.

Prior to acquiring Crystal, Business Objects was a pioneer in BI web services, permitting customers to securely expose the BI catalog and reports themselves as web services in its v.5 product. After acquiring Crystal, Business Objects soon released Unified Web Services (UWS) 1.0, the next-generation web services implementation, with the BusinessObjects Crystal Integration Pack. UWS bridged the Crystal Enterprise 10 and Business Objects 6.5 enterprise infrastructures, providing a single “unified” façade. The integration pack implementation carries forward to XI, with a handful of improvements:

• Session—Authenticate, create a session, close a session. XI adds support for LDAP authentication.
• BI Catalog—Navigate folders, reports, office documents, program objects, and other repository objects. XI adds support for categories and personal categories.
• ReportEngine—Viewing reports interactively, filling prompts and handling drilling. XI adds cluster readiness through optional use of Page Server (versus RAS).

These services follow the WS-Interoperability Basic Profile 1.0.

By the time this book goes to print, the next iteration of UWS will be nearing release. Enhancements will include

• BI Query—Provides full access to the BusinessObjects metalayer providing a dynamic, but secure, ad hoc query gateway directly to Enterprise BI datasources.
• Microsoft Office sample applications—Extraordinary sample applications for Microsoft Word and Excel have been built using the Microsoft Visual Studio Tools for Office (VSTO). These are designed to be extended by you, the customer and developer.

Consuming Web Services

Before continuing, it is important to mention that over the past year, Business Objects released a powerful XML data driver for Crystal Reports that permits writing reports off local and remote XML files. Likewise, it also parses XML documents from SOAP formatted messages returned by web services. Web service data sources are accessed through a Web Services Description Language (WSDL) endpoint—the standard format for describing a web service. After specifying a WSDL, the driver enables you to select which service, port, and method you want to use. The XML web services driver is part of the standard Crystal Reports distribution. Be sure to check for updates on the Business Objects website.

Deciding to Use Web Services

It is perfectly reasonable to question the utility of having a web services API. After all, Business Objects provides full-featured Java and .NET APIs. In short, web service interfaces are different from traditional APIs in the following two ways:

• Non-Proprietary Transport—How the application calls travel inside a machine or through the network that connects machines within your local network or wide area network to the public internet. Rather than using a proprietary network protocol and/or high or random port, web services use HTTP/SSL, typically over port 80 or 443 respectively.
• Non-Proprietary Format—How the information is encoded so other programs can read it. Rather than using a proprietary, binary data format, web services use SOAP-formatted XML text messages exclusively.

There are several advantages to using web services. First, there are no transport-specific limitations that could prevent API-level access outside the machine, the local network, or the wide area network. The traditional BusinessObjects Enterprise client SDKs communicate with back-end services over IIOP (Corba), using a range of ports. By default, these number some 30 ports (not including Enterprise Performance Management (EPM) services), half of which are random high-ports defined at run-time. The challenge of connecting to the BusinessObjects Enterprise cluster from client SDK applications can be made easier by setting the –request and –port command switches.

By contrast, any API in the UWS SDK can be accessed over a single configurable port using TCP/IP, like any other website in your company. Often, this port is 80 or 443. With web services, any machine on the World Wide Web internet can invoke this application—thus the name web service. Additionally, with UWS, there are no programming or platform-specific limitations that restrict the client application platform. Communication is accomplished by passing specially formatted text files back and forth.

On the flip-side, there are a number of disadvantages with using web service SDKs generally. The most commonly cited ones are performance and security.

With web services, performance is a concern because application calls are not just traveling from one CPU register to another, but rather out to the network card, through a network cable, routers, routers, firewalls, routers, firewalls, millions of criss-crossing spam emails, and back through routers and firewalls to the machine on the other end. This is experienced every day when surfing the Web; there is a noticeable lag or latency between requests. What if every time you typed a letter in Microsoft Word, the program locked up, went out to MSN.com, looked up the word you were typing, checked to see whether it was spelled properly, and then returned a yes or no before letting you continue typing? What if it couldn’t just exchange with MSN.com a tiny 1 kb binary file containing the letters of the current word and a single method such as “check spelling” represented by a single code such as “CS,” but rather had to send a verbose one-page text document with a header, body, and footer, and get one back in return, which it had to open and parse using loops and regular expressions?

Converting native calls to XML documents, sending them through the networking, and deserializing them on the other end takes many CPU cycles and time. Computer people say that this is a very costly or expensive process.

On this issue of security, how does one program know that the requestor is who he says he is? Just because anyone can reach a web service does not mean he should be able to reach it. The most common approach to solving this problem is to simply require people seeking access to provide a username/password credential and to encrypt traffic through an SSL tunnel so nobody can “snoop” on it and read that information. This approach is supported by Business Objects UWS. Certificates guarantee the physical address of the receiver and/or the sender. Emerging standards might resolve this quandary issue.

Service-Orientated Architecture Explained

As described above, finely grained calls to remotely hosted programs simply don’t work. Microsoft would never dream of hosting the always-on Word spell checker remotely.

In fact, such approaches don’t work in most distributed environments. Java programmers will remember what happened when “experts” ported their finely grained JavaBeans to EJB architectures: every getter and setter required a call over the network to the EJB server. No matter how much hardware you threw at these programs, they ran very slowly. Over time, programmers wised-up and built their objects locally before sending them over to the EJB server for processing or manipulation. Moreover, they began to bundle together objects and methods to perform on those objects so fewer network requests would be needed to get the job done. As interfaces became less object specific, they were no longer object oriented; they acted like commands of a prior generation of procedural languages.

The term service oriented was developed to describe this new approach generically. Service orientation is simply the idea that to facilitate efficient interoperability, especially in distributed environments, software applications should expose fewer, more functionally meaningful (but internally opaque) interfaces to other applications. Web services follow this approach and are increasingly synonymous with the service orientated architectures (SOA). Web services make their calls by passing around text messages and are therefore also called message oriented.

Object-Oriented and Message-Oriented APIs Compared

Because web service calls are so inefficient (bloated XML traveling over congested networks), API designers attempt to require a minimum number of them. Pseudo-code Table 32.1 compares (good) web services message-oriented APIs with traditional, locally accessed object-oriented APIs.

Table 32.1. Object Oriented and Web Service Oriented APIs Compared

Adapted from Business Objects, Unified Web Services Developer’s Guide, p. 14

Although this approach might seem unnatural to object-oriented programmers, it cuts down the number of remote calls, thereby increasing performance.

SOAP, WSDL, and UDDI

Web service requests are XML text provided in a standard format called Standard Object Access Protocol (SOAP). SOAP is a W3C standard that defines how web service messages are structured. Specifically, SOAP describes the header and footer “envelope” that surrounds the data being exchanged. Web Services Description Language (WSDL), also a W3C standard, refers to the structure of the XML documents that describe web services so applications know what arguments their SOAP requests should contain, what data they should expect in the response, and the network address of the service.

Although showing neither the full WSDL nor SOAP documents, Figure 32.1 shows how WSDL documents describe the data SOAP requests must contain and what they should expect back from the service in return.

Figure 32.1. WSDL-SOAP relationship example highlighting common usage.

To facilitate sharing these interface specifications, WSDLs are often published to a Universal Description, Discovery, and Integration (UDDI) directory service that itself has a well-known interface. Obviously, not every service would be published to the outside world.

These standard-based interfaces facilitate automated discovery and invocation of web services between software applications that know nothing about one another. Web services client applications, such as Cape Clear permit users to browse UDDI directories to identify web services of interest, download their WSDL interface files, and build a simple form through which a user can invoke a web service with the arguments the service expects and see a resulting data grid.

In the current implementation of UWS, it is possible to publish the three BI services to UDDI. Used together in sequence—create a session, browse the catalog, and retrieve report data—these services do permit full access to assets in the BusinessObjects Enterprise repository. On the other hand, this implementation is like publishing a listing for the White Pages in the Yellow Pages; it’s impossible to identify your BI assets from the Directory listing.

Customers might find it more useful to write a wrapper around these services that exposes a single report (including login, prompt, and formatting inputs) as a WSDL in a UDDI directory. Extend this with a publishing wizard for publishing WSDLs for all reports. With tools such as .NET Studio or Weblogic Workshop, this should not be difficult.

BI Web Services in the Real World

Given these interesting capabilities of a web services SDK, how are Business Objects customers actually using it? Here, two common use-cases are presented: portals and extranets, and EAI.

Portals and Extranets

By reducing or eliminating firewall concerns, UWS enables a wide variety of integration scenarios that were previously impossible.

Business Objects customers commonly use UWS to provide deep integration of reporting and analysis into their centrally hosted Java or .NET portals. The portal might be pulling data from BusinessObjects Enterprise servers at remote locations or even outside the company at partner locations. The other side of this coin is to offer BI services to remote and partner portals using UWS.

Enterprise Application Integration (EAI)

One of the most compelling cases for deploying BI web services is for traditional application integration. Crystal Reports, for instance, makes it a trivial matter to extract data from SAP by writing complex BAPI code within its datasource adapter. In addition to providing impressive data access capabilities, including joining heterogeneous datasources, Crystal Reports permits complex business logic, including custom compiled functions, to be applied to that data. Additionally, through BusinessObjects Enterprise, Crystal Reports can be scheduled to run and archive at night, providing historical snapshots.

When exposed securely to client applications in the enterprise, Crystal Reports become the perfect connector to live and historical data from any or all enterprise data sources. Traditional application integration tools, such as SeeBeyond or WebMethods, are vastly more expensive and complex to configure than setting up a BusinessObjects Enterprise XI server and writing a few Crystal Reports!

One customer, a large defense contractor, saves approximately $10,000 per EAI flow handled through BI report versus a traditional EAI tool. The firm’s CIO’s office has wrappered BusinessObjects Enterprise web services with .NET code, exposing individual reports as XML data providers within their UDDI directory. Figure 32.2 highlights this usage pattern.

Figure 32.2. Architecture model: Web services as EAI.

Configuring the Unified Web Services (UWS) Server

The Unified Web Services (UWS) server component is a J2EE Web application that uses the Apache Axis web services library. Even if you are connecting to UWS from .NET, you must deploy the server component on a Java application server.

To deploy the UWS server, follow these steps:

1. Configure a JAVA_HOME environment variable with the operating system. Set JAVA_HOME=C:Program FilesBusiness ObjectsJavaSDK
2. Unzip C:Program FilesBusiness ObjectsBusinessObjects Enterprise 11Web Servicesdsws_webservice_boedatadswsBobjeAssembly.zip to C:Program FilesBusiness Objects. This creates a dswsBobjeAssembly directory.
3. Change directories to the dswsBobjeAssembly directory.
   

   cd C:Program FilesBusiness ObjectsAssembledswsBobjeJava

4. Build a WAR file by opening a CMD prompt and calling the dswsBobjeAssemblyEn batch file.
   

   

   Your code might look like this example:

   > dswsBobjeAssemblyEn.bat DCAKRINSKYO2.crystald.net 8080 DCAKRINSKY02

A successful build will look something like the console output shown in Figure 32.3.

Figure 32.3. Successful UWS build console output.

5. Copy the WAR file C:Program FilesBusiness ObjectsAssembledswsBobjeJavadswsboje.war to Tomcat C:Program FilesBusiness ObjectsTomcatwebapps. It will be deployed as an application called dswsbobje.

You can test your configuration by calling a URL such as http://dcakrinskyo2.crystald.net:8080/dswsbobje/happydsws.jsp. At the same time, you should test that the WSDL files deployed by the service are correct by looking in the exploded dswsbobjeWEB-INFclasses directory under Tomcatwebapps. Search for soap:address to find the URL for accessing the various services. Sometimes these services will be on machines that differ from the initial connection URL, so you might need to change them from the defaults. Here’s the default which corresponds to the preceding implementation:

UWS may also be configured to use SSL. This requires that the client application use an X509 public key certificate for communication. More information on setting up this configuration is not in the core documentation; look for it in a documentation update and/or on the support site.

Building UWS Client Applications

The fact that this kind of application-to-application interaction is possible at all demonstrates the flexibility of web services. Web services present a text-file interface over HTTP(s) to any back-end service. As such, you can interact with these services directly through HTTP(s) and XML parsing. From a programming standpoint, however, this direct approach takes plenty of knuckle grease.

You can write the code to build XML documents, request and receive them from the web service, and parse responses into something meaningful, if you like. Or, you can simply use the Business Objects Java or .NET consumer SDK libraries to do the dirty work for you. These SDKs make WSDL conformant requests to the UWS server, which in turn interacts with BusinessObjects Enterprise XI over HTTP or SSL through a Java-based program designed for sending and receiving SOAP requests. Additionally, this SDK supports requests to clustered environments transparently by handling the state internally.

Listing 32.1 uses the Java-consumer SDK to output HTML from reportID=386.

Listing 32.1. Simple UWS Report Viewer

In the snippet above, notice how output format and view mode are specified. Tables 32.2 and 32.3 show all of the retrieval options possible for Crystal Reports and WebI Documents respectively.

Table 32.2. UWS View Types and View Modes Supported for Crystal Reports

Table 32.3. UWS View Types and View Modes Supported for WebIntelligence

Because Web Intelligence supports retrieval of multiple, incongruous resultsets, WebIntelligence XML documents contain sections per resultset or data provider. With Crystal Reports, XML is returned using the RAS Rowset Controller because XML is not yet a first-class export format through the page server in this release.

Building an UWS SDK Portal

Now that you know how about using the web services SDK, you can now build BI portals using it. As with the samples provided for deploying the Business Objects Enterprise SDK, you can download a white-box starter portal using the web services SDKs at www.usingcrystal.com. Table 32.4 shows several of the files you will find.

Table 32.4. White-box UWS SDK Portal JSP Pages

Portions of these pages are described in greater detail in the sections that follow.

Setting Up a Consumer SDK Project

Using the UWS Consumer SDKs in the Java environment requires the 1.4.2 version of the Java 2 SDK Standard Edition and a Java application server. Client jar and .NET assemblies can be found in the Web Servicesendsws_consumerdata directory of the installation directory. For J2EE clients, unzip the client JAR files from dswsJavaApi.zip into the WEB-INFlib directory of your project. These files include dsws-bicatalog.jar, dsws-common.jar, dsws-reportengine.jar, dsws-session.jar, and wilog.jar. Additionally, the implementation requires these six jars that are part of the Apache Axis distribution: Axis.jar, commons-discovery.jar, Jaxrpc.jar, Saaj.jar, Wsdl4j.jar, and Jtools.jar. If you followed the previous build instructions, these files will be in the C:Program FilesBusiness ObjectsAssembledswsBobjeJavasrcWEB-INFlib Directory. For rich Java clients, add these JAR files to your application’s classpath. Note that these JARs are considerably smaller than those required to deploy the alternative CORBA-based SDK application.

Checking Authentication

As with the SDK portal shown in Chapter 30, “Using the BusinessObjects Enterprise APIs,” every page (except for login.jsp) in the UWS portal includes a special JSP page, check_authentication_uws.jsp, that ensures that the user has logged in properly. This page can process for credentials posted from the login page or create a page-level pointer to an EnterpriseSession in application session scope. In the event that an EnterpriseSession does not exist or has timed-out, it sends a user to the login page.

Listing 32.2 contains login code from check_authentication_uws.jsp which shows how to create a new session from a username and password.

Listing 32.2. Creating a New UWS Session

Listing 32.3 shows the login form itself, which is found in login.jsp. What is different about this login page versus the CORBA SDK code is that it does not reference a CMS name, but rather the UWS server endpoint URL. In this application, the actual URL is stored in the property file under the key UWS_CONNECTION_URL.

Listing 32.3. Simplified Logon Form

Keeping sessions alive longer than necessary may tie-up licenses and server memory. Be sure to provide a logout page that includes logic to close the Business Objects session (see Listing 32.4) and optionally invalidate the appserver session.

Listing 32.4. Logging Off

The default page is the UWS portal is directory.jsp. This page renders a permission-aware folder catalog. Reports can be viewed as HTML by clicking on their name and as PDF by clicking on the PDF icon. It renders a pseudo-breadcrumb at the top of the page. Portions of directory.jsp are shown in Listing 32.5.

Listing 32.5. Listing Folders and Reports

Finally, the UWS viewer page (viewer.jsp) is used to output a report as HTML or PDF and a second file (getImage.jsp) is used to render image call-backs. Drilling in CrystalReports and simple text prompts are supported. These listings are quite long and can be downloaded from usingcrystal.com.

Review

Web services are by now the most exciting new paradigm in software development. They allow disparate systems to communicate with each other over non-proprietary protocols (HTTP) using a non-proprietary data exchange format (XML text files). This flexibility comes at a cost. Performance and security are often cited. Performance issues are partially overcome through web service SDK design. Developers will notice that methods are more coarse-grained than object-oriented design patterns.

Business Objects provides a rich web services SDK for browsing folders and securely accessing Crystal Reports and WebIntelligence documents in the BOE repository. In the next release you will be able to query the Universe meta-layer directly as well. You can get started using the UWS SDK by reviewing the code in this chapter and by downloading a ready-to-run sample portal from www.usingcrystal.com.