biExport for Lumira Blog

New simple way of creating complex Briefing Books with multiple URL parameters

created: 29.04.2020

biExport has been supporting Lumira Designer customers for years in exporting the whole content of a dashboard and creating complex Briefing Books. These capabilities have already been nicely described in the following Blog Posts (available on www.designstudio-export.com):

Using the "Briefing Book" (aka "Iteration") feature, biExport not only supports exporting the content of several tabs / pages or multiple individual filters on one dimension. It also allows you to combine both, or "iterate" on mutliple dimensions at the same time.

Some examples for these complex scenarios are:

  1. Show the content of all tabs individually for the TOP 10 profit centers
  2. Show the content of all tabs, and for each tab show all pages of a page book
  3. Show figures for several countries and for one country, apply special additional filters on sales org.
  4. Show figures for several countries and for one really important country, show different sales regions
  5. Show figures for several countries and for one really important country, show different sales regions. Moreover, these views shall be presented for several product groups.

How customers have implemented it in the past

For all these scenarios, you have multiple "iterations" that depend on each other: For example 1 to 4 you have two iterations, for example 5 you have even three iterations.

For performance and system load reasons, biExport does not allow building Cartesian products of these individual iterations. So far, you had to build up so called "dependent iterations".

For example 1 you would have defined the profit centers as the main iteration and the tabs as a dependent iteration. This resulted in the following complex script:

var lvalues = "";
CHECKBOXGROUP_1.getSelectedValues().forEach(function(element, index) {
  lvalues = lvalues + element + ";";
});
var lparam = OPENBIEXPORT_1.createUrlDependentParameter("XTABNO", true, lvalues);
var lparams = [lparam];
// create profit center param for overview page
var lprofitctr_values = [OPENBIEXPORT_1.createUrlDependentValueComplex(“”, lparams)];
DS_1.getMembers("0PROFIT_CTR", 10).forEach(function(element, index) {
    // Create URL param value object for each profit center, with Dependent Parameter of tab
    var lvalue_profitctr = OPENBIEXPORT_1.createUrlDependentValueComplex(element.internalKey, lparams);
    lvalues_profitctr.push(lvalue_profitctr);
});
// Set Profit Center Url Parameter with value object array
var param_profitctr = OPENBIEXPORT_1.createUrlParameter2Complex("", "", "XPROFITCTR", true, lvalues_profitctr);
// Create URL Parameter Array
var params_all = [param_profitctr];
// set all URL parameters on export component
OPENBIEXPORT_1.setUrlParameterArray(params_all);

For example 4 you would have defined country to be the main iteration, then you would have added sales regions as a dependent iteration to country, and again product groupds as a dependent iteration to sales regions. You can just imagine that the code to realize this would have been much more complex.

How you can implement it now

To reduce code complexity, we now provide you with an alternative approach: The simple idea is to set up each view as an individual definition. Of course, your existing dependent iteration coding will still be supported - you can use both the old and new approaches in the future.

The new script method setBriefingBookExecutions() expects an array of objects with the following properties. These objects can be created via the new method createBriefingBookDefinition().

Property
Usage
Property
Ordinal
Usage
Index of the definition within the execution array.
Property
urlParameters
Usage
An array of parameters created with the createNameValuePair() script method. In fact, you define all parameters that shall be added to the execution URL for the application for this particular execution step.
Property
exportTemplate
Usage
Optional, name of the template that shall be used for this particular execution step.
By using different templates for individual execution steps you can easily create complex documents, very much alike using the Dynamic Template Definitions.
Property
exportSelection
Usage
Optional, an array of components created with the createVisibleComponents() script method.
By using this parameter in combination with a generic template that holds the CONTENT placeholder, you can define for each execution step individually the components that shall be added.
Property
exportFilename
Usage
Optional, name of the file that shall be created.
If not provided, the “Filename” property of the biExport Component will be taken.
If multiple definitions have the same exportFilename, they will be merged into one document. You can also set filenames individually, should you want to generate one file by execution. This makes this property much more powerfull than the combination of the “Filename” and “Separate Files” properties of the biExport Component.
Property
customTexts
Usage
Optional, an array of Custom Texts created with the createNameValuePair() script method.
You can pass for each execution step individually different texts that shall replace placeholders in the Export Template.
Property
documents
Usage
Optional, only Lumira 2.x: If you specify multiple documents in “Alternative Export Application”, you might want to pass different parameters to the indiividual documents. Enter the document CUIDs separated by semicolon, for which this particular parameter shall be used.
Property
applications
Usage
Optional: If you specify multiple applications in “Alternative Export Application”, you might want to pass different parameters to the indiividual applications. Enter the application IDs separated by semicolon, for which this particular parameter shall be used.

The script for example 1 now looks as follows and is much more legible:

// create an empty component array - in our example we only use the urlParameter property of the Briefing Book Definition
var lcount = 0;
var lempty = [OPENBIEXPORT_1.createVisibleComponent("", false)];
// create the definition
var ldefs = [OPENBIEXPORT_1.createBriefingBookDefinition(1, "", [OPENBIEXPORT_1.createNameValuePair("", "")], "", lempty, "", "")];
ldefs.pop();
var lparam = OPENBIEXPORT_1.createNameValuePair("", "");
var lparams = [lparam];
lparams.pop();
// loop over profit centers
DS_1.getMembers("0PROFIT_CTR", 10).forEach(function(element, index) {
    if (index > 0) { lparams.pop(); lparams.pop(); }
    lparam = OPENBIEXPORT_1.createNameValuePair("XPROFITCTR", element.internalKey);
    lparams.push(lparam);

    // loop over tabs
    CHECKBOXGROUP_1.getSelectedValues().forEach(function(element, index) {
        if (index > 0) { lparams.pop(); }
        lparam = OPENBIEXPORT_1.createNameValuePair("XTABNO", element);
        lparams.push(lparam);
        // create the definition
        lcount = lcount + 1;
        ldefs.push(OPENBIEXPORT_1.createBriefingBookDefinition(lcount, "", lparams, "", lempty, "", ""));
     });
});
// set array of definitions for the biExport Component
OPENBIEXPORT_1.setBriefingBookExecutions(ldefs);

A third iteration as in example 4 would now result only in an additional loop. If you are interested in the coding for examples 2 to 5, this is available in the biExport documentation starting with version 2020.