Avoka Blog: Adobe LiveCycle

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

Blog at WordPress.com.