c8xml as a Data Source

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


Copyright and Trademarks Licensed Materials - Property of IBM.

© Copyright IBM Corp. 2010

IBM, the IBM logo, and Cognos are trademarks or registered trademarks of InternationalBusiness Machines Corp., registered in many jurisdictions worldwide. Other product andservice names might be trademarks of IBM or other companies. A current list of IBMtrademarks 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 isaccurate and complete, some typographical errors or technical inaccuracies may exist. IBMdoes not accept responsibility for any kind of loss resulting from the use of informationcontained in this document. The information contained in this document is subject to changewithout notice.This document is maintained by the Best Practices, Product and Technology team. You cansend comments, suggestions, and additions to [email protected].

Business Analytics

2

http://www.ibm.com/legal/copytrade.shtml

mailto:[email protected]


Table of Contents1 Introduction .................................................................................................................. 4

1.1 Purpose ........................................................................................................................ 4 1.2 Applicability .................................................................................................................. 4 1.3 Assumptions ................................................................................................................. 4 1.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 Unpack the Installation ................................................................................................ 13 7.2 Configure the Installation ............................................................................................. 13 7.3 Build the WAR file ........................................................................................................ 14 7.4 Deploy the WAR file ..................................................................................................... 14

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

8.1 Run a Script to Generate an XML File ............................................................................ 15 8.2 Call a JSP to Stream XML Data Over HTTP ..................................................................... 17

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

Business Analytics

3


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, anddeploying an application to an application server or servlet/JSP container. Administrator privileges willbe 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 ensureacceptable performance in the environment these techniques are used. For larger data sets or moreflexible XML implementations consider using IBM Cognos Virtual View Manager.

2 OverviewIBM Cognos provides many types of data sources to connect to for reporting. XML is one of them andis 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 XMLsource can be an XML file residing in a Web server directory, or can be XML that is streamedprogrammatically, such as with a JavaServer Page (JSP). This document will provide examples ofhow to implement these methods.

3 Valid XML for IBM Cognos 8When using IBM Cognos 8 to connect directly to an XML source, the XML source must adhere to theschema found in the xmldata.xsd schema file located in <IBM Cognos 8 install location>\c8\bin. It isnot necessary to specify the location of the schema in the XML source file itself. The XML sourcesimply needs to validate with the xmldata.xsd file.

Here is a brief listing of some of the data types supported.

xs:intxs:stringxs:doublexs:bytexs:date

Business Analytics

4


Please refer to the xmldata.xsd schema file and the documentation for more information and a fulllisting 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

5


It is important to note that the “length” attribute affects the efficiency of processing the XML data byIBM Cognos 8. Memory is allocated to the number specified in the “length” attribute regardless of theactual size of the data. For example, if the largest piece of data for an element is 50 characters, but ahigher value is chosen for the “length” attribute, such as 255, memory will be allocated for the full255. 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 VirtualView Manager.

4 Connect to an XML File on the File SystemProvided with this document is a file called Test.xml which conforms to the xmldata.xsd schema. Thisfile 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 aFramework 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 isplaced 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

6


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 theTest.xml file.

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

Business Analytics

7


multiple IBM Cognos 8 servers. If a local path is used, a copy of the XML file will need to beplaced 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 beingimported 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

8


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 inIBM Cognos 8.

5 Connect to an XML File over HTTPIn this example, the Test.xml file provided will be copied to a virtual directory and then referenced asa 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 ofimplementation, the webcontent directory will be used, which is a virtual directory for theIBM 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

9


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 URL to the Test.xmlfile, in this case http://localhost/cognos8/Test.xml. It is recommended that localhostbe replaced with the actual server name or IP address.

9. Click Finish, and then click Close.

Business Analytics

10


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.

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 inIBM Cognos 8.

6 Transform XML for Use in IBM Cognos 8As mentioned earlier in this document, before an XML data source can be used in IBM Cognos 8, itmust adhere to the schema found in the xmldata.xsd schema file located in <IBM Cognos 8 installlocation>\c8\bin. If the source XML does not conform to this schema, Extensible Stylesheet LanguageTransformations (XSLT) can be used in conjunction with a programming language of choice totransform the source XML into IBM Cognos 8 consumable XML.

Business Analytics

11


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

The calling application can write the XML to a file which IBM Cognos 8 can connect to on the filesystem or over HTTP through a virtual directory. This is a good choice if the resulting XML documentis larger in size and has relatively static data. If the calling application is Web-based, such as a JSP, itcan directly stream the XML to IBM Cognos 8. This is more suitable when there is a requirement forreal time data where the XML source is smaller in size (the transformation of the source XML willoccur each time the JSP is called).

Both cases will be demonstrated in subsequent sections. However, before testing each scenario, theapplication called devWorksXMLDS, which is provided with this document, will be deployed using theTomcat servlet/JSP container which ships with IBM Cognos 8.

If deploying to another application server such as IBM WebSphere, consult the documentation fordeployment instructions.

Business Analytics

12

Original XML

Source

Calling Application

(Shell Script, JSP, etc.)

Referenced XSLT

IBM Cognos 8

Consumable XML

IBM Cognos 8


7 Setting up the Provided SampleThe following is a list of high level steps followed by detailed instructions required to deploy thedevWorksXMLDS application provided with this document. For multi-server installs, the applicationmust 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 anIBM 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 needsconfiguration per environment; devWorksXMLDS.bat for Windows and devWorksXMLDS.sh for Unix orLinux.

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 thecorrect 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 theJRE or JDK in that environment.

if [ "$JAVA_HOME" = "" ]; thenJAVA_HOME=/usr/bin

fi

JAVA="$JAVA_HOME/java"

Business Analytics

13


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.

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 IBMCognos 8 is running.

Copy the <IBM Cognos 8 install location>/war/devWorksXMLDS/devWorksXMLDS.warfile 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 WARfile can subsequently be deleted once released by Tomcat.

The deployed application contains required JAR files which are used by the application's shell scriptsand JSP.

These jar files are required for the XML implementation and transformation. The XSLT processor usedby 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

14

http://xml.apache.org/xalan-j

http://xml.apache.org/xalan-j


8 Transforming an RSS Feed into Consumable XMLThe devWorksXMLDS application provides two mechanisms by which an RSS XML feed can betransformed into IBM Cognos 8 consumable XML:

1. by running a shell script (devWorksXMLDS.bat for Windows or devWorksXMLDS.sh for UNIXor 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 XMLdocument.

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 IBMdeveloperWorks site), transforms the XML into IBM Cognos 8 consumable XML and stores it in a fileon the file system. This file can act as an IBM Cognos 8 data source by connecting to the file througha local path or UNC path or by calling the file from a virtual directory over HTTP.

Again, this method is best suited for larger data sets and where the underlying data is relativelystatic. The data is refreshed by running the script on a pre-determined schedule.

The syntax for running the script with parameters is:WindowsdevWorksXMLDS <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 adifferent value than the default, all parameters must be specified.

Business Analytics

15

IBM Developer

WorksRSS Feed

devWorksXMLDS bat or sh file

Referenced XSLT

IBM Cognos 8Consumable

XML File

IBM Cognos 8


Once the script is run, an XML file appears in the specified output location which can be used as adata 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 systemas 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 8servers.

Business Analytics

16


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


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 beresource 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 IBMDeveloperWorks site), transforms the XML into IBM Cognos 8 consumable XML and then streams it toIBM Cognos 8.

No data is stored with this method.

Business Analytics

17

IBM Developer

WorksRSS Feed

devWorksXMLDS JSP page

Referenced XSLT

IBM Cognos 8Consumable XML Stream over HTTP

IBM Cognos 8


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 wasdeployed to. This is the same URL to be specified when configuring the Connection String property forthe 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 nameor IP address.

To test the application, enter the URL in a Web browser. The results should appear similar to thescreen capture below.

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

Business Analytics

18


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


http://localhost:9300/devWorksXMLDS/devWorksXMLDS.jsp

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

Business Analytics

19

Date post:	27-Oct-2014
Category:	Documents
Upload:	viji-banu
View:	45 times
Download:	1 times

c8xml as a Data Source

Documents