Вы находитесь на странице: 1из 33

IBM Cognos Proven Practices: IBM Cognos 8 Audit Extension

Nature of Document: Proven Practice; Product(s): IBM Cognos 8 BI; Area of Interest: Security, Infrastructure, Development
Skill Level: Intermediate Cognos Proven Practices Team Cognos Proven Practices Team IBM

05 Jul 2010 Updated 20 Oct 2011 An IBM Cognos 8 SDK application that provides enhanced auditing for IBM Cognos 8 BI, including Role auditing. The version of the application is 1.5.08 and it can be installed on IBM Cognos 8 BI versions 8.3 and 8.4.x.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 1 of 33

developerWorks

ibm.com/developerWorks

Introduction
Purpose The standard auditing features that come out of the box with IBM Cognos 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 c8AuditExtension 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 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 configured in the Cognos namespace (such as report authoring) 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.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 2 of 33

ibm.com/developerWorks

developerWorks

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 8 BI versions 8.1 MR1, 8.2, 8.3, 8.4 and 8.4.1 and makes use of the IBM Cognos 8 BI SDK to communicate with the various IBM Cognos 8 BI components. It is also intended to interact with any third party application that can issue commands via web services. Limited support is also provided for IBM Cognos ReportNet 1.1 servers, although differences in product features mean that not all audit features are supported. 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 supported databases for the application are, DB2 8.1 and 9.x MS SQL Server 2000 and 2005 Oracle 10g MySQL 5 Apache Derby 10

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 3 of 33

developerWorks

ibm.com/developerWorks

The Status audit depends on some information provided by the IBM Cognos 8 server that is subject to change and may be affected by future upgrades of IBM Cognos 8. This application will only work within a JRE 1.5 or above. An appropriate JRE is provided with installations of IBM Cognos 8 BI versions 8.3 and above. Usage, support and feedback This application should only be supplied to customers as part of a suitable 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 8 machine, running in either the IBM Cognos 8 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 8 servers and namespaces. Generally only one server entry would be used for each group of IBM Cognos 8 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 8 security is that the application can interact with multiple IBM Cognos 8 installations, so there is no one IBM Cognos 8 security namespace to tie it to. When the administrator enters the details of a new IBM Cognos 8 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

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 4 of 33

ibm.com/developerWorks

developerWorks

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 file that can be used with any suitable servlet container or application server such as IBM WebSphere. You must first build the WAR file within your IBM Cognos 8 installation using the supplied scripts and then deploy this 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 8 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 WAS instance. Please refer to the documentation of Tomcat, WAS 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 8 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 8 server Unpack the zip file containing the Audit Extension application to a suitable temporary location. This contains two main folders, reporting This folder contains materials to allow you to report on the Audit Extension output in Cognos 8 and contains a Framework Manager model and a Cognos 8 deployment archive. You do not need to do anything with this at this stage.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 5 of 33

developerWorks

ibm.com/developerWorks

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 8 installation directory under the directory <c8install>/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 c8AuditExtension.properties file (see section 3.7) or the logging settings in the log4j.properties file (see section 5.2), the files are located in the <c8install>/war/AuditExt/classes directory.

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 sqljdbc.jar. The Oracle driver file is ojdbc14.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 file(s) for your database, place them in the <c8install>/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.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 6 of 33

ibm.com/developerWorks

developerWorks

Build and deploy the WAR file Build the war file by running the <c8install>/war/AuditExt/build.bat (Windows) or <c8install>/war/AuditExt/build.sh (UNIX/Linux) script. This will create the WAR file <c8install>/war/AuditExt/AuditExt.war. Place this file in the <c8install>/webapps directory. After a short time, the IBM Cognos 8 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 c8AuditExtension application can use either an existing IBM Cognos 8 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 8 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.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 7 of 33

developerWorks

ibm.com/developerWorks

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 Installation and Configuration Guide as if it were being used for a Content Store. You may also use a standard IBM Cognos 8 audit logging database, which should also have been configured in this way. IMPORTANT: For 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 8 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 8 service. Edit the file <c8install>/webapps/AuditExt/WEB-INF/classes/c8AuditExtension.properties. Re-set the JDBC connection details as follows,
# JDBC connection details: jdbc.url= jdbc.user= jdbc.password=

Restart IBM Cognos 8. When IBM Cognos 8 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 c8AuditExtension.properties and can be found at <c8install>/webapps/AuditExt/WEB-INF/classes. This configuration file contains the following parameters,

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 8 of 33

ibm.com/developerWorks

developerWorks

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).

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 9 of 33

developerWorks

ibm.com/developerWorks

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 8 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 8 BI users. The default value is false, meaning that a traditional recursive search of all users will be performed.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 10 of 33

ibm.com/developerWorks

developerWorks

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 users 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 8 installation using a relative file path. If this application was deployed anywhere other than the Tomcat servlet container that was installed with IBM Cognos 8, this value will need to be edited.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 11 of 33

developerWorks

ibm.com/developerWorks

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).

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 12 of 33

ibm.com/developerWorks

developerWorks

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, or if your IBM Cognos 8 installation uses a JRE older than 1.5, 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 8. 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/c8AuditExtension.log. While this works with IBM Cognos 8, you may need to change this to either a different relative path or a fully qualified path such as C:/logs/c8AuditExtension.log. The file WEB-INF/classes/lc8AuditExtension.properties contains a relative path in the security.keystore.filename property (../configuration/c8AuditExtension.keystore). Verify that this path works in your environment and if necessary update it. Remember to use forward slashes for the pathname.

2.

Another alternative configuration is to install into a dedicated IBM Cognos 8 installation. As the audit extension can communicate with multiple IBM Cognos 8 servers and not just the one it is installed in, you could have a dedicated IBM Cognos 8 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 8 and delete the following,

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 13 of 33

developerWorks

ibm.com/developerWorks

the <c8install>/webapps/AuditExt.war file the <c8install>/webapps/AuditExt directory Optionally, the keystore file can also be deleted. By default, the keystore file is located at <c8install>/configuration/c8AuditExtension.keystore but this location will be different if the application has been deployed outside of the Tomcat servlet container installed with IBM Cognos 8. 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.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 14 of 33

ibm.com/developerWorks

developerWorks

Add a server From the Manage Servers page, add a new server entry by filling in the fields beside the label Add new server and clicking the Add button. The fields to fill in are, ID: A text identifier for the server. This could be a hostname or simple identifier like PrimaryServer. 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 IBM Cognos 8. This URL could either be directly to a IBM Cognos 8 Dispatcher or to a dedicated gateway for IBM Cognos 8 SDK applications. Version: The IBM Cognos 8 version running on the server.

Once a new server has been added successfully, the Edit Server page that contains the various properties that apply to the IBM Cognos 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 BI server to be audited.
IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011 Trademarks Page 15 of 33

developerWorks

ibm.com/developerWorks

Version: The version of the IBM Cognos BI server behind the specified URL. Description: An optional description generally used to describe the auditing that will take place on the IBM Cognos 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 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

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 16 of 33

ibm.com/developerWorks

developerWorks

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 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.

When a new server has been added, any namespaces that have been configured on the IBM Cognos 8 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 8 instance, the configured namespaces will not automatically appear. Configured namespaces can be added manually by filling in the fields under the label Add new namespace login. When a new server has been added, the Manage Servers page will contain a list of

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 17 of 33

developerWorks

ibm.com/developerWorks

all the servers that can be audited by this application.

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.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 18 of 33

ibm.com/developerWorks

developerWorks

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 Within the server properties page, additional properties can be set for the server. The properties 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 Click on the Update button to save the modified properties. 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 the filter boxes of the server properties screen. If no filter is to be applied (the default), leave the filter values empty. The filters take 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 that is within Accounts, for all configured namespaces, the filter term would be, */Accounts/Users

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 19 of 33

developerWorks

ibm.com/developerWorks

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 filter 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 Set admin password link on the main Manage Servers page to specify the password required to run the application.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 20 of 33

ibm.com/developerWorks

developerWorks

After a password has been set, users will be prompted to enter it in order to access the application.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 21 of 33

developerWorks

ibm.com/developerWorks

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 8 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

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 22 of 33

ibm.com/developerWorks

developerWorks

From the Add a Task list, select Advanced > 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.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 23 of 33

developerWorks

ibm.com/developerWorks

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.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 24 of 33

ibm.com/developerWorks

developerWorks

Save the agent. The agent can now be scheduled through IBM Cognos Connection. Sample deployment An IBM Cognos 8 deployment archive consisting of a package containing some sample reports and agents created against the sample 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 8 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 8 studios, Copy the file AuditExt_deployment_ver_yyyymmdd.zip to the IBM Cognos 8 deployment directory, usually <c8_install>/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 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 25 of 33

developerWorks

ibm.com/developerWorks

IBM Cognos 8 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 c8_audit. 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 8 studios. Sample Framework Manager model A sample 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 c8_audit must exist in the IBM Cognos 8 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 Framework Manager, open the project file AuditExt.cpf.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 26 of 33

ibm.com/developerWorks

developerWorks

Other
Recognition of c10AuditExtension The c8AuditExtension application recognizes the existence of the c10AuditExtension application. If the c10AuditExtension application has been set up to use the same audit database as the c8AuditExtension, then the IBM Cognos 10 BI servers that were defined in c10AuditExtension will appear on the Manage Servers page and can be edited on the Edit Server page. However, audits for IBM Cognos 10 servers will not run from the c8AuditExtension application. See http://www.ibm.com/developerworks/data/library/cognos/development/utilities/page574.html
IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011 Trademarks Page 27 of 33

developerWorks

ibm.com/developerWorks

for more information on the c10AuditExtension application. Logging This application uses log4j to provide logging services. To change the logging settings, edit the file <c8-install>/webapps/c8AuditExtension/WEB-INF/classes/log4j.properties. The log file defaults to <c8install>/logs/c8AuditExtension.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.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 28 of 33

ibm.com/developerWorks

developerWorks

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.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 29 of 33

developerWorks

ibm.com/developerWorks

AE_STATUSAUDIT_DISP_PING Results of simple network tests on dispatchers. AE_STATUSAUDIT_PING_TEST_TYPES Possible types of 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.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 30 of 33

ibm.com/developerWorks

developerWorks

Change History
Version 1.0 Initial release. Version 1.1 Added Status Audit feature. Added ability to restrict audit scope for Content and Account audits. Database structure change to remove search path from primary keys. Recreate any 1.0 database from scratch or contact the Proven Practices team to obtain an update SQL script. Version 1.2 Support for Oracle database. Some database naming changes. Enhancements to Content Audit. Version 1.3 Support for IBM DB2 database. Performance and scalability optimisations. Version 1.4 Support for Apache Derby and MySQL databases. Content Auditing for users My Folders. Support for IBM Cognos 8.4 BI. Version 1.5 Removal of support for Java 1.4. Removal of third party JDBC drivers from installation war file. Additional user audit functionality. Various internal changes.

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 31 of 33

developerWorks

ibm.com/developerWorks

Added option.aa.flatsearch property (version 1.5.07). Changes to recognize the existence ofc10AuditExtension (version 1.5.07).

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 32 of 33

ibm.com/developerWorks

developerWorks

Downloads
Description
Sample scripts for this article Information about download methods

Name

Size

Download method
HTTP

c8_Audit_Extension_Public_Package.zip 4868KB

About the author


Cognos Proven Practices Team Cognos Proven Practices Team

IBM Cognos 8 Audit Extension Copyright IBM Corporation 2010, 2011

Trademarks Page 33 of 33

Оценить