jcognos

Library that encapsulates the (undocumented) IBM Cognos Analytics REST API.

You can use this to write tests, external clients or build tools for your Cognos environment. As the Cognos API is not official, things might break (badly) after Cognos upgrades.

Getting Started

npm install jcognos

Once the jcognos has been installed, you can include it in your projects as a CommonJS module

require("jcognos");

or as an ES2016 module

import getCognos from "jcognos";

Then get going like:

jcognos
  .getCognos("https://cognos.example.com/ibmcognos/", true)
  .then(function(lcognos) {
    lcognos.login("username", "password"); // Which also returns a promise
  });

If you want to run this module in your browser, this version does not support XSRF headers. It is (temporarily) broken. To use the module against Cognos Analytics 11.0.7 or later, follow these steps:

1. Open the Windows Services window and stop the IBM Cognos service.

2. Open the file installation_location\wlp\usr\servers\cognosserver\bootstrap.properties.

3. Add the following line:

   disableXSRFCheck=true

4. Save the file.

5. Restart the IBM Cognos service

You do not need to do this if you use jcognos in nodejs or in cordova.

Usage

Table of Contents

• Cognos
  • Parameters
  • capabilities
  • preferences
  • defaultNamespace
  • namespaces
  • login
    • Parameters
  • logoff
  • reset
  • getCurrentThemeSettings
  • getCognosVersion
  • setConfig
    • Parameters
  • getConfig
  • getConfigKey
    • Parameters
  • _getPublicFolderId
  • listRootFolder
  • listPublicFolders
  • listFolderById
    • Parameters
  • getFolderDetails
    • Parameters
  • addFolder
    • Parameters
  • deleteFolder
    • Parameters
  • uploadExtension
    • Parameters
  • loggedin
• getCognos
  • Parameters
• NameSpace
  • Properties
• CognosObject
  • Properties
• cRequest
• isStandardBrowserEnv
• isNode

Cognos

Class that helps you connect with your inner Cognos. You can not create this class directly, use getCognos to retrieve the Cognos instance.

Parameters

• debug
• timeout
• ignoreInvalidCertificates

capabilities

capabilities - returns the Cognos User Capabilities object

Returns Object Object with Capabilities

preferences

preferences - returns the Cognos User Preferences, eg. timezone, skin, accessibiltity settings etc.

Returns Object Object with Preferences

defaultNamespace

defaultNamespace - returns the default namespace that jCognos will login to

Returns String id of the default namespace

namespaces

namespaces - returns a list of possible namespaces, also when there is only 1

Returns Array<NameSpace> An array of objects describing the namespaces

login

login - Logs into Cognos.

Parameters

• user String Cognos username
• password String Password
• namespace String Namespace (optional, default CognosDefaultnamespaceorthenamespacethatistheonlynamespace)

Returns Promise returns a promise.

logoff

logoff - Logs off from Cognos.

Returns Promise returns a promise.

reset

reset - Create a new connection

Returns Promise When resolved we are logged in

getCurrentThemeSettings

getCurrentThemeSettings - Fetches current theme settings

Returns Promise The promise resolves to an object that holds the spec.json of the current theme. It has attributes such as brandTextSmall etc.

getCognosVersion

getCognosVersion - Fetches Cognos Product Version

Returns Promise The promise resolves to a string that holds the version number

setConfig

setConfig - Sets Configuration Key

Parameters

• inkey
• value String Value of the key
• key String Name of the key

Returns Promise The promise resolves to a string that holds the key value

getConfig

getConfig - Fetches Configuration Keys

Returns Promise The promise resolves to a string that holds the full config

getConfigKey

getConfigKey - Fetches Configuration Keys

Parameters

• key

Returns Promise The promise resolves to a string that holds the key value

_getPublicFolderId

_getPublicFolderId - Internal function to retrieve the ObjectId of the public folders

Returns Promise Promise that results in an id as {String}.

listRootFolder

listRootFolder - Returns the Public Folders and the My Content

Returns Array<CognosObject> Array of CognosObjects

listPublicFolders

listPublicFolders - List content of the Public Folders

Returns Array<CognosObject> List of sub-folders

listFolderById

listFolderById - Lists the folder content by id

Parameters

• id String Cognos Object id of the folder
• pattern String = '' Pattern like you would use when listing folders in your filesystem. eg. 'Sales' (optional, default '*')
• types Array = '['folder']' Types of Cognos objects to list. defaults to folders only. Other values could be 'report' (optional, default ['folder'])

Returns Array<CognosObject> List of sub-folders

getFolderDetails

getFolderDetails - Gets the raw Cognos details of a folder

Parameters

• id String objectId

Returns Object Full object as returned by Cognos

addFolder

addFolder - Creates a new folder

Parameters

• parentid String Id of the parent folder of the new folder.
• name String The name of the new folder

Returns CognosObject The newly created folder

deleteFolder

deleteFolder - Deletes a folder, its content and subfolders

Parameters

• id String Id of the folder to be deleted
• force type = true Not sure, actually (optional, default true)
• recursive type = true Will probably fail if folder contains children and set to false (optional, default true)

Returns Boolean Returns true upon success

uploadExtension

uploadExtension - Uploads zipfile containing Cognos Extension or visualisation. Only supports updating an existing module. This function is only supported by Node.js. In the browser this function returns false;

Parameters

• filename String Path to the .zip file
• name String name of the module (as found in the spec.json), for visualisations: id of the visualisation (as found in the package.json > meta > id)
• type String type of upload. Default is 'extensions', for themes use 'themes' for visualisations 'visualisation'. (optional, default 'extensions')

Returns Promise Promise that resolves to a string.

loggedin

Check to see of user is loggedin or not

Type: Boolean

getCognos

getCognos - Static function to get the Cognos Object. You can have only 1 Cognos object in your application at any time.

Parameters

• url String The URL of your Cognos installation. If empty, this function becomes static and a Promise for the current jCognos object is returned. (optional, default false)
• debug Boolean If true, starts debugging into the console (optional, default false)
• timeout (optional, default 60000)
• ignoreInvalidCertificates (optional, default false)
• Timeout Number value for http(s) connections. In milliseconds. Default is 60000.
• ignoreinvalidcertificates Boolean Should invalid certificates over ssl be ignored. Default = false

Returns Promise a promise that will return the jCognos object

NameSpace

Type: Object

Properties

• id String The id of the namespace
• value String Displayname of the NameSpace
• isDefault Boolean Set to true if this is the default namespace

CognosObject

Type: Object

Properties

• id String Cognos Object Id
• name String Name of object.

cRequest

Local Variable that holds the single CognosRequest instance

isStandardBrowserEnv

Determine if we're running in a standard browser environment returns {boolean}

isNode

Determine if we're running in node returns {boolean}