Configuration

MetaManager™ Configuration Options

MetaManager^TM works in conjunction with your existing IBM Cognos configuration with respect to authentication and authorization. It communicates with your IBM Cognos environment via the IBM Cognos Application Programming Interface (API). Because of this architecture, there is very little configuration required for MetaManager^TM to work in any environment.

NOTE: MetaManager^TM was not created using the IBM Cognos Software Development Kit (SDK), but rather directly from the Application Programming Interface (API). MetaManager^TM customers are therefore not required to own the IBM Cognos SDK, however for those that do own the SDK, there will be no contention between SDK applications and MetaManager^TM. Some of the configuration options are required while others are not.
Required options that must be set before the product can be found in the following tabs of the options.

• General

• Framework Manager

• Connections

NOTE: Keep in mind that all options set within MetaManager^TM are tied to the machine and active logon on that machine. In the event that MetaManager^TM is installed on a shared server, each logon to that server will have their own configuration options set, and these options will not be shared by any other user on that machine (unless they are set in the same manner).

General Options

When you need to establish or modify the application's general options, you must:

1. From the Tools menu, select Options.

2. Select the General tab.

General

Within the General section of the General tab, users have the option of specifying a 3rd party file comparison program as well as a MetaManager^TM Master Password. While establishing a Master Password is optional, specifying a 3rd party file comparison program is important in several of the application modules.

Setting a MetaManager^TM Master Password

Unlike in previous versions of MetaManager^TM, version 3.0 and forward by default uses a machine hash to protect the user’s connection credentials if no Master Password is set. Therefore, a Master Password is no longer required. However, for added security a user can specify a Master Password, and if specified, when MetaManager^TM loads the user will be prompted for the Master Password.

NOTE: If the MetaManager^TM settings file is copied to another machine, the machine hash will be different and the various connection credentials will not be able to be read. Any connection credentials stored by the application will be cleared upon launching the application. If another user has access to the machine running MetaManager^TM, they will have the ability to use MetaManager^TM with the user’s stored connection credentials if no Master Password is set, however they will not be able to read the user’s stored passwords.

Specify a 3rd Party File Comparison Program

The "updater" modules of MetaManager^TM (i.e. Find / Replace, Screen Tip Generator, Report Validator, Template Blaster) allow for the comparison of xml specifications from various content to be modified within your IBM Cognos environment. In order to properly compare two specification files, users need to specify which 3rd party file comparison program they wish to use. Some of the common programs used for this purpose are WinDiff, WinMerge, Beyond Compare and Ultra Compare. Note that BSP Software does not endorse any of these products over any other. WinDiff can be found for free in the Options Packs for most Windows OS versions, and both this and WinMerge can be downloaded for free on the internet, while Beyond Compare and Ultra Compare are commercial applications.

NOTE: Many of the commercial applications allow users to modify the files being compared, and MetaManager^TM supports this technique. While in the "diff" mode within MetaManager^TM, users can modify the XML specifications directly within the applicable 3rd party file comparison program and the changes will be applied directly within MetaManager^TM upon updating the object.

User Preferences

You can choose to search the whole Content Store or just Public Folders by default. This can be modified in the search window while performing the search, but this will set the default. If you choose to append a timestamp, when the process is run from a command line a timestamp will be added to the name to prevent naming conflicts and to help manage the output files when multiple copies are saved.

If the names of objects in your Content Store contain Unicode characters, and they show up as strange characters or squares, then select this option. Checking this option will change all of the controls that contain Content Store items to use a font that is capable of displaying those items correctly.

NOTE: Unicode characters are always documented correctly; selecting the Unicode option will affect the user interface only

Environment

Here you can specify the different versions of BMTScriptPlayer needed in your environment. MetaManager^TM uses BMTScriptPlayer to make changes to Framework Manager Models in Meta Editor.

Enable Transaction Manager – ability to enable and disable Transaction Manager.
Limit logs – ability to select the number of days to keep transaction logs.
Specify the location… – allows the user to specify the location to save all transaction logs.

Transaction Manager

MetaManager^TM records a transaction entry for each change that is made to the IBM Cognos Content Store. These transactions can later be used for reverting bulk changes. Currently Transaction Manager is only supported in specific modules. Please refer to the User Guide for a list of supported Modules. This section will allow you to enable Transaction Manager, set a limit to the number of days it will keep them before they are deleted, and specify the location to save the logs.

Logging

If you are experiencing any issues while using MetaManager^TM, the detailed debug logging section should be used to help capture the root cause of the issue so that they may be reported to and resolved by BSP Software support. Enabling this option will log every MetaManager^TM transaction for debugging purposes, and therefore, by default, this box should NOT be selected. Once the issue has been captured to the log, this box should once again be unselected to prevent MetaManager^TM from continuing to detail log product usage, resulting in potentially very large log files.

Delete Temporary Log Files - If you wish to delete the log files created from previous sessions of MetaManager^TM, simply click this link and the log files contained within the default MetaManager^TM logs directory will be purged.
Save Session Log - If you encounter a problem while using MetaManager^TM, you do not have to search for the appropriate log file manually. With this link, MetaManager^TM will zip up the log files from the active session and allow you to email the .zip file directly to BSP Software support.

NOTE: MetaManager^TM log files are only created if the detailed debug logging is enabled.
NOTE: Log files are produced in a logs folder within the current user’s application data directory. “Enable detailed debug logging” produces a logs folder that contains a sub folder for the session which will contain not only a log file, but trace files as well.

User Preferences

Default Search Location

In the User Preferences section, you can choose to search the whole Content Store or just Public Folders by default. This can be modified in the search window while performing the search but this will set the default.

MetaManager^TM Generated Files

If you choose to append a timestamp, when the process is run from a command line a timestamp will be added to the name to prevent naming conflicts and to help manage the output files when multiple copies are saved.

If the names of objects in your Content Store contain Unicode characters, and they show up as strange characters or squares, then select this option. Checking this option will change all of the controls that contain Content Store items to use a font that is capable of displaying those items correctly.

Note: Unicode characters are always documented correctly; selecting the Unicode option will affect the user interface only.

Performance Options

When you need to establish or modify the application’s performance options you must:

1. From the Tools menu, select options.

2. Select the Performance tab.

Performance

These performance settings are used to control how data is handled during conversations with the gateway. To limit the impact on the server or workstation running MetaManager^TM, you can set the various MetaManager^TM application performance options.

NOTE: The performance options set within MetaManager^TM are not directly related to your IBM Cognos server performance. They are options set and used by MetaManager^TM on the machine running MetaManager^TM

Communication Threads

When modules perform their work, concurrent threads can often be used to process multiple actions at the same time. While increasing the thread count can speed up MetaManager^TM, it also puts more of a load on the machine running MetaManager^TM and the IBM Cognos server. Therefore, we recommend four (4) threads as the default setting. Trial and error can be used to determine if there is a more effective thread count to use in your environment.

MetaManager^TM Timeout

This setting represents the amount of time in seconds that an HTTP request will stay open before closing due to inactivity. The recommended setting is 300 seconds (5 minutes). Trial and error can be used to determine if there is a more effective timeout value to use in your environment.

NOTE: Certain modules require more time to gather the requests necessary to complete (i.e. Content Store Documenter). The module requiring the most amount of time to gather information needed (thus requiring the HTTP request to remain open) is the one that should be used when considering modifying this setting.

Portal Tree Objects Default Display Count

For scalability and performance, the MetaManager^TM portal tree and search trees can be configured to retrieve and display a specified number of objects at a time. If there are more objects in any given lineage to be displayed, a “More…” node will be shown at the bottom of the list. The user can select “More…” to retrieve the next batch of results.

MetaManager^TM should never lock up while loading even very large lists of objects. As large lists are often difficult to browse in a meaningful way, MetaManager^TM can be configured to load a reasonable sampling from the list.

The default setting is to display 25 objects at a time. Each MetaManager^TM user can change this number based on their preference.

NOTE: The powerful search capability in each module enables users to easily find the content they are looking for and can be very beneficial in instances where a large volume of content exists.

Maximum Content Query Objects

While the MetaManager^TM portal tree and search tree use the More... limit for scalability and performance, the grid area of a module must use the maximum query objects limit. When a module processes a list of objects, all of the objects must be loaded. If a request is made to the server to load a list of objects, and producing that list exceeds the server or client timeouts, then the request will fail. Instead of requesting the entire list, MetaManager^TM breaks up the request into smaller chunks.

For example, if 10,000 objects exist in any given request, all 10,000 will eventually be loaded into MetaManager^TM if desired. However, MetaManager^TM may have made 100 calls to the server to produce the list.

The recommended setting is 300. A higher batch count will:

•         Produce fewer calls to the server.

•         Increase MetaManager^TM performance.

•         Increase the risk of a timeout.

•         Decrease MetaManager^TM’s responsiveness (i.e. to a cancel request).

Trial and error can be used to determine if there is a more effective maximum content query value to use in your environment.

Allowing the user of temp files to conserver memory

Running certain processes on a large number of items can consume large amounts of memory on the client. Allowing the use of temp files to conserve memory allows MetaManager^TM to write some of that information to disk to save memory. The files on disk are cleaned up automatically when the application is closed.

NOTE: Selecting the option to use temporary files will reduce the memory footprint but will also add substantial overhead to the process; this can cause a process to take much longer. Depending on resources, disk speed and file size some processes could potentially take several times longer than without it.

Enable GZIP

This option is selected by default and enables GZIP for compression of HTML and JavaScript files so they can be sent over the network quicker.

Monitoring

It is necessary to install and configure a background monitoring service in order to utilize the MetaManager^TM Performance Monitoring tools.  MetaManager^TM must be run as administrator to install and configure the service.

To install the service,

1. Select “Install Service”

2. MetaManager will auto populate the required fields.

   

3. The default options are set to Enable Web Server with port 3333, but you may select another Web Server Port as needed.

4. Log files, as a default, are set to be deleted after 30 days, so as not to create significantly large files. 

5. Click “Start” to begin the monitoring service.

Proxy & SMTP Options

When you need to establish or modify the application's Framework Manager options, you must:

1. From the Tools menu, select Options.

2. Select the Proxy & SMTP tab.

Proxy Settings

If your environment requires a Proxy Server in order to get through to your IBM Cognos Connection portal, you will need to establish the Proxy information here. See your company's network administrator if applicable for settings.

SMTP Server Settings

In order to send email for the Performance Monitoring solutions, the Simple Mail Transfer Protocol (SMTP) Server must be configured.  See your company's network administrator if applicable for settings.

Version Control

By default, MetaManager^TM will save project item backups for projects located within the Version Control Source Control folders.  You can adjust how long those backups are held, by default backups are held for 30 days.  You may select a specific location to store backups.

Cognos BI Network Options

When you need to establish or modify the application's Cognos BI Network options, you must:

1. From the Tools menu, select Options.

2. Select the IBM Cognos BI tab.

Connections

MetaManager^TM supports connections multiple Cognos environments and multiple namespaces per connection. All information is stored and is used for subsequent connections to the IBM Cognos server(s).

NOTE: By establishing connections to multiple connections, you can easily switch between them without having to close MetaManager^TM.

Within the Connections grid, users can:

• Double-click any row to edit the connection.

• Click the edit icon to edit the connection.

• Click the delete icon to delete the connection.

• Select one or more rows and select the delete key on the keyboard.

Adding a New Connection

You can add as many connections as your environment contains. A connection is defined by MetaManager^TM as the unique combination of IBM Cognos Connection URL and logon credentials.

Connection Properties

1. Name - The name field represents a logical name for the connection you are establishing (i.e. Development, Production, etc.). The information used for a connection is displayed in the following locations within MetaManager^TM.

• The Gateway Selection dropdown in the top right corner of the MetaManager^TM user interface

• The root node in all MetaManager^TM portal trees

• In command line to specify connection information

• In any files saved by MetaManager^TM to specify connection information

2. URL - The gateway or dispatcher URL used to connect to your IBM Cognos Connection portal. This can be found in your IBM Cognos Configuration properties. The URL is either the gateway or dispatcher to IBM Cognos Connection. For example, use the following format http://<SERVER>/cognos8/cgi-bin/cognos.cgi for the gateway or http://<SERVER>:9300/p2pd/servlet/dispatch for the dispatcher.

   In case if there are any questions regarding running reports through the dispatcher, Please contact BSP Software Support if you have questions, Support@BSPSoftware.com

NOTE: In some environments, the gateway can be used if IBM Cognos Application Firewall (CAF) is enabled. However, in other instances the dispatcher must be used as an alternative. If possible, the gateway is preferable, as when users run reports from MetaManager^TM, if the dispatcher is used, graphics / icons may not display in the content. This is because the dispatcher does not utilize the web server to determine the location of these graphical files.

NOTE: The URL textbox will show the user's browser history to autosuggest the URL that the user is entering.

Authentication

The IBM Cognos Connection Authentication grid supports entering logon credentials for multiple namespaces. Specifying logon credentials is optional. When MetaManager^TM connects to a connection, it will attempt to use the anonymous account if no credentials have been specified. The user can then choose to manually logon and / or logon into more namespaces if desired.

If the anonymous account is disabled, then the user will be prompted to log on. This behavior mimics the behavior of IBM Cognos Connection.

If credentials are specified in this data grid, then an explicit logon request will be issued to the IBM Cognos Connection server when the user chooses the applicable connection from the dropdown box within MetaManager^TM. The user will not receive any error message if the credentials are invalid, but instead the user will simply not have the associated access to that connection within MetaManager^TM. As a result, when the user expands the MetaManager^TM portal tree, they will be required to logon manually if the anonymous account is disabled.

NOTE: To log on to multiple namespaces, click the link “Log on to multiple namespaces” and enter the credentials for each namespace.

NOTE: If the master password is cleared, then the passwords for any established credentials will also be cleared and become invalid. The user should either delete the credentials or reset the passwords. If not, MetaManager^TM will send failing logon requests to the server when the server is selected form the dropdown.

HTTP Security

Some web servers require HTTP Basic Authentication information to be provided when communicating with the server. As with the IBM Cognos credentials, providing this information is optional. If the information is provided it will be sent along with the authentication request, if it is not provided and it is required, then MetaManager^TM will receive an "Authentication error" from the web server. MetaManager^TM will then display a dialog to the user prompting them to enter their network credentials.

NOTE: To enable HTTP security, click “Advanced Security Options” under stored credentials. If the HTTP Security information is not stored with each connection, the information will not be saved in the stored settings and will only be retained in memory for the session.

If HTTP Security credentials are not supplied, then the currently logged on user’s “Default Credentials” are supplied on every request.

Advanced Security Options

External Single Sign-On

External Single Sign-on is used to handle Forms Based Authentication (FBAC) mechanisms. These include external proxy systems like SiteMinder.
If the External Single Sign-on checkbox is selected, then the user will be presented with a logon page when the connection is selected from the dropdown in the top right corner of the MetaManager^TM user interface.
When MetaManager^TM attempts to connect to IBM Cognos Connections in an environment protected by FBAC, one of these FBAC proxy systems will redirect the request to an HTML logon page. When the user logs on and obtains the external 3rd party authentication session information, the next request to IBM Cognos Connection will succeed. MetaManager^TM command line mode is not supported when a 3rd party FBAC authentication security system is in place because the user must enter in the required credentials manually. These credentials cannot be saved and automatically used by MetaManager^TM.

External Authentication

This option is needed if there is an external website or gateway that you have to authenticate through in order to get to Cognos. Simply check the box and enter the URL and this option will prompt a logon page where the user can enter credentials.

Cognos TM1 Connection Options

The TM1 connection details can be located by:

1. From the Tools menu, select Options.

2. Select the IBM Cognos TM1 tab.

The TM1 properties need to be completed before connections to TM1 Admin Servers can be created.

TM1 Properties

Details of a TM1 Installation Bin Directory are required in order to use the TM1 modules. This can be located on the same machine that MetaManager^TM for TM1 is installed on or a TM1 server.

Connections

To create a connection to a TM1 Admin Server, first choose ‘Add’ to display the Add Connection options. Name the connection and provide the name of the machine on which the TM1 Admin Server is installed. Ensure that all TM1 Servers are running before selecting ‘Load’:

Once complete the connection will be displayed.

During the load, the Tm1s.cfg file of each TM1 Server is accessed to confirm the Integrated Security Mode. Select the ‘Edit’ button to view the TM1 Servers and add credential details.

TM1 Servers using native TM1 security only require a Username and Password; Cognos BI security also requires the Namespace. These details are case sensitive.

Select OK to store the connection information.

Control Objects

There is the option to toggle between displaying or hiding control objects, simply check the box the box to display and uncheck to hide:

Selecting a Connection

TM1 Servers are selected using the ‘Select a connection’ drop down menu in the top right-hand corner.