Updating IBM Cognos 8 Models Using Code and XML (1)

7/27/2019 Updating IBM Cognos 8 Models Using Code and XML (1)

1/24

Guideline

Updating IBM Cognos 8 ModelsUsing Code and XMLProduct(s): IBM Cognos 8

Area of Interest: Development


2/24

Updating IBM Cognos 8 Models Using Code and XML 2

Copyright

Licensed Materials - Property of IBM

IBM Cognos Products: DOCS

(C) Copyright IBM Corp. 2010

US Govenment Users Restricted Rights - Use, duplication or disclosurerestricted

by GSA ADP Schedule Contract with IBM Corp.

CognosProprietary Information


3/24


Contents

1 INTRODUCTION .................................................................................. 42 ASSUMPTIONS ....................................................................................43 OVERVIEW .........................................................................................54 USING FRAMEWORK MANAGER TO REPLAY XML ACTION LOGS .............. .....65 USING BMTSCRIPTPLAYER TO REPLAY XML ACTION LOGS ...................... ...76 CHANGING MODELS USING JAVA AND XML ACTION LOGS ..........................86.1 RUNNING BMTSCRIPTPLAYERFROMANEXTERNALAPPLICATION............................................................. 86.2 USING IBM COGNOS 8 APISTOAPPLYCHANGESTOAMODELUSING XML ............................................9

7 JAVA APPLICATIONS USING THE JAVA FRAMEWORK MANAGER API ....... ... .118 PUTTING IT ALL TOGETHER ................................................................128.1 OPTION 1 XML INCODE .............................................................................................. 12

8.2 OPTION 2 XML INEXTERNALFILESASTEMPLATES.................................................................... 14

9 CRITERIA FOR SELECTING A TECHNIQUE ..............................................14APPENDIX A BMTSCRIPTPLAYER EXAMPLE ...........................................16APPENDIX B MDPROVIDERHELPER EXAMPLE ...................................... ..18APPENDIX C RETRIEVE A MODEL ALREADY PUBLISHED IN IBM COGNOS 8 22APPENDIX D HOW TO PUBLISH A MODEL. ......................................... ..22APPENDIX E THE FRAMEWORK MANAGER API UPDATEMETADATA METHOD 22APPENDIX G DATASOURCE CONNECTION RELATED EXAMPLES ............ .... .23

A. UPDATEACONNECTIONSTRING.............................................................................................. 23B. CREATEORUPDATEADATASOURCEAND CONNECTION. ...................................................................24C. SETTINGACONNECTIONSTRINGATRUNTIME................................................................................ 24

APPENDIX H DOCUMENTATION ON ERROR CODES. ................................24



4/24


1 IntroductionThis document describes various automation techniques that can be used tocreate and modify Framework Manager models. These automation scenarios

would be common for situations that have dynamic models that change oftenor, as with OEM organizations, are different for each customer but are basedon a common set of modeling operations. Another common situation occurswhen a model would require many man hours of repetitive operations tocreate or modify and automation would free resources to address morespecific tasks. Additionally, there may be scenarios where a model needs tobe modified in a Unix or Linux environment where the full FrameworkManager modeling tool is not available.

The focus on this document is to demonstrate capability with examples. Thisdocument should be used in conjunction with in the Framework Manager

Developer Guide. This document was based on testing with IBM Cognos 8.2,8.3, and 8.3 SP1.

As indicated in the Framework Manager Developer Guide, FrameworkManager is a data modeling product. It lets users import metadata from oneor more data sources and transform it into a business-oriented model forcreating reports. The Framework Manager Developer Guideis for developersinterested in using the collection of cross-platform Web services, libraries,and programming interfaces provided with the SDK API, to access the fullfunctionality of Framework Manager. You can use the Framework ManagerSDK to model metadata and publish packages without the use of theFramework Manager application. For more details on the FrameworkManager API and the structure of the log files please refer to the FrameworkManager Developer Guideprovided with the Cognos documentation.

2 AssumptionsThis document assumes that persons attempting this are familiar withFramework Manager, XML, writing Java code and the necessary infrastructurerequirements such as starting and stopping the IBM Cognos 8 server.

Administrator or developer privileges will be required as well as a workingknowledge of how to test Framework Manager Models by creating reports inIBM Cognos 8 in order to test the results. This document was created andtested with IBM Cognos 8.2, 8.3, and 8.3 SP1. Persons using this documentshould also have the The Framework Manager Developer Guide as areference.

The code utilized in this document is not considered production ready. It isintended to a demonstration of various techniques available for updating andor creating Framework Manager models with IBM Cognos 8. Modification orsupport for these samples is the responsibility of the user. However, feedback

on these samples is appreciated.



5/24


NOTE : An SDK licence for Cognos 8 is required if modifications are made tothe Java source code.

3 OverviewIBM Cognos 8 provides customers the ability to create and or modifyFramework Manager models in three different ways.

1. The Framework Manager modeling tool

2. BMTScriptPlayer

3. The Framework Manager API

All three techniques utilize XML to implement changes to a model (which isitself an XML document). The Framework Manager modeling tool is aWindows-only thick client application that is used to create a FrameworkManager model. This modeling tool generates and modifies XML fileswhenever any add, change or deletes are done to a Framework Managermodel. As an example, the action log files for the sample model ofgosales_goretailers are located at1:

\webcontent\samples\Models\gosales_goretailers\logs

Any time a change is made to a model you should see a file created thatcontains the package name along with a date time stamp such as

gosales_goretailers-20070828122354-log.xml

For IBM Cognos 8.3 the log files are located in the following directory:

\webcontent\samples\Models\gosales_goretailers

Starting with 8.3 there is only one log maintained and the name of the file islog.xml

Note: Some functions such as creating a datasource or a datasourceconnection can only performed using the Framework Manager API ratherthen with XML scripts. Classes such as: DataSource, DataSourceConnectionand DataSourceSignon are used to implement this capability. See theexample in Appendix G for more details.

1

The samples for 8.3 are provided as a separate install option and must be made availableby the administrator.



6/24


4 Using Framework Manager to Replay XML Act ion LogsThe action log files that Framework Manager creates can be replayed asscript files using Framework Manager. This task is accomplished byselecting the Run Script option from the Project menu in Framework

Manager.

Once you select a file to be run you should see the following screen. Thisscreen has a run button to the right side of the screen. After running thescript you should see a number of messages indicating changes that weremade or errors that were encountered when replaying the actions2. You canthen accept or reject the changes.

2

Errors may occur for several reasons. For example an action may fail if the referencedobjects are no longer accessible or security restrictions prevent access to specific objects.



7/24


5 Using BmtScr iptPlayer to Replay XML Action LogsThe action logs from Framework Manager can also be used as script filesfor a command line utility provided with IBM Cognos 8, BmtScriptPlayer.exe,rather than using the UI options in Framework manager itself.

The Script Player accepts a script file as a command line argument and willexecute the associated commands in batch. The Script Player interfaces withthe Framework Manager engine and metadata directly, allowing you tobypass the Framework Manager application. You can use action logs thathave been created either by the Framework Manager application, a customprogram or manually. It is ideally suited for automated tasks related to modelcreation and model maintenance. After reviewing the actions of your log files,you can use the command line options to run specific transactions.

Depending on the options selected for BmtScriptPlayer, you can either createa new model or open an existing one. The action log, consisting of a set oftransactions, is then analyzed and each action is executed in sequence.Actions usually change the model. Before the Script Player terminates, themodified model is saved and replaces the original model. Saving the model isthe default action but can be overridden using the command options. This isuseful if you wish to test the actions in your script without committing thechanges. The Script Player maintains an internal log of all executed actions,allowing you to back out of any changes if necessary.

This BmtScriptPlayer utility can be found at:

\bin\BmtScriptPlayer.exe

Use the following simplified syntax to run the Script Player:

BmtScriptPlayer [-c|-m] [-a ][options]

where is the name of the project and isthe name of the action log. For example,

BmtScriptPlayer -m goSales.cpf -a import.xml

The Framework Manager Developer Guidecontains additional details on howthis utility can be used to implement change to models using xml action logs.The full command syntax for BmtScriptPlayer.exe can be obtained bysupplying an invalid argument such as -? when executing BmtScriptPlayerfrom a command line.



8/24

Updating IBM Cognos 8 Models Using Code and XML 8The BmtScriptPlayer utility was written to process one file at a time. If agroup of files need to be applied to a model it is important that they beprocessed in order because actions in the log files may depend on the resultsof actions in earlier logs. When log files are created by Framework Managerthey are time stamped and this will allow for easy determination of the

appropriate script order. Action logs created by external applications may notcontain such information in the file names and care would need to be takenin such situations to process the scripts appropriately. See Appendix A for anexample of using BmtScriptPlayer to process multiple files.

6 Changing Models using Java and XML Act ion LogsYou can use the Framework Manager SDK to perform all the same metadatamodeling tasks and processes as the Framework Manager application. Forexample, you can

import a data source

enhance query subjects with SQL, expressions and filters

create model query subjects to extend value of data source querysubjects

create a basic package

publish a package to report authors

The Framework Manager SDK supports two methods of modeling metadata inaddition to the Framework Manager application: BmtScriptPlayer and theMetadata Service. Each of these methods allows you to perform metadatamodeling and create a Framework Manager package that you can thenpublish for report authors.

At the core of each of these methods is the action. An action is a request thatis sent to the Framework Manager Engine. Actions can be grouped togetherto perform certain modeling activities. Actions are recorded as elements of anXML document. These actions are the same elements that are written to theaction logs created by Framework Manager. For more information, see"Action Logs" in the Framework Manager Developer Guide.

When using a programming language to implement these actions there are

two main methods that can be used: calling BmtScriptPlayer from theexternal application or using the Framework Manager APIs directly.

6.1 Running BmtScr iptP layer f rom an externa l appl icat ion.The first technique for an external application to implement changes to amodel using XML is to invoke the BmtScriptPlayer from an externalapplication such as a Java program. This can be done using the Java classRuntime.getRuntime().exec,

Here is an example:

String locationofBMT = pfile.getProperty("BMTScriptcmdString");



9/24

Updating IBM Cognos 8 Models Using Code and XML 9String cmdString = locationofBMT+ " -m "+ modelName+ " -a "+

logFileName+ " -u " + userName + " -p " + password + " -s " +

nameSpaceID;

Process p = Runtime.getRuntime().exec(cmdString);

See Appendix A for a sample program.

6.2 Using IBM Cognos 8 APIs to apply changes to a model us ing XMLThe second technique for an external application to implement changes to amodel using XML is to invoke the IBM Cognos 8 APIs from an externalapplication. The Framework Manager API will allow the external application toact as a client to an IBM Cognos 8 server, communicating through the BI BusAPI. The client interacts with the server via Simple Object Access Protocol(SOAP) requests using the HTTP transport protocol. The Metadata Servicerunning on the IBM Cognos 8 server receives and processes the SOAPrequests from the client application and sends them to the FrameworkManager Engine. Responses from the Framework Manager Engine are fedback to the Metadata Service which encapsulates the response as a SOAPmessage and returned to the client application through the BI Bus.

The Metadata Service can query existing models for information or applyactions to modify a model. The responses for action results and queries willbe returned as an XML document.

There are two types of requests that can be made to the Metadata Service to

manipulate an unpublished model:

Send generic requests to create, open, save, and close the model.

Send action requests to modify the metadata or publish a package.

Both types of request use the Framework Manager API Request element.

There are a number of different classes to support the creation of a modelusing Java code. The most common Java class is the MetadataServiceStubused along with the updateMetadata method. When using these classes andmethods, actions are still defined in the same XML format but must bewrapped within an mdprovider XML element. Please refer to Chapter 1 of theFramework Manager Developer Guidefor details on the mdprovider elementand examples of its use.

Here is an example of a method that implements a generic request to open aproject:

private String openProject(String projectLocation) throws Exception {

String sXML = "";

XmlEncodedXML encodedXML = new XmlEncodedXML(sXML);



10/24

Updating IBM Cognos 8 Models Using Code and XML 10return getMetadataService().updateMetadata(encodedXML.toString());

}

Here is an example of a method that implements an action request to publisha project:

public void publish(String model) {

updateMetadata(getTransactionHeader(model)

+ "" + ""

+ ""

+ "package"

+ "[].[packages].[GO Data Warehouse]"

+ "" + ""

+ "2 " + ""

+ ""

+ "/content " + ""

+ ""

+ "GO Data Warehouse " + ""

+ "" + "1"

+ "" + ""

+ "1 " + ""

+ "" + "-1"

+ "" + "" + ""

+ "" + " " + ""

+ "" + getTransactionTrailer());

}

private String getTransactionHeader(String modelName) {

Date now = new Date();

DateFormat df = new SimpleDateFormat("yyyyMMddHHmmssSSS");

String nowTime = df.format(now);

String transactionSeqNbr = Integer.toString(transNbr++);

String transactionXML = ""

+ "";

return transactionXML;

}



11/24


See Appendix D for the complete sample program.

7 Java Appl ications using the Java Framework ManagerAPIThe majority of Framework Manager model building can be done with XML-encoded actions. The XML actions in the Framework Manager API can beused to add, change, or delete many objects in a model such as aQuerySubject, QueryItem, DBImport, NameSpace, Folder, MeasureDimension or Regular Dimension.

The easiest method for determining how the XML should be structured is touse the Framework Manager modeling tool create the sample syntax for you.By performing the action once in Framework Manager you can obtain the

associated XML-encoded action from the action log file. The action can thenbe brought into your code with appropriate substitutions.

For example, the Framework Manager log might contain the following actionentry for renaming a namespace:

namespace/name

/O/name[0]/O/[OriginalName]

NewName

Here is an example of a Java class that makes a modification to thenamespace. Notice a pair of String variables were created to make this classmore generic then the original XML which hard-coded the actual name of theoriginal namespace and the new name of the namespace in the XML:

public class ModifyNamespaceName extends Action {

private String oldName;



12/24

Updating IBM Cognos 8 Models Using Code and XML 12private String newName;

public ModifyNamespaceName(String oldName, String newName) {

this.oldName = oldName;

this.newName = newName;}

public String getParams() {

return "\n" +

"namespace/name\n" +

"/O/name[0]/O/[" + oldName + "]\n" +

"\n" +

"\n" +

""+ newName +"\n" +

"";

}

}

The idea is to take some very specific XML that was generated by FrameworkManager and then make it more generic so you can then pass programparameters to the methods and implement your model in this manner.Another best practice is to build a framework that can allow for code reuseand maintainability. A framework that encourages the use of patterns, goodobject oriented design practices and implementation of utility classes is

desirable so that time to develop and maintain application can be optimized.See Section 8 for an example.

Another idea for a potential framework is to use the concept of templates.This approach takes the raw XML action log generated by FrameworkManager and manipulates the XML content using java classes such as JDOMto rewrite components of the action log. For example, you could create anaction log that imports a table, renames it and then moves it to anothernamespace within the model. With this template you can manipulate theXML to import a different table, rename the resulting query subject withanother name and then move it to yet another final namespace. By using atemplate approach you can eliminate the need to duplicate actions for eachpermutation and simply make the appropriate substitutions in the action logbefore processing the actions in the file. See Section 9 for an example.

8 Put ting it al l t oge ther8 .1 Opt ion 1 XML in code

This example is the beginning of a Java framework that can be used toimplement the building of a metadata model using XML embedded in code

along with the Framework Manager API.



13/24


There are a number of Java classes that are used to implement manydifferent functions. Every customer has their own unique requirements sothis Java framework may be too much for some and not enough for others.The requirements in your environment will dictate the best approach for your

applications and this example is meant as a sample rather than a hard rule.However, this example does use some common elements such as objectoriented practices including inheritance and some of the new Java 1.5collections that are useful in creating reusable and flexible code. Someoneusing this framework should be familiar with these concepts.

Here is a brief review of the main method in the SampleApplication class:

String workingNamespace = new String("Model");

String modelPath = new String("C://NewProject1//bcdtest.cpf");

CognosConnect cognosConnect = new CognosConnect("localhost");

cognosConnect.connect();

Project project = new Project(cognosConnect, modelPath);

project.create();

project.open();

project.setLocale();

project.setName("TEST");

project.setCoreNamespace(workingNamespace, "Analysis");

workingNamespace = "Analysis";

Vector tables = new Vector();

tables.add("titleauthor");

tables.add("titles");

tables.add("authors");

project.importTables(workingNamespace, "Analysis", "pubs", "dbo",DBType.OL, tables);

project.createRelationship(workingNamespace, workingNamespace,"titleauthor", "title_id", RelationshipCardinality.ONE2ONE,workingNamespace, "titles", "title_id",

RelationshipCardinality.ONE2MANY);

project.createNamespace(workingNamespace, "Import View");

project.createNamespace(workingNamespace, "Dimensional View");

project.createNamespace(workingNamespace, "Business View");

project.createNamespace(workingNamespace, "Development View");



14/24

Updating IBM Cognos 8 Models Using Code and XML 14The above code will create a model (if it does not exist3), import from a datasource that points to the MS SQL Server pubs database4 and import thetitles, titleauthor, and authors tables. It then creates a relationshipbetween the titles and titleauthor tables based on the respective title_idcolumns. The code will do this in the Analysis namespace. It will also

create additional namespaces: Import View, Dimensional View, BusinessView, and Development View.

8.2 Option 2 XML in external f i les as templates.FileName: fmcodeintemplates.zip

This example is the beginning of a Java framework that can be used toimplement the building of a metadata model using external XML files astemplates rather then embedding XML in code. This example utilizes theJDOM classes (www.jdom.org) to parse the XML5. Listed below are someexamples of how this can be used:

createNameSpaceTest: - This method will create a new XML file that willcreate a namespace. This example utilizes an XMl template file calleddbimport_template.xml.

dbImportTest: - This method will create a new XML file that willdemonstrate how to perform a database import. This example utilizes an XMLtemplate file called importnewtable-log.xml.

deletefolderTest: - This method will create a new XML file that willdemonstrate how delete a folder. This example utilizes an XML template filecalled delete_template.xml.

Notice that in this example there is no XML embedded in code. The idea withthis version is to isolate the XML in files to be parsed with code and thenupdate the relevant entry to perform a new similar action on another object.The resulting XML files can be executed as scripts in Framework Manager,through BMTScriptPlayer or through the Framework Manager API.

9 Cri teria for se lect ing a techniqueThe two main approaches to automating model changes are theBmtScriptPlayer and the Framework Manager API. Depending on thedevelopment project, one may be better suited to the task than the other.

3 If the class is modified to point to an existing model then be aware that several of themethods are defined to use specific namespace names and these may need to be modified tolocate the appropriate elements within the existing model.4 This sample database is available from Microsoft. To use the sample code a data sourceconnection named Analysis must be configured within the Cognos 8 environment to accessthe pubs sample database.5

SAX, DOM, or any other XML processing package could be used to perform the XMLdocument manipulation. JDOM just happens to be the one chosen for this example.



15/24

Updating IBM Cognos 8 Models Using Code and XML 15Typically, BmtScriptPlayer is used to reproduce a set of changes made in oneenvironment to the same base model in another environment. The XMLaction logs produced by Framework Manager in a development environmentcan be used as-is to quickly update a model in a training or productionenvironment.

The Framework Manager API is normally used for situations when there aremany new objects or modifications that need to be implemented in a model.In such a scenario, automation would be useful in freeing modelers fromhaving to perform repetitive actions and also reduce the time required toimplement a package.

Another scenario where the Framework Manager APIs are useful is for OEMsor consulting partners. Here a single base model may exist and automationwould be used to create customized models for the individual OEM customersolutions.

So, if the project scope calls for simple playback of recorded actions withminor variations then BmtScriptPlayer is ideal for executing a series of actionsfrom a file. On the other hand, if the project calls for more detailedautomation where many objects are manipulated in complex ways then theFramework Manager API is likely the better choice as it will allow for smallercode blocks to be reused in these multiple and varied actions.



16/24


Appendix A BMTScriptPlayer ExampleFileName: BMTScriptLogProcessor.zip

This example will run the BMTScriptPlayer for all the log files in a directory.

The sample requires updates to several path locations. TheBMTScriptLogProcess.properties file contains the location of the model, actionlogs and the location of the log processor utility. The run.bat and thebuild.bat contain path references to the java compiler and the installationlocation of IBM Cognos 8. Each of these paths must be updated to reflect thelocation of the extracted sample and the installation location of your Javacompiler and your IBM Cognos 8 instance.

Once the locations have been set properly the sample can be compiled usingbuild.bat and then executed using run.bat. The BMTScriptLogProcessor canalso be called directly using java.exe with the appropriate classpath.

Sample scenarioMachine 1 is the development machine. Machine 2 is the training machinewhich does not have Framework Manager installed on it. Some newenhancements were made to a model on Machine 1 that the trainingdepartment needs on Machine 2.

Copy the log files from Machine 1 to Machine 2 and modify theBMTScriptLogProcessor.properties properties file to indicate where the logfiles are located. Execute the run.bat to apply the changes using thisexample.

Expected resultsAll the changes from the development Machine 1 are now made to the modelon Machine 2.

Note: It is still necessary to publish the model for report authors to use theupdated information. See Appendix D on how to publish the model usingautomation.

Example NoteThe example includes a sample model located at the following location:

\yourziplocation\BMTScriptLogProcessor\gosales_goretailers

Steps: Use FrameworkManager to open the provided model in locationabove. You will notice that under the DatabaseView\Go Sales thatTIME_DIMENSION and INVENTORY_LEVELS have not been imported yet.



17/24

Updating IBM Cognos 8 Models Using Code and XML 17The sample model contains a logs directory with 3 log files. These are theaction log files that contain the necessary XML to add the two tables to themodel.

Using run.bat for the first time will add these two tables to this view.

If you want to delete the two tables then delete the exiting files out of thelog directory and then copy the file deletelog.xml from the main modeldirectory to the log directory and execute the run.bat again. (Note thebackup directory contains the original log files).



18/24


Appendix B MDProviderHelper ExampleFileName: MDHelperAPIDemo.zip

This sample application demonstrates the use of the Framework ManagerAPI.

Listed below are the steps to be performed before the application can be run.

1. Modify run.bat to identify the location of your Java runtimeenvironment and your IBM Cognos 8 installation location.

2. Modify the MDProviderHelper.properties file to include your endpoint,security, and project information.

The text below is an example of the properties file:

#Cognos Settings

reportNetEndPoint=http://localhost:9300/p2pd/servlet/dispatch

authenticate=no

userName=sa

password=sa

nameSpaceID=Sample1

#Script Settings

projectLocation=C:\\MDHelperAPIDemo\\targetmodel83\\go_sales_MDHelperA

PIDemo\\go_sales_MDHelperAPIDemo.cpf

scriptLocation=C:\\MDHelperAPIDemo\\sourcemodel83\\go_sales_MDHelperAP

IDemo\\logs\\go_sales_MDHelperAPIDemocreate-log.xml

updateonly=no

The reportNetEndPoint identifies dispatcher target for the IBM Cognos 8server. It should be the same value as the External Dispatcher URI settingthat was specified in Cognos Configuration. The username, password, andnameSpaceID properties are the logon information for the IBM Cognos 8

server. The value for the namespaceID must be the value of theNamespaceID setting that was specified in Cognos Configuration. The value isnot necessarily the same as the display name of the namespace. If noauthentication provider has been configured for the IBM Cognos 8environment then set authenticate=no in the properties file. If theenvironment is secured and a logon is required then set authenticate=yes inthe properties file.

The projectLocation is the location of the Framework Manager model and thescriptLocation is the location of the action log that is to be applied to themodel.



19/24

Updating IBM Cognos 8 Models Using Code and XML 19Finally, updateonly is a property that allows you to identify whether theaction log is to be applied to an existing model or that the model should becreated before applying the actions in the log file. By setting this property toyes the script will apply the actions to an existing model. Using no willcause the script to create the model before applying the action log.

Sample scenario 1Model from Machine 1 needs to be created on Machine 2 and Machine 2 doesnot have Framework manger installed on it.

The steps to do so using the MDHelperAPIDemo would be:

1. Prepare the target environment

a. Create a directory for the new model on Machine 2.

b. Copy the action log from Machine 1 to Machine 2.c. Modify the MDHelperAPIDemo.properties file to define the

connection information, location for the new project file (fromstep a) and the location of the action log (from step b)

In this case, since a new model is to be created, setupdateonly=no in the properties file.

2. Call MDHelperAPIDemo by executing run.bat

Expected resultsThe model from Machine 1 is now on Machine 2.

Note: It is still necessary to publish the model for report authors to use theupdated information. See Appendix D on how to publish the model usingautomation.

Sample scenario 2Model changes from Machine 1 needs to be applied to an existing model onMachine 2 and Machine 2 does not have Framework manger installed on it.

The steps to perform this operation with MDHelperAPIDemo would be:

1. Prepare the target environment

a. Copy the action log for the changes from Machine 1 toMachine 2.

b. Modify the MDHelperAPIDemo.properties file to define theconnection information, location of the existing project file onMachine 2,and the location of the action log (from step a).

In this case, since the model already exists, setupdateonly=yes in the properties file.

2. Call MDHelperAPIDemo by executing run.bat

Expected results



20/24

Updating IBM Cognos 8 Models Using Code and XML 20All the changes from the development Machine 1 are now applied to themodel on Machine 2.

Note: It is still necessary to publish the model for report authors to use. SeeAppendix D on how to publish model using automation.

Notes on exampleThe tables and data source connection used in the samples were createdfrom the IBM Cognos 8.1 sample SQL Server database. Subsequent releasesof IBM Cognos 8 have updated the sample databases and the tables andschemas may be different than those available with IBM Cognos 8.1. Tomake this example work in your environment the tables from the 8.1 sampledatabase have been included with this sample application in the scriptGOSL.sql. To use this content with this sample application the ddl must beexecuted to create the tables in a SQL Server database named gosl. The

associated IBM Cognos 8 data source must be named gosales.

This example includes sample models located at the following locations:

\yourziplocation\MDHelperAPIDemo\sourcemodel

\yourziplocation\MDHelperAPIDemo\targetmodel

An empty directory structure is also present to satisfy the create optionavailable with this application at the following location:

\yourziplocation\MDHelperAPIDemo\targetnewmodel

When applying changes to the sample target model the target model must beupgraded to the current Framework Manager release that you are using. Toensure that the model is at the correct release, open the model, respond toany upgrade messages and then save the upgraded model.

Before using the sample, use Framework Manager to open the providedmodels. Notice that the target model does not have any tables imported.

There are two configuration files provided with this sample.

MDProviderHelper.properties.create.txt MDProviderHelper.properties.update.txt

Use these files for the different scenarios. The Java code looks for theMDProviderHelper.properties file. To test the update scenario then copyMDProviderHelper.properties.update.txt to MDProviderHelper.properties.Similarly, if testing the create scenario then copy theMDProviderHelper.properties.create.txt to MDProviderHelper.properties.

Modify the properties files to identify the source and target locations of the

extracted models and to identify the appropriate logon information.



21/24


After executing run.bat you should see the new tables imported into themodel (within targetmodel or targetnewmodel depending on the propertiesfile that you use).



22/24


Appendix C Retrieve a model already published inIBM Cognos 8 http://www-01.ibm.com/support/docview.wss?uid=swg21344196

Many of the examples used in this document obtain the model from the filesystem where it is was originally created by Framework Manager. Thisexample will retrieve a package from Cognos 8 and create an instance of theModel class to be used to implement changes.

The input for this program is the package name.

Expected results: Program now has an instance of the Model class to beused to implement changes.

Appendix D How to publish a model. http://www-01.ibm.com/support/docview.wss?uid=swg21335762

This sample application demonstrates how to use the IBM Cognos 8Framework Manager API to publish a package. It assumes that the packagehas already been created within the model.

Sample scenario Some changes have already been made to a model (usingtechniques from Appendix A or B) and report authors need the new changes.

Expected results: After running the program the package specified shouldbe available to report authors.

Appendix E The Framework Manager APIupdateMetadata methodThe most used class for the Framework Manager API is theMetadataServiceStub class. The most used method of this class is the

updateMetadata method. Here is the signature.

public XmlEncodedXML updateMetadata(XmlEncodedXML request)

throws java.rmi.RemoteException

Specified by:

updateMetadata in interface MetadataService_Port

Throws:

java.rmi.RemoteException

As indicated above, the method takes in a XmlEncodedXML class. Here aresome examples of how it can be used:

http://www-01.ibm.com/support/docview.wss?uid=swg21344196http://www-01.ibm.com/support/docview.wss?uid=swg21335762http://www-01.ibm.com/support/docview.wss?uid=swg21344196http://www-01.ibm.com/support/docview.wss?uid=swg21335762


23/24


Sample XML within the updateMetadata method for opening an existingproject:

private String openProject(String projectLocation) throws Exception {

return getMetadataService()

.updateMetadata(new XmlEncodedXML("")).toString();

}

Sample XML within the updateMetadata method for saving an existingproject:

private String saveProject(String projectLocation) throws Exception {return getMetadataService()

.updateMetadata(new XmlEncodedXML("")).toString();

}

For an example of this method and for more details please refer toMDProviderHelper in Appendix B.

Appendix G Datasource Connection relatedexamplesA. Update a connect ion string

This example can be used to modify an existing connection string of a datasource registered in IBM Cognos 8.

http://www.ibm.com/search/csass/search?q=getmodel&sn=spe&filter=language%3Aen+collection%3Astgsysx%2Cdblue%2Cic%2Cpubs%2Cdevrel1&prod=U487531B48832U38#q%253dsdk%2520create%2520datasource%2526filter%253d%252blanguage%253aen%2520%252bcollection%253astgsysx%252cdblue%252cic

%252cpubs%252cdevrel1%2526prod%253dU487531B48832U38%2526sn%253dspe%2526sortby%253d%2526o%253d0

Do a search on sdk create datasource

Sample scenarioA custom application needs to change the connection string to switchbetween development and production. This is most applicable to a testenvironment where testing routines are comparing results from limiteddevelopment data to results from the full production data.

http://www.ibm.com/search/csass/search?q=getmodel&sn=spe&filter=language%3Aen+collection%3Astgsysx%2Cdblue%2Cic%2Cpubs%2Cdevrel1&prod=U487531B48832U38#q%253dsdk%2520create%2520datasource%2526filter%253d%252blanguage%253aen%2520%252bcollection%253astgsysx%252cdblue%252cic%252cpubs%252cdevrel1%2526prod%253dU487531B48832U38%2526sn%253dspe%2526sortby%253d%2526o%253d0http://www.ibm.com/search/csass/search?q=getmodel&sn=spe&filter=language%3Aen+collection%3Astgsysx%2Cdblue%2Cic%2Cpubs%2Cdevrel1&prod=U487531B48832U38#q%253dsdk%2520create%2520datasource%2526filter%253d%252blanguage%253aen%2520%252bcollection%253astgsysx%252cdblue%252cic%252cpubs%252cdevrel1%2526prod%253dU487531B48832U38%2526sn%253dspe%2526sortby%253d%2526o%253d0http://www.ibm.com/search/csass/search?q=getmodel&sn=spe&filter=language%3Aen+collection%3Astgsysx%2Cdblue%2Cic%2Cpubs%2Cdevrel1&prod=U487531B48832U38#q%253dsdk%2520create%2520datasource%2526filter%253d%252blanguage%253aen%2520%252bcollection%253astgsysx%252cdblue%252cic%252cpubs%252cdevrel1%2526prod%253dU487531B48832U38%2526sn%253dspe%2526sortby%253d%2526o%253d0http://www.ibm.com/search/csass/search?q=getmodel&sn=spe&filter=language%3Aen+collection%3Astgsysx%2Cdblue%2Cic%2Cpubs%2Cdevrel1&prod=U487531B48832U38#q%253dsdk%2520create%2520datasource%2526filter%253d%252blanguage%253aen%2520%252bcollection%253astgsysx%252cdblue%252cic%252cpubs%252cdevrel1%2526prod%253dU487531B48832U38%2526sn%253dspe%2526sortby%253d%2526o%253d0http://www.ibm.com/search/csass/search?q=getmodel&sn=spe&filter=language%3Aen+collection%3Astgsysx%2Cdblue%2Cic%2Cpubs%2Cdevrel1&prod=U487531B48832U38#q%253dsdk%2520create%2520datasource%2526filter%253d%252blanguage%253aen%2520%252bcollection%253astgsysx%252cdblue%252cic%252cpubs%252cdevrel1%2526prod%253dU487531B48832U38%2526sn%253dspe%2526sortby%253d%2526o%253d0http://www.ibm.com/search/csass/search?q=getmodel&sn=spe&filter=language%3Aen+collection%3Astgsysx%2Cdblue%2Cic%2Cpubs%2Cdevrel1&prod=U487531B48832U38#q%253dsdk%2520create%2520datasource%2526filter%253d%252blanguage%253aen%2520%252bcollection%253astgsysx%252cdblue%252cic%252cpubs%252cdevrel1%2526prod%253dU487531B48832U38%2526sn%253dspe%2526sortby%253d%2526o%253d0http://www.ibm.com/search/csass/search?q=getmodel&sn=spe&filter=language%3Aen+collection%3Astgsysx%2Cdblue%2Cic%2Cpubs%2Cdevrel1&prod=U487531B48832U38#q%253dsdk%2520create%2520datasource%2526filter%253d%252blanguage%253aen%2520%252bcollection%253astgsysx%252cdblue%252cic%252cpubs%252cdevrel1%2526prod%253dU487531B48832U38%2526sn%253dspe%2526sortby%253d%2526o%253d0http://www.ibm.com/search/csass/search?q=getmodel&sn=spe&filter=language%3Aen+collection%3Astgsysx%2Cdblue%2Cic%2Cpubs%2Cdevrel1&prod=U487531B48832U38#q%253dsdk%2520create%2520datasource%2526filter%253d%252blanguage%253aen%2520%252bcollection%253astgsysx%252cdblue%252cic%252cpubs%252cdevrel1%2526prod%253dU487531B48832U38%2526sn%253dspe%2526sortby%253d%2526o%253d0http://www.ibm.com/search/csass/search?q=getmodel&sn=spe&filter=language%3Aen+collection%3Astgsysx%2Cdblue%2Cic%2Cpubs%2Cdevrel1&prod=U487531B48832U38#q%253dsdk%2520create%2520datasource%2526filter%253d%252blanguage%253aen%2520%252bcollection%253astgsysx%252cdblue%252cic%252cpubs%252cdevrel1%2526prod%253dU487531B48832U38%2526sn%253dspe%2526sortby%253d%2526o%253d0http://www.ibm.com/search/csass/search?q=getmodel&sn=spe&filter=language%3Aen+collection%3Astgsysx%2Cdblue%2Cic%2Cpubs%2Cdevrel1&prod=U487531B48832U38#q%253dsdk%2520create%2520datasource%2526filter%253d%252blanguage%253aen%2520%252bcollection%253astgsysx%252cdblue%252cic%252cpubs%252cdevrel1%2526prod%253dU487531B48832U38%2526sn%253dspe%2526sortby%253d%2526o%253d0


24/24

Updating IBM Cognos 8 Models Using Code and XML 24Expected resultsThe connection string is updated to reflect the parameters defined whencalling the Java application.

Note that for migration of packages from one environment to another itwould be more appropriate to create the deployment export package withoutincluding data source definitions. After importing the package into a newenvironment the content will use the same data source name reporting butwill use the connection information that has been defined in the newenvironment. Different connection definitions can be present in the differentenvironments as long as the data source names are the same.

B. Create or Update a Datasource and Connection.This example can be used to either create a new datasource or update theproperties of an existing data source and connection.

Sample scenarioA custom application needs to create a new datasource and datasourceconnection. This would be most useful when creating many new data sourcesor to automate application development for serviced environments.

Expected resultsThis example will create a datasource and a datasource connection in IBMCognos 8.

C. Sett ing a connection str ing at runt imeThis example will demonstrate how to set a connection used by a report atruntime.

Sample scenarioA custom application needs to run a report with a specific connection string.

Expected results: This will example will run the sample report Add Colorwith a specific connection string.

Appendix H Documentation on error codes.http://www-01.ibm.com/support/docview.wss?uid=swg21428247&myns=swgimgmt&mynp=OCSS9RTN&mync=R

The action log XML description information was moved out of the SDK docs and into anmdActions.xsd file in the FM install at:

\templates\bmt\FMSDK
http://www-01.ibm.com/support/docview.wss?uid=swg21428247&myns=swgimgmt&mynp=OCSS9RTN&mync=Rhttp://www-01.ibm.com/support/docview.wss?uid=swg21428247&myns=swgimgmt&mynp=OCSS9RTN&mync=Rhttp://www-01.ibm.com/support/docview.wss?uid=swg21428247&myns=swgimgmt&mynp=OCSS9RTN&mync=Rhttp://www-01.ibm.com/support/docview.wss?uid=swg21428247&myns=swgimgmt&mynp=OCSS9RTN&mync=R

Date post:	02-Apr-2018
Category:	Documents
Upload:	nagendra-kumar
View:	230 times
Download:	0 times

Updating IBM Cognos 8 Models Using Code and XML (1)

Documents