Guest Post: A New Take on Date Range Prompts

Since version 10.2 of IBM Cognos BI Suite, IBM included an API to access and manipulate prompt objects. Since prompt objects are the main instrument we use to allow users to communicate with a report (Interactivity or user selection), being able to manipulate them however we see fit can change user experience dramatically for the better. There are countless examples of how the prompt API can be used to achieve this. For example, dynamic defaults: Suppose you have two prompts, for region and for products. You want the default product selected to be the best selling product in the region selected. With prompt API, this can be achieved easily.

In this post I’d like to showcase one of the first solutions I ever wrote using Prompt API, because it was one of the things I wanted to solve for a long time.

Every so often we add “from date” and “to date” prompts to a report, to use for filtering the report output to show only data from the date range selected. The problem is, most users and most use cases don’t require the sort of flexibility a date range offers: most users will not run their sales-per-branch report between April 23rd and May 2nd, for instance, because it’s an arbitrary chunk of dates. Instead, users are likely to filter dates for last month, this MTD, QTD, YTD, last week and so on. So, basically, set, standard, comparable time frames. And sometimes the date range prompt can be replaced with a drop down list of such pre-set ranges, but other times, users ask to still have the flexibility of choosing to and from date, but nonetheless, still mostly use the set, comparable ranges.

Now, in order to select last month’s dates with two date prompts, your average user will need 6 clicks: One to open from date calendar, one to page back to last month, one to click on “1”, and the same process with the “To date” prompt. For YTD, they might need more. That’s a lot of clicks. Also, developers often have to write scripts to get the default value right, and because these date prompts are never done in a centralised, reusable manner, they end up writing a script for each report. I have long fought the war on developers wasting time by doing things more than once, and this case is no different. Even if reports require different default times, the solution can still be generalised, and therefore made reusable.

My solution uses JavaScript and Prompt API to add to the date prompt functionality. Here is how it works:

Date Solution

I’m using two date prompts, and adding 7 pre-defined links, which, when clicked, fill in their respective dates. So, for example, clicking on MTD will set the from date prompt to the 1st of the current month, and the to date prompt to today’s date. There’s also a verification mechanism in place to ensure that from date is always earlier than to date, or equal to it.

But how do I make this solution generalised? Let’s take a look at the report studio report:

RS Look

The bit in blue is the error message the user will get if they choose an end date that’s prior to the start date. The bit in blue is a text that should be replaced with another text – containing just one number between 1 and 7, corresponding with a dynamic ate range.  “1” is YTD, 4 is WTD and so on.

Now, if you drag in a layout reference object to this interface, here’s what you’ll get:

override

You can override&replace the warning message and the default text. So, if the default for a certain report is “last month”, you’ll override “Defaults”

replace

Drag in a text item and insert “5”

default set

When you run the report, the default would be last month:

final result

This way you can set a different default value for each report in a reusable manner.

I’m attaching the XML, of course, but pay attention to these caveats:

1. The script has seven preconfigured date ranges. You can change them or add to them as you require, and use the general example in the code, but it requires some knowledge of scripting. Unfortunately, I will not be able to provide support for such customisations.

2. If you’re relying on my script to manipulate weeks, pay attention that my script assumes Monday is the first day of the week. Israelis especially, this means you’ll have to change this logic (Weeks in Israel begin on Sundays).

3.This is 10.2.2 – You can downgrade it to 10.2.x by changing the version number at the top.

 

daterange.txt (1924 downloads)

 

Nimrod (Rod) Avissar is a Cognos expert, with a penchant for specialized UX solutions. Feel free to drop me a line! (LinkedIn).

 

 

Passing parameters without refreshing the page

Recently a reader had an interesting problem. Her client needed a prompt page from which they could open different reports. As it stands now, the client needed to select their prompts, hit the finish button, and then click on the links. She wanted a way to skip the second step – select the prompts, and have those values pass in the drill through.

With the prompt API, and a bit of JS, this is incredibly easy.

The first step is to identify the target report. You can get the report search path through the properties. Click on the “View the search path, ID and URL Location” link, and a window will pop up with the path and other details.
1. Get search path

Notice the double quotes? That can potentially cause trouble with the JavaScript, so I recommend using a URL Encoder: /content/folder[@name=’JavaScript Examples’]/folder[@name=’Drill Target’]/report[@name=’Target’] becomes %2Fcontent%2Ffolder%5B%40name%3D%27JavaScript%20Examples%27%5D%2Ffolder%5B%40name%3D%27Drill%20Target%27%5D%2Freport%5B%40name%3D%27Target%27%5D

The example I’m posting will be using the URL Encoded version.

The next step will be the JavaScript:

<script>

  var paulScripts = {}
    , oCR = cognos.Report.getReport("_THIS_")
    , gateway = window['oCV_THIS_'].getRV().getCV().sGateway
    , report1 = decodeURIComponent("%2Fcontent%2Ffolder%5B%40name%3D%27JavaScript%20Examples%27%5D%2Ffolder%5B%40name%3D%27Drill%20Target%27%5D%2Freport%5B%40name%3D%27Target%27%5D%0A%0A");
 

  /* function paulScripts.URLEncode - Paul Mendelson = 2013-10-21
   * Based on the JSONEncode function, this will return the use/display values of
   * a prompt in a format that can be based via POST or GET.
   * usage: 'p_Parameter1='+paulScripts.URLEncode(paulScripts.getControl('MyPrompt'))
   */
  paulScripts.URLEncode = function(promptControl){
    var urlData = '<selectChoices>'
      , aPromptValues = promptControl.getValues()
      , nonRange = []
      , range =[];

    if (aPromptValues.length == 0) {return false}
   
    for (var j=0; j< aPromptValues.length; j++) {
      var promptValue =  aPromptValues[j];
     
      if (promptValue.use) {// Non Range value
        nonRange.push("<selectOption useValue='"+promptValue.use + "' displayValue='"+ promptValue.display + "'/>");
        }
      else { // Range value   
        var rangeStart = promptValue.start
          , rangeEnd = promptValue.end
          , start, end, startDisp, endDisp;
        if (rangeStart && rangeEnd) { //has both Start and End (bounded)
          rangeStart.display?startDisp = " displayValue='"+ rangeStart.display+"'":"";
          rangeEnd.display?endDisp = " displayValue='"+ rangeEnd.display+"'":"";
          range.push("<selectBoundRange><start useValue='"+rangeStart.use +"'" + startDisp +"/><end useValue='"+rangeEnd.use +"'" + endDisp +"/></selectBoundRange>")
        }
        else if (rangeStart && !rangeEnd) {//unboundedEndRange
          rangeStart.display?startDisp = " displayValue='"+ rangeStart.display+"'":"";
          range.push("<selectUnboundedEndRange><start useValue='"+rangeStart.use +"'" + startDisp +"/></selectUnboundedEndRange>");
        }
        else if (!rangeStart && rangeEnd) {
          rangeEnd.display?endDisp = " displayValue='"+ rangeEnd.display+"'":"";
          range.push("<selectUnboundedStartRange><end useValue='"+rangeEnd.use +"'" + endDisp +"/></selectUnboundedStartRange>");
        }
        else {
          alert ("Range not set.");
        } // end if
      } // end if
    } // end for
    if(nonRange.length>0) urlData += nonRange.join();
    if(range.length>0) urlData += range.join();
    urlData+='</selectChoices>';
    return urlData.replace(/&/g,'&amp;');
  }

  /* function paulScripts.getPrompts
   * Paul Mendelson - 2013-10-21
   * Retrieves all the prompts on the page and returns the parameter values
   */
  paulScripts.getPrompts = function(){
  //find all of the controls and stick them in aPromptControls.
    var aPromptControls = oCR.prompt.getControls( ),
    prompts = [];

  //loop through the controls - finding the name and values and sticking them into the names array
    for(i=0;i<aPromptControls.length;i++)
    {
      if(aPromptControls[i].getValues().length == 0) continue;
      prompts.push(aPromptControls[i].getParameterName());
      prompts.push(paulScripts.URLEncode (aPromptControls[i]));
    }
   
  return  prompts;
  }

paulScripts.runReport = function(reportName,reportPath,gateway, prompts){
  var basicInfo = [
          reportName, "toolbar=no,height=200,width=400"
        , 'ui.gateway' , gateway
        , 'ui.tool' , 'CognosViewer'
        , 'ui.action' , 'run'
        , 'ui.object' , reportPath
        , "run.prompt" ,"false"
        , "cv.toolbar" ,"false"
        , "cv.header" ,"false"
        , "run.prompt", "false"
    ];

    basicInfo=basicInfo.concat(prompts);
  return cognosLaunchInWindow.apply(this,basicInfo);
  }



</script>
 

Let’s go through the functions.

var paulScripts = {}
, oCR = cognos.Report.getReport(“_THIS_”)
, gateway = window[‘oCV_THIS_’].getRV().getCV().sGateway
, report1 = decodeURIComponent(“%2Fcontent%2Ffolder%5B%40name%3D%27JavaScript%20Examples%27%5D%2Ffolder%5B%40name%3D%27Drill%20Target%27%5D%2Freport%5B%40name%3D%27Target%27%5D%0A%0A”);

We’re defining the variables on the page. Notice that I’m hardcoding the report search path into a variable here. There’s actually no reason to do that, we could put it directly into the function, or put it into another prompt, or even insert it into a table and build a list with each row calling another report.

The gateway variable is pulling the gateway from the report you’re running. Another gateway could be entered here, if needed.

The paulScripts.URLEncode will take a prompt control, process the selected values, and spit out a string that Cognos can use to populate parameters.

paulScripts.getPrompts will look for every prompt on the page, and create an array of the parameter names and the selected strings. This makes updating the report simple – you won’t need to modify and JavaScript when adding or removing prompts.

paulScripts.runReport is the last function. It uses the cognosLaunchInWindow function to run a report in the specified window, using the specified search path, on the specified gateway, with the results of the paulScripts.getPrompts function.

To use it, all you need to do is creating an onclick event like this:

<input type="button" onclick="paulScripts.runReport('_blank',report1,gateway, paulScripts.getPrompts())" value="Run Report 1"/>

And finally, we can test it:
passingPrompts

This report was built on 10.2.1, but should work on all versions 10.2 and up.
Passing Parameters Without Refresh (1041 downloads)

Tab Solution That’s Easy to Maintain Without Code – Guest Post

“How corrupting boredom is, everyone recognizes also with regard to children. As long as children are having a good time, they are always good. This can be said in the strictest sense, for if they at times become unmanageable even while playing, it is really because they are beginning to be bored[…]Adam was bored alone; then Adam and Eve were bored en famille. After that, the population of the world increased and the nations were bored en masse. To amuse themselves, they hit upon the notion of building a tower so high that it would reach the sky. This notion is just as boring as the tower was high and is a terrible demonstration of how boredom had gained the upper hand. Then they were dispersed around the world, just as people now travel abroad, but they continued to be bored” (S. Keirkegaard, the Rotation of Crops).

I like writing nifty solutions for Cognos, which look good, work well, and add a necessary functionality. Tabs for Cognos reports (Not Active Reports, where tabs exist out of box) are a great demonstration for such functionality: It’s a necessary functionality, and when done properly, they make a report look wonderful.

However, I get bored doing the same thing over and over. When writing a tabbing solution, the principal is always the same: There are the tabs themselves, which are essentially links to be clicked on, and when clicked, there are the contents which need to be either hidden or shown based on the tab that was clicked.

Every now and again a developer who may not be very well versed in HTML, JavaScript and/or CSS would ask me to add, remove or change a tab, or change the style of a tabbed menu, or any such thing. To me, this is boring, and as Kierkegaard noted, boredom is corrupting – indeed, it is the root of all evil.

What needed to be done, then, was to come up with a tabbing solution that allows developers to add, remove and edit tab contents and tab styles without needing to write a single letter of code. The scripted solution needed to be generalized so that developers would be able to use Cognos built-in features to control all aspects of tabs. In other words, I needed to write a tabbing solution that would be a piece of cake to maintain, leaving me with more free time to get bored productively in Cognoise forums.

POCT (=Piece of Cake Tabs) is just that solution. It requires no coding to add, remove, or edit the content a tab. It allows the user to style the tabs using nothing but Cognos built in features. Basically, once you set the solution up, you never have to open an HTML item again.

Let’s look at the page structure:

POCT

Under “Tab Headers” HTML Item, one would simply drop in text items one after the other, each containing the name of the tab (The text that would be written in the tab).

Under “Tab Content” HTML Item, one would create a block for each tab, and drop in the necessary objects for each tab. The uppermost block is the content for the leftmost tab header, and so on – tab headers from left to right, content blocks from top to bottom.

Under “Style” HTML Item there are 3 table cells. One can style them as one wish. The leftmost cell represents how a selected tab would look. The middle one represents the styling of a tab which isn’t currently selected. The rightmost cell controls how a tab looks on mouse over. You can also control the look of the entire tab row, by highlighting the blue table cell where the tab headers are and changing its design to modify the design of the tab row.

And that’s it.

Want to add a tab? Add a text item and a block accordingly. Want to change the content of a tab? Just change the content of a block. Want to remove a tab? Remove the header text item and the corresponding block. And styling is truly piece of cake.

Report XML (10.1) – you can either use that as base or copy the main block and anything in it to any report. This was tested on all Cognos 10.x versions, and should work fine on 8.4.x.

POCT-XML-101.txt (1821 downloads)

Nimrod (Rod) Avissar is a BI Front-End Specialist, with a penchant for specialized UX solutions (LinkedIn).