Search

Module:Editor

Version:3.3.0 +

User:Developer

Object Type:Output Object

Parent of:

no children

Child of:

- Document

- Node

 

Description

The edition Futurama Webservice enables you to offer your own custom made webservice. You can build this webservice in the Futurama Editor, using the WebService object.

The Futurama WebService offers a generic webservice. This webservice holds a build-in WCF Webservice.
It provides the following four methods:

  1. GetDocumentInfo: returns information about the Futurama Document that holds the Webservice.
  2. GetDocumentVersion: returns the version number of the Futurama Document that holds the Webservice.
  3. GetFuturamaVersion: returns the version number of the Futurama version in which the Webservice is built.
  4. GetWebServiceResult: executes the webservice defined in the Futurama Document.

From Futurama 21.11 onward three additional methods are provided as well:

  1. StartSession: starts a session for the specified Futurama Document and returns the SessionID
  2. SessionKeepAlive: keeps the session with a specified SessionID alive (to prevent a time-out)
  3. SessionEnd: ends the session with a specified SessionID

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

The GetWebServiceResult method is the most important method. This method has to be used while building the custom webservice. When requesting the GetWebServiceResult webservice, Futurama opens the corresponding Futurama Document and executes the requested webservice. This means that the input submitted is entered in the webservice object in Futurama. The result of the XMLBuilder in the XMLOutput property, is given back as the response.

From Futurama 17.11 onward it is possible to deviate from the ‘generic’ WSDL (Web Services Description Language) with the four standard methods as stated above and create a custom made WSDL instead. The schema of the Request as well as the Response of the webservice can then be detailed in a custom XSD File. The WSDL of this webservice is then generated based on this schema. See the Properties section for more details.

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

DefaultNamespace (Futurama 23.12+)

Define the namespace to be utilized in your webservice request. When executing a RESTful JSON call to this webservice, the 'DefaultNamespace' parameter ensures the inclusion of the required namespace at the top of the XML during the JSON-to-XML conversion process. This guarantees the validity and alignment of your XML with your application requirements. It's important to note that this parameter is specifically applicable within the context of a RESTful JSON call.

HttpHeaders (Futurama 23.09+)

Here you can define a list of headers that will be added to your response. The value needs to be an XML structure and will usually reference to a XmlBuilder. By default it is empty. The XML should have the structure as shown below:


  data1
  ...
  data1

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.

StatusCode (Futurama 23.09+)

This will be the response code of your request which can reflect the status of the server. To learn more, you can check HTTP Status. Each range of status code have different meanings so please use it with care. The status code should be a value between 100 and 599. By default, the StatusCode is empty. If not set, your request will return the status code 200.

TestValue

In the Editor you can enter data here that serves as test input in order to simulate the workings of your webservice. The input has to have the type String and has to be valid XML complying to the required input of the webservice. The property is not used when the webservice is requested in a LIVE situation.

XmlOutput

In this property the outcome of the webservice is defined. You have to refer to an XMLBuilder that holds the results.

(Name)

The name of the object.

Comment

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

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.

Type

This is an automatic property. The value is String by default.

ExposeExplicitOperation (Futurama 18.03+; previously called GenerateCustomWsdl from Futurama 17.11+)

Possible values are 'True' or 'False'. If the value is set to 'False', no explicit webservice operation is exposed and thus no explicit WSDL will be generated alongside the standard ‘generic’ WSDL. If the value is ‘True’, an explicit WSDL will be generated for this operation. In order to accomplish this, a couple of properties will have to be set as mentioned below. There also have to be added some elements to the webservice configuration-file. See Installation Futurama Webservice, paragraph “Explicit operation exposure (Futurama 18.03+)” for more information.

Request (Futurama 17.11+)

Here the properties of the Request have to be set. The following subproperties are available:

  • Name: This property is mandatory. Here the name has to be set of the element in the XSD File that contains the schema of the Request. In the example below the name to be used is ‘WebserviceRequest’. This element is expected in the target namespace of the XSD File. The names have to match, otherwise Futurama will return a Validation error. In the paragraph Generating XSD files below it is explained how to generate XSD files.

    
        
             
        
    
  • XsdFile: This property is mandatory. Here the XSD File has to be set which contains the schema of the Request to the webservice. Read this topic for more details.

Response (Futurama 17.11+)

Here the properties of the Response have to be set. The following subproperties are available:

  • Name: This property is mandatory. Here the name has to be set of the element in the XSD File that contains the schema of the Response. In the example below the name to be used is ‘WebserviceResponse’. This element is expected in the target namespace of the XSD File. These names have to match, otherwise Futurama will give a Validation error. In the paragraph Generating XSD files below it is explained how to generate XSD files.

		
			
				
			
		
	 
  • XsdFile: This property is mandatory. Here the XSD File has to be set which contains the schema of the Response of the webservice. This is often the same XSD File that contains the Request, but this is not obligatory. Read this topic for more details. 

InterfacesNode

In the Futurama Document that holds the WebService object(s), there also has to be a so-called InterfacesNode object. In this Node you have to create a separate Reference to each of the Webservice objects. Make sure to name each Reference appropriately for when calling the webservice, the name of the reference linked to it is used. This construction ensures that each webservice has a unique and uniform way to call it, even when you have multiple Webservices, or if you rename or move one of them.

Generating XSD files (Futurama 17.11+)

From Futurama 17.11 onward it is possible to expose explicit operations and thus publish specific WSDL alongside 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. 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 could need further alterations (such as specifying element types). Read this topic to get started.

Example

In the tutorials a webservice is created that can be downloaded as an example.

Download

Download the Webservice example out of the page Tutorials - Examples and Downloads.

Description

  1. Open the website.xml-document which is contained in the zip-file in the Futurama Editor (Version 4.2.1 or later).
  2. Here a Webservice object can be seen within the Futurama Document.
  3. The document contains an XMLBuilder which is referred to in the XmlOutput property of the WebService object. This XmlBuilder holds the outcome of the webservice, which is a reference to a formula.
  4. In the TestValue property a reference is made to an xml-file that holds test data. This enables us to simulate the outcome of the webservice.
  5. The document also contains an InterfacesNode, which holds a reference to the Webservice object. The name of the reference 'GetSavings' is used when calling the webservice.
  6. See the tutorial series for how you can test or run this webservice.

Related Topics

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

- WebReference: The WebReference can be used to call an external webservice

- InterfacesNode: The InterfacesNode is required for creating a webservice

- Creating XSD files and using them in combination with Futurama.

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 webserivce application in Futurama.

 

Updated: 2018-01-09