Search

 

Edition:Futurama Webservice

Module:Futurama Webservice

User:Developer

Prerequisites

- not applicable

Introduction

Overview of the Futurama Webservice module.

 

Description

Futurama Webservice is the Futurama component that enables you to create your own custom made webservice applications. Using dedicated objects such as the InterfacesNode and the WebService it is possible to create an application that performs actions, makes calculations etc. and then to make the result(s) available to others as a webservice.

When creating a webservice Futurama provides a pre-defined WSDL for the definition of the webservice. This WSDL describes four standard methods to call the webservice. These methods are described in the paragraph Methods. In general this will be sufficient for basic usage. From version 17.11 on Futurama offers functionality for further customization. This functionality is suited for more advanced usage. It offers the possibility to create a custom WSDL to describe the methods of the webservice. See the paragraph Generic WSDL and custom WSDL for more information.

Steps to use Futurama Webservice

To use Futurama Webservice follow the next steps:

  1. Installation of Futurama Webservice
  2. Configuration of Futurama Webservice
  3. Testing Futurama Webservice
  4. Creating a webservice application

Installation Futurama Webservice

See the support page Installation Futurama Webservice how to install Futurama Webservice.

Configuration of Futurama Webservice

After the installation of Futurama Webservice the configuration can be done. See the configuration paragraph at the support page Installation Futurama Webservice how to do the configuration of Futurama Webservice. In the release of this component a default configuration file is available to be used to do the configuration.

Testing Futurama Webservice

After the configuration of Futurama Webservice it can be tested whether the installation and configuration were succesfull. See the testing paragraph at the support page Installation Futurama Webservice on how to test the webservice, the webservice request and the response. In order to perform webservice tests a dedicated package is needed to send requests and receive responses. One such package is SOAPUI.

Creating a webservice

Using Futurama Editor and the special objects InterfacesNode and WebService you can now create your own application as well as the interface needed to make it available to others as a webservice. See the Tutorial and Exercises below for more information.

Generic WSDL and custom WSDL

The webservice that Futurama offers is a ‘generic’ webservice using a pre-defined WSDL. This implies that although the webservice itself can be built according to your own design, the same four methods are always generated to access it. See the paragraph Methods below on more information about these four methods. As explained in the testing paragraph at the support page Installation Futurama Webservice the URL to generate these methods is typically of the form http://servername/applicationname/service.svc?wsdl.

The use of the generic GetWebServiceResult operation implies that the request and response are described as 'xml' in its wsdl and therefore give no additional information about the structure and types.

To solve this problem, from Futurama 17.11 on it is also possible to generate your own custom WSDL, offering control over the operations that are offered within your Futurama document. When modelling a webservice it is now possible to define the Response and Requests in dedicated XSD files and let the webservice refer to them. See Webservice for more details. In order to request the custom WSDL instead of the generic WSDL the URL mentioned above has to be extended with the following two parameters:

  • folder: This parameter is optional. It states the folder in which the Futurama Document is located. When omitted, it is assumed the Futurama Document is located in the root folder.
  • document: This parameter is obligatory. It states the name of the Futurama Document in which the webservice is modelled.

Using the parameters mentioned above the extended URL will now become of the form http://servername/applicationname/service.svc?wsdl&folder=foldername&document=application.xml. When entering this URL in a browser it will not show the four generic methods, but the modelled webservices instead. This URL can be used in packages such as SOAPUI for further testing.

Methods

Description

With the Futurama Webservice module a custom made webservice can be created. The Futurama webservice offers four methods:

  1. GetDocumentInfo: returns information about the Futurama Document in which the webservice is built;
  2. GetDocumentVersion: returns the version number of the Futurama Document in which the webservice is built;
  3. GetFuturamaVersion: returns the version number of the Futurama installation in which the webservice is built;
  4. GetWebServiceResult: executes the webservice that is defined in the Futurama Document and returns the response defined in this 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

Below for each of these methods the input that is required. Both for SOAP and REST requests. See for REST requests the paragraph ‘Call REST Services with Futurama’ at this page for an example of client configuration. For the REST service the endpoint, the method and the request are relevant. Both JSON and XML requests are possible. A JSON request means a JSON response, a XML request means a XML response.

GetDocumentInfo

SOAP

Below an example of a SOAP request of the GetDocumentInfo method.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.ActuIT.nl/Futurama/WebService">
   <soapenv:Header/>
   <soapenv:Body>
      <web:GetDocumentInfo>
         <web:location>
            <web:Document>savingsaccountwebservice.xml</web:Document>
            <web:Folder>SavingsAccount</web:Folder>
			<!--the WebServiceName can be omitted from Futurama 17.11+:-->
            <web:WebServiceName>GetSavings</web:WebServiceName>
         </web:location>
      </web:GetDocumentInfo>
   </soapenv:Body>
</soapenv:Envelope>

REST

Endpoint: http://servername/applicationname/rest/DocumentInfo, where http://servername/applicationame points to the installation of Futurama Webservice.

Method: GET (From Futurama 17.11+, access is explained below)
Method: POST

Below an example of a JSON request (the WebServiceName can be omitted from Futurama 17.11+):

{
	"location": {
		"Folder": "SavingsAccount",
		"Document": "savingsaccountwebservice.xml",
		"WebServiceName": "GetSavings"
	}
}

Below an example of a XML request (the WebServiceName can be omitted from Futurama 17.11+):

<root>
    <location>
        <Document>savingsaccountwebservice.xml</Document>
        <Folder>SavingsAccount</Folder>
        <WebServiceName>GetSavings</WebServiceName>
    </location>
</root>

Explanation

In the request the next parameters are relevant:

  • Document: the name of the Futurama Document in which the webservice is built;
  • Folder: the folder that contains the Futurama Document in which the webservice is built;
  • WebServiceName: the name of the webservice to be executed. This webservice is defined in the Futurama Document.

 

GetDocumentVersion

SOAP

Below an example of a SOAP request of the GetDocumentVersion method.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.ActuIT.nl/Futurama/WebService">
   <soapenv:Header/>
   <soapenv:Body>
      <web:GetDocumentVersion>
         <web:location>
            <web:Document>savingsaccountwebservice.xml</web:Document>
            <web:Folder>SavingsAccount</web:Folder>
             <!--the WebServiceName can be omitted from Futurama 17.11+:-->
            <web:WebServiceName>GetSavings</web:WebServiceName>
         </web:location>
      </web:GetDocumentVersion>
   </soapenv:Body>
</soapenv:Envelope>

REST

Endpoint: http://servername/applicationname/rest/DocumentVersion, where http://servername/applicationame points to the installation of Futurama Webservice.

Method: GET (From Futurama 17.11+, access is explained below)
Method: POST

Below an example of a JSON request (the WebServiceName can be omitted from Futurama 17.11+):

{
	"location": {
		"Folder": "SavingsAccount",
		"Document": "savingsaccountwebservice.xml",
		"WebServiceName": "GetSavings"
	}
}

Below an example of a XML request (the WebServiceName can be omitted from Futurama 17.11+):

<root>
    <location>
        <Document>savingsaccountwebservice.xml</Document>
        <Folder>SavingsAccount</Folder>
        <WebServiceName>GetSavings</WebServiceName>
    </location>
</root>

Explanation

In the request the next parameters are relevant:

  • Document: the name of the Futurama Document in which the webservice is built;
  • Folder: the folder that contains the Futurama Document in which the webservice is built;
  • WebServiceName: the name of the webservice to be executed. This webservice is defined in the Futurama Document.

GetFuturamaVersion

SOAP

Below an example of a SOAP request of the GetFuturamaVersion method.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.ActuIT.nl/Futurama/WebService">
   <soapenv:Header/>
   <soapenv:Body>
      <web:GetFuturamaVersion/>
   </soapenv:Body>
</soapenv:Envelope>

REST

Endpoint: http://servername/applicationname/rest/FuturamaVersion, where http://servername/applicationame points to the installation of Futurama Webservice.

Method: GET

Below an example of a JSON request:

GET method, no parameters needed.

Below an example of a XML request:

GET method, no parameters needed.

Explanation

In the request no parameters are needed.

GetWebServiceResult

SOAP

Below an example of a SOAP request of the GetWebServiceResult method.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.ActuIT.nl/Futurama/WebService">
	<soapenv:Header/>
	<soapenv:Body>
		<web:GetWebServiceResult>
			<web:location>
				<web:Document>savingsaccountwebservice.xml</web:Document>
				<web:Folder>SavingsAccount</web:Folder>
				<web:WebServiceName>GetSavings</web:WebServiceName>
			</web:location>
			<web:inputxml>
				<!--You may enter ANY elements at this point-->
				 <data xmlns="http://www.futurama.eu/Safe2SaveWebservice">
                    <cashbalance>10000</cashbalance>
                    <interest>3</interest>
                    <years>25</years>
                </data>
			</web:inputxml>
		</web:GetWebServiceResult>
	</soapenv:Body>
</soapenv:Envelope>

REST

Endpoint: http://servername/applicationname/rest/WebServiceResult, where http://servername/applicationame points to the installation of Futurama Webservice.

Method: POST

Below an example of a JSON request:

{
	"location": {
		"Folder": "SavingsAccount",
		"Document": "savingsaccountwebservice.xml",
		"WebServiceName": "GetSavings"
	},
	"input": {
		"data": [{
			"CashBalance": 10000,
			"Interest": 4,
			"Years": 25
		}]
	}
}

Below an example of a XML request:

<root>
	<location>
		<Document>savingsaccountwebservice.xml</Document>
		<Folder>SavingsAccount</Folder>
		<WebServiceName>GetSavings</WebServiceName>
	</location>
	<input>
		<data>
			<cashbalance>10000</cashbalance>
			<interest>3</interest>
			<years>25</years>
		</data>
	</input>
</root>

Explanation

In the request the next parameters are relevant:

  • Document: the name of the Futurama Document in which the webservice is built;
  • Folder: the folder that contains the Futurama Document in which the webservice is built;
  • WebServiceName: the name of the webservice to be executed. This webservice is defined in the Futurama Document.
  • The data that is sent to the webservice is the complete XML element, or in the case of JSON data, a version of the JSON data that is converted to XML. Because a JSON Object does not contain a name, like an XML Element would, the converted JSON object will be contained in a element. So when the data element needs to be accessed within Futurama, an XmlNode with the XPath value '//data' should be used.
  • From Futurama 21.11 it is possible to make use of sessions in webservices. To be able to use sessions first a change has to be made in the configuration of Cache. Then a SessionID can be generated using the method StartSession (see below). This SessionID then has to be included in the metadata of the request (and not for instance in the <soapenv:Header/>)

StartSession (from Futurama 21.11)

SOAP

Below an example of a SOAP request of the StartSession method.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.ActuIT.nl/Futurama/WebService">
   <soapenv:Header/>
   <soapenv:Body>
      <web:StartSession>
         <web:location>
            <web:Document>savingsaccountwebservice.xml</web:Document>
            <web:Folder>SavingsAccount</web:Folder>
            <web:WebServiceName></web:WebServiceName>
         </web:location>
      </web:StartSession>
   </soapenv:Body>
</soapenv:Envelope>

Explanation

In the request the next parameters are relevant:

  • Document: the name of the Futurama Document in which the webservice is built;
  • Folder: the folder that contains the Futurama Document in which the webservice is built;
  • The result of this request will be a SessionID. This ID has to be used in subsequent requests in order to make use of session preservation. The SessionID has to be included in the Header of the request using the key "FUT_SessionKey".

SessionKeepAlive (from Futurama 21.11)

SOAP

Below an example of a SOAP request of the SessionKeepAlive method.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.ActuIT.nl/Futurama/WebService">
   <soapenv:Header/>
   <soapenv:Body>
      <web:SessionKeepAlive>
         <web:req>
            <web:SessionID>a29502a7-a7e2-44a7-8001-e7e3cfe499ec</web:SessionID>
         </web:req>
      </web:SessionKeepAlive>
   </soapenv:Body>
</soapenv:Envelope>

Explanation

In the request the next parameter is relevant:

  • SessionID: the ID of the session that has to kept alive (therebij preventing a timeout);

EndSession (from Futurama 21.11)

SOAP

Below an example of a SOAP request of the EndSession method.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.ActuIT.nl/Futurama/WebService">
   <soapenv:Header/>
   <soapenv:Body>
      <web:SessionEnd>
         <web:req>
            <web:SessionID>5d9c118f-16d7-4173-a77d-d3a580622c81</web:SessionID>
         </web:req>
      </web:SessionEnd>
   </soapenv:Body>
</soapenv:Envelope>

Explanation

In the request the next parameter is relevant:

  • SessionID: the ID of the session that has to be ended. The SessionID wil no longer be available to perform requests;

Using location data in the URL [Futurama 17.08+]

For REST calls to GetWebserviceresult method, you can also provide the location data in the URL. When this method is used, the input data can be provided without any surrounding root element.

For example, the earlier webservice call would using the URL http://servername/applicationname/rest/WebServiceResult/?folder=SavingsAccount&document=savingsaccountwebservice.xml&webservicename=GetSavings and the XML request would look like this:

<data>
    <cashbalance>10000</cashbalance>
    <interest>3</interest>
    <years>25</years>
</data>

For Futurama version 17.11+, this same approach can be used to access the Rest webservices for DocumentInfo and DocumentVersion, using the HTTP Get or Post method, for both the XML and JSON datatype.

Related Topics

- Installation Futurama Webservice: How to install and upgrade Futurama Webservice

- InterfacesNode

- WebService

Related Tutorials

- Creating a Webservice Application: Tutorial about how to create a webservice application in Futurama

- Webservice Exercise (Easy): Exercise about creating a simple Webservice application

- Webservice Exercise (Medium): Exercise about creating a more elaborate Webservice application

Feedback

If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.

Updated:2017-04-07