A simple approval process

Designing an approval process is vastly simplified in Workbench ES2. The ES User service has been deprecated and replaced with single/multi-user versions — specifically the Assign Task and Assign Multiple Tasks service operations. First I’ll take a look at the Assign Task operation.

The property sheet for Assign Task contains a few new property groups. The asset and action profile to be presented to the user are defined in the Presentation & Data section.


The User Actions section simplifies the configuration of user actions, which options are presented to the end user and what will happen when a specific option is selected.


You can even define a confirmation message to appear when an action is selected.


The Workspace User Interface contains an Approval Container option that enables features within Workspace that allow end users to see the review status and add comments. This is particularly useful with the Multi-user task when documents need to be reviewed by a number of different people.


Be aware that property sheets in Process Designer now contain a Basic/All filter. When Basic is selected (which it is by default), only the most commonly used property groups for that service operation are displayed.


Here again is my sample application that demonstrates pre-population of a form on process initiation as well as this simple approval process: LeaveRequest.lca


Data pre-population on initiating a process

Designing a process that pre-populates a form when the process is started is way simpler in ES2. This work is done in a separate process called a “prepare data process” and is managed by an “action profile”. In the next couple of posts I plan to use the LeaveRequest application as an example of new features in ES2 such as this.

If you right-click on the form in the LeaveRequest application, you’ll see the menu item: “Manage Action Profiles…”


In the Manage Action Profiles dialog, you can select an existing prepare data process or create a new one. If you create a new process, Workbench will create the process variables for you.


The prepare data process includes 2 variables: a taskContext input variable and an xml output variable. The output variable needs to be populated with the data that you want to show up when the main process is inititiated. In the provided example, take a look at the PersonalLeaveFormPrepareData process. The employee name is determined from the taskContext and assigned to a node in the xml. In addition, a couple of LDAP queries are made to gather further employee data, including the manager’s name. This data is also assigned to the xml output variable and will be used to pre-populate the form.


That simple! You’ll need to adjust the LDAP queries in order to have it work in your environment. Next up, I’ll explain the simple approval workflow in the main process of this example.


Sample – Dynamic Assembly of XDP Form

Let’s say you’re responsible for producing retail or service invoices for some company that has outlets all over the country. Every province and/or state has their own unique tax laws and your invoices need to accommodate the appropriate ones.   


   Sample Invoice for British Columbia        Sample Invoice for Newfoundland

Wouldn’t it be nice if your automated process could automatically drop in the right tax fields, complete with calculations, based on the province/state field of each record in the massive xml data file?

This sample demonstrates a new feature in LiveCycle ES2 – the ability to dynamically assemble an XDP template within a running process. It also demonstrates how to break up that massive xml data file and iterate through the records one at a time. While the LiveCycle Output service manages iterative loading intuitively, attempting a similar scenario with Assembler has unfortunately always been rather more, uh, challenging.

Dynamic Assembly is managed with what are called “insertion points” in the XDP file. If you open the SalesInvoice.xdp file in Designer, you’ll note that the Body.Total.Taxes subform has been defined as an insertion point.


This subform will be overwritten by one of the fragments contained in the TaxFrags.xdp file. How does the process know which fragment to throw in there, you ask? Well, the process gets the value of the province field from the data and feeds it to the Assembler Service. The magic happens in the DDX file, which looks like this:

<DDX xmlns=”http://ns.adobe.com/DDX/1.0/”>

  <XDP result=”finalform.xdp”>
    <XDP source=”invoice.xdp”>
      <!–  Assemble unique tax fragment from library –>
      <XDPContent insertionPoint=”TaxFields” source=”application:///InvoiceSample/1.0/Forms/Fragments/taxfrags.xdp” fragment=”inputmap:///province”/>

The fragment attribute in XDPContent maps to the value stored in the process variable. Give it a shot. Import the sample LCA file into your ES2 server. It will create an application called InvoiceSample. Open the AssembleInvoices process in Workbench. The annotation explains how to run the sample.

As I mentioned earlier, this sample also demonstrates how to break up the incoming xml file and iterate through the records. Since the XDP is bound to a schema, the individual data nodes need to match the schema in order for the data to show up in the rendered PDF. After using XPath to extract a single node, that node then needs to be re-wrapped in the original root element in order to again match the schema. This work is done in the “Extract single data record” operation of the process. The node is first serialized, then a concat() function is used to wrap string versions of the element at the front and back, and is finally deserialized.  If anyone know a better/simpler way to do this, I’m all ears.


Building actions in LiveCycle Designer

While we’re looking at LiveCycle Designer, here’s another great new tool that will help you avoid writing potentially long and tedious script. It’s called Action Builder and it’s pretty powerful. You can use it to define actions that will add or remove fields or sections of your form, set field values, change field or background colours, hide or show objects, or set focus to a specific field. All without writing any script by your yourself.

In this example, we want to either show or hide a bunch of credit card fields depending on the Payment option that was selected.


Assuming you have a form with these fields already on them, you would follow these steps (a link to the sample form is below):

  • Select Tools > Action Builder…
  • Click the “Add a new action” icon
  • actionbuilder1.jpg

  • Set the condition by selecting an object and a corresponding event. You can create multiple conditions with AND/OR operators. But for this example we’ll set only one condition for each action. For the first action, we want a result to be triggered when “Credit Card” has been selected by the end user.
  • Set one or more results. In this action we want a bunch of fields to become visible.
  • Create a second action. This time the condition will monitor for when the Credit Card option is NOT selected. When the condition is met, it will trigger several results that will make the fields invisible
  • actionbuilder2.png


    Action Builder creates what is called “managed script”. You can see this script in the Change event of the Payment field. You can, of course, edit this script – but it’s not recommended. And if Designer detects any modifications it will assume that you’re taking control and the script will become unmanaged.

    Here’s the sample pdf if you want to take a look: Registration.pdf


    New options for validation messages in Designer

    You’ve created this great form with tons of validations in the various fields to ensure the data that is typed into the field has the correct formatting.  Unfortunately, the default behaviour in Acrobat/Reader is to display each validation error separately, one after the other.


    You think this is not the best user experience so would like to change it so that all validation errors show up in a single message box.  Prior to Designer ES2 this was possible, but involved a considerable amount of script to get the desired behaviour.  But now all you have to do in Designer is select File > Form Properties > Form Validation and you’ll see this:


    Here you have several options for how you’d like these messages to show up.  You can even set colors for the fields that fail validation. If you select the option to combine all messages into one message box, as shown above, it will look like this:


    Nice eh?  And no need for any scripting. Note there is a limit to the number of messages that will show in a single box.

    LiveCycle ES2

    Yep. Lots of hype around the upcoming launch of LiveCycle ES2.  Don’t get me wrong – it’s a great product. Something that will allow you to throw around lots of action-oriented verbs concerning your documents. Verbs like building, empowering, collaborating, interacting. And you can do it all “in the cloud”. Which might sound rather vague or nebulous, but is really quite, uh, empowering.

    Great stuff.  But my goal in this blog is not to paint pretty pictures of LiveCycle ES2. You can go here for an overview of the product if you like. What I want to do is provide specific samples of how to build LiveCycle ES2 applications. How to use Designer to aggregate validations into a submit button (without writing any script!). Or how to dynamically assemble documents from a bunch of XDP fragments. That kind of stuff. Coming up soon…