IBMCognosBusinessIntelligencev10:TheCompleteGuide

Chapter 7: Event Studio

Overview Event Studio is a web-based component used to create and manage agents that monitor changes in data (aka events) and perform defined tasks when the event is detected. It is a core IBM Cognos BI component and uses the same data sources and administration and security infrastructure already defined in the IBM Cognos BI environment. It is installed as part of IBM Cognos BI. Event Studio Capabilities Event Studio enables you to proactively detect and react to exceptional business events. As soon as these events are detected, using a business condition, you can do the following:
n

Notify stakeholders via email alerts or web portal headlines. Run reports that can then be sent via email as a link or as an attachment. Assign a task to someone for action. Execute a stored procedure or initiate a web service. Automate certain administrative tasks such as run an export or import or run a content maintenance task.

Agents may also be run automatically at a time that suits your business. For example, if you need to track noncompliant service-level agreement (SLA) metrics that missed their target, you can set up rules that track those metrics and send out email with attached report when it happens. In financial reporting, it is required by law (that is, certain Sarbanes-Oxley acts) that companies report within a certain period of time. Event Studio agents enable you to monitor such events when they happen, enabling you to respond to them immediately. You can use relational, dimensional, or dimensionally modeled relational data in Event Studio. In Cognos BI v10, the Human Task Service is added that enables auditable user interaction around events and processes. This service supports the following functionality:
n

Assign responsibility for completion of a task to an individual or a group. Assign task approval and sign off. Automatically assign tasks when a value changes or an event occurs. Perform task status tracking and escalation. Control the complete and start dates. Escalate tasks to users or subtasks. Fully task auditable. Add comments to a task.

Typically Event Studio is used by Cognos administrators or developers to create agents and tasks that an end user can run or schedule as required. Launch Event Studio You can launch Event Studio from the Welcome screen by selecting the Manage my events option, or from the IBM Cognos Connection launch option. Choose Launch > Event Studio. You must select a package to work with when launching Event Studio. You can use the data items from the package to build your event conditions. You can work with only one package at a time, so you must ensure that all the metadata required for alert and notification is available in a single package.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

Event Studio High-Level Interface Event Studio interface is easy to use and consists of four main areas, as shown in Figure 7.1:
n

I want to Insertable Objects Summary Content area

Figure 7.1: Event Studio interface. The following list describes the areas and options available from the Event Studio interface (refer to Figure 7.1):
n

I want to : An area displays the tasks you can perform to create an agent. This area has four options available as links displayed by default (refer to Figure 7.1). You may see the option Reorder the tasks only when there are multiple tasks in the agent:

Specify an event condition: This is the first step where you should define the event condition in the Specify an event condition pane. The two tabs, Detail and Summary, enable you do define query expressions that should work on individual rows that satisfy the event condition (Detail), whereas you can use the Summary tab to specify a query expression that should work on the summaries. Add a task: This option enables you to define tasks that should be executed if the event condition is met. You can define one or more tasks. This option has the following suboptions: for example, Send an email, Publish a news item, Run a report, Run a job, Run an agent, Run an approval request, Run a notification request, Advanced > Database Update, Web Service, Export, Import, Index Update, Content Maintenance Task, Metric Task, Migration Task. Each of these is discussed in the later section "Create Tasks." Manage the task execution rules: This option enables you to specify when the tasks should be executed, for example, the first time the event condition is met, always, or when the event ceases to occur. Each of the options is discussed in detail in the section, "Manage Event Studio High-Level Tasks." Schedule the agent: This option enables you to define a schedule for the agent, for example, the frequency, date, time, and so on. This option is discussed in detail in the section "Manage Event Studio High-Level Tasks." Reorder the tasks: This option is context-sensitive and is available only when there are multiple tasks in the agent. It enables you to modify the sequence in which the tasks should be executed. You can change the sequence using the Up, Down, To top, To bottom links in the Reorder the tasks window. The order you specify is applicable only when you have chosen the Submission of tasks option as In sequence instead of All at once.

Insertable Objects: An area that has everything you need to build the agent. It has six tabs:

Source tab: Contains all the items in the currently selected package that you can use to build the event condition, tasks, and so on.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

Data Items tab: Has items currently used by the agent. You can add data items from the Source tab to the Data Items tab by right-clicking the data item in the Source tab and selecting Insert as Data Item. If you created any calculations, they also display in this tab. Functions tab: Contains the supported mathematical functions, operators, and summary functions that you can use to build the event condition, for example, total, maximum, and running-total. If you are familiar with Report Studio, it is similar to the Functions tab in Report Studio. When working with the Functions tab, you notice an Information area with two tabs: Tips and Errors. The Tips tab displays the syntax and how to use the function, whereas the Errors tab displays any errors or No Errors after you validate the expression. Parameters tab: Contains all the parameters you created. It will be empty if you have not defined any parameter to use in the event condition. Run history items tab: Displays the list of items that you can specify when you add an on-error task to an agent. Member Search Results option: Displays the search results.

Summary: This area provides you the summary of the event condition and all the tasks defined in the agent. Content: This area provides the pages and dialogs used to create and manage agents.

Application Menu The Application menu (refer to Figure 7.1) contains options that you can perform to create and manage agents, events, and tasks, as described in the following sections.
File Option

The File option in the application bar has five different options. Create a new agent (New), open an existing agent (Open), save the currently opened agent (Save), save the currently opened agent with a new name (Save As ), exit Event Studio (Exit).
Edit Option

The Edit option in the application bar has six different options. Undo a change with Undo, if you undid a change and would like to revert it use Redo; to remove an item from its current location and put it in the clipboard, use Cut; to copy an item and put it in the clipboard use Copy; to paste the copied item from the clipboard use Paste; and to remove an item use Delete.
View Option

View has one option, Tasks and Objects. Use this option to hide the left pane (with I want to and Insertable Objects) and view only the Events and Tasks pane.
Insert Option

The Insert option in the application bar enables you to insert a Task, Calculation, Parameter, As Data Item, In Task As Data Item, and Previous value.
n

Task option: Enables you to add one or more of the tasks listed for this option for the agent to run. You can choose one or more tasks from here and specify the sequence in which they should be executed that is, in sequence or all in parallel. The interface for each task is different depending on what needs to be done and information you need to specify:

Email task enables you to send emails optionally attaching the Activity list and a report with details on the event condition for recipients to review. You can specify users in the TO list, CC list, and BCC list as required. News Item task can be used to publish news on the event condition on a portal. Report task is used to specify the report to be run when the event condition happens. This is a good option as you can then send the report with latest data as the event occurs. Also, because the report is run only when the event happens rather than at scheduled times, it helps improve system performance. Job task can be used to put one or more related tasks together in one job and run the job as required. It is also

IBMCognosBusinessIntelligencev10:TheCompleteGuide

common to create a job consisting of tasks with the same run schedule.

Agent task enables you to run an agent. Approval Request task enables you to send a request for approval via email to the person or persons identified in the email list. Notification Request task is used to send a notification request via email to the person or persons in the email list.

Advanced option: Contains a list of tasks used to perform administrative functions in the IBM Cognos BI environment. The options available are Database Update that enables you to update the database via database procedures when certain event conditions happen. The Web Service task enables you to invoke a web service that integrates with other applications when the event condition occurs. The Export task is used to export Cognos content. The Import task is used to import Cognos content. The Index Update task enables you to update the indexes used by the IBM Cognos Search feature. The Content Maintenance Task is used to run Content Maintenance tasks created in IBM Cognos Connection that searches the Content Store to check for users that do not exist in the external namespaces and fixes it by deleting them from the Content Store. The Metric Task is applicable if you use IBM Cognos Metric Studio and want to run tasks available in a Metric package, for example, import data from files into staging area. The Migration Task can be used to add tasks to the agent that has already been defined in IBM Cognos Administration to Migrate IBM Cognos Series 7 PowerPlay content to IBM Cognos PowerPlay. Calculation option: Enables you to create a calculation using data items available in the Source tab that you can use in the event condition. Parameter option: Enables you to create a parameter that you can use in the event condition. As Data Item: Enables you to add a data item from the Source tab to the Data Item tab. You can also select the item in the Source tab > right-click and select Insert as Data Item to accomplish the same. In Task as Data Item: Enables you to add the selected data item to the task. Previous Value option: Enables you to insert a previously used value for the data item in the task page. It is used to tell the agent that you want to use the value the item had when the agent ran the previous time.

Actions Option

The Actions option in the Application menu has the following options (some of which are also available to you on the toolbar):
n

Specify Event Condition: Described in detail later in the section "Event Studio High-Level Tasks." Manage Task Execution Rules: Described in detail later in the section "Event Studio High-Level Tasks." Remove Task Execution Rules: Enables you to reset execution rules for all the tasks in the agent to the default values so that going forward each task will be performed for all new instances and ongoing instances of the event. Edit Definition: Enables you to modify the definition of a data item or a parameter. Schedule: Enables you to schedule the agent to run at a specified time without running it manually, discussed in later in the section "Schedule the Agent." Validate: Enables you to ensure that there are no errors in the expression. Validate provides details on errors or warning on the Error tab that you can use to troubleshoot the issue. Preview: Displays the event list with sample data for items currently on the Data Items tab. For troubleshooting purposes you can add additional items from the Source tab to the Data Items tab. Preview All: Enables you to preview the output of each event instance without running the agent. Count Events: Enables you to count the number of event instances. Set Default Options for All Tasks: Enables you to define default options for all tasks in the agent. The agent will then use the same value for all the report task options and content maintenance options.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

Reset Event List: Enables you to clear the past run history from the event list for the agent. This is helpful when you want to ensure that the next agent run assigns every event a status of New. You may also want to clear old events instances from the event list for event conditions that have been modified to allow the next occurrence of the instance to be treated as new. Manage Alert List: Enables you to permit users to add their email addresses to the agent alert list. Email address from the alert list is added to the Bcc option of the email when the agent runs an email task or report task.

Help Option

Help enables you to get additional help via the Event Studio User Guide and has six different options, including Help:
n

Contents: Use this option to access Event Studio product documentation for additional help. Quick Tour: Use this option to get a quick tour of IBM Cognos Connection, IBM Cognos Query Studio, IBM Cognos Report Studio, IBM Cognos Analysis Studio, and IBM Cognos Event Studio, in versions prior to Cognos BI v10.2. Getting Started: Use this option to access the document that provides information on IBM Cognos BI. IBM Cognos on the Web: Use this option to go to the IBM website. About IBM Cognos Event Studio: Use this option to verify information like the version of Event Studio you use.

Toolbar Options The Toolbar contains icons for easy access for frequently performed actions. Some of these options are also available via the application menu and are discussed there. For New, Open, Save, Save As, Cut, Copy, Paste, Delete, Undo, Redo, New Calculation, and New Parameter, refer to the section "Application Menu." To ensure an agent/expression is error free, use the Validate option before you run the agent. Using the Validate option ensures that the query expression in the event condition is valid, parameters (if used) are satisfied correctly, and all data items used in the expression are valid. The Preview option has three suboptions:
n

Preview: Enables you to preview the output of the agent based on current data to ensure that the event condition is correct, without running the agent. Preview All: Displays the event list of all the tasks in the agent and output of each task in the agent, which you can use to decide whether to run the agent yet. Count Events: Determines the number of event instances.

The Insert Task option lists all the different types of tasks you can include in the agent, for example Email, News Item, Report, Job, Agent, Approval Request, Notification Request, Advanced (which has further suboptions used for administrative tasks: Database Update, Web Service, Export, Import, Index Update, Content Maintenance Task, Metric Task, and Migration Task). These options were discussed previously in the "Application Menu" section. Event Studio High-Level Tasks This section discusses the different tasks and their sequence that must be followed if you want to set up alerts using Event Studio. Figure 7.2 shows the process flow for defining tasks in Event Studio.

Figure 7.2: Event Studio process flow. You must first determine the business scenarios that require monitoring and then define exception rules that should trigger the alert. The Event Studio process flow (refer to Figure 7.2) is as follows:

IBMCognosBusinessIntelligencev10:TheCompleteGuide

1. Define Event Condition to Monitor: To proactively monitor a business event/condition, you can create agents. An agent consists of the task(s) and event condition(s). The event condition here refers to the exception condition that the agent should monitor. 2. Add Task(s) to Agent: Depending upon how you want to handle the business condition or event when it happens, you should determine the task(s) the Agent should execute. You must then create these task(s) for the agent to perform. By default, all tasks are performed at the same time, in parallel. You can modify the tasks to run sequentially, if required. 3. Manage Task Execution Rules: Specify if you want to track new events, ongoing events, and so on. You can define task execution rules for each task in the agent. For example, you may have a task that runs the report the first time the event condition is detected. This task can have an associated rule of New. You may have another task (in the same agent) to send email, with an associated rule that it should keep sending emails until the issue has been completely addressed (Ongoing). Each of these options is discussed in further detail later in this section. 4. Run/Schedule the Agent: Run the Agent as required or schedule it to run at a specific time/interval to detect if the event condition is met. Define Event Condition You specify the event condition in the I want to area discussed earlier. The event condition is a business condition that needs to be monitored. Event Studio monitors these events via the agent. So you need to create an event condition that tells the agent how to determine that the event has occurred. The event condition is typically a query expression, similar to an expression you create to define a filter in Report Studio. You can create this expression using data items from the package or use parameters and calculations for the agent. If the expression is already used in Report Studio, you can simply copy/paste the query expression from there into the event condition in Event Studio. Also similar to Report Studio, when you add a data item to the report from the Source tab, the data item then also appears in the Data Items tab; likewise, when you add a data item from the package in the Source tab to the event condition then that data item appears in the Data Items tab. You can also right-click and use Insert a data item from the Source tab and directly add it to the Data Items tab in Event Studio. After you create the event condition, you can preview to check if there is any data currently in the database that satisfies the event condition. Use the Preview option to display the data that satisfies the event condition as a list report. The report displays each row in the database that satisfies the event condition. To create a parameter, perform the following steps: 1. In Cognos Connection, click Launch > Event Studio. 2. Select GO Data Warehouse (query) package. 3. Click Insert menu > Parameter. 4. In the Define the parameter window > Parameter name box > type a name for the parameter, for example Returns_ProductLine. 5. Click OK. 6. Select the Parameters tab on the Insertable Objects pane; the parameter Returns_ProductLine should be listed here. 7. Click Save, and provide a name, for example, Returns by Product Line. To create a calculation, perform the following steps: 1. If not already open, in Cognos Connection > select Returns by Product Line > in the Actions column, click Open with Event Studio. 2. Click the Insert menu > choose Calculation. 3. In the Define the data item window > Name box > type a name for the calculation, for example, Total_Returns_ProductLine. 4. In the Expression box, build your calculation by dragging and dropping items from the Insertable Objects pane,

IBMCognosBusinessIntelligencev10:TheCompleteGuide

such as the Source tab, Functions, Parameters, and so on as required. 5. Navigate to the Insertable Objects pane > click the Functions tab > expand Summaries folder > drag and drop total. 6. Navigate to the Source tab > expand GO Data Warehouse (query) > Sales and Marketing (query) > Returned items (query) > Returned items fact > drag and drop Return quantity to the Expression window. 7. At the end of the expression, insert a blank space and type for Expand Products > drag and drop Product line to the end of the expression Type). Your expression should look like this: total([Returned items (query)].[Returned items fact].[Return quantity] for [Returned items (query)].[Products].[Product line]) NoteUse the information in the Information Tip tab to get help with the syntax. 8. Click Validate (tick mark on top right) to validate the expression. 9. In the Information box, review the message. No Errors means the query expression is correct; otherwise, troubleshoot and fix the errors listed on the Errors tab. 10. Click Save to save the agent. Specify an Event Condition When creating the agent, the first step is to specify an event condition. You can define the event condition in the I want to area. Figure 7.3 shows an event condition using a parameter and calculation you created in the previous exercise.

Figure 7.3: Specify an event condition. To define an event condition, perform the following steps: 1. If not already open, open the agent Returns by Product Line. 2. In the Specify an event condition section, click the Detail tab. 3. Using data items from the Insertable Objects pane, select the Source tab, Functions, Parameters, and so on to build the query expression that defines the business event condition you want to monitor. In the Insertable Objects pane > Data Items tab > click Return quantity > click the Insert button. This adds it to the Expression box. 4. In the Expression window, at the end of the expression type > 0 and

IBMCognosBusinessIntelligencev10:TheCompleteGuide

5. From the Data Items tab > drag and drop Total_Returns_ProductLine to the end of the expression > type a space and an angle bracket (>) 6. Navigate to the Parameters tab > drag and drop Returns_ProductLine to the end of the expression > type and 7. Navigate to the Source tab > expand Returned items (query) > Return reason > drag and drop Reason description to the end of the expression > type a blank space > type in > click the Select Values icon (on top right of the Expression box). 8. From the Select Value window, Ctrl+click Incomplete product and Defective product > click the right green arrow. 9. Click OK. NoteYour expression should look like this: [Return quantity] > 0 and [Total_Returns_ProductLine] > ?Returns_ProductLine? and [Reason description] in(('Defective product','Incomplete product') 10. Click Validate to ensure the expression has no errors. 11. From the Actions menu > Preview to ensure the data in the list is correct. 12. Provide a value in the Provide a number box. 13. Click OK. Create an Event Condition for a Cell or Intersect in a PowerPlay Cube You can also create an event condition in a PowerPlay cube. This enables you monitor the data and proactively respond when an event condition is met. As discussed earlier, to monitor an event condition, you must create an agent, which you can either run manually or schedule to run it at regular intervals. To use OLAP or dimensionally modeled data to create an event condition, follow these steps: 1. In Cognos Connection, select Launch > Event Studio. 2. Navigate to Public Folders, in the Cognos samples folder > select Sales and Marketing (cube), when prompted to select a package. 3. In the I want to pane, select Specify an event condition. 4. In the Detail tab > Expression area, type value(tuple( NoteYou can use the Functions tab > Dimensional Functions folder > expand folder RZ > select tuple from the list to add to the expression. 5. In the Insertable Objects pane, navigate to Products dimension > Products > Members folder. 6. Expand Products member > select Personal Accessories. 7. Drag the Personal Accessories member or click the Insert button (the green arrow beside the Expression area). The expression should look like this: value(tuple([Personal Accessories] 8. At the end of the expression, type a comma (after the member reference). 9. In the Insertable Objects pane, navigate to Order method dimension > Order method > Members folder > drag and drop Web to the end of the expression. 10. At the end of the expression, type a comma (after the member reference). 11. In the Insertable Objects pane, navigate to the Measures folder > drag and drop Quantity to the end of the expression.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

12. At the end of the expression, type)) NoteThe final Result should look like this: value(tuple([Personal Accessories],[Web],[Quantity])) 13. At the end of the expression, add the condition > 50000. 14. Click the Actions menu > select Preview or click the Preview icon on the toolbar, to ensure the condition is defined correctly and the data displayed in Cognos Viewer is valid. 15. Click File menu > Save to save the agent. Result: value(tuple([Personal Accessories],[Web],[Quantity])) > 50000 16. Press the Play button to preview the results of the condition. NoteIf you validate the expression, a warning message may display regarding filters on aggregated values. This warning is intended for relational sources only, not dimensionally modeled or OLAP sources. Running Preview confirms that the condition works. If required, you can add tasks, such as sending an email when this condition is detected in the cube. Tasks will be triggered as soon as the condition is true. Refining when to respond to this condition, such as "respond only after the condition is detected three times in one week," can be defined in the Task Execution Rules. Create Tasks Depending upon your requirement, you can create tasks that fulfills your monitoring and notification needs. Tasks can be created from the I want to area. From here you can also reorder the task sequence of the already created tasks, if required. You can choose to run the tasks you create in a sequence or run them all at once (default) if that fits your requirement. If the tasks logically depend on the output of another task, then you should run them in sequence; however, if all the tasks are independent of each other and the output of one task does not impact the output of the other tasks, you can choose to run them all at once. You can add any of the following tasks to the agent:
n

Send Email: Use to send an email to a group of people or stakeholders who need to be notified when the event occurs. You can optionally attach a report to the email that provides the details on the event allowing them to respond to it immediately. Add task: Using this option, you can create as many tasks as you need. Figure 7.4 demonstrates two tasks created so far: one to run the report and the second to send email. Notice that there are links that enable you to attach the report to the email being sent to the recipient. Use the Select recipient link to add users from the authentication source.

Figure 7.4: Create a task to send email.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

Publish a news item: Use to publish a notification headline to a folder that can be viewed in the Cognos Navigator (see Figure 7.5).

Figure 7.5: Create a task to Publish News Item.

n

Run a report: Use to run a report that can provide additional information on the event condition. Doing this enables you to provide current information in the report by running it when required (see Figure 7.6).

Figure 7.6: Create a task to Run Report.

n

Run a job: Use when multiple tasks need to be run together at the same schedule. The job can contain one or more reports, other jobs, agents, report views, and so on. Run an agent: Use to run another agent; you can then use the output of that agent as the input to this agent or multiple agents that work with different data sources. Run an approval request: Use when you want a subsequent task to occur only after approval has been received. When this task is run, it sends an approval request to the Inbox in the IBM Cognos BI environment of the recipients listed in the approval request. You can identify the recipient as a Potential Owner or Stakeholder. You can list individual users, groups, or roles as Potential Owners. A Potential Owner cannot be identified as a Stakeholder also. If you want to track the progress of an approval task you create, you can add yourself as a Stakeholder. The task owner must approve or reject the task before it can get to the status of Complete. If more than one task owner is specified, only one out of the group needs to approve or reject the task. If a response is required from multiple task owners, a task must be specified for each owner. NoteWhen you add an approval request, the task execution is automatically set to sequential.

Run a notification request: Use this option to add tasks to the agent that sends secure notification about the event to the Inbox of recipients specified. You can also include a report output in the notification that provides the recipients with background or supporting information about the event.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

To track the progress of notification tasks you create, add yourself as the Stakeholder.
Steps to Create a Task

You now create a task that allows you to run a report. Using this, you can select the report output formats, specify prompt values, and so on. Follow these steps: 1. In Cognos Connection, click Launch > select Event Studio. 2. Select Sales and Marketing (query) package. 3. In the I want to area, click Add a task. 4. Click Run a report. 5. In the Specify the report to run section > Report section > click Select the report link > navigate to the folder that contains the report you want to run in IBM Cognos Connection, for example, Public Folders > SampleOutdoorReports > Returned Products by Order Method. 6. Click OK. 7. In the Specify the report to run section > Options section > click on the Set link. 8. In the Select the report options window, specify the run options appropriate for you > select the check box for Override the default values. 9. In the Select the report options window > Format section > select the report formats required, for example PDF, HTML(default), and CSV. 10. In the Select the report options window > Delivery > select check box for Save (if not already selected) > select Save the report radio button (if not already selected). 11. Click OK. 12. Optionally, if applicable in your situation, select Prompt values > Method column > click Use an item > drag and drop the item (that is required in your situation) from the Source tab to the Value box. 13. Click Save. You can use Event Studio to distribute the reports using the Burst option. The following example walks you through the steps.
Combining Burst Reports into a Single Email by Recipient

When a single burst report is run, the various outputs are emailed to their respective recipients; however, this might result in some users receiving multiple emails, each containing a single report. Instead of users receiving multiple reports in separate emails, you can collect the outputs of all these reports and send them together in a single email by running them in Event Studio Agent. An alternative to running multiple reports in a job is to include them in an Event Studio agent. An agent can contain multiple report tasks, each running a single report. You can also create an email task and attach the results of the various report tasks to the email. And you can address an email dynamically by dragging a data item containing an email address to the Recipient fieldwhich causes an email to be sent to each person in the list. By combining all these features, you can send one email to each person containing the burst outputs of multiple reports. You will now create a task that runs the report and distributes it to other users via email. You can distribute reports to users via the burst option. To burst the report you must enable it by selecting the check box Burst the reports in the Bursting section, as shown in Figure 7.7.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

Figure 7.7: Distribute Reports with the Burst option. To create a task that runs the report and distributes it to other users via the email option, follow these steps: 1. In the I want to area, click Add a task > select Run a report. 2. In Specify the report to run > Report section > click the Select the report link. 3. In the Select the report window, locate the report that you want to run > click OK. 4. In the Specify the report to run section > Options section > click Set link. 5. In the Select the report options window, select the check box for Override the default values. 6. In the Select the report options window > Bursting section > select the check box for Burst the reports. NoteDo not select Send the report by email. (This will be accomplished by the email task.) 7. Click OK. 8. Repeat from step 2 to create more report tasks to set the options for each of the reports that you need to run.
Steps to Add Email Task

Next, you add a task to the agent that sends email to the users. You can send email to users who exist in the authentication source or users whose email addresses are available as a data item in the package. When you have multiple tasks defined in the agent, you can specify the order in which they should be executed. Also, ensure that the In sequence option is selected when you want the tasks to be executed in a sequence. Because you want to first run the report and then email the report output, you must ensure that the In sequence option is selected. 1. In the I want to area, click Add a task > select Send an email. NoteIf there is an entry in the To: field, delete it. 2. Navigate to the Insertable Objects pane > drag and drop the data item that represents the email address of the recipients to the To: field of the email. NoteThis is the same data item used to define the recipients key in the Burst Options in the report.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

3. In the Subject section, type the subject of the email. NoteYou can add data items to the subject line to display values dynamically by utilizing data from the package. 4. Click the Attach drop-down (bottom right of the screen) > locate the output of each report to attach to the email. 5. Click I want to area > click the Reorder the tasks link > if not already selected, select In sequence > ensure the tasks are listed in the correct sequence > click OK. 6. Save the agent.
Automatically Distribute Reports Using Approval Request Task

As the manager of the Sample Outdoor Company, you are required to approve the accuracy of a report before it is distributed to the sales representatives. You can add an approval request task by creating it directly from My Inbox. However, you want the report to be distributed automatically when you, as the manager, approve the report. Figure 7.8 shows options available to you when creating an approval task.

Figure 7.8: Create a task to run an approval request. To create an approval request task, perform the following steps: 1. In Cognos Connection, click Launch > Event Studio. 2. Select GO Sales(query) package. 3. In the I want to area, click Run an approval request. 4. Navigate to the Source tab > Sales (query) > Sales Staff. 5. Drag and drop Manager Email to the Potential owners box. NoteYou are automatically added as a stakeholder of the task. 6. In the Subject box, type Product Forecast Report for Approval. 7. In the Body box, type Please approve or reject the content of the attached report. If you approve this report it will be distributed to. 8. Add the email distribution list for the sales representatives to the message, navigate to the Source tab > Sales (query) > Sales Staff > drag and drop Email to the end of the message. 9. Save the agent.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

10. In the I want to area > click Add a Task > Send an email. 11. Navigate to the Source tab > Sales (query) > Sales staff > drag and drop the Email data item to the To box. 12. In the Subject line > type Please take immediate action. 13. In the Body > type Please submit your findings prior to next monthly board meeting. Thanks! 14. Click Add links > locate Product Forecast and Revenue by Products (or another report in your environment to test) > select the report(s) via check boxe(s) > click the right green arrow to complete the selection > click OK. 15. Save the agent. After the agent runs, a task is created within My Inbox in IBMCognosBusiness Intelligence, and notifications are sent via email to the potential owner and stakeholder identified for the task. To have the report automatically distributed if the report is approved by the manager, add a second task for run a report. Manage Task Execution Rules Event Studio compares the status of the Current run with the previous runs of the agent. It is important to correctly specify which event statuses should cause the agent to perform the report task. You must identify an Event Key that uniquely identifies each event instance, as shown in Figure 7.9. To define the task execution rules, you must define the event key. The event key must uniquely identify the data evaluated by the event condition, for example, the Product number.

Figure 7.9: Manage task execution rule You must also specify for each task when the task should be executed, for example, New events, Ongoing events, Ceased events, and No events, as shown in Figure 7.9. By default, each task is executed when the agent detects a new or ongoing event. You can change this behavior to suit your requirement.
n

New events option: Specifies that the task should be executed the first time only, when the agent detects the condition for the first time for an item, for example, for a product number. Ongoing events option: Use to specify that the task be executed every time the agent detects the event for a data item specified by the event key. You can also use this option to detect if a data item value has changed. Ceased events option: Use to specify that the task be executed when the event that the agent detected earlier does not meet the event condition anymore. No events option: Use to specify that the task be executed only when no events are detected by the agent.

To manage task execution rules, perform the following steps:

IBMCognosBusinessIntelligencev10:TheCompleteGuide

1. In the I want to area > click Manage task execution rules. 2. Click the Event Key tab. NoteBy default all data items are listed here. 3. Click Include only selected items. NoteRemove the data items you do not want to use as the event key. Also, depending upon your business requirement, you may have more than one data item to determine the uniqueness of the event, for example, returned data item and date returned. 4. From the Insertable Objects pane > Source tab, drag and drop the data item that uniquely identifies the event instance to the Event Key box. 5. Click the Event Selection tab. 6. In Select when to perform each task > select the ones applicable in your situation, for example, New, Ongoing, Ceased, and so on. 7. Click OK. 8. Click Save to save the agent. Preview After you add the task, you should preview the tasks to ensure the results are as expected. You can either preview individual task or all the tasks in the agent together. You can preview the tasks from the Actions menu > Preview/Preview All/Count Events. Alternatively, you can preview using the Preview option in the toolbar and choosing the appropriate value from the drop-down list:
n

Preview: Enables you to preview the result of a specific task. You must select the task you want to preview by clicking the tab for the task you want to preview, and choosing the preview option. Preview All: Enables you to preview the results of all the tasks in the agent. Count Events: Enables you to count all the instances of the event detected by the event condition. The count is determined using the current data in the database.

You can Preview the result via the Actions menu > Preview/Preview All or using the Preview icon on the toolbar, as shown in Figure 7.10.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

Figure 7.10: Preview the output and test event condition results. Validate Agent It is good practice to validate the agent after it is created to ensure that it is error free and can run successfully. You can validate the agent via the Validate icon on the Toolbar or Actions menu > Validate. Create Agent Views Agent views have similar functionality to report views. The agent view is a pointer to the agent and has the same event condition and tasks. Because each agent can have only one schedule defined, you can create agent views to define multiple schedules by creating one or more agent views depending on the schedules you need to define. Consider creating agent views when the prompt value varies, however, the event condition and tasks remain the same. If the agent is located in a folder, you do not have write access to, you can create the agent view in My Folders and use the agent. Similar to report views, when you modify the parent or original agent on which the view is based, the changes are automatically reflected in all the views of that agent. Also, if you delete the parent, that is original agent on whom the view is based, the agent view icon appears broken indicating it cannot be run anymore. You require Read or Execute permission on the agent to create a view for that agent. Steps to Create Agent Views To create an agent view, perform the following steps: 1. In IBM Cognos Connection, in the Actions column for the agent, click the icon for Create an agent view of this agent icon (blue color box). 2. In the Specify a name and description New Agent View wizard window > type a name for the agent view, for example, Returns By Product Line Monthly. 3. Optionally, type a Description and Screen tip. 4. In the Location section, select a location, for example, Public Folders > SampleOutdoors > SampleOutdoorEvents. 5. Click Finish. NoteYou can now define a schedule for the Agent view that is different from the original agent view schedule.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

Alternatively, you can also create Agent Views from the Actions column > More link > Create an agent view of this agent link. Manually Run Agent After the agent is created, it appears in the IBM Cognos Connection along with the other Cognos content. You can run the agent manually via the Run option in the Actions column. To run the agent, you require the Execute permission for the agent and Traverse permission on the parent object (that is, the folder where it is located). To manually run the agent, perform the steps outlined in Figure 7.11 and described in the list that follows.

Figure 7.11: Event Studio Agent in Cognos Connection. 1. In IBM Cognos Connection locate the Agent you want to work with > from the Actions column for the Agent > click Run With Options (the blue triangle). 2. For Time click Now to run it immediately or Later to run it later, and specify the date/time when it should run, as shown in Figure 7.11. 3. To allow users to specify values for which the agent should run, select the check box for Prompt Values > Prompt for values. 4. Click Run. 5. If you checked the Prompt for values (in step 3), provide an appropriate value for the prompt, as shown in Figure 7.12. 6. Click OK. Figure 7.12 shows how you can check the status of the agents if they successfully completed or not via the View run history.

Figure 7.12: Manually run the agent via Run with Options. Bringing It All Together This section uses the techniques used in this chapter. Create an Event Condition for a Cell in a PowerPlay Cube You can specify an event condition based on a cell value in an IBM Cognos PowerPlay cube. This functionality is similar to what you have seen so far. Figure 7.13 shows how to set up an event condition on a cell in a PowerPlay cube, and the steps that follow explain the procedure in more detail.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

Figure 7.13: Specify event condition using a PowerPlay cube. 1. In Cognos Connection, click Launch > Event Studio. 2. From the Select a package window, select the Sales and Marketing (cube). 3. Select Specify an Event Condition. 4. Click Insert menu > Calculation. 5. Specify the name for the calculation > type PersonalProductsQuantityOrdered ByWeb. 6. In the Expression area, type value(tuple( 7. In the Insertable Objects pane, navigate to Products dimension > Products > Members folder > Product. 8. Drag and drop Personal Accessories to the end of the expression in the Expression box. 9. Type a comma at the end of the expression. 10. In the Insertable Objects pane, navigate to Order method dimension > Order method hierarchy > Order method level > Members folder > Order method. 11. Drag and drop Web to the end of the expression. 12. Type a comma after the member reference, at the end of the expression. 13. In the Insertable Objects pane, navigate to the Measures folder. 14. Drag and drop Quantity at the end of the expression. 15. Type )) to complete the expression. NoteYour final result should look similar to this: value(tuple([sales_and_marketing].[Products].[Products]. [Product line]->:[PC].[@MEMBER].[993],[sales_and_marketing]. [Order method].[Order method].[Order method type]->:[PC]. [@MEMBER].[605],[sales_and_marketing].[MEASURES].[Quantity]))

IBMCognosBusinessIntelligencev10:TheCompleteGuide

16. Click the Validate icon (green tick on the top right of the expression window). 17. Ensure the Information pane shows No Errors. NoteIf errors are encountered you must troubleshoot the errors and validate again to resolve issues. 18. Click OK. 19. Click the Actions menu > Specify Event Condition. 20. In the Insertable Objects pane, navigate to the Data Items tab. 21. Drag and drop PersonalProductsQuantityOrderedByWeb to the Expression window. 22. At the end of the Expression, type > 50000. 23. Click the Actions menu > Preview, to display rows that satisfy the condition. NoteIf there are rows that satisfy the expression in the Expression box, it will be displayed in Cognos Viewer. 24. Click Insert menu > Tasks > Email, to create a task that sends email notifications as shown in Figure 7.14.

Figure 7.14: Send email with dynamically changing data. 25. Click the Select the recipients link to assign recipients. 26. From the Select recipients window, navigate to the namespace that has users listed, for example, Directory > SampleOutdoor, to select the recipients or select users from the authentication source in your environment. NoteFor help on how to assign recipients, refer to Chapter 12, "Securing IBM Cognos BI Environment and Its Objects." 27. In the Subject box, type PPES Cell Notification Personal Accessories Ordered via Web exceeded 50000. 28. In the Body, type Personal Accessories order via Web exceeded 50000! 29. To display the total ordered amount for reference, type Total quantity ordered via Web is. 30. From the Data Items tab, drag and drop PersonalProductsQuantityOrderedByWeb to the end of the statement. 31. Click Actions menu > Preview to display the result.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

32. Click Manage task execution rules link > uncheck the option Ongoing events > click OK. 33. Click File > Save to save the Agent, type in SampleOutdoorPersonalAccessories Target. 34. You can also schedule and specify the frequency at which it should be executed. Schedule the Agent If you do not want to run the agent manually, you can schedule the agent to run at a later time or at intervals you require. There can be only one schedule per agent. If you require multiple schedules to be defined for the same agent, you must create a view of the agent (one for each schedule required) and specify the schedule for it individually. Schedules for agents can be created similar to any other schedule you create in IBM Cognos via IBM Cognos Connection or via the Schedule the agent link in the I want to option in Event Studio. Figure 7.15 shows the options available to define the schedule frequency.

Figure 7.15: Specify frequency for the agent. The schedule window enables you to define the frequency as By Day, By Week, By Month, By Year, and By Trigger. You can also specify the Start and End date/time. If you want the agent to run without an end date, you can choose No end date option. To prompt the user for a value, you must check the Override the default values check box. If the agent contains parameter, you must provide a value for the agent to run successfully. Steps to Schedule an Agent To schedule an agent, perform the following steps: 1. In the I want to area, click Schedule the agent. 2. Specify the Frequency, as appropriate. 3. Specify the start date and time when you want the schedule to start via the Start option. 4. Specify the end date and time when you want the schedule for the agent to stop via the End option. NoteIf you do not specify any value for the End date/time, it will be ongoing until you specify one. 5. If the agent has required parameters, in the Prompt values section, select the check box for Override the default values to override the default agent prompt settings. 6. Click OK. For additional information on scheduling, refer to Chapter 3, "Explore IBM Cognos Connection." Monitor Agent Status

IBMCognosBusinessIntelligencev10:TheCompleteGuide

Similar to the way to monitor the status of a report you ran, you can monitor the run status of an agent by performing the following steps: 1. Click the More link in IBM Cognos Connection for the agent. 2. Click View run history link. NoteExamine the Start time, Completion time, and the run Status of the agent. Reset Event List You can use Reset Event List for an individual task or all tasks in the agent. After you complete your testing of the agent, you should use Reset the Event List via Actions > Reset Event List. This option is especially relevant for those tasks that are set up for new events only. These tasks will not be executed again when the event is detected because your test run results from previous runs exist in the list. It may also be meaningful that you reset the list each time to modify the event condition. Subscribe to Agent Notification Lists If you want to be notified each time the agent runs, you can subscribe to the agent. Subscribing to the agent adds you to the agent notification list enabling you to receive emails each time the agent is run. To subscribe to the agent, it must first be enabled via the Allow users to subscribe to the notification list check box. After this property is enabled, users with appropriate permission, for example, Read, Traverse can subscribe to the agent via the Actions > More > Add me to the notification list link in IBM Cognos Connection or via the Actions menu > Manage the notification list > Allow users to subscribe to the notification list check box in Event Studio. Set Permissions on Agents You can set permissions on agents the same way you set permissions for any other object in IBM Cognos Connection. You can set permission on the agent in IBM Cognos Connection Actions > Properties > Permissions. You can use the users, groups, and roles used to secure other Cognos content or create new ones if required. You must ensure that the user/group/role has Execute permission for the agent and Traverse for the folder/subfolder it is located in. In a Nutshell: Reviewing by IBM Cognos BI Audience Depending on your role in IBM Cognos BI project implementation, you may be interested to know those aspects of using IBM Cognos Event Studio that relate to your role on the project. The following points review the IBM Cognos Event Studio by role at a high level. Architect Perspective Architects are interested in knowing about the capabilities of the product so that they can appropriately recommend a tool/component for the overall BI implementation. Event Studio is a core component of IBM Cognos BI and is installed with the Cognos BI install. Event Studio is geared more for authors or IBM Cognos BI Administrators who are responsible for creating agents, defining the tasks, scheduling, and executing them. It uses the existing IBM Cognos BI security and needs to interact with the mail server to send email alerts to stakeholders when the exception business conditions are met. Some of the points that you may want addressed early are:
n

Event Studio in IBM Cognos v10.x has enhanced event management capabilities and uses the new Human Task service for process management tasks like approval and rejection of tasks defined for each event condition. Event Studio enables attaching reports to the emails that can be sent to the stakeholders. It is recommended that these users be defined in the authentication source that the IBM Cognos BI environment is attached to. It is worth finding out upfront the maximum number of users in the distribution list at any point because this information may reveal any additional steps you need to take care of to ensure enough licenses exist to cater to this need. Event Studio agents can be created by the Cognos developer and can be either scheduled to be run at a later time or can be run manually as required. The IBM Cognos BI Administrator must ensure required permissions exist on the agents for end users to access it and run it.

IBMCognosBusinessIntelligencev10:TheCompleteGuide

Project Manager Perspective Project Managers are interested in knowing if Event Studio has been identified and recommended as part of the IBM Cognos BI solution. If it will be used, what are the related tasks, skills, and resources required to implement the tasks and what phase do these belong to? Here are some points to consider:
n

Event Studio is a good fit for customers who proactively monitor business events that require immediate action as they happen. Event Studio enables defining such business conditions and associated tasks that must be executed when they happen, for example, send email alerts, publish news item to the portal, and include process management around these events by adding approval and rejection of steps where required. Event Studio tasks are performed by a Cognos developer with knowledge of Event Studio. That said, it has an easy-touse interface enabling developers to use it easily. Event Studio is a core component of IBM Cognos BI and is installed when the IBM Cognos BI server is installed. Because Event Studio enables users to send email alerts to stakeholders about business events monitored, when they happen, it is a good idea to get an understanding of the number of users in the distribution list to ensure that appropriate licenses exist to support the same. Event Studio uses the metadata available in the IBM Cognos BI environment, and developers can start working on them as soon as the Framework Manager package is published by the IBM Cognos Metadata Modeler.

Business Analyst Perspective Business Analysts should be familiar with the features of Event Studio so that they can guide the end users appropriately. Event Studio is a good fit for users who need to proactively monitor business events such as service-level agreements and respond to them immediately as they happen. It can also be considered when you need to include an approval process into the event management process. For example, if it is determined that an SLA metric did not make its target, and although someone needs to act upon it, it requires prior approval of the manager and stakeholders prior to taking action. You can add tasks that attach a detail report highlighting the issue to the email automatically sent to the appropriate person authorized to approve the action before it is acted upon. When it is approved, the person to act on it can automatically be notified of the approval or rejection so that they know how to proceed. Some of the key requirements to gather are
n

During the requirements gathering process, you should identify any business scenario that is a good fit for Event Studio. If Event Studio has been identified as part of the IBM Cognos BI implementation, carefully capture the business condition and the tasks that need to be executed when the event happens, the sequence in which they should happen, or all together at the same time. Along with the business event that needs to be captured, you should also identify if the event check should be scheduled to run at a certain time, that is, automated or will the users run the event check (agent in Event Studio) as required? This information enables the Cognos development team to automate the agent, if required. For events that need to be automated, you should capture the days, frequency, and time when the agent should be run. The other piece of information relevant to find out from the end users is who needs to be notified when the event occurs. It is common that there is a person who needs to take action or approve the action, and others should be notified to make them aware that the event has occurred. Although they do not need to take any action, for example, the email TO list and CC List. After this requirement has been captured, share it with the BI Architect, Cognos developer, and IBM Cognos BI Administrator. The Cognos developer can ensure these people are in the list while the BI Architect/Cognos BI Administrator can work with the Project Manager to ensure that everyone to be notified can be catered to using the existing licenses. The Event Conditions you capture is key information for the metadata modeler and Cognos developer to ensure that all the required information is captured and available in the IBM Cognos Framework Manager package to build the event condition, tasks, and agent in Event Studio. Event Studio supports working with calculated values based on existing metadata.

Developer Perspective Developers here refers to the Cognos development team. As a person responsible for creating the events and automating the same, you must understand the requirement. Developers must give careful consideration to some of the points

IBMCognosBusinessIntelligencev10:TheCompleteGuide

highlighted here:
n

Ensure the metadata required to build the event condition and tasks is available in the package. Should the agent be automated or manually run by the end user or both? Ensure appropriate permissions are assigned to support this requirement. Is there a requirement for email notification and approval/rejection of tasks? The answer to this question can help you ensure that people who need to be notified exist in the authentication source and in the appropriate distribution list.

End User Perspective End Users for Event Studio are those who either run agents to check on business events, or they are responsible for the approval/rejection of tasks before the agent can complete the check. Some of the things you should think about are listed here:
n

How do I know if this is the right tool for me? If your business requires proactive monitoring of business events and immediate notification as they happen, Event Studio is the appropriate choice for you. You should consider using Event Studio in scenarios in which there is an approval/rejection process involved after a business event has been identified. Only those business events can be identified by Event Studio for which associated metadata is available. Ensure that you clearly communicate the business event to the Business Analyst during the requirements gathering phase so that the Cognos development team ensures all related information is available and captured in the BI reporting system. You have an option to automate the event condition check. For this you must provide the Business Analyst/Cognos development team all the relevant information, for example, how often the condition should be monitored, which days, and the time. Do you want the flexibility to run the event condition check anytime you want? If you want to run the event checks yourself, inform the Business Analyst. This ensures that you are granted appropriate permission to run it.

IBM Cognos BI Administrator Perspective IBM Cognos BI Administrators should work together with the team to ensure that the Cognos BI system can cater to those needs with the existing Cognos BI installation. There are many situations in which a choice must be made between easy to implement and easy to maintain. You can help the team make the right decision based on the infrastructure, unique customer situations, and culture. Some of the points worth considering are:
n

The mail server exists to support the requirements for sending emails with attachments. Users who have been identified as people to be notified via email have their information (email) in the authentication source used for IBM Cognos BI security. Users who have been identified to run agents manually have appropriate privileges to access and execute them. Does the current Cognos infrastructure support the Event Studio requirements identified for the project? Work with the team to ensure the recommended solution is viable using the current infrastructure.