TechNote

Potential migration issue between LiveCycle Designer 8.1 and LiveCycle Designer 8.2.1

Issue

Saving an existing PDF form that was previously saved in LiveCycle Designer ES (v8.1) in Adobe LiveCycle Designer ES Update 1 (v8.2.1) can potentially cause migration or compatibility issues.
If you are working with LiveCycle Designer ES and LiveCycle Designer ES Update 1, then you can encounter compatibility issues with PDF forms in the following situation:

The form was previously created or saved in LiveCycle Designer ES and the target version was set to Acrobat or Adobe Reader 8.0.
The form contains one or more fragment references.
Fragment references cause the XFA template version to increase to XFA 2.6. Fragment references are the only LiveCycle Designer ES feature that does this. The same form without fragment references would not have migration problems.
The form contains script variables that have conflicting names.
These scripts may break if you resave the form in LiveCycle Designer ES Update 1 and then open it in Acrobat 8.1 or later.
The form is opened and saved in LiveCycle Designer ES Update 1.
LiveCycle Designer ES Update 1 writes sourceBelow = updatein the XFA template because the version of the template that is used in the target version is not equal to the version that is used in the form. After you save the form in LiveCycle Designer ES Update 1, some scripts may break when the form is opened in Acrobat or Adobe Reader 8.1.

Reason

A versionControl configuration element was introduced to the XFA template to regulate which version of the template to use when the version that is used in the PDFform differs from the version that is used in the target version. The sourceBelow option indicates what to do if the version of the PDF form being loaded is below the version of the XFA processor.

LiveCycle Designer ES version	sourceBelow setting	Result
LiveCycle Designer ES (v8.1)	maintain	If possible, render the form by using the same version of the XFA template as in the form. If this is not possible, stop rendering and report error.
LiveCycle Designer ES Update 1 (v8.2.1)	update	Update the form to the version of the XFA processor.

LiveCycle Designer ES writes sourceBelow = maintain in a form that targets Acrobat and Adode Reader 8.0 or later. However, if you open this type of form in LiveCycle Designer ES Update 1 and it contains fragment references, LiveCycle Designer ES Update 1 will write sourceBelow = update, which will cause scripts in the form to fail when the form is opened in Acrobat 8.1. Scripts in the form will run differently in Acrobat and Adobe Reader 8.0 and Acrobat and Adobe Reader 8.1. Acrobat and Adobe Reader 8.0 render the form with sourceBelow= maintain. Acrobat and Adobe Reader 8.1 render the form with sourceBelow = update. Scripts that use variables with conflicting names will break when the form is opened in Acrobat 8.1.

Solution

Avoid using LiveCycle Designer ES features in a form if they are not supported by the target version, Acrobat or Adobe Reader 8.0. A warning message appears on the Warnings tab in the Report palette when the target version does not support a particular feature.
Avoid using variables that have the same name as XFA reserved names when writing scripts. Name your variables uniquely by adding a prefix to identify the variables as your own. For example, use abc_x instead of x where abc is a meaningful prefix for your company or the form.
Avoid writing scripts that use the variables renderAs and useHref without using a unique prefix before the variable name.