IBM Cognos 8 BI XML as a Data Source

Nature of Document: Tip or Technique Product(s): IBM Cognos 8 BI Area of Interest: Infrastructure, Modeling

Business Analytics

IBM Cognos 8 BI XML as a Data Source Copyright and Trademarks Licensed Materials - Property of IBM. Copyright IBM Corp. 2010

IBM, the IBM logo, and Cognos are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or technical inaccuracies may exist. IBM does not accept responsibility for any kind of loss resulting from the use of information contained in this document. The information contained in this document is subject to change without notice. This document is maintained by the Best Practices, Product and Technology team. You can send comments, suggestions, and additions to cscogpp@ca.ibm.com.

Business Analytics

IBM Cognos 8 BI XML as a Data Source

Table of Contents
1 Introduction..................................................................................................................4
1.1 1.2 1.3 1.4 Purpose........................................................................................................................ 4 Applicability.................................................................................................................. 4 Assumptions................................................................................................................. 4 Exceptions.................................................................................................................... 4

2 Overview...................................................................................................................... 4 3 Valid XML for IBM Cognos 8........................................................................................... 4 4 Connect to an XML File on the File System...................................................................... 6 5 Connect to an XML File over HTTP..................................................................................9 6 Transform XML for Use in IBM Cognos 8....................................................................... 11 7 Setting up the Provided Sample....................................................................................13
7.1 7.2 7.3 7.4 8.1 8.2 Unpack the Installation................................................................................................ 13 Configure the Installation............................................................................................. 13 Build the WAR file........................................................................................................ 14 Deploy the WAR file..................................................................................................... 14 Run a Script to Generate an XML File............................................................................ 15 Call a JSP to Stream XML Data Over HTTP..................................................................... 17

8 Transforming an RSS Feed into Consumable XML.......................................................... 15

9 Conclusion...................................................................................................................19

Business Analytics

IBM Cognos 8 BI XML as a Data Source

1 Introduction
1.1 Purpose
This document will illustrate techniques for connecting to XML data sources with IBM Cognos 8.

1.2 Applicability
The techniques in this document were tested with IBM Cognos 8 BI version 8.4.

1.3 Assumptions
This document assumes familiarity with Framework Manager, XML, JSP code, shell scripts, and deploying an application to an application server or servlet/JSP container. Administrator privileges will be required to create data sources in IBM Cognos 8.

1.4 Exceptions
The techniques in this document are intended for smaller XML data sets. Testing is required to ensure acceptable performance in the environment these techniques are used. For larger data sets or more flexible XML implementations consider using IBM Cognos Virtual View Manager.

2 Overview
IBM Cognos provides many types of data sources to connect to for reporting. XML is one of them and is done without any extra infrastructure requirements such as middleware. Administrators can connect directly to an XML file, or access XML via a URL. For the latter, the XML source can be an XML file residing in a Web server directory, or can be XML that is streamed programmatically, such as with a JavaServer Page (JSP). This document will provide examples of how to implement these methods.

3 Valid XML for IBM Cognos 8

When using IBM Cognos 8 to connect directly to an XML source, the XML source must adhere to the schema found in the xmldata.xsd schema file located in <IBM Cognos 8 install location>\c8\bin. It is not necessary to specify the location of the schema in the XML source file itself. The XML source simply needs to validate with the xmldata.xsd file. Here is a brief listing of some of the data types supported. xs:int xs:string xs:double xs:byte xs:date

Business Analytics

IBM Cognos 8 BI XML as a Data Source

Please refer to the xmldata.xsd schema file and the documentation for more information and a full listing of the supported data types. Below is a small example of what a valid IBM Cognos 8 XML data source looks like.
<?xml version="1.0" encoding="UTF-8"?> <dataset xmlns="http://developer.cognos.com/schemas/xmldata/1/" xmlns:xs="http:// www.w3.org/2001/XMLSchema-instance"> <metadata> <item name="AsOfDate" type="xs:string" length="12"/> <item name="RateOfReturn" type="xs:double"/> <item name="FamAcctIndex" type="xs:string" length="3"/> <item name="RowID" type="xs:string" length="1"/> <item name="BrM" type="xs:string" length="1"/> <item name="ProductLineCode" type="xs:int"/> </metadata> <data> <row> <value>Apr 26, 2002</value> <value>0.210066429</value> <value>JA1</value> <value>F</value> <value>B</value> <value>1</value> </row> <row> <value>Apr 27, 2002</value> <value>0.1111111</value> <value>BBB</value> <value>G</value> <value>B</value> <value>2</value> </row> </data> </dataset>

Business Analytics

IBM Cognos 8 BI XML as a Data Source

It is important to note that the length attribute affects the efficiency of processing the XML data by IBM Cognos 8. Memory is allocated to the number specified in the length attribute regardless of the actual size of the data. For example, if the largest piece of data for an element is 50 characters, but a higher value is chosen for the length attribute, such as 255, memory will be allocated for the full 255. It is recommended to specify a length as close as possible to the largest estimated piece of data. Again, for more flexible implementations of XML as a data source, consider using IBM Cognos Virtual View Manager.

4 Connect to an XML File on the File System

Provided with this document is a file called Test.xml which conforms to the xmldata.xsd schema. This file contains the structure of a basic XML data source. In the following steps, a data source connection will be made to the Test.xml file and then a Framework Manger model will be created using this new XML data source. 1. Place the provided Test.xml file somewhere on the file system. In this example, the file is placed on the root of the C drive. 2. Open Framework Manager and create a new project called XML File Test. 3. Select a Design Language, and then click OK. 4. Under Select Metadata Source, select Data Sources, and then click Next. 5. Click the New button. 6. Click Next, and then in the Name field, type xmlFileTest.

Business Analytics

IBM Cognos 8 BI XML as a Data Source

7. Click Next, and then select XML as the data source type.

8. Click Next, and then in the Connection string box, enter the full or UNC path to the Test.xml file.

A UNC path is recommended when the XML file is on a share and needs to be accessed by

Business Analytics

IBM Cognos 8 BI XML as a Data Source

multiple IBM Cognos 8 servers. If a local path is used, a copy of the XML file will need to be placed in that location on each IBM Cognos 8 server, whic requires more maintenance. 9. Click Finish, and then click Close. 10. Select xmlFileTest as a data source, and then click Next. 11. Select Tables. (In this portion of the UI, the tree can be expanded to see the items being imported as seen below.)

12. Click Next, click Import, and then click Finish. 13. In the Project Viewer pane, expand the xmlFileTest namespace. 14. Right-click the xmlFileTest query subject, click Test and then click Test Sample.

Business Analytics

IBM Cognos 8 BI XML as a Data Source

The data in the XML file is retrieved. 15. Click Close, and then expand the xmlFileTest query subject.

The item names found in the XML document are represented by query items. At this point a package can be created and published to be used as a reporting source in IBM Cognos 8.

5 Connect to an XML File over HTTP

In this example, the Test.xml file provided will be copied to a virtual directory and then referenced as a data source in IBM Cognos 8. 1. Place the provided Test.xml file in <IBM Cognos 8 install directory>\webcontent. Any virtual directory can be used, but for the purposes of this example and ease of implementation, the webcontent directory will be used, which is a virtual directory for the IBM Cognos 8 application. 2. Open Framework Manager and create a new project called XML Over HTTP Test. 3. Select a Design Language, and then click OK. 4. Under Select Metadata Source, select Data Sources, and then click Next. 5. Click the New button. 6. Click Next, and then in the Name field, type xmlOverHTTPTest.

Business Analytics

IBM Cognos 8 BI XML as a Data Source

7. Click Next, and then select XML as the data source type.

10

8. Click Next, and then in the Connection string box, enter the full URL to the Test.xml file, in this case http://localhost/cognos8/Test.xml. It is recommended that localhost be replaced with the actual server name or IP address.

9. Click Finish, and then click Close.

Business Analytics

IBM Cognos 8 BI XML as a Data Source

10. Select xmlOverHTTPTest as a data source, and then click Next. 11. Select Tables, click Next, click Import, and then click Finish. 12. In the Project Viewer pane, expand the xmlOverHTTPTest namespace.

11

13. Right-click the xmlOverHTTPTest query subject, click Test and then click Test Sample.

Again, the data in the XML file is retrieved, but this time over HTTP. 14. Click Close. At this point a package can be created and published to be used as a reporting source in IBM Cognos 8.

6 Transform XML for Use in IBM Cognos 8

As mentioned earlier in this document, before an XML data source can be used in IBM Cognos 8, it must adhere to the schema found in the xmldata.xsd schema file located in <IBM Cognos 8 install location>\c8\bin. If the source XML does not conform to this schema, Extensible Stylesheet Language Transformations (XSLT) can be used in conjunction with a programming language of choice to transform the source XML into IBM Cognos 8 consumable XML.

Business Analytics

IBM Cognos 8 BI XML as a Data Source

12

In the diagram below, a calling application, which can be any one of a number of programming languages or shell scripts, retrieves the XML from the source location. For example, the application may pull an RSS feed from a web site. The calling application then references an XSLT file that is used to transform the source XML into a different XML document, in this case, one that is appropriate for IBM Cognos 8.

Original XML Source

Calling Application
(Shell Script, JSP, etc.)

IBM Cognos 8 Consumable XML

IBM Cognos 8

Referenced XSLT

The calling application can write the XML to a file which IBM Cognos 8 can connect to on the file system or over HTTP through a virtual directory. This is a good choice if the resulting XML document is larger in size and has relatively static data. If the calling application is Web-based, such as a JSP, it can directly stream the XML to IBM Cognos 8. This is more suitable when there is a requirement for real time data where the XML source is smaller in size (the transformation of the source XML will occur each time the JSP is called). Both cases will be demonstrated in subsequent sections. However, before testing each scenario, the application called devWorksXMLDS, which is provided with this document, will be deployed using the Tomcat servlet/JSP container which ships with IBM Cognos 8. If deploying to another application server such as IBM WebSphere, consult the documentation for deployment instructions.

Business Analytics

IBM Cognos 8 BI XML as a Data Source

13

7 Setting up the Provided Sample

The following is a list of high level steps followed by detailed instructions required to deploy the devWorksXMLDS application provided with this document. For multi-server installs, the application must be deployed on each IBM Cognos 8 dispatcher.

Unpack the installation to an IBM Cognos 8 server Edit files that may require modification Build a WAR file Deploy the WAR file to an application server or servlet container

7.1 Unpack the Installation

Unpack the devWorksXMLDS.zip to the <IBM Cognos 8 install location>/war directory of an IBM Cognos 8 BI installation. The devWorksXMLDS directory should now be present. At this point, it is best to configure the application before building the WAR file. Only one file needs configuration per environment; devWorksXMLDS.bat for Windows and devWorksXMLDS.sh for Unix or Linux.

7.2 Configure the Installation

Navigate to <IBM Cognos 8 install location>/war/devWorksXMLDS to edit the required file. If editing the devWorksXMLDS.bat file, the following line may need to be updated to point to the correct JRE or JDK location in that environment.
set MY_JAVA="c:\Program Files\cognos\c8.4\bin\jre\1.5.0\bin\java.exe"

If editing the devWorksXMLDS.sh file, the following lines may need to be updated to point to the JRE or JDK in that environment.
if [ "$JAVA_HOME" = "" ]; then JAVA_HOME=/usr/bin fi JAVA="$JAVA_HOME/java"

Business Analytics

IBM Cognos 8 BI XML as a Data Source 7.3 Build the WAR file
Build the WAR file by running the appropriate build script for the environment. For Windows, run <IBM Cognos 8 install location>/war/devWorksXMLDS/build.bat. For UNIX or Linux, run <IBM Cognos 8 install location>/war/devWorksXMLDS /build.sh.

14

The build scripts will create the <IBM Cognos 8 install location>/war/devWorksXMLDS/ devWorksXMLDS.war file. 7.4 Deploy the WAR file
In this example, the WAR file will be deployed to the IBM Cognos 8 Tomcat server. Ensure that IBM Cognos 8 is running. Copy the <IBM Cognos 8 install location>/war/devWorksXMLDS/devWorksXMLDS.war file to the <IBM Cognos 8 install location>/webapps directory. After a short time, the IBM Cognos 8 Tomcat server will automatically unpack the WAR file. The WAR file can subsequently be deleted once released by Tomcat. The deployed application contains required JAR files which are used by the application's shell scripts and JSP.

These jar files are required for the XML implementation and transformation. The XSLT processor used by this application is Xalan-J. Detailed information about Xalan-J can be found at http:// xml.apache.org/xalan-j. The devWorksXMLDS installation is now ready for use.

Business Analytics

IBM Cognos 8 BI XML as a Data Source

15

8 Transforming an RSS Feed into Consumable XML

The devWorksXMLDS application provides two mechanisms by which an RSS XML feed can be transformed into IBM Cognos 8 consumable XML: 1. by running a shell script (devWorksXMLDS.bat for Windows or devWorksXMLDS.sh for UNIX or Linux) which stores the transformed XML data in a file 2. by calling a JSP and streaming the transformed XML data over HTTP Both methods use XSLT to transform the source data into an IBM Cognos 8 consumable XML document.

8.1 Run a Script to Generate an XML File

The devWorksXMLDS shell scripts provided retrieve XML from an RSS feed (in this case from the IBM developerWorks site), transforms the XML into IBM Cognos 8 consumable XML and stores it in a file on the file system. This file can act as an IBM Cognos 8 data source by connecting to the file through a local path or UNC path or by calling the file from a virtual directory over HTTP.

IBM Developer Works RSS Feed

devWorksXMLDS bat or sh file

IBM Cognos 8 Consumable XML File

IBM Cognos 8

Referenced XSLT

Again, this method is best suited for larger data sets and where the underlying data is relatively static. The data is refreshed by running the script on a pre-determined schedule. The syntax for running the script with parameters is: Windows
devWorksXMLDS <sourceXML> <xsltFile> <outputXML>

Unix or Linux
./devWorksXMLDS.sh <sourceXML> <xsltFile> <outputXML>

The sample scripts provide default values for the parameters, but if any parameter requires a different value than the default, all parameters must be specified.

Business Analytics

IBM Cognos 8 BI XML as a Data Source

16

Once the script is run, an XML file appears in the specified output location which can be used as a data source for IBM Cognos 8. By default, the output location is the same location as the shell script.

This file can now be connected to in an IBM Cognos 8 data source connection through the file system as shown below:

The full connection string reads: C:\Program Files\cognos\c8\webapps\devWorksXMLDS\devWorksXMLDS.xml Again a UNC path is recommended so that the file may be accessed by multiple IBM Cognos 8 servers.

Business Analytics

IBM Cognos 8 BI XML as a Data Source

17

If the XML file is in a virtual directory (as is the case with this example), the connection string would be as shown below:

The full connection string reads: http://localhost:9300/devWorksXMLDS/devWorksXMLDS.xml Localhost should be replaced by the server name or IP address.

8.2 Call a JSP to Stream XML Data Over HTTP

Again, this method is typically used when there is a requirement for real time data that will not be resource intensive. The amount of data should be small in order to ensure performance. The sample devWorksXMLDS JSP provided retrieves XML from an RSS feed (again, from the IBM DeveloperWorks site), transforms the XML into IBM Cognos 8 consumable XML and then streams it to IBM Cognos 8.

IBM Developer Works RSS Feed

devWorksXMLDS JSP page

IBM Cognos 8 Consumable XML Stream over HTTP

IBM Cognos 8

Referenced XSLT

No data is stored with this method.

Business Analytics

IBM Cognos 8 BI XML as a Data Source

18

The URL to call the JSP is http://<server>:<port>/devWorksXMLDS/devWorksXMLDS.jsp, where <server>:<port> is the the application server that the devWorksXMLDS web application was deployed to. This is the same URL to be specified when configuring the Connection String property for the IBM Cognos 8 data source. In this example, the URL to the JSP deployed to Tomcat is http://localhost:9300/ devWorksXMLDS/devWorksXMLDS.jsp where localhost is replaced by the actual server name or IP address. To test the application, enter the URL in a Web browser. The results should appear similar to the screen capture below.

The location of the source data and the XSLT file is specified within the JSP. The variable sXMLSrc specifies the location of the source XML data and the variable sXSLTFile specifies the location of the XSLT file.

Business Analytics

IBM Cognos 8 BI XML as a Data Source

This page can now be connected to in an IBM Cognos 8 data source connection as shown below:

19

The full connection string reads: http://localhost:9300/devWorksXMLDS/devWorksXMLDS.jsp

9 Conclusion
Using the steps and sample code provided with this document can help to quickly implement XML as a data source in an IBM Cognos 8 environment.

Business Analytics