Posts in Category "LiveCycle"

Flat PDF vs. XFA Form PDFs

A frequent mistake that is made is to assume that, since XFA Forms can be saved as PDFs, they will behave like any other PDF. Truth is: XFA PDFs and flat PDFs are entirely different beasts.

1) About PDF

“PDF” stands for Portable Document Format. Initially, PDFs were meant to be a digital counterpart to printable documents. You can open a PDF, and see the layout exactly as the page designer intended, with pictures and page breaks in the right places, ergonomic page margins, and most noticeably, with the original fancy fonts preserved. This is the original flat PDF.

Flat PDFs contain the page render data – a binary encoding of how the document should visually be drawn on screen or on paper (minus interactive items such as videos and flash animations).

PDF has come a long way since. It really has embraced the idea of “portable document,” the idea of the distribution of a published, polished document, and seeks to be all that printed documents could never be.

You can embed videos, flash animations and 3D spaces, protect them with encryption, limit their usage with DRM solutions (Adobe’s own is called LiveCycle Rights Management), annotate through comments and highlighting, measure elements, digitally sign them, make form fields to be filled in – and make forms that change according to the data inside them. Wow.

2) About forms – AcroForms

The first iteration of interactive form filling came as AcroForms.

At the most basic, an AcroForm is a flat PDF form that has some additional elements – the interactive fields – layered above the flat render, that allow users to enter information, and allow developers to extract data from.

You can create these using Adobe Acrobat, or any third-party PDF creation application that allows creation of PDF forms.

Flat PDFs can be annotated (comments, highlighting, and various other scribbles as desired), as these annotations can be mapped to an {x,y} location on the page.

Flat PDFs can have their pages extracted, as each page is already defined in the render.

Flat PDFs can be linearly optimized, for fast web viewing, which ensure that data for the first page all occurs before the data for the second page, in turn being before the data of the third page, and so on.

Such features are not available to XFA PDFs.

3) About forms – Dynamic XFA Forms

Dynamic forms are based on an XML specification known as XFA, the “XML Forms Architecture”. The information about the form (as far as PDF is concerned) is very vague – it specifies that fields exist, with properties, and JavaScript events, but does not specify any rendering. This allows them to redraw as much as necessary, with subforms repeating on the page, sections appearing and disappearing as appropriate, the ability to pull in form fragments stored in different files, and objects re-arranging as you (the developer) dictate.

This also means that some features of AcroForms and flat PDFs are lost.

XFA Foms cannot be annotated. Reader (or Acrobat) cannot know whether all your custom code may change the layout. As such, without any render data, and a chance that the render data may be drastically altered on the fly, local annotations cannot be implemented. An annotation only has sense at an {x,y} location, but if the item you are annotate changes location, your annotation becomes meaningless, if not misleading.

XFA Forms cannot have their pages extracted. There is no render data to determine pages. Change some data in the form, and the layout of the pages may change drastically. You must “flatten” the PDF before extracting pages, thereby losing interactive properties.

XFA Forms cannot be optimized for fast web viewing. There is no render information. Data at the end of the document may affect displays on the first page of the document.

4) Acrobat is not a word processor

A final common misconception is that you can edit pages in Acrobat as you could in Word. This is not the case. Acrobat focuses on the integrity of the layout – as such, if you have a page with 2 paragraphs, each 5 lines long, that is what Acrobat’s PDF engine will commit to showing.

The editing tools available are provided for minor cosmetic changes – nothing more. It is essential to keep the original documents – Word, PowerPoint, OpenOffice, TIFF or otherwise – for your editing process. Once converted to flat PDF, the intent is that the overall layout should never change.

For the same reason, XFA Forms are in conflict with Acrobat’s editing tools – the latter operate on the render layer, which does not exist in the saved XFA PDF. Such editing tools lose meaning faced with XFA Forms.

I hope this helps clear some of the confusions around what XFA PDFs can and cannot do in Acrobat and other PDF manipulation tools.

Updating a LiveCycle Process on a Live System

Recently I have been seeing reports of stalled / failed processes, both short-lived and long-lived. It turns out that in some cases, the process developers were updating processes on their live systems without taking due precautions. The following post is to explain what is actually happening under the hood, and why you can’t simply “hot change” a process.

A simple process

Imagine you have a process called MyNotify with two steps in it: a first task (not start point) AssignUser, and a second task SendEmail. Pretty straight forward.

You have deployed this process, and process instances are merrily being kicked off. Great. Now you realize that you don’t want the AssignUser task; rather, you want a Workspace Start Point. Remove the AssignUser task, configure the Workspace Start Point to open the same form as you had in the now deletd AssignUser task. Save and deploy.

You may now start getting calls from your users saying their form submission never resulted in an email. Upon investigating, you will likely find errors saying that “Job ID could not be found for Job […]”.

Oh no. What happened?

Tasks not found

Let’s wind back to where there were two steps. When a process instance is kicked off, what happens is that an entry in the database is made saying that process MyNotify has been kicked off by user “Alice” (for example), and it has been assigned to Alice, in the AssignUser task.

When Alice submits the form, LiveCycle goes to its database and checks the process – Alice just submitted the AssignUser step, so it checks MyNotify for an AssignUser step, and figures out what to do next from that.

If you have deleted the AssignUser task from MyNotify, LiveCycle will be unable to determine what to do next – and stall the process instance. Future instances should work fine (they are before the change point), anything that was at the SendEmail point in the process will be fine as well (they are after the change point). It is specifically process instances that are in a state that could be affected by the change that risk failure, and that will happen without possibility of roll-back or recuperation (bar performing some incantations in the database to recuperate the data, and then constructing some half-processes to mimick pre-change parts of the changed process, in the hope of pushing the data onwards — a lot of avoidable hassle, itself prone to failure).

Staying safe

It is understandable that you may think that if the process were modified, already-running processes would continue with the older version. This is not so, or at least, not in this scenario.

When kicking off a new process instance, LiveCycle does not automatically make a copy of the process to be followed should a new edit of the process come into existence. Maintaining a copy of all the configurations of a process for each instance created would cause extremely severe performance issues on the server, so a more de-coupled implementation serves best. The work of ensuring that a new copy of the process configuration is created is left up to the process developer.

Once a process is deployed, there are only two “safe” ways of updating the process.

Application Version

The first is to create a new Application version, and when all the new changes are made, deploy the new version.

  • All old instances will continue their course in the old version.
  • Workspace processes will kick off in the new version
  • Calls to the old version of the process will still call the old version

Once you have ascertained for sure that NO more processes from the old version are running, and that no applications rely on the old version, you can safely undeploy it from runtime, and delete it if you so wish.

When will references point to the new version automatically?

Having done this, all references to sub-processes inside the same application will be updated, as will all resources referenced relatively inside the application. For example, MyApplication/1.0/ProcessA can reference /FormA (in Assign User tasks for example) which means “the current application’s version’s FormA”. A sub-process on the process-workflow convas will be referenced relatively if the sub-process is contained inside the same application.

When do you need to update references manually?

Take special heed however — processes and resources that do not reside in the same Application do not see their references updated — they are absolutely referenced. If MyApplication/1.0/ProcessA is upgraded, it will not change the references to, for example, OtherApplication/1.0/OtherProcess. Similarly, if we upgrade to OtherApplication/2.0/OtherProcess, then MyApplication/1.0/ProcessA will still point to OtherApplication/1.0/OtherProcess.

Finally, note that if you create a new version of an application, all resources and processes are copied over with it with new version numbers too, and any textual references to other resources remain the same. So if MyNotify/1.0/ProcessA has a variable referencing MyNotify/1.0/FormA, then MyNotify/2.0/ProcessA will also reference MyNotify/1.0/FormA ; the same goes for resources uch as XDPs, XSLTs, and any other resources stored in an Application. The reason for this is that these references are stored as “strings” (pieces of text) and Workbench cannot, upon creating a new version, differentiate what snippets of text all through the Application are versions to update, what versions should not be updated, and what strings do not actually contain versions at all.

Down time (clean “brute force” update)

The other way is to plan downtime.

  • Prevent people from kicking off new processes
  • Let all processes complete
  • … and only then deploy the new edit of the process

You could choose the second method to avoid having to update references to resources, but it would defeat the purpose of having this versioning at all and does, unavoidably, incur the overhead of a downtime.