IBM Cognos Proven Practices: IBM Cognos 10 Audit Extension

Nature of Document: Proven Practice; Product(s): IBM Cognos 10 BI; Area of Interest: Security, Infrastructure, Development

A IBM Cognos 10 SDK application that provides additional auditing, including Role Auditing, for IBM Cognos 10 BI. The version of the application is 1.1.01 and it will work with IBM Cognos 10 BI versions 10.1 and up.

Share:

Business Analytics Proven Practices Team, Business Analytics Proven Practices Team, IBM

Business Analytics Proven Practices Team



15 February 2013 (First published 13 July 2011)

Also available in Russian Portuguese

Introduction

Purpose

The standard auditing features that come out of the box with IBM Cognos 10 BI cover many aspects of operation. However, some areas such as the auditing of users and capability assignments are not included. The aim of the c10AuditExtension application is to provide additional auditing for these areas.

Account Audit

An audit of all the user accounts that are found in all configured namespaces and certain properties of those accounts (basic details, portal pages, created and modified dates etc.). This allows reporting on the IBM Cognos user base and provides additional information to go with the role/capability audit. This type of audit will also by default record the content of users’ My Folders.

Content Audit

An audit of all the objects that exist in the main Content Store. This audit will process through the content store tree and log all the objects (folders, reports, queries, etc.) that it finds. It will log the basic information (such as name, search path, object permissions, created and modified date), as well as some details more specific to the item types (such as the specification XML of reports and queries, any saved parameter values applied to saved reports and the details of report output versions).

In order to also record the items in the Content Store that are located inside individual users’ My Folders areas, this audit type should be used in conjunction with the Account Audit (see above).

Status Audit

An audit of the current state of a server and related dispatchers. For each dispatcher registered in the target system, the configuration and activity will be logged, saving information such as time taken to connect, number of active processes and request duration.

Role/Capability Audit

An audit of all capabilities (such as report authoring) configured in the Cognos namespace and which roles, groups and users have been assigned access to those capabilities. Where a role or group is assigned access, the audit will log all the individual users that make up the role or group, so it is possible to accurately determine which individual users have access to a given capability.

Usage

The application is managed via a web front end that allows the configuration of server and namespace information and can be used to turn on or off individual audit types for a given server.

Audits can be initiated in three ways,

  • via the management web interface
  • via a simple URL/web form call
  • via a web services call (i.e. from Event Studio)

The results of each audit are logged to a database and an IBM Cognos Framework Manager model is provided to help report off the data.

Applicability

This application is designed for IBM Cognos BI version 10.1.

It is also intended to interact with any third party application that can issue commands via web services.

Exclusions and Exceptions

This application may not be compatible with all Custom Authentication Providers, depending on the implementation of the provider – for example, it generally expects a provider/namespace to require a simple username and password to log on - where a custom provider uses some other form of credential, the audit extension may be unable to authenticate to that namespace to audit it. This does not affect trusted signon type custom providers, providing that the underlying provider can be authenticated to in the normal way.

The databases that this application is known to work with are,

  • DB2 9.x and 10.x
  • MS SQL Server 2000, 2005 and 2008
  • Oracle 10g & 11g
  • MySQL 5
  • Apache Derby 10

The Status Audit depends on some information provided by the IBM Cognos 10 BI server that is subject to change and may be affected by future upgrades of IBM Cognos 10 BI.

This application will only work within a JRE version 1.5 or above.

Usage, support and feedback

It is recommended that this application be used as part of an IBM services package to ensure successful implementation and interpretation of the results.

The application and model are provided on a strictly “as is” basis and IBM Cognos Support is not able to offer any support for it. However, any feedback, bug reports or suggestions are welcomed.


Application Details

Process overview and architecture

The application is a web application and web service written in Java/AXIS. It is intended to be installed on an IBM Cognos 10 BI machine, running in either the IBM Cognos 10 Tomcat instance or its own application server.

After installation, the application will create its own database tables if they do not already exist and present an interface to allow the administrator to enter the details of IBM Cognos 10 BI servers and namespaces. Generally only one server entry would be used for each group of IBM Cognos 10 BI servers that makes use of the same Content Store. However, separate server entries are often used for different functional groups such as Production and Development.

The application can be secured from the management interface by defining a local password which will subsequently be required to access the interface or run audits. The reason a local password is used rather than tying to IBM Cognos 10 security is that the application can interact with multiple IBM Cognos 10 BI installations, so there is no one IBM Cognos 10 BI security namespace to tie it to.

When the administrator enters the details of a new IBM Cognos 10 BI Dispatcher, the application will connect to that Dispatcher and gather details of the configured security namespaces. These details will be added to the properties page for that Dispatcher and made ready for editing. It is essential that an entry exists, complete with valid login details, for every namespace that is used for object security or capability assignment in the Content Store so that they can be audited. This is because the application needs to be able to authenticate to the namespace in order to audit its contents. If the application cannot authenticate to a namespace that is used for object security or users, then its objects cannot be audited. If multiple namespaces are specified in a single server entry, authentication to all namespaces must be made otherwise the application will terminate the audit run.

Namespace login details will be encrypted and stored in the application database.


Installation

The application is deployed as a WAR (Web Archive) file that can be used with any suitable servlet container such as Tomcat or application server such as IBM WebSphere. You must first build the WAR file within your IBM Cognos 10 BI installation using the supplied scripts and then deploy the WAR file to your server.

The procedures outlined in this document cover deploying the application into the Tomcat servlet container that is normally installed with an IBM Cognos 10 BI server. Consult the documentation of the specific application server/servlet container for instructions on deploying a WAR file into alternative destinations.

Generally speaking, it is desirable for a production environment to run this application within its own Tomcat or IBM WebSphere instance. Please refer to the documentation of Tomcat, IBM WebSphere or other application server for details on how to deploy a web application.

The process for installation is as follows,

  • Unpack the installation to an IBM Cognos 10 BI server
  • Customise any files that you wish to modify
  • Import any third party JDBC drivers that you intend to use
  • Build the WAR file
  • Deploy the WAR file to an application server or servlet container
  • Configure the application using the web user interface

Unpack the installation and copy to an IBM Cognos 10 BI server

Unpack the ZIP file containing the Audit Extension application to a suitable temporary location. There will be two main folders,

reporting
This folder contains materials to allow you to report on the Audit Extension output with IBM Cognos 10 BI. It contains a IBM Cognos Framework Manager model and a IBM Cognos 10 BI deployment archive. You do not need to do anything with this at this stage.
war
This folder contains the application itself, in a subdirectory named AuditExt. You need to use this to build the WAR file.

From the war folder, copy the AuditExt directory and its subdirectories to your IBM Cognos 10 BI installation directory under the directory <c10install>/war. At this point, you can customise the application before building the WAR file. The default settings should be fine in most cases but if you need to make any changes to the configuration settings in the c10AuditExtension.properties file (see section 3.7) or the logging settings in the log4j.properties file (see section 6.1), the files are located in the <c10install>/war/AuditExt/classes directory.

Figure 1. The .properties files in the directory <c10install>\war\AuditExt\classes
Illustration 1: The .properties files in the directory <c10install>\war\AuditExt\classes

Install any required JDBC drivers

If you are using an IBM DB2 or Apache Derby database to store the Audit Extension data, you will not need to install any additional JDBC drivers, as the DB2 Universal Driver is included in the distribution (the DB2 license file will still need to be provided). If you plan to use Microsoft SQL Server, MySQL or Oracle then you will need to obtain the correct driver file and install it.

  • The SQL Server driver file is sqljdbc4.jar.
  • The Oracle driver file is ojdbc5.jar. You may also need to obtain orai18n.jar if using a non-English locale.
  • The MySQL driver file is mysql-connector-java-5.1.6-bin.jar.

Once you have obtained the correct JAR and/or license file(s) for your database, place them in the <c10install>/war/AuditExt/lib directory. If you do not install the correct driver at this stage, the application will warn you when you attempt to first configure the database.

Build and deploy the WAR file

Build the WAR file by running the <c10install>/war/AuditExt/build.bat (Windows) or the <c10install>/war/AuditExt/build.sh (UNIX/Linux) script. This will create the WAR file <c10install>/war/AuditExt/AuditExt.war. Place this file in the <c10install>/webapps directory. After a short time, the IBM Cognos 10 Tomcat server will automatically unpack the WAR file. The application is now ready to be configured.

Configure via UI

Access the web administration URL at http://servername:9300/AuditExt/. A screen prompting for database connection details will be presented. The prompts include the database type, the name and port number of the host database server, the database name and the userid/password used to connect to the database.

Figure 2. Screen with fields to provide connection information to the Audit Extension databases
Illustration 2: Screen with fields to provide connection information to the Audit Extension databases

The c10AuditExtension application can use either an existing IBM Cognos 10 BI audit database or a separate database created specifically for this application. It is strongly recommended not to use a database that is already in use for a IBM Cognos 10 Content Store.

IMPORTANT: The database specified in the Database name field must already exist prior to connecting. The application will create the necessary tables under this database.

The process of creating and populating database tables may take some time, depending on the speed of the server. Once OK has been clicked, wait for the screen to refresh before continuing – do not click OK more than once.

Database preparation

To prepare the database for use by this application, you should configure it in the same way as described in the IBM Cognos 10 BI Installation and Configuration Guide as if it were being used for a Content Store. You may also use a standard IBM Cognos 10 BI audit logging database, which should also have been configured in this way.

IMPORTANT: For IBM DB2, you must create an additional regular user tablespace with a page size of 16 KB. If you are using a database that has already been set up for IBM Cognos 10 BI audit logging, you may already have done this.

IMPORTANT: For Oracle, you may need to increase the maximum number of open cursors supported by the database. The default is 50, which will probably be insufficient for this application – a more suitable value would be 500. For more information see http://www.orafaq.com/node/758.

Reconfiguration

To reconfigure the main database connection, click on the Reset configuration link on the Manage Servers page. This allows for the re-entry of the database connection details. Alternatively, the main database connection can be reset manually by following these steps,

  • Stop the IBM Cognos 10 BI service
  • Edit the file <c10install>/webapps/AuditExt/WEB-INF/classes/c10AuditExtension.properties
  • Re-set the JDBC connection details as follows,
    # JDBC connection details:
    jdbc.url=
    jdbc.user=
    jdbc.password=
  • Restart IBM Cognos 10 BI

When IBM Cognos 10 BI is restarted and the administration URL is accessed again, the screen prompting for the JDBC connection details will be presented.

Configuration file reference

The main configuration file is called c10AuditExtension.properties and can be found at <c10install>/webapps/AuditExt/WEB-INF/classes. This configuration file contains the following parameters,

jdbc.url
jdbc.user
jdbc.password
Connection details for the database used by the Audit Extension application. These are generated by the application configuration interface and should not be edited manually, except to reset to empty values for reconfiguration. Note that the password is stored in an encrypted format.
option.ra.recurse.everyone
A Role Audit option that determines if the audit should perform a full recursion of the namespace(s) when the Everyone group is encountered in a capability or membership. This will cause users that have access via Everyone to be explicitly audited, but will increase database space and processing time required. Possible values are true and false. The default value is false.
option.ra.recurse.auth
A Role Audit option that specifies if the audit should perform a full recursion of the namespace(s) when the Authenticated Users group is encountered in a capability or membership. This will cause users that have access via Authenticated Users to be explicitly audited but will increase database space and processing time required. Possible values are true and false. The default value is true.
option.ra.recurse.anon
A Role Audit option that determines if the audit should perform a full recursion of the namespace(s) when the Anonymous Users group is encountered in a capability or membership. This will cause users that have access via Anonymous Users to be explicitly audited, but will increase database space and processing time required. Possible values are true and false. The default value is false.
option.ra.max.items
A Role Audit option that limits the maximum number of items that will be processed by the audit. If the number is exceeded, the audit is terminated and recorded as a failure. If it is set to a value of zero, no limit will be applied. The default value is 20000.
option.ra.max.duration
A Role Audit option that limits the maximum length of time, in seconds, that the audit should be run for. If this time is exceeded, the audit is terminated and recorded as a failure. If it is set to a value of zero, no time limit will be applied. The default value is 900 (15 minutes).
option.ca.include.specifications
A Content Audit option that determines if the audit should record the specification XML of any reports/queries/analyses that it finds. Possible values are true and false. The default value is true. If this parameter is set to false, less database space will be used.
option.ca.include.output
A Content Audit option that determines if the audit should record details of report versions and outputs for report objects that it finds. Possible values are true and false. The default value is true. If this parameter is set to false, less database space will be used and the audit may run faster.
option.ca.max.items
A Content Audit option that limits the maximum number of items that will be processed by the audit. If the number is exceeded, the audit is terminated and recorded as a failure. The default value is 0 (zero) which means no limit will be applied.
option.ca.max.duration
A Content Audit option that limits the maximum length of time, in seconds, that the audit should be run for. If this time is exceeded, the audit is terminated and recorded as a failure. If it is set to a value of 0 (zero), no time limit will be applied. The default value is 900 (15 minutes).
option.ca.policy.calculation
A Content Audit option that determines whether security policy calculation should be done in FM. Possible values are true and false. If set to false, the calculation will instead be done at runtime. The default value is true meaning there will be no calculation done at runtime.
option.aa.flatsearch
An Account Audit option that changes the method of scanning the namespace from the default recursive approach to a flat search. This option may be useful for very large namespaces. If this option is set, instead of processing recursively through the entire namespace, the app will perform a flat search only of users that have previously logged in to IBM Cognos 10 BI and record only those users. Users who exist in the source namespace but who have never logged in will be ignored. This approach can greatly improve processing times in cases where the source namespace is large but only a small fraction of its members are IBM Cognos 10 BI users. The default value is false, meaning that a traditional recursive search of all users will be performed.
option.aa.max.items
An Account Audit option that limits the maximum number of items that will be processed by the audit. If the number is exceeded, the audit is terminated and recorded as a failure. If it is set to a value of zero, no limit will be applied. The default value is 10000.
option.aa.max.duration
An Account Audit option that limits the maximum length of time, in seconds, that the audit should be run for. If this time is exceeded, the audit is terminated and recorded as a failure. If it is set to a value of 0 (zero), no time limit will be applied. The default value is 900 (15 minutes).
option.aa.include.content
An Account Audit option that determines if the audit should process the content of users’ My Folders. If set, this will cause a mini-Content Audit to be run for each user’s content where it exists. Possible values are true and false. The default value is true.
option.sa.include.configuration
A Status Audit option that determines if the audit should record the configuration information of dispatchers. This includes such information as the maximum number of processes. Possible values are true and false. The default value is true. If this parameter is set to false, less database space will be used.
option.sa.include.rawstatus
A Status Audit option that specifies if the audit should record the raw status XML of services that the audit finds. Possible values are true and false. The default value is true. If this parameter is set to false, less database space will be used.
option.sa.include.ping
A Status Audit option that specifies if the audit should perform additional basic network tests on the dispatchers registered with a server. Possible values are true and false. The default value is true.
security.keystore.filename
The location of the keystore file that is used for security. If the file does not exist at this location, a new one will be generated. Note that this must be a writeable location otherwise the application will fail. The default value will place the keystore in the ./configuration directory of the IBM Cognos 10 BI installation using a relative file path. If this application was deployed anywhere other than the Tomcat servlet container that was installed with IBM Cognos 10 BI, this value will need to be edited.
option.db.setdefault.audittypes
A database option that determines if the application should reset the audit type descriptions in the database to their default values if they have changed. Possible values are true and false. The default value is false.
option.db.setdefault.statusresulttypes
A database option that determines if the application should reset the status result type descriptions in the database to their default values if they have changed. Possible values are true and false. The default value is false.
option.db.setdefault.serverversiondesc
A database option that determines if the application should reset the server version descriptions in the database to their default values if they have changed. Possible values are true and false. The default value is false.
option.db.setdefault.pingtype
A database option that determines if the application should reset the ping test type descriptions in the database to their default values if they have changed. Possible values are true and false. The default value is false.
option.db.setdefault.pingresult
A database option that determines if the application should reset the ping test result descriptions in the database to their default values if they have changed. Possible values are true and false. The default value is false.
option.db.dimension.time.populate
A database option that determines if the application should fully populate the time dimension table when the table is created on first startup. Note that any missing times will be added when the audit for that time runs, so pre-population is not required, although it is considered better for reporting purposes. Possible values are true and false. The default value is true.
option.db.dimension.date.initdays
A database option that specifies the number of days (starting from the current date) to pre-populate in the date dimension table when it creates it on first startup. Note that any missing dates will be added when the audit for that time runs, so full pre-population is not required, although it is considered better for reporting purposes. The default value is 730 (2 years).
option.db.maxbatch
An option that specifies the maximum number of items that should be processed before a database write. This applies to all audit types and is designed to reduce overall memory consumption for very large audits. The default value is 2000.
option.db.random-audit-id
An option that controls whether the database ID generated for each audit should be a pseudo-random number (a value of true) or sequential (a value of false). The default value is false.

Considerations for deploying into another application server

As noted above, if installing into a heavily used production environment, you should consider installing into another servlet container. This could be a standalone Tomcat instance (http://tomcat.apache.org/download-55.cgi), or a full application server such as the IBM WebSphere Application Server.

Generally, the procedure is as simple as deploying any web application – in the case of Tomcat, you can just drop the WAR file in the webapps directory as you would with IBM Cognos 10 BI. There are two file path considerations to make though,

  1. In WEB-INF/classes/log4j.properties, the log file name is specified using a relative path, ../logs/c10AuditExtension.log. While this works with IBM Cognos 10, you may need to change this to either a different relative path or a fully qualified path such as C:/logs/c10AuditExtension.log.
  2. The file WEB-INF/classes/lc10AuditExtension.properties contains a relative path in the security.keystore.filename property (../configuration/c10AuditExtension.keystore). Verify that this path works in your environment and if necessary update it. Remember to use forward slashes for the pathname.

Another alternative configuration is to install into a dedicated IBM Cognos 10 BI installation. As the Audit Extension can communicate with multiple IBM Cognos 10 BI servers and not just the one it is installed in, you could have a dedicated IBM Cognos 10 BI instance for running this audit and reporting off it. Verify your licensing to determine is this is a viable alternative.

Removal and reinstallation

To uninstall the application, stop IBM Cognos 10 BI and delete the following,

  • the <c10install>/webapps/AuditExt.war file
  • the <c10install>/webapps/AuditExt directory

Optionally, the keystore file can also be deleted. By default, the keystore file is located at <c10install>/configuration/c10AuditExtension.keystore but this location will be different if the application has been deployed outside of the Tomcat servlet container installed with IBM Cognos 10 BI.

IMPORTANT: If the keystore file is deleted or the application is installed on another machine without copying the keystore file to the new machine, it will no longer be possible to access saved passwords and there may be errors running and administering audits.

Optionally, the database tables created by the application can be deleted. The database tables are all prefixed with “AE_”.


Using The Application

Manage servers

After the application has been configured, the main interface is the Manage Servers page, which is accessed via http://servername:9300/AuditExt/. The initial Manage Servers page will contain no servers.

Figure 3. The initial Manage Servers page showing no defined IBM Cognos 10 servers
Illustration 3: The initial Manage Servers page showing no defined IBM Cognos 10 servers

Add a server

From the Manage Servers page, add a new server entry by filling in the fields below the label Add new server and clicking the Add button. The fields to fill in are,

ID: A text identifier for the IBM Cognos 10 BI server to be audited. This could be a hostname or simple identifier like “Production”. As the value of this identifier may be used to refer to the server for commands, it is suggested that this value be a simple, short string with only standard characters.
URL: The URL the application will use to connect to the IBM Cognos 10 BI server to be audited. This URL could either be directly to a IBM Cognos 10 BI dispatcher or to a dedicated gateway for IBM Cognos 10 SDK applications.
Version: From the dropdown list, select the IBM Cognos 10 BI version that is running on the server to be audited.
Figure 4. Adding an IBM Cognos BI server using the Manage Servers page
Illustration 4: Adding an IBM Cognos BI server using the Manage Servers page

Once a new server has been added successfully, the Edit Server page that contains the various properties that apply to the IBM Cognos 10 BI server just added will automatically be shown. There are several fields on this page and these fields are grouped into three sections, the Set properties section, the Saved namespace logins section and the Add new namespace login section.

Set properties section

URL: The URL of the IBM Cognos 10 BI server to be audited.
Version: The version of the IBM Cognos 10 BI server behind the specified URL.
Description: An optional description generally used to describe the auditing that will take place on the IBM Cognos 10 BI server behind the specified URL.
Filter (Content Audit): A text field used to define a filter that will be used on a Content Audit. The Content Audit filter will be described shortly.
Filter (Account Audit): A text field used to define a filter that will be used on an Account Audit. The Account Audit filter will be described shortly.
Role audit active: When checked, the Role Audit will be performed. This item is checked by default.
Content audit active: When checked, the Content Audit will be performed. This item is checked by default.
Account audit active: When checked, the Account Audit will be performed. This item is checked by default.
Status audit active: When checked, the Status Audit will be performed. This item is checked by default.

Saved namespace logins section:

User: The userid for the associated security namespace that will be used by the application to logon to the IBM Cognos 10 BI server being audited.
Password: The password associated with the userid.
Password (verify): To verify the value in the password field.
Save icon: Save the login information for the associated namespace.
Delete Login icon: Delete the login information for the associated namespace.

Add new namespace login section:

Namespace ID: The ID of the security namespace to login into. This needs to be the same value as the one in the Namespace ID field for the security namespace definition in IBM Cognos Configuration.
Username: The userid for the specified security namespace that will be used by the application to logon to the IBM Cognos 10 BI server being audited.
Password: The password associated with the userid.
Password (verify): To verify the value in the password field.
Add button: Add the login information for this namespace to the Saved namespace logins section.

Click the Update button to save the changes, click the Return button to return to the Manage Servers page.

Figure 5. Edit Servers page used to define audit filters and namespace logins
Illustration 5: Edit Servers page used to define audit filters and namespace logins

When a new server has been added, any namespaces that have been configured on the IBM Cognos 10 BI server to be audited will have been automatically added to the properties page without userids and passwords.

NOTE: If using this application in a test or development environment and Anonymous access has been enabled on the IBM Cognos 10 BI instance, the configured namespaces will not automatically appear. Configured namespaces can be added manually by filling in the fields in the Add new namespace login section.

When a new server has been added, the Manage Servers page will contain a list of all the servers that can be audited by this application.

Figure 6. Manage Servers page showing several IBM Cognos 10 BI servers that can be audited
Illustration 6: Manage Servers page showing several IBM Cognos 10 BI servers that can be audited

Delete a server

A server can be deleted from the Manage Servers page. To delete a server, click the Delete Server icon next to the server entry. A page will appear asking the user to confirm or cancel the deletion. If confirmed, the Manage Servers screen will reappear with the deleted server removed from the list.

Manage server namespaces

For each server, namespaces can be managed from the properties page of the specified server. If a new server has just been added, the properties page will be displayed automatically. To access and edit the properties page for any server shown in the list on the Manage Servers page, click the Set Properties icon beside the targeted server and the Edit Servers page will be displayed. The fields on the Edit Servers page were described earlier in the section titled Add a server.

Before a namespace can be included in an audit, the login credentials the application is to use must be supplied. Enter usernames and passwords one namespace at a time, clicking the Save icon next to that namespace entry after each one. If an attempt is made to save multiple namespace credentials at the same time, only the credentials that correspond to the Save icon that was clicked will be saved. Note that saved namespaces will display the saved user but will never display the saved password.

For any unwanted or unused namespaces, they should be deleted these by clicking the Delete Login icon. If they are not deleted, the application will attempt to login to the namespace and the audit may fail if unable to login. An example of such a namespace is one that is used only for single signon.

To add a new namespace, enter the details in the section labelled Add new namespace login at the bottom of the screen. The fields for this section were described earlier in the section titled Add a server.

When finished with the server properties page, click the Return button to go back to the Manage Servers page.

Configure server properties and audit types

As mentioned earlier, within the Edit Server page, additional properties can be set for the server. The properties that can be set are,

  • Update the dispatcher URL
  • Add or modify a description for the server
  • Set which audit types should be run for that server
  • Apply filters to the audits

Set audit filters

For Account and Content audits, it is possible to specify a filter to limit the scope of the auditing to a subsection of the namespace or content store. These filters are specified in one of the filter fields of the Edit Server page. If no filter is to be applied (the default), leave the filter values empty.

A filter takes the form of a series of regular expressions, separated by forward slashes to denote folders. Usage is slightly different depending on whether it is a content or account audit. More information about regular expressions can be found at http://www.regular-expressions.info/.

Account audit filter

The filter is assumed to start at the namespace level, so the first item in the filter will refer to the namespace. For example, to restrict the audit to members of the Users folder within the Accounts folder for all configured namespaces, the filter term would be,

*/Accounts/Users

The asterisk in the first item means that all namespaces will be matched. Alternatively, to restrict the audit to the same set of folders but also restrict to just the namespace with the ID “ADNamespace”, the filter term would be,

ADNamespace/Accounts/Users

The following filter would be slightly less restrictive and pick up all items under Accounts for all namespaces,

*/Accounts

Any regular expression can be used. However, it is important to remember that the ‘/’ character is a special case and will be treated as a folder separator.

Content audit

The filter is assumed to start from the top content (package) level. For example, the following filter would restrict the content to everything within the “GO Sales and Retailers” package,

GO Sales and Retailers

To restrict it further to the “Report Studio Report Samples” folder within that package, the filter would be,

GO Sales and Retailers/Report Studio Report Samples

To limit the content audit to all packages that start with “GO”, use the following,

GO*

Note that the filter is case sensitive.

Set security

As stated earlier, the application uses its own security mechanism. Click the link named Set admin password on the main Manage Servers page to specify the password required to run the application. A screen with Password and Confirm Password fields will be presented. Specify the password in both of these fields and click the OK button to set the admin password.

Figure 7. The Set admin password screen prompting for a password and password confirmation
Illustration 7: The Set admin password screen prompting for a password and password confirmation

After a password has been set, users will be presented with a prompt screen that will ask them to enter the password required to access the application.

Figure 8. The screen that prompts the user for the admin password
Illustration 8: The screen that prompts the user for the admin password

Run audits via web interface

To run an audit via the web interface, go to the Manage Servers page. Each server entry has a Run button that will cause the configured audits to be run for that server. To run the audit for all configured servers, click on the Execute button next to the All servers field.

Run audits via URL

To run an audit for a server ID using a URL use the following syntax,

http://servername:9300/AuditExt/AuditServlet?action=run_audit&server_id=serverId

To run an audit for all servers specified in the Manage Servers page using a URL use the following syntax,

http://servername:9300/AuditExt/AuditServlet?action=run_audit&server_id=all

Run audits via web service call

The WSDL for the web services interface can be found at the URL,

http://servername:9300/AuditExt/services/AuditService?wsdl

There are two methods available in the web services interface:

  • runAudit – Takes one parameter, the server ID, and runs the configured audits for that server.
  • runAuditAll – Takes no parameters and runs the configured audits for all servers.

This web service can be called from any application but an example will be presented here that uses Event Studio to create a IBM Cognos 10 BI agent that will call the web service interface to run an audit. The example will use the sample package that accompanies this application.

When Event Studio is invoked to create a new agent, the first screen that appears is Specify an event condition... Use a measure in the model that is known to be greater than zero or non-null. This will force the event condition to be true and the agent will be guaranteed to run on demand or as scheduled. In this instance the condition will be set to,

[Server Added(Timestamp)] <> null

Figure 9. In Event Studio, specify a known event condition that will resolve to true
Illustration 9: In Event Studio, specify a known event condition that will resolve to true

From the Add a Task list, select Advanced > Call a Web service...

Figure 10. In Event Studio, set the task for the known event condition to call a web service
Illustration 10: In Event Studio, set the task for the known event condition to call a web service

Enter the URL to the WSDL into the Web service URL: field and click on the Retrieve button to get the available methods.

Figure 11. In Event Studio, click the Retrieve button to getthe WSDL for the web service at the specifed URL
Illustration 11: In Event Studio, click the Retrieve button to getthe WSDL for the web service at the specifed URL

Once the WSDL has been retrieved, the operations that can be performed will be stored into the dropdown list labelled Operation: and a box labelled Arguments: will allow setting the value for each argument associated with each operation. In this instance, the runAudit method has been selected from the dropdown list and the previously configured server ID PrimaryServer has been supplied as the serverIdentifier argument.

Figure 12. In Event Studio, select the desired operation for the web service and specify the necessary arguments
Illustration 12: In Event Studio, select the desired operation for the web service and specify the necessary arguments

Save the agent. The agent can now be scheduled through IBM Cognos Connection.

Sample deployment

An IBM Cognos 10 BI deployment archive consisting of a package containing some sample reports and agents created against the sample IBM Cognos Framework Manager model is provided with this application. The sample deployment and model are contained within the file AuditExt_reporting_ver_yyyymmdd.zip, where the ver portion of the name is the version(s) of IBM Cognos 10 BI to use and the yyyymmdd portion of the name represents the date the reporting package was released.

To import the sample deployment so that it can be used by the IBM Cognos 10 BI studios,

  • Copy the file AuditExt_deployment_ver_yyyymmdd.zip to the IBM Cognos 10 BI deployment directory, usually <c10install>/deployment.
  • From IBM Cognos Administration, click the Configuration tab, select Content Administration, and click the New Import icon. Select the deployment archive named AuditExt_deployment_ver yyyymmdd. From there, follow the instructions and options presented by the New Import wizard. In most instances, the default settings will suffice. Note that the internal deployment name is Cognos_Audit_Extension.

Before the package can be used, it is necessary to create a new data source in the IBM Cognos Content Store that will interact with the audit database specified when this application was initially installed. From IBM Cognos Administration, click the Configuration tab and select Data Source Connection. Click on the New Data Source icon and give the new data source the name audit_ext. From there, follow the instructions and options presented by the New Data Source wizard to create the data source.

The package can now be used by the IBM Cognos 10 BI studios.

Sample model

A sample IBM Cognos Framework Manager model is also supplied with the application as a basis for further development. The sample model is provided in the file AuditExt_model_yyyymmdd.zip where the yyyymmdd portion of the name represents the date the model was released.

Before this model can be used, a data source named audit_ext must exist in the IBM Cognos 10 Content Store. This data source is the same as the data source described in the section titled Sample deployment.

Unzip the sample model to a suitable directory and from IBM Cognos Framework Manager, open the project file AuditExt.cpf.

Figure 13. Open the AuditExt.cpf project with Framework Manager
Open the AuditExt.cpf project with Framework Manager

Recognizing c8AuditExtension

The c10AuditExtension application recognizes the existence of the c8AuditExtension application.

It is recommended that the c10AuditExtension application use a separate database from the c8AuditExtension application. However, it is possible for c10AuditExtension to make use of the database that was established with c8AuditExtension. If the c10AuditExtension application is configured to use an existing database that will be shared with c8AuditExtension then the following apply,

  • IBM Cognos 8 servers that were defined in c8AuditExtension will appear on the Manage Servers page and can be edited on the Edit Server page.
  • Audits for IBM Cognos 8 servers will not run from the c10AuditExtension application.
  • Reporting should be done using the reporting package supplied with c10AuditExtension.

See http://www.ibm.com/developerworks/data/library/cognos/development/utilities/page509.html for more information on the c8AuditExtension application.


Other

Logging

This application uses log4j to provide logging services. To change the logging settings, edit the file <c10install>/webapps/c10AuditExtension/WEB-INF/classes/log4j.properties. The log file defaults to <c10install>/logs/c10AuditExtension.log.

See the log4j documentation at http://logging.apache.org/log4j/1.2/index.html for more information on how to configure log4j.

Database tables

The application creates/uses the following tables:

General configuration

AE_CONFIG_MAIN
Main application configuration containing the configured servers.
AE_CONFIG_NS
The saved namespaces configured for each server.
AE_AUDIT_TYPES
List of possible audit types.
AE_SERVER_VERSIONS
List of supported Cognos server versions.
AE_CONFIG_AUDIT_TYPES
Which audit types are configured for each server.
AE_SECURITY
Table containing encrypted admin password.

Account audit

AE_ACCOUNTAUDIT_MAIN
Main detail table.
AE_ACCOUNTAUDIT_PORTALPAGES
Records of any user portal pages.

Content audit

AE_CONTENTAUDIT_MAIN
Main detail table.
AE_CONTENTAUDIT_PARAMS
Record of saved parameters for reports and views.
AE_CONTENTAUDIT_POLICIES
Record of all security policies applied to all objects.
AE_CONTENTAUDIT_SPEC
Record of report, query and analysis specifications.
AE_CONTENTAUDIT_REPORT_VERSIONS
Record of report output versions saved in the Content Store.
AE_CONTENTAUDIT_REPORT_OUTPUTS
Record of report outputs saved in the Content Store.

Role audit

AE_ROLEAUDIT_HEIR
A flattened version of the hierarchy of the Capabilities and Namespace folders.
AE_ROLEAUDIT_DETAIL
Main detail table.

Status audit

AE_STATUSAUDIT_MAIN
Main detail table.
AE_STATUSAUDIT_RESULT_TYPES
Lookup table for result type codes.
AE_STATUSAUDIT_DISP
Main audit details for each dispatcher registered in the content store.
AE_STATUSAUDIT_DISP_CONFIG
Additional configuration details for each dispatcher registered in the content store.
AE_STATUSAUDIT_DISP_SERVICES
Details on the running services for each dispatcher registered in the content store.
AE_STATUSAUDIT_DISP_PING
Results of simple network tests on dispatchers.
AE_STATUSAUDIT_PING_TEST_TYPES
Possible types of simple network tests that can be performed on dispatchers.
AE_STATUSAUDIT_PING_RESULT_TYPES
Possible result codes and descriptions of simple dispatcher network tests.

General audit data

AE_STATUS
History and status of audit runs.
AE_AUDIT_TYPE_LOG
Log of the audit types run for each audit.
AE_ITEM_LOOKUP
Lookup table mapping item store IDs to names.
AE_ITEM_LOOKUP_FAILURES
Record of all items that could not be looked up (for example because they were removed from the content store but were found in audits as owners of other items etc.)
AE_MAP_DATETIME
Table for mapping timestamps (such as the audit start and end times) to date and time dimension table keys.
AE_DIM_DATE
Date dimension table. The granularity is days.
AE_DIM_TIME
Time dimension table. The granularity is minutes.
AE_SECURITY_MEMBERS
Optional data on security policies generated during an Account or Content Audit when the option.ca.policy.calculation option is set to false.

Change History

Version 1.0

Initial release, based on c8AuditExtension version 1.5.


Download

DescriptionNameSize
Sample scripts for this articlec10AuditExtensionPublicPackage.zip2424KB

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Big data and analytics on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Big data and analytics, Information Management
ArticleID=699978
ArticleTitle=IBM Cognos Proven Practices: IBM Cognos 10 Audit Extension
publish-date=02152013