Avoka Blog: Adobe LiveCycle

April 29, 2009

PDF and Flex Accessibility – part 1

Filed under: 1, Designing Forms, LiveCycle — Tags: , — pcopeland @ 7:57 am

The bottom line

Despite some misconceptions, PDF and Flex/Flash solutions can be highly accessible. However, it does not happen automagically. Project commitment is required to attain the desired level of accessibility. It is advocated that ITC professionals spend time to understand accessibility, regulatory compliance, the capabilities of Adobe technologies and apply the appropriate level of consideration in project planning. It is far more expensive to retro-fit changes, rescue a failed project or limit brand damage caused by building a solution that, for example, is unavailable to an important community of Mac users or is complained about in a public forum by a blind user. This blog is the first in a series that explores the, often misunderstood, field of accessibility. This introduces the basic concepts and sets the context for subsequent blogs which will cover the practical aspects of implementing accessible PDF and Flex solutions.

What is accessibility?

Accessibility can be considered the degree to which electronic services and products can be accessed by the largest number of users possible. Although, often focused on disabled people, this is relevent to all people, including those that are on slow broadband, using non mainstream operating systems, using a mobile device or speaking non native languages. Accessibility is closely related to the concept of usability. Usability can be considered the ease with which a specified group of people can use an electronic service or product.

Why should I care about accessibility?

Technological progress and the meteoric rise of the Internet continues to fuel the trend of delivering services and goods through electronic channels. As the trend progresses, the opportunities and responsibilities of accessibility increase. The three primary reasons to care about accessibility are:

  1. It is good for business – increase leads and convertion to sales
  2. It is good for society – provide access for more people to the benefits of technological advancement
  3. You have to – legislation has been passed around the world that mandates accessibility requirements

Accessibility and disability

Although, accessibility is often set in the context of totally blind people, there are different categories of disabilities with different accessibility requirements.

Types of disability

The major categories of disability types are:

Visual disability Visual Blindness, low vision, color-blindness
Hearingdisability Hearing Deafness
Motor disability Motor Inability to use a mouse, slow response time, limited fine motor control
Cognitive disability Cognitive Learning disabilities, distractibility, inability to remember or focus on large amounts of information

What is Assistive Technology?

Assistive technology refers to any product or software program that has been developed or modified to make it accessible for the disabled. Of the wide range of assistive technologies available, the most relevent to PDF and Flex solutions are screen readers, text-to-speech, screen magnifiers and braille output devices.

Screen Readers

Screen readers are software that interprets what is being displayed on screen and re-presents it as synthesised speech or on a Braille output device. According to the WebAIM Survey of Preferences of Screen Readers Users completed in January 2009, the top three screen readers being used by 1121 respondents were:

JAWS and Window-Eyes are commercial products that offer evaluation licences. NVDA is a free, open-source screen reader. Screen readers are highly configurable, complex software that is designed to enable the operation of a computer in ways that are very different from the traditional keyboard and mouse methods employed by fully sighted users. The WebAIM screen reader simulation tool is an interesting way for a fully sighted user to experience the use of screen readers. It is recommended that screen reader testing be performed by specialist users.

Text to Speech

Text to speech software re-present normal language text as an artificial production of human speech. This software is used by screen readers and can be used independently. Common programs include ReadPlease and NaturalReader.

Screen Magnifiers

Screen magnifiers are software that interface with a computer’s graphical output to present enlarged screen content for the partially sighted.

Braille output devices

Braille output devices re-present text as braille by raising pins through a flat surface in braille characters.

What is the web standard for accessibility?

Since 1999 the primary international standard for website accessibility has been the Web Content Accessibility Guidelines (WCAG) developed by the W3C. This has formed the basis for accessibility legislation around the world, including Section 508 in the US and the 2000 Government Online Strategy in Australia. In December 2008, the W3C released WCAG 2.0 recommendation. Version 2 is a significant update to its predecessor. WCAG 2.0 is build around four basic principles:

Perceivable Information and user interface components must be presentable to users in a way that they can perceive
Operable User interface components and navigation must be operable
Understandable Information and the operation of user interface must be understandable
Robust Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies

Each of these four principles contains a number of guidelines outlining how a website should meet all users’ needs. Within the guidelines there are a number of success criteria which outline how the web content should be developed to meet the guidelines. There are three levels of conformance within WCAG 2.0, A, AA and AAA (the highest level). In order to conform to WCAG 2.0, the web content must satisfy at least level all of the Level A success criteria. The diagram below shows the minimum success criteria that must all be satisfied for web content to conform to WCAG 2.0: WCAG 2.0 - Level A WCAG 2.0 introduces the notion of “Accessibility Supported” and the requirement that only “accessibility supported ways of using technologies” can be relied upon to satisfy the success criteria. As both Adobe Reader and Flash Player are free and generally available from the Adobe web site, PDF and Flex satisfy the first of the basic requirements for it to be considered “accessibility supported” under the standard:

  • Users of the web must be able to obtain user agents for the Web Content technology that are accessibility supported. The W3C suggests this can be achieved in one of four ways.
    • In its basic state the technology is accessible to common user agents – e.g. HTML is supported by browsers. OR
    • The technology is supported by an accessible plug in such as Flash that is generally available. OR
    • he content is to be used in a closed environment such as a university or corporate network, where the necessary accessibility supported technologies are supplied. OR
    • The user agent that allows the technology to be accessible is easy for a person with a disability to obtain and it doesn’t cost any more than it would for someone without a disability.

Developments in the Adobe Acrobat, Reader and Flash Player in partnership with assitive technology vendors results in PDF and Flex passing the second of the basic requirements:

  • The way a particular web content technology is used must be supported by the assistive technology, that is, if you use JavaScript or PDF, for example, you must do so in a way that allows the final product to be accessed by assistive devices like screen readers and switches.

The accessibility myth

It is a misconception that PDF and Flex solutions cannot be accessible. There are two primary reasons for this:

Many existing PDF and Flex solutions on the web are not highly accessible

This is either due to projects not investing in accessibility or, particularly in the case of PDF technology that has been around for a long time, and was developed prior to versions of Reader and Flash Player that do support accessibility. Although HTML supports accessibility, it is possible (even easy) to implement HTML web-sites that are horribly inaccessible. Just because HTML supports accessibility does not mean that all HTML sites are automatically accessible – it takes effort and care to achieve this. In the same way modern versions of Reader and Flash do support accessibility and it is possible to build PDF and Flash content that is accessible. It is up to PDF and Flash developers to learn about these features and implement them correctly.

A bias of the earlier standard WCAG 1.0 was towards W3C web technologies

WCAG 1.0 has been the W3C endorsed standard for nine years and is the referenced standard for accessibility legislation around the world. WCAG 1.0 is technology dependent; Guideline 11 of the standard has two checkpoints relating to what technologies are accessible:

  • Checkpoint 11.1 has priority 2 (should) and says to use W3C technologies
  • Checkpoint 11.4 has priority 1 (must) and says that if you cannot create an accessible page, then an alternate accessible page that uses W3C technologies must be provided

One of the key drivers to WCAG 2.0 was to become technology agnostic, thereby opening the standard to non-W3C technologies such as PDF and Flex.

Advertisements

March 1, 2009

What do the LiveCycle ‘Process Fields’ really do?

Background

In order to integrate a LiveCyc le PDF form into LiveCycle Process Management, you need to embed some special fields into your form.

The LiveCycle documentation does indicate what these fields are for, but doesn’t really explain exactly how they are used and populated.

Process Field Documentation Link

This blog entry explains how it all really works.

The Fields

The Process fields inside Designer look like this:

process-fields-in-designer

The scenarios

When integrating with Process Management, the form will be presented inside Workspace. There are a number of scenarios:

  1. A user is submitting a form within Workspace (either to initiate a process, or as an item in their To Do list)
  2. The user has taken an initialization form offline
  3. The user has taken a form from their inbox offline.

Submitting a form within Workspace

In fact, for this basic scenario, you don’t need the process fields at all. All you really need is a Submit button.

However, if you do use the process fields, you get a few extra capabilities, including user choices, and the option to take the form offline.

The field AWS_SUBMIT is a regular button that contains some Javascript code. This code, among other things, checks whether you’re running in an online (within Workspace) or offline mode. If you’re running online, it simply sends a “click” event to the real submit button, FSSUBMIT_ (which is a hidden http submit button).

Apart from the choice fields described below, none of the other fields are necessary – LiveCycle knows exactly who you are, and what you’re doing, because you’re logged into a live session in Workspace. It’s only when you take a form offline that the other fields are necessary.

Giving the user a choice

Sometimes you want to give your users a choice, which will affect the routes that are taken within the LiveCycle process. If you put a bit of text into the AWS_CHOICE text field, such as “Approve,Deny”, the Javascript code will:

  • Display the Action dropdown (if there are no choices, it will be hidden)
  • Populate the Action dropdown with the values from the AWS_CHOICE field.

It will look something like this:

approvedeny

You can put your own comma-separated text into AWS_CHOICE, but LiveCycle will automatically do a whole bunch of useful things for you.

  • When you create a User Assign Task step in your workflow, check the checkbox that says “Populate Form with Routes”. LiveCycle will then look at all the route names coming out of your User step, and populate AWS_CHOICE with the route names.
  • When the user submits the form, LiveCycle will interrogate the value of the Action dropdown, and automatically route the process down the selected route.

Note: If you choose not to use this option, you can simply create rules in your routes that interrogate other data within your form to decide which route to follow.

Note: Certain route names are associated with special icons in Workspace. These are “Approve” and “Reject” (or maybe “Deny”, I forget.) You can configure these special icons and their associated routenames from Adminui.

Taking a form offline.

Once you take a form offline, it is “disconnected” from Workspace. You can fill it in, and when you click the Submit button, it will be submitted via email, rather than over the web. The AWS_Submit button has logic to determine whether you’re online or offline, and submit either via the web or via email.

If you’re submitting via email, the form needs to know what email address to submit it to. This email address is automatically populated by LiveCycle into the AWS_MAILTO field when you take the form offline. Like all the other fields, there’s no real magic – you can set the field to an email address manually or in code if you want to, but generally it’s easier and safer to let the LiveCycle server take care of this for you.

Note: In order to allow offline submissions, you need to set up a email box, and configure LiveCycle to monitor this email box. That’s the subject of another blog sometime. Email info-at-avoka.com if you’re having trouble.

When you submit your form data via email, LiveCycle no longer knows anything about you, or why you’re submitting the form. It simply knows that an email arrived in an inbox containing some XML as an attachment. So…

When you take the form offline, LiveCycle injects some data into a few fields:

  • When you take an initialization form offline, the LiveCycle server will populate AWS_PROCESSTYPE with the name of the process that should be initiated when you submit the form. When you submit the form via email, LiveCycle will start the named process on your behalf, using the data from the email attachment.
  • When you take a form in your inbox offline, the LiveCycle server will populate AWS_TASKID with the id of the task that this relates to. When the submit the form via email, LiveCycle will complete that task on your behalf.
  • In both cases, LiveCycle will use the email address of the sender of the email of the email to determine who the “completer” was. Warning: make sure you send from an email associated with your LiveCycle identity – if LiveCycle doesn’t recognize the sender, it will treat the email as spam, and silently discard the incoming email. (I haven’t verified this lately, but it used to work this way.)
  • In both cases, the LiveCycle server will populate the AWS_ASSIGNEDID with the internal LiveCycle ID of the user who was originally assigned this form. I have no idea whether this is used for anything, or why it might be useful to either you or LiveCycle.
  • Finally, once you submit via email, Reader will set the AWS_STATUS field from ” ” to “Submitted”. Once this field has the “Submitted” value, you will not be able to submit the form again. This simply prevents duplicate submissions being accidentally emailed.

Summary

While there’s quite a bit of logic associated with these fields, both within the form and with the LiveCycle server, you don’t really need to know how it all works. Just drop the fields into your form, and LiveCycle takes care of the rest. It is helpful, however, to know how this works, so that you can tweak the behaviour if necessary.

January 12, 2009

Populating a drop-down using XML and Dynamic Binding

Filed under: Designing Forms, LiveCycle Forms — htreisman @ 8:45 pm

In one of our previous blogs, we mentioned several techniques for populating a drop-down list with data. In this posting, we’re going to use a technique called “Dynamic Binding”. We’re going to use an XML file to populate the drop-down, as well as for populating a repeating lists of questions.

The form we’re going to develop is a general purpose survey form, where both the list of questions, and the answers allowed, are pre-populated with XML. Since Designer only supports a single XML file, we’re going to store the drop-down values, the questions, and the answers that the end-user selects, all in the same XML file.

The Sample PDF is here: dynamic_survey_with_embedded_data. Try it out before you start the exercise, so you can see what we’ll end up achieving.

Note:

  • You can just open this file in Reader to try it out
  • You can open it in Designer to see how it works
  • The PDF has two attachments, the XML schema and a sample XML file. Click on the paper-clip icon to get at these.

It also contains the sample XML and schema files as embedded attachments.

Step 1: create the schema

Schema

Note that “Question” and “ResponseItem” are repeating, with a cardinality of 1..*. “Questions” will be used to populate the list of questions dynamically. “ResponseItems” will be used to populate the drop-down list containing the user’s responses.

Step 2: Create a simple form

You must save it as a Dynamic PDF form, because it’s going to grow based on the data we put into it. Also, because we’re going to grow the number of questions based on the data in the XML file, we need to use a Flowed rather than Positioned layout.

Form Design

Note that the table has only one row (set to “repeating” on the binding tab), and a DropDown list with no values specified.

Step 3: Add the schema to the form

data_connection

Add the schema to the form by defining a new data connection. Embedding the schema is optional, but useful if you’re ever going to use this form within a LiveCycle process.

Step 4: Create the XML file

Make sure it conforms to your schema. Here’s a snippet:

xml

Step 5:Turn on Dynamic Binding

This is available from the drop-down menu of the Object palette in Designer.

Dynamic Properties

Step 6: Bind the schema elements to the form objects

Use the Binding sub-tab of the Object palette.

  • Bind Row1 to the Question[*] repeating group – this will ensure that for every row of Question data in the XML, we’ll get a new Row1 in the form.
  • Bind the Question and Answer fields to the sub-elements of the repeating group. Note that you use relative binding, because the repeating element is already bound to Row1.

Step 7: Dynamic Binding

Bind the drop-down’s values and labels to the elements defined in the schema. Click on the green “Specify Item Values” link, and in the Dynamic properties dialog, enter the repeating element, and the sub-items containing the text (the values displayed) and value (the values stored in the data). This is summarized in the screenshot below:

drop_down_bindings

If you don’t see the green link, revisit Step 5.

Step 8: Preview the form

In Designer, set the “Data File” to point to your sample xml file.

preview_data

Click on the Preview tab. You should see something like this:

final_form

Try changing the data in the sample XML file (for example, adding “No opinion” to the drop-down data, or a new question), and then preview again. You should see the new question and drop-down items appear.

Finally

You can embed the XML data into the form manually using Acrobat or automate it on the server via LiveCycle Forms or Process Management. Using a LiveCycle orchestration, you could of course generate the XML using a database query or some other source.

If you’d like more information on how to do this, please contact info@avoka.com

November 8, 2008

Creating a Read-only copy of a form

Filed under: Designing Forms, Designing Processes, LiveCycle — htreisman @ 2:27 pm

Overview

Very often, as part of a process, you’ll want to create a read-only copy of a form, and store it somewhere, or email it to someone. There are various ways of achieving this, and they vary in different ways.

Making the fields read-only

It’s possible to make all the fields in the form read-only, using some Javascript coding. This is fairly straight forward, and looks something like:

TextField1.access="readOnly"

If you have a few fields on your form, you can just do this for each field. If you have a lot of fields, you’ll probably want to write this as a recursive function, and do all fields in a single function call. This can be quite fiddly, because you need to correctly handle all the different types of form objects. (Avoka can help with this – contact info-at-avoka.com for assistance.)

Pros
  • Inexpensive

Cons

  • Can be fiddly to program
  • While this makes the form appear to be read only, a clever end-user could still modify it. To modify it, open the form in Acrobat, use Forms/Manage Form Data…/Export Data… to export the data as XML, modify the XML, and then re-import the XML data using Forms/Manage Form Data…/Import Data… The form data will have changed, and nobody is any the wiser.

“Flattening” the form

Adobe have a server product called LiveCycle Output. One of the things that LC Output will do is “flatten” a form – that means that it will be converted from an editable type of PDF document to a more traditional “read-only” document. The fields are no longer editable fields, they are really now just boxes and text drawn onto the page.

Pros

  • This is much more secure than setting fields to read only. The XML data no longer exists, and cannot be modified.
  • No JavaScript programming required to achieve this – simply route your form to LiveCycle Output, and generate the flattened PDF.

Cons

  • It’s still possible to modify the PDF file to change what appears on the form. This is much harder, because the PDF is now in a binary format, but it’s possible.
  • Requires server-side integration
  • Requires purchasing LiveCycle Output (but LC Output does other useful things, so this may really be an overall benefit to your organization).

Digitally Signing the Document

Digitally signing the document doesn’t actually prevent the document from being modified, so needs to be used in conjunction with one of the above techniques. However, it does take a “snapshot” of the document, and if any changes are made, the signature will be invalidated. This enables you to guarantee that the version of the file you saved has not been modified since it was produced.

Pros

  • Guarantees that the PDF has not been modified since it was saved.

Cons

  • If signing is performed directly by the client, it requires Adobe Acrobat (or Reader Extensions)
  • If signing is performed on the server, then you must purchase a copy of LiveCycle Digital Signatures, and integrate this into your process.

Summary

There are several different techniques for making a form read-only. The one to use depends primarily on how willing you are to accept the risk of the document being changed (accidentally or maliciously) after it’s been produced, and how much you are willing to spend to achieve the level of protection you want.

October 31, 2008

What is Reader Extensions?

Filed under: Designing Forms, LiveCycle, LiveCycle Architecture — htreisman @ 9:44 am

Adobe have two products for dealing with PDF files:

  • Adobe Acrobat – mainly for creating new PDF files, in many different ways.
  • Adobe Reader – mainly for reading existing PDF files. Can also be used to fill in forms. Reader is free.

There are some additional limitations in Reader. In particular, when you fill in a form, there are several things that you can ONLY do if the form is opened in Acrobat, and will not work in Reader. These include:

  • Saving a copy of the form with the form data embedded in it. (This is considered to be creating a “new” form, which can only be done in Acrobat.)
  • Submitting the form as PDF. (Again, this is considered to be creating a new PDF.) Submitting as XML is always possible in both Reader and Acrobat.
  • Digitally signing the form. (Again, this is considered to be creating a new version of the form.)
  • Adding comments or annotations. (Ditto.)
  • Invoking web services directly from the form.

So what do you do if you’ve created a PDF Form, and you want to publish it on your web site, and want your users to be able to do any of the above?

Enter Reader Extensions! Tadaaah!

Reader Extensions allows you to apply a special “tag” to a PDF document. When that document is opened in Reader, all the features listed above will miraculously be available (just for that one document).

There are two ways to apply Reader Extensions to your document:

  1. Purchase a Reader Extensions certificate for your document from Adobe (<plug>through one of Adobe’s authorized partners, such as Avoka </plug>) You will need to install Adobe LiveCycle on one of your servers to actually apply the certificate to your document – but once the certificate has been applied, you don’t need to use the server any more. (Although you do get LiveCycle Foundation with Reader Extensions – so you have a server with a whole lot of really useful features.)
  2. Use the limited-use, cut-down version of Reader Extensions available in Acrobat. This only enables a subset of the capabilites above, and is limited to a maximum of 500 recipients. In Acrobat, use Forms/Distribute Form…

For more information about Reader Extensions, see:

http://www.avoka.com/ad_livecycle_es/reader_extensions_es.shtml

If you’re interesting in more information, or purchasing Reader Extensions, please email sales-at-avoka.com

October 30, 2008

Submitting from a form in PDF Format

Filed under: Designing Forms, LiveCycle — htreisman @ 3:21 pm

When you put a Submit button on a form, you can select either XML or PDF format (as well as some others that we’ll ignore for now.)

  • XML format contains only the data from your form, in XML format.
  • PDF format contains a copy of the form being filled in, as a PDF file.

Submitting as XML always works. However, submitting as PDF may or may not work. Here’s what happens:

  • If you open the form in Acrobat, it will submit correctly as PDF.
  • If you open the form in Reader, it will silently fail when you try to submit. (There will be no warning or error messages – it just doesn’t appear to work. This will not impress your customers 🙂 )

The reason for this is that only Acrobat can create a “new” PDF file; Reader is only for reading existing files. Since you’ve typed new information into the fields on your form, submitting as PDF would effectively create a “new” PDF file and is not allowed in Reader.

You have a number of options for resolving this problem:

  1. Ensure that everyone filling the form has Acrobat rather than Reader. (Difficult to do if this is a public form.)
  2. Buy an Adobe product called LiveCycle Reader Extensions for your form – this will allow you to “extend” the capabilities of Reader to allow it to send the completed form as PDF.
  3. If there are fewer than 500 recipients of your form, there is a limited version of Reader Extensions built into Acrobat. You simply need to convert the form after saving it. Open it in Acrobat, use Forms/Distribute… and select Save for later.
  4. Change from PDF submission to XML. You will either need to:
  • Teach the recipient of the XML how to import the XML data back into a blank copy of the form. Open the original blank form in Acrobat, select Forms/Manage Form Data…/Import Data…
  • Use Adobe LiveCycle on the server (LiveCycle Forms or LiveCycle Output is the product you’ll need) to merge the XML data back into the original blank PDF template.

    For more details on Reader Extensions, check this out:

    What is Reader Extensions?

    If you’d like any further information about Reader Extensions or anything else in this blog post, please contact info-at-avoka.com

    July 30, 2008

    A fix for some cosmetic differences between Reader 8 and 9

    Filed under: Designing Forms, LiveCycle — htreisman @ 5:07 pm

    When Reader 9 starts up, by default it clicks the “Highlight Fields” toggle button. In Reader 8, this was unchecked by default.

    In general, this is a good thing. It makes it much more obvious to end-users which documents are fillable/editable PDFs, and which are plain PDFs that can only be printed.

    However, in some cases, where your user-base is already expecting fillable forms, this means that all your carefully color-coordinated forms now don’t look as good on startup.

    Another issue is when you have required fields, which show up with red borders – apart from looking a bit garish, our usability testing has indicated that it can make new users freak out, thinking they’ve already made a mistake before they’ve even done anything.

    This is compounded if you have fields with caption above the field, which in Reader 9 is rendering as two red borders, as shown here:

    There is a very simple way to preserve the Reader 8 behavior – simply add the following line to the root node of your form:

    On Initialize
    app.runtimeHighlight = false;

    This has been tested in Reader 8.1 and Reader 9.

    Note: In Reader 9 the “Highlight Fields” seems as it is clicked even though this line of code deactivate it. Therefore, If you want to click it to highlight the fields you have to click it twice for the first time (1.Deactivate 2. Activate).

    Thanks to Mohammad Al-omari for coming up with this code.

    Avoka has a LiveCycle Forms JavaScript library that allows you to handle validation errors in a more graceful way, as well as providing a whole lot of other useful utility functions that makes building forms easier, quicker, and more effective. If you’re interested in more information about this library, please email info(at)avoka.com.

    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

    Notes:

    • 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.

    June 19, 2008

    Best practise for pre-populating a Drop Down with data?

    Filed under: Designing Forms, Designing Processes, LiveCycle — htreisman @ 1:53 pm

    One of our internal consultants recently asked: “What is best practice for populating a Drop Down list in a PDF form with data?”

    There are several ways to do it, and there is no “best” or “recommended” way. The suggestions below are roughly in order of complexity.

    1. You can just hard code the values in the form template.
    2. You can populate a hidden field with comma-separated data, and use JavaScript to split the items and add them to the drop down. (If you use a comma separator, make sure that your data doesn’t have any commas in it).
    3. You can bind a Drop Down directly to element in your form’s XML, using a feature called Dynamic Properties (in Designer). Then, instead of populating a hidden field, you just populate elements directly into your XML. No javascript required, but a bit more work in your XML Schema.
    4. You can have your form calling a web service in order to get the data it needs, and use Javascript to process the results, and populate the Drop Down. You can build the web service any way you like, including as a LiveCycle orchestration. This is often the only way to approach things if the contents of the drop down depends on other data in your form.

    For #2 and #3, you can modify the LiveCycle Default Render process to inject the data into your XML.

    The screenshot below shows how to turn on “Dynamic Properties” in Designer.

    Dynamic Properties in LiveCycle Designer

    If anyone reading this blog needs more information on exactly how to do this, email info-at-avoka.com

    April 14, 2008

    How Can You Interface a PDF Form to a Third-party Application?

    Filed under: Designing Forms, LiveCycle — htreisman @ 9:36 am

    A customer new to LiveCycle recently asked for some technical information regarding the requirements of SmartForms for interfacing to a third party application.

    Unfortunately (or perhaps fortunately), there are several ways of interfacing Smart forms to a third party application – the technique you choose depends on a number of factors, including exactly what you’re trying to achieve, and the capabilities of the application.

    I’ll try to go through some of them:

    1. You can submit the data from a Smart Form directly into your application, via http or https (This is similar to if you submitted an html form to the same application). In order to do this, the application must already define some web-based interfaces using http POST requests. It’s quite straightforward to create a button in a form that invokes an http POST.

    2. You can submit the data directly from the form to the application via web services (ie SOAP). Again, in this case, the application must already expose the appropriate web services. Alternately, you could write (using the tool of your choice), a web-service front-end to the application. Calling a web-service from within a form is reasonably straight-forward, since a form can simply import the WSDL (web services definition language). There are some limitations:

    • Some types of web services are not supported by Reader
    • Some complex WSDL definitions may exceed the capability of Reader to invoke them easily. (You can drop down to Javascript code, but this is quite a lot more difficult.)
    • There are some issues with secure web services, and with authenticating proxies.
    • It is quite fiddly to change the destination of the web service. For example, if you have two different web services, one for testing, and the other for production, it generally requires the two versions of the form, each pointing to a different destination.

    3. You can submit the data directly from the form to the application via the sending of an email. It’s quite easy to create a button in a form that will send either the form’s data, or the full form, as an attachment. Obviously, again, the application will have to poll a particular mailbox server, and process the data that arrives.

    4. You can submit the data from the form using any of the above methods (http/SOAP/email) to an intermediate web application, which you build. The web application can optionally process the data, and then invoke the third-party application. You can build the intermediate application in whatever language/platform you like.

    5. You can submit the data from the form using http/SOAP/email to the LiveCycle orchestration engine. You can then use any of the capabilities of the LiveCycle engine to process or manipulate the data, and then submit it to the third-party application. In order to communicate with the third-party application, you can either use one of the “out of the box” capabilities of the orchestration engine (eg database access, messaging, file system, web services, and many more), or you can create a custom component for this purpose.

    The final option is by far the most powerful, as well as possibly being the simplest to modify if requirements change. You will need LiveCycle Foundation, however, this is an “almost free” product, that Adobe bundles with just about every LiveCycle product that it sells. LiveCycle Foundation gives you a rich graphical flowchart-like environment for defining exactly what should happen when the data from your form is submitted, and a wide variety of ways of integrating with your third-party application. A full discussion is beyond the scope of this short blog, but it is very powerful and easy. Please see Adobe’s web site for more details.

    Avoka provide an add-on component for invoking a LiveCycle process directly as a http or https request from a form. Please see our web site at: http://avoka.dnsalias.com/confluence/display/Public/Avoka+Process+Invoker
    for details.

    Another type of integration with a form is populating the form with data from the application – we’ll get to this another time.

    Create a free website or blog at WordPress.com.