* .config File Reference

[This is preliminary documentation and is subject to change.]

In the .config files chapter under Configuration Guide, it is described, that the TOPICA framework uses the following .config files:

Location (folder)	Filename
Framework Folder	Web.config
Configuration Folder	Application.config
Configuration Folder	Server.config

It is also possible to have a configuration specific Web.config file - this is seldom used (and ignored here).

This topic contains the following sections.

Overall Structure
Keys
Using .config file parameters - examples

Overall Structure

The Web.config in the framework adheres to the structure defined by ASP.NET. This structure is defined by a schema (an XSD file), that comes with Visual Studio.

Caution
Only framework developers should edit Web.config. All other roles that need to know about .config files (configurators and application developers) are not allowed to edit this file - - but they WILL need to read this file, as this is the file that defines all the "appSettings", that the TOPICA framework understands!

Example contents of Web.config

Copy

<?xml version="1.0" encoding="utf-8"?>
<configuration>

  <appSettings>

    <!-- ASP.Net / .Net stuff omitted -->

    <!--  ************************************************************************************
          Titles
    -->
    <add key="ApplicationTitle" value="{config}" />
    <add key="ApplicationVersion" value=""/>
    <add key="Environment" value=""/>
    <add key="WindowTitle" value="{ApplicationTitle + Space + ApplicationVersion +  &quot; - &quot; + Webserver.host + Space + Environment}"/>

    <!--  ***************************************************************************************************************
          Performance log
    -->
    <!-- log to database -->
    <add key="PerformanceLog.Database.Enabled" value="true" />
    <add key="PerformanceLog.Database.ServerTiming.Enabled" value="true" />
    <add key="PerformanceLog.Database.ServerAndClientTiming.Enabled" value="false" />
    <add key="PerformanceLog.Frameset" value="false" />

    <!--  ***************************************************************************************************************
          Log in 
    -->
    <!-- Password change -->
    <!-- PasswordChangeRule is a TOPICAbasic computation that should return a bool value indicating whether it is time to change the password -->
    <!-- example: datediff_day(User.PasswordChangedDate, Now) > 60 -->
    <add key="PasswordChangeRule" value="false" />
    <!-- PasswordChangeMessage is the message given to the user when password must be changed (use of inlined {} TOPICAbasic is allowed) -->
    <!-- example: Din adgangskode er 60 dage gammel den skal ændres. -->
    <add key="PasswordChangeMessage" value="" />
    <!-- PasswordChangeWarnRule is a TOPICAbasic computation that should return a bool value indicating whether the user should be warned about pending password change -->
    <!-- example: datediff_day(User.PasswordChangedDate, Now) > 46 -->
    <add key="PasswordChangeWarnRule" value="false" />
    <!-- PasswordChangeMessage is the message given to the user when there is a password change pending (use of inlined {} TOPICAbasic is allowed) -->
    <!-- example: Password must be changed no later than {adddays(User.PasswordChangedDate, 60)}. Do you wish to chenge it now? -->
    <add key="PasswordChangeWarnMessage" value="" />
    <!-- PasswordStrengthRule is a TOPICAbasic computation that should return a bool value indicating whether a password is strong enough -->
    <!-- example: regex_match(password, &quot;^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?!.*\s).{8,}$&quot;) -->
    <add key="PasswordStrengthRule" value="true" />
    <!-- PasswordStrengthMessage should describe the rules for password strength-->
    <!-- example: "Password must contain at least one digit, one lower case letter and one upper case letter. Password must containt at least 8 characters. Blanks are not allowed -->
    <add key="PasswordStrengthMessage" value="" />
    <!-- PasswordSaveClearTextVersionToDatabase indicates if password is saved/updated in clear text or not (password is always saved using hashing) -->
    <add key="PasswordSaveClearTextVersionToDatabase" value="false" />
    <!-- -->
    <add key="PasswordCaseSensitive" value="true" />
    <add key="ForcePasswordChangeForNewEmployees" value="false" />
    <add key="UsingDomain" value="false" />
    <add key="LoginAsEmployee" value="true" />
    <add key="LoginAsPatient" value="false" />
    <add key="LoginForm.PanelLogin.Width" value="500px" />
    <!-- start page after "log in as patient" - legal values "None", "Standard", "Custom"-->
    <add key="LoginAsPatient.StartPage" value="None" />
    <!-- user with blank passwords are not allowed to login when running plain TOPICA (outside contextmanager OCW etc.) -->
    <add key="DenyOutOfContextLoginWithBlankPassword" value="false" />
    <add key="NewsLogin" value="true" />
    <add key="NewsStart" value="true" />
    <!-- Session cookie check -->
    <add key="SessionCookieCheck" value="true" />
    <!-- Session time-out values -->
    <add key="SessionTimeOutDays" value="1" />
    <add key="SessionTimeOutHours" value="" />
    <add key="SessionTimeOutMinutes" value="" />
    <!-- Required profile or permission -->
    <add key="Login.RequiredProfile" value="" />
    <add key="Login.RequiredPermission" value="" />
    <!-- Overwrites default message if not empty -->
    <add key="Login.DeniedMessage" value="" />

    <!--  ***************************************************************************************************************
    <!-- 1000+ appSetting key/value pairs omitted ... -->

  </appSettings>

  <system.web>
    <!-- omitted ... -->
  </system.web>

  <system.webServer>
    <!-- omitted ... -->
  </system.webServer>

  <runtime>
    <!-- omitted ... -->
  </runtime>

  <system.web.extensions>
    <!-- omitted ... -->
  </system.web.extensions>

</configuration>

The application/environment specific .config files (Application.config, Server.config) have the SAME overall structure as Web.config, except that only the <appSettings> ... </appSettings> element is used.

Example contents of Application.config (from several of the demo configurations, that come with the framework):

Copy

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="ApplicationTitle" value="{config}" />
    <add key="WindowTitle" value="{ApplicationTitle}" />
    <add key="Culture" value="en-GB" />
  </appSettings>
</configuration>

Example contents of Server.config (from the demo configuration DemoForms, that has been connected to a database):

Copy

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="Database" value="Data Source=.\EXPRESS2014;Initial Catalog=DemoForms427;Integrated Security=False;User ID=DemoForms427_AppLogin;Password=app" />
  </appSettings>
</configuration>

Note
An application may only run, when both Application.config and Server.config exist, and Server.config must define a useable connection string in the "Database" parameter.

Keys

Every parameter / setting defined in the appSettings element of the framework's Web.config file may be overridden in Application.config and/or Server.config. If a key is defined in both files, the value from Server.config is used.

Web.config contains more than 1000 "appSettings". The list of "appSettings" recognized by the TOPICA framework depends on the version. When a new versinon of the TOPICA framework is developed, some parameters may be removed, and some may be added.

Note
At each new relase of the framework, consult the Release Notes - here added / removed keys will be listed.

It is not practical to list all the keys (and associated legal values) here (that would be a maintenance nightmare...). Refer to Web.config for an exhaustive list (there are some XML-style comments, that should help with the understanding).

Caution
Some of the keys in Web.config may be obsolete. This will happen, when a new version of the framework does not use the key any more, and the developer forgot to remove the key from Web.config.

Below is a description of a few keys, including some of the most importants ones, and the keys used in above examples.

Key	Description
ApplicationTitle	The title of the (end-user) application.
WindowTitle	The title display the browser window / tab. May contain "embedded" TOPICA Basic expressions, which makes it possible to display dynamic content in the window title, e.g. the logged-in user. Example: Copy <add key="WindowTitle" value="{configuration} webserver={webserver.name} database={db.name} {if(isnull(user),blank,"user=" + user.username)}" /> This will display the configuration name, webserver name, database name, and user name when user is logged in. (The check for logged in user is made, because the window title is displayed for ALL pages, including the log in page, where no user is logged in yet.)
Culture	The "culture" that the configuration is constructed for. As described in localization, a given configuration is developed for one specific culture (language). Legal values are defined by the database creation scripts. This ensures that the list of valid cultures for databases and configurations match. The value defined in the configuration is automatically used, when the administration module, is used to crate a database for a configuration. Should be specified in Application.config.
Database	The "connection string" used to connect to the database. Automatically set by the administration module, when it is used to connect a configuration to a database. Must be specified in Server.config - the database to connect to will depend on the environment.
Environment	Optional description of the current environment Should be specified in Server.config.
LogInAsEmployee	Enable log in as employee. Default value: true.
LogInAsPatient	Enable log in as patient. Default value: false. May be set from the administration module.
UsingDomain	Only used when LogInAsEmployee is true Default value is false. In this case, employee users are only identified by username. The login form (for employee users) will display fields for username and password. The user interface for user administration will NOT display a field Domain. When overridden to true, employee users are idntified by (domain, username). The login form (for employee users) will display fields for domain, username and password. The user interface for user administration will display a field Domain.

Using .config file parameters - examples

All .config file parameters may be read from TOPICA Basic expressions.

For simple key names (without '.' characters), simply specify the key name:
Display application name
Copy
```
"Current application name is: " + ApplicationTitle
```
The type of ALL parameters (when read from the .config file) is String - even those that should logically be Boolean (legal values true and false). Use the type conversion function CBool to convert from String to Boolean:
Display different texts depending on whether log in as patient is enabled or not
Copy
```
If(CBool(LogInAsPatient), "Log in as patient is enabled", "Patients cannot log in")
```
Keys that contain '.' cannot be used directly - use the function ConfigString instead:
Display information on performance logging
Copy
```
"Log performance information to database: " + If(CBool(ConfigString("PerformanceLog.Database.Enabled")), "Yes", "No")
```