Documentation
PDF Injector is a REDCap module that enables you to populate fillable PDFs with record data from variables.
Overview:
Installation
Important: Please read Requirements and Limitations before your proceed to setup and use the module!
Install automatically from REDCap Repo
You can download and install the latest version of PDF Injector from REDCap Repository of External Modules. If you open the Repo link from your REDCap instance, than automatic install will be triggered.
Install manually from Github Repository
You can download the latest release of the module from its releases page. Pleas ensure to download the pre-composed .zip file (redcap-pdf-injector-vX.X.X.zip), otherwise you have to run composer install --no-dev before installing on your server. To install the module on your server upload the unzipped module folder to /modules/ within your redcap instance.
After successfully installing the module you should be able to enable the module through Control Center on system level.
Configuration
Enable Debugging
If you have problems with the module you can output javascript console logs.
Set UI Mode
To define how your Injections should be displayed on the Record Home Page, choose the option in module configuration that suits you best.
Set Preview Mode
You can choose in module configuration settings how the filled PDF should be previewed on the record page: either within a modal or in a new tab. Previewing in a new tab has the advantage that you can configure your browser to directly open the PDF in Adobe Reader, that enhances given browsers issues as described below.
Learn here how to configure Firefox to chose another viewer for PDFs.
How to use
The standard procedure to use PDF Injector is to upload your ready made PDFs to REDCap, create an Injection and then Inject Record Data into a PDF. ADditionaly, you can edit, preview or delete your Injection.
Create Injection
You can add a new PDF Injection as follows:
0.Click on “Add new Injection”
A modal opens up where you can add your new Injection
1.Upload your PDF that satisfies given requirements and limitations. If the file is valid and has readable fields, than an automatic thumbnail of the PDF will be inserted and available fields will be listed under Step 2.
2.Add your title and description. This is important for organizing your documents.
3.Bind variables to given form fields.
4.Save (only valid “field - to - variable - bindings” are going to be saved). Anything invalid is going to be ignored. If everything goes fine you should see your new Injection in the overview.
Advanced use:
If you would like to fill multiple variables into a form field, you can use @CALCTEXT inside the field annotation of that field. PDF Injector can handle fields with CALCTEXT and also in combination with Smart Variables and Action Tags (please check Supported Action Tags section).
Preview Injection
You can preview your Injection to check if the variable that you have binded to PDF fields are shown correctly on the document. To preview an Injection click on “Preview” next to the Injection thumbnail.
Edit or Delete Injection
To edit an Injection click on “Edit” on the Injections overview page. A modal will open up where you can edit all data for that Injection. To delete click on “Delete” and Confirm your decision. This action cannot be undone.
Inject Record Data
To Inject Data for a Record and retrieve the PDF proceed as follows:
0.Ensure you have entered values for the variables that you have binded to your PDF fields.
1.On the Record Home Page for the record that you entered the data you will see a button “PDJ Injection”
2.Depending on your Preview Mode you will see after clicking on the relevant Injection your injected record data within a modal or in a new tab.
Advanced use:
To populate checkbox fields you need to return either a ‘true’ or ‘false’ value to that variable. The easiest way to achieve this is with REDCap field type “True/False”, but can also be done by returning true of false within @CALCTEXT.
Requirements and Limitations
Please notice that the current module version has several requirements. Ensure to test your setup before use in production.
Requirement 1: form fields
The PDF has to have form fields that can be filled (otherwise you will only output an unfilled PDF). It is recommended to use solid PDF Editors to create PDFs with form fields such as:
- Adobe Acrobat Pro (Commercial) Learn here how to create fillable pdf forms
- LibreOffice Writer (Free) Fillable PDF Forms With LibreOffice Writer
Requirement 2: readable and fillable
To make the PDF and its fields readable & fillable through PDF Injector we have to process the pdf with an open source tool called pdftk.
If you do not do this step, PDF Injector will not be able to scan your document and read the fields or fill them!
There are two ways of processing your PDFs with pdftk:
a. Use the pdfk web service to upload, convert and download your PDF. Alternatively, you can setup the pdftk web service on your own server/localhost. Go to pdftk-web-service-repository for setup instructions.
Please note: pdftk-web-service currently has some errors reported. In case you cannot convert your documents, it is recommended to use pdftk on your system (Option b).
b. Use pdftk for your system and run:
$ pdftk document.pdf output document_converted.pdf
// Check pdftk docs for further help
Limitation 1: PDF field types
Currently the following PDF field types are supported:
- Textfield: Insert text as one line or also as multiline (option multline for textfield has to be active)
- Checkbox: Insert a value that is true or false to tick or untick the checkbox. Please note: There have been errors reported when using this field type. Please test your setup carefully, before using for production.
Limitation 2: REDCap Action Tags
Currently the following Action Tags are supported during an injection:
- @TODAY: returns date in format “d.m.Y”
Known Issues
Firefox Browser
“This PDF document might not be displayed correctly.”: Direct printing within Mozilla Firefox PDF Preview is currently not possible. To ensure proper displaying & printing please download the file and open in Adobe Acrobat or use Chrome Browser.
REDCap calculated fields
In some cases it might be that an injection has not updated the values for its variables that correspond to @CALCTEXT. This is related to how REDCap handles calculated fields. To fix this please use the REDCap Data Quality application and execute Data Quality Rule #H: “Incorrect values for calculated fields”.