Search

Module: Editor

Version: 5.2.0 +

User: Developer

Object Type: Data Object

Subpage of:

- Webreference
 

Description

Contains extra information about the Webreference.

Configuration with WCF

WCF stands for Windows Communication Foundation. It provides a (.Net) Framework to build connected service-oriented applications on Windows.

When the method is 'WCF' Futurama uses the properties that are defined in the config file for various configuration choices. This allows much more control over the properties that are used for the communication.

EndPoint

The endpoint provides information about the configuration of the application being called, for example the location of the application and security properties. The endpoint is defined in the Config file of the Client. For more information about this look at section "Config file" below. The advantage of using an endpoint is that it separates the configuration from the functionality. The functionality stays the same whereas the adjustments can be done inside the configuration file.

Config file

The Server Config file is the Config file of the application being called. The Client config file is the Config file of the application which the call is made from. Making a webreference from an existing webservice installation towards another webservice, both configurations, of the Server and the Client, need to be added to the Config file of the existing webservice installation.

Notes about the samples

  • In the sections below, samples are given for the configuration of different WCF services. Each time the server configuration is given, as well as the client configuration. Most of the times you will be in a situation where you want a webreference to an existing webservice. This means you are only able to alter the client configuration. The server configuration therefore is only given as an example. 
  • The samples hold pieces of code which should be included in your existing configuration file. For each section, the part of the configuration in which this code should be included, is mentioned.
  • Below the code part, some elements of it are further explained.
  • Whenever an extra endpoint is needed then you can add the code of the second endpoint below the first endpoint in the Client configuration, with a different endpoint name.

Bindings

Futurama supports the following bindings:

  • basicHttpinding
  • wsHttpBinding
  • webHttpBinding (Rest)

Basic webservice without authentication

To use the most basic WCF webservice you need the following config:

Server configuration:

<system.serviceModel>
	<serviceHostingEnvironment multipleSiteBindingsEnabled="True">
	</serviceHostingEnvironment>
	<services>
		<service behaviorConfiguration="ActuIT.Futurama.WcfService.Service" name="ActuIT.Futurama.WcfService.Service">
			<endpoint address="" binding="basicHttpBinding" contract="ActuIT.Futurama.WcfService.IService">
			</endpoint>
			<endpoint address="mex" binding="mexHttpBinding" contract="IMetadataExchange">
			</endpoint>
		</service>
	</services>
	<behaviors>
		<serviceBehaviors>
			<behavior name="ActuIT.Futurama.WcfService.Service">
				<serviceMetadata httpGetEnabled="true">
					<serviceDebug includeExceptionDetailInFaults="false">
					</serviceDebug>
				</serviceMetadata>
			</behavior>
		</serviceBehaviors>
	</behaviors>
</system.serviceModel>

Client configuration:

<!-- Section within: <system.serviceModel><client> -->  
<endpoint address="http://localhost/TestWebService/service.svc" binding="basicHttpBinding" contract="*" name="Test"></endpoint>

Note: in the situation of:

  • the connection with Futurama Vision,
  • with a VisionReference,
  • where WCF configuration has to be set,

see this page for the client configuration for either Futurama HTML or Futurama Editor. See the sample config for Futurama HTML and Futurama Editor at this page for more information. The configuration mentioned above must be included within the vision connected="true" element. Use the structure for endpoint and binding as mentioned in this sample.

Explanation of elements

  • endpoint
    • adress: the address that is used to call the service. If the address is empty, the address that is defined in the URL property of the WebReference in Futurama is used.
    • contract: the contract is not used, but it cannot be empty, hence ‘*’

Note: when working in the Futurama Editor, this element has to be placed in the configuration file of the Futurama Editor (ActuIT.Futurama.Editor.exe.config) in order to use the webservice.

Call REST Services with Futurama

You can use Futurama to call RestServices. You can use this to call webservices with XML or JSON. To determine which format to use Futurama uses the property defaultOutgoingResponseFormat that is defined on the webHttp behavior that is associated with the endpoint. This format is used for both the input and the output. Here you find a sample configuration:

Server configuration:

<services>
	<service behaviorConfiguration="ActuIT.Futurama.WcfService.Service" name="ActuIT.Futurama.WcfService.ServiceRest">
		<endpoint address="" behaviorConfiguration="web" binding="webHttpBinding" contract="ActuIT.Futurama.WcfService.IServiceRest">
		</endpoint>
	</service>
</services>
<behaviors>
	<serviceBehaviors>
		<behavior name="ActuIT.Futurama.WcfService.Service">
			<serviceMetadata httpGetEnabled="true">
				<serviceDebug includeExceptionDetailInFaults="false">
				</serviceDebug>
			</serviceMetadata>
		</behavior>
	</serviceBehaviors>
	<endpointBehaviors>
		<behavior name="web">
			<webHttp>
			</webHttp>
		</behavior>
	</endpointBehaviors>
</behaviors>

Client configuration:

<!-- Section within: <system.serviceModel><behaviors><endpointBehaviors> -->
<behavior name="webEndpointTestRest">
	<webHttp defaultOutgoingResponseFormat="Xml"></webHttp>
</behavior>
	
<!-- Section within: <system.serviceModel><client> -->
<endpoint address="http://testwebservices/TestServicesVS/RestServiceImpl.svc/getxml/5" behaviorConfiguration="webEndpointTestRest" binding="webHttpBinding" bindingConfiguration="webHttpBindingTestRest" contract="*" name="TestRest"></endpoint>

<!-- Section within: <system.serviceModel><bindings><webHttpBinding> -->
<binding name="webHttpBindingTestRest"></binding>

Note: in the situation of:

  • the connection with Futurama Vision,
  • with a VisionReference,
  • where WCF configuration has to be set,

see this page for the client configuration for either Futurama HTML or Futurama Editor. See the sample config for Futurama HTML and Futurama Editor at this page for more information. The configuration mentioned above must be included within the vision connected="true" element. Use the structure for endpoint and binding as mentioned in this sample.

Explanation of elements

  • webHttp
    • defaultOutgoingResponseFormat: this property can be either Xml or Json. Use this property to specify if the input is Xml or Json. The value is used to fill the headers of the http message. it is used for both the accept and the content-type header.
  • endpoint
    • address: the address that is used to call the service. If the address is empty, the address that is defined in the URL property of the WebReference in Futurama is used.
    • contract: the contract is not used, but it cannot be empty, hence ‘*’ 

Note: when working in the Futurama Editor, this element has to be placed in the configuration file of the Futurama Editor (ActuIT.Futurama.Editor.exe.config) in order to use the webservice.

Raw input or output for REST calls

With REST calls normally the input is passed as JSON and the received output will be JSON. In some cases you want to use Raw input or Raw output.

You can create Raw input by adding a rawinputbehaviorelement to the endpointbehavior that is used in the WCF configuration.

You can specify Raw output by adding the following attribute to the binding that is used in the WCF configuration: contentTypeMapper="ActuIT.Futurama.Engine.RawJsonContentTypeMapper, ActuIT.Futurama.Engine, Version=*, Culture=neutral, PublicKeyToken=null"

Security with Windows Authentication on the Transport Layer

You can use the identity of the process that runs Futurama as a client credential. To do that, use the sample configuration below:

Server configuration:

<system.serviceModel>
	<serviceHostingEnvironment multipleSiteBindingsEnabled="True">
	</serviceHostingEnvironment>
	<services>
		<service behaviorConfiguration="ActuIT.Futurama.WcfService.Service" name="ActuIT.Futurama.WcfService.Service">
			<endpoint address="" binding="basicHttpBinding" bindingConfiguration="TestBindingWindowsAuth" contract="ActuIT.Futurama.WcfService.IService">
			</endpoint>
			<endpoint address="mex" binding="mexHttpBinding" contract="IMetadataExchange">
			</endpoint>
		</service>
	</services>
	<bindings>
		<basicHttpBinding>
			<binding name="TestBinding">
				<security mode="None">
				</security>
			</binding>
			<binding name="TestBindingWindowsAuth">
				<security mode="TransportCredentialOnly">
					<transport clientCredentialType="Windows">
					</transport>
				</security>
			</binding>
		</basicHttpBinding>
	</bindings>
	<behaviors>
		<serviceBehaviors>
			<behavior name="ActuIT.Futurama.WcfService.Service">
				<serviceMetadata httpGetEnabled="true">
					<servicedebug includeExceptionDetailInFaults="false">
					</servicedebug>
				</serviceMetadata>
			</behavior>
		</serviceBehaviors>
	</behaviors>
</system.serviceModel>

Client configuration:

<!-- Section within: <system.serviceModel><bindings><basicHttpBinding> -->
<binding name="TestBindingWindowsAuth">
	<security mode="TransportCredentialOnly">
		<transport clientCredentialType="Windows">
		</transport>
	</security>
</binding>

<!-- Section within: <system.serviceModel><client> -->
<endpoint address="http://localhost/TestWebService/service.svc" binding="basicHttpBinding" bindingConfiguration="TestBindingWindowsAuth" contract="ActuIT.Futurama.WcfService.IService" name="TestWindowsAuth"></endpoint>

Note: in the situation of:

  • the connection with Futurama Vision,
  • with a VisionReference,
  • where WCF configuration has to be set,

see this page for the client configuration for either Futurama HTML or Futurama Editor. See the sample config for Futurama HTML and Futurama Editor at this page for more information. The configuration mentioned above must be included within the vision connected="true" element. Use the structure for endpoint and binding as mentioned in this sample.

Explanation of elements

  • security
    • mode: with TransportCredentialOnly, you use windows authentication on the transport layer. For more details about the various options please refer to the documentation on MSDN 
       
  • endpoint
    • address: the address that is used to call the service. If the address is empty, the address that is defined in the URL property of the WebReference in Futurama is used.
    • contract: the contract is not used, but it cannot be empty, hence ‘*’ 

Note: when working in the Futurama Editor, this element has to be placed in the configuration file of the Futurama Editor (ActuIT.Futurama.Editor.exe.config) in order to use the webservice.

Security with certificates

You can use certificates as a clientcredential.

Certificates

Working with certificates can be a complicated matter, which is why we will only explain a simple base situation to build upon. More information can be found here.

Both the Host and the Client must possess a unique certificate to identify it. One can generate a temporary certificate for development purposes by using SelfCert. These keys can be imported by clicking on them, and selecting "Local machine" as the store location. 
using the  local machine certificate manager can be used with the command "certlm.msc"

Both the Client and the Host must export their certificate public key to file, which will be imported by the other into the LocalMachine certificate store, into the "Trusted People" location.

Below you find sample configurations:

Server configuration:

<services>
	<service behaviorConfiguration="TestServiceBehavior" name="ActuIT.Futurama.WcfService.Service">
		<!-- Service Endpoints -->
		<endpoint address="https://localhost/TestWebServiceCertificaten/service.svc" binding="wsHttpBinding" bindingConfiguration="TestBindingCertificate" contract="ActuIT.Futurama.WcfService.IService">
		</endpoint>
	</service>
</services>
<bindings>
	<wsHttpBinding>
		<binding name="TestBindingCertificate">
			<security mode="Transport">
				<transport clientCredentialType="Certificate">
					<message clientCredentialType="None">
					</message>
				</transport>
			</security>
		</binding>
	</wsHttpBinding>
</bindings>
<behaviors>
	<serviceBehaviors>
		<behavior name="ActuIT.Futurama.WcfService.Service">
			<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="false">
				</serviceDebug>
			</serviceMetadata>
		</behavior>
		<behavior name="TestServiceBehavior">
			<serviceMetadata httpGetEnabled="true">
				<serviceCredentials>
					<clientCertificate>
						<authentication certificateValidationMode="PeerOrChainTrust">
						</authentication>
					</clientCertificate>
					<serviceCertificate findValue="localhost" storeLocation="LocalMachine" storeName="TrustedPeople" x509FindType="FindBySubjectName">
					</serviceCertificate>
				</serviceCredentials>
			</serviceMetadata>
		</behavior>
	</serviceBehaviors>
</behaviors>

Client configuration:

<!-- Section within: <system.serviceModel><behaviors><endpointBehaviors> -->   
<behavior name="TestCertificateBehavior">
	<clientCredentials>
		<clientCertificate x509FindType="FindBySubjectName" storeName="TrustedPeople" storeLocation="LocalMachine" findValue="localhost">
		</clientCertificate>
	</clientCredentials>
</behavior>

<!-- Section within: <system.serviceModel><bindings><wsHttpBinding> -->
<binding name="TestBindingCert">
	<security mode="Transport">
		<transport clientCredentialType="Certificate">
			<message clientCredentialType="None">
			</message>
		</transport>
	</security>
</binding>

<!-- Section within: <system.serviceModel><client> -->
<endpoint behaviorConfiguration="TestCertificateBehavior" name="TestCert" contract="ActuIT.Futurama.WcfService.IService" binding="wsHttpBinding" address="https://localhost/TestWebServiceCertificaten/service.svc" bindingConfiguration="TestBindingCert">
</endpoint>

Note: in the situation of:

  • the connection with Futurama Vision,
  • with a VisionReference,
  • where WCF configuration has to be set,

see this page for the client configuration for either Futurama HTML or Futurama Editor. See the sample config for Futurama HTML and Futurama Editor at this page for more information. The configuration mentioned above must be included within the vision connected="true" element. Use the structure for endpoint and binding as mentioned in this sample.

Explanation of elements

  • clientCertificate: For a description of this element, please read http://msdn.microsoft.com/en-us/library/ms731323(v=vs.110).aspx
  • security
  • endpoint
    • address: the address that is used to call the service. If the address is empty, the address that is defined in the URL property of the WebReference in Futurama is used.
    • contract: the contract is not used, but it cannot be empty, hence ‘*’ 

Note: when working in the Futurama Editor, this element has to be placed in the configuration file of the Futurama Editor (ActuIT.Futurama.Editor.exe.config) in order to use the webservice.

Creating JSON-input

For a webservice that requires JSON-input, there are different ways to create the required JSON-input.
In Futurama it can be convenient to construct the input in an XMLBuilder, and then convert it to JSON, by use of the ConvertXML formula.
This Formula should have an appropriate XSLT-file for the conversion. We give an example of such an XSLT-file below.

Example XSLT: Convert XML to JSON

Here you can download an example XSLT-file that can be used to convert XML to JSON.
The conversion has the following properties:

  • Your XMLBuilder can hold any number or order of elements and there are no restrictions in element or attribute names
  • The main element itself is left out of the result. (So the XMLBuilder you are referring to does not appear in the JSON-input)
  • Nodes which have children are included before nodes that only hold a value (simple elements). Therefore the order of the elements in JSON may be different from its XML base.
  • All nodes which have children are placed between square brackets which indicates an array, even when it’s only one child.
  • If you want to indicate an element as an individual element instead of an array, add an attribute ‘array’ with the value ’False’ to the element. This should be the first attribute of the element.

Example of use

In the example below, the XML that results from an XMLBuilder in Futurama, is converted to JSON by using the ConvertXML formula with the XSLT-file mentioned above.

Source code

<input xmlns="http://exampleURL">
	<advicedate>2014-06-20</advicedate>
	<cars>
		<car>
			<price>8800</price>
			<kilometersperyear>16000</kilometersperyear>
			<status>New</status>
		</car>
	</cars>
	<persons>
		<person>
			<dateofbirth>1970-06-01</dateofbirth>
		</person>
	</persons>
	<netincomepermonth>2000</netincomepermonth>
	<home array="False">
		<type>Rental</type>
		<rentpermonth>300</rentpermonth>
	</home>
</input>

Result code

{"AdviceDate" : "2014-06-20", "Cars" : [{"Car" : [{"KilometersPerYear" : 16000, "Price" : 8800, "Status" : "New"}]}], "Home" : {"RentPerMonth" : 300, "Type" : "Rental"}, "NetIncomePerMonth" : 2000, "Persons" : [{"Person" : [{"DateOfBirth" : "1970-06-01"}]}]}

Related Topics

- WebReference: The main page about the WebReference object.

- Futurama Objects: The Atlas chapter that describes all Futurama objects. See the Output-section for a description of the type of objects this object belongs to.

- WebService: The WebService enables you to offer a webservice.

Updated: 2014-06-30