Documentation is Good

Designer 3.0 is the first time that I have been able to find the extended prompt syntax documented. It even mentions the primary_key attribute which was apparently present (and usable) in XI R2. This feature allows me to create prompts in the Universe Designer that will still leverage Index Awareness, assuming I have set that up.

Here is the prompt syntax shown in the XI 3 Designer manual:

@Prompt(’message’,'type’,[lov],mono/multi,free/constrained/primary_key,per
sistent/not_persistent, [{'default value':'default key'[,'default value':'default
key',...]})

I’ve covered the prompt syntax before so I won’t review everything. But the new features are interesting. The new feature primary_key was used in my “Ninja” presentation from last year with a disclaimer about it being an “undocumented feature” and the note of being a bit risky to use as a result. Now it is not only documented but there is a modifier for the default value option as well.

Using Index Aware Objects With Prompts

Recall that index awareness is designed to create more efficient SQL. Instead of

RESORT.RESORT = 'Bahamas Beach'

I would see

RESORT.RESORT_ID = 2

With the new prompt parameter I can specify the default value in a value:key pair, like this:

RESORT.RESORT_ID = @Prompt('Please select Resort', 'A', 'Resort\Resort', mono, primary_key, not_persistent,{'Bahamas Beach':'2'})

The option mono of course means I will only select one value. That is not new. The option primary_key tells the SQL generator that this object is index aware, and that I want the key to be used rather than the value. The option not_persistent is used to tell the SQL generator that I don’t want to retain the last user selected value. And finally, the string 'Bahamas Beach':'2' is used to show that the default value shown to the user is Bahamas Beach but the default value provided to the prompt is the key value 2 instead.

Special note: if I want to use a default value, then I have to specify not_persistent. If I don’t, then the default value is only good the first time the query is refreshed. From that point forward the last user selection will be used instead.

What About Those {}?

A reader with extremely good attention to detail will notice that the syntax I posted above does not match what was shown in the user manual. In order to get the object to parse I had to follow the exact syntax shown in the function help in Designer rather than what is in the documentation. What’s different? The code I used has curly braces { } around the value:key pair at the end. The curly braces are also used when providing a hard-coded list of values, so I guess that’s not too surprising.

Conclusion

The primary_key and default:key additions to the @prompt() syntax are quite powerful, and should be well-received by universe designers. I feel much more comfortable using something that is documented (even with slight errors) than using a feature that isn’t detailed in the documentation or help files anywhere. The concept of index awareness just became a lot more attractive with this addition.

This feature was one of several mentioned in my Designer Essentials presentation delivered at the 2008 GBN conference. This feature was covered on page 9.

You can’t do it, sorry.

At the end of that post I mentioned something called a “magic date” that I frequently use in my universes to get past this limitation. That’s my subject for today.

Problem Definition

I have a date prompt in my universe. I would like to be able to provide a default value of today’s date. This would allow my users to click-n-go on the report without having to update the date value each time. It is also essential for scheduled reports, which is something I didn’t really touch on last time. When I schedule a report, I have to provide values for every prompt. I have a long series of posts on how to create some dynamic date objects that can be used for scheduling, but those were not prompts.

In a nutshell: I need a way to accept a prompt value and convert it to today’s date for user convenience and for scheduling. Can I make that happen?

Defining the Magic Date

First, a quick recap. When I set up a prompt in the universe, one of the required arguments is the datatype. A ‘D’ designates a prompt as a date value. That means that anything entered in that date prompt field has to pass the basic validation that will be done by the application. I can’t put the word “Today” in this prompt, as “Today” is not anywhere close to being a valid date. That’s where the concept of a “magic date” comes from.

What I do is define a specific date as the magic date. Quite frequently I will use something like January 1, 1900, as it is highly unlikely that any of my records will include that date as a valid entry. That is the first important point about this concept: I must pick a date that will never appear as part of my normal data. That’s my magic date.

Defining the Prompt

Once I have selected my magic date I can now create my prompt using the basic five parameters. It might look something like this:

@prompt('Enter shipping date','D',,mono,free)

In this prompt I am asking for a shipping date, I am expecting a valid date value, there is no list of values, and the user will enter only one value. There’s nothing magical about that prompt. The magic comes in when I create the condition object that includes that prompt. Imagine that I have a report that is designed to show orders that shipped today. Suppose that my magic date is January 1, 1900, as I mentioned before. Here’s what the code looks like (I will explain it after):

orders.ship_date = case when @prompt('Enter shipping date','D',,mono,free) = '1900-01-01' then DATE else @prompt('Enter shipping date','D',,mono,free) end

I’ve used Teradata syntax here but the concept applies to any database. (Teradata offers several options to return the date for “today” and DATE is the example I selected here.) One of two things will happen in this condition. A user will either enter a standard date, or they will enter the magic date. If they enter a standard date the code resolves to this:

orders.ship_date = case when '2008-07-21' = '1900-01-01' then DATE else '2008-07-21' end

In this case the case logic eliminates the first option and takes the second option and the net logic becomes:

orders.ship_date = '2008-07-21'

What if the user enters the magic date? Using the same process the code first resolves to this:

orders.ship_date = case when '1900-01-01' = '1900-01-01' then DATE else '1900-01-01' end

Which is logically the same as this:

orders.ship_date = DATE

So, there I have it. By applying a case statement to the right-hand side of this database condition, I can react in two different ways. In one case I take the user parameter value exactly as entered. In the other case I convert a special date (magic date) into the system current date instead. Now if one of my users schedules a report with this prompt, all they have to do is enter 1900-01-01 as their date parameter and each time their scheduled report is executed the parameter value will change.

Conclusion

With some creative date logic I can convert the magic date to today, yesterday, end of this week, end of last week, end of the month… just about anything else that I’ve already covered in my dynamic date series of posts. I can use the concept of a “magic number” for numeric prompts and a “magic string” for text prompts as well, although those are generally not used as frequently.

Would it be nice if I could use a variable in a prompt to avoid this sort of extra work? Sure, I think it would. I listed a bunch of different prompt enhancements that I have been looking for, in some cases for years, in my last post on prompts. One of those enhancements that I (and a gazillion other folks) would like to see is proper cascading prompts. I plan to have that as my next post on prompts.

Problem Description

I have a report. The report has a date prompt. I want the date prompt to have a default value (partially possible) and I want the default value to be “today” instead of a standard date. The question is quite reasonable, in my opinion. Prompt handling has been one of the weakest points of the Business Objects tools for a long, looonnng time. A prompt can be created on a report or in the universe. If the prompt is defined in the universe there is a standard syntax. So I will start with a brief review of that syntax and move on from there.

@Prompt() Me One More Time…

The standard prompt syntax has five arguments. The first two are generally considered required while the remaining three are optional. Here is the syntax:

@prompt('Enter prompt text here','A',LOV Source,mono/multi,free/constrained)

I’ll break down each of those five parameters next. First, the prompt text. The first argument is required and is the most obvious… it contains the text that the user will react to. It’s a good idea to let the user know what’s going on and to provide some clue as to how the prompt will operate. For example, if you are using a prompt in an equality test, you should inform the user that they can only select a single value. If you are using the prompt in a list, then let them know they can select one or more values.

The next argument has three options: A, N, or D. These match with the datatype expected from the prompt. The ‘A’ represents alphanumeric data, and any data entered is accepted as it was entered. Using an ‘N’ denotes a numeric prompt and only valid numeric values are accepted. Finally, a ‘D’ represents a date prompt. With this type of prompt Webi will include a spiffy calendar that a user can use to select their entry. This is available even if the LOV has been turned off.

The third parameter is a reference to a potential list of values for the prompt. There are two possible options: either a hard-coded list, or an object from the universe. If I wanted to make a hard coded list with the values “Yes” and “No” on it here is the syntax:

{'Yes','No'}

The values are surrounded with curly braces { } and entered as a comma-separated list. Character data is in quotes. Simple enough, yes? no?

If I wanted to use an existing object in the universe for the list of values I would enter that choice without the curly braces and in the format 'Class Name\Object Name' instead. One common designer mistake is attempting to use a table.column syntax here. The table.column is of course the eventual source for the list of values, but the LOV query is defined as part of an object definition. That’s why you enter an object here rather than a table column.

The last two parameters are optional, but even if you leave them out you have to include the commas for the prompt syntax. In other words, this is valid:

@Prompt('Do you like BOB?','A',{'Yes','Yes, of course'},,)

Even though the values are missing the commas remain. What do the values do if you include them? The fourth parameter allows you to specify whether the prompt is a multi-select option or not. The value mono (no quotes here) says the prompt is restricted to a single value. The value multi (again, no quotes) allows for multiple values to be selected. The fifth parameter determines whether the user can type the prompt response or if they are required to pick from the list of values. The value free does the former, and the value constrained requires the LOV selection. Here’s a hint: don’t make a prompt constrained without providing a valid list of values source.

So those are the five basic arguments for the @Prompt() function. Most of you will have noticed that none of them have anything to do with providing a default value.

@Prompt() Extended Syntax for Web Intelligence

We got some new prompt options starting with Web Intelligence 6.x. One of the options a report writer could use was whether or not the last prompt value entered was the default for the next report run or not. Another option was whether the prompt had a default value or not. And finally, report prompts could appear in a user-specified order rather than in alphabetical order as before. But all of these options were report specific and not supported in Universe Designer.

Here’s what the extended prompt syntax looks like:

@Prompt('Enter value(s) for Something:','A','Class\Something',Multi,Free,Persistent,{'Default Option'},User:0)

I’ve already covered the first five parameters so now I’ll detail the last three. The sixth parameter has the value Persistent or Not_Persistent. The default value is to retain the last value entered (Persistent). This is also the legacy behavior; previous versions of the reporting tools only worked in a persistent manner.

The seventh parameter has a syntax that looks a bit like the hard-coded LOV from earlier with the curly braces. This is where a default value for the prompt can be stored. And finally, the last parameter determines the order of the prompt, starting with zero (0) as the first prompt and incrementing from there.

To reiterate something I stated earlier: These are report options only. These parameters can be entered into a prompt object definition in the universe, but they are unlikely to parse because of the extended syntax. In order to test this syntax I would have to export my universe and test in a Web Intelligence query.

What About That Default Value?

Extended prompt parameter number six: a default value. That brings me back to the original subject for this post, doesn’t it? I wanted to have a value like “sysdate” or a formula of some kind like CurrentDate() plugged into that parameter. Unfortunately, it doesn’t work. Any value entered for that parameter is treated as data, and no formulas or calculations will be calculated. So anything like sysdate or getdate() or CurrentDate() is going to fail.

The next trick is to try to reference an object, and store the formula as the object definition instead. Unfortunately, again, it fails. The object name becomes the default value for the prompt which is generally not the intended result.

Conclusion

What it boils down to, as I see it, is this: you can’t do it. There is no way to create a prompt syntax that will substitute in a value like “today’s date” for a prompt default value. It would be nice, but it doesn’t work.

However, I do have a work-around that I’ve used for many years. I create a “magic date” and some creative logic within the prompt to do the substitution after the user has already responded to the prompt. That’s the subject for the next post in this series. Stay tuned for details.

Things I really REALLY wish prompts could do…

1. Set a default with a variable. It’s the subject of this post, need I say more?
2. Be optional! With XI 3.0 a report writer can create optional prompts now, but we still can’t do them in Designer. Boo.
3. Do cascading prompts effectively. This has been on my wish list for-EVER. I have another post about cascading prompts coming up soon so I’ll save the majority of my whining until then.
4. We have free and constrained, I want a third option: validated. This would be the best of both worlds. A user would be “free” to enter the value if they wanted to, but it would be validated against the LOV provided in the universe. Today I have to allow the user to shoot themself in the foot by typing the wrong value, or I have to force them to use the LOV.
]]> http://www.dagira.com/2008/07/15/how-can-i-make-today-my-default-prompt-value/feed/ 29