We have heard from a number of PDF users that one of the common workflows they run into is that a PDF Form has been designed to be used as a “template” that will be populated with data that customizes the PDF before it is sent out. This might sound a bit like the process that creates “junk mail” which is true, however, this workflow is useful in any space where there is a need to merge data from a data source into a PDF form. For example, data can be taken from a patient record and added into a PDF so that when a patient shows up at a hospital for a procedure, the forms already include patient information. This saves the patient time, provides a better overall experience, as well as prevents mistakes by minimizing the keying of data by hospital staff to complete the patient’s check in.
One of the common problems, though, that comes up in this workflow is that the data the PDF Form gets populated with does not always match the requirements of the PDF Form itself. For example, phone numbers may be stored with or without the hyphens that typically separate the country code from the area code. In order to produce consistent results without writing custom application code for every variant of the form, the logic for manipulating the data should be embedded in the PDF itself. Merging data and running validation scripts or formatting scripts should not require knowledge of the PDF, and that is exactly what we will be supporting with our PDF Java Toolkit.
Executing calculation and validation scripts when importing data into a PDF Form
We are excited to say that the new version of PDF Java Toolkit (8.7.0) will support running validation scripts when importing data with the FDFService or the XFDFService. This version is currently in QA and changes the default behavior of the FDFService.importForm and XFDFService.importFormData method so that they execute both the calculation and validation scripts. We are also providing overloaded methods that will allow you as the developer to pick which scripts should be run when importing data into forms.
Our FillForm sample for PDF Java Toolkit utilizes the FDFService or XFDFService methods that execute both calculation and validation scripts to demonstrate the functionality. It is important to note that validation scripts come in two flavors in PDF: there are scripts that can be executed when a user is typing into a form, known as keystroke scripts, and there are scripts that can be executed once the user has finished filling in a field, known as validation scripts. It is common to see these two pieces of logic written together as one script, dependent on whether the user is still typing in a graphical user interface. For PDF Java Toolkit, the concept of a user typing as a form is being filled in on the server does not really fit, and since the logic can be split into two places, we execute both when importing data. By executing both, the forms being used do not need to be modified to work with PDF Java Toolkit because, frankly, that would be a hassle for you. Let’s take a look at the new functionality along with a concrete example.
Between PDF Java Toolkit 8.5.0 and 8.7.0, the FillForm was refactored some and the code we are really interested in is in the FormImporter class. To keep things simple, let’s work with an XFDF dataset. This means the code we are interested in is around line 225 where we open an InputStream to the XFDF dataset and pass it into the XFDFService to import into the PDF.
final InputStream formStream = inputDataUrl.openStream(); XFDFService.importFormData(pdfDocument, formStream);
By default, this will run the calculation and validation scripts, if any exist in the PDF. If you want to try this out on your own, at the end of this post there is an input PDF that you can use that has keystroke scripts as well as a good and a bad dataset to try importing. Importing the bad dataset will result in the following exception:
Exception in thread "main" com.adobe.pdfjt.core.exceptions.PDFFieldValidationException: Return code from validate JavaScript was false, the field named 'quantity' was not updated
Unfortunately, importing data into a form is an all or nothing operation so if an exception occurs no data is imported into the PDF. At that point, it is up to you to determine how you want to recover. The best path forward will depend on how it is being used in your application. If you only want to run a certain type of script, that is also possible by modifying the line that calls the XFDFService to specify which scripts should be run. If you just wanted to run the calculation scripts, you would modify it so that it was the following instead:
XFDFService.importFormData(pdfDocument, formStream, EnumSet.of(Scripts.CALCULATE));
Depending on your use case, you may want to run all possible scripts or just a certain subset. No matter the use case though, PDF Java Toolkit is here to help reduce the complexity of working with PDF Forms and save you from making costly mistakes.
If you are a customer and you are interested in this new functionality, keep your eyes open for our next service bulletin announcing the availability of PDF Java Toolkit 8.7.0 . If you are not a customer and can benefit from integrating this functionality in your application, contact us for an evaluation and mention that you are interested in PDF Java Toolkit 8.7.0 so we can help you out!
The post Executing Calculation and Validation Scripts with PDF Java Toolkit appeared first on Datalogics Blog.
