Thom Parker March 6, 2011
Was this tutorial useful to you?
The two most severe changes, one exciting and one depressing, have to do with how Acrobat interacts with external data in the context of workflow automation. These updates completely change how we think about automation scripting in Acrobat, and it is these bipolar updates that are covered here.
One of these holes was a clean and simple way to access data in an external file. It is common for the data used in a workflow to be stored in some external data source, such as a database, Excel, CSV or XML file. For example, say a document needs to be individually watermarked and labeled for each user, then e-mailed to each user. The user information is maintained in a CSV file on the local file system. Watermarking, labeling and e-mailing a PDF are all simple tasks for an automation script. The awkward part is getting the information out of the CSV file. In earlier versions of Acrobat, there were three different, general-purpose methods for solving this issue.
The missing object in the Acrobat X SDK is ADBC, which is used for accessing an ODBC-connected database. From a purely scripting perspective, direct database access is the simplest, cleanest solution for accessing external data. The ADBC object communicates with the DB through standard SQL, and this is the only method for accessing external data that allows the original data file to be modified.
Because of the security issues, Adobe took steps in Acrobat 8 to make it more difficult to use. A registry setting was added for turning ADBC on and off. The default value is off. As it turns out, this was also a heads-up to developers, “ADBC is Dead.” As of Acrobat X, the ADBC object no longer exists.
Ironically, the same technology as the ADBC object is implemented in the LiveCycle Scripting Model. It has the same limitations and awkwardness (Windows only, etc.), and is less secure because it operates from the document context and does not require a special registry setting.
So, if you are currently using ADBC in your automation scripts, you have the option to move to LiveCycle. Stefan Cameron has written a bit on this topic at his blog, ADBC Now Disabled by Default. I also have some information on LiveCycle database connections in an article titled, Acrobat, PDF, and Excel Spreadsheets.
If you had to choose only one thing to improve Acrobat automation scripting, you couldn’t do much better than adding a no-hassles function to read the contents of a disk file, and they did it. This is the best update made to the SDK, the util.readFileIntoStream()
For most automation scripting purposes the disk files, such as the CSV file used in the example above, will contain plain text. To use the data from the file, the stream needs to be converted into a text string. Fortunately, Acrobat provides an easy solution as shown in the following code:
//Read file data into stream var stmFileData = util.readFileIntoStream(); // Convert data into a String var strTextData = util.stringFromStream(stmFileData);
The first line calls the util.readFileIntoStream() function with no input parameters. However, this function does have two input parameters-- the file path and a Boolean for determining how the data is encoded in the stream object. If the file path is not specified, Acrobat displays the file open dialog to allow the user to browse for the file. If the user selects a file, the contents are returned as a stream object. If the user cancels the dialog, this function returns an “undefined” value. In the next line, the stream object is converted into a String using the util.stringFromStream function. The data can now be parsed using regular String functions.
If the file contains binary data, it cannot be converted directly into a string, so the stream data must be handled differently. The stream object has a read function for extracting the data as hexadecimal encoded text. Each two text characters read from the stream represents one byte of file data. To parse this data, you’ll need to know how every byte of data in the file is used. This is an advanced topic, but in general, a single byte can be converted into a number or text character with the following code:
//Acquire 1 byte of stream data, 2 text characters(Hex Encoded) var cDataByte = stmFileData.read(1); // Convert Data into a Number var nVal = parseInt("0x" + cDataByte); // Convert Data into a text character // (Assuming that it is in fact a text character var cVal = String.fromCharCode("0x" + cDataByte);
This tool could be extended to work with LiveCycle PDF forms and/or generalized to use data in the XML file to control which fields are populated on the form.
The script, i.e., the main function, is at the top of the “PopulateFieldsFromXML_Tool.js” file.
|Acrobat X ProAcrobat X StandardAcrobat X Suite|