How To add User Prompts (parameters) to Out-of-the-Box Remedy/ITSM Web Reports with the BIRT editor

BMC provides some starting points for this – how to download the all-in-one BIRT editor, install and configure it, how to export the Web Report definition file (attachment) from the Report form record, basics of editing existing reports.

However, BMC is lacking in how to do simple BIRT things such as:

Use a date range (start/end date) supplied by the user in the report qualification (query) so it limits the number of results returned. (Some, maybe all, the OOB reports use this in the “filter” – which is used AFTER the actual SQL query. In some cases the query (qualification) is ‘EntryID’ != $NULL$, so this means the report fetch ALL the incidents, then show only those within the date range selected. This makes these reports unusable (takes too long to finish, overwhelms the mid-tier) or useless (any configuration setting limiting the returned results – such as the recommended “2,000” – means the selected date range is probably not returned (the first 2000 results of 1.8 million probably won’t include any for this week/month/or year), resulting in an empty (“contains no data”) report.

Create a cascading prompt (Company, Support Organization, Assigned/Support Group) to restrict the results (with as many tickets per week and Support Groups as our system has, any charts or details become messy or simply have too much volume to be useful).

The BIRT community (Google is your friend) does have a lot of information (sometimes conflicting, sometimes confusing), but very little specific to Remedy/ITSM.

The BMC Developer Community has some helpful stuff.

Passing (report) parameters to the dataset qualification (Remedy query):

When you see “Parameter” in BIRT documentation, think “Report Parameter”. Report Parameters typically open a dialog window when the report is run, allowing the user to type or select one or more dates, text entries such as Assigned Group name, etc.

These have to be both “linked” in the appropriate dataset (usually this is the Remedy/ITSM form that data is being pulled for the report) to a dataset parameter (can be the same name, best practice is probably to put “ds” in front to make it clear this is a dataset parameter) and then referenced in the dataset query/qualification (actually, it’s referenced by POSITION, not NAME, more on this later).

Linking the dataset parameter to the report parameter is done in the dataset Parameters section, something like:

WARNING: as part of its BIRT heritage – the PARAMETER NAME HERE DOESN’T MATTER. ONLY THE ORDER MATTERS from the PARAMETER section. Typically BIRT uses ? as a placeholder/reference for each parameter. The first parameter goes to the first “?”, the next parameter to the second “?”, etc. So make sure that the order in the Parameter section matches the order you want them used in the query/qualification, eg, the one at the top (#1) is used first, the next one second, the bottom one .. last.

Using these in the dataset qualification is done in the dataset Query section using the syntax [param:name] with no quotes around it for a date/time, eg ‘Reported Date’ >= [param:Start Date] as shown below (text values, for Assigned Group, for example, will need double-quotes around the [param:name] ):

(delete the Start/End date entries in the Filters section, if they exist in the OOB report already).

Once you’ve got Report Parameters set up, and figured out that the order of the linked Parameters in the dataset is what matters, using them in a predetermined (fixed, hardcoded) query qualification is fairly straightforward.

-----------------------------------------------

What if you need MORE flexibility – for example, to use LIKE (instead of Equals(“=”) if a search term includes one or more wildcards (preferably the Remedy wildcards such as %), or different field names for the query depending on the parameters selected by the user (or multiple EQUALS statements if your user selects multiple items from a menu)?

You could probably use some convoluted (but static, that is, unchanging) Remedy query syntax (…. ‘Assigned Group’ = “[param:AssignedGroup]” or ‘Assigned Group’ LIKE “[param:AssignedGroup]” …)

However you’d have to add that parameter multiple times in the dataset Parameters section, in the right order…. You might have to make that hardcoded query very complicated with AND statements to determine if some search term was or was not empty…so the above becomes a mess similar to

(….“[param:AssignedGroup]” !=$NULL$ AND ( ‘Assigned Group’ = “[param:AssignedGroup]” or ‘Assigned Group’ LIKE “[param:AssignedGroup]”)

OR (“[param:AssignedGroup]” =$NULL$ AND [param:SupportOrg]!= $NULL$ AND 'Assigned Support Organization’= “[param:SupportOrg”)

OR (“[param:AssignedGroup]” =$NULL$ AND [param:SupportOrg]= $NULL$ AND [param:SupportCompany]!= $NULL$ AND 'Assigned Support Company’= “[param:SupportCompany”)

…)

So now you’d have to have each of the parameters shown in the Parameter section multiple times in the exact right order…

It might be better to dynamically (e.g. programmatically) update the query depending on the user selections made for the parameters.

----------------------------------------------------------

Updating the query at runtime:

BIRT provides TWO ways to do this:

Using the Property Binding section on the dataset (which I could NOT get to work). Supposedly you use javascript here to create a text value that completely replaces the query qualification shown on the dataset Query section. This could be as simple as the expression ‘1=1’ or as complicated as multiple nested IF statements, etc. This MAY NOT be implemented in the driver BMC provides for BIRT to access Remedy data – I simply could not make it work. I’d appreciate a working Remedy/ITSM example if someone has one… as it would seem to me, more direct and maintainable to do this here.

Using the “beforeOpen” script for the dataset to replace all or part of “this.queryText” (since this script belongs to a particular dataset, this references that query.

I’m not positive but I think the content of “this.queryText” is ONLY the section displayed in the Qualification section and does NOT include the Select, From clauses of the SLQ query as it does for other data sources as shown in online BIRT discussions/examples.

(To create or edit the “beforeOpen” script, select the dataset in the Outline section on the left, select the Script tab at the bottom of the main window… select “beforeOpen” as the script to edit…. By default this will be blank).

Edit it.. using standard javascript syntax (there’s no Expression Builder available here to make it easier but there IS a Check Syntax button at the top…) when finished, save and run.

(This script may NOT run when the Preview tab is used in the main window, may only be invoked when the “globe” icon in the top menu section (“View in web viewer”… etc is used). )

I created a Cascading Prompt for the user to select the Company, Support Organization, and the assigned Support Group (so “Assigned Group”). (This requires adding a Dataset for Support Groups to pull the information for the menus from). By making only the Company required, and making the Support Group a Combo Box, a field for the user to type an assignment group name was provided and the user could either select one entry from the menu, or click the radio selector next to the field and type into it. By including the standard Remedy % wildcard, that entry could be used with a LIKE statement rather than an Equals statement.

If only a Company were selected, or only a Company and Support Organization, the query would be changed to use those.

If the Assignment Group was selected or typed, the query would be (only) on that – this could easily be changed to include the Company and Support Organization, if desired.

I originally investigated this to allow making the Assignment Group a multi-select parameter (eg, you could select multiple entries and multiple Equals statements would be generated (eg… AND (‘Assigned Group’ = “[selection1]” OR …(‘Assigned Group’ = “[selectionN]”).

After having difficulty accomplishing this I consoled myself that allowing wildcards or leaving the Assigned Group empty and allowing ALL the relevant Support Organization incidents to be returned was good enough.

The javascript .replace() method gave me some trouble. BIRT examples and javascript documentation suggest this can use a search string for an exact match OR a regular expression. I couldn’t get a regular expression to work, and the exact match failed to match the Equals sign (“=”) in the queryText

This is the reason that the hardcoded query I save on the dataset has an obvious error:

(standard paramterized start date/end date query…) AND ‘Assigned Group’…”ReplaceBybeforeOpenScript”

(yes, you can combine start/end date parameters with a dynamically updated query…)

I use this part (AND ‘Assigned Group’…”ReplaceBybeforeOpenScript” ) as the search term to be replaced. (any other obvious placeholder would work. I’d prefer to leave a hint that the “beforeOpen” script is going to be used as THIS WON’T BE OBVIOUS otherwise).

Recommendations are to use a placeholder that will be a valid query so that the report won’t fail if the beforeOpen script does NOT replace the query – but then, you might not know that a syntax error in that script made the replacement part fail – as it “fails quietly”. After this happened to me several times, I feel that an obvious Query error is better.

Also, each time I moved from one section of the dataset to another (for example, selecting the Parameter section after updating the Query section) the Query is run. An invalid query fails silently (and

quickly), but a valid query… that returns LOTS of results… makes the BIRT editor unresponsive until the query completes, and maybe longer as the results are processed. This made me think the editor was hung, multiple times, until I saw the SQL statements being produced in the Remedy SQL logs.

Screenshots for the Support Groups dataset, cascading prompt, dataset qualifiers, and the “beforeOpen” script shown below.

Navigating to the ‘beforeOpen’ script after selecting the dataset (and other features of interest):

--------------------

// change the query based on the Assigned Group selected by the user.. //if none was selected consider using just the Support Org or the Company for the query.var st= "AND 'Assigned Group'...\"ReplacedBybeforeOpenScript\"";//\"ReplacedBybeforeOpenScript\"" ; //the searchterm (looks like it CAN'T be a literal regexp here for some reason!// eg var st = /AND.*$/i and var st = '/AND.*$/i';; don't work).

///only a search STRING (without any regexp stuff) works - and the "=" doesn't match the query.if ( ! ( params["rpAssignedGroup"].value == '' || params["rpAssignedGroup"].value == null ) ){

if ( params["rpAssignedGroup"].value.indexOf('%') == -1){//user selected a (single) entry from the list or typed a single

entry without the Wildcard (%) charthis.queryText = this.queryText.replaceAll(st, 'AND \'Assigned

Group\' = "' + params["rpAssignedGroup"].value + '"' );}

else {// user TYPED a support group name with the % as wildcard eg

"%Desktop%//so pass it in as a LIKE statement.this.queryText = this.queryText.replaceAll(st, 'AND \'Assigned

Group\' LIKE "' + params["rpAssignedGroup"].value + '"' ); }

} else {if ( ! ( params["rpSupportOrg"].value == '' ||

params["rpSupportOrg"].value == null) ) {this.queryText = this.queryText.replaceAll(st,

'AND \'Assigned Support Organization\' = "' + params["rpSupportOrg"].value + '"' );

} else {if ( ! (params["rpCompany"].value == '' ||

params["rpCompany"].value == null ) ) {this.queryText = this.queryText.replaceAll(st,

'AND \'Assigned Support Company\' = "' + params["rpCompany"].value + '"' );}

}}