Deployment of IBM COGNOS BI

Nature of Document: Tip or Technique

Product(s): Event Studio, Cognos Connection
Area of Interest: Infrastructure

1 of 17
 Deployment of IBM COGNOS BI

1. Abstract
In stabilized IBM Cognos environments, deployment of IBM Cognos artifacts from one IBM Cognos
environment to another IBM Cognos environment (e.g. development to quality assurance) can be
automated to minimize the time and effort involved in the code migration process for the IBM Cognos
administrators and to provide flexibility to the IBM Cognos report developers to promote their code.
This approach involves providing a common deployment location in the IBM Cognos Content Manager
configuration in the source and target IBM Cognos environments. The export of the IBM Cognos artifacts
(Archive file) from the source environment will be placed in this common deployment location and the
Import to the target environment will pick the artifacts (Archive File) from the same common deployment
location.
Using this approach, the user just needs to run an Event Studio agent in the source IBM Cognos
environment for the code to be promoted to the target IBM Cognos environment. The Event Studio agent
run by the user in the source environment will perform the “export of IBM Cognos Content” operation
and trigger an Event Studio agent in the target IBM Cognos environment by way of the “Trigger.bat”
utility. The triggered agent in the target environment will perform the “import of IBM Cognos Content”
task. The IBM Cognos administrators and the respective user community will be notified by an email on
the status of the code deployment.
A specific agent needs to be designed for each application in such a way that the application specified
code is considered for code deployment. Each application architect can run their own Event Studio agent
in the source environment for their code to be deployed in the target environment.

2. Introduction
The organizations using IBM Cognos BI for reporting have development, quality assurance and
production environments where the IBM Cognos artifacts needs to be promoted from one IBM
Cognos environment to another IBM Cognos environment based on the requirements.

3. COMPONENTS USED

● IBM Cognos Configuration

● IBM Cognos BI Event Studio
● IBM Cognos Framework Manager
● Trigger. bat Utility
● Database Server

2 of 17
 Deployment of IBM COGNOS BI

4. ARCHITECTURE
The figure depicts a sample environment which uses a common deployment location in the source and
target environments to deploy to.

Figure 1

3 of 17
 Deployment of IBM COGNOS BI

Figure 2

5. PREREQUISITES
The following are required in order to make this technique work successfully.
1. A common location (shared drive) within the network which is accessible from the IBM Cognos
content manager.

4 of 17
 Deployment of IBM COGNOS BI

2. A mail server configured in the IBM Cognos Instances (source and target).
3. A database server preferably owned by IBM Cognos administration team.
4. The following capabilities need to be provided for the application architects to run the Event
Studio export tasks in source environment.

5. Execute permission to the administration tasks secured feature.

6. Traverse permission to the administration secured function.
7. Execute and traverse permission to the content administration page.

6 AUTOMATION AND STATUS UPDATION

The Steps in the Automation approach include:
● INITIAL SETUP
1. Configuring shared drive in IBM Cognos configuration of Content Mangers.
2. Setting up IBM Cognos Trigger.bat utility
3. Creating stored procedure to run the trigger

● EVENT STUDIO AGENT SETUP

1. Export deployment strategy (creating Event Studio export agent )
2. Import deployment strategy (creating Event Studio import agent )

6.1 CONFIGURING SHARED DRIVE IN IBM COGNOS CONFIGURATION OF CONTENT

MANAGERS
1. The “Deployment files location” of Environment properties in IBM Cognos Configuration of both
the environments (source and target) is modified to a shared location. After modification IBM
Cognos Services are restarted.
Figure 3

2. This shared location should be in the same network of the Content Manager servers in
environments and the service account running the IBM Cognos Service should have access
permissions to this shared location.
3. If the IBM Cognos environments are configured with multiple Content Managers, then the
“Deployment files location” needs to be modified in each of the IBM Cognos Configurations for
each of the Content Manager servers.

5 of 17
 Deployment of IBM COGNOS BI

6.2 SETTING UP IBM COGNOS TRIGGER.BAT UTILITY

The IBM Cognos utility called Trigger.bat is required for this process. This utility is used to trigger an Event
from a remote location (e.g. a database server) where a set of IBM Cognos Jar files are available. In the
current approach, the Trigger.bat utility is used to trigger the import operation in the target environment
from the Event Studio Agent that the user runs in the source environment.

1. This utility is deployed in a database server (which is preferably owned by the IBM Cognos
administration team).
2. The following screen shot shows the Trigger.bat utility files that are placed in a server location
where a SQL Server Database is installed.(these files can be placed anywhere in the physical
location of the server where the service account running the database server has access
permissions).
Figure 4

3. Of the above files “GoDatawarehouse.bat” and “Gosales.bat” are the files created for this
process. These files each represent two different applications. All other files are part of the
Trigger.bat utility. The batch file content would be as shown below. The
“GoDatawarehouse.bat” file will call the “Trigger.bat” file.
Figure 5

6 of 17
 Deployment of IBM COGNOS BI

4. The Dispatcher URI of the Target Environment, user ID and password which has traverse
permissions to IBM Cognos Administrator and the corresponding namespace and a trigger
name are passed as parameters to the Trigger.bat through this batch file. GoDatwarehouse is
the Trigger name mentioned in this batch file which is the name of the trigger used to setup
trigger schedule for “Event Studio Import Agent”. This is explained in the upcoming section
7.5.6. To know more about Trigger.bat utility, please refer Appendix B

6.3 STORED PROCEDURE CREATION TO RUN THE TRIGGER

The purpose of this stored procedure is to automate the batch file execution,. In order to accomplish this a
stored Procedure is created in the Database. Below is an example of a Stored Procedure for Microsoft SQL
Server 2005.

CREATE Procedure [dbo].[Bat_execution]

AS
EXEC master.dbo.xp_cmdshell ‘D:\flats\TriggerDeployment\GoDateaWarehouse.bat’

As shown in the screen shot, this stored procedure basically executes the “GoDatawarehouse.bat” in the
provided location, and this batch file in turn would run the Trigger.bat utility with the supplied parameters.
The Trigger.bat utility will trigger the required “Event Studio Import Agent” in the target environment that
will run the export and import of the deployment. The batch files and stored procedures need to be
created specifically for each of the application for their respective code deployment. The respective stored
procedures can be referred to in the agents created for the corresponding applications. e.g.
GoDatwarehouse, Gosales. The following conditions are required to leverage the stored procedure.

1. An IBM Cognos data source is created with the database containing the stored procedure as a
source in the IBM Cognos administration page.
2. A package is created from this datasource with a “Stored Procedure” imported for each of the
applications.
3. The IBM Cognos package is then published to IBM Cognos Connection.

6.4 EXPORT DEPLOYMENT STRATEGY

6.4.1 EXPORT CONTENT TASK CREATION

The content which needs to be exported to the target environment is done for the first time from the IBM
Cognos Administration page to use the corresponding export task for the automation. The Event Studio
agent can not be created until the export task exists, so an initial export must be configured. Make note of
the name of the export in IBM Cognos Administration as it will be required in Event Studio

7 of 17
 Deployment of IBM COGNOS BI

6.4.2 EVENT STUDIO AGENT CREATION-EXPORT

The Event Studio agent is designed in the source environment where the deployment is to be taken.
Below are the steps required to build this agent
1. The IBM Cognos Package published in the previous step is used as the Source package for the
Event Studio Agent
2. An always succeeding event is created in the first step of the event. This event is created to
make sure as the tasks defined in the agent should be executed successfully without checking
for any condition whenever the agent is run.

6.4.3 CREATING THE EXPORT DEPLOYMENT

1. Insert a “Run an export” task to the agent.
Figure 6

2. The export was created previously in the IBM Cognos Administration portal is used here. Select
the appropriate export to include in the agent.

8 of 17
 Deployment of IBM COGNOS BI

Figure 7

6.4.4 TRIGGERING THE IMPORT TASK

1. Insert an ‘Update a database’ task to the agent.
Figure 8

2. The package published and the corresponding stored procedure created in the Step 6.3 is
configured in this task.
3. The data modification stored procedure will run the “Trigger.bat” utility on the database server
which in turn triggers the import deployment agent in the target environment.

9 of 17
 Deployment of IBM COGNOS BI

Figure 9

6.4.5 EMAIL NOTIFICATION ON SUCCESS

1. The “Send an email...” task is added to the agent to send an email notification for the successful
completion of export task and successful trigger of import deployment in target environment.
Figure 10

2. The email body content and the recipients list are added as required notifying the successful
completion of tasks. The recipients list can include IBM Cognos administrators and application
architects who would run this agent as and when required for deployment.

6.4.6 EMAIL NOTIFICATION ON FAILURE

1. The “Send an email...” task is added to the agent to send an email notification if any of the tasks
in this agent failed.

10 of 17
 Deployment of IBM COGNOS BI

Figure 11

2. The email body content and the recipients list are added as required notifying of the failure of
tasks. The recipients list can include IBM Cognos administrators and application architects who
would run this agent as and when required for deployment.
3. The execution rule for this email task is defined via “Manage the task execution rules”.

Figure 12

4. The task execution rule for this task is configured to “When the agent or any of it’s tasks fail”
and defined in such a way that this task will be executed only if the agent itself fails or any of its
tasks fail.

11 of 17
 Deployment of IBM COGNOS BI

Figure 13

When completed the agent should resemble the one shown below. There should be four tasks, one to
export the deployment, one to execute the batch file, and then one to e-mail notification for either
success or failure of the agent or any of the previous tasks.
Figure 14

12 of 17
 Deployment of IBM COGNOS BI

6.5 IMPORT DEPLOYMENT STRATEGY

6.5.1 IMPORT CONTENT TASK CREATION

The content which needs to be imported into the target environment is done for the first time from the
IBM Cognos administration page to use the corresponding import task for the automation. The Event
Studio agent can not be created until the import task exists, so an initial import must be configured. Make
note of the name of the import in IBM Cognos Administration as it will be required in Event Studio

6.5.2 EVENT STUDIO AGENT CREATION

The Agent is designed as follows in the target IBM Cognos BI environment to which the IBM Cognos
content is to be deployed. Any IBM Cognos package can be used as a source package for this Event Studio
agent since the stored procedures created earlier are not used in this agent. To maintain integrity, the
package used for the Event Studio agent for the export task in the source IBM Cognos environment can
be used here after publishing the same deployment in the target environment.
An always succeeding event is created in the first step of the agent. This event is created to make sure as
the tasks defined in the agent should be executed successfully without checking for any condition
whenever the agent is run. The agent further consists of three tasks after the always succeeding event.

6.5.3 IMPORT DEPLOYMENT

1. The Advanced task, “Run an import” is added in the agent.
Figure 15

2. This task requires that the user select a deployment to import. Choose the deployment that
corresponds to the export run in the previous steps that is also the import deployment that was
configured in step 6.5.1.

13 of 17
 Deployment of IBM COGNOS BI

Figure 16

6.5.4 EMAIL NOTIFICATION ON SUCCESS

1. The “Send an email” task is added to the agent to send an email notification for the successful
completion of import task in the agent.
Figure 17

2. The email body content and the recipients list are added as required notifying of the successful
completion of tasks. The recipients list can include IBM Cognos administrators and application
architects who would run this agent when required for deployment.

6.5.5 EMAIL NOTIFICATION ON FAILURE

1. The “Send an email” task is added to the agent to send an email notification if any of the tasks in
this agent fails.

14 of 17
 Deployment of IBM COGNOS BI

Figure 18

2. The email body Content and the recipients list are added as required notifying the failure of
tasks. The recipients list can include IBM Cognos administrators and application architects who
would run this agent as and when required for deployment.

3. The execution rule for this email task is defined via “Manage the task execution rules”.
Figure 19

4. The task execution rule for this task is configured to “When the agent or any of its tasks fail”
and defined in such a way that this task will be executed only if the agent itself fails or any of its
tasks fail.

15 of 17
 Deployment of IBM COGNOS BI

Figure 20

5. The Event Studio import agent should now look like.

Figure 21

6.5.6 SCHEDULE THE EVENT BASED ON TRIGGER

The Event Studio Import Agent needs to be scheduled based on Trigger. This will allow the agent to be
launched by the trigger.bat utility. The Trigger name mentioned here as “GoDatwarehouse” is the Trigger
name passed as the parameter to the IBM Cognos “Trigger.bat” Utility.(as shown in Figure: 5.0)

16 of 17
 Deployment of IBM COGNOS BI

Figure 22

7 BENEFITS
1. This one time activity highly reduces the manual effort involved by the IBM Cognos
administrators in code migration process.
2. This approach provides flexibility for the IBM Cognos architects to perform the code
deployment themselves by just running the Event Studio agent in the source IBM Cognos
environment.
3. The architecture is defined in such a way that the deployment would be successful, even in case
of Content Manager Fail-overs’ in any of the configured IBM cognos environments.
4. The emails triggered after the tasks completion provides the status of the deployment.
5. Usage of the above technique will remove the dependency of using other third party tools
which are specifically used for IBM Cognos code migration by the developers and this provides
full control of the environment to the IBM Cognos administrators.

7 CONCLUSION
This approach can be further enhanced by integrating with the audit reports and the history of code
deployment performed by the users. This automated process will save time and provides the flexibility to
the application users to migrate their artifacts on their own schedule.

7 Appendix
A. Cognos Administration and Security Guide

B. KB 1022042: How to fire a trigger using the Trigger.bat utility

17 of 17