Avoka Blog: Adobe LiveCycle

April 7, 2009

Processes, Orchestrations, Services, and other confusing terminology

Filed under: Components, Designing Processes, LiveCycle, LiveCycle Architecture — htreisman @ 11:47 am

Introduction

There are a number of different terms used in Adobe LiveCycle Process Management, including process, orchestration, workflow, service, and component. These can be confusing.

Part of the reason for the proliferation of terminology is the history of the Process Management product and industry trends, and this blog entry tries to provide this perspective. This is my understanding of how these terms fit together, and should not be regarded as a definitive explanation.

If you don’t care about the historical perspective, skip to the end for a summary.

Workflow

The first version of Process Management was called “Adobe Workflow”. And the things you created were called “Workflows”. Even today, many people will generically refer to any combination of boxes and lines that you create in Workbench as a “workflow”.

However, the term workflow was used primarily in the 80’s and 90’s to refer to more traditional image storing and routing applications, and doesn’t really adequately describe the much more useful data-oriented and integration capabilities of LiveCycle. In the 2000’s, the terms BPM or Business Process Management started to become more widely used, not just as a technology, but also as a way of thinking about and improving your business. Various BPM disciplines evolved, including Six Sigma, Lean, and others. LiveCycle fits in much more closely with BPM than it does with the older imaging-oriented workflow systems, so…

Adobe Workflow became LiveCycle Process Management, and Workflow was replaced with …

Process

A Process is no different to a workflow, really, it’s just a term that better reflects the data-orientation and integration capabilities of the LiveCycle platform.

In LiveCycle, a process is almost always associated with a Form, and a series of human interactions that allow people to interact with the form and its data. There are almost always integration steps as well, such as pre-filling the form, writing to a database, adding a digital signature, sending emails, etc. These are also known as “long lived processes”, because they involve people interating with the form over a period of days or weeks.

Long lived process have a unique process-id, have every step recorded and audited, can be re-tried if any step fails, and can be viewed and managed through the Adminui interface.

Orchestration

In LiveCycle ES, we started seeing an increasing number of processes that are short-lived, and don’t include human steps. An example is the Default Render Process in LiveCycle ES. These processes used to be written as Java code in LiveCycle 7 – in ES, they have the advantage that being processes, we end-users can see and modify them very easily. It’s really just visual drag-and-drop programming. You can also easily build your own orchestrations to do something useful – for example, you may want to grab some data from an XML file, populate a form with it, encrypt the form with a password, and email the result to someone. There are no human steps in that, just a series of operation that need to be performed as quickly as possible. You could do this using the API’s, but implementing this as an orchration is quicker, more reliable, and much easier to change.

These short-lived or “straight-thru” processes do not store an audit trail, run as fast as possible (very close to native Java speeds), and do not have a unique process-id that identifies them. They cannot be managed through Adminui, and if they fail, they simply throw an exception back to the caller, rather than being able to be re-tried thru Adminui.

Someone coined the term “Orchestration” to refer to this type of process, and the name has stuck. I’m not sure where the use of this term originated, but it’s used in several other standards BPM standards and products.

Notes:

  • Adobe do not officially use this term in their documentation (see http://blogs.adobe.com/livecycledocs/2009/02/the_livecycle_terminology_secr.html) but I think it’s a helpful term that differentiates a process as being short-lived.
  • You can still use a long-lived process for something that doesn’t involve humans. We often use long-lived-processes for processes that geneally run very quickly, because of the advantages of having each step audited, and for the ability to re-try a step if anything goes wrong. I would still call this an orchestration, because it doesn’t involve any human steps.

Here is a screenshot from WorkBench. This shows a process, its implementation, and its properties. This is a short-lived process, so I would call it an orchestration.

process

Component

A LiveCycle Component is basically a bunch of Java code, packaged up into a jar file, and deployed into the LiveCycle server.

LiveCycle Components are brilliant. I love ’em. They are my insurance policy. I know that there is no problem that I can’t solve in the process world, because if i get stuck, I can write Java code to implement it. Then I can turn it into a LiveCycle component, drop it into LiveCycle, and bingo, I can use it my processes. And the real beauty of it is that anyone else can use my component too, without needing to understand programming. In LiveCycle, Adobe have created the best implementation of a server-side component model that I’ve ever seen – it’s a bit like those Visual Basic ocx controls that you can buy to build your GUI – but on the server.

The concept of LiveCycle server-side components came from a predecessor of Process Management, and were originally called QPACs – Quick (QLink for the real old-timers) Process Action Components.

Each component defines one or more services (see below). Although in reality, most components only define a single service, so components and services are somewhat interchangable.

A service can define one or more operations. An operation is the thing that actually does the work – like sending an email, encrypting a PDF, or writing a file to disk. Services group common operations together – so the File Utilities component contains a FileUtilsService, which in turn contains operations to read, write, create and delete files. Operations each define a number of input and output parameters.

For Java programmers:

  • Component == .jar file
  • Service == Class
  • Operation == method

Here is a screenshot of a Component within LiveCycle.

components

Avoka has been building components to solve real business problems with LiveCycle for many years, and we turn most of our components into re-usable components that anyone can use. We have a large library of components that solve most of the problems we’ve encountered over the last 5 years. So most of the time, you don’t even have to learn how to build components – if it’s not already in the Adobe “box”, then check out our website – there’s a good chance we may already have built it for you.

For more information, see: http://www.avoka.com/avoka/escomponents.shtml, or email info@avoka.com

Service

Another concept that was introduced in LiveCycle ES was that of a “Service Bus” or “Service Oriented Architecture”. LiveCycle is internally implemented as a service bus. In simple terms, any bit of functionality within the LiveCycle server can be exposed to the outside world as a “Service”, and can be invoked in a number of different and useful ways. Once you’ve defined a service, you can define one or more EndPoints for that service. So for example, I might have a service that encrypts a PDF – I could add a Web Service Endpoint that allows me to invoke that service using Web Services. And I could also add a Watch Folder endpoint that allows me to invoke that service by dropping a file into a folder.

Now things get a little confusing. Services can be implemented as either some Java code, or as a LiveCycle process.

  • If you need to write Java code, you create a component, deploy that, and you get a service.
  • Or you can do it by creating an orchestration (or process), you define your orchestration, activate it, and you get a service.
  • Either way, you get a service. The choice of whether to use an orchestration or Java code depends on the complexity of the service you’re trying to create, and whether it can be created by joining together (or orchestrating) a number of other existing services.

The LiveCycle process engine doesn’t really care whether your service is implemented in Java or as an orchestration, you invoke and manipulate it in exactly the same way. You can either call a service externally (by defining an endpoint), or you can invoke one service from another, simply by dragging the service into process. This is a very neat way to handle things – why should you care how something is implemented, you should be able to use it the same way.

Note: An orchestration only ever defines a single operation, always called “invoke”. Whereas a component can define multiple operations.

This screenshot shows two services, one implemented as a component, and the other as an orchestration.

services1

Summary

  • Process: Something that you build in Workbench, and looks like a flowchart. Can be user-oriented/long-lived, or straight-thru/short-lived.
  • Orchestration: An unofficial but commonly-used term for a straight-thru/short-lived process.
  • Workflow: An older term for a process.
  • Component: A jar file containing some code to do something “useful”, that you deploy to the LiveCycle server. A component contains services, which in turn contain operations. All the Adobe services are built as components, as are all the Avoka add-on services.
  • Service: Something that lives in the LiveCycle server that provides some sort of “service”. Can be implemented either as Java code (as a component) or as a process/orchestration.
Advertisements

March 17, 2009

Speedup JBoss LiveCycle Startup

JBoss Start-up Performance

Starting JBoss with a fully configured LiveCycle installation can take an awfully long time! We’ve done some digging and found that a large portion of this time is spent unpacking the LiveCycle EAR file – and copying these files into the jboss/server/all/tmp directory. In fact a fully configured LiveCycle EAR can amount to over 800 MB of data being written – which adds a considerable amount of time to the start-up.

JBoss supports unpacked EAR and WAR files in the deploy directory, which will save these files from being unpacked at start-up time. To simplify this we’ve created a small utility that unpacks the LiveCycle EAR file and all of its contents into the deploy directory.  

We’ve found that its halved the JBoss start-up time – on my laptop this saved nearly 8 minutes – which is lots when you have to restart Jboss often.

Instructions:

Download Link
 

 

 

  1. Download the utility and unzip the file. You should have a file called “AdobeJBossEarUnpacker.jar
  2. Run the Jar – it will prompt you for the location of the JBoss deploy directory (typically its under your LiveCycle install directory in /jboss/server/all/deploy).
  3. That’s it. It will create a copy of your LiveCycle.ear file then proceed to unpack LiveCyle inside your deploy directory. Whenever you need to redeploy LiveCycle make sure you delete the exploded directory first. 

Startup Sequence

While we are on the topic of starting JBoss another really handy trick is to make use of the “deploy.last” sub-directoy. Any files placed in this directory won’t be deployed until all the files in the main deploy directrry have started. This can be very handy when you have an application that is dependant on a LiveCycle service – which means that you don’t want it to start until LiveCycle its-self has fully started.

PS – Thanks to Malcolm Edgar for some great investigative work and creating the unpacker util.

March 2, 2009

Which “bit” of LiveCycle do I need?

Filed under: Components, LiveCycle, LiveCycle Architecture — htreisman @ 7:45 pm

Overview

LiveCycle has a lot of components, somewhere around 15 last time I counted. Some run on the server, some run on the client, some you cannot actually buy but are bundled with others – it’s really confusing, even for those of us who specialize in LiveCycle. But if you’re new to LiveCycle, we don’t blame you for feeling a little lost.

This blog entry attempts to match up your requirements to the various bits of LiveCycle that you may need.

I want to…

Put a “print and fill” PDF form on my site

What you need: Acrobat.

You don’t need LiveCycle, you just need Acrobat. Create your form using whatever tools you like (InDesign, FrameMaker, Word, even Excel) and convert it to a PDF using Acrobat. Your users can download it, print it out, and use a pen to fill it out.

What else you get:

  • You get the joy of having to open a whole lot of envelopes, sort the contents, and give the illegible hand-writing to someone to do the data entry into your systems.
  • You get the added joy of having incomplete or invalid information in the forms, and having to get back in touch with the user to gather the missing and/or correct information.
  • Sigh…

Put a PDF SmartForm on my site, and allow users to fill it out electronically and print it out

What you need: LiveCycle Designer.

Use LiveCycle Designer to create the SmartForm. If your SmartForm is pretty straight forward, you may be able to do this yourself. Alternately, you may need to attend a Designer Training Course, or enlist the help of an Adobe Partner. <shameless-plug>www.avoka.com </shameless-plug>. LiveCycle Designer is a very powerful tool, and you can do amazing things with it – but if you don’t have a programming background, you will quickly get lost in the more complex aspects of the tool.

What else you get:

  • You still need to have someone read the printed form and enter the data into your backend systems. However, it’s much easier to read a printed form than a hand-written one.
  • OCR (Optical Character Recognition) is much more reliable and accurate with typed forms than hand-written ones.
  • SmartForms can really make it easier for your end users by providing in-line help, can automatically hide those sections of the form that aren’t relevant, auto-complete, auto-fill, and provide other assistance to your users when filling in forms.
  • SmartForms can ensure that the data you receive is complete and error free, by identifying mandatory fields and validations. Forms won’t print until all mandatory fields and validations pass.

Allow a user to submit a SmartForm back to me via email

What you need: LiveCycle Designer

Use LiveCycle Designer to create the form, and add a “Submit by Email” button to your form.

Note: You will receive the form data as XML. You will then need to use Acrobat to re-inject this XML data back into a blank copy of your form. If you want to avoid this manual process, and allow your users to submit the form directly as PDF, you will need Reader Extensions for your SmartForm or Acrobat for your users (see below).

Allow a user to submit a SmartForm back to me via the web (i.e. http or https) avoiding manual data re-keying

What you need: LiveCycle Designer, some server infrastructure

Just use LiveCycle Designer to create the form, and add a “Submit” button to your form.

Notes:

  • You will need to create a Java servlet or ASP.net server or PHP server or some other technology to actually receive or process the incoming submission. This means that you will need to get programmers involved – they can use the tools of their choice – it’s just the usual web request “thing”.
  • Alternately, you can use a LiveCycle server to process the incoming http request. You will then be able to process the incoming request in a completely graphical “workflow” environment without any coding. You will need to acquire a copy of:
  • LiveCycle Foundation (at a minimum). You cannot buy Foundation, it is bundled with other LiveCycle services, so you will need to pick the most appropriate one. Contact info@avoka.com for advice.
  • Avoka’s Process Invoker. This is the “bridge” between the incoming web request and the LiveCycle engine. http://www.avoka.com/avoka/addons.shtml#invoker
  • If you want to turn the submitted XML back into a PDF, you’ll need either LiveCycle Forms or LiveCycle Process Management.

Allow a user to save a partially completed form offline or call a web service from within a Form or Submit or Send a form as PDF rather than XML

What you need: LiveCycle Designer and LiveCycle Reader Extensions for your form, or Adobe Acrobat for each of your users.

Using the free Adobe Reader, your users can save a copy of your blank SmartForm to their machines. But once they start entering data, they can’t save that partially completed form (they can only print it or submit it). There are also a number of additional capabilities that can only be performed in Acrobat (and not in Reader), including:

  • Invoking a web service from a form (for example, to convert a dollar amount to some other currency)
  • Commenting on a form
  • Digitally signing a form
  • Submitting or sending a form as PDF (a normal submission just sends the XML data contained in the form, but not the form itself)

If you want to allow your users to save a partially completed form, or perform one of these other actions, then you can purchase “Reader Extensions” for your form. By applying Reader Extensions to a particular form, this temporarily extends the capabilities of Reader to allow these features for this particular form. You can purchase Adobe Reader Extensions from Adobe Enterprise Partners.

Alternately, you can purchase a copy of Acrobat for each of your users – this may be more cost effective if you have a large number of forms and a small number of users.

Alternately, Adobe Acrobat provides a “cut-down” version of Reader Extensions built it. It only provides some of the above features, and is limited to a small number of forms and small number of end-users. Contact your Adobe Enterprise Partner to find out whether you can use this feature for your scenario.

Pre-fill a form with information that I already know about the user (or some other information)

What you need: LiveCycle Forms or LiveCycle Process Management

Your user has already logged into your site, so you know who they are and other information about them. When they open a form, it’s “polite” to pre-fill the PDF with information you already know about them, to a) avoid them having to re-key it b) reduce errors in their typing. LiveCycle Forms is a server product that that allow you to inject data into any LiveCycle Form prior to serving it up to your users. LiveCycle Process Management is actually a tool for automating human-oriented activities within your organization, but it also includes a light-weight version of the service that allows you to inject data into a form. Contact your Adobe Enterprise Partner for more information on which of these two services is best for your needs.

What else you get:

  • Common and Foundation

Provide a user with a printable record or receipt of their interaction with my site

What you need: LiveCycle Output

Your user has already performed some sort of interaction with your site (bought something, filled in a html or PDF form, made a booking, or whatever), and you want to present them with a PDF that is a permanent and printable record of that interaction. Build a LiveCycle SmartForm, and use LiveCycle Output to turn that form into a “flattened” PDF form. It’s now a regular PDF document, without the ability to make any changes to the values of any fields.

What else you get:

  • Common and Foundation (see below)
  • LiveCycle Output also includes facilities for printing PDF forms directly from the server to a network printer.
  • LiveCycle Output also allows you to create documents of record in an ISO archiving format.

Digitally sign my outbound documents to give my users a sense of security that it did come from me and hasn’t been changed

What you need: LiveCycle Digital Signatures

With Livecycle Digital Signatures, you can apply a digital signature to a PDF you’ve created with LiveCycle Designer, or any other PDF document. This can be signed with your corporate (or personal) digital signature. The signing process is automated on the LiveCycle server, and can be invoked programmatically from existing applications, or can be easily incorporated into human processes.

What else you get:

  • By signing a document, you make it tamper-proof – if anyone attempts (either maliciously or accidentally) to modify the document in any way, it will invalidate the signature.
  • Common and Foundation (see below).

Enter into binding agreements with my customers or suppliers without paper signatures

What you need: LiveCycle Digital Signatures and Reader Extensions

Create a PDF SmartForm with a digital signature field. Post this form on your web site. When users have completed the form, they can use their digital signature to sign the form, and submit it back to you as a signed PDF. You can use the Digital Signatures service on the LiveCycle server to authenticate the signature, obtain information about the person signing, and validate that the document has not been changed since it was signed.

You can use the signature for non-repudiation – in other words, if the person who signed the document says that it wasn’t them, you can show them their digital signature, and since only they can sign things with their digital signature, it had to be that person.

Note: You will need to have a closed user group where you can roll out electronic signatures. For electronic signatures to be valuable, they have to be issued by a certification authority who make you prove who you are, and will attest that you are who you say you are. (You can create self-signed certificates quite easily, but there’s nothing from stopping me from creating one that says I’m Warren Buffet. A certification authority will require proof that I am in fact Warren Buffet before issueing me a signature in that name. Some countries and organizations are starting to roll out digital certificates more broadly.)

What else you get:

  • By signing a document, your users make it tamper-proof – if anyone attempts (either maliciously or accidentally) to modify the document in any way, it will invalidate the signature. That way you can prove that it hasn’t been tampered with.
  • You can also add a digital signature field to any PDF document on the server (not just SmartForms), and send that to your users for signature.
  • You also get services for encrypting a PDF with a password or certificate.
  • Common and Foundation (see below).

Capture data from a printed PDF Smartform with 100% reliability and without Optical Character Recognition or manual data entry.

What you need: LiveCycle Barcoded Forms

Create a PDF SmartForm with a 2-D barcode field on it. The barcode can store up to about 512 characters of information, and can be set up to automatically capture information from the SmartForm fields as the user types into the form. When the form is printed, the barcode contains all the information entered into the form. Instead of OCR-ing the text in the form, simply scan the barcode and get all the data. 100% accuracy – you get all the data in one scan.

Turn Office documents into PDFs on the server.

What you need: LiveCycle PDF Generator

Pass any common office document (Word, Excel, Powerpoint, Open Office, many picture formats and other document formats) to PDF Generator, and it will turn it into a PDF. The recipient will not need to have the original application in order to read the document. Can be easily integrated into manual, ad-hoc processes, or invoked from other appliations in order to automate backend processes.

Add Reader Extensions, and cater for ad-hoc commenting and review processes using the capabilities of Adobe Reader.

What else you get:

  • You can also do a lot of other types of translations, such as images to PDF, PDF to images, etc.

Store any documents created using LiveCycle (or any other document) in a Document Management System

What you need: LiveCycle Content Services or ECM (Enterprise Content Management) Connectors

You may want to store your documents in a document repository for archiving, or so that users can find all document relating to a particular subject or case or client or whatever. Adobe provide ECM (Enterprise Content Management) Connectors that allow you to store, retrieve and manage documents in many different enterprise document repositories. If you don’t already have a document repository, Adobe provide Document Services, a light-weight but powerful and scalable document management system that is fully integrated with the LiveCycle system.

Content services contains it’s own user interface for browsing, searching, editing, and uploading documents called ContentSpace.

Create approval or back-office processes within my organization

What you need: LiveCycle Process Management

LiveCycle Process Management is a state of the art human-oriented Business Process Management System (BPMS). Processes are generally invoked when someone submits a form (although there are lots of other ways of invoking a process). You can then route a form to a manager or process worker for approval or action. You can also augment the data in the form by fetching additional data from other internal systems (e.g. databases), save form data out to internal systems (e.g. file system, document management systems), send and receive emails, add attachments, send reminders, automatically escalate or deadline tasks to ensure Service Level Agreements, and much more.

What else you get:

  • Workspace: An end-user portal where you can initiate new processes, or view your inbox to find tasks that have been allocated to you or a group you belong to.
  • Business Activity Monitoring: Dashboards and reports that allow you to view workloads and throughputs, bottlenecks in your process and much more.
  • By combining with other LiveCycle services, you can archive documents, merge documents together, send emails, etc.

Host documents on a public-facing site, with pre-population, save-online, receipts, branding, online payment processing, versioning

What you need: Avoka Form Center

Adobe LiveCycle provides all the core services to create, host, pre-populate and process SmartForms. However, if you actually want to create a portal for doing all these things, you have to build it yourself in Java or .Net or some other technology – it’s not provided “in the box”.

Avoka Form Center is built upon Adobe LiveCycle. It provides a rich form-hosting portal that allows public or occasional internal users to:

  • Locate forms
  • Fill them in
  • Save partically completed forms in a drafts location online
  • Pre-fill forms based on configurable “profile” information
  • Brand the same SmartForm differently depending on the origin of the request, or the user login details
  • Automate payment processing for forms that incur a cost
  • Provide a history of all submitted forms
  • Provide an automatic receipt on completion

Form Center also provides an extensive administrative module, that allows forms to be uploaded, configured, versioned, branded, and much more.

http://www.avoka.com/avoka_formcenter/formcenter.shtml

What are “Common” and “Foundation”?

Common and Foundation are a set of lower level services that are bundled along with other LiveCycle services. You cannot buy these on their own. Foundation is always included with every LiveCycle product. The Common services that are bundled vary from product to product. Please contact info@avoka.com for more details if you’re unsure.

  • Common includes services for combining multiple PDFs into one, adding watermarks, adding table of contents, headers, and footers, extracting and injecting data and meta-data, encryption, and more.
  • Foundation gives you fantastic integration capabilities with databases, email, file system, messaging and directory services, XML manipulation, and more. This is stuff that the EAI (Enterprise Application Integration) vendors charge you big bucks for, and Adobe gives you for free (with other products).
  • The orchestration engine underlying the whole of LiveCycle provides a graphical user interface for defining your “workflows” – no coding required.
  • The orchestration engine is inherently extensible – we’ve never found something that a client wanted it to do that we couldn’t make it do.

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

July 8, 2008

Form Guide Rendering Explained – Part II

Filed under: LiveCycle, LiveCycle Architecture — htreisman @ 6:12 pm

A number of people (Gareth and Mark from Adobe – thanks guys) indicated that the first blog on this topic was correct, but incomplete.

Here is the rest of the story…

Q: What is an orchestration?

A: An orchestration is really a LiveCycle process that runs as if it were really just Java code. You design an orchestration by dragging a series of steps into a “short-lived” process, and joining those steps together using lines. Each step is really a method call on an object, and the process engine simply follows the lines, and executes each method call in the correct order. It’s basically visual programming.

You can invoke an orchestration from Java or C## or other code, via SOAP, from another orchestration, etc. When you call it, it’s almost identical to calling a real Java program, except that:

  • The logic of the code is visible graphically
  • It can be maintained and modified by non-programmers
  • It’s much easier and quicker to change
  • It runs a teeny bit slower than if you’d written the code in Java

There is a sample orchestration for rendering a Form Guide as a step inside of LiveCycle Workspace – you can refer to that if you want to take a closer look at both an orchestration, and also an orchestration rendering a Form Guide.

Q: What if I’m using the feature where you can switch between the Form Guide and a PDF?

A: Well, things do get a little more complicated.

Form Guide With PDF

Form Guide With PDF

In this case, a few extra things happen:

  1. After loading the SWF file, the SWF file checks to see whether the minimum version of Reader/Acrobat is available.
  2. If so, creates a new, hidden DHTML iframe.
  3. Into the iframe, it loads a URL that points back to the LC Forms servlet.
  4. When invoked, the servlet in turn invokes the LC Forms Render process. It supplies different parameters, this time requesting a PDF to be returned, rather than SWF.
  5. The PDF is returned to the hidden iframe.
  6. The Form Guide enables a button that allows the end user to toggle between the Form Guide and the PDF view.
  7. When the user clicks the PDF toggle button, the Form Guide extracts the current state of the XML contained in the Form Guide, and dynamically injects it into the PDF.
  8. The Form Guide then hides itself, and displays the iframe containing the PDF.
  9. When the user toggles back, the current value of the XML is obtained from the PDF, and injected back into the Form Guide, and the hide/show happens.
  10. Voila

Notes:

  • The injection of XML data into the PDF is achieved using something called the Form Bridge, which is a combination of JavaScript in the form itself, and some Javascript in the iframe. This basically allows the Form Guide to communicate to the PDF. You can either manually insert the Form Bridge into your form (in Designer, look for it in the Custom palette), or you can dynamically inject the Form Bridge into your form in the orchestration, using a service called the Form Augmenter.
  • Like the generation of the Form Guide SWF itself, the PDF will also be cached by LC Forms – on subsequent invocations, the PDF will be obtained from the cache.

Please click on the “Comments” link for some excellent additional material – a big thank you to John for contributing.

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 16, 2008

LiveCycle directories – Global Storage/Temp, clustering, and more…

Filed under: LiveCycle, LiveCycle Administration, LiveCycle Architecture — htreisman @ 11:03 am

The information in this Blog is correct to the best of my knowledge – if you discover any errors, please post on the comments area.

Thanks to Pete Spencer of Adobe for his expertise.

General

  • You need to specify various directories when you configure LiveCycle using the Configuration Manager. These include:
    • Global Document Storage (GDS) Directory
    • Temporary Directory
    • Font Directories
  • The values you enter into Configuration Manager are stored within the LiveCycle ear file. The values in this ear file are only used during initializing (bootstrapping) the LiveCycle database – after this, they are no longer used, and the values from the database are used instead.
  • All of the directories must be specified from the perspective of the application server, NOT the perspective of the machine running Configuration Manager. In other words, these directories must exist on the application server. It’s therefore simplest if you actually run Configuration Manager on the target machine.
  • You can modify the directory names in the database using Adminui at any time, including after installation. Home > Settings > Core System Settings > Configurations. You must restart the server before your changes take effect. You MUST move files from the old GDS to the new GDS while the server is stopped. You do not need to reconfigure or redeploy your ear files.
  • There is only one directory location stored in the database, no matter how many instances you have in your cluster. In a clustered environment, you must set up your servers so that all of them have the same GDS, temp and font directory names. (There’s a way around this for the temp directory – see below.)

For example: if you’re running LiveCycle on different operating systems, you cannot set the System Font directory to c:\windows\fonts on one machine, and c:\winnt\fonts on a different machine. You will have to make the directory the same on all machines, even if this means copying files to matching directories.

Another example: You cannot set the Global Storage Directory to “C:\Adobe\Global” on one machine, and “\\machine1\c$\Adobe\Global” on another. You can use “\\machine1\c$\Adobe\Global” on both machines (although this would create a single point of failure).

  • Make sure that the user under which you run the Application Server has read/write access to the temp/GDS directories, and read access to the Font directories.
  • You can use the same LiveCycle ear files for installs onto multiple boxes (eg Dev, Test, Production), even if the actual directories on a second box don’t match those that you specified for the first box. You can deploy the LiveCycle ear files, run LiveCycle, and bootstrap the database. Then you can modify the directories using Adminui, and restart LiveCycle. Once you’ve done this, you can complete the configuration by installing components and samples, etc. (Note: We haven’t thoroughly tested this, and don’t know for sure that those directories in the LiveCycle ear file aren’t used for some other purpose – we recommend that you create separate LiveCycle ear files for each machine configuration.)

Font Directories

  • These can be shared, or each application server in a cluster can have its own copy on a local drive.
  • If you’re running Configuration Manager on one machine, and deploying to another, you must copy the LiveCycle fonts from the installation directory (usually C:\Adobe\LiveCycle8\fonts) to a location on the application server machine.
  • Under Windows, the system fonts are generally either in C:\windows\fonts or c:\winnt\fonts.

Global Document Storage Directory (GDS)

  • The GDS should be considered an extension to the database, and is part of the persistent state of the LiveCycle system. Don’t “clean up” the files in this directory.
  • You should back up the files in this directory simultaneously with the database. See my previous post on this topic.
  • The GDS must be a single directory that is shared between all instances of LiveCycle in a cluster. Usually this means setting up the GDS on a shared drive, or a Storage Area Network (SAN).
  • It must also be referred to by exactly the same pathname for all instances of LiveCycle.
  • If you change the location of the GDS, you must ALSO move all the files to the new location while the server is stopped.

Temporary directory

  • Each running instance of LiveCycle requires its own temporary directory. There are a number of ways of specifying the temporary directory:
  • If you specific a non-blank directory in Configuration Manager (which also means a non-blank directory in adminui), then LiveCycle will use this value.
  • If you specify a blank directory in Configuration Manager/Adminui, then LiveCycle will use the Java VM java.io.tmpdir system property.
  • The java.io.tmpdir property can be set in several ways:
    • You can specify it explicitly in the command line that you use to launch the Java VM that runs LiveCycle. For example, “java -Djava.io.tmpdir=C:\temp …”
    • If you do not specify it explicitly, Java will set this value based on operating system defaults (eg value of “TEMP” system variable)
  • If you are using vertical clustering, the members of the cluster will each need their own temp directory, but they are sharing the same physical drive. Therefore
    • Leave the temporary directory blank in Configuration Manager/Adminui.
    • Specify a different java.io.tmpdir Java system property for each instance of LiveCycle.

June 6, 2008

Hot Back-ups of LiveCycle

Filed under: LiveCycle, LiveCycle Administration, LiveCycle Architecture — htreisman @ 4:17 pm

Most of LiveCycle’s data is held in the LiveCycle database. Backing up the database is easy – just use the native backup facilities provided by your database vendor.

Usually you can do a “hot” backup, while the application (i.e. LiveCycle) is still running. What the backup utility does is to set a “marker” in the database transaction log – the backup is the state of the entire database at the point in time the marker was set. The database will continue to run, and execute transactions, but the data from these new transactions won’t appear in the backup – so no matter how big the database is, you always get a consistent set of data.

LiveCycle is a bit more complicated, because it has the Global Document Storage directory (GDS). The GDS is really an extension or overflow for the database. For any large documents, these are actually stored in the GDS, rather than in the database – this helps with performance, and also helps to ensure that your database doesn’t grow too rapidly.

You always need to ensure that when you do a backup of your database, you do a backup of your GDS. Similarly, if you do a restore, you should also restore both the GDS and the database at the same time.

The trick is: how do you ensure that the database and GDS are consistent with each other? Any missing files in the GDS will cause LiveCycle to start throwing exceptions.

One technique is to shut down LiveCycle while you’re doing the backup. If you need to do hot backups, then there are different approaches depending on your version of LiveCycle.

LiveCycle 8 Update 1

In LiveCycle 8 update 1 (at the time of writing, in beta), Adobe have added “backup mode” to enable backups to be made more reliably. The steps are:

  • Turn on “backup mode” in the adminui – this will temporarily prevent LiveCycle from deleting any files from the GDS.
  • Backup the database.
  • Backup the GDS.
  • Turn backup mode off.

LiveCycle 8

There is no backup mode in LiveCycle 8. The following procedure is the one that we recommend for hot backups.

  • Backup the GDS
  • Backup the database
  • Backup the GDS again, to the same backup location. Ensure that you use a backup mode that adds any new or modified files, but does NOT remove any files that have been removed since the first backup.

You should also try to ensure that the entire process above occurs as quickly as possible. This may mean that you initially copy the files to a temporary location, and then perform the real backup (to tape or whatever) from there.

There is apparently a small window of possibility that errors occurs – if a file in the GDS is created and removed between the time that the first backup starts and the second backup completes. This is generally a small window. Thank you to Rob Ryan of Adobe for pointing this out.

Create a free website or blog at WordPress.com.