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).


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.
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):


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


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")

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

27 Responses to Better Form Design with XFA 2.5

  1. LHigbee says:

    Is this part of why we’re having problems with field and subform presence settings not switching from invisible to visible in 8.0 products? And does this also explain why the 8.0 products are not working with ADBC connections that did work with 7.0 version products?You mention a new version of XFA, but on the Adobe site there is no documentation anywhere – am I looking in the wrong places?

  2. LHigbee says:

    About the Legacy Mode, I read that Designer 8.0 is supposed to intuitively know to open a form created with XFA 2.4 in legacy mode. But – it doesn’t seem to be working. I open the form in 8.0 and none of my database functionality works. But, if I use your workaround and insert the child element in the XML source directing it to use XFA 2.4 and then save the document with that change, the file now opens and works just like I expect it to. Is this a bug that it’s not opening it correctly in legacy mode to begin with?

  3. LHigbee,I’m not aware of problems with switching subforms from invisible to visible in Designer/Acrobat 8.0. If you give me a little more detail on what’s happening, I might be able to figure-out what’s going on.Unfortunately, I don’t think the new XFA 2.5 spec has been posted at the spot where I linked to in my post. It should be up there soon.About the need for Legacy Mode, this is an Acrobat 8.0 specific thing. Are you saying your data connections don’t work in Designer 8.0 at design-time or in Acrobat 8.0 at run-time? When you look at the XML Source view in Designer 8.0 (where you added the Legacy Mode processing instruction), can you perhaps find an identical processing instruction near the end of the <template> element which actually specified XFA 2.5 as the form’s original version? It is technically possible to have the template set to XFA 2.4 but have the processing instruction specify XFA 2.5 and Acrobat 8.0 will load it as XFA 2.5, which would break your data connections (unless you fixed them with the cloning method).

  4. LHigbee says:

    Thank you for the reply Stefan. I can send a copy of the form to you – where can I get your email address? I’m thinking that we’re going to find that it is something about the ADBC data connections in my form. Does XFA 2.5 still support the ADBC object?I’ll keep looking for the new documentation.My data connections don’t seem to run at run-time in either Designer PDF preview mode or in Acrobat 8 (or Reader 8 for that matter). I don’t know if they work at design time since this is a form created with Designer 7.0 and the data connections are through ADBC rather than the data bindings most Designer forms probably use.I’ve since uninstalled 8.0 from my machine – I kept getting a splash screen every time I opened Acrobat 8.0 saying that I was in the 30 day grace period (even though we have a production copy of 8.0 and a license number), and when I tried to click on the Download eLicense all I got were errors saying that my system was not set up correctly and I’d have to contact our Adobe rep for help.I use Acrobat every day – it’s vital to the work I do. And this Designer form gets used 30+ times every day. So when it wouldn’t open correctly in 8.0, I started getting behind on work and finally had to uninstall it and reinstall 7.0 so that I’d be able to get work done. I will reinstall on another machine and follow your instructions above to see if that makes a difference.I really appreciate your help with this. I love Designer – it has allowed me to create a form which saves me hours of work every week, so I’m anxious to know what I can do to keep the form working in newer versions. :)LHigbee

  5. LHigbee says:

    I could find nothing further in the XML source that specified XFA 2.5 (I perhaps could have missed it.)I’m very, very frustrated with this – we’ve called Expert Support and I was told that if it involved scripting that they didn’t support it. When I tried to explain that it wasn’t my scripting, but that it was a potential issue with an object in the new version of XFA built into the product, they still said that they provided no support for that. They suggested I post to the forums. I have – one person responded and asked me to submit a copy of the form, but I haven’t heard back since then. No one else has any ideas…I’d look it up in the XFA 2.5 documentation, but there isn’t any…is there a chance I could get a draft copy? I’m not sure what else to do to resolve this.

  6. LHigbee,I’m very sorry that this issue has resulted in a lot of frustration on your part.I will send you an email to the address you provided with your comment to solicit your form for further investigation. I can’t promise I’ll find a solution nor can I promise I’ll find it quickly but I’ll do my best to figure-out what’s going on.As you do, I suspect it’s something with Acrobat’s support of ADBC via XFA forms. I assume you’re using ADBC via JavaScript in XFA events rather than using the usual ODBC data connections that are supported in XFA. Nonetheless, I’m surprised that your form would be broken in Acrobat 8.

  7. LHigbee says:

    Again, thank you! I know this one is probably very technical, so I figured I’d need a developer to help me out – I appreciate whatever time you could give me with this or any suggestions.Yes, I’m using ADBC through Javascript on the form initialize event and then in some button scripts. Problems arose because I was trying to write info to a database that has an auto-incrementing primary key (actually, three tables with auto-incrementing primary keys). The ADBC object calls an already established ODBC connection set up through the Control Panel | Administrative Tools | Data Connections.I did read your previous post regarding the data connectivity and the issues with the auto-incrementing primary key, and your solutions for getting around those, but I couldn’t find an option that would work in my situation. Possibly because I don’t know enough of the technical stuff yet.Again, thank you for any help you might be able to give. For the time being, we’ll just have to alert my form users that they can only access and use the form in Acrobat/Reader 7.x versions. I’m really curious about what might be causing this.

  8. LHigbee,I did some digging and I believe I have found the answer to this problem.It appears that ADBC was deemed a security risk and therefore has been disabled by default in Acrobat 8. The reason being that it makes no efforts to validate that the form’s user has agreed to permit the connection. In some ways, you could draw parallels between this and proctecting the SourceSet model in Acrobat 8 with XFA 2.5, as I mentioned in this post.Fortunately, there’s a simple way to enable ADBC on a system and it can be found in the Acrobat 8 SDK Readme. Since that link is currently broken, here’s the excerpt you’re interested in:

    ADBC SupportAcrobat 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\ADBCThis 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

    Note that ADBC is still only available via Acrobat Standard or Professional and on Windows only. Reader doesn’t have the ability to use ADBC.

  9. LHigbee says:

    Beautiful – that is exactly the info that I needed! Thank you SOOOOOOOOOO much!

  10. Rick Kuhlmann says:

    Can you give us/me a date for the availablity of the 2.5 XFA specifications?Thanks.

  11. Rick,Unfortunately, I can’t give any specifics but I would expect it to be posted within the next few months.In the mean time, is there a specific XFA 2.5 question I might be able to answer for you?

  12. Rick Kuhlmann says:

    Stefan,Thanks for the information. I have found the current XFA 2.4 document very helpful especially when writing javascript.Waiting a little longer for XFA 2.5 will, I am sure, be worth the wait.Thanks,Rick Kuhlmann

  13. LHigbee says:

    Hi Stefan,Thanks again for the info on getting my form working in 8.0. We’re still on 7.0 officially, and we just updated to 7.0.9 and now the form no longer works – doesn’t recognize the established data connection. Is this possibly the same thing, that they’ve turned off ADBC as a security precaution now? HELP!!!!LHigbee

  14. LHigbee says:

    Stefan,It appears that the ADBC is indeed turned off now with the 7.0.9 update. So I went in and added a new registry key for 7.0 based on the one you posted previously for 8.0.I’m really quite miffed about this – turning ADBC off in an existing version when it worked in all previous updates is something I consider to be a HUGE, HUGE change. And I think that there should have been some warning that the 7.0.9 update turned ADBC off due to security issues. Is there anywhere on the Adobe site where there is documentation on what the 7.0.9 update includes? I didn’t see anything about it from the auto-updater feature within Professional. Where do I find out what each of these updates is going to change or fix before I update?So, this leaves me with a rather large dilemma – it’s obvious I’m going to have to stop using ADBC for the data connection in my form. But in the alternate methods, I’m not sure I understand how it would handle locating an Access database that is in different locations on each of 20+ computers. Do you know where I could find more info on that? I guess I just don’t quite grasp how it would work.Thanks again for all your help.LHigbee

  15. LHigbee,You’re correct: ADBC is, in fact, disabled by default in all flavours of Acrobat 7.0.9, as well as 8.0.I wish it would’ve been clearer to everyone downloading the update — as well as installing Acrobat 8.0 — that this change was going to happen and I’m sorry it caused you so much grief. Unfortunately, the only documentation I can find on Adobe’s web site about the update is a security bulletin but it doesn’t mention anything about disabling ADBC. I’ll do some digging to see if I can find more detailed information about the update.As for migrating to XFA data connections from ADBC, I don’t know ADBC well enough to tell whether the migration will be easy or not but the one thing they have in common is ODBC. That is, you can create data connections in XFA forms which connect to databases via ODBC using a DSN just like you use a DSN with ADBC.Theoretically, as long as all the computers have the same DSN setup, whether the form uses ADBC straight from Acrobat or an ODBC data connection within XFA, there shouldn’t be any difference in the way the form connects to the database and the physical location of the database on each computer shouldn’t matter either since it’s abstracted by the DSN.There will undoubtedly be differences in the way the form interacts with the data connection as opposed to interacting with ADBC and for that, you can always ask me questions or post to the Designer Forum.

  16. Jackie says:

    Hey I read over this and I apear to not be able to solve my problem by adding the .clone to my project I still get theThis operation violates your permissions configurationError now I am a newbie but here is what I am doing…I create a data dropdown and I set the text value to a column called name and the hiddenvalue t0 the auto increment ID. Once the item is selected from the drop down I have the user click a refresh button like in the 7 code and use the same code given thereif (Len(Ltrim(Rtrim(DataDropDownList.rawValue))) > 0) then$sourceSet.DataConnection.#command.query.commandType = “text”$ = Concat(“Select * from testDb Where ID = “, Ltrim(Rtrim(DataDropDownList.rawValue)) ,””)//Reopen the Dataconnection$ ideas guys?thanks

  17. Jackie,I believe you simply aren’t using the “.clone” method in the correct location.Based on the script you outlined, you’re still modifying the Data Connection node directly:


    If you change your script to first retrieve a reference to a cloned version of the DataConnection node, you should be fine (note the use of the Ref function to retrieve a reference to an object in FormCalc):

    var oDC = Ref($sourceSet.DataConnection.clone(1))if (Len(Ltrim…) then    oDC.#command.query……

    The important thing to remember from this article is that if you’re working on an XFA 2.5 (Acrobat/Designer 8.0) form, you must always work on a cloned copy of any Data Connection node (node parented to the $sourceSet model) otherwise you’ll run into these security exceptions.Updated Mar 21, 2007: Jackie, Doug’s comment below (on Mar 19) made me realize that I forgot to use the “Ref” function to retrieve a reference to the cloned copy of the data connection in memory when scripting in FormCalc. This is vital to the remainder of your script functioning properly. I’m sorry I didn’t realize this earlier.

  18. fursten says:

    Hello Stefan,Regarding Form Certification/Ubiquitization,can you tell me where can I read more about Form Certification?I need to find a solution to this situation:My forms have scripts that change the layout of the form depending on who is opening it (for instance, if the user is from the financial department or form any other department).At the same time, each kind of user needs to digital sign the form.So for instance, a user at the financial department opens a form and see specific text in some text fields or he can even see specific input fields (some can be hidden).After he digital sign the document another user from another department will open the form, but while opening the form, the scripts in the form will change some text in the text fields and hide (or not) some sections or some input fields.Despite the form is being programmatically changed, this user need to see the digital signature from the first user, and the signature needs to be valid. He will then place his own digital signature on the document.I know Adobe as the LiveCycle Designer workflow for doing this, however my solution can´t be dependent of a specific technology. Plus, I think that while using livecycle workflow, these different views of the forms would be accomplish with rules that would create different files. However, I would like to accomplish this kind of functionality using only one file.Is this possible?Thank you

  19. fursten,Applying a Certification Signature to a form enables the verification of the integrity of the document at the time at which it was signed but still permits changes to the form, if the author of the signature decided to allow changes of a specific type.Based on that, if the signatures applied to the form in its various stages throughout the workflow and departments allow for changes to the form, then I believe you would be able to achieve what you’re attempting to do (a single form which modifies itself as per each department).

  20. Doug Einstadter says:

    I’m having the same problem that Jackie noted above. I’m using Adobe Acrobat 8 Professional and LiveCycle Designer 8.0. I’m trying to add a drop down list and Refresh button to a form to allow the user to go to any record in the database. I’m using the code described in the article ‘Adobe LiveCycle Designer 7.0 Providing interactive database lookup from forms,’ modified by addition of a clone(1) reference as suggested.Here’s my code for the Refresh button:var oDC = $sourceSet.FCGDB.clone(1);if (Len(Ltrim(Rtrim(SelectID.rawValue))) > 0) then//Change the commandType from TABLE to TEXT. TEXT is the equivalent of SQL PropertyoDC.#command.query.commandType = “text”//Set the Select Node. Select in this case will be whatever the SQL Property you = Concat(“Select * from fcg1 Where ID = “, Ltrim(Rtrim(SelectID.rawValue)) ,””)//Reopen the the .clone(1) reference solved the permissions error, but now I get the following error:accessor ‘oDC.#command.query.commandType’ is unknown.Any ideas what the problem might be?Thanks for any assistance.

  21. Doug,I’m glad you asked this question because you made me realize that I made a mistake when I answered Jackie’s question earlier:I’m noticing now that both you and Jackie are using FormCalc script to do your work as opposed to JavaScript.The major difference between the two, in this case, is that in JavaScript, the call to “clone(1)” will return a reference to the new cloned data connection object in memory. In FormCalc, however, you must explicitly request a reference to the cloned object. Otherwise, you seem to end-up with a copy of a generic object which isn’t what you’re expecting it to be (hence the error about the unknown accessor).The correct syntax for cloning the data connection object in FormCalc is the following:

    var oDC = Ref($sourceSet.FCGDB.clone(1))

  22. osama says:

    Hi advanceI’m design form with Adobe Designer. I can’t send datato database access or sqlserver.I hope give me and to learn me what I doingthanks

  23. Mike Fitzgerald says:

    Hey Guys,I’m in the same boat with this example. Here is my code:—– form1.#subform[0].TextField1111::exit: – (FormCalc, client) ———————————-var oDataConn = Ref(xfa.sourceSet.DataConnection.clone(1))oDataConn.#command.query.commandType = “text” =concat(“SELECT LN_APP_GNRL_A1.acn,LN_APP_GNRL_A1.ln_app_no,LN_APP_GNRL_A1.namFROM LN_APP_GNRL_A1 WHERE LN_APP_GNRL_A1.LN_APP_NO = “, 22809)…I now get the “expect a dict object”Please help.

  24. osama,I’m afraid I’ll need some more details about the problem you’re running into.What exactly is your form attempting to accomplish?Are you getting a specific error message when you run your form in Acrobat?Have you checked the Acrobat JavaScript Console for error messages (press “Ctrl + j” in the Preview tab or in Acrobat to show the console)?What versions of Acrobat and Designer are you using?

  25. Mike,Unfortunately, I can’t see what’s wrong with your script based on what you quoted in your comment. It all looks good to me.Is the error message telling you the line which contains the error?

  26. Mike Fitzgerald says:

    Stefan,Can you provide me some clarifcation? Can I have a form that I designed in lifecycle 8.0 with data access, enable it in professional and have it work in reader 8.0. After talking to adobe support, they didn’t seem to think that reader has data access.

  27. Mike,If you extend your form using either Acrobat 8.0 Professional or Reader Extensions, it will then enable data import in the free Adobe Reader for that specific form so that it can retrieve data from a database.