SAP

Author

Fabien Aubert

Fabien Aubert

Fabien is a product manager in the SAC analytics designer team. Fabien has over 20 years of experience in Business Intelligence, starting back when he worked at Business Objects. More recently, he held roles such as Lumira Product Owner and Design Studio/Lumira Designer Product manager. He is based in Paris and in his spare time he enjoys traveling, hiking and running.

Keep in touch

Subscribe for the latest news, updates, tips and more delivered right to your inbox.

Subscribe to updates

Category

Learning

Connect with us

Analytics Designer is a powerful capability that allows you to create analytical applications in the SAP Analytics Cloud. An analytic application typically contains some custom logic, expressed with the help of scripts. Scripting brings flexibility, allowing you to implement custom behaviors.

Why Scripting?

You might be wondering why you would want to script and what advantage it could possibly be.

Most modern analytics tools avoid scripting to simplify the designer’s tasks. Users may find it easier to use at first, but they quickly find themselves limited to the scenarios built into the tool.

Scripting allows you to go beyond present narratives, to respond to user interaction in a custom way, to change data result sets, and to dynamically alter layout. Scripting frees your creativity.

Scripting Language Overview

The scripting language in Analytics Designer is a limited subset of JavaScript. It is extended with a logical type system at design time enforcing type safety. Being a true JavaScript subset allows executing it in browser natively. All scripts are run and validated against strict mode. Some more advanced JavaScript features are hidden. Scripts are either tied to events or global script objects.

Type System

The logical type system runs on top of plain JavaScript. It enforces strict types to enable more powerful tooling. The behavior at runtime doesn’t change as it is still plain JavaScript.

Tooling – Code Completion and Value Help

The Analytics Designer scripting framework exposes analytics data and metadata during script creation and editing. This enables

 

  • Code completion in the traditional sense like completing local or global Identifiers
  • Semantic code completion by suggesting member functions or similar
  • Value help in the form of context-aware value proposals like measures of a data source for function parameters

For example, when calling an API method on a Business Warehouse DataSource, the code completion can propose measures as code completion options or values to specify a filter.

 

Events

Scripts always run in response to something happening in the application. Application events are your hook. There are several types of events in analytic applications. Some occur in the application itself and some occur on individual widgets.

Application Events

The application has three events: one that fires when the app starts, one that is called in certain embedded scenarios, and another that is triggered when the application window resizes.

onInitialization: This event runs once when the application is instantiated by a user. It is where you script anything that you want to be done during startup. Like most events, it has no input parameters.

onPostMessageRecieved: If your application is embedded in an iFrame, your SAP Analytics Cloud analytic application can communicate bidirectionally with the host web app using JavaScript PostMessage (see also: https://developer.mozilla.org/ en-US/docs/Web/API/Window/postMessage) calls. It allows the host application to pass information into the analytic application. This event is called whenever the host application makes a post message call into the analytic application.

onResize: the event is cached to be dispatch every 500 ms when the application window resizes. Inside the onResize event, you can use the Layout API to dynamically set the size and position

 

 

Individual Widget Events

Most widgets have an event that is fired when the widget is clicked by a user. However, some widgets have no events, such as text labels. Data bound widgets generally have an event that is fired when the result set of the data source changes.

Most events have no input parameters, like onSelect and onResultChanged.

 

Global Script Objects

Global script objects act as containers. They allow you to maintain and organize script functions that are not tied to any event and are invoked directly. You can maintain libraries of re-usable functions. These library scripts are called functions.

 

Accessing Objects

You can access every object in the Outline pane such as widgets, script variables, or script objects by its name when you are working on a script.

Script Variable

By referencing Script Variable in Calculated Measure, users can easily build a what-if simulation with query results. For example, an analytic application developer can bind a calculated measure which references one script variable (ScriptVariable_Rate) to a chart.

 

 

Scripting Language Features

Normal JavaScript is weakly typed and dynamically typed. Weak typing means that the script writer can implicitly coerce variables to act like different types. For example, you could have an integer value and treat it as if it were a string. Dynamic typing means that the runtime will try to guess the type from the context at that moment and the user can even change the type after the variable is already in use. For example, you could change the value of the beforementioned integer to another type of object at will; “Dear integer, you are now a duck”.

SAP Analytics Cloud, analytics designer forbids both. Once you have a duck, it remains a duck and you can’t recycle variable names as new types. If you want something else, you’ll need another variable. It is also strongly typed, meaning that if you want to use an integer as a string, you’ll have to explicitly cast it. Both are a consequence of enabling the rich code completion capabilities in the editing environment.

The analytics designer scripting language is still JavaScript. You can write perfectly valid JavaScript while treating the language as if it was strongly and statically typed.

No Automatic Type Casting

A consequence of strong typing is that you can’t expect automatic conversions. The following is valid JavaScript:

var nth = 1;

console.log("Hello World, " + nth);

In analytics designer, you will see an error in the script editor, informing you that auto-type conversion is not possible, and the script will be disabled at runtime, until fixed. Instead, you should explicitly cast nth to a string.

var nth = 1; console.log(“Hello World, ” + nth.toString());

Accessing Objects

Every object (widget or global script object) is a global object with the same name as in the outline. Suppose you have a chart in your application, named Chart_1 and want to check and see if it is visible. You can access Chart_1 as a global variable and then access its functions, in this case to see if it is currently visible.

var isVis = Chart_1.isVisible();

Finding Widgets with Fuzzy Matching

The application author can type in the complete name of a widget or just some first letters. By typing CTRL+Space, the system either Scripting in Analytics Designer 42

  • Completes the code automatically if there is only one valid option
  • Displays a value help list from which you can select an option

Fuzzy matching helps you finding the result even if you have made a typo or the written letters are in the middle of the function. Fuzzy matching is applied automatically for the standard code completion (for example, “cose” → “console”).

The script validation runs automatically in the background and shows errors and warnings indicated with red and orange underlying and a red or orange marker before the line number.

External Libraries  

There is no provision in SAP Analytics Cloud, analytics designer for importing external JavaScript libraries. You can use the standard JavaScript built-in objects such as:

  • Math
  • Date
  • Number
  • Array
  • Functions on String

All standard functions listed in the SAP Analytics Cloud, analytics designer API Reference are supported even if some browsers don’t support them natively.

For example, String#startsWith is not available in Microsoft Internet Explorer, but can be used in SAP Analytics Cloud with all browsers.

Loops  

Two types of JavaScript loops are possible in SAP Analytics Cloud, analytics designer, for and while loops. Other types, such as foreach iterators, are not supported.

For loops

 for loops are standard JavaScript for loops, with one caveat. You must explicitly declare the for iterator. This is valid JavaScript, but it isn’t accepted in the script editor:

for (i = 0; i < 3; i++) {

console.log("Hello for, " + nth.toString());

}

Instead, explicitly declare i. The example below is valid:

 

for (var i = 0; i < 3; i++) {

console.log("Hello for, " + nth.toString());

}

While loop

We fully support while loops in SAP Analytics Cloud Analytics Designer:

var nth = 1;

while (nth < 3) {

console.log("Hello while, " + nth.toString());

nth++;

}

 

for in loop

An additional type of loop is the for in iterator. Suppose you had a JavaScript object: you can iterate over the properties with the for in loop. Data selections are JavaScript objects and can be iterated over:

var selection = {

“Color”: “red”,

“Location”: “GER”

};

for (var propKey in selection) {

var propValue = selection[propKey];

};

Double and Triple Equals Operators

Plain JavaScript has two kinds of “equals” comparison operators, == (double equals) and === (triple equals). The main difference between these is that double equals has automatic type casting while triple equals doesn’t. With triple equals, both the value and type must be the same for the result to be true. The triple equals is known as the strict equality comparison operator (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/ Equality_comparisons_and_sameness).

SAP Analytics Cloud, analytics designer has no automatic type casting. It supports

  • Triple equals
  • Double equals only if both sides have the same static type

The examples below show the difference between double and triple equals operators. In both cases, there is a variable aNumber, with an integer value and we are comparing it to the string “1”.

In the double equals case, aNumber is cast to string and compared. The result is true, and the if block is entered. In the triple equals case, aNumber is not cast to string and the comparison is false, because the values are of a different type.

This is true, and you can see the if statement is entered:

var aNumber = 1;

if (aNumber == "1") {

...

}

This is false, and you can see the if statement is skipped:

var aNumber = 1;

if (aNumber === "1") {

...

}

if and else Statements

The statements if and else are supported. Remember that there is no automatic type casting and double equals are valid only if both sides have the same static type:

if (nth === 1) {

console.log("if...");

} else if (nth < 3) {

console.log("else if...");

} else {

console.log("else...");

}

this statement

The this keyword allows you to ignore the name of the object. It is simply the object that this script is attached to, regardless of what it is called. It doesn’t matter and is merely a stylistic choice. With this, refer to

  • The instance itself within widget scripts or script object functions
  • The parent instance explicitly by its variable name, such as Chart_1
  • The parent instance as this

When performing the above console print on one of the events of Chart_1 itself, use the following variation of the code:

var theDataSource = this.getDataSource();

console.log(theDataSource.getVariables());

 

switch Statements

You can use normal JavaScript switch statements:

switch (i) {

case 0:

day = "Zero";

break;

case 1:

day = "One";

break;

case 2:

day = "Two";

break;

}

break Statement

You can use break to break out of loops and switch statements, as seen in the example above.

In this blog post you have seen the main principles of scripting in analytics designer. In a future blog post, I will explain how to use the script editor in Analytics Designer

To learn more about scripting in Analytics designer, check out Analytics Designer Handbook

SAP Analytics Cloud earns a top ranking from BARC

See how SAP Analytics Cloud performed in the world’s largest survey of Business Intelligence software users.