Search

Edition: Futurama Website

Module: Futurama HTML

User: System administrator

Prerequisites

- License file

- User name and password for Futurama downloads

- Windows 2008 R2 server or higher (for client Windows 7 or higher)

- .NET Framework 4.6.2 with ASP.net to be installed

- Internet Information Server 7.5 or higher

 

Description

To create website applications with Futurama, the module Futurama HTML has to be installed. At this page you can find the steps to install this module.

Download

Visit the Futurama website www.futurama.eu to download the Futurama HTML code:

  • Go to www.futurama.eu
  • Go to the download section of the Support menu
  • Log in with user name and password
  • Click the most recent Futurama release
  • Extract the zip-file 

Installation

Release folder

Use the release code from the folder 'site'.

Installation initial version

If this is the first installation of the Futurama HTML code for a new application follow the steps in this paragraph. If you already have a working application and are intended to upgrade this to a new Futurama version consult the next paragraph 'Upgrading existing version'. To install the Futurama HTML module for a new application follow the next steps:

  • Create at the Windows webserver a new folder in which the code from the release folder can be installed
  • Copy the code from the release folder to this new folder
  • Copy the license file to this new folder
  • Rename the default.config to web.config (see the description in chapter 'Configuration' for the way the web.config can be configured)
  • Within IIS create a new application. Choose as physical path the path to the new created folder
  • Create an application pool in which this application has to run. Make sure the application runs on .Net Framework v4.0.30319
  • Make sure the setting 'LoadUserProfile' within your application pool is set to true when using an external identity provider.
  • Choose from your application this application pool
  • Choose an url you want to use for the website application with Futurama, and configure that the website application listens to this url

Upgrading existing version

If you already have installed the Futurama HTML code, and want to upgrade this to a new version follow the steps in this paragraph. If this is the first installation follow the steps in the preceding paragraph 'Installation initial version'. Follow the next steps to upgrade an existing version of the Futurama HTML:

  • If you update from a Futurama version before Futurama version 18.02 you need to install .NET Framework 4.6.2 first
  • Open the folder at the Windows webserver where you have installed the Futurama HTML code
  • Copy the code from the release folder to this folder.
  • Make sure the application pool runs on .Net Framework v4.0.30319
  • Convert existing Futurama documents (see below 'Installation Futurama application) to the new Futurama version. See the chapter 'Converting Futurama Documents' at the page 'Installation Futurama Editor' for more information regarding the conversion of Futurama documents

Installation Futurama application

After installing the Futurama code you have to install your Futurama application. The Futurama application is a folder containing Futurama xml-files and other files that define the website. Install this folder in the same folder as the installation of the Futurama code.

Download files

You can use a sample application to test if the Futurama HTML installation works. Follow the next
steps to install the sample Futurama application:

  • Download the zip-file with the sample Futurama application from this page;
  • Extract the contents of the zip-file;
  • Copy the folder "SavingsAccount" to the folder that contains the Futurama HTML code (version 4.2.1 or higher);
  • Configure in the web.config the element . See the chapter 'Configuration Mapping' where you can find information about how to configure some default locations of the HTML application. Make sure the attribute 'document' has the value website.xml. Optionally you can choose to give the attribute 'folder' the value SavingsAccount (see next bullet); 
  • Your website should now be displayed by opening the URL "http://servername/[name of folder with Futurama HTML code]/?folder=SavingsAccount" in your internet-browser (or "http://servername/[name of folder with Futurama HTML code]" when the folder attribute has te value 'SavingsAccount').

You can visit a demo-version of the sample application to see if the installation was succesful: Demo-version Savings Account Website

Configuration

Description

After installing the Futurama HTML code the configuration can be done. See below for this configuration.

Configuration File

In the release folder we provided a default.config. In the Installation steps mentioned above this default.config is renamed to web.config. In this configuration section the sections within this configuration file are explained.

configSections and futuramaSettings

Within the section 'configSections' you find a sectionGroup named futuramaSettings. This sectionGroup futuramaSettings is also a separate section in the config under the configSections section. Each section name within the sectionGroup futuramaSettings is also contained within the futuramaSettings section. Below a brief explanation of these futuramaSettings sections.

Configuration Log

It is possible to log errors, warnings, information messages and developers messages with Futurama. In the chapter 'Configuration Log' you can find information how to configure the configuration file to log this information.

Configuration Cache

In the chapter 'Configuration Cache' you can find information about configuring the settings of caching information. More information about website caching can be found at this page.

Configuration Debug

Settings for debugging while developing with Futurama are described in the chapter 'Configuration Debug'.

Configuration Format

The format settings of for example dates and numbers are described in the chapter 'Configuration Format'.

Configuration Identity Provider

The identity provider settings are described in the chapter 'Configuration Identity Provider'. With an identity provider you can control the way Futurama allows users to log in to the website. Be carefull, if you use an Identity Provider with a load balancer, you also need the 'SAML LoadBalancer' component.

Configuration Mapping

In the chapter 'Configuration Mapping' you can find information about configuring default locations of your Futurama applications.

Configuration Monitor

It is possible to store session information of a Futurama application. The configuration of this can be found in the chapter 'Configuration Monitor'.

Configuration Vision

The configuration of the connection between Futurama HTML and Futurama Vision is described in the chapter 'Configuration Vision'.

Configuration Render

It is possible with FICO to change the render output of Futurama. On default Futurama renders the webpage with xHTML1.0. It is possbile with FICO to render a page with, for example HTML5. The configuration, to change how Futurama renders, can be found in the chapter: 'Configuration Render'

appSettings

The appSettings section of the configuration file is a place to store connection strings, server names, file paths and other miscellaneous settings that can be used by a Futurama application. The items inside the appSettings are items that need to be configurable depending upon environment. For instance, any database connection strings will change as you move your application from a testing server into production. With the Futurama formula 'ReadConfigKey' the value of any of these keys can be read and used within the modelling of your application. When using Futurama to run a website application the value of these environment dependable can be set in the web.config.

sessionState

The sessionState element is a .NET setting. Below the attributes that can be used:

  • the attribute 'mode' default is InProc. Futurama only supports this mode;
  • from Futurama 5.2.1.1 the attribute 'cookieless' default is 'false' (until 5.2.1.1 the default value was 'true'). It is recommended to use cookies as this is more secure then having the session ID in the URL. See the ‘Use cookies’ paragraph at this page for more information. More information about website caching can be found at this page.
  • the timeout attribute indicates the session timeout in minutes. After expiration of this timeout the user will be redirected to the TimeOut page of Futurama. The session timeout is a sliding expiration
  • the cookiename is the name the session cookie gets  

customErrors

The customErrors element is a .NET setting that specifies whether custom erroros are enabled. Below the attributes that can be used:

  • the attribute ‘mode’ can have the values ‘On’, ‘Off’ and ‘RemoteOnly’. ‘On’ specifies that custom errors are enabled, ‘Off’ specifies that custom errors are disabled, ‘RemoteOnly’ specifies that custom errors are shown only to remote clients and ASP.NET errors are shown to the local host.
  • the attribute ‘defaultRedirect’ is used only in combination with mode=On and mode=RemoteOnly. It specifies the default URL to direct a browser to if an error occurs. When defaultRedirect is not specified, a generic error is displayed instead.

The customErrors element can contain subelements . The error subelement can appear multiple times. Each appearance defines one custom error condition. Below the attributes that can be used:

  • the attribute ‘statusCode’ specifies the HTTP status code that will result in redirection to the error page.
  • the attribute ‘redirect’ specifies the error page that will present information to the client about the error.

If you use customErrors, make sure to redirect to a page appended with a question mark. So for example 'error.htm?'. This forces .Net to remove ant request parameters that indicate the type of error. 

Securing access to website

Futurama supports the standard .Net authentication ways to secure the access to a website. See for more information the Installation Futurama Website page.

Testing

The installation and configuration can be tested. See below how to test. If you encounter problems, check the chapter 'Troubleshooting'.

Browse website in IIS

In the web.config you have configured in the mapping section what the default Futurama folder is. In IIS you have made an application for the Futurama installation. Check whether you can browse from IIS to the sample Futurama folder (see download example at paragraph 'Installation Futurama application').

Open website in browser

Open a browser and browse to the url you have chosen for your Futurama application. If you want to browse to another Futurama application then the application you selected in the mapping section of the web.config, you have to add the parameter 'folder' with value the name of your Futurama application in the url: http://url_to_application/?folder=name_application

Troubleshooting

If you encounter problems with the installation of Futurama HTML check the sections below.

Logging information

In the web.config the log section is configured. First step in troubleshooting is checking the information in the different log files. Make sure that the log information is actually created. If you don't see any log information consult the chapter 'Configuration Log' for the settings to get this information.

IIS does not recognise ASP.Net

This problem can be identified because the tab ASP.Net is not shown in IIS or because default.aspx is not present in the list of default documents. The problem is often caused by the fact that ASP.Net has been installed before IIS itself. The solution is therefore to re-register asp.net in IIS. This can be done through the following command:

%WINDIR%\Microsoft.NET\Framework\v4.0.30319\aspnet_regiis -ir -enable

If you do have a 64-bit version use the following command:

%WINDIR%\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis -ir -enable

If this doesn't solve the problem, it is recommended to reinstall IIS and ASP.Net altogether. The correct sequence is then first IIS followed by ASP.Net.

Multiple Futurama installations on a single server with Forms Authentication

If you have mulitiple Futurama installations on a server host and for the websites you make use of Forms Authentication it is relevant to use a different Forms Authentication name for every Futurama installation. You can set these names in the web.config using the property name inside the Forms Authentication section.

Application doesn't open on login.aspx

When you make use of Forms Authentication this has to be set in the web.config. When using Forms Authentication it is important that in IIS both Forms Authentication and Anonymous Authentication is turned on. Furthermore the following code has to be added to the web.config:

<location path="default.aspx">
	<system.web>
		<authorization>
			<deny users="?"> </deny>
		</authorization>
	</system.web>
</location>
<location path="partial.aspx">
	<system.web>
		<authorization>
			<deny users="?"> </deny>
		</authorization>
	</system.web>
</location>
<location path="logoff.aspx">
	<system.web>
		<authorization>
			<allow users="*"> </allow>
		</authorization>
	</system.web>
</location>

This code has to be placed directly in the configuration tag. It will ensure that users are directed to the Login.aspx. When DigiD is used for the authentication proces, also the following code has to be added to the web.config to ensure that SAML messages are accepted.

<location path="SAML">
	<system.web>
		<authorization>
			<allow users="*"> </allow>
		</authorization>
	</system.web>
</location>

...\default\calc.xml does not exist or is not accessible

In the web.config you have to configure in the mapping section the default Futurama application folder and the default Futurama file. If you don't fill in these values the default Futurama application is 'default' and the default Futurama file is 'calc.xml'. Check the name of your Futurama application and the name of your Futurama file and fill in these names in de mapping section.

Windows Platform FIPS error message

Browsing to the application gives the next error message: 'This implementation is not part of the Windows Platform FIPS validated cryptographic algorithms'. This error can be disabled to change the Local Security Policy of the server. Below the steps to change the policy:

  1. go to Control Panel - Administrative tools
  2. Local Security Policy
  3. Local Policies
  4. Security options
  5. Policy: System cryptography: Use FIPS compliant algorthms for encryption, hashing, and signing
  6. Disable this policy

The file '/default.aspx' has not been pre-compiled, and cannot be requested

In the Internet Information Services (IIS) Manager you have to check the Basic Settings of the Application Pool attached to the Futurama. It has to be set to .Net version 4 (instead of version 2).

This error can also occur when a new Futurama is copied over the old Futurama without deleting the old files first. Interaction between old and new files can cause problems. Therefore always delete the old Futurama files before copying the new Futurama files.

OverflowException: Arithmetic operation resulted in an overflow.

This can occur when using version 4.x of Futurama. In the Internet Information Services (IIS) Manager you have to check the Advanced Settings of the Application Pool attached to the Futurama. Set the setting 'Enable 32-Bit Applications' to True (instead of False).

Key not valid for use in specified state.

In the situation an external identity provider is used for the authorization of the users of your application the error message ‘key not valid for use in specified state’ can be logged. This message implies that the external identity provider wants to sign messages with the certificate imported. In order to sign certificates it is necessary to use the ‘mark this certificate as exportable’ option while importing the certificate. So check whether your certificate is exportable or not when the error message appears.   

Unable to read private key for certificate.

In the situation an external identity provider is used for the authorization of the users of your application the error message ‘Unable to read private key for certificate’ can be logged. The external identity provider is trying to read the private key, but is not able to. To make sure an application can read the private key, the property 'LoadUserProfile' needs to be set to true. This property has to be set to true for all applications that uses an external identity provider. This property can be set in the advanced settings of the applicationpool in IIS.   

Feedback

If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.

Updated: 2015-04-03