Search

 

User: Developer

Prerequisites

  • Futurama Editor
  • Web services

Introduction

Describes the method in which Futurama documents can be accessed through the new WebAPI

 

Description

In order to let computer systems interact with a Futurama Document we started development of our new WebAPI feature, which consists of a WebService that can manipulate and display Futurama WebControls. This will allow custom front-end user interface applications to be created, that in turn communicate with Futurama as a back-end.

The way a Futurama Document is manipulated through and navigated through using Futurama WebAPI mimics the way it would have been should it be loaded in Futurama Web. It can be characterized as follows:

  • A request is made to WebAPI for the default WebPage.
  • The Webpage containing various controls is rendered, and returned in a response message.
  • One of the controls found in the response is going to be manipulated, so a new request is constructed with a parameter that indicates that the control with the found ID will be assigned a new value.
    Another found control (like a button, or autopostback textbox) will be given along in another parameter, but not with a new value, but marked as “eventtarget”.
  • The new request will cause various events within Futurama to change the value, and trigger actions found in the eventtarget-control, and the resulting page will be rendered and returned in a response message.
  • This response message contains a sessionID value that can be re-used for consecutive requests, so that the same objects will be manipulated, instead of a resetting the document every single request.

Configuration

To configure WebAPI, the following changes must be made in the web.config file of an application:
A configurationsection must be specified in the sectiongroup “futuramaSettings”:


  
    
... ...

This allows the inclusion of the setting specified below:


  
...

The attributes within this section have the following meaning:

  • enabled: This is a Boolean value indicating whether WebAPI is enabled. The default value is “false”.
  • includeExceptionDetails: This Boolean value dictates whether any errors are summarized, or explained in greater detail.

WebAPI Message format

The messages that are exchanged between the WebAPI are SOAP requests and responses. Within the body element of a SOAP request and response, it will contain a number of fields that are specified below.

To discover the format of these messages, you can access the WSDL by calling the following URL as soon as you have a running FICO-enabled Futurama Webservice installation:

http://{hostname}/{applicationpath}/WebAPIService.svc?wsdl

Request

The request object can contain a number of fields that are all optional. Should a request be made without providing any fields, the Futurama WebService will look for the default document that can be configured in the mapping section of the web.config, and load the start page that happens to be defined in that documents root node.
  • Document: This field contains the document name. This can also be configured in the Futurama mapping element specified in web.config. Usually this field is filled with the value ‘calc.xml’ or ‘website.xml’.
  • Folder: This field contains 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.
  • 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 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).
  • Prefix: The prefix field is a feature used in case of multiple parallel WebAPI calls, which would generate Futurama Client-IDs in the form of “id{prefix}{number}”.

    • ProcessFullPage: This field should indicate whether the full page should be processed, or only a requested panel, and is set to “true” when omitted. 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”.
    • RequestValidationToken (From Futurama 6.0+): This field needs to be used for posting back changes to the document. See the part about RequestVerificationTokens below in the Postbacks segment.
    • 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.

    Postbacks

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

    Response

    The response object has the following fields:

    • Panels: The panels object will hold a list of Elements that contains the requested WebPage or WebPanels rendered in the FICO notation. The format of this language will be explained below.
    • Errors: If any errors occur during the execution of the Futurama Engine in regard to the WebAPI request, the errors will be shown here. If no errors occur, this field will be omitted.
    • SessionID: The document will be loaded into a user-session, and the unique identifier will be returned to the client. Should the request have provided a sessionID to continue, then this value should be identical to the one provided in the earlier request object.

    Example

    An example request and response is shown below.

    Request

    
    	
    	
    		
    			calc.xml
    			VVR
    			
    				
    				
    					id139
    					425741
    				
    				
    				
    					__EVENTTARGET
    					id2140
    				
    			
    			5664686552 (From Futurama 6.0+)
    			7288db71-5efb-46f7-a2ca-fcf26fb3c036
    		
    	
    

    Response

    The response to the request above for a typical planner will be shown here. All elements that represent the WebControls with XML namespace "http://www.actuit.nl/futurama/concept" is specified in the FICO format, which can be read about here.

    
    	
    		
    			        
    			
    				
    					
    						<script language="JavaScript" type="text/javascript" src="/portals/0/MyPlanner/scripts/qtip_library.js"></script>
    						
    							
    							
    								
    									
    										Enter ID:
    									
    									
    										Please enter the unique identifying number for the participant
    										425741
    									
    								
    							
    						
    						<script language="JavaScript" type="text/javascript" src="/portals/0/MyPlanner/scripts/qtip_call.js"></script>
    					
    				
    			
    			
    			1245541254 (From Futurama 6.0+)
    			7288db71-5efb-46f7-a2ca-fcf26fb3c036			
    			0
    		
    	
    

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

  • 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.
  • 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.
  • 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.
  • SessionID: This contains the ID of the current user-session.
  • WindowIndex: This value indicates which virtual window has been opened within Futurama, and its only purpose is when a button is called which has a buttontype set to NewWindow or NewThread.

Request validation tokens (Futurama 6.0+)

In order to protect users from Cross-Site Request Forgery attacks, Futurama Web now employs a system called Request Validation Tokens. This security feature has also 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 to be be allowed by Futurama WebAPI, 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.

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

TextBox

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

    id139
    2888620

CheckBox

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:


  id20
  on

DateBox

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


  id20
  2013-10-09

DropDownListBox

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.


  id9377sub0_9387
  15

RadioButton/Group

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.


  id2013
  id2015

Button

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:


  __EVENTTARGET
  id213

WebSlider

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:


  id9921_ClientState
  {"value":744}

FileUploader

FileUploader is currently not supported yet as a postback capable control, as it would require the uploading of a file through a parallel stream or extra XML parameter. If you have a suggestion regarding the implementation of this control, we urge you to contact us with your thoughts.
It is important that in order to render a panel that contains a fileuploader, one must make sure that the web.config contains the appsetting with name “wcf:serviceHostingEnvironment:useClassicReadEntityBodyMode” and value “true”.

UpdatePanels (partial postbacks)

It's also possible that a webcontrol has its UpdatePanel property set. 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 WebAPI 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 (AJAX).

Using REST and JSON to access WebAPI

All directions above are based on the SOAP-Webservice, using XML as the messageformat language. From WebAPI release 4 on, a connection using REST can also be used, by observing the following differences:

First of all, the request must be made to a different URL, namely the following:

http://{hostname}/{applicationpath}/WebAPIServiceRest.svc/PostPage/

Request

A HTTPPost method must be used to access this URL, using a JSON interpretation of the Request object described above, which would look similar to this:

{
"Document":"calc.xml",
"Folder":"MyPlanner", 
"PanelIDs": [9303],
"Parameters": [{
		"Name": "__EVENTTARGET",
		"Value": "id9341"
	}],
"ProcessFullPage": false,
"SessionID":"5cd78fbc-ac71-471d-b8b7-1c59825ea719"
}

Response

The response will also be a JSON interpretation of the response described above.Normally the response would contain a "Panels" collection, containing XML elements with FICO rendering. It is however possible to let the webAPI convert the generated FICO into another language by using an XSL tranformation, for instance to transform the XML into JSON. This is explained in the FICO documentation in the section "XSL transformation". A very good method of transforming XML to JSON is by using the XSL file from http://www.JSONML.org.

Should an XSLT be used to output transformed data instead of the usual FICO markup, then the results for this code will be placed in the PanelsJSON collection, instead of the normal Panels collection.

An example of the response following the request above would look like this:

{
   "PanelsJSON": ["{/* this section contains the rendering of the webpanel with id=id9303 */ }"],
   "SessionID": "5cd78fbc-ac71-471d-b8b7-1c59825ea719"
}

The PanelsJSON property contains a string with the rendered output. Should this actually consist of JSON code, it can be converted to javascript objects by using the JSON.Parse() method.

Web.Config alterations for WebAPI release 4 on

Because of the new address for using REST, some changes must also be made to the web.config file to support this webservice. They are illustrated below:


	
		
			
		
		
	
	
		
			
				
				
			
			
		
		
			
				
			
		
	

 

Related Topics

- Futurama Intermediate Control Output (FICO): This document will elaborate the FICO schema.

Feedback

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

Updated: 2016-07-12