Avoka Blog: Adobe LiveCycle

June 30, 2008

Form Guide Rendering Explained

Filed under: Designing Forms, LiveCycle, LiveCycle Architecture — htreisman @ 4:05 pm

You probably already know that Form Guides are an exciting way to render an Adobe dynamic form via a Wizard-style interface. See this link for more details: http://help.adobe.com/en_US/livecycle/es/fggettingstarted.pdf

However, all this document says about how rendering a Form Guide works is:

“The process for rendering form guides is similar to the process used to render forms in PDF or HTML. You must create a new process in Workbench ES that uses the form guide rendering operation renderFormGuide.”

How does rendering a Form Guide really work?

The short answer is that it is similar to rendering a PDF. The longer answer is that there are some subtle differences, and these differences can have an impact on how you architect your solution. In particular, a Form Guide actually consists of three separate parts:

  1. An html page containing the Form Guide SWF file.
  2. Some Javascript libraries (mostly dealing with Browser Flash detection).
  3. The SWF file that is the Form Guide itself.

Each of these is loaded in a different interaction between the user’s browser, your custom servlet, a special LiveCycle servlet, and LiveCycle Forms itself.

The easiest way to explain this is via a sequence diagram:

Click For Full Size

(Click for larger image)

  1. HTML page
    1. The user clicks on the link to your Form Guide, sending a http request to your custom servlet.
    2. The servlet will invoke an orchestration defined in LiveCycle Workbench.
    3. The orchestration will obtain pre-population data if required (usually from some sort of database, using the logged-in user’s details)
    4. The orchestration will then invoke the LiveCycle Forms “render” operation, passing through the name of the XDP template, and the pre-population data.
    5. The render operation will return an html page. This page will contain some JavaScript references, and an <object> tag containing the SWF.
    6. The object tag will identify a uniquely named SWF file on the LiveCycle server
    7. The object tag will also include a “Flash Variable” embedded within the page – this Flash variable contains the pre-population data in an encoded form.
    8. The html page will be returned to the browser.
    9. Note: You could use Java code to directly invoke the LiveCycle Forms API, rather than using an orchestration.
  2. JavaScript
    1. The browser will identify the JavaScript libraries on the page, and request them from the LiveCycle server. Note that the request goes directly to JavaScript resources located within a web application on the LiveCycle server – your orchestration is not involved.
  3. Form Guide (SWF file)
    1. The browser will identify the object tag on the page.
    2. It will make a request to the LiveCycle server to obtain the object referenced in this page. This request goes directly to the LiveCycle supplied servlet, it does not involve your orchestration or custom code.
    3. The servlet will look at the unique object id specified, and will use this to locate the correct XDP template to turn into a SWF. (This is the same template that you specified when you called the “render” method.)
    4. The servlet will convert the XDP into MXML/ActionScript, and invoke the Flex compiler to generate the SWF file.
    5. It will then save the SWF file into the LiveCycle Forms cache. As long as the underlying XDP file doesn’t changed, (and assuming you don’t manually clear the cache), the servlet will serve up the SWF file from the cache from now on. This is because compiling the SWF file can be quite time-consuming.
    6. Finally, the SWF will be returned to the browser.
  4. Final display.
    1. The browser now has everything it needs to render the page. It will run the Javascript, and execute the SWF file, passing into it all the encoded pre-population data.
    2. Voila


  • In a clustered environment, it doesn’t matter whether #2 and #3 go to the same member of the cluster, or a different member of the cluster – what’s returned to the browser is always identical.
  • LiveCycle only needs to generate the SWF the first time, because it’s always identical. The pre-population data is embedded in the html file, which is generated each time the client requests a Form Guide, and may be different for each invocation.
  • You should manually load the Form Guide the first time you publish the Form Guide into production – otherwise the first user to load it will experience a longer than usual delay.

Things can get a little more complicated in a real production environment.

Click to View Larger

The second diagram indicates a more real-life environment, where:

  • An Apache server has been introduced which front-ends the Application Server. The end-user can only “see” the Apache server, and cannot directly access the custom servlet or the LiveCycle Forms application server. This is generally considered to be a more secure way to architect any public-facing web application.
  • A firewall has been introduced between the custom servlet, and the LiveCycle server. Another firewall is usually inserted between the Apache server and the custom servlet, although this is omitted from the diagram.
  • A variation on this architecture is that the custom servlet may run on the LiveCycle application server.
  • The LiveCycle server may run in either the DMZ or within the corporate zone, depending on it’s accessibility requirements to databases and other corporate resources.

This requires some modifications to the architecture of our application.

  1. When rendering the form using LiveCycle Forms “render”, you must specify the URL of the Apache server, rather than the URL of the LiveCycle server. This ensures that the client’s browser will interact with the Apache server, rather than attempting to communicate directly with the LiveCycle server.
  2. You must set up Apache to “pass-through” requests for both the custom servlet and the LiveCycle servlet.
  3. You must somehow allows requests to the LiveCycle servlet to pass from Apache through to the LiveCycle servlet on the LiveCycle server. There are a number of ways of doing this:
    1. If the Apache server can “see” the LiveCycle server, you can set up a proxy rule to allow traffic for the servlet to be passed through.
    2. You may need to write a simple proxy service within your custom servlet. This is basically a servlet with the same name as the LiveCycle servlet, which passes any requests through to the LiveCycle servlet, and forwards any responses back to the browser.

Thanks to Rak Siva of Avoka and Gareth Faulkner of Adobe for assistance with this blog.


Leave a Comment »

No comments yet.

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

Blog at WordPress.com.

%d bloggers like this: