Introduction

The Reportal scripting capability enables developers to leverage the power of Forsta Reportal with greater flexibility for report interface customization. Most advanced Forsta Plus reports contain a quantity of script code; the scripting functionality is added to Reportal to enable the user to, for example:

• Perform custom permission control.
• Build aggregated table definitions based for example on user information (e.g. enduser role or company) or parameter values (e.g. selected project and question/question type).
• Build the domain (valid values) of parameters dynamically.
• Mask a parameter domain dynamically, based for example on information about the user (usertype, company or role).
• Send email.

The target audience for using Reportal Scripting is developers familiar with programming in Microsoft developer tools.

Scripting language

The scripting Language is Microsoft JScript.NET. This is a modern scripting language with a wide variety of applications. It is JScript extended with features of class-based languages. All script code in Forsta Plus will however be wrapped as functions inside a class. This means that you cannot define your own classes in Forsta Plus scripts, except in the Codelibrary scripts.

Scripts are used for:

• Building dynamic components on a report page
• Dynamically changing the components based on various criteria listed below
• Hiding report pages or components on report pages
• Controlling user access to parameter values and initializing parameter values based on user-related criteria.
• Validating parameter values selected by user
• Creating dynamic filters with multiple execution points.

The following criteria are used to change and\or hide report pages and components:

• Parameter values selected by user
• User’s organizational hierarchy level
• User role
• User IP
• Table cell value
• Report export mode.

Forsta Plus uses Microsoft’s the JScript .NET scripting engine to evaluate all Reportal components and to execute scripts. The run-time environment of the report engine supplies a number of functions and objects that provide references to and let you manipulate report and survey variables.

Syntax highlighter

A syntax highlighter is enabled by default in all areas in Reportal where scripts can be written (go to Syntax Highlighter Overview for more information). If the BETA CodeCompletion component is not enabled, this syntax highlighting will be used. When the syntax highlighter is in use, each time the Tab key is pressed, the current line of script is indented one step. Each press of the Shift-Tab keys removes one indent from the line. Note that the Tab key does not insert a tab in the text. To disable the syntax highlighting, in Survey Designer, go to the Design page > Item Editor menu and uncheck the “Syntax highlighter" option.

Scope

This documentation covers some of the fundamentals of JScript.NET and the functions and objects provided by Forsta Plus. This manual only covers server-side programming, i.e. scripts that are running on the server. It does not consider client-side scripts (scripts that run on the respondent's browser – typically written in JavaScript), so for example scripting of HTML elements is outside the scope of this documentation.

For detailed information, refer to the Scripting documentation.