Event Studio User Guide

IBM Cognos Analytics

Version 11.1

IBM

Product Information

This document applies to IBM Cognos Analytics version 11.1.0 and may also apply to subsequent releases.

Licensed Materials - Property of IBM

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with

IBM Corp.

IBM, the IBM logo and ibm.com are trademarks or registered trademarks of International Business Machines Corp.,

registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other

companies. A current list of IBM trademarks is available on the Web at " Copyright and trademark information

" at

www.ibm.com/legal/copytrade.shtml.

The following terms are trademarks or registered trademarks of other companies:

• Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe

Systems Incorporated in the United States, and/or other countries.

• Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States,

other countries, or both.

• Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel

SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in

the United States and other countries.

• Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.

• UNIX is a registered trademark of The Open Group in the United States and other countries.

• Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its afliates.

Microsoft product screen shot(s) used with permission from Microsoft.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with

IBM Corp.

Introduction

This document is intended for use with IBM

Cognos

Event Studio. Event Studio is a web-based product

for creating and managing agents that monitor data and perform tasks when the data meets predened

thresholds.

This document describes how to use Cognos Event Studio to ensure that critical information is detected

quickly and delivered to key stakeholders in your business.

Audience

To use Cognos Event Studio, you should have

• Knowledge of your business requirements.

• Knowledge of business analysis concepts.

• Knowledge of databases and data modeling concepts.

Finding information

To nd product documentation on the web, including all translated documentation, access IBM

Knowledge Center (http://www.ibm.com/support/knowledgecenter).

Accessibility features

IBM Cognos Event Studio does not currently support accessibility features that help users with a physical

disability, such as restricted mobility or limited vision, to use this product.

IBM Cognos HTML documentation has accessibility features. PDF documents are supplemental and, as

such, include no added accessibility features.

Forward-looking statements

This documentation describes the current functionality of the product. References to items that are not

currently available may be included. No implication of any future availability should be inferred. Any such

references are not a commitment, promise, or legal obligation to deliver any material, code, or

functionality. The development, release, and timing of features or functionality remain at the sole

discretion of IBM.

Samples disclaimer

The Sample Outdoors Company, Great Outdoors Company, GO Sales, any variation of the Sample

Outdoors or Great Outdoors names, and Planning Sample depict ctitious business operations with

sample data used to develop sample applications for IBM and IBM customers. These ctitious records

include sample data for sales transactions, product distribution, nance, and human resources. Any

resemblance to actual names, addresses, contact numbers, or transaction values is coincidental. Other

sample les may contain ctional data manually or machine generated, factual data compiled from

academic or public sources, or data used with permission of the copyright holder, for use as sample data

to develop sample applications. Product names referenced may be the trademarks of their respective

owners. Unauthorized duplication is prohibited.

iv IBM Cognos Analytics Version 11.1: Event Studio User Guide

Chapter 1. IBM Cognos Event Studio

Use IBM Cognos Event Studio to notify decision-makers in your organization of events as they happen, so

that they can make timely and effective decisions.

You create agents that monitor your organization's data to detect occurrences of business events. An

event is a situation that can affect the success of your business. An event is identied when specic items

in your data achieve signicant values. Specify the event condition, or a change in data, that is important

to you. When an agent detects an event, it can perform tasks, such as sending an e-mail, adding

information to the portal, and running reports.

For information about how to use Cognos Event Studio, see Chapter 2, “Creating an Agent,” on page 17.

Note: Some of the features available in Cognos Event Studio are not compatible with Firefox. For this

reason, you are recommended to use Microsoft Internet Explorer web browser.

You can follow a tutorial that shows you how to create and run an agent in response to a business

scenario. For more information, see Chapter 3, “Tutorial,” on page 41.

Source Items

IBM Cognos Event Studio works with source items that were dened in an IBM Cognos Framework

Manager model and published as a package. Source items are used to specify an event condition that is

monitored by the agent. You can also use source items to derive calculations or parameters that may be

included in the event condition.

To use Cognos Event Studio effectively, you should be familiar your organization's business and its data.

You may also need to be familiar with other components of IBM Cognos Analytics.

IBM Cognos Analytics - Reporting

IBM Cognos Analytics - Reporting is the professional reporting tool for IBM Cognos Analytics. Use it to

author more complex reports.

Reporting offers greater flexibility in calculating and formatting results. Report authors can open IBM

Cognos Query Studio reports to create more advanced reports.

Cognos Reporting gives users access to the full range of Cognos Reporting functionality. Use Cognos

Reporting to create any report type, including charts, maps, lists, and repeaters, using any data source

(relational or multi-dimensional).

IBM Cognos Workspace

IBM Cognos Workspace is a report consumption tool that provides an integrated business intelligence

experience for business users. This web-based tool allows you to use IBM Cognos content and external

data sources to build sophisticated interactive dashboards that facilitate collaborative decision making.

IBM Cognos Framework Manager

IBM Cognos Framework Manager is the data modeling tool for IBM Cognos Analytics.

The packages you use to generate reports are based on models that are created in Cognos Framework

Manager. A model is a set of related objects, such as query subjects, dimensions, lters, and calculations.

When you open a package in Cognos Analytics, these model objects are visible in the frame.

IBM Cognos Analysis Studio

IBM Cognos Analysis Studio is the analysis tool for IBM Cognos Analytics. Use it to explore, analyze, and

compare dimensional data.

Analysis Studio helps you answer business questions by nding meaningful information in large data

sources.

IBM Cognos Query Studio

IBM Cognos Query Studio is the reporting tool for creating simple queries and reports in IBM Cognos

Analytics, the web-based reporting solution. In Query Studio, you can view data, create reports, change

the appearance of reports, and work with data in a report.

Building IBM Cognos Analytics Applications

You use the IBM Cognos Analytics components to build reporting and analysis applications.

The lifetime of an Cognos Analytics application can be months, or even years. During that time, data may

change and new requirements appear. As the underlying data changes, authors must modify existing

content and develop new content. Administrators must also update models and data sources over time.

For more information about using data sources, see the IBM Cognos Analytics Administration and Security

Guide and the IBM Cognos Framework Manager User Guide.

Before you begin

In a working application, the technical and security infrastructure and the portal are in place, as well as

processes for change management, data control, and so on. For additional information, see the IBM

Cognos Solutions Implementation Methodology toolkit, which includes implementation roadmaps and

supporting documents. Information about the toolkit is available on the IBM Cognos Information Centers

(http://pic.dhe.ibm.com/infocenter/cogic/v1r0m0/index.jsp).

The following graphic provides an overview for how to use Cognos Analytics to build applications across

all of your Cognos Analytics components.

Locate and prepare

data sources and models

Build and publish

the content

Deliver the information

Procedure

1. Locate and prepare data sources and models

Cognos Analytics can report from a wide variety of data sources, both relational and dimensional.

Database connections are created in the Web administration interface, and are used for modeling, for

authoring, and for running the application.

To use data for authoring and viewing, the business intelligence studios need a subset of a model of

the metadata (called a package). The metadata may need extensive modeling in Cognos Framework

Manager.

2. Build and publish the content

Reports, scorecards, analysis, dashboards and more are created in the business intelligence studios of

Cognos Analytics. Which studio you use depends on the content, lifespan, and audience of the report,

and whether the data is modeled dimensionally or relationally. For example, self-service reporting and

analysis are done through IBM Cognos Analytics - Reporting, IBM Cognos Query Studio, and IBM

Cognos Analysis Studio, and scheduled reports are created in IBM Cognos Analytics - Reporting.

Reporting reports and scorecards are usually prepared for a wider audience, published to a portal, and

scheduled there for bursting, distribution, and so on. You can also use Cognos Reporting to prepare

templates for self-service reporting.

3. Deliver and view the information

IBM Cognos Analytics Version 11.1: Event Studio User Guide

You deliver content from the IBM Cognos portal or other supported portals, and view information that

has been saved to portals, or delivered by other mechanisms. You can also run reports, analyses,

scorecards, and more from within the business intelligence studio in which they were created.

For information about tuning and performance, see the IBM Cognos Analytics Administration and

Security Guide and the IBM Cognos Information Centers (http://pic.dhe.ibm.com/infocenter/cogic/

v1r0m0/index.jsp).

The IBM Cognos Event Studio Window

Use the IBM Cognos Event Studio window to interactively create and manage agents.

The Cognos Event Studio window is made up of four areas:

• the I want to area

This area shows the main tasks that you perform when you create an agent.

• the Insertable Objects area

This area shows available source items, data items used by the current agent, functions you can insert

in the event condition, and parameters you created.

• the summary area

This area contains tabs with summary descriptions of the event condition and of each task dened for

the agent.

• the content area

This area contains the pages and dialogs that you use to create and manage an agent.

The four areas are shown in the following example.

Chapter 1. IBM Cognos Event Studio

I want to area

Summary area

Insertable Objects area

Content area

Figure 1. Event Studio user interface work areas

Insertable Objects Area

The Insertable Objects area contains items that you can add to the event condition and tasks.

The Source Tab

The source tab

shows a hierarchical list of the source items, both relational and dimensional, in the

model package.

The Data Items Tab

The data items tab shows a list of all the data items contained in the agent. The data items tab also

shows the calculations used in the agent.

The Functions Tab

IBM Cognos Analytics Version 11.1: Event Studio User Guide

The functions tab shows a list of mathematical functions, such as operators and summaries, that you

can use in event conditions and to create calculated data items.

Tip: If you are specifying an event condition and want to know the meaning of a function icon, click the

icon and read the description in the Information box.

The Parameters Tab

The parameters tab shows a list of each parameter you dened, indicated by the parameter icon. You

can use parameters when specifying the event condition.

The Run History Tab

The run history tab

shows a list of items you can specify when you add an on-error task to an agent.

Example - Create an Agent with a Single Task

You create an agent to perform a task when it detects a business event.

You are a sales manager who wants to ensure that your most valued customers are pleased with the

quality of service they receive.

You decide that, whenever a valued customer calls your support group, you will call the customer the next

day to make sure they're satised. You use IBM Cognos Event Studio to create an agent that monitors

support call records. You specify an event condition as follows:

[Call_Status]= Open AND [Customer_Profile]= Gold

Next you add a task and specify that, when the event occurs, the agent sends you an e-mail entitled

Urgent: Call Customer Today.

The e-mail message you receive contains details both about the customer and about the call. You do not

need to continually check the call system or run reports. The relevant data is sent to you only when you

need to act upon it.

Events

An event is an exceptional item of data, dened by specifying a query expression against items in a data

package. When a record matches the event condition, it causes an agent to perform tasks.

When an agent runs, it checks the data for any event instances.

For example, you can specify an event condition as follows:

[Account_Balance] < 0

Event Instances

An event instance is a single row of data that matches the event query expression. When an agent

monitors data, it detects each event instance. The agent then follows the task execution rules to

determine if it should perform a task.

Some types of tasks are performed only once by the agent. Other types of tasks are repeated for each

event instance. For more information, see “Task Frequency” on page 8.

Chapter 1. IBM Cognos Event Studio

Event List

An event list shows the events processed by the agent. Each event is categorized by one of the following

statuses: new, ongoing but changed, ongoing and unchanged, or ceased.

When an agent runs, it derives the status by comparing the detected events with those detected in the

previous run. There is only one event list per agent, and it is updated each time the agent runs.

For each task in an agent, the event list is checked against the task execution rules. The task is performed

for each event that conforms to the rules.

Event Key

An event key is used to determine whether an event is new, ongoing but changed, ongoing and

unchanged, or ceased.

IBM Cognos Event Studio compares the event instances detected in each agent run with those detected

in the previous run. To ensure it correctly matches the event instances for comparison, you must dene

an event key. The event key is the combination of data items that uniquely denes an event instance.

For example, you are dealing with orders that were placed for out-of-stock goods. You dene Order

Number as the event key, because each order placed has a unique number. If Order Number 1234

appears in this run and in the previous run, it is an ongoing event. If Order Number 4567 appears in this

run, but not in the previous run, it is a new event. If Order Number 7890 appeared in the last run but not

this one, it has ceased.

Task Execution Rules

When an agent runs, it uses the event key to compare the event instances it detects with those of the

previous run.

The agent allocates a status to each event - new, ongoing but changed, ongoing and unchanged, or

ceased. If no event instances are detected, the status is no events. The task execution rules specify the

event status for which each task is performed. You can optionally specify that an event must also pass a

Boolean test before it is used in a task. If you do not set any execution rules, the agent performs its tasks

for all the event instances it detects.

You can also set a special task to execute if the agent fails, for example, if the agent condition fails or one

of the agent's tasks fails to complete. This special task can include items from the agent's run history,

such as its run time, status, and error messages.

Example - Event Status of New

You want to receive an e-mail message advising you whenever a Gold category customer phones

technical support about a new problem.

You specify that an e-mail task be performed only when the event status is new. You receive an e-mail

when the call record from a Gold customer is rst placed in the call database. However, even if the call

record is still open the next time the agent runs, you receive no further e-mails because the status of the

event is now ongoing.

Example - Event Status of Ongoing But Changed

You want a report to run if the account balance of an overdrawn customer changes.

Example - Event Status of No Events

You want to receive a daily e-mail that reassures you that none of your company's accounts has a balance

less than zero.

You dene the following event condition:

[Account_Balance] < 0

You specify that an e-mail task be performed if the event status is no events.

IBM Cognos Analytics Version 11.1: Event Studio User Guide

In this example, you may also want to create another task that sends an urgent e-mail if any of the

account balances does become less than zero. That is, you create another e-mail task that is performed if

the event status is new.

Example - Task-Level Boolean Filter

You want to e-mail your Regional Managers whenever a very large order is received from a customer in

their territory.

You create four calculated data items containing Boolean expressions:

• Item IsNorth: If ([Region] = ‘North') then (‘True') else (‘False')

• Item IsEast: If ([Region] = ‘East') then (‘True') else (‘False')

• Item IsSouth: If ([Region] = ‘South') then (‘True') else (‘False')

• Item IsWest: If ([Region] = ‘West') then (‘True') else (‘False')

Add four e-mail tasks to the agent, one addressed to each Regional Manager. Add the appropriate task-

level lter to each task. In this example, the task that e-mails the Northern Regional Manager includes

only orders that pass the test Region = ‘North'.

Agents

Agents monitor data for instances of an event and perform tasks when events occur. These tasks can help

to notify people about events immediately, so that they can make timely and effective decisions.

When an agent runs, it checks for occurrences of the event. If it detects the event, the agent performs its

tasks for events that meet the execution rules. An agent runs its tasks either all at the same time or in the

order that you specify.

Example - Create an Agent with Multiple Tasks

You are a meteorological analyst who wants to be alerted to extreme drops in air pressure that could

result in a violent storm.

You create an agent named Pressure_Drop. You specify the event condition as follows:

[Air_Pressure].[Current_Time-60] - ([Air_Pressure].[Current_Time])>

5.0

Next, you add an e-mail task and specify that, when the event occurs, the agent sends you an e-mail

entitled Pressure Drop Alert. Finally, you add a report task that sends a report of the latest air pressure

readings to people in surrounding weather ofces.

Prompting Agents

A prompting agent prompts a user to specify values for the event condition. This can result in the task

being performed in a situation that is specic to the user.

For example, you specify an event condition that prompts sales managers to specify their region and their

product. The task is then performed only for events that are of interest to the sales manager who is

running the agent.

The prompts of an agent can also be answered by passing in the values of source items from the events of

another agent.

Tasks

An agent can perform one or more tasks that you dene for it. You can use some tasks to notify the right

people quickly about a change in a business event so they can take appropriate action. Other tasks can

help you to automate a work flow.

Chapter 1. IBM Cognos Event Studio

An agent can perform its tasks in sequence, where each task is performed in the order you choose, or in

parallel, where you specify that tasks be performed at the same time. By default, tasks are performed in

parallel.

Note: For parallel tasks, tasks are run in a specic order, depending on the task types included in an

agent.

You can specify tasks that do the following:

• send an e-mail

• publish a news item

• run a report

• run a job

• run an agent

• send an approval request

• send a notication request

• update a database

• call a web service

• run an export

• run an import

• run a content maintenance task

Task Frequency

Before you specify an event condition, you should understand how often different tasks are performed.

Task type

Number of times performed

Run a report; run an agent; run a job; run an import;

run an export; run a content maintenance task

Once

Update a database; call a web service Once per event instance

Send an e-mail; send an approval request; send a

notication request

Variable

For more information, see “How Multiple Events

Affect E-mail Messages, Approval Requests, and

Notication Requests” on page 9.

Publish a news item Once

Notication Methods

If you want to notify people about a business event, you should understand the notication methods that

an agent can use. The notication method you choose should contain all information relevant to the

event, and each person who must know about the event should be notied.

An IBM Cognos Event Studio agent can notify people about business events by

• delivering an email to your audience

• publishing a news item to a folder frequently viewed by your audience

The notication feature can contain dynamic information. This means that source items from a package

can be inserted into the message. The values for these items are not retrieved until the agent is run

because a notication message about a critical data item always contains the current values.

Both e-mail and news item notications can contain dynamic information. In an email task, the email can

contain dynamic content in the list of recipients, the subject, and the message body. For more

information, see “Add an Email Task” on page 46.

IBM Cognos Analytics Version 11.1: Event Studio User Guide

The parts of a news item notication that can contain dynamic content are the headline, the screen tip,

and the text. For more information, see “Add a News Item Task” on page 48.

Although email and news item notications can both show content dynamically, only email notications

can change their target dynamically. By inserting email address items in the recipient elds, you can

specify that the recipient list change according to the data in the event list.

Email Notications

You can notify people by e-mail using either a report task or an email task. To help you decide which

method to use, you should understand how they differ.

You can use either a report task or an email task

• to send a single email text message

• to attach a single report in the specied output formats

Note: If you attach only one HTML report and leave the body eld empty, the report appears in the

message body.

• to add links to a single report for the specied output formats

For an e-mail task but not a report task, you can also

• add dynamic content to the message, which may result in multiple emails

This means that you can insert source items from a package into the message. If you insert an e-mail

address item in the recipient elds, you can tailor the recipient list so that it is specic to the data in the

message.

• send multiple reports in a single email as attachments, links, or both

For example, you can attach a report about stock usage and a report on unfullled customer orders

when a particular stock item falls below a reorder level.

• attach the event list

Emailing reports from an IBM Cognos Event Studio agent is useful if you want the report to be tailored to a

specic event.

News Item Notications

A news item task publishes a headline to a folder whose contents can be viewed in an IBM Cognos

Navigator portlet and in any folder view. When someone clicks on a headline, they can open IBM Cognos

Analytics content or view a web page.

How Multiple Events Affect E-mail Messages, Approval Requests, and Notication

Requests

When you create an e-mail message, approval request or notication request, you can drag data items

into the recipient, subject, and message body elds. These data items act as placeholders. When the

agent runs, the placeholders are replaced with actual values from the data source.

If data items appear only in the message body, a single message is usually sent containing details of all

the events detected. If the recipient or subject elds include data items, many e-mails or requests may be

sent.

For an example that illustrates the effect of multiple events, see “Add an Email Task” on page 46

Dynamic Address

Chapter 1. IBM Cognos Event Studio

For some e-mails or requests, the appropriate recipient depends on the values in the event. For example,

an e-mail about a support call from Customer A must be addressed to Customer A's account manager.

If the data source includes an item that represents e-mail addresses, you can drag this item to the

recipient elds. The agent uses this data to generate the e-mail address dynamically. If the agent detects

several events that satisfy the event condition, it generates one message or request for each e-mail

address. The source items in the message body are grouped by address.

Dynamic Subject

If you include a source item in the subject eld, the agent generates one message or request for each

subject. The source items in the message body are grouped by subject.

Dynamic Address and Dynamic Subject

If you include source items in both the address and subject elds, the messages or requests are grouped

by address and subject.

Dynamic Message Body

If an agent detects several events that satisfy the event condition, the size of the message body in the

delivered message or request can increase. Every line that contains a data item placeholder is repeated

for each event instance that satises the task execution rules.

The Sample Outdoors Company

The Sample Outdoors Company samples illustrate product features and technical and business best

practices.

You can also use them for experimenting with and sharing report design techniques and for

troubleshooting. As you use the samples, you can connect to features in the product.

The Sample Outdoors Company, or GO Sales, or any variation of the Sample Outdoors name, is the name

of a ctitious business operation whose sample data is used to develop sample applications for IBM and

IBM customers. Its ctitious records include sample data for sales transactions, product distribution,

nance, and human resources. Any resemblance to actual names, addresses, contact numbers, or

transaction values, is coincidental. Unauthorized duplication is prohibited.

Samples outline

The samples consist of the following:

• Two databases that contain all corporate data, and the related sample models for query and analysis

• Sample cubes and the related models

• A metrics data source including associated metrics and a strategy map for the consolidated company,

and a model for Metric extracts.

• Reports, queries, query templates, and workspaces

To run interactive reports, scripts are required. To see all the reports included in the samples packages,

copy the les from the samples content installation into deployment folder and then import the

deployments into the IBM Cognos Business Intelligence product.

Security

Samples are available to all users.

To implement security, see the IBM Cognos Business Intelligence Administration and Security Guide.

IBM Cognos Analytics Version 11.1: Event Studio User Guide

IBM Cognos Event Studio Samples

IBM Cognos Analytics includes report samples and an agent sample.

The Customer Contact Sample

This report sample is used in a tutorial in this document.

For more information, see Chapter 3, “Tutorial,” on page 41.

The Returns Agent Sample

The Returns Agent sample noties you when a customer returns a product because it was defective,

unsatisfactory, or incomplete, or because the wrong product was shipped.

This agent sample was created using the IBM Cognos Event Studio example illustrated in IBM Cognos

Analytics Getting Started. If you try this example yourself, you can compare the agent that you create with

the Returns Agent sample.

The ELM Returns Agent Sample

The ELM Returns Agent sample noties you when a customer returns a product because it was defective,

unsatisfactory, or incomplete, or because the wrong product was shipped.

Two days after detecting the event, this agents checks if the issue is resolved. If unresolved event

instances still exist, it runs the ELM Escalation Agent sample.

This agent sample is used in the topic “Example - Managing the Life Cycle of an Event” on page 11

The ELM Escalation Agent Sample

The ELM Escalation Agent sample is run by the ELM Returns Agent sample.

If more than two days have lapsed since the ELM Returns Agent sample detected an event, the ELM

Escalation Agent sample escalates the issue by sending an e-mail to the customer fullment manager.

This agent sample is used in the topic “Example - Managing the Life Cycle of an Event” on page 11.

Example - Managing the Life Cycle of an Event

Try this example to see how the ELM Returns Agent sample performs different tasks depending on the

stage of the life cycle for the event.

Event Life cycle Management (ELM) is the ability to identify, track, and take appropriate action on an event

at the right time and in the right sequence. Different information, people, and tasks are required at

different stages in the life cycle of an event.

You are the customer fullment manager for a company. After analyzing data warehouse metrics, you

determine that when orders are returned for reasons that your company can control, there is a signicant

impact on customer loyalty. Customers withhold payment for the entire order until the issue is resolved.

To identify these issues and resolve them as quickly as possible, you decide to run the ELM Returns

Agent sample. To run this agent, do the following:

• Perform setup tasks that are necessary only to demonstrate this example. These tasks are as follows:

– Congure your mail server so that IBM Cognos Analytics can send notications.

– Modify the agent samples to send e-mails to you.

– Simulate the occurrence of initial events.

– Simulate the passage of time and the resolution of some events.

• Preview the output of all agent tasks.

• Detect initial events and act on them as necessary.

Chapter 1. IBM Cognos Event Studio

• Detect an ongoing, unresolved event and escalate the issue.

• Conrm that the ELM Escalation Agent sample completed all its tasks successfully

Example - Congure Your Mail Server

Congure your IBM Cognos Analytics mail server to send notications using IBM Cognos Event Studio.

Procedure

1. Start IBM Cognos Conguration.

2. In the Explorer pane, click Notication.

3. Enter the notication properties:

• In the SMTP mail server box, type a mail server that is appropriate for your environment.

• In the Account and Password box, type your e-mail user ID and password.

• In the Default sender box, type the following:

notifications@ibmcognos

4. Save the conguration.

Example - Modify the Agent Samples to Send E-mails to You

The IBM Cognos Event Studio agent samples named ELM Returns Agent and ELM Escalation Agent are

set up to send e-mails to other people.

To view the e-mails that these other people would normally receive, change the recipient e-mail address

to your own e-mail address.

Modify the ELM Returns Agent Sample

Use the following steps for the ELM Returns Agent sample.

Procedure

1. In IBM Cognos Analytics, click Team content > Samples > Models > GO Sales (Query).

2. Click Event Studio Samples.

3. Click the Event Studio button

on the actions toolbar next to the ELM Returns Agent sample.

Event Studio starts, and the ELM Returns Agent sample appears.

4. Click the Follow up required e-mail task.

5. In the Specify the email to send window, in the To box, replace

[email protected] with your own e-mail address.

6. From the File menu, click Save.

7. From the File menu, click Exit.

Results

The destination address is changed to your e-mail address so that the agent sends e-mails to you. The

sender address remains notications@ibmcognos.

Modify the ELM Escalation Agent Sample

Use the following steps for the ELM Returns Agent sample.

Procedure

1. In IBM Cognos Analytics, click Team content > Samples > Models > ELM Escalation Agent and

launch Event Studio.

Event Studio starts, and the ELM Escalation Agent sample appears.

2. Click the Outstanding Returned Item Order e-mail task.

IBM Cognos Analytics Version 11.1: Event Studio User Guide

3. In the Specify the email to send window, in the To box, replace

FullmentManager@yourcompany.com with your own e-mail address.

4. From the File menu, click Save.

5. From the File menu, click Exit.

Results

The destination address is changed to your e-mail address so that the agent sends e-mails to you. The

sender address remains notications@ibmcognos.

Example - Simulate the Occurrence of Initial Events

Run part of the IBM Cognos Event_Studio_ELM_Agent_Modify_GoSales.sql script to simulate data

changes.

The following data changes can be simulated:

• change the date to the current date

• change the follow-up code to -1 in four records

A code of -1 indicates that follow-up is required.

Procedure

1. In SQL Query Analyzer, from the File menu, click Open.

2. Go to c10_location/webcontent/samples/datasources/sqlserver and double-click the

Event_Studio_ELM_Agent_Modify_GoSales.sql le.

3. In the toolbar, from the list of databases, click gosales.

4. In the Query window, under Part 1, select all sixteen lines of code.

5. From the Query menu, click Execute.

Results

The database is updated with the changes.

Example - Preview the Output of Each Task of an Agent

You can preview the output of the IBM Cognos Event Studio ELM Returns Agent sample based on the

current data, without running the agent.

Procedure

1. In IBM Cognos Analytics, click Team content > Samples > Models > ELM Escalation Agent and

launch Event Studio.

Event Studio starts, and the ELM Escalation Agent sample appears.

2. From the Actions menu, click Preview All.

Results

A window appears that shows the event list and the output that would be produced by each agent task.

Based on this preview information, you can decide whether to run the agent.

Example - Detect Initial Events and Act on Them

Run the IBM Cognos Event Studio ELM Returns Agent to detect the initial instances of products returned

for specic reasons.

When these events are detected, the ELM Returns Agent does the following:

• It runs the AssignStaff stored procedure.

AssignStaff provides details about the sales representatives associated with each event instance,

including the e-mail address.

Chapter 1. IBM Cognos Event Studio

• It sends an e-mail to the appropriate sales representatives, advising them to contact their customer.

• It runs the ELM Escalation Agent.

The ELM Escalation Agent checks for returned product events flagged by the ELM Returns Agent. If

one of these events still exists after two days, the ELM Escalation Agent sends an e-mail to the

customer fullment manager.

Procedure

1. In IBM Cognos Analytics, click Team content > Samples > Models > GO Sales (Query) > Event Studio

Samples.

2. Click the run with options button on the actions toolbar next to the ELM Returns Agent sample.

3. Under Time, click Now.

4. Under Prompt values, clear the Prompt for values check box.

5. Click Run.

6. Click OK.

Results

You receive two e-mails, originally intended for sales representatives Karen Bowman and Clarice Oliveira.

The e-mail to Karen Bowman noties her of one returned order. The e-mail to Clarice Oliveira noties her

of the three returned orders assigned to her.

The task execution rules for the ELM Returns Agent sample specify that all tasks are performed for new

events only. If you do not receive any e-mails, the agent may already have run, so that none of the

detected events are new. You can reset the event list so that when the agent runs next, all detected

events have a status of new.

Tip: From the Actions menu, click Reset Event List.

Example - Simulate the Passage of Time and the Resolution of Some Events

Run part of the Event_Studio_ELM_Agent_Modify_GOSALES.sql script to simulate data changes.

First, change it so that two days elapsed since the ELM Returns Agent sample was last run. Second, for

three of the four event instances found the last time that the ELM Returns Agent sample ran, change the

follow-up code from -1 to +1. This indicates that only one of the these event instances still requires

follow-up and the other instances are resolved.

Procedure

1. In SQL Query Analyzer, from the File menu, click Open.

2. Go to install_location/webcontent/samples/datasources/sqlserver and double-click the

Event_Studio_ELM_Agent_Modify_GOSALES.sql le.

3. On the toolbar, click GOSALES from the list of databases.

4. In the Query window, under Part 2, select all lines of code that appear after the comments.

5. From the Query menu, click Execute.

Results

The database is updated with the changes.

Example - Detect an Ongoing Unresolved Event and Escalate the Issue

Run the IBM Cognos Event Studio ELM Returns Agent sample a second time. The agent now detects only

one event because you modied the follow-up codes in the previous task. In addition, because two days

lapsed since the sales representative was notied, the event condition of the ELM Escalation Agent

sample is met. The ELM Escalation Agent sample detects the event and sends an e-mail to the customer

fullment manager.

IBM Cognos Analytics Version 11.1: Event Studio User Guide

Procedure

1. In IBM Cognos Analytics, click Team content > Samples > Models > GO Sales (Query) > Event Studio

Samples.

2. On the actions toolbar, click the run with options button next to the ELM Returns Agent sample.

3. Under Time, click Now.

4. Under Prompt values, clear the Prompt for values check box.

5. Click Run.

6. Click OK twice.

Results

After this agent runs, you receive only one e-mail. Instead of being sent to the sales representative, this

issue is escalated to the customer fullment manager.

Example - Conrm that the ELM Escalation Agent Sample Completed Its Tasks

Successfully

You can conrm that the IBM Cognos Event Studio ELM Escalation Agent sample, which is run by the

ELM Returns Agent sample, completed its tasks successfully.

Procedure

1. In IBM Cognos Analytics, click Team content > Samples > Models > GO Sales (Query) > Event Studio

Samples.

2. On the actions toolbar next to the ELM Escalation Agent sample, click More.

3. Click View run history.

4. In the Actions column, click the view run history details button

Results

A window appears showing that the event query and e-mail task succeeded.

Chapter 1. IBM Cognos Event Studio

16 IBM Cognos Analytics Version 11.1: Event Studio User Guide

Chapter 2. Creating an Agent

Create an agent to monitor data for instances of an event and to perform tasks.

Before you begin

Before you create an agent, you should understand the notication methods that an agent can use. You

should also know how often an agent performs different types of tasks.

To create an agent, do the following:

• Specify the event condition.

• Add one or more of the following types of tasks for the agent to perform when the event status meets

the task execution rules:

– e-mail task

– news item task

– report task

– job task

– agent task

– approval request task

– notication request task

– database update task

– web service task

– export task

– import task

– content maintenance task

– planning macro task

– migration task

• Specify the task execution rules.

After you create an agent, you can:

• preview it

• test it

• run it

• modify the event condition

• modify a task

• modify the task execution rules

Specify an Event Condition

When you specify an event condition, you describe a specic occurrence of data items that an agent must

detect before it performs its tasks. The event condition is a query expression that you create using items

from the package.

For more information, see “Specify an Event Condition” on page 43.

Before you begin

If you want to include parameters or calculations in the event condition, you must create them before you

dene the event.

Procedure

1. From the Actions menu, click Specify Event Condition .

2. Create a detail expression, a summary expression, or both:

• If you want part of the event condition to apply to values of individual source items, click the Detail

tab and follow step 3.

• If you want part of the event condition to apply to aggregate values, click the Summary tab and

follow step 3.

3. In the Expression box, create a query expression:

• Drag items from the source tab or type text directly.

• Drag operators, summaries, and other mathematical functions from the functions tab or type text

directly.

Tip: To see the meaning of an icon on the functions tab, click the icon and read the description in the

Information box.

• If you want to insert a parameter, drag it from the parameters tab.

• If you want to insert a calculation, drag it from the data items tab.

• Insert values if required.

Tip: To select from a list of possible values for the selected item, click the select value button .

Move the values you want from the Select Value box to the Selected Items box and click OK.

Note: IBM Cognos Event Studio always processes data items before performing aggregation on an

expression. This can lead to conditions being evaluated before the data item contains information.

For example, you can type the following expression:

[Unit price] * [Quantity sold]> 5000

4. To check the event list to ensure that you specied the event condition correctly, from the Actions

menu, click Preview.

5. To determine how many event instances there are, from the Actions menu, click Count Events.

6. From the File menu, click Save As .

7. Specify a name and location for the agent and click OK.

Results

You can preview the event list returned by the event condition. For more information, see “Preview the

Data” on page 34.

Dene a Parameter

You can dene a parameter and include it in an event condition. When the agent runs, it prompts the user

to enter a value for the parameter. You can also use parameters to accept the results of a previous agent.

For more information, see “Dene a Parameter to Insert Into an Event Condition” on page 42

Procedure

1. From the Insert menu, click Parameter .

IBM Cognos Analytics Version 11.1: Event Studio User Guide

2. In the Parameter name box, type a name for the parameter.

3. Click OK.

The parameter appears in the data items tab.

Results

You can include the parameter when you specify an event condition.

Dene a Calculation

A calculation is a query expression that denes an arithmetic combination of data items. For example, you

can dene a calculation named Product Sales that is the product of the unit price and the quantity sold.

For more information, see “Dene a Calculation to Insert Into an Event Condition” on page 42

Procedure

1. From the Insert menu, click Calculation

2. In the Name box, type a name for the calculation.

3. In the Expression box, dene the calculation:

• Drag items from the source tab or type text directly.

Tip: If you type the text, you must include the full path of each data item. For example, you can type

the following expression:

[gosales_goretailers].[Orders].[Unit price] * [gosales_goretailers].

[Orders].[Quantity]

• Drag operators, summaries, and other mathematical functions from the functions tab or type text

directly.

Tip: To see the meaning of an icon on the functions tab, click the icon and read the description in the

Information box.

• Insert values if required.

Tip: To select from a list of possible values for the selected item, click the select value button

Move the values you want from the Select Value box to the Selected Items box and click OK.

4. Click OK.

The calculation icon appears on the data items tab.

Results

You can include the calculation when you specify an event condition or specify a task.

Adding Tasks

You can add multiple tasks to an agent. However, you can specify only one event condition per agent.

Each task is performed for the event list that meets the execution rules you specify for the task. The agent

performs tasks in the order that you add them, unless you change their order later. You can save an agent

and add additional tasks to it later.

You can add source items or data items to some types of tasks. When the agent performs the task, it uses

the current value of the item. If you want the agent to use the value that a particular item had the previous

time the agent ran, you can insert the previous function before the item.

To insert the previous function, from the Insert menu, click Previous Value.

Chapter 2. Creating an Agent

Add an Email Task

Add an email task to an agent to send an email about an event to specied recipients. You can include

content, such as report output, in an email task.

For more information, see “Add an Email Task” on page 46.

You can also add other types of tasks. Email tasks share some similarities with report tasks. For more

information, see “Email Notications” on page 9.

Before you begin

Before you add any type of task, you must specify an event condition.

Procedure

1. In the I want to area, click Add a task.

2. Click Send an email.

3. In the To box, and if applicable, in the Cc or Bcc boxes, enter the email addresses of the recipients

using one or more of the following methods:

• Type the addresses directly, separating each email address with a semicolon.

• If your model contains a data item that is an email address, drag this item from the source tab or

from the data items tab. When the agent runs, the current value in the package replaces the data

item for each event instance.

• Click Select the recipients. Select the users, groups, roles, contacts, and distribution lists. Select

the entries you want, click the arrow button to update the Selected entries list, and click OK.

4. In the Subject box, type the subject of the email.

Tip: You can also drag items from the source tab or from the data items tab. When the agent runs, the

current value in the package replaces the data item for each event instance.

5. In the Body box, type the email message text directly or drag items from the source tab or from the

data items tab.

If you insert data items in the Body box, the body message will be longer. When the agent runs, the

current value in the package replaces the data item for each event instance. For more information, see

“How Multiple Events Affect E-mail Messages, Approval Requests, and Notication Requests” on page

If the email has a single HTML attachment and the Body box is empty, the attachment appears inline.

6. To change the message format from HTML to plain text or vice versa:

• To change from the default HTML format to plain text format, click Change to plain text.

Note: If you switch to plain text format, any HTML formatting changes are lost.

• To change from plain text to HTML, click Change to HTML format. You can then use formatting

buttons to edit the message.

7. To add attachments, click Attach and choose the attachments.

8. To add links, click Add links, select the entries you want, click the arrow button to update the

Selected entries list, and click OK.

Important: When you click a link that was generated and sent with email, saved output is opened if it

exists. If there is no saved output, the following message is displayed:

Unable to load requested view. Displaying home view instead.

Report outputs can be generated using a Report run task in the agent or with a separate report

schedule.

9. From the File menu, click Save .

IBM Cognos Analytics Version 11.1: Event Studio User Guide

Results

You can preview the email task. When the agent runs, it retrieves values for all source and data items and

sends the email to the recipients you chose.

Add a News Item Task

Add a news item task to an agent to publish a headline to a folder.

For more information, see “Add a News Item Task” on page 48.

You can also add other types of tasks.

Before you begin

Before you add any type of task, you must specify an event condition.

Procedure

1. In IBM Cognos Analytics, create a new folder.

2. In IBM Cognos Event Studio, specify an event condition.

3. In the I want to area, click Add a task.

4. Click Publish a news item.

5. In the Headline box, type the text you want to appear at the top of your news item.

Tip: You can also drag items from the source tab or the data items tab.

6. To add a description in the Screen tip box and in the Text box, type a description of the entry.

The screen tip is limited to 100 characters.

Tip: You can also drag items from the source tab or from the data items tab.

7. Under Link to, choose an object to appear when you click a news headline:

• To link to IBM Cognos Analytics content, click Select an entry, go to the entry, and click OK. For

example, if you want the Customer Contact report to appear when someone clicks the headline, click

Select an entry, locate the Customer Contact report, and click OK.

Tip: You can add a report task that runs a report before the news item task is performed. If you link

that report to the news item task, the report always shows information about current event

instances when someone clicks the headline.

• To link to a URL, type the URL address in the box.

If the URL points to a web site address, include the protocol, such as http. For example, to create a

URL for the IBM web site, you would type http://www.ibm.com.

8. Under News list location, click Select a location, go to the folder or portlet in which the news item

will be published and click OK.

From the File menu, click Save

Results

You can preview the news item task. When the agent performs the news item task, it publishes the news

headline to the location you chose. When you click the headline, the Cognos Analytics entry or the web

page you linked to appears.

The description text appears when you set your preferences to use the details view. The screen tip

appears when you pause your pointer over the icon for the entry in the news list location.

Add a Report Task

Add a report task to an agent to run a report that is related to an event.

For more information, see “Add a Report Task” on page 44

Chapter 2. Creating an Agent

You can also add other types of tasks. Email tasks share some similarities with report tasks. For more

information, see “Email Notications” on page 9.

Before you begin

Before you add any type of task, you must specify an event condition.

You must have permissions to run the report that you select. For more information, see the IBM Cognos

Analytics - Reporting User Guide.

Procedure

1. In the I want to area, click Add a task.

2. Click Run a report.

3. In the Select the Report dialog box, specify the report, query, analysis, or report view to include in the

agent.

• Search the folders to nd the entry you want.

• Click the entry and click OK.

4. To customize the report, under Options, click Set and make the necessary changes.

5. If the report includes parameters, under Prompt values, choose how to specify prompt values for

each parameter:

• If you are using an item, in the Method column, click Use an item and drag an item from the source

tab or from the data items tab to the Value column.

Tip: When you specify a data item, values from the event list are passed as prompt values in the

report. If the event list has multiple instances, then multiple values are passed as prompt values.

Therefore, you must ensure that the report being run has a prompt that can accept multiple values.

For more information, see the IBM Cognos Analytics - Reporting User Guide.

• If you are using a value, in the Method column, click Use a value, click Specify values, and in the

Value column, type a value.

Tip: If you want to clear the prompt values and return to the default values, click Reset to default.

6. From the File menu, click Save

Results

You can preview the report task. When the agent performs the report task, it runs the report and delivers

it according to the delivery options you chose.

Customize the Report

You can change the report options from the defaults to customize the report for your audience.

The following are the options you can change:

• Change one or more report output formats.

• Change one or more languages.

• Change one or more delivery methods.

• Burst the report if it was authored with bursting specications.

Default options are set by the report author. You can change some default run options for reports.

You change the report options when you click Set or Edit in the Specify the report to run dialog box. For

more information, see “Add a Report Task” on page 21.

Procedure

1. In the Select the report options dialog box, select the Override the default values check box.

2. Under Formats, click the formats you want for the report output.

IBM Cognos Analytics Version 11.1: Event Studio User Guide

3. To select different or additional languages for the report, click Select the languages and use the arrow

keys to move the available languages to the Selected languages box and click OK.

Tip: To select multiple languages, press Ctrl+click or Shift+click.

4. Under Delivery, choose a delivery method:

• To save the report, select the Save check box, then click the button next to Save the report.

• To save the report as a report view, select the Save check box, then click the button next to Save the

report as a report view. You can change the name or target folder of the report view by clicking Edit

the options. Make the changes, and click OK.

Tip: Save the report as a report view if you do not have write access to the report. You can then add a

link to the report view when you specify an e-mail task.

• To print the report, select the Print the report check box and click Select a printer. Click the button

next to the printer you want to use and click OK. Or, if the printer is not listed, you can type the

printer information.

Tip: If you have administrator privileges and want to set up the printer for future use, click New

printer. You must type the network address of the printer by using the format \\server_name

\printer_name for a network printer on a Windows operating system installation and printer_name

for a UNIX operating system installation or for a local printer.

• To e-mail the report, select the Send the report by email check box.

5. If you clicked Send the report by email, click Edit the options to specify what you want:

• To send the e-mail to IBM Cognos Analytics recipients, click Select the recipients. Select the check

box next to the names you want to include, and click To, Cc (copy), or Bcc (blind copy). The entries

that you select are listed under Selected entries. Click OK.

Tip: To select all entries in a list, click the check box. To remove names from Selected entries,

select the check box next to the name and click Remove. To search, click Search. In the Search

string box, type the phrase you want to search for. For advanced search features, click Advanced.

• If you want to send the e-mail to other recipients, in the To:, Cc, or Bcc boxes, type the email

addresses separated by semicolons (;).

Tip: If you logged on, your name automatically appears in the To list box.

• Under Subject, type the subject of the e-mail.

• Under Body, type a message to be included in the e-mail.

• If you want to include an attachment, select the check box to include the report or a link to the

report, and click OK.

If you are an administrator, you can prevent users from including attachments. For more information,

see the IBM Cognos Administration and Security Guide.

6. Under Bursting, specify whether the report should be bursted.

This option is available only if the report author dened burst keys in the report.

7. Click OK.

The Specify the report to run dialog box appears.

8. Continue specifying the report. For more information, see “Add a Report Task” on page 21

Add a Job Task

Add a job task to an agent to run a job. A job identies a collection of reports, report views, agents, and

other jobs that are scheduled together and share the same schedule settings.

For example, you create a job named Two Reports, and select two reports that you want the job to run. In

IBM Cognos Event Studio, you add a job task and select the Two Reports job. When the agent runs and

detects events that meet the task execution rules, it runs the Two Reports job.

You can also add other types of tasks.

Chapter 2. Creating an Agent

Before you begin

Before you add any type of task, you must specify an event condition.

Before you create a job task, you must create a job.

Procedure

1. In the I want to area, click Add a task.

2. Click Run a job.

3. In the Select the job dialog box, specify the job to include in the agent.

• Search the folders to nd the job you want.

• Click the entry and click OK.

4. From the File menu, click Save .

Results

You can preview the job task. When the agent performs the job task, it runs all the IBM Cognos Analytics

items identied in the job.

Add an Agent Task

Add an agent task to an agent to run another agent. By running multiple agents in sequence, you can use

the output from one agent as the input to another agent. You can also use multiple agents that interact

with each other using data retrieved from different data sources. This removes the need to join databases

using IBM Cognos Framework Manager.

For more information, see “Example - Adding an Agent Task” on page 25.

You can also add other types of tasks.

Before you begin

Before you add any type of task, you must specify an event condition.

Procedure

1. In the I want to area, click Add a task.

2. Click Run an agent.

3. In the Select the agent dialog box, choose an agent.

• Search the folders to nd the agent you want.

• Click the entry and click OK.

4. If the task includes parameters, under Prompt values, choose how to specify prompt values for each

parameter:

• If you are using a value, in the Method column, click Use a value, click Specify values, and in the

Value column, type a value.

• If you are using an item, in the Method column, click Use an item and drag an item from the source

tab

or from the data items tab to the Value column.

Tip: If you want to clear the prompt values and return to the default values, click Reset to default.

5. From the File menu, click Save .

Results

You can preview the agent task. When the agent performs the agent task, it runs the agent you specied.

IBM Cognos Analytics Version 11.1: Event Studio User Guide

Example - Adding an Agent Task

You want to run the high_returns_followup agent to detect a high rate of returned items and resolve the

related issue. However, for each item that has a high rate of return, you also want to check the

importance of the customer to your company as calculated from data in a data warehouse system. The

customer's importance value is calculated using projected sales and prot data.

You create a second agent named high_returns_customer_check that is run by the high_returns_followup

agent. When a high return event occurs, the high_returns_followup agent runs and passes customer

details to the high_returns_customer_check agent. The high_returns_customer_check agent then runs a

query to check the customer importance value. If the customer importance value is high, the

high_returns_customer_check agent sends an e-mail asking the customer services agent to contact the

customer and x the problem immediately.

Add an Approval Request Task

Add an approval request task to an agent when you want an event to occur only after approval. This task

sends an approval request related to an event to the task inbox of specied recipients in IBM Cognos

Analytics.

A recipient can be a potential owner or a stakeholder. Multiple users, groups, roles, and distribution lists

can be assigned as potential owners of an approval request task. Stakeholders can be users, groups,

roles, and distribution lists that are identied as interested parties, but are not potential owners.

Tip: To track the progress of an approval request task that you create, you can add yourself as a

stakeholder.

You can include content, such as report output, in an approval request.

You can set up approval requests with different actions:

• Approve/Reject the request

The task owner must approve or reject the request from their task inbox to complete the task. If you

schedule further agent tasks to run after the approval request task, these are dependent on approval by

the task owner. If the request is rejected, no further agent tasks will run.

• Specify which of the remaining tasks to run

When you schedule further agent tasks to run after the approval request, the task owner must select

which of those tasks to run on completion of the approval request.

You can add start date and due date deadlines to an approval request when you create the task in IBM

Cognos Event Studio. Alternatively, potential owners or stakeholders can add deadlines at a later date by

updating the approval request from their task inbox.

You can set up notication options for e-mails to be sent to

• all potential owners when an approval request is created

• the task owner when an approval request is not completed by the due date

• the task owner when an approval request is not started by the start date

Note: Stakeholders are also copied on e-mails.

In addition, you can set up notication options for the task owner and all stakeholders to receive emails

when

• the status of an approval request changes (started, completed or canceled)

• the owner of an approval request changes

• a comment is added to an approval request

Note: Potential owners and stakeholders can unsubscribe from receiving specic notications by

updating the approval request from their task inbox.

You can add customized icons, using your own graphic les, to approval requests that appear in a

recipient's task inbox.

Chapter 2. Creating an Agent

To add a customized icon, use one of the following methods:

• Type the explicit location and name for the graphic le.

• Insert an item from the Insertable Items pane that contains a value for the relative path and name for

the graphic le.

Files to support custom icons must be located within the c10_location\webcontent directory and a copy

of the les must exist on all Cognos Analytics gateway server installs.

For example, to use the le green.jpg, where Cognos Analytics is installed in c:\program les\IBM\cognos

\c10\, green.jpg must exist within a path contained within c:\program les\IBM\cognos\c10\webcontent\

When you congure a task to use green.jpg (located in c:\program les\IBM\cognos\c10\webcontent

\samples\images\) as a customized icon, the value you enter in the icon Item box is either

• ./samples/images/green.jpg (explicit location)

• or, an item from the insertable items pane which contains the value ./samples/images/green.jpg

(relative location)

You can also add other types of tasks.

Procedure

1. Specify an event condition which always returns the value True. For example "1=1".

For more information, see “Specify an Event Condition” on page 17

2. In the I want to area, click Add a task.

3. Click Run an approval request.

4. In the Potential owners box, and if applicable, in the Stakeholders box, enter the names of the

recipients by using one or more of the following methods:

• If your model contains a data item that is a user, group, role or distribution list, drag this item from

the source tab or from the data items tab. When the agent runs, the current value in the package

replaces the data item for each event instance.

• Click Select the recipients to select the users, groups, roles or distribution lists.

To choose from listed entries, click the appropriate namespace, and then select the required check

boxes.

Tip: To make the user entries visible, click Show users in the list.

To search for entries, click Search and in the Search string box, type the phrase you want to search

for. For search options, click Edit. Find and click the entry you want.

Click the Potential Owner or Stakeholder arrow button to update the Selected entries list, and

click OK.

Tip: To remove entries from the Selected entries list, select them and click Remove. To select all

entries in a list, click the check box.

Click OK.

Note: You must add at least one stakeholder. By default, you are added as a stakeholder when you

create the approval request.

5. In the Subject box, type the subject of the approval request.

Tip: You can also drag items from the source tab or from the data items tab. When the agent runs,

the current value in the package replaces the data item for each event instance.

6. In the Body box, type text directly or drag items from the source tab or from the data items tab.

If you insert data items, the body message will be longer. When the agent runs, the current value in

the package replaces the data item for each event instance. For more information, see “How Multiple

Events Affect E-mail Messages, Approval Requests, and Notication Requests” on page 9.

7. To change the message format:

IBM Cognos Analytics Version 11.1: Event Studio User Guide

• Click Change to plain text to change from the default HTML format to plain text format.

Note: If you switch to plain text format, any HTML formatting changes are lost.

• Click Change to HTML format to change from plain text to HTML. You can then use formatting

buttons to edit the message.

8. To add attachments, click Attach and choose the attachments.

9. To add links, click Add links, select the entries you want, click the arrow button to update the

Selected entries list, and click OK.

10. Select the following due date options if required:

• Start within to add a start by deadline, and then type the number of days in the Days box.

• Due within to add a due date deadline, and then type the number of days in the Days box.

11. To add a customized icon to the approval request in the task inbox, drag an item from the source tab

or from the data items tab into the icon Item box.

Tip: To revert to using the default task icon, select the Default icon option.

12. To change the priority of the approval request, select a predened option from the Priority list or

drag an item from the source tab or from the data items tab into the priority Item box.

13. Select the action required by the task owner to complete the task:

• Approve/Reject the running of all remaining tasks (default)

By default, the approval request contains Approve and Reject action buttons. To change the

default button names, click Customize, type the required names, and then click OK.

• Specify which of the remaining tasks to run

Select the tasks to include in the approval request.

Note: Only agent tasks that are scheduled to run after the approval request are listed here.

By default, the approval request contains a Submit action button. To change the default button

name, click Customize, and type the required button name. When you have nished, click OK.

Tip: You can also change the names of the agent tasks as they appear in the task inbox. For

example, you could append the task type to the agent task name.

14. Select the approval request creation and deadline notication options as required:

• Send notication upon creation (default)

• Send notication if not started by start by date

• Send notication if not completed by due date

15. Select the approval request change notication options as required:

• Started

• Comment

• Owner changed

• Completed

• Canceled

16. From the File menu, click Save

Results

You can preview the approval request task. When the agent runs, it retrieves values for all source and

data items and sends the approval request to the recipients you specied.

Chapter 2. Creating an Agent

Add a Notication Request Task

Add a notication request task to an agent to send a secure notication about an event to the task inbox

of specied recipients in IBM Cognos Analytics.

A notication request can have various recipients:

• users, groups, roles, and distribution lists to whom the request is sent (To list recipients)

• stakeholders to whom the request is copied (CC list recipients)

Tip: To track the progress of a notication request task that you create, you can add yourself as a copied

(CC) recipient (stakeholder).

You can include content, such as report output, in a notication request.

You can set up the following notication options:

• Request an acknowledgement from each recipient included on the To list, with an optional deadline

date.

• All recipients receive an email when a notication request is added to their task inbox.

• Recipients included on the To list receive an email if they have not acknowledged a notication request

by the deadline date.

• Stakeholders included on the CC list receive an email on the deadline date informing them that some

recipients on the To list have not acknowledged the notication request.

You can also add other types of tasks.

Procedure

1. Specify an event condition which always returns the value True. For example 1=1.

For more information, see “Specify an Event Condition” on page 17

2. In the I want to area, click Add a task.

3. Click Run a notication request.

4. In the To box, and if applicable, in the Cc box, enter the names of the recipients by using one or more

of the following methods:

• If your model contains a data item that is a user, role or group, drag this item from the source tab

or from the data items tab. When the agent runs, the current value in the package replaces the

data item for each event instance.

• Click Select the recipients to select the users, groups, roles or distribution lists.

To choose from listed entries, click the appropriate namespace, and then select the required check

boxes.

Tip: To make the user entries visible, click Show users in the list.

To search for entries, click Search and in the Search string box, type the phrase you want to search

for. For search options, click Edit. Find and click the entry you want.

Click the To or Cc arrow button to update the Selected entries list, and click OK.

Tip: To remove entries from the Selected entries list, select them and click Remove. To select all

entries in a list, click the check box.

Click OK.

5. In the Subject box, type the subject of the notication request.

Tip: You can also drag items from the source tab or from the data items tab. When the agent runs,

the current value in the package replaces the data item for each event instance.

6. In the Body box, type text directly or drag items from the source tab or from the data items tab.

IBM Cognos Analytics Version 11.1: Event Studio User Guide

If you insert data items, the body message will be longer. When the agent runs, the current value in

the package replaces the data item for each event instance. For more information, see “How Multiple

Events Affect E-mail Messages, Approval Requests, and Notication Requests” on page 9.

If the notication request has a single HTML attachment and the Body box is empty, the attachment

appears inline.

7. To change the message format:

• Click Change to plain text to change from the default HTML format to plain text format.

Note: If you switch to plain text format, any HTML formatting changes are lost.

• Click Change to HTML format to change from plain text to HTML. You can then use formatting

buttons to edit the message.

8. To add attachments, click Attach and choose the attachments.

9. To add links, click Add links, select the entries you want, click the arrow button to update the

Selected entries list, and click OK.

10. To change the priority, select a predened option from the Priority list or drag an item from the

source tab or from the data items tab into the Item box.

11. Select the notication request notication options as required:

• Send notication by email upon creation

• Request acknowledgement

• Send notication if not acknowledged within

Type the specied number of days in the Days box.

12. From the File menu, click Save

Results

You can preview the notication request task. When the agent runs, it retrieves values for all source and

data items and sends the notication request to the recipients you specied.

Add a Database Update Task

Add a database update task to an agent to run stored procedures that exist in a database. A stored

procedure takes arguments as input and updates the database. The database that contains the stored

procedures can be different from the database in the package that the agent is monitoring.

For information about running stored procedures, see the IBM Cognos Administration and Security Guide.

You can also add other types of tasks.

A stored procedure is accessible in IBM Cognos Event Studio only if it was marked as a data modication

type in IBM Cognos Framework Manager. If the input parameters to the stored procedure task are

unavailable, check how your procedure has been modelled. For more information, see the IBM Cognos

Framework Manager User Guide.

Before you begin

Before you add any type of task, you must specify an event condition.

Procedure

1. In the I want to area, click Add a task.

2. Click Update a database.

3. Under Package, select the package to use to update the database.

4. Under Data modication stored procedure, select a stored procedure that exists for the package you

selected.

Chapter 2. Creating an Agent

5. If the stored procedure includes arguments, under Arguments, choose how to specify values for each

argument:

• If you are using a value, in the Method column, click Use a value, click Specify values, and in the

Value column, type a value.

• If you are using an item, in the Method column, click Use an item and drag an item from the source

tab or from the data items tab to the Value column.

Tip: To clear the argument values and return to the default values, click Reset to default.

6. From the File menu, click Save .

Results

You can preview the database update task. When the agent performs the database update task, the

stored procedures are run and the database is updated.

Add a Web Service Task

Use a web service task to trigger an external process. Web services let software programs interact with

one another using standard Internet protocols, so interaction is not dependant on operating system or

program language compatibility. Web services also work well in a distributed environment because they

use URLs to reference programs.

You can also add other types of tasks.

Before you begin

Before you add any type of task, you must specify an event condition.

When you specify the web service URL, IBM Cognos Event Studio calls a web server and requests the Web

Services Description Language (WSDL). This shows you the web service input and output parameters.

Note: Before you can run a web service task in Cognos Event Studio, you must follow additional

preparation steps. For more information, see “Preparing to Run a Web Service Task” on page 39

Procedure

1. In the I want to area, click Add a task.

2. Click Advanced.

3. Click Call a Web service.

4. In the Web service URL box, type the URL of the web service.

If the URL points to a web site address, you must include the protocol, such as http.

5. Click Retrieve.

The available web service operations are retrieved.

6. Under Operation, click the web service operation you want to perform.

The available method and the list of arguments is retrieved.

7. If the operation includes arguments, under Arguments, choose how to specify values for each

argument:

• If you are using a value, in the Method column, click Use a value, click Specify values, and in the

Value column, type a value.

• If you are using an item, in the Method column, click Use an item and drag an item from the source

tab or from the data items tab to the Value column.

Tip: To clear the argument values and return to the default values, click Reset to default.

IBM Cognos Analytics Version 11.1: Event Studio User Guide

8. From the File menu, click Save .

Results

You can preview the web service task. When the agent performs the web service task, it calls the web

service and runs its service.

Example - Adding a Web Service Task

You want to notify customer service representatives and suppliers about orders that have a high rate of

return. You could do this by adding an e-mail task. However, you know that some of the service

representatives and suppliers do not have access to e-mail. You also know that they all closely monitor

the Customer Relationship Management (CRM) system.

You decide to notify the service representatives and suppliers by creating records in the CRM system.

Each record is linked to a customer name and to the type of product that was returned. Your company

developed a web service that creates CRM records. In IBM Cognos Event Studio, you add a web service

task that calls your company's web service.

When the agent performs the web service task, the web service updates the prole of customers who

returned products. An updated customer prole can improve your sales performance in two ways:

• It helps the services representative contact the customer quickly to resolve the current problem.

• It helps the supplier ensure that they don't make the mistake of supplying a particular product to that

customer again.

Add an Export Task

Add an export task to an agent to export entries to a deployment archive.

For more information, see the IBM Cognos Administration and Security Guide.

You can also add other types of tasks.

Before you begin

Before you add any type of task, you must specify an event condition.

Procedure

1. In the I want to area, click Add a task.

2. Click Run an export.

3. Click Select the export, and specify the export to include in the agent.

• Search the folders to nd the export you want.

• Click the entry and click OK.

4. From the File menu, click Save

Results

You can preview the export task.

Add an Import Task

Add an import task to an agent to import entries from a deployment archive to your target environment.

For more information, see the IBM Cognos Administration and Security Guide.

You can also add other types of tasks.

Before you begin

Before you add any type of task, you must specify an event condition.

Chapter 2. Creating an Agent

Procedure

1. In the I want to area, click Add a task.

2. Click Run an import.

3. Click Select the import and specify the import to include in the agent.

• Search the folders to nd the import you want.

• Click the entry and click OK.

4. From the File menu, click Save

Results

You can preview the import task.

Add a Content Maintenance Task

Add a content maintenance task to an agent to run a content maintenance task. A content maintenance

task searches the content store for user information that no longer exists in your external namespaces. It

can also x the content store by deleting any users that do not exist in your external namespaces.

For more information, see the IBM Cognos Administration and Security Guide

You can also add other types of tasks.

Before you begin

Before you add any type of task, you must specify an event condition.

Procedure

1. In the I want to area, click Add a task.

2. Click Run a content maintenance task.

3. Click Select the content maintenance task and specify the content maintenance task to include in

the agent.

• Search the folders to nd the content maintenance task you want.

• Click the entry and click OK.

4. Under Mode, choose whether to nd or nd and x problems:

• To nd user information that no longer exists in your external namespaces, click Find only.

• To nd and delete from the content store any users that do not exist in your external namespaces,

click Find and x.

5. From the File menu, click Save

Results

You can preview the content maintenance task.

Add a Planning Macro Task

Add a planning macro task to an agent to run Contributor macros when specied conditions are met. A

planning macro is created in IBM Cognos Planning Contributor to automate tasks such as loading import

data and publishing data.

For more information about planning macros, see the IBM Cognos Planning Contributor Administration

Guide.

You can also add other types of tasks.

IBM Cognos Analytics Version 11.1: Event Studio User Guide

Before you begin

Before you add any type of task, you must specify an event condition.

Procedure

1. In the I want to area, click Add a task.

2. Click Advanced.

3. Click Run a planning macro task.

4. Click Select the planning macro and specify the task to include in the agent.

• Search the folders to nd the task you want.

• Click the entry and click OK.

5. From the File menu, click Save .

Results

You can preview the task.

Add a Migration Task

Add a migration task to an agent to migrate IBM Cognos Series 7 PowerPlay

content to IBM Cognos

PowerPlay. The migration task must be dened in IBM Cognos Administration.

For more information on dening a migration task, see the IBM Cognos PowerPlay Migration and

Administration Guide.

You can also add other types of tasks.

Before you begin

Before you add any type of task, you must specify an event condition.

Procedure

1. In the I want to area, click Add a task.

2. Click Advanced.

3. Click Run a migration task.

4. Click Select the migration task and specify the task to include in the agent.

• Search the folders to nd the task you want.

• Click the entry and click OK.

5. From the File menu, click Save

Results

You can preview the task.

Specify the Task Execution Rules

Task execution rules specify when a task is performed. By default, a task is performed for new instances

of events and all ongoing instances of events, but you can change this.

For more information, see “Change the Task Execution Rules for a Report Task” on page 45 or “Change

the Task Execution Rules for an Email Task” on page 47.

You specify the task execution rules separately for each task in the agent.

Chapter 2. Creating an Agent

Before you begin

Before you specify the task execution rules, you must add one or more tasks.

Procedure

1. In the I want to area, click Manage the task execution rules .

2. On the Event Key tab, click one of the following:

• Include all items (default)

• Include only selected items, then on the source tab , click one or more data items that

uniquely dene an event and drag it to the box.

For example, click Order Number, because no two event instances can have the same order

number.

The event key is dened for all tasks in the agent.

3. Click the Event Selection tab.

4. In the Task box, click the task that the agent will perform for the event statuses you specify.

5. Under Select when to perform each task page, click one of the following:

• For selected events, and select one or more event status values.

• When the agent or any of its tasks fail.

6. Click OK.

The execution rules for each task you selected are set.

Tip: If you want to reset the execution rules for every task in the agent to the default values, from the

Actions menu, click Remove Task Execution Rules. Each task is reset to be performed for new

instances of events and all ongoing instances of events.

7. Save the agent.

Preview the Data

You can see the list of events detected when the event denition is applied to the current data. You can

also see preview information about each task in your agent.

For example, you are an administrator and want to preview the event list and all the tasks before you

make the agent available for other people to use.

The preview information for each type of agent item is described in the following table.

Agent item

Preview information

The event list A table appears with columns for each data item contained in the event condition.

For each event instance, a row appears that shows the value of each data item.

e-mail task Representations appear of all e-mails that would be sent using the default task

execution rules. Data items in the recipient, subject, and body elds are replaced

by values from the source data.

News item task A representation appears of the news item that would be created using the default

task execution rules. Data items in the recipient, subject, and body elds are

replaced by values from the source data.

34 IBM Cognos Analytics Version 11.1: Event Studio User Guide

Agent item Preview information

Report task If the report accepts prompt values, a table appears with columns for each

parameter. For each event instance, a row appears that contains the prompt

values.

If the report does not accept prompt values, a sentence appears telling you that the

report will run once.

Job task A sentence appears telling you that the task will run once.

Agent task If the agent accepts prompt values, a table appears with columns for each

parameter. For each event instance, a row appears that contains the prompt

values.

If the agent does not accept prompt values, a sentence appears telling you that the

agent will run once.

Approval request

task

A representation appears of the approval request that would be created using the

default task execution rules. Data items in the recipient, subject, and body elds

are replaced by values from the source data.

In addition, a table appears indicating the approval request deadlines, priority, and

action button names.

Notication

request task

A representation appears of the notication request that would be created using

the default task execution rules. Data items in the recipient, subject, and body

elds are replaced by values from the source data.

In addition, a table appears indicating the priority and notication request options.

Database update

task

If the stored procedure accepts arguments, a table appears with columns for each

argument. For each event instance, a row appears that contains the argument

values.

If the stored procedure does not accept arguments, a sentence appears telling you

that the stored procedure will run once.

Web service task If the web service accepts arguments, a table appears with columns for each

argument. For each event instance, a row appears that contains the argument

values.

If the web service does not accept arguments, a sentence appears telling you that

the web service will run once.

Export task A sentence appears telling you that the task will run once.

Import task A sentence appears telling you that the task will run once.

Content

maintenance task

A sentence appears telling you that the task will run once.

Planning macro

task

A sentence appears telling you that the task will run once.

Migration task A sentence appears telling you that the task will run once.

Items shown on the preview pages show data for every event instance in the event list. If you change the

task execution rules, the preview data remains the same. For more information, see “Specify the Task

Execution Rules” on page 33.

Before you begin

Before you can preview data, you must dene an event condition.

Chapter 2. Creating an Agent

Procedure

From the Actions menu, click Preview All or Preview.

Results

The Preview All report begins with a table of contents that contains links to the preview information for

each agent item. The Preview report shows preview information for the agent item on the current page.

Create a Schedule for an Agent

By scheduling an agent to run at regular intervals, you do not have to manually run the agent. The agent

monitors data and performs tasks to ensure that problems are dealt with as soon as possible.

Only one schedule can be associated with each agent. If you require multiple schedules for an agent,

create agent views and then create a schedule for each view.

Procedure

1. In the I want to area, click Schedule the agent.

2. Under Frequency, select how often you want the schedule to run.

3. Under Start, select the date and time when you want the schedule to start.

4. Under End, select when you want the schedule to end.

Tip: If you want to create the schedule but not apply it right away, select the Disable the schedule

check box. To later enable the schedule, clear the check box.

5. If you want to override the default values that you dened for the agent, under Prompt values, select

the check box.

6. Click OK.

Specify Default Options for an Agent

Specify default options for an agent when you want every task in the agent to use the same values for

report task options or content maintenance options.

Procedure

1. From the Actions menu, click Set Default Options for All Tasks.

2. Specify the default options you want.

3. From the File menu, click Save

Allow Users to Subscribe to the Alert List of the Agent

You can specify that you want users to be able to add their e-mail addresses to the agent alert list.

When the agent runs, the alert list is added to the Bcc box in all e-mails sent using e-mail tasks or report

tasks.

Procedure

1. From the Actions menu, click Manage Alert List.

2. Select the Allow users to add themselves to the alert list check box.

Tip: If you want to remove everyone from the alert list, click Remove all.

3. From the File menu, click Save

IBM Cognos Analytics Version 11.1: Event Studio User Guide

Change the Order in Which to Run Tasks

You can change the order in which to run tasks. By default, all tasks run at the same time. These tasks are

called parallel tasks. If some tasks require a signicant amount of processing time, parallel tasks can

save time.

Note: For parallel tasks, tasks are run in a specic order, depending on the task types included in an

agent.

You can also specify that one task nishes before the next task begins. These tasks are known as

sequential tasks.

For example, an agent runs a report task that saves a prompted report. Next, the agent runs an e-mail

task and attaches the saved report. For more information, see Chapter 3, “Tutorial,” on page 41.

If your agent contains any of the following tasks, and the task includes a saved report from a report task,

you must order the tasks in a particular way:

• email task

• approval request task

• notication request task

You must order the e-mail task or request task after the report task. If you do not order the tasks in this

way, the saved report output or report link is missing from the e-mail or request that is created.

Procedure

1. In the I want to area, click Reorder the tasks .

2. Choose whether to specify the order or run all tasks at the same time:

• To run the tasks in a specic order, click In sequence and, in the Tasks box, click tasks and change

their order by clicking Up or Down.

• To run all the tasks in parallel, click All at once.

3. Click OK.

4. From the File menu, click Save .

Modify an Event Condition

Modify an event condition when you want to change the data instances that prompt the agent to perform

its tasks.

Procedure

1. Click the edit agent button for the agent you want to modify.

2. In the summary area, click the Event tab.

3. Change the values as required. For more information about the values required for an event condition,

see “Specify an Event Condition” on page 17.

4. From the File menu, click Save .

Chapter 2. Creating an Agent

Modify or Delete a Task

Modify or delete a task when you want to make changes to any of the tasks in the agent.

If you want to add a task, in the I want to area, click Add a task, and click a task type. For more

information, see “Adding Tasks” on page 19.

Procedure

1. Click the edit agent button

for the agent you want to modify.

2. If you want to modify a task, do the following:

• In the summary area, under Tasks, click the tab for the task you want.

• Change the values as required. For more information about the values required for each type of task,

see “Adding Tasks” on page 19.

3. If you want to delete a task, do the following:

• In the summary area, under Tasks, click the tab for the task you want to delete.

• From the Edit menu, click Delete .

4. Save the agent.

Modify the Task Execution Rules

Modify the task execution rules when you want to change the list of event instances for which a task is

performed.

Procedure

1. Click the edit agent button for the agent you want to modify.

2. In the I want to area, click Manage the task execution rules.

3. Change the values as required. For more information, see “Specify the Task Execution Rules” on page

33.

4. If you want to reset the task execution rules to the default values, from the Actions menu, click

Remove Task Execution Rules.

The task is performed for new instances of events and all ongoing instances of events.

5. From the File menu, click Save .

Test an Agent

Before you run an agent, you can test whether certain conditions are met to increase the chance that the

agent runs successfully.

The conditions are as follows:

• The event condition is a valid query expression.

• All parameters are satised correctly.

• All referenced data items exist.

Procedure

1. From the Actions menu, click Validate .

IBM Cognos Analytics Version 11.1: Event Studio User Guide

The View the validation results dialog box appears.

2. If an error message appears, x the error and then repeat steps 1 to 2.

If an error message appears when you run the agent, write down the error message and troubleshoot

the problem.

For more information, see the Troubleshooting section of the IBM Cognos Analytics Administration and

Security Guide.

3. When the No Errors message appears, click OK.

Results

The agent is now ready to run.

Preparing to Run a Web Service Task

Before you can run a web service task in IBM Cognos Event Studio, you must generate the required Java

object (.jar) le for the web service and register the domain name for the web service.

Generating a Java Object File

When you generate Java object (.jar) les, the folder c10_location\webapps\p2pd\WEB-INF\lib

\es_ws_objs is created automatically, and les are stored here by default.

If you are an administrator, you can change this folder using IBM Cognos Conguration.

To generate .jar les, you must be running Java Development Kit (JDK) with a Java compiler (javac.exe).

Note: If you are running multiple web services, you must generate a separate .jar le for each one.

Because each generated le has the same le name, you must rename each .jar le before generating the

next one.

Procedure

1. On a Windows operating system, open the le c10_location\bin\es_build_ws_objs.bat in an

XML editor.

On non Windows operating systems, open the le c10_location\bin\es_build_ws_objs.sh in

an XML editor.

2. Modify the JAVA_HOME environment variable to point a JDK location.

3. Run the following command from the c10_location\bin location:

On a Windows operating system, type

es_build_ws_objs <web_service_URL>

For example, es_build_ws_objs http://wtwincqclab7/ws6/service.asmx?wsdl

On non Windows operating systems, type

./es_build_ws_objs.sh <web_service_URL>

This command generates a le named es_ws_objs.jar in the specied location.

The following steps are optional, and only required if you want to change the default location for your

Java object les.

4. Start IBM Cognos Conguration.

5. In the Explorer window, click Local Conguration.

6. In the Properties window, next to Advanced properties, click inside the Value box, and then click

the edit button.

7. Click Add, and then type the following property name in the Name box:

emf.webservice.objs.folder

Chapter 2. Creating an Agent

Note: You must create this folder manually in your directory structure.

8. In the Value box, type the required folder location.

Note: The location must be accessible to the server user.

9. Click OK, and save your changes.

10. Restart the services.

Registering the Domain Name

You must register the domain name for the web service in the IBM Cognos Application Firewall (CAF)

using IBM Cognos Conguration.

Procedure

1. Start Cognos Conguration.

2. In the Explorer window, under Security, click IBM Cognos Application Firewall.

3. Add host and domain name to the Cognos list of valid names:

• For the Valid domains and hosts property, click the value and then click the edit button.

• In the Value - Valid domains or hosts dialog box, click Add.

• In the blank row of the table, click and then type the host or domain name.

4. Click OK, and save your changes.

5. Restart the services.

40 IBM Cognos Analytics Version 11.1: Event Studio User Guide

Chapter 3. Tutorial

This tutorial shows how the various tasks in creating an agent are related to each other. It shows that

managing task execution rules is performed for each task in an agent, but that specifying an event

condition is performed once for an agent.

Scenario

You are the Director of Sales of a company. The Finance department identied a problem with invoice

payments. Analysis of warehouse data shows that a large proportion of late payments are by customers

who returned damaged or faulty items and did not receive replacements.

Customers tend to withhold payment for the entire order even if only one or two items are in dispute.

They may even refuse to pay for other completed orders until the disputed order is resolved.

Therefore, rapid resolution of the returns issues has a direct effect on cash flow. The Director of Finance

asks you to establish a process that closely monitors data for problems with high rates of return and takes

immediate action to resolve any problem it detects.

Solution

You decide to use IBM Cognos Event Studio to detect event instances and notify the people who must

quickly resolve the issue.

You create an agent named high_returns_followup. The agent detects cases where the actual value of

returned products is greater than the threshold value that the person running the agent denes. You

include a parameter in the event condition to represent this threshold value. Initially, you concentrate on

large return orders because they have the greatest effect on cash received. After you address problems

with the largest returns, you monitor lower valued returns.

To provide sales representatives with customer contact information, you decide to add a report task that

runs the Customer Contact report. The sales representatives can then quickly call the retailer and try to

resolve the issue.

Before you can distribute the report, you require a sales manager to approve and sign it off as being

accurate, so you decide to an approval request task.

When you add the e-mail task to distribute the report, you specify that the e-mail message be in HTML

format. When you edit an HTML message, you can click a button that inserts a table. You list return values

by order number in the table. Then you attach to the e-mail message both the report that you saved in the

report task and the event list that shows the event instances for which the agent performed its tasks.

To create this example agent, perform the following tasks:

• Start Cognos Event Studio and select the Go Sales (query) package.

• Dene a parameter named total_return_value_for_item.

• Dene a calculation named order_item_return_value_calc.

• Specify an event condition that contains the calculation and parameter.

• Add a report task that saves a report customized with contact information for the retailers who returned

the products.

• Change the task execution rules for the report task.

• Add an approval request task that sends the report to the sales manager for sign-off.

• Add an e-mail task that sends an email to the sales representative for the returned product. Attached to

the email is the approved report.

• Change the task execution rules for the email task.

• Add a news item task that publishes a dynamic headline that shows the current value of preventable

returns.

• Schedule the agent.

• Save the agent.

• Run the agent.

Start IBM Cognos Event Studio

You want to start IBM Cognos Event Studio and ensure that your agent uses a data package that it can

monitor for the events you want and that it can use to perform tasks.

You decide to use the Go Sales (query) package because it contains data items related to returned

products, retailers, and order details.

Procedure

1. Click the Event Studio link

2. In the Select a package window, click Go Sales (query).

Cognos Event Studio opens in a new window. The data items you can use are listed in the Insertable

Objects area.

Dene a Parameter to Insert Into an Event Condition

You want to dene a parameter named total_return_value that you can insert into an event condition.

Procedure

1. From the Insert menu, click Parameter.

2. In the Parameter name box, type

total_return_value_for_item

3. Click OK.

Results

To see the parameter, in the Insertable Objects area, click the parameters tab .

Dene a Calculation to Insert Into an Event Condition

You want to dene a calculation named total_return_value_calc that you can insert into an event

condition. This calculation must determine the total value of each order returned.

Procedure

1. From the Insert menu, click Calculation.

2. In the Name box, type

order_item_return_value_calc

3. In the Expression box, do the following:

• In the Insertable Objects area, click the functions tab and expand Summaries.

• Click the total function item, and drag it to the Expression box.

• In the Insertable Objects area, click the source tab and expand Returned items (query).

IBM Cognos Analytics Version 11.1: Event Studio User Guide

• Under Returned items (query), expand Returned items.

• Click the Return quantity measure item, and drag it to the Expression box.

• After you insert the source item, type for.

• Under Returned items (query), expand Order.

• Click the Order number item, and drag it to the end of the expression.

• After you insert the source item, type a closing parenthesis.

The calculation expression is dened as follows:

total([Returned items (query)].[Returned items].[Return quantity]for[Returned items (query)].[Order].

[Order number])

4. Click OK.

Results

The calculation appears as a calculation icon on the data items tab.

Specify an Event Condition

You want the agent to detect cases where the actual value of returned products is greater than the

threshold value that the person running the agent denes.

Also, you want to see what parameter value would return an event list of between 5 and 10 items from

the current data.

Procedure

1. Click the Detail tab.

2. In the Insertable Objects area, click the source tab .

3. Expand Returned items (query).

4. Under Returned items (query), expand Returned items.

5. Click the Return quantity measure item, and drag it into the expression box.

6. After the source item you just inserted, type

> 0 and

7. On the data items tab , click the order_item_return_value_calc calculation that you dened

previously, and drag it to the end of the expression.

8. At the end of the expression, type a greater than symbol:

9. Click the parameters tab , click the total_return_value parameter that you dened previously,

and drag it to the end of the expression.

10. At the end of the expression, type

and

11. On the source tab, under Returned items (query), expand Return reason.

12. Click Reason description, and drag it to the end of the expression.

13. At the end of the expression, type

14. To include only the description types you want, do the following:

• On the source tab, under Return reason, click Reason description.

Chapter 3. Tutorial

• Above the Expression box, click the select value button .

• In the Select Value window, use Shift+Click to select Incomplete product, Unsatisfactory

product, and Defective product.

• Click the insert button , and click OK.

The detail expression appears as follows:

[Return quantity]>0 and [order_item_return_value_calc]>?total_return_value_for_item? and [Reason

description] in ('Defective product','Incomplete product','Unsatisfactory product')

15. Do the following to see whether an event list of between 5 to 10 items is returned when the total

return value calculation exceeds $4000:

• From the Actions menu, click Preview.

• On the report viewer Prompt pages, in the Provide a number box, type

4000

• Click OK.

Add a Report Task

Sales representatives must ensure that items returned for a preventable reason are not returned again for

the same reason. You want to save a report of customer contact information associated with the

excessive rate of return event that you dened. Sales representatives can use this information to contact

the retailer, discuss how to prevent future returns, and then take the appropriate action.

You decide to add a report task that runs the sample report named Customer Contact. When the agent

runs the report task, the value of the Retailer name data item for each event instance is passed to the

report output.

By adding an email task, you can include additional information in the e-mail message that you cannot

include using the report task.

Procedure

1. In the I want to area, click Add a task.

2. Click Run a report.

3. Specify the report that you want to run:

• Click Public Folders, and click Go Sales (query).

• Click Event Studio Samples.

• Click Customer Contact Report and click OK.

4. Under Options, click Set.

5. Specify the run options that you want:

• Select the Override the default values check box.

• Under Formats, select the PDF check box and ensure that none of the other check boxes are

selected.

• Under Delivery, select the Save check box, and ensure that Save the report is selected.

• Click OK.

6. Specify the prompt values that you want:

• In the Method column, click Use an item.

• In the Insertable Objects area, click the source tab and expand Sales (query), Retailer.

IBM Cognos Analytics Version 11.1: Event Studio User Guide

• Click Retailer name, and drag it to the Value box.

7. Save the agent.

Change the Task Execution Rules for a Report Task

The status of each event instance is obtained by comparing the event instances of the current run of the

agent to those of the previous run. You want to specify which event statuses will cause the agent to

perform the report task.

You know that for the event condition you specied, the Product name, Retailer name, and Order

method data items have duplicate values in two or more event instances. However, because the Order

number data item has a different value for each event instance, you choose it as the event key.

You decide that the report task that you added previously should be performed for both:

• new event instances

New event instances are instances that are detected when the agent runs and were not previously

detected.

• ongoing event instances in which the return quantity has changed

Ongoing event instances are detected when the agent runs and have previously been detected. In this

case, only ongoing event instances in which the return quantity has changed cause the report task to

run.

Procedure

1. In the summary area, click new report.

2. In the I want to area, click Manage the task execution rules.

3. Click the Event Key tab.

4. Click Include only selected items.

5. On the source tab , expand Returned items (query) and Order.

6. Under Order, click Order number, and drag it to the Event key box.

7. Click the Event Selection tab.

8. Under Select when to perform each task, select the New events and Ongoing events check boxes.

This chooses the event status for which the report task is performed.

9. Click OK.

10. Save the agent.

Add an Approval Request Task

You require a sales manager to approve the accuracy of the report that you saved previously and to sign it

off before it is distributed to the sales representatives.

You decide to add an approval request task. When the agent is run, a task will be created within My Inbox

in IBM Cognos Analytics and notications will be sent via email to the potential owner and stakeholder

identied for the task.

For more information on approval request tasks, see “Add an Approval Request Task” on page 25.

Note: When you add an approval request, the task execution is automatically set to sequential.

Procedure

1. In the I want to area, click Run an approval request.

Chapter 3. Tutorial

2. Click the source tab , and expand Sales (query).

3. Expand Sales Staff.

4. Click Manager Email and drag it to the Potential owners box.

Note: You are automatically added as a stakeholder of the task.

5. In the Subject box, type

Customer Contact Report for Approval

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

7. To add the email distribution list for the sales representatives to the message:

• Click the source tab, and expand Sales (query).

• Expand Sales Staff.

• Click Email and drag it to the end of your message.

8. Save the agent.

Add an Email Task

When the Customer Contact report has been approved by the sales manager, you want to notify sales

representatives about orders that have a high rate of return.

You decide to add an email task. You specify that the e-mail message use HTML format. When you edit an

HTML message, you can click a button that inserts a table. You list return values by order number in a

table. Then you attach to the email message both the report that you saved previously, and the event list

showing the event instances for which the agent performed its tasks.

Note: The email task will only execute if the approval request that you previously added is approved by

the potential owner.

Procedure

1. In the I want to area, click Add a task.

2. Click Send an email.

3. Click the source tab , and expand Sales (query).

4. Expand Sales Staff.

5. Click Email and drag it to the To: box.

6. In the Subject box, type

Urgent: Please contact customer

7. In the Body box, type:

Please contact your customer about the following returned order(s), and

determine how to prevent it from happening again

8. Add a table to the Body message:

• Click the insert table button .

• Type 4 in the Number of columns box, type 2 in the Number of rows box, and click OK.

9. Type the column headings in the rst row:

• In the rst cell, type

Order Number

IBM Cognos Analytics Version 11.1: Event Studio User Guide

• In the second cell, type

Value of items returned

• In the third cell, type

Reason description

• In the fourth cell, type

Customer name (see attached contact information)

10. Select the heading row, and click the bold button .

11. Enter data items in the second row:

• Click the source tab, expand Sales (query), then expand Order, and click Order number and drag it

to the rst cell.

• Click the data items tab , click total_return_value_calc, and drag it to the second cell.

• Click the source tab, expand Returned items (query), then expand Return reason, and click

Reason description and drag it to the third cell.

• Expand Sales (query), then expand Retailer site, and click Retailer name and drag it to the fourth

cell.

12. In the Body box, after the table, type

Thanks, the GO Sales Customer Loyalty Team

13. Click Attach, and click Attach the event output.

14. Click Attach, and click Attach the report Customer Contact.

15. Save the agent.

Change the Task Execution Rules for an Email Task

The status of each event instance is obtained by comparing the event instances of the current run of the

agent to those of the previous run. You want to specify which event statuses will cause the agent to

perform the email task.

You know that for the event condition you specied, the Product name, Retailer name, and Order

method data items have duplicate values in two or more event instances. However, because the Order

number data item has a different value for each event instance, you choose it as the event key.

You decide that the email task you added previously should be performed only for event instances that

did not appear in the event list the last time the agent was run.

Tip: You can add multiple tasks to an agent and use task-level lters to include only those events that

satisfy a Boolean condition. See “Example - Task-Level Boolean Filter” on page 7.

Procedure

1. In the summary area, click new message.

2. In the I want to area, click Manage the task execution rules.

3. Under Select when to perform each task, select the New events check box and ensure that none of

the other check boxes are selected.

4. Click OK.

5. Save the agent.

Chapter 3. Tutorial

Add a News Item Task

The customer fullment manager wants to be informed of the current preventable returns. However, he

does not always check his e-mail. He prefers to view important updates on a Web dashboard that he

checks regularly.

You decide to add a news item task that updates a headline with the total value of returns that are

preventable. That is, you publish the values of products returned because they are incomplete, defective,

or unsatisfactory.

Procedure

1. Create a folder named High Returns.

• Click the new folder button

• In the Name box, type

High Returns

• Under Location, click Select My Folders.

• Click Finish.

The High Returns folder appears in My Folders.

2. In IBM Cognos Event Studio, in the I want to area, click Add a task.

3. Click Publish a news Item.

4. In the Headline box, type Preventable Returns for Large Value Individual Items.

5. Drag the calculation data item total_return_value_calc to the end of the text you just typed.

6. Under Link to, choose what you want to link to:

• Click Select an entry.

• Click Public Folders, and click Go Sales (query).

• Click Event Studio Samples.

• Click Customer Contact Report and click OK.

7. Under News list location, click Select a location, go to the High Returns folder in which the news

item will be published and click OK.

8. Under Run this news item for the events, review the event status that will cause the news item to be

published.

9. From the File menu, click Save.

Results

When the agent performs the news item task, it publishes the news item to the My Headlines folder.

The description text appears when you set your preferences to use the details view. The screen tip

appears when you pause your pointer over the icon for the entry in the news list location.

Schedule an Agent

When the excessive rate of return event you dened occurs, signicant potential revenue has already

been lost. Following up on returned products increases your shipping charges and administration fees.

However, the most important impact of returned products is that they can reduce customer loyalty and

decrease your future sales. Therefore, it is important that you respond quickly to an event instance as

soon as it occurs.

You decide that you can provide a timely response to event instances by monitoring the data hourly. You

also decide that $17,000 is an appropriate threshold value for this initial schedule.

IBM Cognos Analytics Version 11.1: Event Studio User Guide

Procedure

1. In the I want to area, click Schedule the agent.

2. Under Frequency, click By Day, and ensure that the frequency is Every 1 hour(s).

3. Under Start, select the date of tomorrow, and specify the time as 9:00 AM.

4. Under End, click No end date.

Tip: You can edit the schedule later if you want to add an end date.

5. Under Prompt values, select the Override the default values check box, and then click Set.

6. On the prompt page, in the Provide a number box, type

17000

7. Click OK twice.

Results

A schedule is created and the high_returns_followup agent runs hourly, starting tomorrow at 9:00 a.m.

Save an Agent

You want to save the agent in My Folders. You also want to give the agent a meaningful name and

description so that you can easily distinguish it from other agents.

Procedure

1. From the File menu, click Save.

2. If this is the rst time you are saving the agent, in the Save As dialog box, describe the agent:

• In the Name box, type

high_returns_followup

• In the description eld, type

This agent checks for orders that have a high value of returned products.

It then sends a report by e-mail to the appropriate sales reps so that they

can contact the retailers and prevent future returns.

• Ensure that the Location is set to My Folders.

• Click OK.

Results

The agent high_returns_followup appears in My Folders, next to an agent icon

Run an Agent

You decide to run the agent immediately to test the results.

If you want to successfully run the agent described in this tutorial, you must rst perform the tasks in all

the other examples. For more information, see Chapter 3, “Tutorial,” on page 41.

Procedure

1. In My Folders, click the run with options button on the actions toolbar next to the

high_returns_followup agent.

2. Under Time, click Now.

3. Under Prompt Values, select the Prompt for values check box.

Chapter 3. Tutorial

4. Click Run.

5. On the Prompt page, in the Provide a number box, type

17000

6. Click OK twice.

Results

The high_returns_followup agent runs using the prompt value you entered. To see the results of the run,

you can review the run history of the agent.

50 IBM Cognos Analytics Version 11.1: Event Studio User Guide

Chapter 4. Troubleshooting

This chapter describes some common problems you may encounter.

You can nd more troubleshooting topics in the Troubleshooting section of the IBM Cognos

Administration and Security Guide.

A Report Link in an Email Notication Does Not Work

If a report link in an email notication does not work, the Gateway URI may not be congured correctly.

You must change the host name portion of the Gateway URI from localhost to either the IP address of the

computer or the computer name. If the URL in the email contains localhost, remote users cannot open the

report.

The Page Cannot Be Found Error Appears for Reports

When a report is distributed by email, no error message appears if the report output from the email link is

not available. This can occur when the output is deleted or when the user does not have permissions to

the report. Instead, the error The Page Cannot Be Found appears.

You are unable to view the report output from the email link when Allow Anonymous Access is set to

True and when the Anonymous user does not have access to the report output.

When you run a secured report from an email link and when Allow Anonymous Access is set to True, a

passport is automatically issued to the Anonymous user. The Anonymous user is not prompted to log on

and is unable to view the report output.

Metadata Change in Oracle Essbase Not Reflected in Reports and in the

Studios

When there is a metadata change on the Oracle Essbase server, the change is not immediately reflected

in the metadata tree in the studios. In addition, when a report is run, the report does not pick up the

republished changes.

To view the new structure, you must restart the IBM Cognos Content Manager server.

Errors When Running Web Service Tasks

When running a Web service task, you might encounter errors.

You must modify one the following les to add the ThreadStackSize (Xss) parameter:

• bootstrap_win32.xml in the bin folder for a 32-bit installation

• bootstrap_win64.xml in the bin64 folder for a 64-bit installation

Adding this parameter prevents these errors:

CNC-ASV-0001 The Following Agent Service General Error Occurred: java.lang.StackOverflowError

CNC-ASV-0007 An error occurred with the agent Web service task.

Procedure

1. Open the appropriate version of the install_location\bin\bootstrap_win.xml le in an XML editor.

2. Add the following text for the parameter (shown in bold) exactly as shown here:

...

<condValue="Sun">-XX:NewSize=${dispatcherMaxMemoryBy4}m</param>

<param condName="${java_vendor}" condValue="Sun">-XX

<process name="catalina"> ...<param condName="${java_vendor}"

condValue="Sun">-XX:MaxPermSize=512m</param><

param condName="${java_vendor}"

condValue="IBM">-Xss512m</param>

The maximum stack size (Xss) parameter is set to 512 MB to avoid an overflow exception error.

Email editing toolbar buttons not available in Firefox 14.01 or Firefox 10.06

When you create an email to send to an individual, group or dynamic recipient, the editing toolbar buttons

are not available when you use Firefox 14.01 or Firefox 10.06.

These toolbar buttons are available in Microsoft Internet Explorer.

52 IBM Cognos Analytics Version 11.1: Event Studio User Guide

Notices

This information was developed for products and services offered worldwide.

This material may be available from IBM in other languages. However, you may be required to own a copy

of the product or product version in that language in order to access it.

IBM may not offer the products, services, or features discussed in this document in other countries.

Consult your local IBM representative for information on the products and services currently available in

your area. Any reference to an IBM product, program, or service is not intended to state or imply that only

that IBM product, program, or service may be used. Any functionally equivalent product, program, or

service that does not infringe any IBM intellectual property right may be used instead. However, it is the

user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

This document may describe products, services, or features that are not included in the Program or

license entitlement that you have purchased.

IBM may have patents or pending patent applications covering subject matter described in this

document. The furnishing of this document does not grant you any license to these patents. You can send

license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation

North Castle Drive

Armonk, NY 10504-1785

U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property

Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing

Legal and Intellectual Property Law

IBM Japan Ltd.

19-21, Nihonbashi-Hakozakicho, Chuo-ku

Tokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any other country where such

provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION

PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR

IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,

MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of

express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically

made to the information herein; these changes will be incorporated in new editions of the publication.

IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this

publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in

any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of

the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without

incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the

exchange of information between independently created programs and other programs (including this

one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Software Group

Attention: Licensing

3755 Riverside Dr.

Ottawa, ON

K1V 1B7

Canada

Such information may be available, subject to appropriate terms and conditions, including in some cases,

payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by

IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any

equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the

results obtained in other operating environments may vary signicantly. Some measurements may have

been made on development-level systems and there is no guarantee that these measurements will be the

same on generally available systems. Furthermore, some measurements may have been estimated

through extrapolation. Actual results may vary. Users of this document should verify the applicable data

for their specic environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their

published announcements or other publicly available sources. IBM has not tested those products and

cannot conrm the accuracy of performance, compatibility or any other claims related to non-IBM

products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of

those products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal without

notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business operations. To illustrate

them as completely as possible, the examples include the names of individuals, companies, brands, and

products. All of these names are ctitious and any similarity to the names and addresses used by an

actual business enterprise is entirely coincidental.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Depending upon the congurations deployed, this Software Offering may use session and persistent

cookies that collect each user's

• name

• user name

• password

for purposes of

• session management

• authentication

• enhanced user usability

• single sign-on conguration

• usage tracking or functional purposes other than session management, authentication, enhanced user

usability and single sign-on conguration

These cookies cannot be disabled.

If the congurations deployed for this Software Offering provide you as customer the ability to collect

personally identiable information from end users via cookies and other technologies, you should seek

your own legal advice about any laws applicable to such data collection, including any requirements for

notice and consent.

For more information about the use of various technologies, including cookies, for these purposes, see

IBM's Privacy Policy at https://www.ibm.com/privacy/us/en/

IBM Cognos Analytics Version 11.1: Event Studio User Guide

IBM®