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.

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

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.

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