Introduction to the SAP Lumira Component API
SAP Lumira Designer is a design tool to create interactive analysis applications. To enable interactivity, you write scripts that are executed when the user performs an action in the executed application. For example, you can place the Button component in the application and assign a script to the Button’s On Click event. Scripts consist of one or more statements written in a JavaScript-based language that follow a specific syntax. For writing scripts the design tool offers the script editor. All objects, methods, and expression types are listed in this API reference.
Script Language
You write scripts in the BI Action Language (BIAL). BIAL is a true subset of the JavaScript/ECMAScript standard. The scripts are executed on the Analysis Application Design Service (unlike JavaScript that is executed in the Web browser). Scripts have a clear definition of the supported language constructs, objects, and methods.
Scripts, Statements, and Events
Scripts consist of statements. Each statement is typically written in a single line. The execution of scripts is triggered by user interaction with the component. This interaction is also referred to as an event and the script executed in response to this event is the event handler. Each component has its own set of one or more events that are displayed in the Properties view of the component.
Remember
Events on components are only triggered by user interaction and not implicitly by scripting. For example, when changing the selection in a List Box component by using the script LISTBOX_1.setSelectedItem(), the On Select event of the List Box component is not triggered. An exception to this rule is the On Result Set Changed event, which can be triggered implicitly by a script method like setFilter or reloadData.
SAP Lumira Designer currently supports the following statement types:
  • Call statements
  • Conditional execution statements
  • Assignment statements
Syntax of Call Statements
Call statements execute an API method of an object and have the following format:
<component>.<method>(<arguments>);
A call statement consists of the following parts:
  • <component> is the name of a data source alias or a component in your application, for example, DS_1 or BUTTON_1.
  • <method> is an operation that is applied to the object specified on the left of the period (.). The available methods depend on the component type. DataSourceAlias objects, for example, provide methods to filter data, and visual components provide methods to modify visibility, enablement, and so on.
  • <arguments> is a comma-separated list of expressions. The specified expressions must match the requirements of the method.
  • Each statement ends with a semicolon (;).
You can use methods as arguments for other methods as long as the return type matches the argument type.
Syntax of Conditional Execution Statements
Conditional execution statements have one of the following formats:
  • First format
    if (<condition>) {
      <sequence of statements to execute when condition is met>
    }
  • Second format
    if (<condition>) {
      <sequence of statements to execute when condition is met>
    } else {
      <sequence of statements to execute when condition is not met>
    }
<condition> is a Boolean expression - one of the following:
  • true or false as value literals (constants)
  • A method call statement returning a Boolean value
  • A comparison for equality in the form a == b
  • A comparison for inequality in the form a != b
  • Multiple conditions joined using && and ||, parentheses are optional
Assignment Statements
Assignment statements have one of the following formats:
  • var <variable> = <expression>;
    This format defines a script variable (see Script Variables in this text) and assigns the result of an expression to this script variable.
  • <variable> = <expression>;
    This format assigns the result of an expression to a script variable, which has been already defined.
Methods and Object Types
Methods are operations that are applied to the object specified on the left of the period (.) in the statement. The available methods depend on the object type. For example, DataSourceAlias objects provide methods to filter data. Visual components have methods to modify visibility, enablement, and so on.
Expressions
Expressions compute a result (also referred to as returned value) in a similar way to a formula. Expressions can appear as method arguments and as conditions (if statements or conditional execution statements). The results of an expression have a type. An expression may consist of literals (String constants, integer and float numbers, arrays, JSONs), operators, method calls, and parentheses. Operators supported by BIAL are:
Operator Description Argument Type Result Type Example
+ Concatenates strings String, (int, float, boolean) (boolean and int will be converted to String automatically) String "ab" + "cd" (= "abcd")
"ab" + 1 (= "ab1")
+ Adds two integer or floating point values int, float int 1 + 2 (= 3)
- Subtracts two integer or floating point values int, float int 3 - 2 (= 1)
* Multiplies two integer or floating point values int, float int, float 3 * 2 (= 6)
/ Divides one integer or floating point value by the other int, float int, float 8 / 2 (= 4)
== Checks if the two operands are equal Any boolean 1 == 1 (= true)
"a" == "b" (= false)
!= Checks if the two operands are not equal Any boolean 1 != 2 (= true)
"a" != "a" (= false)
&& Logical AND boolean boolean true && false (= false)
true && true (= true)
if (<condition1> && <condition2>) {
  <statements>
}
The statements will be executed if both conditions are true.
|| Logical OR boolean boolean true || false (= true)
false || false (= false)
if (<condition1> || <condition2>) {
  <statements>
}
The statements will be executed if at least one of the conditions is true.
! Logical NOT boolean boolean !true (=false)
!false (= true)
if (!<condition>) {
  <statements>
}
The statements will be executed if the condition is not true.
Expression Type System
Expression results can be used as method arguments. The expression type must match the argument type. In some cases, BIAL will automatically convert between types. This typically only happens for certain strings, where BIAL can check that the string value is valid (see below). The + Operator automatically converts arguments of type int and boolean to String. In all other cases, the type system is strict and error messages are displayed if there is a mismatch. Types can be divided in the following groups:
  • Primitive types
    Type Example
    String "Hello"
    int 123
    float 123
    boolean true, false
    String array ["A", "B"]
    int array [1, 2]
    JSON {"key": "value"}
  • BI types (DataSourceAlias, Dimension, Measure, and so on) enable context-relevant input help for API method arguments in the script editor. These special types are sometimes written in enum, array, or JSON format (or even a combination of those ). To view examples, refer to the API reference.
  • Component types (Button, Text, Pagebook, ...)
The visual component types correspond to the list of components in the Components view of the design tool.
Enums
In many cases, the input for a method can be one of a fixed set of values. This set of values is referred to as an enumeration or simply “Enum”. An Enum value is written as <EnumType>.<EnumValue>, for example, ChartType.PIE.
Script Variables
Script variables store expression results. They are useful, for example, for storing intermediate results that are used repeatedly in a script. Script variables have a name composed of the characters A-Z, a-z, 0-9, and _. The name cannot begin with any of the digits 0-9. Like expressions, script variables have a type. There are local and global script variables:
  • Local script variables

    Local script variables are script variables that can only be used in the script in which they were defined, and not in any other scripts. To define a local script variable, open a script with the Script Editor and add a line with the following format:
    var <variable> = <expression>;
    The type of the script variable is automatically determined by the type of the expression.

  • Global script variables

    Global script variables are script variables that can be used in any script of your application. To define a global script variable click the Application in the Outline view, then click in the Property sheet the item ScriptingGlobal > Script Variables. Click the button .... This opens the Edit Global Script Variable dialog box. You can insert a new global script variable and define its name, type, and default value. In addition you can specify whether the global script variable is a URL parameter. If you make it a URL parameter, then you can set the value of this global script variable by adding the global script variable and its URL parameter value to the application’s URL.
Note
Script variable names used as a URL parameter must start with a capital x (X) and must not end with an underscore (_) or a digit (0-9).
Methods Calling the Event Handler
To avoid event handlers calling each other infinitely, which could result in runtime crashes, events on components are only triggered by user interaction on the component and not by scripting. For example, if a user swipes the pages of a Pagebook component, the On Select event is raised, and the relevant event script is executed. In contrast, if the selected page index is set by script using the method setSelectedPageIndex of the Pagebook component, the On Select event is not raised. Another example is, if a user selects a value from a Dropdown Box component, the On Select event is raised and the event script is executed. In contrast, if the selected item is set using the setSelectedValue method of the Dropdown Box component, the event is not raised. However there are situations when you want to execute the relevant event script without duplicating script code. In these cases, each component with an event (On Click, On Select) has a corresponding method that allows the event handler to be called from another handler’s code. For example, the statement BUTTON_1.onClick(); calls the On Click event handler of the Button component with the name BUTTON_1. Another example is the statement TABSTRIP_1.onSelect(); that calls the On Select event handler of the Tabstrip component with the name TABSTRIP_1.
Example
You have created an application with a Dropdown Box component DROPDOWN_1 and a Button component BUTTON_1. If the user selects a value in the Dropdown Box component, the selected value filters the dimension MYDIM in the data source aliases DS_1 and DS_2. For this scenario, the On Select event script of the Dropdown Box component looks like this:
DS_1.setFilter("MYDIM", DROPDOWN_1.getSelectedValue());
DS_2.setFilter("MYDIM", DROPDOWN_1.getSelectedValue());
If the user pushes the Button component, a specific value in the Dropdown Box component should be selected programmatically using the same logic defined for user interaction. In other words, the selected value filters the dimension MYDIM in the data source aliases DS_1 and DS_2. Instead of duplicating the script code of the On Select event of DROPDOWN_1, you add the following statements in the On Click event handler of the Button component:
DROPDOWN_1.setSelectedValue("MYDIMVALUE");
DROPDOWN_1.onSelect();
The benefits of calling the onSelect method increase as you start to work with more uses cases in the application (where you want to set the selected value programmatically) and more statements in the On Select event handler of the Dropdown Box component.
Member Key Format
The most frequently used API methods deal with dimension members in the context of setting filters or variable values. Often the filter or variable values to set are returned from the selection of a user interface component. In SAP Business Warehouse (BW) there are multiple key types; the most important are the internal and the external key types (often also referred to as key formats). Whereas the internal key is a unique identifier for all users (user-locale independent), the external key can be user-locale dependent. By default, all methods dealing with member keys as returned values or as parameters, work with the internal key format. This keeps applications language-independent to ensure that they can work for multilingual user groups. However, you might want to choose the external key format for various situations or reasons:
  • The external key format is more compact and either the application is known to be used only by users sharing the same locale, or the external key format is known to be locale-independent.
  • The number of complex selections is more than the single values that need to be specified as parameters for the API methods setFilter and setVariableValue. In this case, the SAP Business Explorer selection syntax (“Input String”) can be used, which references individual members by their external key.
For these special use cases, SAP Lumira Designer provides “Ext” variants of methods, for example, setFilterExt and setVariableValueExt.