Limitations of Dynamic XDP Assembly for References to Fragments and Images (LiveCycle ES2)

The Assembler service's dynamic assembly capabilities allow for XDP files to be joined and for fragments to be placed at insertion points in XDP files. If form designers use the LiveCycle Designer ES2 default behavior of relatively referencing fragments and images, other LiveCycle ES2 services sometimes have trouble assembling and rendering the form. In particular, these problems can occur:

• Inability to resolve relative image references that appear within fragments 
• Failure to resolve XDP forms and fragments that use relative references to fragments 

These limitations will be resolved in a future service pack. 

LiveCycle ES2 Designer and the Assembler service let you create XML form templates that include fragments. A fragment is a part of a form that is used in other forms. Using fragments simplifies and speeds up the creation and maintenance of large numbers of forms. 

• Designer lets form designers create forms that include fragments.  
• Beginning with LiveCycle ES2 (9.0), the Assembler service supports XDP dynamic assembly, where DDX documents specify insertion of fragments into a form. (Dynamic XDP assembly can also assemble multiple XDP documents into a single XDP document.) XDP Dynamic assembly enhances Designer support for form fragments; that is, using Design and XDP dynamic assembly to include fragments in a form are compatible.

Here is an illustration that shows how fragments and images can be used in a base form. The base form references two fragments. One of those fragments references an image. The lower form shows the appearance of the assembled and rendered form.

Using Designer to create forms that include fragments

Form designers can insert fragments into a form by selecting a fragment from a fragment library. In the XML version of the form, Designer inserts corresponding references to the fragments. By default, these references are relative.

Subforms from an existing form can be extracted as a fragment into the fragment library. In this case, the form designer can replace the subform with a reference to the extracted fragment (which is the default behavior) or keep the subform content as it is.

Using Designer to create forms that include images

When form designers add image objects to a form, they can specify a URL or browse to the location of the image. In the latter case, Designer by default uses a relative reference to identify the location of the image file.

Issue:

When the Forms or Output service renders an XDP form, it cannot resolve relative image references (for example ../myImage.jpg) that appear within fragments that are used to construct the form. With XDP forms that have such unresolved images, these services render the XDP form, but the result omits unresolved images. They also provide a warning indicating that images cannot be resolved.

Solution: 

Form designers can ensure the Forms or Output service can resolve image references by embedding the image in the form or changing the image reference to an absolute URL that correctly locates the image. Here is an example of an absolute URL: File:///myDirectory/myImage.jpg. The Designer ES2 default behavior is to use relative references for images. 

Using the Assembler service to create forms that include fragments (XDP dynamic assembly)

With XDP dynamic assembly, developers create DDX documents that direct the Assembler service to import fragments into insertion points within an XML form template. Those DDX documents can also import fragments into the insertion points of another fragment. The DDX expressions cannot specify images to import into a form or fragment. Instead, form designers create image references. 

Issue:

When the Assembler service processes a DDX document that specifies an XDP source as a document object (via the input map) or as a File URL, it cannot resolve relative references to fragments that appear within that XDP source. Also, it cannot resolve relative references to fragments that appear within other fragments that are included in the XDP source (nested fragments). Here is an example of a relative reference ../myForm.xdp.

In contrast, if the DDX document uses an application or repository URL to specify the XDP source, and if the XDP form and fragments also use application or repository URLs, then the Assembler service can resolve relative and absolute references to fragments.

When the Assembler service is unable to resolve references to fragments, it terminates the job with this error: 

  The operation-name operation failed on XDP name.

  XFA Dynamic assembler failed to stitch a fragment. 

Solution: 

There are two ways to avoid this problem: 

• Use only application or repository URLs for your DDX and XDP references. All references in the DDX and XDP form and fragments must consistently use application or repository URLs. Within the XDP form and fragments, these references can be relative. 
• Use only absolute references within the XDP form and fragments. (This solution applies only if application or repository URLs cannot be consistently used.) When form designers add a fragment to an XDP form (or to another fragment), Designer ES2 creates a reference to the fragment. By default, the reference is a relative reference to a fragment library. Form designers can ensure that the Assembler service can resolve fragment references by changing the relative reference to an absolute reference.