Understanding LiveCycle ES2’s application model

Note: If you’re visiting this blog from the Adobe LiveCycle Developer Center or from the Adobe LiveCycle Blog, welcome to my musings. You’re invited to tell me what you want to know about LiveCycle via a comment. Thanks in advance! :-)

This longer-than-usual post is intended to help customers understand why the new application model exists in LiveCycle ES2 and understand how to migrate LiveCycle ES assets into ES2 assets, based on business value into doing so. It is meant to complement, not reiterate, other content already published concerning the application model (e.g. the section on migration process, below, is just an example meant to whet the reader’s appetite for more detailed demonstration/conversation elsewhere).

So, without further ado…

Table of contents:

  1. Introduction
  2. Application model principles
  3. Conclusion
  4. Additional resources


When Adobe LiveCycle ES2 released, major advancements and changes occurred in several areas of application development. The purpose of this white paper is to explain these advances specifically in the context of migrating existing LiveCycle assets into the new ES2 application model. However, before the migration process is described step by step, it’s important to understand the new model, why it is exists and when it should be leveraged.

The most notable changes to application development in LiveCycle ES2 are as follows:

  • LiveCycle Applications
  • Versioning
  • Far and Near References

All new development work in LiveCycle ES2 occurs in LiveCycle Applications.[1] A new Applications view replaces the Processes and Resources views in LiveCycle Workbench ES2 as the primary view for application development. Both Processes and Resources views remain to support upgraded LiveCycle assets that have not yet been migrated to LiveCycle Applications.

LiveCycle Applications contain processes, forms, guides, data models, events, fragments, images, DDX files (Assembler document service), DSC’s, etc.[2] A LiveCycle Application is a container of design-time assets. When a LiveCycle Application is deployed, services are delivered into the runtime, and at this point a particular service’s implementation becomes hidden from the consumer (e.g. there is no “File | New -> Service” that emits a service object in LiveCycle). Consumers continue to discover services via the LiveCycle Service Registry.

It is important to understand that from now on when you do something in Workbench the first thing you do is “File | New -> LiveCycle Application” and that the Application is the container for all your application assets.

A LiveCycle Application is the basis for a hardened, discrete versioning model in LiveCycle ES2. That is, application assets do not have versions of their own; they inherit the version of their parent LiveCycle Application. These version numbers are immutable, meaning that they do not change even when the application is deployed on different LiveCycle systems. In LiveCycle ES an edit/save gesture on an application assert could result in the creation of a new version of that asset; however, in LiveCycle ES2 such gestures will not–version is defined solely by the hosting application.

A LiveCycle Application is the context for how asset references are maintained. An asset referring to another asset in the same LiveCycle Application uses a relative near reference. When an asset refers to an asset in a different LiveCycle Application then it is a far reference. Far references are required to state LiveCycle Application name and version (e.g. repository:///Applications/NewCustomers/1.0/Loan/Forms/request.xdp).

Applications, assets and references
Figure 1. Applications, Assets and References

In the above figure, there are two applications (i.e. App1 and App2) and a total of three application assets (i.e. A, B and C). The line between A and B represents a near reference (i.e. wholly contained by App1). The line between A and C represents a far reference (i.e. a reference that spans from one application to another application–specific version).

In the above figure, App1 and App2 can be versioned (i.e. 1.0, 1.1, 2.0, etc.); however, A, B and C cannot be versioned apart from their containing LiveCycle Application.

Application Model Principles

So, why did LiveCycle ES2 usher in a new application model, and why should you want to upgrade to leveraging it?

In LiveCycle ES, there were services/processes, events, forms and Document Service Components (DSCs). Each object had distinct user interface with different semantics for how the object could be edited, locked, activated, secured, versioned and exported. Conceptual information that the user acquired while using one subsystem was not transferable to the other subsystems. One of the design goals of the LiveCycle ES2 application model was to normalize these behaviors and provide a consistent user model across the managed objects.

The LiveCycle ES2 application model provides hooks at strategic points in an asset’s runtime. The ability to transactionally deploy a collection of assets and the ability to intercept the runtime lookup of a named asset both represent key indirection points that can be leveraged in future versions of LiveCycle.

The LiveCycle ES2 application model enforces a consistent persistence model for the design-time assets. This, in turn, provides the foundation for supporting disconnected mode (offline or occasional connectivity), SCM integration and intuitive experience in Workbench (e.g. login/logout, open/save).

Your confidence during migration is of utmost importance. The LiveCycle ES2 application model addresses migration confidence by enabling existing investments to continue running in a “bug compatible” manner. Maintenance of existing systems can involve evolving an existing system on an as-needed basis.

The application model in ES2 supports two types of changes: semantic and non-semantic. Given that an application is a composition of assets, change can refer to the set of assets in the application and/or to the assets themselves–both their content and their associated metadata.

A non-semantic change represents an update that does not provide any new functionality over prior versions but rather represents an incremental refinement. Bug fixes and patches are good examples for a non-semantic change. A non-semantic change never requires consumers to be aware of the change. Non-semantic changes can be imposed by the producer on all of its consumers without requiring the participation of the consumer.

A semantic change represents an update that will introduce new capability above what is available in pre-existing versions. It is possible that a semantic change will necessitate that the consumers adjust the way that they interact with the objects. A semantic change must be explicitly requested by consumers, it is never implicitly forced upon them by the producer.

Example migration to ES2 application model

So, now that you have a better understanding of a LiveCycle Application and the new application model in LiveCycle ES2, let’s walk through the process of migrating a LiveCycle ES (8.x) process to a LiveCycle ES2 (9.x) process:

  1. Deploy the LiveCycle ES LCA as LiveCycle Archives (8.x) (Compatibility mode).
    • The LiveCycle ES processes will run as-is on LiveCycle ES2 as LiveCycle is backward-compatible. If your goal is to simply move the running content to an ES2-based server (without taking advantage of any new capabilities) you are done.
    • If you want to leverage native ES2 functionality, you will need to follow the rest of these migration steps in order to convert the LiveCycle ES process to LiveCycle ES2 process. Converting the process will result in a service name change since the LiveCycle Application name (namespace), version, etc. become part of the service name in LiveCycle ES2.
    • Best practice: If you are adding new resources to the application the recommendation would be to do a full migration and import all assets into the new application, resetting the deployment identifiers. Mixing and matching legacy ES resources and the new ES2 application model is not recommended.
  2. In Workbench, create a new application (e.g. MyApplication).
    • Application name forms a namespace for assets therein.
    • You can optionally create folders within the application to specialize this namespace further.
    • For example, your development team may have particular standards for organization (e.g. based on asset type, based along functional lines, etc.).
    • In this particular migration, we’ll create a “processes” folder to receive the imported ES process assets.
  3. In Workbench, right-click on MyApplication/1.0/processes and select Import. In the dialog shown, select Process and click Next. In the next screen, select the LiveCycle ES process from its LiveCycle ES category. Click Finish.
  4. The LiveCycle ES process will be added to the LiveCycle Application (i.e. MyApplication). Please note that this is a copy of the original process.
    • The service name of original process is the process name itself; however, the service name of the new process is ApplicationName/processes/ProcessName.
    • Assets in ES lived apart from a namespace (i.e. unqualified services at runtime). ES assets in ES2 operate in a global service namespace (implied) at runtime. Native ES2 assets operate in application-scoped namespaces.
  5. If the original LiveCycle ES process has dependencies on other LiveCycle ES sub-processes, the new LiveCycle ES2 process will also have the same dependencies (i.e. LiveCycle ES2 process depending on LiveCycle ES processes). Therefore, in order to create a self-sufficient LiveCycle ES2 LCA containing processes with the same functionality, we need to identify and reset these dependencies. That means finding each dependency, visiting it and pointing it to something new.
    • In order to point a dependency at something new, the desired dependency target must exist in the application.
    • Best practice: create self-contained applications.
  6. To remove dependencies from other LiveCycle ES processes, we’ll have to repeat steps #3 to #4 and import all those processes under the same LiveCycle Application (e.g. ApplicationName/processes/SubprocessName).
  7. After importing all processes under the LiveCycle Application, we’ll have to edit all the processes individually in order to replace all the sub-process activity with the new processes.
    • Consider the following example: Process A uses process B (LiveCycle ES).
      • Both ES processes are imported into the LiveCycle Application, which results in processes A’ and B’ (LiveCycle ES2).
      • However, process A’ (LiveCycle ES2) still uses process B (LiveCycle ES).
      • We edit A’ and replace activity B with B’, using the same input/output parameters.
    • This step requires manual editing of all processes using sub-processes, which is time-consuming and can be error-prone without sufficient attention to detail.

This example is simply focused on process asset migration, but, as previously noted, there are several other application asset types that may be migrated.


Hopefully this paper has been helpful to your understanding of why there is a new application model in LiveCycle ES2 and how to take advantage of this capability with your LiveCycle ES investments in mind.

The LiveCycle team continues to work on enhancing migration support for its customers (e.g. increased automation), and it appreciates your feedback.

Additional Resources

For a more detailed dive into the process of migrating LiveCycle ES applications and assets to LiveCycle ES2, please consider the following content:


  1. LiveCycle Application should not be confused with LCA, which stands for LiveCycle Archive. LiveCycle Archives continue to provide the ability to export an application along with its assets (i.e. variables, images, documents, etc. since ES, service endpoint configuration and security since ES Update 1, etc.). Asides: (a) legacy LCA’s are still supported in ES2 (i.e. it’s possible to create/import them), and (b) there are two kinds of native ES2 LCA’s: patch (a specifically selected set of assets) and full (one or more applications where all content from the application is involved–no need to explicitly enumerate assets).
  2. These contained objects are called assets (i.e. application assets).