Installation: Futurama Vision
Component: Futurama Vision Management Site
User: System administrator
- License file
- User name and password for Futurama downloads
- Windows 2008 R2 server or higher
- .NET Framework 4.6.2
- Internet Information Server 7.5 or higher with ASP.Net to be installed
When using Futurama Vision both the Futurama Vision Management Site and the Futurama Vision Database have to be installed. At this page the installation of the Futurama Vision Management Site is described. For the installation of the Futurama Vision Database consult this page.
Visit the Futurama website www.futurama.eu to download the Futurama Vision Management Site 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
Use the release code from the folder 'Vision_ManagementSite'.
Installation initial version
To install the Futurama Vision Management Site 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. Use the next settings for this application pool:
- select .Net Framework 4
- Managed pipeline modus: Integrated
- Identity: if you use the module Futurama Register choose localsystem. With this identity the module Futurama Register does have the permission to read the certificates necessary for the communication with the Dutch 'Nationaal Pensioenregister'. If you don't use the module Futurama Register the identity AppPoolIdentity can be used
- 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 Vision Management Site
- Depending on your situation select either the Forms Authentication or the Windows Authentication
- Select also the Anonymous Authentication verification. With this setting the VisionService.svc can be invoked
Upgrading existing version
If you already have an install of the Futurama Vision Management Site, and want to upgrade this to a new version, follow the steps in this paragraph. If this is the first installation of the Futurama Vision Management Site consult the preceding paragraph 'Installation initial version'.
Follow the next steps to upgrade an existing version of the Futurama Vision Management Site:
- Open the folder at the Windows webserver where you have installed the Futurama Vision Management Site
- Copy the code from the release folder to this new folder
- When there are database changes, the site will automatically lead you to the upgrade page from version 18.04. After pressing ‘start upgrade’ on that page, the database upgrade will happen automatically.
Note that the Vision Management Site is not available until this upgrade is completed.
Most of the configuration settings for Vision can be done within the Management Site itself. The configuration of your applications can be done at the admin pages. Furthermore you can use the security configuration pages to define which Management pages can be viewed by which users. Some of the configuration settings has to be done in the web.config. These are settings regarding:
- configuration regarding the logging of errors and warnings
- configuration of the mailserver to be invoked by Vision
- configuration of external webservices to be invoked by Vision for the module Futurama Register
- configuration of encryption and decryption keys to be used for the encryption of xml-data within Vision
- configuration of the connection between the Management Site and the database
See below for this configuration.
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 visionSettings
Within the section 'configSections' you find a sectionGroup named visionSettings. This sectionGroup visionSettings is also a separate section in the config under the configSections section. Each section name within the sectionGroup visionSettings is also contained within the visionSettings section. Below a brief explanation of these visionSettings sections.
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.
In order to send e-mails a mailserver (SMTP) has to be used. Within the section visionSettings the name of this SMTP-server has to be set.
It is possible to change the lay-out of the Vision Management Site by using a different CSS styling. For more information see the following page: Skinning
In order to configure the securitymode or administrative access for Vision, a new security section has been created from Futurama 18.07 onwards. For more information, please visit Security
Authentication and Authorization
Authentication is about how a user identifies itself, authorization means defining what users are allowed to do.
Note that what is discussed here is not about credentials for the communication between vision and the database. For that see connection with vision database below.
Like all .NET applications, the Vision Management Site can be secured by using:
- Anonymous authentication
- Windows authentication
- Forms authentication
The authentication methods you plan to use in Vision should be enabled in your IIS config.
In an advanced scenario it is possible to choose which pages of the Vision Management Site can be accessed by which users. See the security section of the Futurama Vision Management Site how to configure this.
For a basic setup you need two settings in web.config, within the element:
In the first step first all users are authorized to view all pages of the Management Site. In IIS besides the choses .NET authentication (anonymous, windows or forms) also anonymous authentication has to be chosen. The second steps denies access to the secure pages of the Vision Management Site to the unauthenticated users of the Management Site. The Secure pages of the Management Site are all the pages except to the Start and the About page. The format of the URL of all of these secure pages is http://servername/visioninstallation/Secure/CategoryName/PageName.aspx.
Connection with the Vision Database
Within the section 'connectionStrings', the connection with the Futurama Vision Database is defined. See Installation Futurama Vision Database, paragraph ‘Installation’. In the section ‘Installation initial version’ either a SQL login or a Windows login is defined.
If a SQL login is defined, define in the section 'connectionStrings' a SQL connection between the Vision Management Site and the Vision Database with a SQL account. In this situation the connection string is of the format:
Data Source=server;Initial Catalog=dbname;User ID=user;Password=pw;MultipleActiveResultSets=True;
- server: the name of the database server (including the instance name) where the Futurama Vision Database runs
- dbname: the name of the Futurama Vision Database
- user: the user of the Futurama Vision Database
- pw: the password of the SQL Server logins that is mapped to the user in the Futurama Vision Database
If a Windows login is defined, define in the section 'connectionStrings' a SQL connection between the Vision Management Site and the Vision Database with a domain account. In this situation the connection string is of the format:
Data Source=server;Initial Catalog=dbname;Integrated Security=True;MultipleActiveResultSets=True;
- server: the name of the database server (including the instance name) where the Futurama Vision Database runs
- dbname: the name of the Futurama Vision Database
Important in this situation is that the Windows login (defined in the SQL Server) is the identity of the application pool of the Futurama Vision Management Site.
Setting the language
The Futurama Vision Management Site is multilanguage (either English or Dutch) and can be displayed in a language depending on the client browser setting. Default settings are English and independant of the browser settings. These default settings can be overrided by setttings of the globalization element in the web.config:
<globalization culture="auto" uiCulture="auto" enableClientBasedCulture="true"></globalization>
- set the enableClientBasedCulture attribute to 'true'
- include the uiCulture attribute. If the value is 'auto', the language of the Management Site will be determined by the browser language (in Internet Explorer for example the browser language can be set via the Tools menu, Internet Options, General tab, language). If the value is 'nl-NL' the language of the Management Site will be Dutch independant of the individual browser settings. For all the other (valid) language settings of uiCulture the language will be English.
Part of the Futurama Vision Management Site is the 'Server' menu. This menu is relevant if you use the Futurama Server module within the Futurama Export edition. Next to the individual installation of Futurama Server some specific settings has to be done in the configuration file of the Management Site.
First you must define the connection between the Futurama Vision Management Site and Futurama Service in order to start Futurama Server jobs. For this configuration include the next code within the system.servicemodel element of the config:
<binding maxReceivedMessageSize="1048756" name="BasicHttpBinding_FuturamaService">
<endpoint name="BasicHttpBinding_FuturamaService" contract="FuturamaServerReference.Service" bindingConfiguration="BasicHttpBinding_FuturamaService" binding="basicHttpBinding" address="http://localhost:8080/FuturamaService"/>
Furthermore within the appsettings the value of two parameters has to be set:
<add value="Path" key="ActuIT_FuturamaServer_JobsDirectory"/>
<add value="Value" key="ActuIT_FuturamaServer_AutoUpdate"/>
Here is 'Path' the path to the file folder where the Futurama Server jobs are stored. In the 'Server' section of the Futurama Vision Management Site this path will be automatically filled in and the jobs that are stored within this file folder are displayed. The 'Value' for the key 'ActuIT_FuturamaServer_AutoUpdate' can have either the value 'True' or the value 'False'. This indicates whether Futurama Server has to refresh the list with the tasks to be executed (value is True) or not (value is False).
At last the server section of the configuration element has to be included. See the configSections mentioned above.
Settings for encryption/decryption
If your application uses encryption for the storing of xml-data (see this page) then you have to define within the appSettings the generic password that has to be used for the decryption of the data (besides the generic password, a user specific salt-value is used). See below an example of this configuration:
<add value="pw1" key="Key1"/>
The name of the key 'Key1' is defined in the Futurama Vision Management Site. The value 'pw1' of this key is the generic password that is used to encrypt the data.
It is possible to store data from your website application in Vision. The format of this data to be stored can be defined in the Management Site. In this Management Site you have to provide an XSD defining the format of the data you want to store, XML for giving a sample XML based on this XSD, and an XSLT for transferring to one version of a format to another one. The input of XSD, XML and XSLT on a website will default give an error. This is a security check that no dangerous script is used in an input field at the website. For the defining of the format this input is allowed. In the configuration file code is included to allow users to input this script at the relevant Management Site page. This script has to be included within the element. Mentioned below this script:
Storing large XML-messages
If you want to store XML-messages larger then 64kb, then the configuration file has to be extended with an extra section to allow the storage of these messages. In this section you can define the maximum size of these messages. Within the configuration element the code mentioned below has to be included:
<endpoint contract="ActuIT.Futurama.Vision.WCF.IVisionService" bindingConfiguration="BasicHttpBinding_IVisionService" binding="basicHttpBinding" address="">
<binding maxReceivedMessageSize="1048576" name="BasicHttpBinding_IVisionService">
In this example the maximum message size is increased to 1048576 bytes (equals 1MB).
In order to import large zip-files in Futurama Vision the maximum allowed file format has to be increased. Default in Microsoft ASP.NET the size of data that can be send to a website is limited. With this setting usually it is prevented that overloading data attacks are send to a webserver. In order to upload large zip-files in the configuration file the import of these large data must be granted. Within the configuration element the next code has to be included:
<httpruntime executionTimeout="3600" maxRequestLength="102400"/>
<!--For IIS 7-->
In this example the maximum file format that can be imported is 102400 KB (equals 100 MB). Also the timeout period for the importing is extended to 3600 seconds (one hour). With these settings it is possible to import zip-files sized with a maximum of 100 MB.
Automatically upgrading the database for new versions (Futurama 18.06+)
When a new version of the Vision managementsite is installed, the database can be automatically upgraded. This requires some configuration changes for security-purposes, please read the information at Installation or Upgrade of the Futurama Vision Database.
Importing large XML-files
If you want to import XML-files larger then 64kb, using the ImportUsers webservice, then the configuration file has to be extended with an extra section to allow the storage of these files. In this section you can define the maximum size of these messages. Within the configuration element the code mentioned below has to be included:
<endpoint contract="ActuIT.Futurama.Vision.Web.Site.Services.IImportUsers" bindingConfiguration="BasicHttpBinding_ImportUsers" binding="basicHttpBinding" address=""/>
<binding maxReceivedMessageSize="1048576" name="BasicHttpBinding_ImportUsers">
In this example the maximum file size is increased to 1048576 bytes (equals 1MB).
Viewing large error messages of XML log files in LogFileViewer
When error messages of XML log files are too large, viewing them in the LogFileViewer will fail. The configuration file has to be extended with an extra section to change the maximum allowed length of error messages. Within the configuration element the code mentioned below has to be included:
The installation and configuration can be tested. See below how to test. If you encounter problems, check the chapter 'Troubleshooting'.
Open website in browser
Open a browser and browse to the url you have chose for the Futurama Vision Management Site.
Check connection with Vision Database
Open the Futurama Vision Management Site and check the 'About' section. In this section the version of the installation is displayed and the name of the server and the database you have set. Check whether this information is correct.
If you encounter problems with the installation of the Futurama Vision Management Site check the sections below.
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.
In the Management Site there are several menus (for example the menu 'Start' and the menu 'About'). If a menu is italic (you cannot see the content of the menu), then first check the correct installation of the licence file (see above at the installation description). If this file is installed correctly contact your contactperson that provided the license file.
Potentially dangerous Request.Form
At the DataStore Management pages in the Futurama Vision Management Site the next error can occur: 'A potentially dangerous Request.Form value was detected from the client'. See the 'Datastore' section within the chapter 'Configuration' for the code that has to be included in the configuration file to solve this error.
Maximum request length exceeded when importing zip-files
If you get this message while importing zip-files in the Management Site check the settings in the configuration file. See the section 'Uploading zip-files' in the section 'Configuration'.
Windows Authentication popup appears
The method of authentication for the Management Site can be set within the configuration file, which includes Windows authentication (also called NTLM). This is configured within Internet Explorer by default, but using Mozilla Firefox as browser can cause some complications. This is because Firefox needs some additional configuration in order to support NTLM authentication. Check the Firefox documentation how to enable the NTLM authentication.
Dropdown list doesn't work
If you are using an old version of Futurama (before version 4.4) and if you use Internet Explorer 10 possibly you can't select another option in the dropdown lists. Internet Explorer doesn't interpret these lists correct. There are two ways to solve this issue.
Use the compatibility view
You can activate compatibility view by clicking the 'broken page' icon in the right side of the address bar. This activates the compatibility view for the entire domain of the current page. Whenever another site within this domain is viewed, compatibility view will be activated again, untill you deactivate it manually by clicking the icon again.
Add a custom header to the site within IIS
You can configure a certain website to be rendered in a different Internet Explorer mode by setting a custom header from within IIS. This can be done by adding a certain section in the web.config, as shown below:
<add name="X-UA-Compatible" value="IE=EmulateIE8"/>
This makes sure that whenever Internet Explorer 9 or higher displays the website, it will use the IE8 rendering engine. This same action can be done from within the IIS manager, by following the steps documented here.
The remote server returned an error: (413) Request Entity Too Large.
If you get this message while executing the ImportUsers service, check the settings in the configuration file. See the section ‘Importing large XML-files’ in the section 'Configuration'.
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.
If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.