Web GUI

The Thinkwise Web GUI is an ASP.NET application and runs on Microsoft Internet Information Services (IIS).

Set up IIS

The Thinkwise Web GUI runs on IIS version 8 or up (10 is advised) and requires the .NET Framework 4.7 as well as the ASP.NET Framework.

An IIS version is included with the standard installation of Windows on a server or PC. Different versions of IIS are released with the different versions of Windows. Checking the installed IIS version can be done by typing http://localhost in the web browser, the IIS version screen will then be displayed.

IIS 8 welcome page

The standard installation of IIS does not contain all components that are needed to run the Thinkwise Web GUI. The right components can be enabled via Windows' Windows Feature screen, which is accessible via the Windows control panel. In the image below, the necessary components are for different Windows versions.

Windows Features screen in Windows 10

Windows Server 20012R2 features

Deployment

To deploy the Thinkwise Web GUI to IIS, copy the GUI files to the web server. The default website directory of ISS for web applications is C:\inetpub\wwwroot. It is advised that the GUI folder is given the name of the application. That way, various GUIs can easily be kept separate from each other.

Set up the application pool

The Web GUI runs under a .NET v4.5 application pool and requires .NET v4.7.2 to be installed. The web application can be started, stopped and restarted via the application pool, with the application being able to gain access to the disk and potentially also to the database. It is advised that each application has its own application pool made for it.

• Name: give the application pool a suitable name, related to the corresponding application to which this is going to be connected.
• .NET CLR: choose the .NET CLR version for the application pool. Version 4.0 is connected to .NET framework 4.7 which is used by Thinkwise applications.
• Managed pipeline mode: set this to 'Integrated'.

Application pool identity

Ensure that the Application Pool Identity has the right to read files in this directory. The Application Pool Identity likewise needs permission to write on the Cache and App_data directory in the Web GUI. If these directories do not yet exist, they can be created in the application's folder. The Cache directory is used to store a user's model in order to speed up the log-in process. The App_data directory is used by the file upload control and the preview component to temporarily store files.

note

To verify the permissions, check whether there are files in the Cache folder after logging in.

The rights can be altered by right-clicking the directory in the security tab.

Security properties of a folder

If the application pool runs under an Active Directory user, the user will be selected from the domain:

If a built-in application pool is used, the location needs to be that of the current machine. The application pool user is then IIS AppPool\[name]:

After checking the name, it is recognized.

Add application

The application's directory set up on the web server in C:\inetpub\wwwroot or a similar location can now be found in the IIS Manager as a virtual directory.

This virtual directory needs to be converted to an application. By right-clicking the directory, it is possible to convert these into an application. A dialogue will appear in which the name, the location of the GUI directory and the application pool can be specified.

Add Application

• In the Alias field, the web application can be provided with a name. The alias will be used in the URL of a web server. The local URL of IIS is: http://localhost/. The application will be accessible via: http://localhost/[application_name].
• With Application Pool, choose the pool that has been created for this application.
• With the buttons for Connect As and Test Settings, it can be tested whether the rights on the application directory for the various accounts have been correctly established.
• Turn Enable Preload on if this option is available. More information is available here.

Now that the web application has been applied to IIS, the GUI can be opened via the browser. For this, open a local browser and go to http://localhost/[application_name]. Now, the log-in page of the GUI will appear in the browser. The next step is to configure the application so that it is also possible to log in.

Configuration

settings.ini

After the GUI has been applied to IIS, it can be set up by modifying the configuration file. That way, the GUI will know where the meta model must be loaded from and where the data of the customer has been saved. The configuration file is in the root of the GUI folder and is called settings.ini.

After changing the settings, it is necessary to restart the Application Pool.

Authentication

The Web GUI offers various possibilities in the field of authentication and password management for which extra settings are needed. This concerns:

• IAM authentication
• Logging in with an e-mail address
• Changing and setting a password

In order to make these functions possible from the Web GUI, the GUI needs to have a database service account with which the user can be validated to log in.

Contrary to versions 2018.2 and earlier, the service account should not be created as a user in IAM. The service account only needs full access to all the databases present in IAM, including the IAM database itself. None of the end users accessing the applications require any physical permissions on any database. Users using RDBMS authentication do need to be created since they will be authenticated by attempting to open a connection to the meta-database.

The service account can be configured in the web.config file of the application, the settings.ini file or to use the Application Pool Identity.

web.config

Add the following line to the connectionStrings section in the web.config or machine.config:

<add name="TsfGlobalUser" connectionString="User ID=myUser;password=myUserPassword" />

Sensitive information in the web.config file, like connection strings and passwords, can be encrypted using Protected Configuration. This way, only the Web GUI will be able to decrypt the information in the web.config file.

To encrypt a configuration section of the web.config file, use the aspnet_regiis.exe tool with the -pe option and the name of the configuration element to be encrypted.

1. Open an administrator command window in the inetpub\wwwroot folder.

2. Execute the following command to encrypt the connectionStrings section of the web.config file:

   C:\Windows\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe -pe "connectionStrings" -app "/myApplication"

settings.ini

The GlobalUser and GlobalUserPassword parameters in settings.ini.

note

This means of storage is not secure because the account details are saved as plain text on the web server. Only use this for testing purposes.

Application Pool

The Application Pool Identity of the application in IIS (with regard to Windows authentication) is used.

IAM Authentication

IAM authentication is meant to simplify the management of large numbers of IAM users. IAM Authentication users are only registered in IAM and not on the database. When logging in, the account details are validated with IAM.

The Web GUI uses the provided IAM account to connect the end product databases for all IAM Authentication users. Therefor, always use the provided tsf_user() function to retrieve the username from within SQL logic, instead of the functions provided by the RDBMS.

Passwords

An initial password for IAM authenticated users can be set using the Change password task in IAM. There is also the option of letting the users set up a password themselves upon logging in for the first time, by redirecting the user to the following link: https://[url]/[application]/ResetPassword.aspx.

To change the password for RDBMS user, the service account must have alter login rights on the database server.

In order to set the password, the GUI uses email functionality to ensure that the user who wants to set up the password is the valid user. During this procedure, a Validation code is sent to the user's e-mail address. The e-mail address can be registered to the user in IAM. Ideally, choose an e-mail address that no other users have access to.

SMTP

The GUI will send e-mails via an SMTP (Simple Mail Transport Protocol) server. Which SMTP server must be used can be specified via the settings.ini or IAM extended properties.

This concerns the following settings:

• SmtpServer
• SmtpPort (default port 25)
• SmtpEnableSsl (default is No)
• SmtpFrom (the from e-mail address)
• SmtpUser (optional)
• SmtpPassword (optional)

The account details for the SMTP server can also be stored encrypted in the web.config so that that account details are not stored as plain text on the web server. See here for information about this.

The content of the e-mail is displayed in the language of the user. The translations can be overwritten per client project with the translations in the SF.

Translation object	Default translation (English)	Parameter
set_password_mail_subject	Set password: {0}	{0} - Title of the application.
set_password_mail_body	We received a request that you want to set your password. In this mail we send you a code which you need to set a password. \<br\/>\<br\/> \<hr>{0}\<hr\/>\<br\/> Copy this code to the '\<i>Validation code\<\/i>' field in the application where you requested a new password. If you have closed the application already you need to request another code.\<br\/>\<br\/> A \<strong>strong password\<\/strong> contains a minimum of 8 characters, numbers, lower and upper case letters, special characters and does not include any part of your username.	{0} - Validation code

Logging in with e-mail

Users can also log in with an e-mail address in the Web GUI. The e-mail address of the user is registered in IAM. The GUI needs a general IAM account in order to connect the e-mail address to a user in IAM to log in.

ADFS

Using ADFS (Active Directory Federation Services) it is possible to make an AD domain controller available in a secure way outside your own network. A web environment, in which the Web GUI has been made available, is made available on the internet via the DMZ. More information about this (as well as the setting up of it) is available here.

Integrated Security

The Web GUI supports Integrated Security. Domain users can log in on the Web GUI with it without entering credentials. How this has to be set up is explained here.

Google Maps API key

If a Google Maps control is used in the application, it is necessary to request a Google Maps API code from Google in order to correctly display the map. This code can be requested for the URL from the application. A Google account is needed to make such a request.

To request a key, go to https://console.developers.google.com/apis and log in with your Google account. The gmapapikey parameter can be used to set up the requested API Key for the Web GUI. The same code can also be used for any other application on this URL.

Captcha

Hackers can use a brute force attack to guess a user's password. In order to prevent them from trying various passwords back-to-back, a captcha can be used at log in so that the log in process is delayed.

Captcha

Use the LoginCaptchaNoise and ResetPasswordCaptchaNoise extended properties to enable the Captcha for login and password reset.

Session timeout

The Web GUI has a mechanism that tells the web server every five minutes whether the user is still active (as long as the tab is open). With this, the Session timeout of IIS is unnecessary.

This interval can be configured for the Web GUI via the KeepAliveSession extended property. A value of 0 or lower will deactivate this function.

More information about the setting up of the Session Timeout of IIS can be found here.

Server/Database information

Within the application, standard information is displayed to the user about which project is connected and on which server. This happens, for example, on the log-in page and on the start tab of the ribbon.

This information can be hidden via the ShowLoginInfo extended property.

Performance

Warm-up application

A known problem for ASP.NET applications is that the first request takes longer before the page is available for the user. This occurs if the application has been unused or after a recycling of the IIS Application Pool.

How Application Initialization can be applied on the Application is described here.

The Web GUI contains a Bootstrap.ashx page, which simulates the logging in of a user. This page runs the log-in process to IAM. Furthermore, components of the application that are used from the main page of the GUI are pre-prepared, such as Crystal Reports reports, components etc. The general IAM user that can be saved to the GUI is used to log in.

By adding the following rules in the web.config file in the system.webServer> section, this page is requested after recycling the Application Pool.

<system.webServer>
   <applicationInitialization
      doAppInitAfterRestart="true"
      skipManagedModules="true"
      remapManagedRequestsTo="startup.htm">
      <add initializationPage="/Bootstrap.ashx"/>
   </applicationInitialization>
</system.webServer>

The RemapManagedRequestsTo specifies an HTML page to display during the recycling of the Application Pool.

For more information about this IIS feature: http://www.iis.net/learn/get-started/whats-new-in-iis-8/iis-80-application-initialization

note

Caution: changing the web.config file causes the application to reload.

Troubleshooting

Enable logging

To write a detailed log file to disk and to set the log level, see here.

Images are missing

GUI icons and images need to be uploaded to the database. Make sure that they have been uploaded properly. If the images were uploaded in a version older than 2020.2 make sure they are not still using a file system path. Icons can be uploaded from file system paths by executing the task "Upload images and reports to database" from the advanced menu under "Master data" - "Software Factory". If the file path doesn't point to a valid file the icon needs to be uploaded at the corresponding object.

Custom error pages are not displayed

The Web GUI supplies as number of custom error pages to deal with error messages and invalid requests. If these pages are not displayed correctly, IIS needs to be configured to make it work.

Default IIS error page instead of the Thinkwise error page

Enter the following command in CMD for this:

%windir%\System32\inetsrv\appcmd unlock config -section:system.webserver/httperrors

To display the error pages for URLs ending in one or more .:

• Download and install the URL Rewrite module if it is not available
• Add the following URL Rewrite rules to the web.config of the server or the application, so that it works for all of the applications and that the GUI can continue to update.

<rewrite>
  <rules>
    <rule name="Remove Trailing Dots after some text" stopProcessing="true">
      <match url="^(.*[^.])\.+$" />
      <action type="Rewrite" url="{R:1}" />
    </rule>
    <rule name="Remove All Dots" stopProcessing="true">
      <match url="^\.+$" />
      <action type="Rewrite" url="/" />
    </rule>
  </rules>
</rewrite>

When configured correctly, a proper page will be displayed for all errors and unknown URLs of the application which fits in with the rest of the application.

The error messages will be displayed to the user on the CustomError.aspx page. In end user mode, only the notification An error has occurred will appear. This happens when a serious error occurs whereupon the work cannot be restarted. To acquire more information about an error message, you can execute the GUI in Developer mode and repeat the reproduction steps or look it up in the Windows Event Viewer under Windows Logs > Application.

Overview of error messages

For 404 errors, the Web GUI displays a FileNotFound page.

FileNotFound message

For a full list of HTTP error codes, see https://nl.wikipedia.org/wiki/Lijst_van_HTTP-statuscodes.

info

When adding your own error pages, please note that there are two types of error pages, depending on the URL.

Slow request responses on Azure

If you encounter slow SignalR request responses when deploying on Azure, the reason can be that you are not using WebSockets.

The solution may be to enable Web sockets in Azure, since the Web GUI uses web sockets. This is the most efficient way to send task progress messages back and forth.

note

Background information: A WebSocket is a constantly open connection between the web server and the client, where both parties can send messages to each other.

SignalR uses web sockets and checks if there is support for web sockets. If not, SignalR chooses an alternative way to achieve two-way communication.

For more information about WebSockets in Azure, see this Microsoft blog.

Enable web sockets in Azure

To enable web sockets in Azure:

1. In the Azure portal, select the app service for which you want to enable web sockets.
2. Select Settings > Configuration from the menu on the left-hand side.
3. Select the General settings tab.
4. Under Platform settings, set Web sockets to On.

Database connection with DB2 does not work

See here.

Crystal Reports

See here.