2023.1:PDF Data Mapping (Behavior): Difference between revisions

From Grooper Wiki
← Older editNewer edit →
No edit summary
Redirected page to PDF Data Mapping - 2021
Tag: New redirect
Line 1: Line 1:
{|cellpadding="10" cellspacing="5"
#REDIRECT [[PDF Data Mapping - 2021]]
|-style="background-color:#ed2330; color:white"
|style="font-size:14pt"|
'''2021'''
|This article is in development for the upcoming version of Grooper, '''Grooper 2021'''.  ''PDF Data Mapping'' is a new '''Content Type''' '''''Behavior''''' option in 2021.  This information is incomplete and/or may change by the time of release.
|}
 
<blockquote style="font-size:14pt">
''PDF Data Mapping'' is a '''Content Type''' '''''Behavior''''' designed to create an exportable PDF file with additional native PDF elements, using the classification and extraction content of a '''Batch Folder'''.  This includes capabilities to export extracted data as PDF metadata, inserting bookmarks, and creating PDF annotations, such as highlighting, checkbox and signature widgets.
</blockquote>
 
== About ==
 
{|cellpadding="10" cellspacing="5"
|-
|style="font-size:14pt; color:#f89420; border: 2px solid #f89420"|'''&#x2357;'''
|style="border: 2px solid #f89420"|
You may download and import the file below into your own Grooper environment (version 2021).  This contains a '''Batch''' with example document(s) discussed in this article and a '''Content Model''' configured according to its instructions.
* [[Media:PDF Generate Behavior (v2021).zip]]
|}
 
''PDF Data Mapping'' '''''Behavior''''' allows Grooper users to more fully leverage the capabilities of the PDF file type.  The standard PDF '''''Export Format''''' in Grooper will use the page image files and their text data to create a multipage PDF file for each document folder upon '''Export'''.  However, this is just the "display information" required to open and read the document.  There's a lot more to what a PDF can be than just a multipage document with page images and machine readable text.  PDF content can also include metadata, keywords, bookmarks, annotations, and more! 
 
''PDF Data Mapping'' creates an exportable PDF file that includes some of this additional content available to the PDF format.  This is part of Grooper's evolving "Smart PDF Architecture".  This is a design philosophy striving to more fully utilize the capabilities of the PDF file type and merge them with Grooper's own document processing capabilities.
 
The expanded ''PDF Data Mapping'' functionality can be divided into three categories:
* '''''Annotations'''''
* '''''Bookmarks'''''
* '''''Metadata'''''
 
<tabs style="margin:20px">
<tab name="Annotations" style="margin:20px">
=== Annotations ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:50%"|
Annotations are additional objects you can add to PDF documents.  Grooper uses information from '''Data Elements''' in a '''Data Model''' collected during the '''Extract''' activity to add these annotations (also called "widgets").  These annotations can increase the readability and add components for the reader to interact with the document, such as checkboxes and signature boxes.
 
The kinds of annotations you can add are:
 
# Highlighting
# Radio group buttons
# Checkboxes
# Signature boxes
# Editable text boxes
 
Grooper uses the data instance information from extracted '''Data Fields''' to insert these annotations.  For example, here we set up a '''Content Model''' with a '''Data Field''' named "Last Name".  After the document's data was collected during the '''Extract''' activity, Grooper has a data instance it can associate with the "Last Name" '''Data Field''', including its size and location coordinates on the document.  We then used the ''Highlight Annotation'' to highlight the extracted last name on the document in yellow.
 
The size of all these annotations can also be adjusted using a '''''Padding''''' property if the size of the extracted data instance is too small for your needs.
|
[[File:Pdf-generate-about-05.png]]
|}
</tab>
<tab name="Bookmarks" style="margin:20px">
=== Bookmarks ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:50%"|
Bookmarks allow easy navigation for multipage PDF documents.  When exporting a single PDF comprised of multiple child sub-documents, you can create bookmarks for each child document.  This way, you can keep all the documents together in a single PDF file, easily navigating from one section of the document to another.
 
For example, this document is an application packet for a study abroad program.  Each document in the packet was separated and classified as a child document folder of one '''Document Type''' or another.  ''PDF Data Mapping'' was used to export the packet as a single PDF and a bookmark was inserted for each sub-document and named after its '''Document Type'''.
 
Grooper can create bookmarks from extracted '''Data Fields''' in the document as well.
|
[[File:Pdf-generate-about-06.png]]
|}
</tab>
<tab name="Metadata" style="margin:20px">
=== Metadata ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:50%"|
Metadata refers to a PDF file's content beyond the information required to display the document (the page images and encoded text data).  Prior to implementing the ''PDF Data Mapping'' functionality, Grooper only had access to edit minimal PDF metadata, notably the file's name upon export.  ''PDF Data Mapping'' allows Grooper to alter and store additional collected metadata as well, including '''Data Field''' values collected during the '''Extract''' activity.  This means Grooper can now create a viewable document with all the extracted data associated with the document itself, independent of that data being stored elsewhere (such as a database table or content management system).
 
This metadata can be accessed by opening a PDF in a PDF viewer application, such as Adobe Acrobat, and opening the "Document Properties" window from the File menu.
|
[[File:Pdf-generate-about-07.png]]
|-
|valign=top|
There are several pieces of metadata Grooper has access to.
 
# All of the fields highlighted here can be created from Grooper, using an expression based syntax to access data extracted from the document and system information.
# Note this gives Grooper the capability to generate and insert keywords into the PDF's "Keywords" field.
#* In this case, Grooper has created a keyword based on the word count length of the essay in this study abroad application packet.
# Extracted '''Data Field''' values can also be exported as PDF metadata.  This information can be viewed either using the "Custom" tab or the "Additional Metadata..." window.
|
[[File:Pdf-generate-about-08.png]]
|-
|valign=top|
# In the "Custom" tab...
# You can see all the '''Data Fields''' Grooper extracted and their values as custom metadata for this document.
 
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#f89420; color:white"
|style="font-size:22pt"|'''&#9888;'''
|
Be aware the PDF file format has metadata fields already named "Title", "Author", "Subject", "Keywords", "Creator", "Producer", "CreationDate", "ModDate" and "Trapped".
 
You may run into an issue upon export if you have '''Data Fields''' in your '''Data Model''' who share one of these names.  If using the '''''Metadata''''' creation capabilities of ''PDF Data Mapping'', consider these names "taken" and adjust the name of the '''Data Field''' to be something different.  For example, in this case a '''Data Field''' returning the title of the proposal listed on the application was changed from "Title" to "Title of Proposal"
|}
|
[[File:Pdf-generate-about-09.png]]
|}
</tab>
</tabs>
 
{|cellpadding=10 cellspacing=5
|style="width:40%" valign=top|
As a '''''Behavior''''', ''PDF Data Mapping'' is configured on a '''Content Type''' object, commonly a '''Content Model''' or a '''Document Type'''.
 
# Here, we have selected a '''Content Model''' in the Node Tree.
# To add a '''''Behavior''''', select the '''''Behaviors''''' property and press the ellipsis button at the end.
# This will bring up a dialogue window to add various behaviors to the '''Content Model''', including ''PDF Data Mapping''.
# Add ''PDF Data Mapping'' to the list using the "Add" button.
# Select ''PDF Data Mapping'' from the listed options.
|
[[File:Pdf-generate-about-01.png]]
|-
|valign=top|
# Once added, you will see a ''PDF Data Mapping'' item added to the '''''Behaviors''''' list.
# Selecting this '''''Behavior''''', you will see property options to configure PDF creation.
 
 
The expanded ''PDF Data Mapping'' functionality can be divided into three categories:
* '''''Metadata'''''
* '''''Bookmarks'''''
* '''''Annotations'''''
 
 
Before we get into what these properties do, how to configure them, and how they effect the exported PDF, there's one key thing to keep in mind when using''PDF Data Mapping''.
|
[[File:Pdf-generate-about-02.png]]
|-
|valign=top|
Along with the ''PDF Data Mapping'' '''''Behavior''''', you will also need an ''Export Behavior'' configured to export a PDF formatted file.  The ''PDF Data Mapping'' '''''Behavior''''' does the job of configuring all the extra content (metadata, bookmarks and/or annotations) you want to add to the exported PDF.  The ''Export Behavior'' does the job of actually creating the PDF (with the content configuration information supplied by the ''PDF Data Mapping'') and sending it off to an external storage platform.
 
''Export Behaviors'' can be added to '''Content Types''', such as the '''Content Model''' here. 
 
# To add an ''Export Behavior'', press the "Add" button in a '''''Behaviors''''' list collector.
# Select ''Export Behavior''.
 
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#36b0a7; color:white"
|style="font-size:14pt"|'''FYI'''
|
''Export Behaviors'' can also be configured on the '''Export''' activity as local ''Export Behaviors'' to the activity configuration.
 
The benefit to adding it to a '''Content Model''' is you will often use information collected from a '''Content Model''' upon exporting your documents, such as a document folder's classified '''Document Type''' or collected data from a '''Data Model''' for field mapping purposes.  You might as well do it now, adding it to the '''Content Model''' while you're adding the ''PDF Data Mapping''.
|}
|
[[File:Pdf-generate-about-03.png]]
|-
|valign=top|
Once the ''Export Behavior is added'', you will need to add an '''''Export Definition'''''.  This will control how the file is exported, most notably where the file is exported.  Whether exporting to a Windows file system, or an IMAP email mailbox, or a CMIS content management system, Grooper needs to know where to put the file.  An '''''Export Definition''''' is how Grooper knows where the file goes. 
 
'''Importantly for the ''PDF Data Mapping''''', you will also use an '''''Export Definition''''' to define what type(s) of file you want to export.  For whichever '''''Export Definition''''' you choose, you will need to ensure you've configured an '''''Export Format''''' for a PDF formatted file in order to export the generated PDF.
 
# To add an '''''Export Definition''''', select the property and press the ellipsis button at the end.
# This will bring up an '''''Export Definitions''''' list collector window.
# Here, we've added a ''CMIS Export'' definition, using a '''CMIS Connection''' to a local NTFS folder.
#* The '''''Export Definition''''' is up to you and your needs.  There are many different external storage platforms Grooper can export to.
# Note, we've added a ''PDF Format'' configuration to the '''''Export Formats''''' property.
 
We will review some specifics of the ''PDF Format'' option's configuration later.  For now, just be aware adding a PDF '''''Export Format''''' is a ''necessary'' step to export the PDF file generated by ''PDF Data Mapping''.
|
[[File:Pdf-generate-about-04.png]]
|}
 
== How To ==
 
The following tutorials use a mock UNESCO Laura W. Bush Traveling Fellowship application to detail a more specific set up for a ''PDF Data Mapping''.  This is a packet of documents from a single applicant containing five different kinds of documents.
 
{|cellpadding="10" cellspacing="5"
|-
|style="font-size:14pt; color:#f89420; border: 2px solid #f89420"|'''&#x2357;'''
|style="border: 2px solid #f89420"|
You may download and import the file below into your own Grooper environment (version 2021).  This contains a '''Batch''' with the example document(s) discussed in this tutorial and a '''Content Model''' configured according to its instructions.
* [[Media:PDF Generate Behavior (v2021).zip]]
|}
 
<tabs style="margin:20px">
<tab name="Application" style="margin:20px">
=== Application ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
This document consists of two pages.  The first is a coversheet for the whole application packet.  The second is the application form itself.
 
Primarily, this document will allow us to demonstrate the different kinds of annotations available when using a ''PDF Data Mapping'' to generate a PDF file (using its '''''Annotations''''' property configuration).  We will see how to set up one example of each of the following annotation types available in Grooper:
* Highlight Annotation
* Checkbox Widget
* Radio Group Widget
* Signature Widget
* Textbox Widget
 
Importantly for any annotation type, a '''Data Field''' must be extracted in order to place the annotation.  How does Grooper know what you want to highlight?  It uses the extraction result of a '''Data Field''', which includes information about where that value is located on the page.  Even if the extraction result is just a blank zone without returning any actual information, Grooper needs some kind of coordinates to know where to place the annotation.
 
Since we're going to end up extracting some data in order to place these annotations, this will also give us the opportunity to see some of the collected data inserted as PDF metadata as well.
|
[[File:Pdf-generate-howto-docset-01.png]]
|
[[File:Pdf-generate-howto-docset-02.png]]
|}
</tab>
<tab name="Essay" style="margin:20px">
=== Essay ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
This application also includes an essay from the student.  This document will demonstrate how to add keywords to the PDF's metadata. 
 
We will use an extractor to count the number of words in the essay and configure the ''PDF Data Mapping's'' '''''Metadata''''' properties to insert a keyword of "long essay", "medium essay", or "short essay" depending on the essay's length.
|
[[File:Pdf-generate-howto-docset-03.png|400px]]
|}
</tab>
<tab name="Other Documents" style="margin:20px">
=== Other Documents ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
This packet contains three other kinds of documents as well:
* a proposal summary
* the applicant's resume
* and a letter of recommendation.
 
These documents (as well as the rest) will allow us to see how to insert bookmarks into the generated PDF, using the ''PDF Data Mapping's'' '''Bookmarking''' property configuration.
|
[[File:Pdf-generate-howto-docset-04.png]]
|
[[File:Pdf-generate-howto-docset-05.png]]
|
[[File:Pdf-generate-howto-docset-06.png]]
|-
|style="width:40%" valign=top|
The original document, imported as a single multipage PDF file, has been processed a bit to facilitate this.
 
# See here this document folder in the '''Batch''' is classified as an "UNESCO Application Packet" '''Document Type'''.  This '''Batch Folder''' was created upon importing the original application packet file, named "UNESCO Packet.pdf",
# The PDF document's pages were split out using the '''Split Pages''' activity to create child '''Batch Page''' objects.  This allowed us to separate the pages into child document folder for each of the documents inside the imported application packet.
# ''PDF Data Mapping'' can create a bookmark in the generated PDF for each of these five sub documents using the '''''Bookmarking''''' property.  Each bookmark will be named after their classified '''Document Type''' (i.e. "Application", "Proposal Summery", "Resume", etc.). 
 
This means we can process the full imported application packet document, and export a single file with easily navigable bookmarks for its component documents.  There's no need to export individual documents for each component document and figure out a way to index them, or put them in their own folder, or any other method you may come up with to relate them to each other in their final storage location.  With the ''PDF Data Mapping's'' bookmarking capabilities, you can export just one file with each child '''Document Type''' bookmarked.
|colspan=3|
[[File:Pdf-generate-howto-02.png]]
|}
</tab>
</tabs>
 
=== Configure PDF Generation for Annotations ===
 
<tabs style="margin:20px">
<tab name="About" style="margin:20px">
=== About ===
{|cellpadding=10 cellspacing=5
|style="width:40%" valign=top|
''PDF Data Mapping'' has the capability of inserting various annotations and native pdf widgets into the generated PDF.  This increases the document's readability and adds functionality for the reader to interact with the document through widgets such as radio group buttons, checkboxes and signature fields.
 
We will demonstrate how to configure one example for each of the '''''Annotation Types'''''.
# ''Highlight Annotation''
#* We will use Grooper to highlight the extraction result for the applicant's name on the document.
# ''Radio Group Widget''
#* Radio buttons are useful for documents when you have a collection of choices listed and can only select one option.  Such is the case for the "US Citizen" field on this document.  You either are or are not a US Citizen and can answer "Yes" or "No".  We will insert a radio group widget into this document to allow the user to toggle between these choices.
# ''Checkbox Widget''
#* It seems every standard form uses checkboxes for one thing or another.  This annotation will allow us to insert checkable checkboxes into the PDF file if located using OMR based extraction techniques.  For example, the checkboxes here next to each checklist item for the application packet.
# ''Signature Widget''
#* With the ''Signature Widget'' we can create a form-fillable signature box for the generated PDF.  Notice the document as imported is not signed.  With the ''PDF Data Mapping'' '''''Behavior''''' we can add a signature box to the processed file.  This way you could send the application back to the applicant and have them sign the document digitally.
|
[[File:Pdf-generate-howto-03.png]]
|-
|valign=top|
We will also use the ''Textbox Widget'' to insert editable text boxes into the document's coversheet.  These text boxes will also be populated with some corresponding information from the rest of the document.
 
# A textbox will be created for the "Candidate" on the coversheet and populated with the applicant's first name, middle initial and last name (Dog O Doggerson).
# A textbox will be created for the "Title" on the coversheet and populated with the proposal title (Who's a Good Boy?)
# A textbox will be created for the "Country of Travel" on the coversheet and populated with the proposed travel country for the study abroad program (Japan).
|
[[File:Pdf-generate-howto-04.png]]
|}
</tab>
<tab name="Prereqs - Data Fields & Extracted Data" style="margin:20px">
=== Prereqs - Data Fields & Extracted Data ===
Before a PDF annotation can be generated, a document's data must be extracted.  Put another way, the '''Extract''' activity must run ''before'' the '''Export''' activity (when the ''PDF Data Mapping'' ultimately builds the PDF and exports it).
 
Each of the '''''Annotation Types''''' point to a '''Data Field''' in a '''Data Model''' as part of their configuration.  If the '''Data Field''' does not collect data during the '''Extract''' activity, the ''PDF Data Mapping'' won't know where to place the annotation.
 
{|cellpadding=10 cellspacing=5
|style="width:40%" valign=top|
# We will ultimately configure ''PDF Data Mapping'' using the '''''Behaviors''''' property of this '''Content Model''' which we've named "PDF Generate - UNESCO Packet"
#* Before we do that, we will need to ensure we have '''Data Fields''' that correspond to the annotations we want to place.
# We've added the necessary '''Data Fields''' to the '''Content Model's'''  '''Data Model'''.
# The "Candidate", "Title of Proposal", and "Country of Travel" '''Data Fields''' will be used to place the ''Textbox Widget'' annotations.
# The "Last Name", "First Name", and "Middle Initial" '''Data Fields''' will be used to place the ''Highlight Annotation'' annotations.
# The "US Citizen" '''Data Field''' will be used to place the ''Radio Group Widget'' annotation.
# The "Application", "Proposal Summary", "Essay", "Resume" and "Recommendation Letter" '''Data Fields''' will be used to place the ''Checkbox Widget'' annotations.
# The "Signature" '''Data Field''' will be used to place the ''Signature Widget'' annotation.
|
[[File:Pdf-generate-howto-05.png]]
|}
</tab>
<tab name="Add the Behavior" style="margin:20px">
=== Add the Behavior ===
{|cellpadding=10 cellspacing=5
|style="width:40%" valign=top|
Annotations are one of the configuration options for the ''PDF Data Mapping'' '''''Behavior'''''.  A '''Content Type''' '''''Behavior''''' can tell an activity (specifically the '''Export''' activity, in the case of ''PDF Data Mapping'') how to use the '''Content Type''' to do something (how to use the '''Content Model's''' collected '''Data Fields''' to insert additional content when generating a PDF upon export, in this case).
 
# All '''''Behaviors''''' are added to a '''Content Type''' object.
#* We will add the ''PDF Data Mapping'' '''''Behavior''''' to this '''Content Model''' named "PDF Generate - UNESCO Packet".
# All '''''Behaviors''''' are added using the '''''Behaviors''''' property.  Select the '''''Behaviors''''' property and press the ellipsis button at the end to add ''PDF Data Mapping''.
# This will bring up the '''''Behaviors''''' editor window.
# Press the "Add" button to add a '''''Behavior'''''.
# Choose "PDF Data Mapping" from the list.
|
[[File:Pdf-generate-howto-06.png]]
|-
|valign=top|
# Once added, you will see ''PDF Data Mapping'' added to the list on the left.  Select it to add an '''''Annotation'''''.
# In the right panel, select the '''''Annotations''''' property and press the ellipsis button at the end.
# This will bring up an '''''Annotations''''' collection editor.
 
We will detail collection and configuration of the various '''''Annotation Types''''' in the next tabs of this tutorial.
|
[[File:Pdf-generate-howto-07.png]]
|}
</tab>
<tab name="Highlight Annotation" style="margin:20px">
=== Highlight Annotation ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:50%"|
 
 
 
 
We will look at the ''Highlight Annotation'' first.  This annotation is what it sounds like.  You can use it to highlight portions of a PDF. 
 
In this example, we will use the ''Highlight Annotation'' to highlight the extracted "Last Name", "First Name" and "Middle Initial" fields from the application form.
|
{|
|style="text-align:center"|
''Before Annotation''
|-
|
[[File:Pdf-generate-howto-08.png]]
|-
|style="text-align:center"|
''After Annotation''
|-
|
[[File:Pdf-generate-howto-09.png]]
|}
|}
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
# In the '''''Annotations''''' collection editor, press the "Add" button to add the ''Highlight Annotation'' annotation.
#* Refer to the previous tab if you are unclear how we got to this window in '''Grooper Design Studio'''.
# Select ''Highlight Annotation'' from the list.
|valign=top|
[[File:Pdf-generate-howto-10.png]]
|-
|valign=top|
# This will add a ''Highlight Annotation'' to the '''''Annotations''''' list.
# The only configuration that is ''strictly required'' is to indicate which '''Data Fields''' you wish to highlight.  Use the '''''Fields''''' property to select which '''Data Fields''' you wish to highlight.
#* Whatever result is returned by the selected '''Data Fields''' will be used to create the highlighted annotation.
# Using the dropdown list, select the '''Data Fields''' you wish to highlight.
#* In our case, we are choosing the "Last Name", "First Name", and "Middle Initial" '''Data Fields'''.  Once collected by the '''Extract''' activity, Grooper will know where these results are located on the document.  The ''Highlight Annotation'' annotation will then highlight the document as seen in the "''After Annotation''" image above.
|
[[File:Pdf-generate-howto-11.png]]
|-
|valign=top|
Optionally, you can control how the highlight looks.  Its color, size, opacity and whether or not there's a stroke around the highlighted rectangle.
 
# For instance, we set the '''''Padding''''' property to ''0.1in''
#* This will increase the size of the highlight rectangle by 0.1 inches on all sides.
#* All annotations have the ability to be padded to increase their size, not just ''Highlight Annotation''.
#* You can also expand the '''''Padding''''' property's sub properties to adjust specific configurations for padding the '''''Left''''', '''''Top''''', '''''Right''''', and '''''Bottom'''''' edges.
# While we did not choose to do so, you can add a colored border around the highlighted rectangle by choosing a '''''Border Style''''' (such as ''Solid'' for a solid border or ''Dashed'' for a dashed line border)
#* The '''''Border Color''''' and '''''Border Width''''' properties will further help you configure the border produced.
#* Note:  While the '''''Border Color''''' and '''''Border Width''''' properties are configured to ''64, 64, 64'' and ''1pt'' by default, the '''''Border Style''''' is set to ''None'' by default.  With no border produced, these properties are ignored.  They will not be used to create a border until you choose a '''''Border Style'''''.
# We also set the '''''Fill Color''''' to ''Yellow''.
#* Grooper defaults to green.  This is the same green you see extraction results highlighted when you're testing out extractors in '''Grooper Design Studio'''.
#* You can select colors using a dropdown list or use comma-separated values in the RBG color space.  For example, "yellow" is also ''255, 255, 128'' in the RBG color space.
|valign=top|
[[File:Pdf-generate-howto-12.png]]
|}
</tab>
<tab name="Radio Group Widget" style="margin:20px">
=== Radio Group Widget ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:50%"|
 
 
 
 
The ''Radio Group Widget'' annotation allows you to add radio buttons to the document.  Radio buttons are common PDF elements used to indicate a single choice from multiple options in a list.  This ''PDF Data Mapping'' '''''Annotation Type''''' uses OMR extraction techniques (such as ''Labeled OMR'' and ''Zonal OMR'') to find existing checkboxes on the document.  A group of radio buttons are then overlaid on top of the checkboxes when the ''PDF Data Mapping'' '''''Behavior''''' builds the PDF file.
 
For example, we will create a ''Radio Group Widget'' annotation from the "US Citizen" '''Data Field's''' result.  We have two choices, either "Yes" or "No".  Only one or the other can be chosen.  So, this is well suited for a radio button group.
|
{|
|style="text-align:center"|
''Before Annotation''
|-
|
[[File:Pdf-generate-howto-13.png]]
|-
|style="text-align:center"|
''After Annotation''
|-
|
[[File:Pdf-generate-howto-14.png]]
|}
|}
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
# In the '''''Annotations''''' collection editor, press the "Add" button to add the ''Radio Group Widget'' annotation.
#* Refer to the "Add the Behavior" tab if you are unclear how we got to this window in '''Grooper Design Studio'''.
# Select ''Radio Group Widget'' from the list.
|valign=top|
[[File:Pdf-generate-howto-15.png]]
|-
|valign=top|
# This will add a ''Radio Group Widget'' to the '''''Annotations''''' list.
# The only configuration that is ''strictly required'' is to indicate which '''Data Fields''' you wish to use to create the radio buttons.  Use the '''''Fields''''' property to select these '''Data Fields'''.
#* Whatever result is returned by the selected '''Data Fields''' will be used to draw and insert the radio buttons.
#* You may use the '''''Padding''''' property to adjust the size of the radio button if you desire.
#* These '''Data Fields''' ''must'' use an OMR based extraction method (''Labeled OMR'', ''Ordered OMR'', or ''Zonal OMR'') to insert the radio buttons.
# Using the dropdown list, select the '''Data Fields''' you wish to use to create the group of radio buttons.
#* In our case, we are choosing the "US Citizen" '''Data Field'''.  Once collected by the '''Extract''' activity, Grooper will know which results you want to use to create the radio buttons.  This will include the checkbox locations and check states stored in the document's layout data.  The ''Radio Group Widget'' annotation will then insert radio buttons into the generated PDF as seen in the "''After Annotation''" image above.
|valign=top|
[[File:Pdf-generate-howto-16.png]]
|-
|valign=top|
Let's briefly look at this "US Citizen" '''Data Field''' and see what's happening behind the scenes when ''PDF Data Mapping'' creates the radio buttons.
 
# We have selected the "US Citizen" '''Data Field''' in the '''Grooper''' Node Tree.
# This '''Data Field''' uses the ''Labeled OMR'' extractor to return its result, looking for checkboxes next to the labels "Yes" and "No" on the document.
# The box next to "Yes" is checked.  This is ultimately the result returned to the "US Citizen" '''Data Field'''.
#* This is how the ''Radio Group Widget'' annotation knows where to place the radio button.  The data instance used to insert the PDF radio button is drawn around the detected box (in this case highlighted in green in the Document Viewer).
#* Since this is the detected checked result, the radio button is configured as "pressed" upon outputting the generated PDF.
# The box next to "No" is not checked.  The ''Radio Group Widget'' will also create radio buttons for the unchecked boxes next to labels on the document as well.
#* The alternate candidate data instances are used to insert the other PDF radio buttons in the group (in this case highlighted in red in the Document Viewer).
#* The unchecked boxes ''must'' be detected from a '''Box Detection''' or '''Box Removal''' '''IP Command''' in order to be inserted in the generated PDF.  They ''must'' be present in the document's layout data file ''before'' the '''Extract''' activity runs.
#* Since this is detected as an unchecked result, the radio button is not pressed upon outputting the generated PDF.
|
[[File:Pdf-generate-howto-17.png]]
|}
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#36b0a7; color:white"
|style="font-size:14pt"|'''FYI'''
|
{|cellpadding=10 cellspacing=5
|valign=top style="width:50%"|
In the case of every '''''Annotation Type''''', ''PDF Data Mapping'' inserts the annotation by overlaying it on top of the document.  This can be important to keep in mind for all annotations but is often particularly relevant when inserting radio buttons using the ''Radio Group Widget''.
 
Notice the original image for this document used checkboxes, not radio buttons.  We see an "X" inside of a square box.
|
[[File:Pdf-generate-howto-18.png]]
|-
|valign=top|
The radio button annotations are simply overlaid on the page's image.  You can actually see the edges of the square box persist in the generated PDF (Here, highlighted in yellow for your viewing pleasure).
 
In this case, the boxes were stored in the layout data using the '''Box Detection''' '''IP Command'''.  This will find and store the checkbox locations and check states, but not actually alter the image in any way.
|
[[File:Pdf-generate-howto-19.png]]
|-
|valign=top|
Maybe you care about this, and maybe you don't.  If you do, you may consider using the '''Box Removal''' '''IP Command''' instead.  '''Box Removal''' will also find and store the checkbox locations and their check states, but it will ''also'' digitally remove the checkboxes from the document's image.
 
In this case, the boxes were stored in the layout data using the '''Box Removal''' '''IP Command'''.  Since the boxes are removed before the '''Export''' activity, the edges of the boxes are not present on the final image.  The radio button annotations are placed on blank pixels.
|
[[File:Pdf-generate-howto-20.png]]
|}
</tab>
<tab name="Checkbox Widget" style="margin:20px">
=== Checkbox Widget ===
{|cellpadding="10" cellspacing="5"
|-style="background-color:#ed2330; color:white"
|style="font-size:14pt"|'''WIP'''||The ''Checkbox Widget'' documentation needs to be finalized after getting some guidance from dev.  If it seems incomplete or images don't match up with text, that is why.
|}
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:50%"|
 
 
 
 
''PDF Data Mapping'' also has the capability to insert form-fillable checkboxes as well, using the ''Checkbox Widget'' '''''Annotation Type'''''.  This '''''Annotation Type''''' also uses OMR extraction techniques (such as ''Labeled OMR'' and ''Zonal OMR'') to find existing checkboxes on the document.  It works a lot like the ''Radio Group Widget'' annotation, just instead of radio buttons, editable checkboxes are overlaid on the document.
 
For example, we will create a ''Checkbox Widget'' annotation for the checkboxes in the "Checklist" section of this document, the "Application", "Proposal Summary", "Essay", "Resume" and "Recommendation Letter" '''Data Fields'''.  These are Boolean OMR checkboxes, returning "true" if the box next to the corresponding label is checked, and "false" if unchecked.  In either case, checked or not, the ''Checkbox Widget'' will insert an editable checkbox element into the generated PDF.
|
{|
|style="text-align:center"|
''Before Annotation''
|-
|
[[File:Pdf-generate-howto-13.png]]
|-
|style="text-align:center"|
''After Annotation''
|-
|
[[File:Pdf-generate-howto-14.png]]
|}
|}
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
# In the '''''Annotations''''' collection editor, press the "Add" button to add the ''Checkbox Widget'' annotation.
#* Refer to the "Add the Behavior" tab if you are unclear how we got to this window in '''Grooper Design Studio'''.
# Select ''Checkbox Widget'' from the list.
|valign=top|
[[File:Pdf-generate-howto-21.png]]
|-
|valign=top|
# This will add a ''Checkbox Widget'' to the '''''Annotations''''' list.
# The only configuration that is ''strictly required'' is to indicate which '''Data Fields''' you wish to use to create the checkboxes.  Use the '''''Fields''''' property to select these '''Data Fields'''.
#* Whatever result is returned by the selected '''Data Fields''' will be used to draw and insert the checkboxes.
#* You may use the '''''Padding''''' property to adjust the size of the checkboxes if you desire.
#* These '''Data Fields''' ''must'' use an OMR based extraction method (''Labeled OMR'', ''Ordered OMR'', or ''Zonal OMR'') to insert the checkboxes.
# Using the dropdown list, select the '''Data Fields''' you wish to use to create the checkboxes.
#* In our case, we are choosing the "Application", "Proposal Summary", "Essay", "Resume" and "Recommendation Letter" '''Data Fields'''.  Once collected by the '''Extract''' activity, Grooper will know which results you want to use to create the checkboxes.  This will include the checkbox locations and check states stored in the document's layout data.  The ''Checkbox Widget'' annotation will then insert checkboxes into the generated PDF as seen in the "''After Annotation''" image above.
|valign=top|
[[File:Pdf-generate-howto-22.png]]
|}
</tab>
<tab name="Signature Widget" style="margin:20px">
=== Signature Widget ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:50%"|
 
 
 
 
Form-fillable signature boxes can be inserted using the ''Signature Widget'' annotation.  This '''''Annotation Type''''' uses a zonal extraction type (such as ''Detect Signature'' or ''Highlight Zone'') to draw the boundaries of the inserted signature widget.  This allows you to create a document that can be digitally signed straight from Grooper upon exporting the generated PDF.
 
For example, we will create a ''Signature Widget'' annotation for the signature line on the application form, using the "Signature" '''Data Field''' of our '''Data Model.  The ''Checkbox Widget'' will insert an interactable signature element into the generated PDF.
|
{|
|style="text-align:center"|
''Before Annotation''
|-
|
[[File:Pdf-generate-howto-23.png]]
|-
|style="text-align:center"|
''After Annotation''
|-
|
[[File:Pdf-generate-howto-24.png]]
|}
|}
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
# In the '''''Annotations''''' collection editor, press the "Add" button to add the ''Signature Widget'' annotation.
#* Refer to the "Add the Behavior" tab if you are unclear how we got to this window in '''Grooper Design Studio'''.
# Select ''Signature Widget'' from the list.
|valign=top|
[[File:Pdf-generate-howto-25.png]]
|-
|valign=top|
# This will add a ''Signature Widget'' to the '''''Annotations''''' list.
# The only configuration that is ''strictly required'' is to indicate which '''Data Fields''' you wish to use to create the signature box.  Use the '''''Fields''''' property to select these '''Data Fields'''.
#* Whatever result is returned by the selected '''Data Fields''' will be used to draw and insert the signature box widget.
#* You may use the '''''Padding''''' property to adjust the size of the signature box if you desire.
#* Zonal based extraction methods (such as ''Signature Detection'' and ''Highlight Zone'') are typically used as the '''Data Field's''' extractor type.
# Using the dropdown list, select the '''Data Fields''' you wish to use to create the checkboxes.
#* In our case, we are choosing the "Signature" '''Data Field'''.  Once collected by the '''Extract''' activity, Grooper will be supplied the size and location of the '''Data Field's''' extraction zone, which will form the size and location of the PDF signature widget. The ''Signature Widget'' annotation will then insert the form-fillable signature box into the generated PDF as seen in the "''After Annotation''" image above.
|valign=top|
[[File:Pdf-generate-howto-26.png]]
|}
 
Just like any '''''Annotation Type''''', the extraction result from the '''Data Field''' is critical for placing the signature annotation on the generated PDF.  Let's look at the "Signature" '''Data Field's''' result to understand a little better how these results are used to create the signature widget.
 
In our case, we're using the ''Detect Signature'' extractor type to supply these results.  The ''Detect Signature'' extractor is perfectly suited for the ''Signature Widget'' '''''Annotation Type'''''. 
* It actually combines both Zonal and OMR based extraction techniques to determine if a signature is present in the zone.  It sets the boundaries of where you expect to find a signature using Zonal based methods and detects if the signature is present by counting the percentage of filled pixels in the zone, which is the basis of OMR based extraction methods.  You can then output different values if the zone is filled above or below a certain percentage.  In this case, the extractor returns "Not Signed" because there aren't enough pixels present in the extraction zone to count as filled.  If there were a signature present, there'd be more pixels present, accounting for a higher filled percentage.
 
This is great for our purposes because it gives us the exact information we need for the ''Signature Widget'', which is an extraction zone.  Grooper needs a data instance indicating the size and location for the generated signature widget.
* But wait there's more!  We also get some bonus information about whether or not there's a signature present.  Does the ''Signature Widget'' '''''Annotation Type''''' need to know if there's a signature present?  No.  It does not.  It will place the widget no matter what the result is.  But might that information be otherwise useful to you?  Probably.
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
# We have selected the "Signature" '''Data Field''' in our '''Data Model'''.
# This '''Data Field''' uses the ''Detect Signature'' extractor to draw the extraction zone used to insert the signature widget.
# This extractor uses the ''Text Region'' '''''Location''''' option.
# This gives us the ability to anchor the extraction zone to an extractable text anchor, using the '''''Text Extractor''''' property.
#* In this case we've anchored the zone to the word "Signature" outlined in blue in the document viewer.  Where do we want to place the extraction zone (and ultimately the signature widget)?  On the signature line.  How do we know where that line is?  It's above the text label "Signature".
# The extraction zone itself is drawn using the '''''Translation''''' and '''''Adjustment''''' properties.
#* This allows us to set the size ('''''Adjustment''''') and location ('''''Translation''''') of the extraction zone (and ultimately the signature widget) relative to the '''''Text Extractor's''''' result. 
#* The extraction zone is the green rectangle in the document viewer.
# When the ''PDF Data Mapping'' '''''Behavior''''' builds the PDF, using the ''Signature Widget'' annotation, the extraction zone's size and location forms the inserted signature widget.
|valign=top|
[[File:Pdf-generate-howto-27.png]]
|}
</tab>
<tab name="Textbox Widget" style="margin:20px">
=== Textbox Widget ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:50%"|
 
 
 
 
 
The ''Textbox Widget'' '''''Annotation Type''''' will insert editable text boxes into the generated PDF.  One simple way to use this functionality is to use the ''Highlight Zone'' extractor type to place a blank zone where you want to place an empty text box on the PDF.  However, any extractor type can be used to define the textbox's location.  Furthermore, if the '''Data Field''' used to create the annotation collects a valued during the '''Extract''' activity, not only will a textbox be inserted into the generated PDF, but it will be prefilled with the '''Data Field's''' extracted value upon export.
 
For example, we will use the ''Textbox Widget'' functionality to fill out the blank coversheet on the first page of our application packet.  We will end up using a ''Highlight Zone'' extractor to define the size and location of the text box.  However, we're going to go one step further and populate the '''Data Field's''' used with some information from other '''Data Field's''' in our '''Data Model'''.  By the end of it, ''PDF Data Mapping'' will not only insert editable textboxes into the generated PDF, but fill them in with text.  By the end of it, we end up with this blank coversheet automatically populated with some information collected during the '''Extract''' activity.
|
{|
|style="text-align:center"|
''Before Annotation''
|-
|
[[File:Pdf-generate-howto-28.png]]
|-
|style="text-align:center"|
''After Annotation''
|-
|
[[File:Pdf-generate-howto-29.png]]
|}
|}
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
# In the '''''Annotations''''' collection editor, press the "Add" button to add the ''Textbox Widget'' annotation.
#* Refer to the "Add the Behavior" tab if you are unclear how we got to this window in '''Grooper Design Studio'''.
# Select ''Textbox Widget'' from the list.
|valign=top|
[[File:Pdf-generate-howto-30.png]]
|-
|valign=top|
# This will add a ''Textbox Widget'' to the '''''Annotations''''' list.
# The only configuration that is ''strictly required'' is to indicate which '''Data Fields''' you wish to use to create the signature box.  Use the '''''Fields''''' property to select these '''Data Fields'''.
#* Whatever result is returned by the selected '''Data Fields''' will be used to draw and insert the textbox widget.  If that '''Data Field''' collected a value during the '''Extract''' activity, it will also be filled with the returned value.
# Using the dropdown list, select the '''Data Fields''' you wish to use to create the checkboxes.
#* In our case, we are choosing the "Candidate", "Title of Proposal" and "Country of Travel" '''Data Fields'''.  Once collected by the '''Extract''' activity, Grooper will be supplied the sizes and locations of the '''Data Field's''' data instances for each result.  This will form the size and location of the textbox widget. The ''Textbox Widget'' annotation will then insert the form-fillable textbox into the generated PDF as seen in the "''After Annotation''" image above.  These boxes will also be prefilled with the extraction results from each '''Data Field'''.
|valign=top|
[[File:Pdf-generate-howto-31.png]]
|-
|valign=top|
The ''Textbox Widget'' annotation has some additional configuration options as well.
 
# As with all '''''Annotation Types''''', you can optionally adjust the size of the annotation using the '''''Padding''''' property.
# You can also change the font and font size of the editable text in the textbox using the '''''Font Name''''' and '''''Font Size'''''.
|
[[File:Pdf-generate-howto-32.png]]
|-
|valign=top|
As far as looking behind the scenes, there's at least two things going on with how we've set up these '''Data Fields'''' extraction, ultimately supplying the result used to insert the ''Textbox Widget'' annotation. 
 
First, we used the ''Highlight Zone'' extractor type to draw the textbox, defining the size and location of the annotation upon generating the PDF.
 
# We have selected the "Candidate" '''Data Field''' in our ''''Data Model'''.
# Each '''Data Field's''' '''''Value Extractor''''' is set to ''Highlight Zone''.
# We used the ''Relative Region'' '''''Location''''' option to anchor an extraction zone to the box next to the label "Candidate".
#* This will form the size and and location of the inserted textbox annotation.
 
Second, we used an expression to return a value, using the results of other '''Data Fields''' in our '''Data Model'''.
 
#<li value = 4> We've used the '''''Calculated Value''''' property (in '''''Calculate Mode''''' ''Always Set'') to return the full name of the candidate extracted by the "Last Name", "First Name", and "Middle Initial" '''Data Fields'''
#* The full expression is as follows: <code>Applicant_Information.First_Name + " " + Applicant_Information.Middle_Initial + " " + Applicant_Information.Last_Name</code>
# This will take the extraction results of these three '''Data Fields''' and concatenate them with space characters in between.
# However, if we test extraction at this point, we're going to get an error.
#* We're in the wrong scope!  We need to go up to the '''Data Model's''' level and test extraction there.  We need the full '''Data Model's''' results to do what we're trying to do here.  Testing extraction on this "Candidate" '''Data Field''', it can't "see" the "Last Name", "First Name" and "Middle Initial" '''Data Fields''' results to combine them.
|
[[File:Pdf-generate-howto-33.png]]
|-
|
# Once we test extraction on the '''Data Model''' you'll see what results are actually collected by the '''Extract''' activity.
# The '''''Calculated Value''''' expression we configured forms one result for the "Candidate"...
# ...using the results of the "Last Name", "First Name" and "Middle Initial" '''Data Field's''' results.
# With a result returned and zone drawn upon extract, the ''Textbox Widget'' annotation has all the information it needs to place the form-fillable textbox and fill it with the results.
 
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#36b0a7; color:white"
|style="font-size:14pt"|'''FYI'''
|
This certainly isn't the '''only''' way to set up a '''Data Field''' for a ''Textbox Widget''.  This is just how we did it for the point of illustrating the ''Textbox Widget'' functionality.  You are not '''required''' to use the ''Highlight Zone'' extractor type.  You can use whatever extractor type best suits your document's needs.  Often Grooper users will use the ''Reference'' extractor to point to a '''Data Type's''' results and adjust the size of the ''Textbox Widget'' using its '''''Padding''''' property.
|}
|
[[File:Pdf-generate-howto-34.png]]
|}
</tab>
</tabs>
 
=== Configure PDF Generation for Bookmarks ===
 
<tabs style="margin:20px">
<tab name="About" style="margin:20px">
=== About ===
 
Bookmarks in PDFs aid readers when navigating through multipage documents.  ''PDF Data Mapping'' can insert bookmarks into the generated PDF to take advantage of this functionality.  This can be done in one of two ways (or both):
 
# Using a '''Batch Folder's''' child document folders.
# Using the document's extracted '''Data Fields'''.
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:50%"|
We will focus on the bookmarking method (as it is more common).  Often it is the case you will import a file into Grooper that has multiple documents inside you want to separate and classify, but otherwise all belong together in one way or another.
 
Such is the case with our study abroad application packet.  The application packet as a whole consists of five separate and distinguishable documents.
# The application itself (and a coversheet)
# A proposal summary
# The student's resume
# A letter of recommendation
# An essay
|
[[File:Pdf-generate-howto-35.png]]
|-
|valign=top|
Our goal is to create a bookmark in the generated PDF file for each of these component documents (or child documents as we will come to call them). 
 
Rather than exporting five separate PDF files for each component document, we will export a single PDF for the whole packet with navigable bookmarks corresponding to each component document.
# Application - For the application itself (and its coversheet)
# Proposal Summary - For the proposal summary
# Resume - For the student's resume
# Rec Letter - For the letter of recommendation
# Essay - For the essay
|
[[File:Pdf-generate-about-06.png]]
|}
 
</tab>
<tab name="Prereqs - Split Pages, Separation and Classification" style="margin:20px">
=== Prereqs - Split Pages, Separation and Classification ===
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
In order to accomplish this goal, we're going to have to do some things to this application packet before we configure ''PDF Data Mapping''.
 
By the end of it, we're looking for a '''Batch''' whose documents have a structure like this.  The documents in this batch consist of two '''Batch Folder''' levels.
# '''Folder Level 1''':  This is the parent document folder.  It is the container for the full document.  All seven pages of the application packet in this case.
# '''Folder Level 2''':  These are the child document folders for the parent document.  They are the containers for each component document of the full application packet.
 
This is what we want to end up with.  How did we get there?  Long story short, we have some document separation and classification requirements before we can insert bookmarks in the generated PDF.  The bookmarks are inserted for each child document folder and named after their classified '''Document Type's''' name.  In order to do that, we need to split out the pages of the imported document, separate them into child document folders, and classify them first.
|
[[File:Pdf-generate-howto-36.png]]
|-
|valign=top|
The full application document came into Grooper like this. A 7 page PDF file with each of these 5 component documents was imported into a new '''Batch'''.  This is now the parent document folder at '''Folder Level 1'''.
 
But there's documents in them there document!  How do we get them out?
|
[[File:Pdf-generate-howto-37.png]]
|-
|valign=top|
First, we need to use the '''Split Pages''' activity to create child '''Batch Page''' objects. 
 
This will split out the pages of the imported PDF file, creating one child '''Batch Batch''' for each page in PDF on the parent document folder.  Now we have page objects we can manipulate in our '''Batch'''.
|
[[File:Pdf-generate-howto-38.png]]
|-
|valign=top|
Now that we have '''Batch Page''' objects in our '''Batch''', we can use the '''Separate''' activity to insert the second folder level.  This is the first step in organizing these pages into child documents.  We need to distinguish between one collection of pages as a document and another collection of pages as a document.  Creating a folders is the first part of that equation.
 
Now, we have child document folders for this parent document folder, but they are just blank folders.  There is nothing to distinguish one folder from the next.
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#f89420; color:white"
|style="font-size:22pt"|'''&#9888;'''||By default, the '''Separate''' activity runs on the '''Batch''' level scope, inserting folders at Folder Level 1.  When separating child documents like this, you will need to change the '''''Scope''''' property of the '''Separate''' activity to run it at the '''Folder Level 1''' scope.  This will separate the loose pages of folders at Level 1, inserting child document folders at Level 2 below the parent folder at Level 1.
|}
|
[[File:Pdf-generate-howto-39.png]]
|-
|valign=top|
And, that's the second part of the organization equation, classification.  Next, these folders will be assigned a '''Document Type''' from our '''Content Model''' using the '''Classify''' activity.
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#f89420; color:white"
|style="font-size:22pt"|'''&#9888;'''||By default, the '''Classify''' activity runs on the '''Folder Level 1''' scope, classifying document folders at the first folder level in the '''Batch''' hierarchy.  We want to classify the child document folders at '''Folder Level 2'''.  When classifying child document folders like this, you will need to change the '''''Scope''''' property of the '''Classify''' activity to run at the '''Folder Level 2''' scope.
 
Furthermore, that parent document folder would need a '''Document Type''' assigned to it at some point as well.  The '''Batch Process''' for this '''Batch''' might have two '''Classify''' activities.  One running on Folder Level 1 to classify the parent document folder and another running on Folder Level 2 to classify the child document folders.
|}
 
Now, we have everything we need to configure the bookmarking functionality of ''PDF Data Mapping''.  Bookmarks will be created every time a new child document is encountered and named after the '''Document Type''' assigned to that folder. 
 
When the full PDF is generated, a bookmark named "Application" will be inserted at the first page of the PDF.  That child document is two pages long.  The third page of the full PDF will be the proposal summary.  So a bookmark named "Proposal Summery" will be inserted at page three.  A "Resume" bookmark will be inserted at page four.  And so on.
|
[[File:Pdf-generate-howto-40.png]]
|}
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#36b0a7; color:white"
|style="font-size:14pt"|'''FYI'''
|
There are many ways to separate and classify documents, including ''[[ESP Auto Separation]]'' which both separates and classifies documents with a single activity (just '''Separate''').  But this is the general idea to get us where we need to go. 
 
One way or another, create classified child document folders from a parent document folder.  That way when we generate the PDF for the parent document folder upon export, bookmarks will be created for the classified child document folders.
|}
</tab>
<tab name="Add the Behavior and Configure It for Bookmarking" style="margin:20px">
=== Add the Behavior and Configure It for Bookmarking===
{|cellpadding=10 cellspacing=5
|style="width:40%" valign=top|
Bookmarking is one of the configuration options for the ''PDF Data Maping'' '''''Behavior'''''.  A '''Content Type''' '''''Behavior''''' can tell an activity (specifically the '''Export''' activity, in the case of ''PDF Data Mapping'') how to use the '''Content Type''' to do something (in this case, how to use the '''Content Model's''' '''Document Types''' to insert bookmarks into the PDF upon export).
 
# All '''''Behaviors''''' are added to a '''Content Type''' object.
#* We will add the ''PDF Data Mapping'' '''''Behavior''''' to this '''Content Model''' named "PDF Generate - UNESCO Packet".
# All '''''Behaviors''''' are added using the '''''Behaviors''''' property.  Select the '''''Behaviors''''' property and press the ellipsis button at the end to add the ''PDF Data Mapping'' '''''Behavior'''''.
# This will bring up the '''''Behaviors''''' editor window.
# Press the "Add" button to add a '''''Behavior'''''.
# Choose "PDF Data Mapping" from the list.
|
[[File:Pdf-generate-howto-06.png]]
|-
|valign=top|
# Once added, you will see ''PDF Data Mapping'' added to the list on the left.  Select it.
# To enable the bookmarking functionality, in the right panel, select the '''''Bookmarking''''' property.
# Change it from ''Disabled'' to ''Enabled''.
|
[[File:Pdf-generate-howto-41.png]]
|-
|valign=top|
For our purposes, this is all we need to configure at this point.  However, be aware of the '''''Bookmarking''''' configuration options.
 
# The '''''Label''''' property allows you to alter the generated bookmark names using an expression editor.
#* Left blank, Grooper will use the '''Document Type's''' name for each child document encountered, which is exactly what we want to do.  We will leave this property unconfigured.
# The '''''Enable Data Bookmarks''''' allows you to create bookmarks using the locations of extracted '''Data Field''' results.
#* Set this property from ''False'' to ''True'' if you want to use this feature.
#* Once set to ''True'' you may also choose to insert bookmarks for every '''Data Field''' in the '''Content Type's''' '''Data Model''' or manually select which ones you want to use to create bookmarks.
|
[[File:Pdf-generate-howto-42.png]]
|}
</tab>
</tabs>
 
=== Configure PDF Generation for Metadata ===
 
<tabs style="margin:20px">
<tab name="About" style="margin:20px">
=== About ===
{|cellpadding=10 cellspacing=5
|style="width:50%" valign=top|
The ''PDF Data Mapping'' ''''''Behavior''''' has the ability to create and insert additional metadata into the generated PDF as well, using information collected during Grooper's document processing.  The metadata you are able to create falls into one of three categories:
 
# Editing the PDF's default metadata fields.
#*This includes the following metadata fields that are standard to every PDF file:
#** Title
#** Author
#** Subject
#** Created Date
#** Modified Date
#** Application (Used to establish the "creator" application which created the original file.  This can be useful if the original file was created in a different application, like Microsoft Word, and converted to a PDF format by Grooper with a ''PDF Data Mapping''.)
# Creating custom metadata fields
#* This is done using extracted '''Data Field''' values collected during the '''Extract''' activity.
# Adding "Keywords" to the PDF metadata
#* This can be done using expression based or extraction based methods.
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#f89420; color:white"
|style="font-size:22pt"|'''&#9888;'''
|
Notice what's not included in this list is the exported document's ''filename'' (i.e. "Im_a_file.pdf").  Filename mappings are always configured using an ''Export Behavior''.
|}
|
[[File:Pdf-generate-howto-43.png]]
|}
 
 
</tab>
<tab name="Prereqs - Data Extraction" style="margin:20px">
=== Prereqs - Data Extraction ===
 
If we're going to insert some metadata into these PDFs, that data has to come from somewhere.  In broad terms, the metadata creation is done in one of two ways (or a combination of the two):
 
# Using expression based creation
#* In the case of the default PDF metadata fields and keywords, expressions can be used to populate the metadata.  This gives you access to system data, classification information, extracted '''Data Field''' results, and various .NET functions to manipulate it.
# Using '''Data Field''' results
#* In the case of the custom PDF metadata, the custom fields are generated from '''Data Fields''' in the document's '''Data Model''' and their collected results from the '''Extract''' activity.
#* This means the document ''must'' be processed by the '''Extract''' activity in order to create and populate these custom fields.
</tab>
<tab name="Add the Behavior and Enable Metadata" style="margin:20px">
=== Add the Behavior and Enable Metadata ===
{|cellpadding=10 cellspacing=5
|style="width:40%" valign=top|
Metadata is one of the configuration options for the ''PDF Data Mapping'' '''''Behavior'''''.  A '''Content Type''' '''''Behavior''''' can tell an activity (specifically the '''Export''' activity, in the case of ''PDF Data Mapping'') how to use the '''Content Type''' to do something (how to use the '''Content Model's''' collected '''Data Fields''' and other information to edit the generated PDF's metadata, in this case).
 
# All '''''Behaviors''''' are added to a '''Content Type''' object.
#* We will add the ''PDF Data Mapping'' '''''Behavior''''' to this '''Content Model''' named "PDF Generate - UNESCO Packet".
# All '''''Behaviors''''' are added using the '''''Behaviors''''' property.  Select the '''''Behaviors''''' property and press the ellipsis button at the end to add the ''PDF Data Mapping'' '''''Behavior'''''.
# This will bring up the '''''Behaviors''''' editor window.
# Press the "Add" button to add a '''''Behavior'''''.
# Choose "PDF Data Mapping" from the list.
|
[[File:Pdf-generate-howto-06.png]]
|-
|valign=top|
# Once added, you will see ''PDF Data Mapping'' added to the list on the left.  Select it.
# To enable the metadata functionality, in the right panel, select the '''''Metadata''''' property.
# Change it from ''Disabled'' to ''Enabled''.
|
[[File:Pdf-generate-howto-44.png]]
|}
</tab>
<tab name="Edit Default PDF Metadata" style="margin:20px">
=== Edit Default PDF Metadata ===
 
Once enabled, the first six '''''Metadata''''' sub-properties all pertain to the default PDF metadata fields Grooper can edit:  Title, Author, Subject, Creation Date, Modified Date, and Creator
 
These are edited with code expressions.
 
{|cellpadding=10 cellspacing=5
|style="width:40%" valign=top|
# The '''''Title''''' property corresponds to the PDF's "Title" field.
#* By default, this expression is set to <code>CurrentDocument.ContentTypeName</code>
#** This will make the title whatever the document's '''Document Type''' classification is.
#** In our case, these document folders are assigned the "UNESCO Application Packet" '''Document Type''' of our '''Content Model'''.
# The '''''Author''''' property corresponds to the PDF's "Author" field.
#* By default, this expression is set to <code>LDAP.CurrentUserDisplayName</code>
#** This will make the author the display name of whatever user is logged into the machine exporting the documents.
#* We've changed this to <code>Candidate</code>
#** This will make the author the result of the "Candidate" '''Data Field''' (which is "Dog O Doggerson" for our example document).
# The '''''Creator''''' property corresponds to the PDF's "Application" field.
#* This field is intended to be used when generating PDFs from different file types.  For example, if the file was originally a Microsoft Word document, you might enter <code>"Microsoft Word"</code> to fill this field.
#* This field is blank by default, and we have left it so.
# The '''''Subject''''' property corresponds to the PDF's "Subject" field.
#* This field is blank by default.
#* We've decided to populate this field with the extracted proposal title, using the results of the "Title of Proposal" '''Data Field''' and the expression <code>Title_of_Proposal</code>
#** Note: Spaces in '''Data Fields''' must be replaced with underscores in expressions.
# The '''''Creation Date'''''' and '''''Modification Date''''' properties correspond to the PDF's "Created" and "Modified" fields.
#* By default, these both use the expression <code>DateTime.Now</code>
#** This will return the current system time of your machine at the time of export.
|valign=top|
[[File:Pdf-generate-howto-45.png]]
|-
|valign=top|
# When we open the document in Adobe Acrobat and view these fields using the "Document Properties" window, you can see the metadata this configuration generated for the PDF.
|
[[File:Pdf-generate-howto-46.png]]
|}
</tab>
<tab name="Add Keywords" style="margin:20px">
=== Add Keywords ===
 
Grooper can add keywords into the PDF's "Keywords" field in one of two ways, either using an expression or a referenced extractor's results.
 
{|cellpadding=10 cellspacing=5
|style="width:40%" valign=top|
In our case, we're going to use an expression to determine if the word count of the "Essay" document in the application packet is "Long", "Short", or "Normal".
 
# We will use the results of the "Essay Word Count" '''Data Field''' of our '''Data Model''' to do this.
# This '''Data Field's''' extraction is configured to count the number of words in the essay.
 
If the word count is above 600 words, we'll call that a long essay.  If it's below 400 words, we'll call that a short essay.  And if it's anywhere in between, we'll call it a normal essay.
 
The expression below uses a series of nested conditional statements using the IIf() function to accomplish this. 
 
: <code>IIf(Essay_Information.Essay_Word_Count > 600, "Long Essay", IIf(Essay_Information.Essay_Word_Count > 400, "Normal Essay", "Short Essay"))</code>
 
If the result is greater than 600 the keyword will evaluate to "Long Essay".  Otherwise, if the result is less than 400, the keyword will evaluated to "Short Essay".  If neither condition is met, the keyword evaluates to "Normal Essay".
|
[[File:Pdf-generate-howto-47.png]]
|-
|valign=top|
To use this expression to add the keyword to the generated PDF's metadata, we will configure the '''''Keywords''''' property.
 
# In the '''''Metadata''''' sub-properties, select the '''''Keywords''''' property and press the ellipsis button at the end.
# This will bring up an expression editor.
#* As is the case with any expression editor, Grooper's IntelliSense code completion will aid you when writing your code expressions.
# Enter the expression you wish to use create the keywords.
# Press "OK" when you're finished.
|
[[File:Pdf-generate-howto-48.png]]
|-
|valign=top|
# When we open the generated PDF in Adobe Acrobat and view the "Document Properties" window, you can see the metadata this configuration generated for the PDF.
#* The keyword "Normal Essay" has been added to the keywords list.
#* The extracted value for the "Essay Word Count" field was 485, which is less than 600 and greater than 400.  Evaluated by our '''''Keywords''''' expression, that returns a value of "Normal Essay".
|
[[File:Pdf-generate-howto-49.png]]
|}
</tab>
<tab name="Add Custom Metadata" style="margin:20px">
=== Add Custom Metadata ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
Last but not least, you can add custom metadata fields to the generated PDF using extraction results from the document's '''Data Model'''.  A custom metadata field is generated for every '''Data Field''' you choose in the '''Content Type's''' '''Data Model'''.
 
# Remember, we add '''''Behaviors''''' to '''Content Types''' (Typically a '''Content Model''' or a '''Document Type''').  In this case we're adding the ''PDF Data Mapping'' '''''Behavior''''' to the '''Content Model'''
# '''Content Models''' and '''Document Types''' can have their own '''Data Models''' as one of their children.  Configuring ''PDF Data Mapping'' on the '''Content Model''', we will utilize ''its'' '''Data Model''' to export this custom metadata.
# This '''Data Model''' is configured with several '''Data Fields'''.  These '''Data Fields''' will collect information about the "UNESCO Application Packet" and its component documents, such as the applicant's name and information about the proposal. 
#* This will be done during the '''Extract''' activity.  Once collected, ''PDF Data Mapping'' can insert the results into the generated PDF, creating one custom metadata field and corresponding result for each '''Data Field''' and its extracted result.
|
[[File:Pdf-generate-howto-50.png]]
|-
|
To do this, we will use the '''''Export Data Fields''''' option of ''PDF Data Mapping's'' '''''Metadata''''' properties.
 
# In the '''''Metadata''''' sub-properties, change '''''Export Data Fields''''' from ''False'' to ''True''
# By default, once you enable this property, Grooper will export all available '''Data Fields''' to the '''Content Type''' on which ''PDF Data Mapping'' is configured.
#* You can be more selective about what you want to include using the '''''Field Filter''''' property.
#* This will give you a drop down list of all the '''Data Field''' nodes available for custom PDF metadata creation.  You can check the box next to which ones you wish to include, leaving those '''Data Fields''' you wish to exclude unchecked.
|
[[File:Pdf-generate-howto-51.png]]
|-
|valign=top|
# When we open the generated PDF in Adobe Acrobat and view the "Document Properties" window, you can see the custom metadata generated in the "Custom" tab.
# The '''Data Fields'''' names show up in the "Names" column.
#* Note: '''Data Fields''' in '''Data Sections''' will have their names appended to the '''Data Section's''' name.  For example the "Proposal Title" '''Data Field''' in the "Proposal Information" '''Data Section's''' name translates to "Proposal_Information.Proposal_Title".
# The '''Data Field's''' result, collected by the '''Extract''' activity show up in the "Value" column.
 
{|cellpadding="10" cellspacing="5"
|-style="background-color:#f89420; color:white"
|style="font-size:22pt"|'''&#9888;'''
|
Be aware the PDF file format has metadata fields already named "Title", "Author", "Subject", "Keywords", "Creator", "Producer", "CreationDate", "ModDate" and "Trapped".
 
You may run into an issue upon export if you have '''Data Fields''' in your '''Data Model''' who share one of these names.  If using the '''''Metadata''''' creation capabilities of ''PDF Data Mapping'', consider these names "taken" and adjust the name of the '''Data Field''' to be something different.  For example, in this case a '''Data Field''' returning the title of the proposal listed on the application was changed from "Title" to "Title of Proposal"
|}
|
[[File:Pdf-generate-howto-52.png]]
|-
|valign=top|
# You can also access this data using the "Additional Metadata..." button in the "Description" tab.
# Select the "Advanced" item.
# You'll see all the generated custom metadata listed under the "<nowiki>http://ns.adobe.com/pdfx/1.3/</nowiki>" node.
|
[[File:Pdf-generate-howto-53.png]]
|}
</tab>
</tabs>
 
=== Export the Generated PDF ===
 
There's one last crucial step to using the ''PDF Data Mapping'' '''''Behavior'''''.  Exporting the generated PDF. 
 
There's no point in generating the PDF with all this additional metadata, bookmarks and annotations if you don't get it out of Grooper and into some kind of external storage platform.  That's the job of the '''Export''' activity.  To properly export the PDF generated by the ''PDF Data Mapping'' there are some specific requirements to keep in mind.
 
<tabs style="margin:20px">
<tab name="Add an Export Behavior" style="margin:20px">
=== Add an Export Behavior ===
 
In order to export any document from Grooper, you need to configure an ''Export Behavior'' for the '''Export''' activity to know how you want to export document folders in a '''Batch''' and what external storage platform you're exporting them to.  So, it makes sense this would be part of exporting the PDF generated by the ''PDF Data Mapping''.
* And if you want to be really technical, the '''Export''' activity (using an ''Export Behavior'' configuration) will truly "generate" the PDF file, in terms of creating it.  ''PDF Data Mapping'' gives the ''Export Behavior'' additional information about how to generate it, utilizing the additional metadata, bookmarking, and annotation elements.
 
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
There are two ways you can configure an ''Export Behavior'':  "Locally" to the '''Export''' activity or "Shared" with a '''''Behavior''''' configuration for a '''Content Type''' object (typically a '''Content Model''')
 
Configured "locally", you will set the ''Export Behavior'' configuration using the '''Export''' activity's properties.
 
# For example, we have selected a working '''Batch Process''' in the Grooper Node Tree.
# The last step in this '''Batch Process''' is an '''Export''' activity.
# You configure a local ''Export Behavior'' using the '''''Export Behaviors''''' property.
|
[[File:Pdf-generate-howto-54.png]]
|-
|valign=top|
Configured as a "shared" '''''Behavior''''', the ''Export Behavior'' is configured using a '''Content Type's''' '''''Behaviors''''' property.
 
# For example, we have selected our "PDF Generate - UNESCO Packet" '''Content Model''' we've been working with in the Grooper Node Tree.
# Like any other '''''Behavior''''', the ''Export Behavior'' is added to the '''Content Model''' using the '''''Behaviors''''' property.
# Pressing the ellipsis button at the end of the '''''Behaviors''''' property will bring up the '''''Behaviors''''' list editor.
# Add the ''Export Behavior'' by pressing the "Add" button.
# Select ''Export Behavior'' from the list.
|
[[File:Pdf-generate-howto-55.png]]
|-
|
{|cellpadding="10" cellspacing="5"
|-style="background-color:#f89420; color:white"
|style="font-size:22pt"|'''&#9888;'''
|
If you configure the ''Export Behavior'' on a '''Content Type''' you '''must''' use a '''''Shared Behavior Mode''''' when configuring the '''Export''' activity.
|}
 
The '''Export''' activity needs to know how to export your documents.  That's what an ''Export Behavior'' is for.  If one is not configured locally, you need to let the '''Export''' activity know you want to use an ''Export Behavior'' configured on the '''Content Type''' or '''Document Types''' of the documents in the '''Batch'''.
 
Furthermore, if you configure ''both'' a local ''Export Behavior'' and a shared ''Export Behavior'', Grooper needs to know what one takes priority.  That's why there are four different '''''Shared Behavior Mode''''' options.
 
* ''LocalOrShared'' - This will execute the shared ''Export Behavior'' configured locally to the '''Export''' activity ONLY IF there are no matching local ''Export Behaviors'' for the document's '''Content Type'''.
** Local behaviors will override shared behaviors.
* ''SharedOrLocal'' - This does the opposite.  Local ''Export Behaviors'' will execute ONLY IF there are no matching shared ''Export Behaviors'' for the document's '''Content Type'''.
** Shared behaviors override local behaviors.
* ''LocalAndShared'' - Local ''Export Behaviors'' execute first.  If they fail to export a document, shared ''Export Behaviors'' will then execute.
* ''SharedAndLocal'' ' Shared ''Export Behaviors'' execute first.  If they fail to export a document, local ''Export Behaviors'' will then execute.
 
These options will allow you to configure the order of execution logic for instances where you have both local and shared ''Export Behaviors'' configured. 
 
However, be aware configuring both is less common.  Most Grooper users will elect to configure the ''Export Behavior'' on either the '''Content Type''' or the '''Export''' activity, but not both.  But, if you are electing to configure the ''Export Behavior'' on a '''Content Type''', you still ''must'' choose one of these four '''''Shared Behavior Mode''''' options.
|valign=top|
[[File:Pdf-generate-howto-56.png]]
|}
</tab>
<tab name="Configure the Export Behavior to Export PDFs" style="margin:20px">
=== Configure the Export Behavior to Export PDFs ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
Whether you elect to use a local or shared ''Export Behavior'', the next step is to configure it to export the document folders in the '''Batch''' as PDF files.
 
# First, you will need to add an '''''Export Definition'''''.  This will define where and how the documents are exported.
# Pressing the ellipsis button at the end of this property will bring up the '''''Export Definitions''''' list editor.
# Press the "Add" button to select the '''''Export Type'''''.  This controls where the documents are going.  What external storage platform will store the generated PDF.
# This is up to you and your needs.  The option you select just needs to be a storage platform that supports the PDF file format.
#* We will choose "File Export" which performs a simple export to the Windows File System.
|
[[File:Pdf-generate-howto-57.png]]
|-
|valign=top|
The last piece of the puzzle is just telling the ''Export Behavior'' what file format you want to use for the exported documents.  To take advantage of ''PDF Data Mapping'', we will want to tell it to export the documents as PDFs.
 
# Next, you will want to find the '''''Export Formats''''' property.
#* Depending on the '''''Export Type''''' selected, this property may be in a different order in the property grid.  Or for '''''Export Types''''' that don't support different formats, this property will not be present (such as the ''Data Export'' which just exports data to a database, not files).
# Press the ellipsis button at the end to bring up the '''''Export Formats''''' list editor.
|
[[File:Pdf-generate-howto-58.png]]
|-
|valign=top|
# Press the "Add" button to add an '''''Export Format'''''.
# Select ''PDF Format'' from the list.
|
[[File:Pdf-generate-howto-59.png]]
|}
</tab>
<tab name="Additional Formatting Considerations" style="margin:20px">
=== Additional Formatting Considerations ===
{|cellpadding=10 cellspacing=5
|valign=top style="width:40%"|
As far as the ''PDF Format'' property configuration goes, there are two properties that are particularly relevant to how it interacts with ''PDF Data Mapping''.
 
# If you are using ''PDF Data Mapping'' to insert bookmarks, you will need to enable the '''''Bookmarks'''''' property.
#* You will find this property under the '''''Build Options''''' set of properties.
#* Enable '''''Bookmarks''''' by changing this property from ''False'' to ''True''
# Depending on how your documents were sourced on import, you may need to enable the '''''Always Build''''' mode as well.
#* Such is actually the case in the workflow we've simulated in this tutorial.  We processed these UNESCO study abroad application packets from an imported PDF, which we split out into individual page objects, so we could separate out the component '''Document Types''' that comprised the full file.  The ''original'' PDF file from import lives on the parent document's '''Batch Folder''' object.  If you leave '''''Always Build''''' set to ''False'', that imported file living on the parent document folder is what will get exported, ''not'' the PDF built by the ''PDF Data Mapping'' with additional metadata, bookmarking and annotation elements.
#* If you run into a situation where the output PDF does not reflect the ''PDF Data Mapping'' configurations you've set up, a good first troubleshooting step is changing '''''Always Build''''' to ''True'' to ensure the exported file is the ''PDF Data Mapping'' built PDF and not the original (also called "native") pre-processed PDF.
 
The remaining ''PDF Format'' property configurates apply more generally to PDF file creation.  While they may be important to your end goals, they are independent from ''PDF Data Mapping'' concerns.
|
[[File:Pdf-generate-howto-60.png]]
|}
 
</tab>
</tabs>
 
== Version Differences ==
 
'''''Behaviors''''' are a new functionality in '''Grooper 2021'''.  Much of the ''PDF Data Mapping'' '''''Behavior's''''' functionality was not available in previous versions.  Prior to version '''2021''', only annotation creation was possible using the '''[[Generate PDF]]''' activity.  In version '''2021''', this activity has been replaced by the ''PDF Data Mapping''' '''''Behavior''''', expanding its capabilities to generate bookmarks and document metadata as well.

Revision as of 11:20, 30 August 2021

Redirect to:

Retrieved from "https://wiki.grooper.com/index.php?title=2023.1:PDF_Data_Mapping_(Behavior)&oldid=6982"