Acrobat Reader Extensions

The following is an explanation of how to programmatically enable Acrobat Reader Extensions from ColdFusion.

‘Reader Extensions’ is a great enabler for pdf technologies. It allows form filling and annotation on a pdf document for users who only have the free Acrobat Reader. It is useful for general Internet applications, where Acrobat Reader is the norm. We will soon be using it on the Land Rover G4 Challenge, where we need an application form that is the same on the web and when printed.

Another useful scenario is when engaging with large corporates, where Acrobat reader is likely to be part of their standard PC build, and where the time and business cost of getting Acrobat Professional installed for a small number of users in the organisation, can be prohibitive. This is a common scenario with some of our larger clients. Reader Extensions allows us to use Acrobat annotations when approving artwork, catalogs, DM packs etc, without all our users having to install full Acrobat.

Acrobat Professional 8 allows you to enable reader extensions on a PDF for free. There are some limitations which are in the Acrobat EULA and discussed here. If you envisage usage beyond the EULA, have a large number of documents, or need to enable the extensions programmatically then you will need the Reader Extensions service in Adobe LiveCycle.

To anyone unfamiliar with LiveCycle, think of it as a suite of pdf related tools, linked together within a workflow management system, that allows non programmers to define complex workflow interactions. Its a powerful system, designed (and priced) for use by large corporates. Its sold as a modular system, so you can buy just the Reader Extensions part.

There is an article by Allen Levine on the Adobe site on how to enable reader extensions using ColdFusion. Adobe has since released LiveCycle ES, which has improved the integration of the LiveCycle components and provided a web service that can be called without the need for any additional installs or changes to the standard installation. Additionally ColdFusion 8 has made it easier to call and debug web services.

The LiveCycle web service can accept Dime, Mime or Base64 encoded files. The example below uses Base64.

<CFSCRIPT>   

// Define username/password.
// Change to match your installation
creds = structnew();
  creds ['username']='administrator';
  creds ['password']='password';   

// Create web service
wsdl = "http://127.0.0.1/readerExtensions.wsdl";
readerExtensions = createObject("webservice", wsdl, creds);   

// Encode pdf
pdfBase64 = tobinary(ToBase64(ipFile.toByteArray(),
  "iso-8859-1"));   

// Create the structs needed for the web serivce
inPDFDoc = structNew();
  inPDFDoc['contentType'] = "application/pdf";
  inPDFDoc['attachmentID'] = javacast('null','');
  inPDFDoc['remoteURL'] = javacast('null','');
  inPDFDoc['binaryData'] = pdfBase64;   

usageRights = structNew();
  usageRights['enabledComments'] = TRUE|FALSE;
  usageRights['enabledCommentsOnline'] = TRUE|FALSE;
  etc   

applyOptions = structNew();
  applyOptions['message'] = "";
  applyOptions['modeFinal'] = TRUE;
  applyOptions['usageRights'] = usageRights;   

applyUsageRightsRequest = structNew();
  applyUsageRightsRequest['inPDFDoc'] = inPDFDoc;
  applyUsageRightsRequest['credentialAlias'] = credAlias;
  applyUsageRightsRequest['credentialPassword'] = credPassword;
  applyUsageRightsRequest['applyOptions'] = applyOptions;   

// Call web service
applyUsageRightsResponse = readerExtensions.applyUsageRights
  (inPDFDoc,credentialAlias,credentialPassword, applyOptions);   

// decode blessed pdf
pdfBinary = ToBinary(applyUsageRightsResponse.binaryData);   

</CFSCRIPT>

When you install LiveCycle Reader Extensions you will get a certificate from Adobe. You define the credentialAlias and credentialPassword values when installing the certificate.

The only tricky part is providing structures of the correct format to the web service. There are a couple of useful flags to help track down any ambiguities or problems with the wsdl:

creds ['saveJava']=TRUE;
creds ['refreshWSDL']=TRUE;

Add these to the creds struct in the example above, These ensure you have the latest wsdl and also instructs ColdFusion to save the intermediate java files that it creates. These will contain the class definitions which map to the above ColdFusion structures.

7 Responses to “Acrobat Reader Extensions”

  1. Rob Ward says:

    Hi David,

    Great article. This is something we’ve been looking at for a while.
    Your’s is the only article I’ve been able to find.

    Do you have any more information or code examples on how best to integrate LiveCycle ES and CFMX?
    Appreciate your efforts.
    Thanks!
    Rob

  2. David Rutter says:

    The easiest way to integrate LiveCycle ES and ColdFusion, is to use web services. The example above can be adapted to your own workflows or any of the default ones.

    The default LiveCycle web services are listed in the documentation under ‘Invoking LiveCycle ES Using Web Services’.

    If efficiency becomes an issue consider changing from base64 encoded attachments to MIME, or create your own LiveCycle web service to take pathnames rather than attachments.

    The alternative to SOAP web services is to use the Java API which uses Java RMI. Given that documents will still need to be serialized, and that ColdFusion isn’t strongly typed, I don’t see any worthwhile advantages in using the Java API.

  3. Rob Ward says:

    Hi David,

    Thanks for the response.
    Few changes but that worked!

    Question though.
    If we want to publish a pdf for review (web accessible location), how do get we embed the link to the livecycle server so that when the pdf is opened remotely, it pushes the shared review comments back to this?
    Can’t seem to find this in the wsdl

    Thanks again!

    Rob

  4. Hi,

    can you please also publish an example for Forms ES called via SOAP from ColdFusion!

    Thanks.
    Sven

  5. [...] the following example on calling the LiveCycle Reader Extensions web [...]

  6. Aditya Marla says:

    Hi,
    Can anyone tell me a way how to use Annotations on PDF using LiveCycle .. I am nwe to Adobe LiveCycle and not sure which one to use.. weather its ReaderExtensions .. or Desing ES or Digital Signatures.. or many more.Can u please let me know … My requirement is .. to Open a PDF in a Browser .. add annotations and display it next time. I have a few questions for the same.. How to save the annotations on the PDF when Openining on the Web Browser, How to store the PDF & Annotations ?? Coz i need to display the PDF wth and without annotations..

    I am trying for this for the past one month it would be great if someone could help me ..

    Thanks and Regards
    Aditya Marla

Leave a Reply