Posts in Category "Acrobat"

ADBC Now Disabled by Default

Ever since the release of Acrobat 8.0 last November and, more recently, the Acrobat 7.0.9 update (for those still using Acrobat 7.x), I’ve had a few inquires about forms using ADBC (Acrobat DataBase Connectivity) that suddenly stop working.

The source of the problem is likely the fact that Acrobat 7.0.9 and 8.0 now disable ADBC by default, regardless of whether you were using it prior to the update or not. The reason behind this change is that ADBC poses a sizeable security risk as it doesn’t provide any mechanism to protect the databases it accesses from malicious use.

Although I wish the installation programs for Acrobat 7.0.9 and 8.0 would’ve warned users that ADBC was being disabled and provided them with information on re-enabling it rather than silently disabling it and causing people a lot of grief, I think disabling ADBC when it isn’t needed is much safer than leaving it enabled in case you ever need it.

Alternatively, you may choose to migrate to ODBC data connections in XFA forms (which you can save as PDF files for use in Acrobat). Since these are still enabled in Acrobat 7.0.9/8.0 and also make use of DSNs to locate and access databases, the migration should be relatively seamless to the people using your forms. Please note, however, that exposing a database to any type of audience always creates a certain security risk which should be assessed and addressed accordingly. You might consider creating a web service to act as the bridge between the database and your form (where your form retrieves data from and pushes data into a database via methods provided by a web service), thereby restricting access to your database’s structure and data.

For those needing to (re-)enable ADBC, the Acrobat 8 SDK Readme contains information on how to do that.
For your convenience, here is the excerpt which contains the instructions (as they were stated on December 13, 2006):

ADBC Support

Acrobat Database Connectivity (ADBC) can now be turned on and off via a registry setting. To activate ADBC, create a registry key of type DWORD with the name “bJSEnable” and a value of “true” (1) in the following location:

HKEY_CURRENT_USER\SOFTWARE\Adobe\Adobe Acrobat\8.0\ADBC

This activates ADBC in Acrobat 8.0. In previous releases of Acrobat, ADBC was active by default. In Acrobat 8.0, this setting has been changed to require user intervention to activate ADBC because most users do not want to have ADBC accessible from PDF.

Windows shell command to activate ADBC:

reg add “HKEY_CURRENT_USER\SOFTWARE\Adobe\Adobe Acrobat\8.0\ADBC” /v bJSEnable /t REG_DWORD /d 1

For Acrobat 7.0.9 users, simply change all instances of "8.0" to "7.0" in the above instructions.

Please note that since ADBC poses a security risk (as outlined earlier), Adobe does not recommend modifying the registry to re-enable this feature. Also note that ADBC is still only available via Acrobat Standard or Professional and on Windows only. The Adobe Reader does not have the ability to use ADBC.

Bug: Images aren’t always embedded into PDFs

Description

Image objects (images and image fields) have a property which you can set to specify whether the image should be embedded or linked (the "Embed Image Data" check box on the Object palette’s Field tab).

When the property is checked, the result is that the image file loaded into the image object is embedded into the XFA Data that’s stored in the form. When the property is unchecked, only the URI (file path or URL) is stored in the XFA Data.

I put emphasis on XFA Data above because it’s important to understand the difference between the XFA layer and the PDF layer of a PDF form in order to understand what this bug is all about: Essentially, an XFA form saved as a PDF file results in a PDF container with the XFA inside (as opposed to saving the form as an XDP where the XFA form is at the top layer). When the PDF form is subsequently filled and saved within Acrobat (Standard or Pro), the image loaded into an image field object is supposed to be saved on one layer or the other depending on the setting of the "Embed Image Data" property on the image field.

When you save a PDF form in Acrobat, what gets saved in the XFA Data (in the XFA layer) depends on the value of the "Embed Image Data" property (which maps to the //field/ui/imageEdit@data attribute). If it’s set to "link" (unchecked), then only the original path to the image file is saved. If it’s set to "embed", then the image file is text-encoded and saved in the data instead of the original file path. In either case, however, the image should always be embedded into the PDF layer (don’t worry, it doesn’t actually get embedded twice, once on each layer, I’m just simplifying things a little here) such that the PDF is self-contained and can be re-distributed without having to ensure that the linked image file remains accessible from any location.

Unfortunately, there are cases when the image file doesn’t get embedded into the PDF layer when it should be. For example, if you have an image field object which is set to link to its image file and you load the image by importing data that contains the file path then save the PDF, the image won’t be embedded into the PDF as expected.

Workaround

At this time, I’m not aware of any workarounds to the specific issue I stated above (when importing the image’s file path).

The only way to consistently get image files to be embedded into the PDF as they should be — regardless of the image field object’s setting to link or embed its data — is to manually click on the image field object in Acrobat and pick the image file.

Fix

Please refer to the Bug List for updated information on the version(s) affected by this bug as well as if and when it was/will be fixed.

Better Form Design with XFA 2.5

You may have noticed that the new version of Designer and Acrobat that Adobe recently released uses a new version of XFA (2.5 to be exact). While the language has many new features in and of its own, the version of the language (2.5 vs 2.4 or older) also dictates how your forms will behave in Acrobat 8+ with respect to certification (digital signatures) and ubiquitization (Reader-enablement).

Background

Since this new behaviour, which is geared to encourage better form design going forward, will ultimately change the way you write certain scripts, I believe it’s important to start with some basic knowledge of XFA forms, see what happens when they get certified/ubiquitized, examine how each used to behave in Acrobat 7 and then how they’ll behave in Acrobat 8+.

XFA Primer

Simply said, an XFA form is described inside an XDP file. When it’s saved as a PDF file, the XDP is actually embedded into the PDF so that it can be processed by Acrobat.

If you look at the XDP (via Designer’s XML Source view), you’ll see that it’s simply a collection of packets that describe the form’s various components. For example, <template> describes the form’s layout and behaviour while <sourceSet> contains a collection of data connection descriptions you’ve defined using the Data View palette. When the form is loaded as a PDF into Acrobat, each packet is loaded into its own in-memory (temporary) model and that’s what you actually reference in your scripts. For example, you access the sourceSet packet via the sourceSet model with "xfa.sourceSet". Changes to these models are reflected directly into their pertaining packets.

Form Certification/Ubiquitization

Without going into more details than are necessary, once a form is either certified and/or ubiquitized, modifications to any of the protected content (the various models) should be prevented. Modifying the form’s protected content post-certification/ubiquitization would invalidate the certification/ubiquitization status. Such modifications mean that the document is no longer in the state in which it was when it was digitally signed and therefore can no longer be trusted by the recipient as being authentic. Even though the modification may have been caused by authored script in the form, no distinction is made between those kinds of modifications and malicious attacks by an unknown party to, for instance, cause form data to be submitted to an alternate server.

Acrobat 7 and XFA 2.4

Acrobat 7 supported XFA forms up to XFA 2.4 (which Designer 7.1 would author). Once an XFA 2.4 form would be either certified and/or ubiquitized, Acrobat 7 would detect modifications to the form’s protected content and would invalidate its certification/ubiquitization status if such modifications occurred. It didn’t, however, prevent the sourceSet model from being modified post-certification/ubiquitization even though the <sourceSet> packet was included as part of the certification/ubiquitization process.

The inherent danger in this was that while any form that would do common things like display all the records in a database or select specific records in a database (filter records) — which required the modification of data connection nodes contained within the sourceSet model — would function happily at first, problems would ensue later on when a form’s certification/ubiquitization status would be inadvertently invalidated, for example, because of an unauthorized modification to a certified/ubiquitized model (sourceSet).

Acrobat 8 and XFA 2.4

In order to address the problem of inadvertent modifications (by form scripts) to certified/ubiquitized XFA 2.4 forms, Acrobat 8 was designed to prevent the sourceSet model (and any other certified and/or ubiquitized content) from being modified post-certification/ubiquitization. This means that if an XFA 2.4 form, loaded in Acrobat 8+, becomes certified and/or ubiquitized, any attempt by a form script to modify the sourceSet model (as in the two examples I mentioned earlier) will result in a security exception:

GeneralError: Operation failed.
XFAObject.setAttribute:25:XFA:form1[0]:initialize
This operation violates your permissions configuration.

One could argue, of course, that this change effectively "breaks" XFA 2.4 forms in Acrobat 8+ but in the end, inadvertently invalidating a form’s certification/ubiquitization status is likely just as bad as a security failure in a form’s script (because it attempted to modify a now-protected model) from a user experience point-of-view. As I mentioned earlier, Acrobat makes no distinction between authored scripts and malicious attacks when certified/ubiquitized content is modified — and neither does the user (in their minds, the content simply can’t be trusted any longer)!

Acrobat 8 and XFA 2.5

With a new version of Acrobat and XFA, there was an opportunity to further improve on the user experience of both certified/ubiquitized and non-certified/ubiquitized forms going forward. It was done simply by ensuring that modifications to any model that becomes protected post-certification/ubiquitization are now prevented from the start (whether the form is certified and/or ubiquitized or not) and by using XFA 2.5 as Acrobat 8+’s “trigger” for imposing the new behaviour.

The result is that we’re now forced to think about security from the very beginning of the form design process by opting to work with copies of the in-memory models (which is achieved by cloning models) rather than with the base models such that our forms don’t fail regardless of their certified/ubiquitized state. With XFA 2.5’s support for "on-the-fly" certification/ubiquitization, a form may become secured and locked-down at any point in its "live cycle" which makes it imperative to use scripting techniques which won’t fail post-certification/ubiquitization.

Legacy Mode

New forms authored in Designer 8.0 will be XFA 2.5 forms by default and you’ll need to use the new cloning technique described later in this article. That being said, if you need things to be back the way they were, there is a way that you can still use Designer 8.0 to design XFA 2.4 forms and that’s by using what’s called the Legacy Mode processing instruction.

Put simply, switch to the XML Source view for an XFA 2.5 form in Designer 8.0 and insert the following processing instruction under the <template> node (as a child element):

<?originalXFAVersion http://www.xfa.org/schema/xfa-template/2.4/?>

The result will be that Acrobat 8.0 will run your form as though it was an XFA 2.4 form — but be aware that this will also prevent you from using any of the new language extensions and APIs that come with XFA 2.5 (more on those in later posts).

(By the way, when you load an older form — earlier than XFA 2.5 — into Designer 8.0, even though the form’s version is upgraded to XFA 2.5, the Legacy Mode processing instruction specifying the form’s original XFA version is automatically added so that your form continues to work properly with respect to the XFA version is was originally designed for.)

Modifying sourceSet in XFA 2.5+ Forms

In order to avoid unexpected security exceptions in your forms after they get certified and/or ubiquitized and to handle the fact that you may not necessarily know for sure at which point in the form’s workflow that it’ll happen (if ever), you need to make sure that when you’re working with the sourceSet model, you’re actually using a cloned in-memory copy of the original sourceSet model rather than using the original sourceSet model directly.

Cloning Form Nodes

Don’t worry: You don’t have to be a scientist to use this simple technique. Using the

clone(deep)

method on the node that defines the particular data connection you’re wanting to modify within the SourceSet model and making sure your script keeps using the clone instead of the actual definition will do the trick. This method accepts a boolean parameter which, when set to 1 (or true), will clone the node and all its children (which is definitely what you want to do or else you will only get a shell instead of the full data connection) and return a reference to the in-memory copy.

As an example, let’s consider the following script taken from the Data Drop Down List object (found in the Library palette’s Custom tab):

...
var oDB = xfa.sourceSet.nodes.item(nIndex);
...
// Search node with the class name "command"
var nDBIndex = 0;
while(oDB.nodes.item(nDBIndex).className != "command")
nDBIndex++;

oDB.nodes.item(nDBIndex).query.recordSet.setAttribute("stayBOF", "bofAction");
oDB.nodes.item(nDBIndex).query.recordSet.setAttribute("stayEOF", "eofAction");

Notice that the script first obtains a reference to a data connection node found within the original sourceSet model and then goes on to modify some of its properties. In an XFA 2.4 form loaded in Acrobat 8+, prior to certification/ubiquitization, this will function properly although it’ll stop functioning if the form ever gets certified/ubiquitized. In an XFA 2.5 form, however, it’ll immediately fail with a security exception simply because Acrobat 8+ determines that the sourceSet model may eventually become protected and protects it from the start.

Applying the cloning technique to this script is trivial. All you need to do is change the line which accesses the sourceSet model to this:

var oDB = xfa.sourceSet.nodes.item(nIndex).clone(1);

Notice the clone(1) method appended to the end of the statement. At that point, "oDB" now receives a reference to a copy of the original sourceSet model which it’s free to modify regardless of the form’s certification/ubiquitization status. The rest of the script doesn’t need to be modified at all!

Note that you could just as easily store the cloned data connection node into a Form Variable or a variable defined in a Script Object in order to reference it again at a later time if you make modifications to it that you would like to persist while the form is running in Acrobat.

Updated Library Objects

If you had already installed Designer 8.0 and tried using the Data List Box and Data Drop Down List objects under the Custom tab in the Library palette, you more than likely ran into the security exception I described earlier. That’s because those custom objects managed to miss the ever so important update which they required in order to function properly in XFA 2.5+ forms with Acrobat 8+ (as we saw in the previous section).

For your convenience, I’ve posted updated versions of both the Data Drop Down List and Data List Box custom Library objects which you can save to your local system and add to your personal (or shared) Library in Designer 8.0.


Updated: December 11, 2006

Scripting Table Columns

A few days ago, Sergio, one of my regular commenters, posted a question about programmatically adding new columns to a table. My reply to his comment quickly turned into something that I thought should be promoted to a blog post so here it is.

This question required some investigation because it led me to the discovery of a bug related to adding/removing instances of a table column in a form viewed in a version of Acrobat prior to 8.0. More on that later in this post.

The short answer to Sergio’s question is that yes, in fact, you can modify the set of columns in a table programmatically at runtime. You can do this by either using the presence attribute — although this isn’t recommended because it can lead to data merging problems — or you can use Instance Managers to do it, which is the recommended method to use.

Here’s a sample form that contains a table with a “repeatable column”. Using the add and remove buttons that are provided, you can add and remove instances of the 3rd column.

Download Sample [pdf]

Minimum Requirements: Designer 7.1, Acrobat 7.0.5.

Continue reading…

Image Field Z-Order Problems

h2. Description

If you’ve ever tried to use an image field’s contents (an image) as the background for a form and wanted to let the user change it at run-time, you’ve probably run into problems if you had placed objects on top of this image field. The most common result is the image field’s contents always appears on top of all other fields which are technically higher in z-order (“in front” in the hierarchy) than the image field.

While this may seem like buggy behaviour, it’s not technically a bug and I’ll try to explain why it isn’t.

The behavior occurs because of the way image fields are translated from XFA objects to “AcroForm objects”:http://blogs.adobe.com/formbuilder/2006/06/acroform_objects.html when your form is saved as a PDF and rendered in Acrobat.

The PDF format has a definition for what is called an _Annotation_ object which represents essentially all the “extra” stuff you can add to PDF documents such as comments, stamps, highlighting, etc. When it comes to image fields, their contents is actually an Annotation in the PDF layer as opposed to contents in the XFA layer. Since the PDF layer is above the XFA layer, Annotations can’t be placed behind objects on the XFA layer — hence why the contents of an image field is always displayed above any objects that may be “in front” of it in the XFA hierarchy (z-order).

Continue reading…

Bug: Cannot Override Calculations

h2. Description

The XFA language supports fields which are calculated yet still overridable by the person filling the form. For instance, you may have an invoice on which you calculate the tax associated with a purchase using a calculated field yet, for customers from other countries, you would like to allow them to override the calculated tax amount and enter the correct amount themselves.

To do this, you would use the Object palette’s Value tab and set the field’s Type property to _Calculated – User Can Override_. You could even go as far as specifying an Override Message which would appear if the user attempted to override the field’s calculated value.

In theory, when the user attempts to override the field’s calculated value, either the Override Message or, if none was specified, an Acrobat default message appears warning that the field is calculated and gives the user the option to continue with the override or to cancel. If the user proceeds with the override, subsequent calculations use the override value instead of the original calculated value regardless of subsequent changes to other fields which the overridden field’s calculations were dependent on.

Unfortunately, there’s a bug in Acrobat that causes the overridden value to be discarded. It manifests itself in a couple of different ways:

# *Dynamic PDF:* Not only will the value specified by the user (the override) not be retained but the Override Message (if specified) won’t be displayed. The behavior is simply to let the user type-in a value but then throw it away and run the calculation again without any warning.
# *Static PDF:* In this case, the Override Message (if specified) is displayed and the user has the option to discard their change or proceed with the override but the specified value is discarded regardless of what they choose to do and the calculation is run again.

Continue reading…

Importing Data in Acrobat

Data is central to every form. Some forms simply collect data while others use pre-collected data to do various things to forms, such as pre-populate names, phone numbers, addresses, affect the layout of a form or various other things.

Using pre-collected data to affect a form as described above involves *importing* data into a form via the host application (assuming a server isn’t part of the picture). This time around, I want to talk specifically about importing data using *Acrobat*.

As you all know, Adobe distributes the “Reader”:http://www.adobe.com/products/acrobat/readermain.html application for free. Because of this, you can save the forms you design in “Designer”:http://www.adobe.com/products/server/adobedesigner as PDF and anyone with the free Reader application can fill your form and submit its data electronically.

The catch is when your PDF form requires data to be imported. Unless the host application is “Acrobat Professional”:http://www.adobe.com/products/acrobatpro or “Acrobat Standard”:http://www.adobe.com/products/acrobatpro/acrobatstd.html, a _regular_ PDF form *cannot* import data — no matter if it comes from an XML Data file or from a data connection to an ODBC or WSDL data source. Acrobat Pro/Std comes with all the tools you need to import data into a form and permits data to be automatically imported via an ODBC or WSDL connection. PDF forms opened in Reader (or “Elements”:http://www.adobe.com/products/acrobatpro/acrobatel.html for that matter), on the other hand, aren’t privy to that functionality by default — that is, Reader 7.0.7+ (the latest version is 7.0.8) doesn’t allow data import by default.

In Reader 7.0.5, there was a bug that resulted in Reader having the ability to import data into forms. Unfortunately (well, that’s my opinion), that bug was fixed in Reader 7.0.7 such that Reader can no longer, by default, import data into a PDF form.

In general (at least as of Reader 7.0.7), PDF forms opened in Reader must be individually _extended_, using Acrobat Professional or “Adobe LiveCycle Reader Extensions”:http://www.adobe.com/products/server/readerextensions, to allow the use of “hidden” functionality in Reader (such as Data Import or Commenting). (You can reader-extend forms using Acrobat Professional’s “File | Form Data | Initiate Data File Collection Workflow” menu item in order to collect data via Reader for a limited number of submissions.)

Another option is to use “Adobe LiveCycle Forms”:http://www.adobe.com/products/server/formserver to deploy your forms. Using this server product, you can pre-populate forms with data _on the server_ prior to deploying them to the client application (on the user’s system). Using this option, you don’t need to reader-extend a PDF form which imports data because the data is imported and merged into the PDF form _on the server_ and then deployed to the client application (any version of Acrobat/Reader on the user’s system), which, in turn, doesn’t need to import any data.

To summarize, here’s a little table that illustrates the conditions under which you can import data into a PDF form in Acrobat:

_|((())). *Version* |((())). *PDF Form* |((())). *With Reader Extensions* |((())). *With LiveCycle Forms* |
|((())). Reader |((())). %{color:red} *no* % |((())). yes |((())). yes |
|((())). Elements |((())). %{color:red} *no* % |((())). yes |((())). yes |
|((())). Standard |((())). yes |((())). yes |((())). yes |
|((())). Professional |((())). yes |((())). yes |((())). yes |

====
~*Updated:* September 20, 2006~