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 a 'PUT'. This can be an XmlBuilder, but also other objects of type String. When the HttpMethod is a '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 a '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. It is possible to add a namespace, but prefixes are not allowed. 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'.

IncludeHTTPHeadersInResult (Futurama 21.11+)

A boolean that indicates if the metadata information located in the httpheader should be included in the result. This property is only available when the method is 'WCF' and only when the config setting showInfoInResponse in the Debug section is set to 'true'.

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

From Futurama 21.11 onward the following MethodNames are available as well:

• http://www.ActuIT.nl/Futurama/WebService/IService/StartSession
• http://www.ActuIT.nl/Futurama/WebService/IService/SessionKeepAlive
• http://www.ActuIT.nl/Futurama/WebService/IService/SessionEnd

See paragraph Methods of the Overview 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.

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

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

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

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

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