Script Runner - API

Script Runner

Script runner is an API that allows that ability to unlock the power of MetaManager^TM by writing custom scripts that can run in a bulk fashion. We have created our own classes and methods that perform functions within Cognos through our MetaManager^TM API.

Object Model

The Object Model section of Script Runner is an interactive tree form of all the classes, methods, and properties. 
All of these can be dragged and dropped into the script area and then edited to suite your need.
When an object is selected, directly below in the Command Help area, documentation and descriptions of that object are visible.

Command Help

Common help describes the parameters and gives example of the objects that are selected in the Object Model tree.
You can also select, in the top right corner of the Common Help, to open our API documentation that is more in-depth documentation on all of our API functionalities.

Messages

The messages tab gives you information on any compilation errors. If a script is written and it fails to compile you will get the details in this tab. It will display the line of code, column and description that should help decipher where to make changes to the query in order for it to compile properly.

Output

The output tab will indicate execution start time, finish time, and any errors that occur. The user can also execute the console.log() method to output information to this console. Console output can be a valuable tool for diagnosing problems and troubleshooting. The output can be displayed as either a text or a list view and it can be saved as a text file.

Examples

Examples are created for enabling the customer to drag and drop general common tasks that are repeatable business cases. They consist of runnable segments of code that provides a degree of flexibility to the user.

Tool Bar

The Script Runner tool bar buttons are slightly different than the rest of the MetaManager^TM Modules. The Open button will search for saved .js files and the Save button will save as a .js file, unlike the other modules where these buttons are used to open and save .mmx files.

Command Line for Script Runner

MetaManager^TM Scripts can be run in command line mode by passing the script (.js) file to MetaManager^TM on the command line.
The .bat file must specify to open the script runner executable instead of the MetaManager Control Panel .exe
It should be located here: C:\Program Files\BSP\MetaManager\ScriptRunner.exe 

Getting Started

The MetaManager^TM 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^TM 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^TM Portal Tree, right clicking on the desired object and choosing Copy SearchPath. The following line of code creates a new folder name “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.ancestors

• cmobject.modificationTime

• cmobject.owner

In addition, common tasks are available such as:

• cmobject.copyTo(location);

• cmobject.deleteObject();

• 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.email;

• 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();
if(!result.successful)
{
     console.log(result.errorText);
}

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];
     console.log(cmobject.name);
}

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");
if(result.successful)
{
     console.log("Report is good");
}else
{
     console.error("Report is bad");
     console.error(result.errorText);
}
console.saveLogData("c:\\log.txt");

var body = helpers.log.getLogData();
helpers.email.sendEmail(smtpHost, 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?"); if(confirmed) {      console.log("The user clicked OK"); } else {      console.log("The user clicked Cancel"); }

Accessing a database to retrieve or update information can be challenging to automate. The MetaManager^TM 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, sql);
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;
}

Next Steps

This tutorial was designed to expose the basic concepts and intents of the MetaManager^TM 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 BSP Support is always available for help with direction as to how to solve your specific problem with the MetaManager^TM Automation API.

Server API

The MetaManager^TM API is licensed and can be used in two forms. First is the Script Runner module which utilizes a JavaScript interface to access and interact with MetaManager^TM API Objects. To use the script runner module you must have a Script Runner license. The second form is as a .NET dependency which is typically used from an ASPX web page. This is designed to help customers integrate extended functionality into the IBM Cognos User Interface. For example using common techniques a user can add a button to the IBM Cognos Connection Toolbar, which when clicked will redirect a logged on user in a secure fashion (utilizing the IBM Cognos Bridge.xts technique) to an ASPX page to perform custom functionality. This ASPX web page can be textual (non-compiled) and utilize the MetaManager^TM API objects to interact with the IBM Cognos Content store logged on as the current user.