The ability to programmatically access and manipulate PDF forms from within ColdFusion has been requested since, well, since we first demonstrated PDF generation abilities in ColdFusion MX 7. At CFUNITED a few weeks ago, Jason Delmore (ColdFusion Product Manager) demonstrated a planned ColdFusion “Scorpio” tag named which he used to populate (pre-fill) and extract values from a PDF form.
Scorpio is scheduled to be released in 2007. So what to do if you need PDF form support in ColdFusion right now? Well, here’s a solution:
Adobe has a Java API named XPAAJ (which stands for XML/PDF Access API for Java). The API can be used to:

  • Extract and insert PDF form field data.
  • Convert PDF documents to XDP format.
  • Access PDF metadata and file attachments.
  • Add, replace, and delete embedded data objects, file attachments, and annotations.
  • Obtain PDF file properties.
  • … and more.

Until a few days ago the XPAAJ license restricted use of the API to customers with licensed copies of LiveCycle servers. But that license has been updated to include other Adobe servers, including ColdFusion. As such, if you have a licensed copy of ColdFusion you may register and download XPAAJ and use it with ColdFusion.
Of course, using XPAAJ from within CFML code requires writing ColdFusion Java code. And so, to make life easier for us CFers, I wrote a Custom tag named which makes it really easy to get and set PDF form field values. Want to pre-fill a PDF form? You can use this code:

Extracting PDF form field values is just as easy:

is not as powerful or capable as Scorpio’s planned tag family, but it’ll help you in the interim.
To use you must download and install XPAAJ.jar from the LiveCycle Developer Center XPAAJ page (you will need to register and accept the license before doing so). XPAAJ comes with extensive documentation and examples (none of which are actually needed to use , although if you want to use XPAAJ to do more, this is all of the documentation you’ll need). Then you’ll need the attached ZIP file (see the download link below) which contains the Custom Tag, documentation, and a CFML example.

99 thoughts

  1. OPPS ! – The reason values passed using CF_PDFForm parameters will not work in calculated PDF columns is that in order do a SUM the field names must include "."
    That is, Field.1, Field.2, and Field.3 would simply use "Field" under the property of the calculated field to SUM the three values.
    Have I made another mistake? Or am I correct?

  2. OK ! – I have not been able to overcome the apparent limitation of CF_PDFForm (or LiveCycle_XPAAJ_SDK) of not being able pass variables (parameters) which are members of a class (Price.1, Price.2, Price.3 … ). Because of this, and the fact that CFMX cannot dynamically include in-form data entry ("active form fields") into either FlashPaper or PDF documents, I am once again stymied. If Report Builder and CFReport could create either PDF or Flash Paper which, in addition to pre-populated fields, could provide user fields, the software would be invaluable.
    Another problem is that even after removing all the class prefixes, and passing simple variables used in a calculated column, a calculated field will not calculate unless one of the values in the calculated column is manually entered or changed. Maybe a client-side trigger could be scripted to calc the field, but web developers will not want to make every small issue like this a life’s work to solve.
    As it stands, the application I spent 4 months developing will result in very primitive, much less flexible reports. Of course, I could use simple, “classless” variables throughout the entire form, and hope that Adobe Acrobat will accept long lists of comma-delimited variables in the “Calculate” properties of the field, but this would be very inefficient and time consuming. It may be possible to write a "Custom Calculate Script" to identify the field to be calculated by wildcard, but my common sense, and past experiences, tell me not to toss good money after bad by building entire system created using bizarre and clumsy work-arounds.
    ColdFusionMX needs a solution for creating highly flexible on-the-fly FlashPaper/PDF forms, and some third-party needs to develop an environment for efficiently building the forms. Report Builder is a failure in this regard.
    Report Builder could be used to produce very simplistic, non-interactive FlashPaper reports. Using RB with PDF to create very simple forms (the Adobe product) requires much more effort. CF_PDFForm also has some merit, but only where simplistic results are expected.

  3. KRD,
    Yes, this tag is very limited. I created it not as a complete feature, but as a stop gap measure that could help some users, as well as a way to encourage users to dig further into Java APIs themselves. I am sorry if you have found limitations, just as I am sure that there are more of them yet to be found. The tag is not a complete feature, and was never intended as such.
    We’ve already publicly stated that we’re working on it. ColdFusion ‘Scorpio’ , the first version of ColdFusion released under the Adobe name will have the expected PDF integration and support, both PDF forms and PDF file manipulation.
    — Ben

  4. Ben-
    Is it possible for CF_PDFForm to read the text of a PDF? I love how simple this is, and would rather use this, or something like it to read PDF text.

  5. It seems that any related discussions, such as CF_PDFForm, quickly are morph to debate concerning problems and limitations of Cold Fusion Report Builder (CFRB). Most people wresting with this problem are likely trying every option they can find, including CF_PDFForm (which has merit), and are probably working with them simultaneously striving for a "hybrid" solution. I certainly hope Adobe adds a lot of report building functionality to CFMX soon, and I hope some third-party makes a report design interface. Adobe is not known for logical user interfaces and CFRP is an outright failure! Trying to build a flexible report efficiently with CFRP is by far the most frustrating experience I have in 8 years CFMX development. CFRB is so clunky, problematic, and extremely limited, that I’m not sure why it is even offered as a product. O.K., point made, frustration vented, "if we must we must":
    (1) TIP – If a field is selected in a CFRB form, and fill color palette is opened, the field will acquire a background color whether you like it or not, and there is no published method (that I can find) of clearing the background color. However, I accidentally discovered that if you reselect the field, open the fill color palette and select a color, then click the Undo icon, the background color will be cleared !!!
    (2) NEW PROBLEM – Snap-to-Grid does not work in the Detail Pane.
    (3) NEW PROBLEM – Cut and Paste operations do not work in the Detail Pane.
    (4) NEW PROBLEM – You better save your form under a new name every minute or so, because the Undo is exceedingly buggy, and you will permanently loose your work.
    (5) The list of additional bugs and glitches is too great for me to list here.
    CF_PDFForm (previously identified field-naming limitation notwithstanding) seems to have much greater pdf form-building utility than CFRB.

  6. Ben,
    First…thanks for all of your work in Coldfusion development.
    Second…I’m a bit lost on how to overcome caching. For example: using your example, I submitted the form and the PDF reflected what I had submitted. BUT, if I hit the back button, changed some of the fields and submitted the form again I simply got what I submitted the first time. The only way I could get around this was by renaming the action.cfm page (ie. action1.cfm) and submitting to the new action page. Please tell me there is a better solution than this.

  7. What I did to overcome the caching was to create a variable appended to the URL for the action page that contained a randRange between 10000 and 99999. It wasn’t needed on the action side, but made the app think it was a new request. My action URL would look something like mypage.cfm?something=18754
    That worked for me.

  8. A related bug I have found in XPAAJ is that you will get a NullPointer error if you try to extract text from a document that ends in spaces (way to go, unit testers). It is easy to recreate. Just make a document in Word ending in spaces. Make it a PDF and try the text extractor in XPAAJ. Doesn’t work because the getWords function gets errors out.
    If you are having problems with a document, try to remove or trim spaces at the end before you use XPAAJ. Unfortunately, that is not a solution for my situation since I do not control the creation of the PDFs I am working with.

  9. I installed XPAAJ.jar and placed the custom tags in their proper places. I then tried to run the example and received this error.
    Object Instantiation Exception.
    Class not found: com.adobe.pdf.PDFFactory
    Can anyone help me solve this issue or tell me whats wrong?
    Thanks in advance@

  10. I’ve tried several iterations of setting the checkbo on a form, and I’m stumped…Here’s the form we’re trying to populate:
    Looking at, for example, block 9a, xexec, we’ve tried the following to trigger the checkbox with no success:
    <cf_pdfformparam name="xexec" value="1">
    <cf_pdfformparam name="xexec" value="yes">
    <cf_pdfformparam name="xexec" value="checked">
    <cf_pdfformparam name="xexec" value="on">
    We’re successful in populating the textual blocks, but we’re not able to trigger the checkboxes. Can anyone offer any suggestions? Thanks.

  11. Ignore my previous comment. Found someone with Adobe Acrobat and discovered that the "checked" values for the checkboxes are a little odd. Note to Form designers: If you’re going to reuse form controls, please make sure that the values reflect the datapoint of the current form, and NOT the one from the previous form
    For example, the checkbox "checked" value to indicate that this is an exec is "1_Commer1" — which was probably a value that indicated this was a commercial versus an autovon phone line. Sheesh!

  12. I installed the XPAAJ.jar file and the cf_pdfform custom tags.
    I tried running the test file – form.cfm. I received the following message.
    Object Instantiation Exception.
    Class not found: com.adobe.pdf.PDFFactory
    The error occurred in D:Testing WEBpdfform.cfm: line 140
    Called from D:Testing WEBpdfform.cfm: line 388
    Called from D:Testing WEBpdfform.cfm: line 354
    Called from D:Testing WEBpdfform.cfm: line 1
    Called from D:Testing WEBaction.cfm: line 27
    Called from D:Testing WEBpdfform.cfm: line 140
    Called from D:Testing WEBpdfform.cfm: line 388
    Called from D:Testing WEBpdfform.cfm: line 354
    Called from D:Testing WEBpdfform.cfm: line 1
    Called from D:Testing WEBaction.cfm: line 27
    138 :
    139 : // Get PDF document object
    140 : PDFfactory=CreateObject("java", "com.adobe.pdf.PDFFactory");
    141 : PDFdoc=PDFfactory.openDocument(formIS);
    142 :
    Any advice would be greatly appreciated.
    Thank you.

  13. I am trying to use a livecycle form to enter information into a database, i have set the form to send via the http post method and have created a cf page ready to accept the info. However the form data is not seprated and coldfusion can not determine the data?
    Output is userName=jasonticketSubject=Helpticket=helpme
    As there is no delimiters i can not access the info, or can i?

  14. Has something changed? We are running this tag on our development server, and it has worked fine. Today, though, we discovered that all instances are returning the following error:
    —- ERROR begins here —-
    The error occurred in: D:CFusionMC7CustomTagspdfform.cfm: line 140
    Object Instantiation Exception
    Class not found: com.adobe.pdf.PDFFactory
    —- ERROR ends here —-
    I just checked server and the XPAAJ.jar file is located where it has been. Can it have become disabled? The only thing I know of that has changed on that server is the installation of SQL Server 2005 and the installation of a virus scanning software.
    Any ideas? Thank you.

  15. Hi Ben,
    Does the cf_pdfform tag cover extracting metadata from pdf files, as they are not actually form fields. If not is there a custom tag available for coldfusion to allow you to access this element of the XPAAJ jar file’s functionalities.

  16. Paul, nope, it does not. But I did post another UDF named GetPDFInfo() using XPAAJ that shows how to get other information out of a PDF. It’s linked to this blog post.
    — Ben

  17. Thanks Ben,
    I found the pdfresponse.cfm page with the latest release of the XPAAJ.jar which will return the metadata for pdf docs. However a lot of the documents I am trying to query were created by GPL’S GhostScript and the pdfresponse tag/code will not process these. Do you know if there is a way to process these pdfs or are they not considered valid pdfs by XPAAJ.

  18. >Hey guys, is there any way to force a cache delete of a pdf file out of the browser. I’m having >trouble when I do a dynamic fill of a pdf, I then go back and make some changes to the data, >fill that pdf again and the old data is there. If I open the pdf with the acrobat that is >seperate from the browser it shows the data. It seems to be a cache problem. Any ideas?
    ># Posted By Scott Casteel | 10/12/06 10:21 AM
    I am seeing the same exact thing. In fact, I’ve noticed that you can open the dynamically generated pdf from a different machine and see the same cached content, which leads me to believe that the cache is pdf server-side.
    Has no one else seen this or come across a solution?

  19. Hey thanks Art for backing me on this… At least I know I’m not loosing my mind. Art got an email shortly after this post telling him to attach a random number to the end of the url as a variable. This causes PDF to think it’s different and regenerate the cache. I implemented this and it worked perfectly for me.
    What makes these forums powerful is when everyone gets the answer when you reply to the post.

  20. I am using XPAAJ. My client does not want to preview his print job. He wants to send the job or several jobs to the printer to print several pdf files at once. How could we accomplish this?

  21. What character should I use to insert a new line into a text field? My param tag looks like this:
    <cf_pdfformparam name="myTextArea" value="#attributes.address# n, #attributes.state#">
    I have tried n and <br>. Any thoughts???

  22. I answered my own question, sorry about that. Incase anyone else is wondering….

  23. I have the CF_PDFForm working in that I can see the well formatted XML data, but I want to now insert the data into a Microsoft SQL server using a CFINSERT Statement. Can you give me an idea of where I need to place this? So far all that happens is that all my columns contain NULL value after the insert. I have placed my CFINSERT statement just before the cfoutput statement on my upload.cfm document

  24. When I ran your example program, it worked great. The resulting pdf file was displayed in my browser. But when I used the ‘Save’ button from Adobe Reader, the file name was "action.pdf". Is there a way to control the name of the pdf file?

  25. We are using the CF_PDFForm tag. It is working great to fill our pdf forms. We need to be able to concatenate filled forms dynamically. We have a combination of form type XML_forms and acroforms. Is there a way to programatically combine filled forms and display the combined, filled forms to the user of the Coldfusion application?

  26. I’m having the same problem as Kevin 4/4/07 10:50 AM, except I’m using CFDOCUMENT. Is this possible? Can you control the filename it prefills when you try to Save the generated PDF? It looks like it just grabs it from your cfm template name. I need control of this to make my awesome app even better and save my users even more time.
    thanks, bl

  27. Thank you for this custom tag – it is exactly what I need.
    However, I am having problems executing it on a Bluedragon server. It works great for me with MX7, but when I try to use it on Bluedragon it fails.
    Can you help? I am getting the following error:
    The function "SetPDFFormFields" was declared twice in different templates
    Tag Context cf_pdfform: Line=9; Column=33
    <cfargument name="PDFOutput" type="string" required="yes">
    7 : <!— XML data (form field values) —>
    8 : <cfargument name="XMLData" type="xml" required="yes">
    9 : <cfscript>
    10: // Init all vars
    Thank you for any help you can provide

  28. Virginia,
    1) I have never installed it used BlueDragon, so can’t comment on why this is not working. I wrote it for CF, and it works on CF6,7, and even 8 (although unnecessary on 8).
    2) Actually, using the XPAAJ.jar file with BlueDragon likely constitutes a license violation. That library is licensed for use with Adobe servers, including Live Cycle and ColdFusion.
    3) That tag was s stop gap measure, the real functionality is in CF8 which is now in beta.
    — Ben

  29. Thanks Ben
    I thought you might tell me it had not been tried on Bluedragon. I know the client I am working for has Adobe Acrobat 8 which comes with some of the LIveCycle tools, but I doubt it comes with the server. I never looked in to it.
    Given that my hands are tied to working with Bluedragon and Acrobat 8, I wonder if I will have to resort to FDF approach. And now that I have tried and love your tag, going to the FDF will be a pain!

  30. Virginia, the <CFPDFFORM> tag in CF8 is far more powerful than my custom tag, it sounds like you may need to try and convince them to try CF8.
    — Ben

  31. I’ve used your(cf_PDFFROM) and i’m able to get the pdf. (great)
    now i need to suppress blank lines. my pdf is a business card template. (see chicago.jpg for example)
    on the left top down
    firstname middlename lastname
    job title
    on the right bottom up:
    this is where I’m stuck: if a user does not enter a fax number… I want the PDF preview to move ‘phone:’ down 1 line and not show the word ‘fax’.
    I did notice today that sometimes the data in the pdf doesn’t change it stays the same of the prior entry.

  32. isanichar,
    This can be done, but not using this tag. I think you’ll need to do some scripting in the PDF itself, you can write scripts that change/move/hide/show content based on other values. If the PDF itself is set up to work that way, then it’ll do what you want when you use this tag (or <CFPDFFORM> in CF8) to set form field values.
    — Ben

  33. I’m using a CF 6.1 installation, and got over a couple of hurdles that were mentioned here:
    > Class not found: com.adobe.pdf.PDFFactory
    The CF server does need to be rebooted after you drop the JAR file into the correct directory, otherwise CF won’t see it.
    > The argument XMLDATA passed to function SetPDFFormFields() is not of type xml.
    It seems that changing all the type="xml" to type="string" worked fine in CF6.1. The only other thing I needed to change was to remove the checks for whether variable names were valid (isValid).
    Now everything seems to be working fine. Thanks so much!

  34. Ben,
    I’m trying to get my ISP to download XPAAJ, but they maintain that it is not free and they won’t pay for it ($1495). However, my understanding was that if you already own a license for CF (CFMX 7, in this case), you can register and use. Is that the case? (I hope so as I already wrote the app and my boss wants it up and running ASAP!)
    Please advise,

  35. Christian, check the license. It does require that you have an Adobe server license to use it, and last I checked ColdFusion was indeed one of the allowed servers. Or, just use CF8 which has the tag built in now.
    — Ben

  36. My company is waiting for the first dot release of CF8 to implement it, but in the mean time I’m stuck trying to manipulate PDFs the old way.
    I tried to download the XPAAJ.jar from the LiveCycle page, however I ran into "Because we are now offering the entire LiveCycle ES suite in a trial version, XPAAJ is no longer available.". Any ideas from here?

  37. Amazing tag ben, im just hvaing issues sending my XML data to the pdf form..
    ive set the fields to be bound to their corresponding xml node, and im sending the data as a post variable, along with a couple other variables, but the form doesnt display the data. i can confirm that it does come through in the post, but no binding is occuring… shoudl i delete the databinding in the livecycle form?
    im royally stuck.

  38. OK here is my delima. We are in the process of upgrading our servers from CFMX7 to CF8. Currently we have CF8 on our Dev Servers and CFMX7 on our Live Server. I am aware of how powerful the <cfpdfform> tag is in CF8. I am having trouble getting the XPAAJ.jar working on our dev servers. I need this to work on our CF8 dev servers until we can upgrade our Live Servers to CF8. The error I am getting is:
    "Object Instantiation Exception. An exception occurred when instantiating a Java object. The class must not be an interface or an abstract class. Error: ”."
    Any ideas on what can be causing this? I have the XPAAJ.jar file in "Jrun4serversbranchcfusion.earcfusion.warWEB-INFlib"
    Any help would be much appreciated.

  39. >Hey guys, is there any way to force a cache delete of a pdf file out of the browser. I’m having >trouble when I do a dynamic fill of a pdf, I then go back and make some changes to the data, >fill that pdf again and the old data is there. If I open the pdf with the acrobat that is >seperate from the browser it shows the data. It seems to be a cache problem. Any ideas?
    ># Posted By Scott Casteel | 10/12/06 10:21 AM
    I am seeing the same exact thing. In fact, I’ve noticed that you can open the dynamically generated pdf from a different machine and see the same cached content, which leads me to believe that the cache is pdf server-side.
    Has no one else seen this or come across a solution?
    # Posted By Art | 3/6/07 11:20 AM
    The problem still exists for me in Coldfusion MX 7. Does anyone know if this was resolved with ‘Scorpio – Coldfusion 8’, or if there was a solution to this problem?

    I seem to have lost my XPAAJ.jar file and am needing it to run some old production code. Can someone please email that file to webmaster AT ? I would be grateful.

  41. Josen,
    Did you just upgrade to CF8? If you did, that knocks out theXPAAJ library. But that’s okay because instead of it being an external, add-on, now it is built in. Instead of using <CF_PDF…> tags, use the new <CFPDF…> tags. They do work better but have slightly different syntax.

  42. Brandon,
    I was in almost the exact same situation. I got around it by stopping the CF8 application service, starting the CF7 application service, then restarting the CF8 service. That has to be a temporary work around, just until I can convert everything to use the new <CFPDS…> tags.
    I hop this helps.

  43. Hi …
    I try to download XPAAJ sdk. But I find only XPAAJ.jar. Without any documentation It is very hard to work with XPAAJ.Instead of XPAAJ adobe providing LiveCycle ES SDK .which needs to deploy on windows server 2003.
    Can anybody provide me XPAAJ SDK ?
    Any Help will be appreciated.
    Thanks & Regards,

Leave a Reply