Edition: Futurama Webservice

Module: Futurama Webservice

User: Developer


- not applicable


Introduction of the Futurama Web API.



At the ‘About-Futurama’ page in paragraph ‘Futurama structure’ the structure of Futurama is explained. Futurama is divided into three different Futurama Editions:

  1. Futurama Website
  2. Futurama Webservice
  3. Futurama Export

The Futurama Webservice edition is used to create webservice applications. In the Futurama Editor you can easily set up the webservice functionality, and implement the computational part that can be as complex as you want your application to be. The Futurama Website edition is used to create interactive website applications. In the Futurama Editor you can build the computational part as well as the website pages in which the results should be displayed. In this situation the entire webpage is built in Futurama and gets its own URL to browse to.

A large part of systems within the work area consist of Content Management Systems (CMS), which are a flexible solution for various IT roles. Its primary role is providing a user with various document/webpages that are retrieved or generated from content in a database. These documents contain various media formats, like formatted text, images, video, audio or file attachments. With Futurama Web API it is possible to integrate the CMS content with Futurama web content. This means that part of the webpage created with the CMS is created using content generated by Futurama. In this situation the webpage is not created in Futurama, but a Futurama Webservice is used to retrieve the suitable data to create the Futurama part of the website created by the CMS.

At this page is explained how to use Futurama Web API.

Futurama Web API

Futurama Web API can be used to integrate Futurama output with your own Content Management System. Using the Futurama Web API the next structure is important to keep in mind.

CMS (front-end)

The front-end is the website created within your Content Management System. This front-end must interact with the back-end . In order to interact with this back-end a CMS specific plugin has to be used/made. Using this plugin it must be possible both to do a request to the Futurama Web API and receive the response of this request and integrate this response in the CMS website.

Futurama Webservice (back-end)

At the back-end the Futurama Webservice edition is used with the Futurama Web API module. The CMS plugin communicates with the Futurama Web API module. See paragraphs ‘Installation’ and ‘Configuration’ how to set up the back-end environment.


Out of the scope of this page is an explanation how to create the plugin to be used by the CMS. This is CMS specific, and no part of a Futurama release. However, the back-end is part of a Futurama release. At the back-end server the Futurama Webservice  code has to be installed. See the ‘Installation’ paragraph of  ‘Installation Futurama Webservice’ how to install the Futurama Webservice code. If this is the first installation follow the steps in the subparagraph ‘Installation initial version’. If you already have installed the Futurama Webservice code, and want to upgrade this to a new version follow the steps in the subparagraph ‘Upgrading existing version’. The subparagraph ‘Installation Futurama application’ can be omitted. Later at this page an alternative example will be used.

The WSDL of the Futurama Web API should now be accessible through  'http://servername/applicationname/WebAPIService.svc?wsdl’.


To use the Futurama Web API functionality in the web.config of Futurama Webservice a Web API specific futuramaSettings section has to be included. See for details ‘Configuration – WebAPI’.

Futurama Web API message format

Communication between the front-end and the Futurama Web API can be done using SOAP or REST. Mentioned below the structure of the request to and the response from the Futurama Web API. 

Request – general – SOAP

The WSDL of the Futurama Web API is  'http://servername/applicationname/WebAPIService.svc?wsdl’. Below the general structure of the SOAP request:


In the request a couple of parameters are used. All of these parameters are optional.  If a parameter is not used then it must be omitted in the request. Should a request be made without providing any fields, the Futurama Web API will look for the default document that can be configured in the mapping section of the web.config, and load the start page that is defined in the Futurama document. See below the explanation of the parameters:

  • Action: This parameter is for internal testing purposes only and should be omitted.
  • Document: This parameter is the document name. This can also be configured in the Futurama mapping element specified in web.config.
  • Folder: This parameter is the Folder in which to look for a document. This can also be configured in the Futurama mapping element specified in web.config. This folder name should be relative to the Futurama Webservice application path.
  • HTTPMethod: This parameter is for internal testing purposes only and should be omitted.
  • PanelIDs: Here a list of IDs can be specified, which limits the scope of the Futurama render action to only those webpanels with these id's. This field will be used most frequently in case a WebControl has an UpdatePanelID specified, which means that should that particular control be the cause of a postback-request, then only the UpdatePanel that is specified should be requested. That way only actions within that WebPanel will be triggered, and no actions outside it. This functionality is associated with the ProcessFullPage parameter mentioned below.
  • PanelNames: Instead of specifying ID-codes for the panels to retrieve you can also specify a list of names. These names need to refer to the name of references within a InterfaceNode within the Futurama document.
  • Parameters: The parameter collection mimics the Forms collection in a traditional HTTP browser request. It contains a list of objects with a 'name' and a 'value field, which can be used to manipulate the value of a WebControl upon request (postback). See the paragraph ‘Manipulating Futurama Web Control’ for more information.
    A parameter can also be used to provide data unrelated to Webcontrols by setting this data in the ‘value’ field of a new Parameter element. This value can be retrieved by using the ReadRequestParameter formula within Futurama, using the value of the Name element as the input for this formula.
    From Futurama 17.02+ it's possible to provide raw XML data by using the XMLData element instead of setting the Value element.
    The element 'ParameterType' is (for the time being) only used for internal purposes and can be omitted.
  • Prefix: The prefix parameter is a feature used in case of multiple parallel WebAPI calls, which would generate Futurama Client-IDs in the form of “id{prefix}{number}”.
    This might be useful if the generated response is in the form of HTML, and is placed within an existing CMS webpage containing HTML elements with similar ID codes. This would be confusing when the CMS page has to interact with it’s webserver. So for this reason it’s possible to use the prefix parameter to prefix all futurama webcontrol id’s with a fixed value.
  • ProcessFullPage: This parameter indicates whether the full page should be processed, or only a requested panel. Default value is 'true'. This can be used to mimic a scenario where a request does an ajax postback for a certain updatepanel. So whenever only a certain panel needs to be updated, it has to be provided as the only panelID/name in the request, and ProcessFullPage must be set to 'false'.
  • PrevStateID: The previous state. If you request an historic state by passing the parameter StateID, you must also pass PrevStateID. In that way Futurama can determine if you are going back or forward in the history.
  • RequestValidationToken (From Futurama 16.11+): This parameter needs to be used for posting back changes to the document. See below 'Consecutive requests' for more information.
  • SessionID: If consecutive calls to the same document should be made, with retention of variable values, then the unique identifier for this session must be provided. It can be retrieved from the response of an earlier WebAPI call. See below 'Consecutive requests' for more information.
  • StateID: The StateID you want
  • UpdatePanelPrefix (From Futurama 17.02+): In order to fully mimic the AJAX functionality of Futurama Web, the prefix of an updatepanel can be provided. This value ensures that panels that need to be updated can be reached through references. The value to enter here is the same updatePanelID that is rendered in the output of a AutoPostback-capable WebControl, such as button.
  • UserAgent (From Futurama 17.02+): The user agent that is used to access the webservice. This field can be used in the transformation XSL file to differentiate output for different user agents.

Response – general – SOAP

The general structure of a request is mentioned below:

         <!DOCTYPE html>
            {base64 encoded binary data}
                        This is the first WebPanel
                        This is the second WebPanel
         123747849849 (from Futurama 6.0 +)
         0 (from Futurama 6.0 +)

The resulting information within the response consists of the following elements:

  • CssFiles (Futurama 17.02+): A list of Stylesheets that are configured within the transformation XSL file's RenderOutput object (see Futurama Intermediate Control Output)
  • DocType (Futurama 17.02+): The Document type that is configured in the Futurama Document, or overridden within the transformation XSL file's RenderOutput object (see Futurama Intermediate Control Output)
  • Download (Futurama 17.03+): When a Download/WordConverter/DocConverter has executed, it will provide its binary data in this object. Its properties are as follows:
    • Data: A base64 encoded string of binary data.
    • DownloadStyle: This tells how the DocConverter or Download object intended the data to be opened by a browser. Possible values are “Open”, “OpenInNewWindow” or “Download”.
    • Filename: This contains a string with a suggested filename to be used when saving to disk.
    • Mimetype: This will contain a string with the mimetype. For instance “image/jpg” for an JPEG image, or “application/XML” for XML data.
  • Errors: A list of errors that might have occurred during the processing of this request. In this example it is set to an empty “nil” value.
  • MetaTags (Futurama 17.02+): A list of MetaTags that are configured within the transformation XSL file's RenderOutput object (see Futurama Intermediate Control Output)
  • PageCssClass (Futurama 17.02+): The CssClass that is attributed to the current WebPage.
  • PageTitle (Futurama 17.02+): The title that is attributed to the current WebPage.
  • Panels: This contains a collection of Panels containing FICO code of rendered panels that are provided in the request, or are the default page/panel to be displayed. See the FICO paragraph below for more information.
  • PanelsJSON: This is a variation of the Panels object for usage in the REST variant of this method.
  • RequestValidationToken: This value should be used in the following request, see below for a further explanation.
  • ScriptFiles (Futurama 17.02+): A list of ScriptFiles that are configured within the transformation XSL file's RenderOutput object (see Futurama Intermediate Control Output)
  • SessionID: This contains the ID of the current user-session.
  • SmartNavigation (Futurama 17.02+): Indicating whether SmartNavigation is enabled for the current Futurama document.
  • StateID: the ID of the state that is retrieved by the current request.
  • StyleSheet (Futurama 17.02+): Indicates the stylesheet attributed to the current Futurama WebPage.
  • WindowIndex: In Futurama there are a couple of different Buttontypes. The Buttontypes NewWindow and NewThread both open a new window retaining the current session.  Within Futurama a so called WindowIndex is used to administrate which windows during a client session are opened. Default this is one window (WindowIndex has value 0). In the situation of the NewWindow and NewThread more windows are used. These successive windows get their own WindowIndex to identify them (WindowIndex=1, WindowIndex=2, and so on). In the Futurama Web API context in the response the WindowIndex is given (i.e. the index of the window from which the response is generated). Default this will be WindowIndex=0, and can be ignored/omitted for further use.

Request – general – REST (from Futurama 17.05+)

In order to access Futurama WebAPI through a REST style of webservice, the same functionality can be achieved. The requests must be performed by sending the input as a HttpPost to the “/rest/Webapi” path. By setting the requests content-type to “application/json” the following kind of request can be sent:

	"Action": "?",
	"Document": "?",
	"Folder": "?",
	"HTTPMethod": "?",
	"PanelIDs": ["id?"],
	"PanelNames": ["?"],
	"Parameters": [{
			"Name": "?",
			"ParameterType": "?",
			"Value": "?",
			"XMLData": "?"
	"Prefix": "?",
	"ProcessFullPage": "?",
	"PrevStateID": "?",
	"RequestValidationToken": "?",
	"SessionID": "?",
	"StateID": "?",
	"UpdatePanelPrefix": "?",
	"UserAgent": "?"

This request mimics the data structure shown earlier in the SOAP example, and therefore all fields are optional. Should the request content-type be set to “application/xml”, then the Request element within the SOAP example can be used as input for the REST web service.

Response – general – REST (from Futurama 17.05+)

The response to a REST web service call will contain the same data as the SOAP variant, but will be rendered in JSON if the content-type of the original request is set to “application/json”. In the case of “application/xml”, then the response will look like the earlier shown SOAP example’s Response-element.

   "PanelsJSON": [/* A string of transformed FICO */ }],
   "SessionID": "8e71006d-259e-464e-8d3d-720033f915cc",
   "RequestValidationToken": "1401258799",
   "ScriptFiles":    [
         "File": "Scripts/jquery-1.4.1.min.js",
         "Type": "text/javascript"
         "File": "Scripts/FuturamaScripts.js?v=",
         "Type": "text/javascript"
   "MetaTags":    [
         "Content": "no-cache",
         "HttpEquiv": "Pragma",
         "Name": null
         "Content": "-1",
         "HttpEquiv": "Expires",
         "Name": null
         "Content": "NO-CACHE",
         "HttpEquiv": "CACHE-CONTROL",
         "Name": null
   "DocType": "",
   "SmartNavigation": true,
   "StyleSheet": "CONTENT.CSS",
   "PageCssClass": "",
   "Download":    {
      "Data": "/*Base64 encoded data*/",
      "MimeType": "application/pdf",
      "Filename": "result.pdf",
      "DownloadStyle": "Download"


The Panels that are listed in the response of the Futurama Web API request contain FICO code. FICO is short for Futurama Intermediate Control Output and is explained thoroughly at the Futurama Intermediate Control Output support page. If needed also for Futurama Web API a customized XSLT can be used to transform the default FICO code to customized FICO code. See the Futurama Intermediate Control Output support page for more information how to use this xslt.

Consecutive requests

If a user wants to change something within the document, like entering a value, or navigating to a different page, some data must be sent back to the server. This action is called “a postback”. In case one of the controls caused a postback (for instance, clicking a button, or a textbox with autopostback="true", a parameter should be added in the Parameters list of the request, with name="__EVENTTARGET" and the id of the control that caused the postback as value. This will trigger any actions that might be associated with this control.

When a user in the website does these consecutive requests it is important to be sure the same session of the user is used. The SessionID parameter can be used to identify the session of the user. Besides this in order to protect users from Cross-Site Request Forgery attacks Request Validation Tokens are used. This security feature has been implemented within Futurama WebAPI and consists of the following procedure: whenever a page is returned by WebAPI, a random code (the 'token') is generated and attached to the response. If a following postback is done to Futurama Web API, the latest of these tokens must be entered in the request, otherwise the sent data will be ignored and an exception will be written to the log.

Session management

When Futurama WebAPI is used within an existing system with its own Sessions, a problem can occur when the Futurama WebAPI Session is timed-out because of lack of usage, while the other systems session still exists. To prevent the WebAPI Sessions from expiring, it’s possible to call a small web service that keeps the session alive. A similar functionality is offered to actually end a session before time-out. To read about using these web services, please view their documentation here: WebAPI Session management

File Resources

With the Web API interface that is specified above, all the required information to make a fully functional website out of a Futurama Web application can be obtained. However, to access files within the Futurama Web application, then the Web API hosting environment must allow direct access to these files, which is not desirable in a lot of cases. For this reason a separate function is created to retrieve these file resources using a Web Service. This way only the Web API services can be exposed by the webserver, and file access can still be maintained. For more information about this function, please view the following support page: Retrieving Resources using Web API


Above the general structure of the Futurama Web API request and response is given. In this paragraph some examples are given. A sample Futurama application can be used for these examples. Follow the next steps to install the sample Futurama application:

  • Download the zip-file with the sample Futurama application from this page;
  • Extract the contents of the zip-file;
  • Copy the folder "WebAPI" to the folder that contains the Futurama Webservice code (version 5.3.2 or higher)


Download files

Download example

The example is a simple Futurama Document. The document has one WebPage (i.e. the StartWebPage of the document). This WebPage contains two WebPanels. Each of these WebPanels has a WebLabel with some text. In the next couple of examples different requests are used to show some options of the Futurama Web API.

Request – example 1

The first example is a simple example where in the request only the Document name and the Folder name are provided.


Response example 1

Result of this request is one Panel containing the entire webpage as defined in the Futurama Editor.

                        This is the first WebPanel
                        This is the second WebPanel

Request – example 2

In the first example two WebPanels were visible (WebPanel with id="id3" and WebPanel with id="id4"). In this example in the request only the output of the first Webpanel is requested. This can be done by define the PanelID=3 in the request (i.e. the ID of the first WebPanel).


Response example 2

Now in the response only the output of the first WebPanel is shown.

                     This is the first WebPanel

Request – example 3

In this example the output of two Webpanels is requested by list the ID's of these WebPanels in the PanelID parameter.


Response example 3

Result of this request are two panels: one with the output of the first WebPanel and one with the output of the second WebPanel.

                     This is the first WebPanel
                     This is the second WebPanel

Futurama postbacks

See Postbacks of Futurama webcontrols for information how Futurama deals with postbacks. A special kind of postbacks are the partial postbacks (AJAX). With a partial postback only a part of the page is requested. In Futurama partial postbacks can be used by defined an UpdatePanel in the Properties Window of a webcontrol. See for example the properties for the Button. Whenever this happens, this will be rendered as the attribute 'updatePanel', where the value is the numerical id. The appropriate way in which these situations should be handled is by creating a new Futurama Web API request where the PanelIDs parameter is filled with only this panelID, and the ProcessFullPage parameter is set to 'false'. This will mimic the control flow as it was for Futurama Web partial postbacks.

Manipulating Futurama WebControls

The following controls can be directly manipulated by returning changed values to Futurama, just like a browser would by performing a form submit (postback). The manipulation of controls can be done by creating a Parameter within the request. Usually it is only needed to provide a parameter where the name is the controls client-id (the ID as it is rendered. E.g. id12 or id209sub0_217, etc), and the parameters value should be the new value. If a control is also the trigger for this postback, for instance, if it’s a button, or a dropdownlist with autopostback=’true’, then there must be a parameter with name=’__EVENTTARGET’, and value=”{the trigger control ID}”. See Postbacks of Futurama webcontrols for more context about the way Futurama deals with postbacks.


For a simple textbox with id=139, the parameter to change the value to “2888620” would look like this:



In order to manipulate a checkbox, a parameter must be created with its client-id as the name, and the value ‘on’ if it is to be checked, or any other value if the check is to be cleared, so ‘off’ would be a good counterpart. So checking a checkbox with id=20 would look like this:



In order to change the value of a DateBox, a value must be provided using the format {year}-{month}-{day}



In order to change the selected item of a DropDownListBox, you must provide the value of the item you want to have selected. So if the current selected index is 0, and therefore the first item is selected, when you create a parameter with value=1, the newly selected item will be the item where its value attribute is 1.



In order to change the selected radiobutton in a radiogroup, a parameter must be made with name={radioGroupID}, and its value must be the newly selected radiobuttons ID. So in the example below, the radiobutton with id=2015 will be the selected button within the group with id=2013.



If a button is pressed, it only needs to be marked as the Event-target in order to trigger its internal actions on submitting the request.
So a virtual click on a button with id=213 would look like this:



In order to change the position of a WebSlider, the client id must be appended with the text “_ClientState”, and the new value must be in the form of a JSON object with a property “value” and a value assigned to that property. So for the example below, the WebSlider with id=9921 will be set to a new value of 744:


State management

Each postback to Futurama will lead to a new state of the Futurama session. If you configure Futurama to enable history, you can retrieve historic states to enable the back (and forward) in the browser. If you want to support history functionality using Futurama WebAPI you can use the value of the StateID that is returned with each response, and pass that in a new request.

If you want to retrieve an historic state you need to fill ‘StateID’ with the ID of the State that you require. You also need to fill ‘PrevStateID’ with the state that was previously displayed. If a certain state was created with an Ajax postback (partial postback, ProcessFullPage=False), then you also need to retrieve the previous state with an Ajax postback (ProcessFullPage=False) for the same panel.

Here is a sample request to replace the content of panel with id ‘id6’ with the previous state.


Here is a sample request to replace the entire page with the previous state.


Here is a sample request to replace the entire page with the next state, so to go back to state 2 from state 1. You can use this when the user presses the forward button in the browser.




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

Updated: 2018-05-04