Search

 

Edition:Futurama Webservice

Module:Futurama Webservice

User:System administrator

Prerequisites

- License file

- User name and password for Futurama downloads

- Windows 2008 R2 server or higher

- .NET Framework 4.6.2 with ASP.Net and WCF-Services to be installed

- Internet Information Server 7.5 or higher

 

Description

In order to use the Futurama Webservice edition, the Futurama Webservice module 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 Webservice 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 webservice.

Installation initial version

If this is the first installation of the Futurama Webservice 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 Webservice 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 ASP .Net 4.0
  • Choose from your application this application pool

Upgrading existing version

If you already have installed the Futurama Webservice 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 Webservice:

  • Open the folder at the Windows webserver where you have installed the Futurama Webservice code
  • Copy the code from the release folder to this new folder
  • 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 webservice. Install this folder in the same folder as the installation of the Futurama webservice code. 

Download files

You can use a sample application to test the Futurama Webservice installation. 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 Webservice code (version 4.2.1 or higher)
  • To test the Futurama Webservice application use a testtool for webservices (for example SoapUI).
  • Fill in the WSDL of your service. (typically of the form 'http://servername/applicationname/service.svc?wsdl')
  • Choose the method 'GetWebserviceResult'
  • In the request the next parameters are relevant:
    - : the name of the Futurama Document with the definition of the calculation to be made. In this sample the name of the document is savingsaccountwebservice.xml;
    : the path to the Futurama file 'savingsaccountwebservice.xml' that is located within the folder 'SavingsAccount'. This path is [path to folder with Futurama Webservice code]\SavingsAccount (for example C:\inetpub\wwwroot\Testwebservice\SavingsAccount);
    : the name of the InterfacesNode that is defined in the Futurama document. In this sample the value of the parameter is 'GetSavings';
    : the input request. Copy and paste the data from the file 'TestInput.xml' that is located in the 'SavingsAccount' folder
  • Example of request:
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.ActuIT.nl/Futurama/WebService">
    	<soapenv:Header/>
    	<soapenv:Body>
    		<web:GetWebServiceResult>
    			<!--Optional:-->
    			<web:location>
    				<!--Optional:-->
    				<web:Document>savingsaccountwebservice.xml</web:Document>
    				<!--Optional:-->
    				<web:Folder>C:\inetpub\wwwroot\Testwebservice\SavingsAccount</web:Folder>
    				<!--Optional:-->
    				<web:WebServiceName>GetSavings</web:WebServiceName>
    			</web:location>
    			<!--Optional:-->
    			<web:inputxml>
    				<!--You may enter ANY elements at this point-->
    				<data xmlns="http://www.futurama.eu/Safe2SaveWebservice">
    					<CashBalance>10000</CashBalance>
    					<Interest>3</Interest>
    					<Years>25</Years>
    				</data>
    			</web:inputxml>
    		</web:GetWebServiceResult>
    	</soapenv:Body>
    </soapenv:Envelope>
  • Use this request to test the Futurama Webservice installation. You can change the values in the inputxml to test other calculations.
  • The installation above uses the pre-defined WSDL provided by Futurama which is typically of the form 'http://servername/applicationname/service.svc?wsdl'. When using a custom WSDL, available from version 17.11, this is typically of the form 'http://servername/applicationname/service.svc?wsdl&folder=foldername&document=documentname.xml'.
  • When using a custom WSDL the available methods are the ones described in this WSDL. In SOAPUI for example, instead of the generic methods only the methods described in the custom WSDL will be generated automatically.
  • The requests will typically be a lot smaller when using a custom WSDL. The web:location element, for example, will not be shown any more. An example is given below: 
    <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ops="http://www.ActuIT.nl/Futurama/WebService/Operation">
    	<soapenv:header>
    		<soapenv:body>
    			<ops:request>
    				<ops:n>8</ops:n>
    			</ops:request>
    		</soapenv:body>
    	</soapenv:header>
    </soapenv:envelope>
  • Similar to the WSDL, a pre-defined WADL is provided by Futurama (from version 18.02) which is typically of the form 'http://servername/applicationname/rest?wadl'.

Endpoints

Futurama Webservice can be exposed as a SOAP service and as a REST service. Fot both types you can use the predefined WSDL (for SOAP) or WADL (for REST) or a custom WSDL/WADL.  Dependable on the type of service and depending on whether a custom WSDL/WADL is used the endpoint differ.

SOAP in combination with predefined WSDL

  • The default endpoint:  http://servername/applicationname/service.svc
  • Folder, Document and Webservice defined in the request (see example request mentioned in the 'Installation Futurama application' paragraph above
  • Folder and/or Document can also be omitted in the request and be defined in the mapping section of the configuration file of your Futurama Webservice

SOAP in combination with custom WSDL

REST in combination with predefined WADL

  • The default endpoint:  http://servername/applicationname/rest/webserviceresult
  • Folder, Document and Webservice defined in the request (see example request mentioned in the 'GetWebServiceResult' paragraph, in the REST sectiona th this page)
  • Folder and/or Document can also be omitted in the request and be defined in the mapping section of the configuration file of your Futurama Webservice

REST in combination with custom WADL

Configuration

Description

After installing the Futurama Webservice 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. caching for webservices should only be used in environments where there is total control of the calls to the webservice. Only sequential calls should be used. More information about the caching for webservices can be found at this page.

Configuration Format

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

Configuration Mapping

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

Configuration Vision

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

Configuration Web API

The configuration how to enable Futurama Web API is described in the chapter 'Configuration Web API'.

Configuration Custom WSDL (Futurama 17.11+)

The configuration how to enable Futurama Custom WSDL is described in paragraph 'Custom WSDL (Futurama 17.11+)' of this page.

The configuration how to enable WADL is described in paragraph 'WADL (Futurama 18.02+)' of this page.

Testing

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

Test the webservice

To test whether the webservice is correct working type the following URL: http://servername/applicationname/service.svc (for example http://localhost/FuturamaWebservice/service.svc in the situation you installed the Futurama Webservice code in the folder FuturamaWebservice within localhost). You should now see a screen stating that you have succesfully created a webservice.

Test webservice request and response

In the screen mentioned at the 'Test the webservice' paragraph, the URL of the webservice is stated. This will typically be of the form http://servername/applicationname/service.svc?wsdl. Using this URL further tests can now be carried out. In order to do these tests a package dedicated to sending requests to the webservice is needed. An example of such a package is SOAPUI.

A straightforward test is to check whether Futurama Webservice returns the proper version number. The following request can be send in order to retrieve the version:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.ActuIT.nl/Futurama/WebService">
   <soapenv:Header/>
   <soapenv:Body>
      <web:GetFuturamaVersion/>
   </soapenv:Body>
</soapenv:Envelope>

Another good test is to download the sample as described in the paragraph 'Installation Futurama application' and check whether you get a response. For more information about the webservice methods that can be used with Futurama Webservice consult the description of the Futurama Object WebService.  

Performance measurement

To measure the performance of a webservice calculation you can, starting from Futurama 20.11, add a HTTP-header ('FUT_AddCalculationTimeToOutput' with value 'TRUE') to a call to Futurama Webservice to include the calculation time in the output. This will return a HTTP response header Fut_CalculationTime with the calculation time in milliseconds. Because this is only the calculation time, without the overhead for the webservice call, if is a better performance measurement. 

Security

When you use WCF, you can use the message security options that WCF provides.

You can use message security, for example with a certificate, or with a username and password.

To use a username and password, you need to specify a few things in the web.config

First you define the 'ServiceCredentialsInHeaderAdapter' extension by adding it to system.serviceModel

<extensions>
	<behaviorExtensions>
		<add name="ServiceCredentialsInHeaderAdapter" type="ActuIT.Futurama.Engine.ServiceCredentialsInHeaderAdapterBehaviorElement, 
      ActuIT.Futurama.Engine, Version=*, Culture=neutral, PublicKeyToken=null">
		</add>
	</behaviorExtensions>
</extensions>

Then you add the name of a behavior to the binding of the service

<service behaviorConfiguration="ActuIT.Futurama.WcfService.Service" name="ActuIT.Futurama.WcfService.Service">
	<!-- Service Endpoints -->
	<endpoint address="" binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_Service" contract="ActuIT.Futurama.WcfService.IService">
	</endpoint>
</service>

Then you add the usernames to the behavior

<behavior name="ActuIT.Futurama.WcfService.Service">
	<!-- To avoid disclosing metadata information, set the value below to false 
        and remove the metadata endpoint above before deployment -->
	<serviceMetadata httpGetEnabled="true"/>
	<!-- To receive exception details in faults for debugging purposes, set the value below to true.  
    Set to false before deployment to avoid disclosing exception information -->
	<serviceDebug includeExceptionDetailInFaults="true"/>
	<serviceCredentials>
		<userNameAuthentication customUserNamePasswordValidatorType="ActuIT.Futurama.WcfService.FuturamaUserNameValidator, ActuIT.Futurama.WcfService" userNamePasswordValidationMode="Custom">
		</userNameAuthentication>
	</serviceCredentials>
	<serviceCredentialsInHeaderAdapter>
		<users>
			<user password="testpassword" username="testuser"/>
			<user password="testpassword2" username="testuser2"/>
		</users>
	</serviceCredentialsInHeaderAdapter>
</behavior>

Make sure the binding configuration BasicHttpBinding_Service is defined within basicHttpBinding.

To apply ServiceCredentials to a Rest call you can define the same behavior. Make sure to name the behavior ActuIT.Futurama.WcfService.RestService.

Explicit operation exposure (Futurama 17.11+)

From Futurama version 17.11 it is possible to expose explicit operations and thus generate a specific WSDL. To enable this functionality the following has to be added to the configuration:

<system.webServer>
	<defaultDocument>
		<files>
			<add value="service.svc"></add>
		</files>
	</defaultDocument>
	<modules>
		<add name="SpecificWsdlHttpModule" type="ActuIT.Futurama.WcfService.SpecificWsdlHttpModule"></add>
	</modules>
</system.webServer>

Specific WSDL is only available if traditional wsdl exposure (service metadata) is enabled in the config file. (N.B. for versions 17.11-18.02 ‘SpecificWsdlHttpModule’ was called ‘CustomWsdlHttpModule’)

WADL (Futurama 18.02+)

From Futurama version 18.02 it is possible to generate a WADL. To enable this functionality the following has to be added to the configuration:

<system.webServer>
	<defaultDocument>
		<files>
			<add value="service.svc"></add>
		</files>
	</defaultDocument>
	<modules>
		<add name="WadlHttpModule" type="ActuIT.Futurama.WcfService.WadlHttpModule"></add>
	</modules>
</system.webServer>

WADL is only available if traditional wsdl exposure (service metadata) is enabled in the config file.

Troubleshooting

If you encounter problems with the installation check the sections below. See also the page Troubleshooting for more information regarding the testing of webservice reuqests and calls.

Enable webservice logging

Webservice requests and responses can be tested by enabling the webservice logging. See paragraph 'Logging webservices messages' how to enable webservice logging. More information how to interpret the webservice logging files can be found at the Troubleshooting page.

Error while browsing to webservice url

If you retrieve an error while browsing to your webservice address, check whether you installed ASP.NET and WCF-services within .NET Framework 4.6.2.

License error after windows upgrade

Up to Futurama version 5.3 a license error occurs after an upgrade to Windows 10 or Windows Server 2012. This issue is solved in Futurama version 5.3. When encountering this problem update to the most recent Futurama version.

HTTP Error 404.3-Not found

The errormessage shows 'HTTP Error 404.3 - Not Found'. The page you are requesting cannot be served because of the extension configuration. If the page is a script, add a handler. If the file should be downloaded, add a MIME map.

The solution depends on the version of IIS that is running on your system. Check the version before continuing.

IIS 7.5

It is possible to install all missing MIME-types with a single command. To do this take the following steps:

  1. Open a Command Prompt
  2. Go to the directory C:\Windows\Microsoft.NET\Framework\v3.0\Windows Communication Foundation
  3. Execute the following command: ServiceModelReg.exe -i

After execution the missing MIME-type has been added and the webservice will work once more. If a Handler is missing see the next troubleshoot.

IIS 8.0

The problem can be resolved by adjusting the installation of certain Windows-parts. When doing a clean install these will not be set properly automatically.

  1. Go to Control Panel/Programs and Features/Turn Windows features on or off
  2. Select all the checkboxes at WCF Services

If you applied the solution for IIS 7.5 while your system has IIS 8.0 instead, the solution for IIS 8.0 will not work any more. First you have to undo the command belonging to IIS 7.5. This can be done with the uninstall-command: ServiceModelReg.exe -u.

Missing HandlerMappings

When requesting a webservice the error appears that type System.ServiceModel.Activation.HttpModule could not be loaded from assembly System.ServiceModel, Version=3.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089. This is because in IIS at the HandlerMappings not all .svc HandlerMappings exist. The ASP.NET 4.0 HandlerMappings have to be added.

The solution depends on the version of IIS that is running on your system. Check the version before continuing.

IIS 7.5

It is possible to install the missing HandlerMappings with a single command. To do this take the following steps:

  1. Open a Command Prompt
  2. 2.Go to the directory C:\Windows\Microsoft.NET\Framework\v4.0.30319
  3. 3.Execute the following command: aspnet_regiis -ir

By doing this IIS is again registered without altering the existing webapplications. In IIS at HandlerMappings a number of .svc HandlerMappings have been added.

Related Topics

- WebService: To build your own custom made webservice, you have to use the WebService object in the Futurama Editor

Relevant Tutorials

- Webservices in Futurama: This tutorial shows how you can work with webservices in Futurama.

- Creating a Webservice Application: This tutorial shows you how you to create a webservice application in Futurama.

External Links

- SOAPUI: Package that can be used to test webservice requests responses

Feedback

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

Updated: 2017-12-27