SAP Business objects Enterprise XI 3.0 Query as a Web Service

Query as a Web Service

BusinessObjects Enterprise XI 3.0

windows

© 2008 Business Objects, an SAP company. All rights reserved. Business Objects owns the following U.S. patents, which may cover products that are offered and licensed by Business Objects: 5,295,243; 5,339,390; 5,555,403; 5,590,250; 5,619,632; 5,632,009; 5,857,205; 5,880,742; 5,883,635; 6,085,202; 6,108,698; 6,247,008; 6,289,352; 6,300,957; 6,377,259; 6,490,593; 6,578,027; 6,581,068; 6,628,312; 6,654,761; 6,768,986; 6,772,409; 6,831,668; 6,882,998; 6,892,189; 6,901,555; 7,089,238; 7,107,266; 7,139,766; 7,178,099; 7,181,435; 7,181,440; 7,194,465; 7,222,130; 7,299,419; 7,320,122 and 7,356,779. Business Objects and its logos, BusinessObjects, Business Objects Crystal Vision, Business Process On Demand, BusinessQuery, Cartesis, Crystal Analysis, Crystal Applications, Crystal Decisions, Crystal Enterprise, Crystal Insider, Crystal Reports, Crystal Vision, Desktop Intelligence, Inxight and its logos , LinguistX, Star Tree, Table Lens, ThingFinder, Timewall, Let There Be Light, Metify, NSite, Rapid Marts, RapidMarts, the Spectrum Design, Web Intelligence, Workmail and Xcelsius are trademarks or registered trademarks in the United States and/or other countries of Business Objects and/or affiliated companies. SAP is the trademark or registered trademark of SAP AG in Germany and in several other countries. All other names mentioned herein may be trademarks of their respective owners.

Third-party Contributors

Business Objects products in this release may contain redistributions of software licensed from third-party contributors. Some of these individual components may also be available under alternative licenses. A partial listing of third-party contributors that have requested or permitted acknowledgments, as well as required notices, can be found at: http://www.businessobjects.com/thirdparty

2008-09-03

Introduction to Query as a Web Service 7Chapter 1

What is Query as a Web Service?...............................................................8

How is Query as a Web Service used as a business solution?...................8

Server and client component architecture of Query as a Web Service.......9

Installing Query as a Web Service 11Chapter 2

Installation pre-requisites for Query as a Web Service.............................12

To install and validate Query as a Web Service........................................12

Troubleshooting Query as a Web Service installation...............................15

Starting Query as a Web Service 19Chapter 3

Startup pre-requisites for Query as a Web Server.....................................20

How to start Query as a Web Service........................................................20

How to manage Hosts...............................................................................23

Query Catalog page...................................................................................25

Ensure the CMS starts up before Tomcat............................................15

Changing the default CMS...................................................................15

Activating web service traces...............................................................16

Optimizing CMS availability..................................................................17

To start Query as a Web Service for the first time................................20

To start Query as a Web Service..........................................................21

To log in with different login credentials................................................23

To add a new Host................................................................................24

To edit a Host.......................................................................................24

Query as a Web Service 3

Contents

Creating a new query to publish as a web service 27Chapter 4

Create and publish a new query as a web service....................................28

How to create a new query using the Publish as a Web Service wizard....28

To start the Publish as a Web Service wizard......................................29

To set query name and description properties.....................................29

To select a universe for a query...........................................................32

To define a query..................................................................................32

To preview and publish a query............................................................35

How to create a new query by duplicating a published query...................36

To duplicate a existing published query...............................................36

Managing queries as web services 37Chapter 5

To create folders in the Query Catalog......................................................38

To edit a query as a web service...............................................................38

To rename a query.....................................................................................38

To delete a query as a web service...........................................................39

To copy and paste a query as a web service.............................................39

To view query properties............................................................................39

To view available query web service instances ........................................40

How to deploy queries to another web server...........................................41

To deploy to another server using the Query as a Web Service client

tool........................................................................................................41

To deploy Query as a Web Service from Import Wizard .....................42

To deploy Query as a Web Service from a BIAR file............................43

To deploy to another server using the Query as a Web Service client

tool.............................................................................................................44

To deploy to another server using the Query as a Web Service client

tool........................................................................................................44

To deploy Query as a Web Service from Import Wizard .....................45

To deploy Query as a Web Service from a BIAR file............................46

4 Query as a Web Service

Contents

To deploy Query as a Web Service from Import Wizard ...........................47

To deploy to another server using the Query as a Web Service client

tool........................................................................................................48

To deploy Query as a Web Service from Import Wizard .....................49

To deploy Query as a Web Service from a BIAR file............................49

To deploy Query as a Web Service from a BIAR file.................................50

To deploy to another server using the Query as a Web Service client

tool........................................................................................................51

To deploy Query as a Web Service from Import Wizard .....................52

To deploy Query as a Web Service from a BIAR file............................53

Deploying Query as a Web Server over multiple web servers..................54

To configure Query as a Web Service Client to connect to a reverse proxy

web server............................................................................................54

Consuming queries as web services with different applications 55Chapter 6

Consuming a query as a web service using WSDL...................................56

Consuming a query as a web service in Crystal Xcelsius.........................56

Cross-domain issue..............................................................................57

To select the web service.....................................................................58

Input messages....................................................................................58

Output messages.................................................................................58

Authentication in Xcelsius....................................................................59

Consuming a Query as a Web Service in Crystal Reports........................59

Consuming a Query as a Web Service in Microsoft Office InfoPath.........60

Query as a Web Service Best Practices and Limitations 63Chapter 7

Best Practices using Query as a Web Service..........................................64

Limitations using Query as a Web Service................................................64

Query as a Web Service 5

Contents

Get More Help 65Appendix A

Index 69

6 Query as a Web Service

Introduction to Query as a Web Service

What is Query as a Web Service?

Query as a Web Service is a Business Objects application that allows business users to quickly create queries and publish them as web services.

A query as a web service is a SQL statement that has been built on a BusinessObjects universe and published as a web service to a host server housing web services.

The query as a web service is available to any application that uses web services, and allows users to access data returned by the query from within the application. It allows Business Intelligence (BI) information to be securely delivered to any application that can consume web services.

Query as a Web Service has a client component that you use to create queries from universes, and a server-side web service that allows developers to create web services from specific Business Objects queries.

How is Query as a Web Service used as a business solution?

Query as a Web Service allows BI content to be delivered to any user interface that can process Web Services. It allows business users define their own query from a universe, and then publish that query as a standalone web service.

Query as a Web Service can be used to provide new client solutions for a business. For example, Crystal Xcelsius uses Query as a Web Service to aggregate multiple disparate data sources into a trusted BI view.

Query as a Web Service also enables a range of client-side solutions in tools such as:

• Microsoft Office, Excel, and InfoPath

• SAP NetWeaver

• OpenOffice

• Business rules and process management applications

• Enterprise Service Bus platforms

8 Query as a Web Service

Introduction to Query as a Web Service

Server and client component architecture of Query as a Web Service

Note:

Business Objects provides a wide range of Web Services for developers. Developers use these Web Services in IDEs with languages such as C# and Java. For more information, go to:

http://diamond.businessobjects.com

Server and client component architecture of Query as a Web Service

Query as a Web Service is designed to work on top of any Windows application the same way as other web services.

Query as a Web Service is based on the W3C web service specifications SOAP, WSDL, and XML. It has two main components:

• Server component

The server component (included in BusinessObjects XI R3) stores the Query as a Web Service catalog and hosts the published Web Services.

• Client tool

This is where business users create and publish queries as web services. You can install the client tool on several machines that can then access and share the same Query as a Web Service catalog stored on the server.

Note:

In this guide, the name Query as a Web Service is used to mean the client. When information is given that refers to the server component, it is referred to as the server component of Query as a Web Service .

The client communicates with the server components using Web Services.

Query as a Web Service 9

Introduction to Query as a Web Service

Server and client component architecture of Query as a Web Service

10 Query as a Web Service

Installing Query as a Web Service

Installation pre-requisites for Query as a Web Service

Before you install Query as a Web Service, you should read the Terms of Use agreement and conditions and ensure you have met the following installation pre-requisites:

The following must be installed on the server:

• BusinessObjects XI Release 3 Enterprise Edition

• Web Services

• Tomcat or another supported Web Application and JDK

For an updated list of supported Web Applications and versions, see:

http://support.businessobjects.com/supported_platforms/

The following must be installed on the client before you install Query as a Web Service :

• .NET 2.0 framework. This is required for the Query as a Web Service

client used to build and publish queries.

You can download the .NET 2.0 framework here:

http://www.microsoft.com/downloads/details.aspx?Fami lyID=0856eacb-4362-4b0d-8edd-aab15c5e04f5&Display Lang=en&displaylang=en

The client platform must be supported for use with BusinessObjects XI Release 3. For an updated list of supported versions, see:

http://support.businessobjects.com/supported_platforms/

To install and validate Query as a Web Service

The server component of Query as a Web Service installs automatically as part of BusinessObjects Enterprise XI 3.0 with Web Intelligence.

12 Query as a Web Service

Installing Query as a Web Service

To install and validate Query as a Web Service

You must then install the Query as a Web Service client on every machine that will access the server through web services.

You must have a separate license for Query as a Web Service client. It is not covered by the general license for BusinessObjects XI 3.0.

1. Navigate to the Add-Ons\Query as a Web Service folder on the

BusinessObjects Enterprise collaterals CD or locate the Query as a Web Service setup.exe file on your network.

2. Double-click setup.exe to launch the Query as a Web Service Wizard.

3. Follow the on-screen instructions in the Query as a Web Service

Installation Wizard to complete the installation procedure.

You are ready to validate your installation.

4. To validate the installation, open a browser and type the following URL

http://[server]:[port]/dswsbobje, where [server] corresponds to

your web server address and [port] corresponds to the port where you set up in your web server. The default used by Tomcat is 8080. dswsbobje is the default name of the Web Service provider web application.

5. Click the Validate link button to get a status of the installation.

6. Browse down to make sure Query as a Web Service is installed. You will

see Found resource:/managequeryasaservice.wsd

Query as a Web Service 13

Installing Query as a Web Service

To install and validate Query as a Web Service

7. In your browser, type the following URL: http://[server]:[port]/dsws

bobje/qaawsservices, where [server] corresponds to your server

address and [port] corresponds to the port where you set up your web server.

Your browser page appears and contains the title "Available QaaWS services". This page contains a list of the Query as a Web Service that have already been created on this system.

14 Query as a Web Service

Installing Query as a Web Service

Troubleshooting Query as a Web Service installation

This section contains information to help you trouble shoot potential installation problems. Refer to the linked topics at the end of the section for information concerning each of the following issues:

• Ensure CMS starts before Tomcat.

• Change the default CMS.

• Activate web service traces.

• Optimize CMS availability.

Ensure the CMS starts up before Tomcat

Ensure that the CMS is launched before Tomcat.

During launch of Tomcat, in the initialization of the Servlet, QaaWS cache reads the definition of the QaaWS in the repository to build its cache, so you must ensure that the CMS is launched before Tomcat.

If you launch the CMS automatically using the NT Services, you do not need to do this manually.

Changing the default CMS

By default, the Web Services connects to the local machine name CMS. If you want to change to a dedicated CMS, you must change the domain property in the dsws.properties file.

If you use a CMS port number different from the default (6400), and you do not change the domain property in the dsws.properties file, you receive an error message "Server not found or server may be down (FWM01003)".

The solution is to specify the new port in the dsws.properties file (located under <INSTALLPATH>\warfiles\WebApps\dswsbobje\WEB-NF\classes\) with domain attribute value (domain=CMSserverName:port).

Query as a Web Service 15

Installing Query as a Web Service

Troubleshooting Query as a Web Service installation

This information complements what is available in the Central Management System documentation.

To set a new default CMS for Query as a Web Service

1. Stop Tomcat.

2. Open the installation path folder of BusinessObjects Enterprise XI Release

3: [InstallationPath]\warfiles\webapps\dswsbobje\WEB-

INF\classes

3. Open the file dsws.properties and locate: domain=

4. Enter your CMS name.

5. Close and save the dsws.properties file.

6. Start Tomcat.

Activating web service traces

If there is configuration issue, the Business Objects Administrator may be required to set up traces to allow better troubleshooting.

Business Objects strongly recommends using traces only for troubleshooting purposes in test environments.

To activate web service traces

1. In the Central Configuration Manager (CCM), stop "Apache Tomcat 5.5.20"

service.

16 Query as a Web Service

Installing Query as a Web Service

Troubleshooting Query as a Web Service installation

2. Change the trace level.

By default Query as a Web Service only traces errors. You may be requested to provide additional traces for customer assurance.

3. Edit log4j.properties located in [installationpath]\dswsbob

je\WEB-INF\classes\

4. Type the following in the properties file:log4j.logger.com.businessob

jects=DEBUG, BO1

5. Change the trace location.

By default, it traces in the output console output. If you want to trace a file, comment the ConsoleAppender and uncomment the RollingFileAp

pender. If Tomcat is set as a service, you will trace in dswsbobje.log

found under the file pathC:\WINDOWS\system32.: # console appender

# log4j.appender.BO1=org.apache.log4j.ConsoleAppender # log4j.appender.AXIS1=org.apache.log4j.ConsoleAppender #rolling file appender log4j.appen der.BO1=org.apache.log4j.RollingFileAppender log4j.appen der.BO1.File=dswsbobje.log log4j.appender.BO1.Append=false log4j.appender.BO1.MaxBackupIndex=5 log4j.appender.BO1.Max FileSize=10

6. In the CCM, start "Apache Tomcat 5.5.20" service.

Optimizing CMS availability

The CMS can have only one single CMS system database. The connection with CMS system database can be lost for the following reasons:

• The database is down.

• A network outage between CMS and CMS System database.

• A software or hardware failure of CMS machine or application.

In any of these cases, deploying two CMS decreases the probability that both CMS will be unable to communicate with the CMS system database that is on the CMS machine.

However, if the CMS system database is down then all CMS will be unable to process incoming requests without errors, regardless of whether there are a single CMS or multiple CMSs in the cluster.

Query as a Web Service 17

Installing Query as a Web Service

Troubleshooting Query as a Web Service installation

You can limit the risk by employing the fault tolerance solutions provided by the database vendor. Each database vendor provides fault tolerance solutions to minimize the risk of the database being unavailable. One fault tolerance option may be to set up a secondary mirror database that runs on a secondary server. For example, if the first database is out the tns.ora file is automatically updated to point to the secondary database server. Since available fault tolerance measures are database-specific, see the documentation for your specific database vendor for more information on fault tolerance measures.

Note:

If the feature is available and enabled, even if the system database connection is lost, the CMS automatically re-establishes the database connection without administrator intervention.

18 Query as a Web Service

Starting Query as a Web Service

Startup pre-requisites for Query as a Web Server

Ensure that the following pre-requisites are completed before you start Query as a Web Service:

DescriptionStartup pre-requisites

You define user group membership in User logged in as Administrator or defined in QaaWS Group Designer.

the Central Management Console. If

you need to be added to this user

group, see your administrator.

How to start Query as a Web Service

Query as a Web Service is used with a Central Management System (CMS). The CMS contains the server component that stores the Query as a Web Service catalog and hosts the published Web Services.

When you start Query as a Web Service for the first time, you must define the host server before starting.

Each successive time you start Query as a Web Service you select an available host server, then log into the CMS.

Once you are logged in, the Query as a Web Service startup Query Catalog page appears. From this page you can start the query creation and publication wizard to publish a new query and edit existing published queries.

To start Query as a Web Service for the first time

When you start Query as a Web Service for the first time, you must define a host server in the CMS where the web services are installed. Once you have defined a host server, this host is automatically available the next time you start Query as a Web Service. You can define multiple host servers, but you can only connect to one at a time.

20 Query as a Web Service

Starting Query as a Web Service

How to start Query as a Web Service

1. Start Query as a Web Service.

The "Manage Hosts" dialog box appears. This dialog box lists available host servers, and allows you to add new servers and edit existing ones. The first time you start Query as a Web Service the list is empty. You must firstly define a host server.

2. Click Add.

The "Edit a Host" dialog box appears. This box contains the parameters that you define to create a new host server. See the section in Related Topics for a description of each parameter.

3. Enter the required information in the "Edit a Host" dialog box.

4. Click OK.

The "Manage Hosts" dialog box appears. The new host is now listed.

5. Select the new host and click Close.

The "Select your credentials" login box appears. The new host information is available.

6. Enter your password, then click OK.

The Query as a Web Service client start up page appears.

To start Query as a Web Service

Before you start Query as a Web Service, ensure that you have met the following pre-requisites. See the Related Topics for more information.

• Your user name must be in the user group QaaWS Group Designer, or

you must be logged in as Administrator.

• You have defined a server host to store the query web service. You do

this when you start Query as a Web Service for the first time, or at any other time by adding a host in the "Edit a Host" dialog box.

You start Query as a Web Service by selecting a host server and entering login information in the login box. You have the following login fields:

Query as a Web Service 21

+ 49 hidden pages