Description

This document will explain how to create a front-end plugin to access a Futurama back-end server using WebAPI

Introduction

In order to offer Futurama functionality within your application, we have created this development guide, in which we will try to assist you as much as possible. For this reason we have created a sample application in Visual Studio 2012, which you can use to recreate your own functionality.

Preparation

In order to develop a WebAPI front-end, the following requirements must be met:

• You should have access to a webserver with the Futurama Webservice installed on this server, which will function as the back-end. Its URL will from now on be referenced to as {FuturamaURL}.
• Place the folder with the Futurama application you wish to (re)use into the hosted webservice folder on the back-end server.
• WebAPI must be enabled in the web.config file. The required changes are documented here.
• (optional) Set the mapping section in the web.config to point to the desired folder/document like you would do within Futurama Website (see here).

The WebAPI's WSDL should now be accessible through the relative path {FuturamaURL}/WebAPIService.svc?wsdl on the back-end server.

The sample application

We have created a small sample application that can be examined using Microsoft Visual Studio 2012 or later, or possibly within a text editor. It contains a Basic page (BasicSample.ashx), and an Advanced page (AdvancedSample.ashx), which allows a degree of incremental understanding of the implementation method. The basic sample is able to connect to a back-end, and retrieve the default page (set in the back-end configuration). It loads a HTML form containing the entire page, and allows this form to be submitted, so that any changes actuates an update in the loaded document.

The WebAPI service

When the preparation phase has been completed, the back-end should be completely functional. Now it's up to you to create a functional front-end. First we will look at the webservice method 'GetPage' that will return the HTML code of a Futurama Page, which is accessed through the {FuturamaURL}/WebAPIService.svc URL. A typical request for this method looks like this:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.ActuIT.nl/Futurama/WebAPI/2014/10/" 
xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:ser="http://schemas.microsoft.com/2003/10/Serialization/">
	<soapenv:Header/>
	<soapenv:Body>
		<ns:Request>
			<ns:Document>website.xml</ns:Document>
			<ns:Folder>WebApi</ns:Folder>
			<ns:PanelIDs>
				<arr:string>id3</arr:string>
				<arr:string>id4</arr:string>
			</ns:PanelIDs>
			<ns:Parameters>
            <ns:Parameter>
               <ns:Name>__EVENTTARGET</ns:Name>
               <ns:Value>15</ns:Value>
            </ns:Parameter>
            <ns:Parameter>
               <ns:Name>__EVENTARGUMENT</ns:Name>
               <ns:Value>Hello world</ns:Value>
            </ns:Parameter>
         </ns:Parameters>
		</ns:Request>
	</soapenv:Body>
</soapenv:Envelope>

See for more detailed information about the type of requests possible this page.

Finally the returning data consists of a Response object, that contains the following fields:

• HtmlSource: The HTML source code of any rendered objects, wrapped within a generated form element.
• ScriptReferences: A list of script elements that need to be included within the front-end page in order to facilitate all functionality within the returned HTML code.
• Errors: A list of occurred error descriptions (if any).

Maintaining session

The Futurama document and objects that a user is retrieving and updating is maintained in a session object within the Back-end server. This is needed to maintain the current document state between user postbacks. By introducing a front-end between the users browser and the Futurama back-end this became a little more involved.

When the front-end calls the back-ends WebAPI service, it will return the requested data, but will also contain a cookie containing the SessionID for the back-end with the name 'ASP.NET_SessionId'. It is up to the front-end to maintain this sessionID/cookie for the current user, and re-use it for every returning call to that same document.

Using the WebAPI resource proxy

Because the WebAPI renders its Futurama objects to HTML code, it will often create elements that rely on external resources, such as an image element that links to a file located on the back-end server. However, the back-end server is not reachable from the clients browser, so the image cannot be retrieved, and a broken link will occur. The solution we developed works like this: In all the generated HTML, WebAPI searches for elements containing the 'src' attribute, and that link is checked whether it is a relative link. When this occurs, the link is replaced with a generated link that can be configured in the WebAPI configuration section on the back-end servers web.config file. This generated link will need to contain an encrypted resource identifier and a session ID. This allows the front-end proxy to contain an encrypted querystring, and should point to an address on the front-end server. It's up to the front-end developer to create a system at this address that can accept the request, and pass-on the encrypted querystring to the back-end address {FuturamaURL}/FutResource.ashx. The returning data contains the requested resource, and should be passed on back to the clients browser.

If the hosting environment for your application supports ASP.NET, we advise you to reuse the proxy.ashx file from the sample for your own purposes.

The generated link will also contain a 'sid' parameter, which contains the sessionID to re-use when calling the back-end. The created request for the resource should include a cookie containing the name 'ASP.NET_SessionId', and the sessionID as value.

The sample

The sample consists mainly of the following files:

• Service references: This contains the proxy that is able to communicate with the WebAPI webservice, and is generated out of the WSDL that is exposed from the WebAPI URL.
• index.html: A simple start page.
• Basic.ashx.cs: A simple HTTP handler that acts as a page, by reading a request, and returning HTML that includes the reponse from the configured Futurama (using the folder/document that is configured within the back-end web.config).
• Advanced.ashx.cs: A HTTP handler that contains the advanced sample. Here you can override the WebAPI request by defining folder, document and panelID's that need to be retrieved from the back-end.
• proxy.ashx.cs: The proxy HTTP handler that passes the Futurama Resource calls from the client to the back-end, and back again.

Feedback

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