prompts explained

Prompts provide a way to dynamically change the reports.

In other words their function is to "show only this", "show only that', "show between this day and that day".

I think it would be fair to say that a prompt is what appears on the screen and a parameter is a programming variable that stores the users choice.

So prompts and parameters are very closely related, they are practically the same.

A prompt appears minimum in two places. On the prompt page - where we get the value - and in an expression - where we use the value. (Otherwise it would not make sense...)

If a prompt appears in an expression but you forgot to put it on the prompt page then it will be autogenerated by Cognos. You don't want this... it's much better to have control over the prompt page.

However it can appear in more than two places as it gets used in expressions and even in the model. 

If you use DMR it is a good idea to use prompts in the model because you can optimize the performance. e.g. If the user selects only a single branch of a bank then there is no need to calculate all metrics for every branch, you can use the prompt in the model to set a filter on the queries... and everything will run faster.

There are a few important things about prompts that are not obvious from the documentation:

1. In Report Studio you can use the same #prompt()# function as in Framework Manager. (Actually you can use all macro functions.) 
   What you see - what the editor offers - ?Parameter1? is just a shorthand for #prompt('Parameter1', 'string')#
2. You need to refer to prompts in exactly the same way everywhere, in expressions and on the prompt page. Otherwise Cognos gets confused. Thisnk about this when you set a prompt as "required" but its not, or when the prompt pop up again even though it already appeared on the prompt page.
   The property settings should match how the #prompt()# macro is called. 
3. For a prompt being optional is the same thing as having default value. 
   If a prompt has default value then it is optional.
   If a prompt is optional it must have a default value. 
   The only exception is to set the default selection property in Report Studio and set the prompt as required; and then in the expressions not setting a default value. This way the prompt is required and the prompt page can provide the value set as default if you hide the prompt. - This technique allows you to do some tricks...
4. Remember: prompt is a macro. It is just a string replacement. Whatever appears between the hashmarks will be replaced and then the expression will be evaluated.
   If you get an error you can usually see what the prompt macro was replaced with.
   You can also debug the report by droppin a Text Item, setting its source to "Report Expression" and setting the expression to something like ParamValue('parameter1')
   - do not use ParamDisplayValue() .. use ParamValue()
5. Since the prompts will be used in different expressions you get most freedom by setting the prompt type to "token". This way the replacement value won't have quotation marks around it. This is useful. Check the other macro functions such as split(), sq() to build a string from the prompt as needed.
6. Keep in mind the promptmany() function. It is practically the multi-selection prompt.
   If you want the prompt to handle multiple values then you need to use this version. 

Working with prompts using a dimensional model

The prompt can return the parameter value in a number of ways: string, date, token, MUN (Member Unique Name).

If you don't know what MUN is please read the documentation; it is important. It's basically a string identifier for a member of a dimension. It's an ID... plus some extra that helps to figue out what the ID is for. 

When working with dimensional model you want to build a member set from the prompt selection... pretty much always. 

If you think you only need to build a filter expression please think twice.

For a DMR model I'm pretty sure filters should not be used - at all.

and I have the same feeling for an OLAP based dimensional model.

So, forget filters. They are for the people still in the kindergarden who use relational models for BI.

All you want to do is to say which members should appear in a crosstab (or chart) based on the users selection. What you need is a member set.

To build a member set the "string" type of prompt is useless because it is surrounded by single quotes which does not play well with the MUN (Member Unique Name) format.

Either you can get the MUN directly from the prompt() function or you need to build it yourself. In this case "token" is better. It's the same value being returned as when using "string" only without the quotes.

I find that using the question mark shorthand: ?Parameter1? is the same as #prompt('Parameter1', 'string')#

Frankly I'm not 100% sure... but I still prefer using the macro format to be certain of what I'll get.

The easiest thing to build a memberset is to do this:

set( #promptmany('Parameter1', 'MUN' )# )

It gets challenging when you want to make the prompt optional.

If you only return an empty string or a space then after the prompt is processed the expression will look like set( ) ... which Cognos does not like and gives you an error.

Instead use the emptySet function as the prompt's default valuet:

set( #promptmany('OptionalParameter1', 'MUN', emptySet([my_dimension].[my_hierarchy])# )

To have the prompt return MUN you need to set the "Use Value" of its query to a dimension level.

The other option is to build the MUn yourself in the expression. If the MUN has only one ID then it's simple. Something like 

[my_dimension].[my_hierarchy].[my_level]->[all].#sq(prompt('parameter1','token'))#

With DMR model it is often not the case... even if you set a level as "Uniquely Identified" Cognos still includes the business keys of all upper levels in the MUN... which makes it difficult - almost impossible - to build MUNs.

(I think it is a bug in Cognos DMR.)

You can only do it if you prompt the dimension members themselves. then Cognos will do it.

Otherwise... not.

e.g. If you have a hierarchy in the time dimension it can become difficult. Because you want a date prompt - which is not built from the dimension. It's just a calendar.

That's OK... you don't want to use DMR anyways. It sucks. Use real OLAP and take control of how the MUNs are generated.

I figured that with the promptmany function using tokens they are separated by semicolons.

start with #split(';', promptmany('Parameter1', 'token'))# and use the substitute macro to build a lst of MUNs.

Time filtering: From and To

Often you want to run the report for a specified time interval. this is not at easy as it seams.

If you find that a simple filter is not working for you.. and remember, IMO you should never use a filter... then you'll appreciate this tip as building a member set containing all dates between "from" and "to" gets quite challenging.

filter(
[Time Dimension].[My Hierarchy].[Date],
roleValue('_businessKey', currentMember([Time Dimension].[My Hierarchy])) >= #sq(prompt('From', 'Date'))# and 
roleValue('_businessKey', currentMember([Time Dimension].[My Hierarchy])) <= #sq(prompt('To', 'Date'))#
)

i know it's crazy... but this will save you 2 days minimum.

• we're using the filter() function to "build" the member set - by taking away unwanted members.
  
• we rely on the fact that dates as string can be still compared and will maintain the same order as the dates
• note that roleValue() returns the selected attribute as a string, regardless of the attribute's type - which is date in this example

I'll write a post about why filtering should be avoided... so hopefully I'll convince you that I'm not crazy and all this overcomplicated crap is necessary for real life reporting... I mean something other than GO Sales :)

substitute() macro

It's not documented anywhere so here you go:

^ matches the beginning of the string
$ matches the end of the string

Multiple substitute() calls can be nested into one another.

e.g. to put a string into square brackets you could write

substitute('^', '[', substitute('$', ']', '_string_goes_here'))

filter vs tuple

why should you use tuple() and not filters.

First of all

you can only use one filter... but you can write as many tuple expressions as you want.

e.g. Sales is a measure and you want to get its value on 1/1/2008 and 3/1/2008 

How would you do it with a filter? One would make the second impossible.

With tuple expressions you can create calculated data items and call them something like Sales_on_1/1/2008 and Sales_on_3/1/2008

tuple([Sales], [Time Dimension].[date hierarchy].[date]->[2008-01-01])

But I have an even better reason!

Cognos user interface does not distinguish between relational and dimensional or DMR model.

You should!

What does a filter mean when working with a dimensional model?

Who the hell knows.

I think with DMR they (Cognos) add a where clause to the generated SQL... so something will happen... it's just ugly. See how your higher level aggregates will behave...

using tuples() is way more clear!

TUPLE RULEZ!

good nite!

Macro functions - undocumented feature in Report Studio

Did you know that you can use the same macro functions that you have in Framework Manager in Report Studio?

It's not documented in the Report Studio users guide and the GUI which lists the available functions doesn't suggest it either.

Yet, they are there!

Try writing an expression where instead of ?Param1? you write #prompt('Param1')# ... there you go.

This lets you use some very powerful tricks when working with a dimensional model.
Some of which I'll describe later...

How do charts work like crosstabs

I found the graphical interface of charts rather challenging to capture but once you understand that they work exactly like crosstabs you can figure it out:

measure (y-axis) = Deafult Measure
Series = vertical axis
Category (x-axis) = horizontal axis

note that just like a crosstab axis can nest one dimension into another, or add measures on the axis you can do the same in the chart

example crosstab:
note the nesting of Revenue and Gross Profit under Retailer
and
Product type under Month(Time)


the corresponding chart:

note: we have the same nesting

















when we run the report the chart will look like this:

note: the two measures on the legend of the vertical axis

















note: the legend explains the color coding for each combination of retailer and revenue or retailer and profit













whether this complex chart makes sense is a good question... sometimes it does, sometimes it doesn't... the point is: you could if you wanted!

How to use prompt values in a tuple expression

This golden nugget can save you 2 days of work - that's how long it took me to figure out the syntax.

In the tuple() you can use a member to specify which value of the measure you want. This will work much like a filter... just better.

Lest say you have a Sales measure and a Time dimension with Date at the lowest level.

You can write something like this:

tuple([Sales], [Time Dimension].[Date hierarchy].[Date]->[all].[1/1/2008])

this will get you the Sales on 1st Jan. 2008

This is great, but you want to make this a parameter, so the user can specify the date.
Maybe you have a reporting interval called ?ReportStart? and ?ReportEnd? and you want to get the Sales on the last day of the reporting interval.

You can do this:

tuple([Sales], [Time Dimension].[Date hierarchy].[Date]->[all].#sb(prompt('ReportEnd','date'))#

You can use this expression in a crosstab or graph to give you the Sales measure on the end of the reporting interval.

In more generic terms this is the syntax to use prompt parameters in tuple() expressions.

Cognos UI

I found that Cognos uses the same user interface when working on dimensional (including DMR) and relational model.
This causes a lot of confusion because the two work totally different.
To further worsen things there is no error message when you do something that... you just should not do. Even worse... you get some results. But who know what those are!