Getting started with the MetaManager™ API


This tutorial was designed to expose the basic concepts and intents of the MetaManager™
API and the Script Runner module. The Script Runner Example docking window contains
two sections of scripts. The Tutorial sections demonstrated basic concepts of the
API with executable code. Each of these scripts can be executed in a test IBM Cognos
Environment. The Snippets section contains demonstrations on common use cases that
have been solved with the API. In addition to these self-service resources Tech Data
BSP Support is always available for help with direction as to how to solve your
specific problem with the MetaManager™ Automation API.


Getting Started

The MetaManager™ Scripting API is designed to provide simplified access to functionality
required to automate common tasks in an IBM Cognos Environment.

For example, many common BI tasks such as setting security, creating objects, setting
prompts and testing datasources can be performed in a simplified manner

often using only a single line of code. In addition the API covers many common non-Cognos
BI tasks that play a role in automation, such as: Sending emails,

accessing a database, writing to the filesystem and interacting with Microsoft Excel
files. To use the MetaManager™ Script Runner module you need to have

a Script Runner license.

In addition to the features available in the JavaScript programming language, 3
additional global objects have been made available in the scripting language:

  • api
  • console
  • helpers

“api” is the starting class for all functionality that interacts with an IBM Cognos
Environment. Most scripts will start by logging onto an IBM Cognos Environment

by creating a server and logging on in this manner:

var url = “http://localhost/ibmcognos/cgi-bin/cognos.cgi”;

var server = api.createServer(url);

server.logon(“AD”, “Ari”, “G0ld”);

The object model tree on the right hand side of the script has been optimized to
reveal information about features that are available as you drill down further

into the API. In addition each of the items in the tree includes documentation in
the bottom pane and an example that can be dragged to the script editor.

Start by dragging the api > createServer method to the editor then on a new line
drag the server > logon(…) method.

Now that we have a connection to the IBM Cognos Server we can begin to perform actions.
First we can create a folder. Drag the createFolder() method to

the editor and you will see that placeholders have been dropped for this method’s
two arguments: location & name. The documentation in the bottom pane

further indicates that location is a searchPath. A searchPath is a descriptive identifier
that selects 1 or more objects from the content store.

See the “Using IBM Cognos SearchPath” document in the documentation directory for
more information. In this case we want the searchPath of the parent folder

to create the new folder in. This is easily accessible by navigating to the object
in the MetaManager Portal Tree, right clicking on the desired object and

choosing Copy SearchPath. The following line of code creates a new folder names
“My New Folder” beneath the public folders.

var cmobject = server.createFolder( “/content”, “My New Folder”);

The Object Model tree indicates that the createFolder method returns a CMObject.
By expanding the method in the Object Model tree you can see the

actions and information that you now have available on this object. A CMObject represents
any object that can be accessed in the Content Store.

Common information across all objects is readily available directly on the object,
such as:



cmobject.ownerIn addition common tasks are available such as:



cmobject.createShortcut(location, name);

Information and actions that are specific to an object type have been grouped beneath
the “Fns” collections. For example, if the cmobject is an account then

cmobject.accountFns is available and the script can access account specific information
such as usernames and email, or account specific actions such as

creating a profile.; cmobject.accountFns.createProfile()

If the cmboject is a report type then the reportFns collection is available and
the script can access information such as the common report setting and the specification.
Additional actions such as: creating a Report View, validating the report and running
the report are also now available.

cmobject.reportFns.defaultPortalAction = “RUN”;var result = cmobject.reportFns.validate();






Some of the “Fns” groups are available for many object types, for example the securityFns
group is available for any cmobject and can be used to modify an objects security
policies. The scheduleFns is available for any object that can have a schedule such
as a report or a job. The promptingFns is available for any object that can store
saved parameters such as a report, view, schedule or a job step.

Most scripts need to perform an action on a specific object or objects that already
exist in the content store. The getCMObject and getCMObjects methods from the api
class are typically the starting point of a script. These 2 methods take in a searchPath
that identifies a single object (getCMObject) or many objects (getCMObjects). For
the getCMObjects it’s common that the result set will be looped on. Dragging this
method to the editor will create a loop for you. The following script searches for
all packages in the content store and writes the name of the package to the console.

var cmobjects = server.getCMObjects(“//package”);

for( var i = 0; i < cmobjects.length; i++ )


var cmobject = cmobjects[i];



The console is a key tool in writing effective scripts that report progress and
diagnostic information. When running interactively any data written to the console
is displayed in the console pane below the editor. Typically data is written using
console.log(), however additional methods such as warn(), debug() & error() are
available to help highlight or separate exceptional information. All data written
to the console is saved in memory so that at the end of the script the console can
easily be saved to file or emailed to a recipient. This is useful when the script
is running in unattended (command line) mode. The following example writes some
information to the console and then saves it and emails it.

console.log(“Testing report”);



console.log(“Report is good”);



console.error(“Report is bad”);



var body = helpers.log.getLogData();, from, to, subject, body);


The helpers class contains collections of functionality for accessing external systems,
such as the file system, databases, email and user input. A common integration point
for the API is to read information from a Microsoft Excel file and perform an action
for each row. The API makes this easy by reading native Microsoft Excel sheets and
returning the results as an array or rows, each row contains an array of cells.
This example reads in an excel file where the first column is the searchPath of
an object and the second column is a description that we want to set as the description
field for that object in the content store.

var rows = helpers.file.readExcelFile(“c:\objects.xlsx”, “Sheet1”);

for (var r = 0; r < rows.length; r++)


var searchPath = rows[r][0];

var description = rows[r][1];

var cmobject = server.getCMObject(searchPath);

cmobject.description = description;


The Dialogs grouping contains user interface prompts that can be used to ask the
interactive user questions. A common example of this would be to prompt the user
for their password so that it doesn’t need to be embedded in plain text in the script.
The Dialogs class cannot be used when the script is used in unattended mode (e.g.
Command Line).

var password = helpers.dialogs.promptMasked(“Please enter your password”,
“Password Entry”);

server.logon(“AD”, “Ari”, password);
var confirmed = helpers.dialogs.confirm(“Do you want to continue?”);



console.log(“The user clicked OK”);




console.log(“The user clicked Cancel”);



Accessing a database to retrieve or update information can be challenging to automate.
The MetaManager™ API simplifies this process by exposing advanced .NET concepts through
the simple JavaScript Editor. Similar to the readExcelFile function previously demonstrated
the readSqlServerTable and readOracleTable functions can be used to execute a SQL
query and return the results as an array of rows, where each row is an array of
cells. In addition the api covers writing to tables and executing non-result set
queries (e.g. DELETE).

// Setup database parameters

var server = “localhost”;

var databaseName = “databaseName”;

var userName = “cognos”;

var password = “cognos”;

var sql = “SELECT * FROM Table”;

var rows = helpers.database.readSqlServerTable(server, database, username, password,

for( var i = 0; i < rows.length; i++ )


var row = array[i];

var searchPath = row[0];

var description = row[1];

var cmobject = server.getCMObject(searchPath);

cmobject.description = description;