Search

Module: Editor

Version: 2.2.1 +

User: Developer

Object Type: Data Object

Parent of:

no children

Child of:

- Document

- Node

Description

With the WebReference object you can refer to a webservice. This enables you to use functionality e.g. a calculation that is processed on another server.

When doing a request to a webservice, the other server will return XML data as a response. The XmlNode and the XmlField objects can be used to use data from this response.

Properties

DebugLogMode (from version 4.1)

Indicates the level of detail of debug information that is logged during runtime of the website to the trace, a logfile, a database etc. The possible values are:

  • None: no debug information is logged
  • Simple: only basic information is given
  • Extended: in addition to the information in the Simple mode the values of all the properties of the object are shown

ErrorBehavior (from version 5.3)

Possible values are 'Fail' or 'Report'. If the value is 'Fail', then the webreference will return the exact answer of the webservice and only that. If the webservice call fails, your application is likely to show unwanted behaviour or even crash.
If the value is 'Report', an xml wrapper with information about the webservice call is added to the xml answer. The status element in the xml answer can be used to handle unsuccessful webservice calls. This means the 'Report' option can f.i. be used to deal with downtime of the webservice.

In 'Fail' mode, if the webservice call is technically correct, but the input is wrong, you will receive a proper error message in xml. Depending on the content of the error message, you can let your application respond in the correct way.
However, if your webservice call is technically incorrect, then you will not receive a result and errors will occur. It's quite difficult to let your application respond to this situation in a proper way.
Therefore the 'Report' option can be used.
Before you use results of the webservice response in your application, first check for the 'Status' in the response, which is allways available. This enables you to prevent referring to non-existing elements of the webservice response.

See below for some examples.

IsPublic

Possible values are 'True' or 'False'. If the value is 'False', then the object can only be used within the document where it is created. If the value is 'True', then also from other Futurama documents can be referred to this object. This means that changes in the object also affect the document in which is referred to this object. If the value is 'True' and you attempt to move or delete the object, a warning will be given. To limit these warnings to a minimum it is recommended to set IsPublic to 'True' only when necessary 

Method

The web reference can be made using one of the following three methods:
  1. SOAP
    • This method uses the soap protocol
    • You can choose an HttpMethod to specify a GET or POST operation
    • The input for the webservice should be entered in the XmlInput property.
  2. WCF
    • Available from version 5.2.
    • All the configuration for the webreference is done in the config files. For extra information how to configure with WCF, see this page.
    • The WCF method can be GET or POST. This depends on the way the input is provided in the webreference. When the WCF has to be GET, the input should be placed in the URL. When the WCF has to be POST, the input should be placed in de XmlInput property.
  3. REST_JSON
    • This method calls a REST service with JSON input and JSON output
    • You can choose the HttpMethod

HttpMethod

When you use Method SOAP or REST_JSON you can specify the HttpMethod

Url

Here you should enter the location of the webservice you want to call. If the Method chosen is 'GET', then you should also provide a parameter in the URL that serves as input for the webservice. When the method is 'WCF' this property is optional. When you are using WCF Futurama first checks if there is an address defined in the Endpoint configuration in the config file. If that is the case than that address is used. If there is no address in the Endpoint then the URL property is used.

You cannot use an ampersand in the address you define in the config file. To define an address with an ampersand use &. For example: the address http://www.webservicex.net/CurrencyConvertor.asmx/ConversionRate?FromCurrency=USD&ToCurrency=EUR should be written in the config file as http://www.webservicex.net/CurrencyConvertor.asmx/ConversionRate?FromCurrency=USD&ToCurrency=EUR

Input

In this property the XML should be entered that serves as input for the webservice to be called if the HttpMethod chosen is a 'POST' or ‘PUT’. This can be an XmlBuilder, but also other objects of type String. When the HttpMethod is ‘GET’, the Input property is ignored.  If you use WCF, the input can be XML, or if the binding is webHttp the input can be JSON. To create JSON in Futurama, see the section 'Creating JSON-input' at this page.

(Name)

The name of the object.

Comment

Here a comment can be entered. For example a short description of the object.

TimeOut

The timeout in seconds to use when connecting to a webservice. When the method is 'WCF' this property is not available. In that situation the timeout can be configured in the applicable configuration file.

EndPointName (only available when method is WCF)

The EndPointName is the name of the endpoint you want to use. The endpoint provides information about the configuration of the application being called, for example the location of the application and security properties.

The endpoint should be configured in the Config file of the application. For extra information about adding the endpoint in the Config file, see this page.

HttpMethod

Possible values are 'GET', 'POST', 'PUT'. This property controls which HttpMethod is used for the webservice call. If you use ‘GET’, no Input will be passed to the webservice.

InputHeader

A reference to the XML Builder that is used as the input for the header. If the XML Builder returns a single XML node, one header is created. If the XML Builder returns multiple Xml nodes (by using a XML Builder with a name that starts with $), Futurama creates multiple headers. This property is only available when the method is 'WCF'. The headers which are created are message headers. So this property is only applicable in the SOAP context as REST doesn’t have message headers.

InputHttpHeader

A reference to the XML Builder that is used as the input for the header. If the XML Builder returns a single XML node, one header is created. If the XML Builder returns multiple Xml nodes (by using a XML Builder with a name that starts with $), Futurama creates multiple headers. This property is only available when the method is 'WCF'. The headers which are created are http headers. 

IncludeHeaderInResult

A boolean that indicates if the header information should be included in the result. This property is only available when the method is 'WCF'.

ID

The unique identification number of the object. This number is automatically generated by Futurama on the moment of creation. This number can be used when searching for a certain object in the Find Window.

MethodName

Here you should enter the name of the calculation you want to perform on the other server. This is because it is possible that there are multiple calculations on the server. For A REST service, no MethodName is required.

If your invoking a webservice that is made with Futurama, the possible MethodNames are:

  • http://www.ActuIT.nl/Futurama/WebService/IService/GetDocumentInfo
  • http://www.ActuIT.nl/Futurama/WebService/IService/GetDocumentVersion
  • http://www.ActuIT.nl/Futurama/WebService/IService/GetFuturamaVersion
  • http://www.ActuIT.nl/Futurama/WebService/IService/GetWebServiceResult

See paragraph Methods of the Installation Futurama Webservice page for more information of these methods.

UseProxyServer

Possible values are 'True' or 'False'. The default values is 'False'. If the value is 'True', then a proxyserver is used when calling a webservice. You can enter the value dynamically, for instance by letting it depend on whether you're working on an in- or external environment.
If the value 'True' is chosen, the three properties below appear. When the method is 'WCF' this property is not available.

Port

Here you should enter the number of the port on the ProxyServer. When the method is 'WCF' this property is not available.

ProxyMode

Possible values are 'Default', 'Anonymous', 'UsernameAndPassword' en 'WindowsAuthentication'. When the method is 'WCF' this property is not available.

If the value is 'Default', then the default proxy server configuration of .Net is used. You can configure this in the configuration of .Net. Consult the documentation of Microsoft for more information.

If the ProxyServer is configured to allow all users to call the webservice via the proxy, then the value should be 'Anonymous'. It's also possible that the ProxyServer is configured to only allow certain users to call the webservice via the proxy. Other users will be blocked by the firewall of the ProxyServer. If this is the case, the value should be 'UsernameAndPassword'. You then should enter the Username and Password of the user that is allowed to call the webservice via the proxy.

Last option is the value 'WindowsAuthentication'. In Editor mode, the data of the Futurama user is passed to the ProxyServer. If this user is not blocked by the ProxyServer's firewall, then he can call the webservice. Otherwise, an error message will appear. In Website mode, the user data of the account that hosts the application pool in IIS is passed to the ProxyServer.

ProxyServer

Here you should enter the name or the IP address of the ProxyServer. When the method is 'WCF' this property is not available.

Testfiles

The XML-data that is returned by a WebReference can be tested in the Editor by creating a testfile. In the menu-item Tools|Settings in the menubar in the Editor the option 'TestFileNameXmlBuilder' can be used to indicate the name and location of this testfile. Therefore the extension always has to be 'xml'. In the Document Explorer a rightclick on the WebReference opens a contextmenu. In this menu select the option Debug|Create Testfile. On the location specified in the option 'TestFileNameXmlBuilder' an XML-file is created containing the XML-data. In this way it can be tested whether the structure and contents of the data is as expected.

Generating XSD files (Futurama 17.11+)

From Futurama 17.11 onward it is possible to generate a custom WSDL instead of the ‘generic’ WSDL. See Installation Futurama Webservice for more information. When modeling a custom WSDL the definition of the Request and Response of the webservice are laid down in a so called XSD file. In general an XSD file (XML Schema Definition) is a file that defines validation rules for XML, in this case the (XML) format of the Request and the Response. Constructing an XSD is not covered in the Futurama Support Site, for much information is available on the internet. However, to accommodate the construction of an XSD file, Futurama Editor contains functionality to generate a basic XSD file. In order to do this, perform a rightclick on the object and select Debug | Create xsd file. Futurama will open a Save As dialog window where the name and location of the XSD file can be specified. The generated XSD file only provides the basic structure. In order to make it work properly for the webservice under development it will need further alterations.

Security

With WCF Futurama has a lot of security options to use when calling webservices. Futurama support the folowing WCF options:

  • transport security with a wsHttp binding
  • based on windows credentials
  • based on a certificate
  • message security with a wsHttp binding

You can also use an http authentication header. This header is sent in plain text, so we advise you to only use that with https connections. This method is not part of the standard WCF options. To use this options first you need to define an extension for the behavior with the following code:

<!-- Section within: <system.serviceModel><extensions><endpointBehaviors><behaviorExtensions>-->
<add name="clientCredentialsInHeaderAdapter" type="ActuIT.Futurama.Engine.ClientCredentialsInHeaderAdapterBehaviorElement,ActuIT.Futurama.Engine, Version=*, Culture=neutral, PublicKeyToken=null"/>

Then you have to add the following code to the behavior-section that corresponds with the endpoint your using:

<!-- Section within: <system.serviceModel><behaviors><endpointBehaviors><behavior>-->
<clientCredentialsInHeaderAdapter>	
	<userName userName="username" password="password"/>
</clientCredentialsInHeaderAdapter>

Examples of the usage of ErrorBehavior

Successful webservice call with ErrorBehavior 'Fail'

<AddNumbersResponse xmlns="http://tempuri.org/">
	<addnumbersresult>3</addnumbersresult>
</AddNumbersResponse>	

Successful webservice call with ErrorBehavior 'Report'

<webreferenceresult xmlns="http://www.futurama.eu/WebReferenceResult/">
	<status>Success</status>
	<result>
		<addnumbersresponse xmlns="http://tempuri.org/">
			<addnumbersresult>3</addnumbersresult>
		</addnumbersresponse>
	</result>
</webreferenceresult>

Unsuccessful webservice call with ErrorBehavior 'Report'

<webreferenceresult xmlns="http://www.futurama.eu/WebReferenceResult/">
	<status>Failed</status>
	<exception>
		<error message="There was no endpoint listening at http://testwebservices/TestServicesVS/WCFServiceUnsecureNonExistent.svc that could accept the message. This is often caused by an incorrect address or SOAP action. See InnerException, if present, for more details." source="Object: ActuIT.Futurama.Engine.WebReference; value: ActuIT.Futurama.Engine.WebReference" time="18:06:15 12:02:01" type="System.ServiceModel.EndpointNotFoundException" xmlns=""/>
		<innerexception message="The remote server returned an error: (404) Not Found." source="Object: ActuIT.Futurama.Engine.WebReference; value: ActuIT.Futurama.Engine.WebReference" time="18:06:15 12:02:01" type="System.Net.WebException"/>
	</exception>
</webreferenceresult>

More information

More information can be found in the subpage of this subject.

Related Topics

- WebReference WCF Configuration: Extra information how to configure with WCF.

- 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.

- XmlNode:

- XmlField:

Updated: 2017-04-10