The _Settings Definition

The _Settings definition contains global configuration settings for your Logi application. This topic discusses the elements available for use in the definition.


About the _Settings Definition

The _Settings definition (yourLogiApp\_Definitions\_Settings.lgx) contains the global configuration settings for your Logi application.
 

It includes a variety of unique elements, some required, some optional, that provide overall control of the application. The required and most-commonly-used elements are shown above.

The definition includes information like database connection strings and security information that may need to be changed when deploying the application from development to production. For this reason, care should be taken when considering copying or overwriting a _Settings definition file.

The _Settings.lgx file of a Logi Info application is expected to be in a nested location under the root folder of the application, specifically in: <application root>/_Definitions.

Combining _Settings definition files for multiple applications or "centralizing" them elsewhere is not possible. A _Settings definition can be obfuscated, using the Obfuscation tool in Logi Studio, a common technique used by developers to protect their software products from theft, tampering, and reverse-engineering. For more information, see the Obfuscation Definitions section of Using Logi 12 Studio.

The following sections describe the purpose of the elements that can be used in this definition and provide links to more detailed information, when available.

Back to top

Application Element

(Required)  The Application element determines the general characteristics of the application. Its attributes are:
 

Attribute Description

Caption

Specifies the text to be displayed in browser tabs or title bar, if no captions have been set in other, individual report definitions.

Default Report

Specifies the report definition to run when one is not specified in an rdReport parameter in the requesting URL. When this attribute is blank, the system looks for a definition named "Default".


Back to top

Connections Element

The Connections element is container for Connection elements, which provide the connections to datasources. A connection established here in _Settings is available for use by any number of report definitions.
 

Connection elements are available for vendor-specific and generic datasources, including databases, online services, and data files. In most cases, they simplify the process of connecting to data. More information about them is available in Datasource Connections.

Back to top

Constants Element

Constants are global, literal values that will not change and that can be used in all definitions. They're created in _Settings, using the Constants element.
 

Constants are created, as shown above, as a parameter list and are accessed using @Constant tokens. For example, the value of the first constant in the list shown above would be available using @Constant.EditMode~. For more information on @Constant tokens, see the Token Types section of Token Reference.

The use of constants provides a way to have values referenced throughout your application while only defining them in a single place, which makes maintenance very easy. Constants are often used for values that might change between development and production environments.

Back to top

Event Logging Element

The Event Logging element enables logging of various events such as session starts, authentication, and database queries. Logging works in conjunction with a Process definition file that usually handles inserts into a logging database table.


 

The Event Logging element is a parent for one or more Log Event elements, each of which logs a specific event. More information about event logging is available in Event Logging.

Back to top

External Definitions Element

Application report definition files are normally stored in the your LogiApp\ _Definitions\ _Reports folder. However, developers can instead specify definitions that come from an external data source, such as a database or a web service, using the External Definitions element.

As shown above, the External Definitions element works with its own datalayer, which retrieves the definition data when the application runs. At runtime, the presence of an External Definitions element alerts the Logi Server Engine to automatically include the datalayer's data in the Engine's inventory of report definitions. When the report is called, the Engine will read the definition from the datalayer rather than from the web server's file system and render it.

The stored definition data should be in two columns:

    ReportID ( varchar/nvarchar(50) ) - which contains the report definition name (without .lgx), and
    Definition ( varchar/nvarchar(max) ) - which contains the complete XML source of the report definition.

When building the data, the XML could be copied, for example, right from Studio's Workspace, Source tab, and inserted into the datasource. All values are case-sensitive.

To use an external definition, reference its ReportID value (the literal text - "BalanceSheet" - not as an @Data token) in the Report Definition File attribute of elements such as Target.Report.

Why would you want to store your definitions in a database? It's a bit more complicated to update definitions in this arrangement and it isn't necessarily for everyone. However, it does allow centralized storage of report definitions, integrates with Content Management Systems, provides portability in virtualized-server environments, and works well in web server farms, so it definitely has its uses.

Back to top

File To Database Mapping Element

The File To Database Mapping element enables storing Bookmark, Gallery, and Save files in database tables. Storing this information in a database instead of the file system can make it easier to manage system backups, create cloud deployments, and more. For complete information about the use of this element, see the Storing Bookmark, Gallery, and Save Files in a Database section in Introducing Bookmarks.

The element's attributes now support tokens.

Back to top

General Element

(Required) The General element is the catch-all for a variety of configuration settings and has two child elements, Global Chart Export and Wait Panel. Its attributes include.
 

AttributeDescription

Bookmark Admin Editor Security Right ID
 

Specifies (when using Logi Security) a comma-separated list of Security Right IDs. Users that have one of these rights can edit bookmarks that have been shared with them.

Bookmark Collection Default

Specifies the default Bookmark Collection attribute value, which is used in a number of elements. Using this attribute helps ensure consistent values for all bookmark collections. This value is required when sharing bookmarks with the Bookmark Organizer element. For more information, see Introducing Bookmarks.

If using Logi Security, you can specify a personal collection for each user by including the @Function.Username~ token here.

Bookmark Folder Location

Specifies the fully-qualified path and folder name where bookmarks will be stored. Bookmarks make it easy for users to build a menu of reports with saved input parameters and can save user configurations of Analysis Grids, Analysis Charts, OLAP Grids, and Dimension Grids.

Bookmarks can also be stored in a database, see Introducing Bookmarks

Cookie Expiration

Specifies the number of days a cookie created by the application will last. The cookie expiration date is calculated from the present day. The default value is 30 days. You may set the value to Session (the equivalent of 0 days) and cookies will expire when the session ends.

Cookie Path

Specifies where cookies created by the application will be stored. By default, cookies are stored at the web server level , where they are available to any application on the server. If you want a customized arrangement instead, the Cookie Path attribute allows you to specify a single storage location for all cookies, using a URL.

Enter a single slash ("/") for this attribute value to have all cookies be stored at the web server (domain) level, for example "myServer/", or enter a more complex URL for other locations in the Logi application. The web server domain is assumed, so don't include the domain in the value and begin it with a slash ("/").

Data Cache Folder

Specifies the fully-qualified path and folder name for storing temporary cache files. Ensure that the ASP.NET system account has full access rights to the folder. You can use a token, such as @Function.AppPhysicalPath~, specify part of the path. Temporary files in this folder are only read by the application and it does not need to be accessible by the end users via HTTP. The default value is the application's rdDataCache folder.

For a web farm environment, specify a network folder and change the application's identity from ASP.NET to a network account.

Debugger Security
Right ID
 

Specifies a comma-separated list of one or more Security Right IDs that enable debugging for the current user and session. For more information, see Debug Reports.

Debugger Style

Specifies which style of debugger should be used. Options include:

NoDetail - Prevents any debugger information from appearing when there's an error, so the user cannot see sensitive system security information. This is the default value. Use this option when deploying to production systems.

ErrorDetail - When an error occurs, displays a detailed error message.

DebuggerLinks - Shows the "Show the Debugger Trace Page" icon or similar link at the bottom every report page. Clicking it displays the Debugger Trace Page. Use this option only during development. For more information, see Debug Reports.

DebuggerLinksNoData - Shows the "Show the Debugger Trace Page" icon or similar link at the bottom of every page, but the Debugger Trace Page will not include links to the data. Use this option only during development.

Redirect - When an error occurs, redirects to a your custom error page. You must specify the URL to redirect to in the Redirect Error URL attribute.

Disable Metadata Builder
 

Specifies whether access to the Web Metadata Builder tool will be disabled for everyone. The default value is False.

Access to the Web Metadata Builder can be restricted more selectively by assigning values to the Security elements's Metadata Admin Security Right IDs attribute.

Doctype Declaration

Adds a Document Type Declaration to the top of the HTML output, which alters the way browsers react to style attributes and tags in HTML and Cascading Style Sheets (CSS). Follow the link above for information about each standard option. For more information, see Doctype Declarations.

The default is Html5, which produces this declaration:  <!DOCTYPE HTML>

You can type-in any value that begins with "<!DOCTYPE" if you want to specify a custom option.

Error Log Location

Specifies an optional, fully-qualified path and folder name where Error Log files will be written when an error occurs, if the Log Errors attribute is set to True. Ensure that the account used to run the application has full File Access rights to the folder. The default value is \rdErrorLog in the application folder.

Tokens can be used here, if desired: @Function.AppPhysicalPath~\MyErrorLogFolder

For use with a Web Farm, specify a shared network folder and change the application's identity to a network account.

Filter Case Sensitivity

Specifies the whether the Analysis Filter element will be case-sensitive when matching text values. Also affects super-elements that utilize the Analysis Filter internally, such as the Analysis Grid and Dashboard.

When set to Sensitive, values match only when the case of the text matches. When left blank or set to Insensitive, case does not matter - so, for example, "abc" will match "Abc".

v12.2 SP3 - The option, DataSourceCollation, is also available and applies only when using ActiveSQL datasources. This option sets the filter's case sensitivity to that of the underlying column or database and results in improved filtering performance, especially for columns that are indexed.

IE Compatibility

Specifies the inclusion of the X-UA-Compatibility meta tag in the HTML output. In some cases, especially when it detects that it's browsing an Intranet, Internet Explorer automatically reverts to IE7 compatibility mode, disabling newer browser and HTML features. This attribute helps ensure that Internet Explorer runs in the appropriate mode/version.

The default value is IE=edge, which has IE run using the latest features of the IE browser. Set to None to prevent output of the tag.

iFrame Embedding Host Restrictions

Specifies options for the X-Frame-Options directive in the HTML response. This can be used to restrict how embedded Logi app pages may be framed by a parent application. Specify values such as SAMEORIGIN, DENY, or a free form option such as a single host name value or a list of comma-separated host names.

When set to SAMEORIGIN, the browser will block rendering only if the origin of the parent application browsing context is different than the origin of the embedded Logi report. When set to DENY, browsers will prevent the embedded Logi report from rendering because it is in a frame. When set to a free form value, the browser will block rendering only if the origin of the parent application browsing context is different than the host name value specified.

If a list of comma-separated host names is provided, the parent application needs to supply its own origin information as part of the link-params attribute in the HTML page mark-up, using the custom link parameter "forOrigin". For example, if the value http://hostname1,http://hostname2 is specified then the parent HTML should include the following link parameter as part of the data-linkParams "{'forOrigin','http://hostname2'}". The engine will verify that the forOrigin value matches one of the values of the accepted host names and set the X-Frame-Options directive to allow embedding.

Input Value Delimiter

Specifies the delimiter character to be used in the Request tokens generated by User Input elements, such as Input Select List, that allow multiple value selection.
The default value is a comma - ",".

License File Location

Specifies the fully-qualified path and name for the folder containing the Logi product license file.

Normally, the license file is located in the root folder of each Logi application. However, it may be desirable to have a common location for a single license file for all Logi applications on the server. This attribute specifies such a common folder. If you using this attribute, you must ensure that all Logi applications run under an account with file access rights to files in the specified folder.

License User Tracking Folder

Specifies a fully-qualified path name for the folder where "tracking" files will be stored. Certain special types of product licenses may log anonymous authentication information. The default location is the rdUserLog folder, under the application's root folder.

In some cases, it may be desirable to set a common location on a network for multiple web servers. Ensure that all applications run under an account with file access rights to create and update files in the specified folder.

Log Errors

Specifies whether the Debugger Trace Report page files will be written, as HTML files, to the folder specified in the Error Log Location attribute when an error occurs.

In order to log the same level of detail found in a typical Debugger Trace Report page (Debugger Style attribute set to DebuggerLinks), the Debugger Style attribute must be set to Redirect and you must specify a Redirect Error URL attribute value.

If Debugger Style is set to ErrorDetail or NoDetail, then the log pages will only include the level of detail provided by the corresponding error messages.

The files, while typically small in size, are not managed automatically and the system admin will need to do it manually.

OEM Distribution License

Specifies the code for a valid OEM Distribution License, which allows Logi Info applications to run on a server that does not otherwise have a license key installed. This is especially useful for XCOPY deployments as the Logi Info installer program does not have to be run on the server. Copy the entire XML contents of the OEM license file into this attribute.

Redirect Error URL

Required if the Debugger Style attribute is set to Redirect. Specifies the URL for a custom error page to be displayed when an error occurs. You may specify a relative or absolute URL, and the custom error page must be an .aspx page.

When an error occurs, before executing the redirect to this URL, the system sets a session variable named rdLastErrorMessage. If desired, you can use this variable in the custom error page to display the actual error message.

Report Author Upload Folder Override*

Specifies the default value for the Report Author element's Uploaded File Folder attribute. This can be a fully-qualified file system path, or one relative to the web application. Tokens such as @Function.UserName~ can be used here to individualize the folder. If the folder is outside of the application folder, at runtime the image files will be automatically copied to the rdDownload folder prior to rendering them to the client.

* Prior to v12.2 SP3, this attribute's name was Report Author Upload Folder.

Repository Friendly

Specifies whether or not to format definition source code for use with 3rd-party source code repositories, such as GIT and TFS. This value can be set manually here or by using Studio Options. When a new application is created using Studio's New Application wizard, this value is set to True.

For more information about its effects, see Using Logi 12 Studio.

Script Source Debugger Style

Specifies the level of debugging support for scripting in the Debugger Trace Page. Options include:

Always - Includes a "View Script" link in the trace page when a script is invoked, if the script is more than one line. If it's only one line, then the script line itself is displayed.

OnError - Includes the "View Script" link described above only appears when an error has occurred.

None - No link or script source is included. This is the default value.

Script Value Cache Count

Specifies the maximum number of script formula results to be cached. Caching eliminates the need for a script to be evaluated by the scripting engine repeatedly. The default value is 500. To disable caching, set the value to 0.

Scripting Language

For .NET applications, specifies the scripting language for attributes that support scripting. The default is JavaScript, which is recommended for new applications. VBScript is still supported but is now deprecated.

For Java applications, the scripting language defaults to JavaScript regardless of this attribute setting.

SQL Injection Guard

This attribute
was deprecated - see Description
.

 With the deprecation of this feature, and in general, we highly recommend that you prevent SQL Injection attacks during development by passing all values into SQL statements as parameters using the SQL Parameters element, or by using SQL Stored Procedures. The syntax to be used for parameters in queries vary by database. For MS SQL Server, for example, question mark placeholders are used for parameters:

    SELECT * FROM Orders WHERE OrderID = ?

Injection attacks can potentially perform database inserts, updates, and deletions. A good practice for guarding against such attack-spawned actions is to connect to the database with an account that does not have privileges for those operations, if they aren't needed.

Studio Element Seeker Port
 

The Element Seeker locates elements, in Studio, that have been clicked in the browser and it's enabled when this value is set. This attribute specifies the TCP port number used for communication between Studio and the browser.

For convenience, use Studio's ribbon menu Debug item to enable and disable the Element Seeker.


Back to top

Global Chart Export

The Global Chart Export element is a child of the General element. It automatically enables all Chart Canvas Chart and Gauge elements to make their visualizations available as a .PNG image to be downloaded and saved.

For more information about using this feature, see Export Chart Canvas Charts.

Back to top

Global Style Element

The Global Style element allows you to specify a Theme (see Work with Themes) and/or a separate style sheet (see Intro to Style Sheets) that will apply to the entire application. This provides a single point for appearance management across the application. Values entered here can be overridden in individual reports, if desired, by using the Style element in their definitions.

Back to top

Globalization Element

The Globalization element allows you to set application-wide characteristics related to Internationalization and Localization , and culture. Its attributes include:
 

AttributeDescription

Default Input Date Format

Specifies a date format that will be used when an Input Date element doesn't have its own Format attribute set. For more information, see Format Data.

Default Input Date Reformat

Specifies a date format that will be used when an Input Date element doesn't have its own Input Date Reformat attribute set. For more information, see Format Data.

When this attribute is specified, Input Date element values are reformatted when they're referenced as @Request tokens and the format of @Date tokens are also changed. For more information, see Token Reference.

Default Input Time Format

Specifies a time format that will be used when an Input Time element doesn't have its own Format attribute set. For more information, see Format Data.

Default Input Time Reformat

Specifies a time format that will be used when an Input Time element doesn't have its own Input Time Reformat attribute set. For more information, see Format Data.

First Day Of Fiscal Year

Specifies the first day of the fiscal year, which is used when calculating dates and quarters for fiscal calendars. The value must be in the format MM/DD. For example, if the fiscal year begins on March 5, enter 03/05. The default value is 01/01.

First Day Of Week

Specifies how the first day of the week is determined for @Date tokens that return first and last days of the week, such as @Date.ThisWeekStart~ and @Date.ThisWeekEnd~.

This attribute value is a number representing the days of the week, where: 0 = Sunday, 1 = Monday, 2 = Tuesday, 3 = Wednesday, 4 = Thursday, 5 = Friday, 6 = Saturday

Input Reformat Culture

This attribute has been deprecated.

Java Font Folder

For Java applications only: Specifies the fully-qualified path and folder name where TrueType fonts are located for PDF exports. The folder is required for PDF exports with fonts that contain characters that are not in the ISO 8859_1 character set, such as Arabic, Cyrillic, and Korean language characters. Depending on your Java environment, you may even need to point the Logi application to the location of your regular fonts in order to ensure that they'll be used.

A typical value for a Windows installation will be something like C:\Windows\Fonts. For Linux, it could be something like /usr/local/share/fonts/ttfonts.

Metric Prefix String

Specifies comma-separated list of custom formatting characters for use with Metric Prefix formatting. Setting Format attributes to "mp" formats numbers with a "metric prefix". For example, to format the value 1,234,567 as $1.23M, the Format attribute value is $#.00mp.

Supported metric prefixes are in the range of 1000^-6 to 1000^6 and the default string of formatting characters is a,f,p,n,,m,k,M,G,T,P,E. You can replace this string with your own comma-separated string of characters to represent this range.

User Culture

Specifies a custom value that overrides the "culture" value obtained from the user's browser at runtime. Tokens, such as @Session or @Request, may be used here.

Culture values are specified as a string, such as en-US. For a list of cultures, see your browser's options. For example, in Internet Explorer, select ToolsInternet Options LanguagesAdd.


Back to top

Java Session Copying Element

Java-based Logi applications and non-Logi Java applications may maintain their session variables in different ways. When these two kinds of applications are integrated, they may need to "copy" session variables so they can be shared between them. Logi session variables are accessed via @Session tokens, while standard Java application session variables are accessed via JSP or, in a Java program, via javax.servlet.http.HttpSession.

The Java Session Copying element, which is ignored in .NET Logi applications, enables session variable copying between the two kinds of Java applications. It has four attributes that let you control which variables are copied, which optimizes performance. The "Include" attributes are processed first, then the "Exclude" attributes. The attributes include:
 

AttributeDescription

Copy From Java Exclude

Specifies a comma-separated list of regular expressions that identify the Java application session variables that will not be copied to the Logi Info application session space. Do not use session variable names that contain spaces.

Copy From Java Include

Specifies a comma-separated list of regular expressions that identify the Java application session variables that will be copied to the Logi Info application session space. Do not use session variable names that contain spaces.

Copy To Java Exclude

Specifies a comma-separated list of regular expressions that identify the Logi Info application session variables that will not be copied to the Java application session space. Do not use session variable names that contain spaces.

Copy From Java Exclude

Specifies a comma-separated list of regular expressions that identify the Logi Info application session variables that will be copied to the Java application session space. Do not use session variable names that contain spaces.


In Logi Info versions prior to v11.0.115, almost all session variables were automatically copied, which didn't always produce the best performance. However, if you want to restore this behavior, you can copy the following element source code and paste it into your _Settings definition:

<JavaSessionCopying CopyToJavaInclude="^" CopyToJavaExclude="DebugFile,-bUsesSort$,-tra$,-xmlDef$,-Xsl$,-rdDef$" CopyFromJavaInclude="^"
CopyFromJavaExclude="^rd,^dt" />

Back to top

Path Element

(Required) The Path element tells the Logi Engine where to find definition files and Studio what the application URL is. Its attributes are:
 

AttributeDescription

Alternative Definition Folder

Specifies a fully-qualified path and folder name for a custom location for definition files. This can be useful for web farm configurations or in other cases in which an alternate definition location is useful. The alternate folder must preserve the standard folder hierarchy by containing a _Definitions folder with its traditional subfolders for _Reports, _Processes, _Widgets and/or _Templates.

Definition files will be used from the alternate folder if they're not found in the application's regular _Definitions folder. Do not include the _Settings definition file in the alternate _Definitions folder.

This attribute value can be a physical or network path. If it's a network path, ensure that the ASPNET process account has network file access rights. This is often done by enabling impersonation in Web.config. You may need to set the Anonymous account to a network account.

Application Path

Specifies the URL of the application, which is used by Studio to preview and test the application. This is set automatically by the New Application Wizard. If you move or rename your application, you will need to reset this attribute.


Back to top

Security Element

The Security element configures the application's security features and enables Logi Security. Flexible authentication and authorization elements provide access control at many levels: application, report, process, element and data row. This is discussed in detail in several documents, beginning with Work with Logi Security.

Back to top

Session Timeout Element

The Session Timeout element allows you to ensure that a user's session will not end prematurely, either automatically or by prompting the user, and is discussed in detail in Manage Session Timeout .

Back to top

Startup Process Element

The Startup Process element lets you run a task automatically when a user session begins (i.e., when the application is browsed by a user for the first time). This allows you to set variables, run procedures, and accomplish any other "startup" work you might want to do, and then redirect the browser to a report definition.

Multiple Startup Process elements can be used; they'll be processed in the order in which they're listed in the definition.

When the Startup Process element's First Session Only attribute equals True, the Processes Task runs only for the server's first session. This enables startup processing to occur when the application starts, rather than when any subsequent session starts.

Any Request variables in the query string used to call the application will automatically be available as Request tokens in the process task called with this element. For example, @Request.rdReport~ will contain the name of the report definition.

The startup task runs before Connection elements are processed. This can be especially useful if you want to set session variables based on user identity or security parameters in the task, then use them as @Session tokens in Connection element attributes to create dynamic connections.

Unlike most process tasks, you do not need to use a Response element at the end of this task. Once the startup task is finished, the complete original URL will be sent to the browser again, automatically, so you don' t need to worry about specifying a report definition or forwarding request parameters. It couldn't be easier.

Of course, if you want to do some evaluation in the task, with Procedure.If, for example, and then redirect to some other report definition, you can use Response and Target elements to do that.

More information about Process tasks can be found in Process Tasks.

Back to top

Team Development Element

The Team Development element enables file locking and file history, making it easier to work on Logi applications as a team.

File locking lets users lock and unlock files and see who is using what file. This helps prevent multiple developers from working on the same file at the same time.

File history retains copies of all file revisions. You can list and view old versions and files. Old versions can be "rolled back", thus making them the current version.

For detailed information about Studio's Team Development features, which work with this element, see Using Logi 12 Studio.

Back to top

Wait Panel Element

The Wait Panel element is a child of the General element and is automatically added to all new applications. When present in the _Settings definition, it's global in effect and causes a Wait Panel to be enabled anywhere one can be used, providing a default for the entire application. The Wait Panel element attribute values become the defaults for the entire application.

If a "local" Wait Panel element exists in a report definition, the attributes of that element will be used when displaying a Wait Panel. However, any empty local element attribute values, such as Caption, Class, or Caption Class, will default to the values set in the global Wait Panel element in _Settings.

For all Wait Panel elements (except in the scenario in the previous paragraph):

  • If there is no specific Caption attribute value specified, the value defaults to "Please Wait...".
  • If there is no specific Class value specified, the value defaults to "rdThemeWaitPanel".
  • If there is no specific Caption Class value specified, the value defaults to "rdThemeWaitCaption".

Back to top