Using PDF Templates
This section discusses how to:
Work with PDF templates.
Create PDF templates.
Map data tags.
PDF templates do not require an external plug-in for offline template design. A mapping feature for XML data element tags is enabled when the PDF template file is uploaded to the Reporting Tools, BI Publisher, Report Definition, Template page. The BI Publisher PDF mapping functionality enables you to match existing form fields in a PDF template with sample data field tags.
You only need to do mapping, if the form field names in the PDF template do not match the tag names in the XML data. This is usually the case when you are using a third-party PDF template (such as government form) and when it is not easy to customize the tag names in XML data to match the PDF form fields.
Observe the following guidelines when working with PDF templates regardless of whether you are mapping PDF template fields or tags:
The PDF document must allow editing.
Check the Security setting in the File, Document Properties, Summary page.
Files must be Adobe Acrobat 5.0-compatible.
If you are using a later version of Adobe Acrobat, select and select the Acrobat 5.0 and later value in theMake Compatible with: option.
Files must have form fields for the placement of application data, with each field tag being unique.
If no form fields exist, use the Adobe Professional version to add field tags. If duplicate tags or non-unique tags are in forms obtained from third parties, use Adobe Professional to update the tags.
Files should not have embedded Javascript.
BI Publisher removes it during the course of the
Map Enablementfunction when theGenerate button on the page is selected.
Processing PDF Templates
The Oracle BI Publisher Core Engine adheres to the following rules when processing PDF templates:
The search for the tag that matches the field name starts at the end of the XML file.
The first match of the tag is used for the field value.
If the tag is not found, the Oracle BI Publisher Core Engine looks at the map file (if provided).
This means that even if the form is mapped, when a tag is in the XML data that matches the PDF template form field tag, it has priority over the map for placing the data.
Using Full Path Mapping
The PeopleSoft implementation for PDF mapping supports full path mapping. Full path mapping is not supported in the BIP Server. Full path mapping should only be used when you have no control on the structure and names of your XML data tags.
Note: Full path mapping is available only for PeopleTools 8.50 and later. It is not backward compatible.
To create a PDF template without mapping tags using Adobe Acrobat:
Design your template in the PDF document as documented in Report Designer's Guide for Oracle Business Intelligence Publisher.
Be sure that the PDF template field names match the XML data tags.
Upload the completed template into the Report Definition by clicking the Upload button on the page.
Note: BI Publisher supports Adobe Acrobat 5.0 (PDF specification version 1.4). If you are using a later version of Adobe Acrobat, use the option to save your file as Adobe Acrobat 5.0-compatible.
See Report Designer's Guide for Oracle Business Intelligence Publisher, “Creating PDF Templates.”
Third parties most often supply PDF templates in which the form fields already exist inside the form template. For the XML data element tags to know where they should print within the PDF template, a mapping is required between the field elements from the data source and the form field elements in the PDF template. Once a PDF form with editable form fields is mapped to the XML sample data fields, the template is ready for use by BI Publisher.
Prior to being able to perform this mapping, some BI Publisher-specific pre-processing of the file is required. This processing requires the existence of an open sample data and the report’s data source. Adobe Standard or above and version 6 or above is required for the template mapping. In the event that the PDF form does not have form fields, the form field and tags can be inserted using the Designer or Professional versions of Adobe. The form field tags can then be mapped to the sample data tags.
To create a PDF template by mapping data element tags using Adobe Acrobat:
Upload the PDF template file to be mapped by clicking the template file Upload button on the page.
If you are using full path mapping, select the Full Path Mapping check box.
Generate the file to be mapped by clicking the map file Generate button.
Generate creates a map-enabled PDF, with the following naming convention. The plug-in enables you to access the data tags by embedding a JavaScript plug-in inside the PDF template.
A dash and the letter m added at the end of the file. For example, if the original file is template.pdf, the mapped file will be template-m.pdf if path mapping is not selected.
A dash and the letter mfp added at the end of the file. For example, if the original file is template.pdf, the mapped file will be template-mfp.pdf if path mapping is not selected.
Visually map the data tags to the form’s field tags.
The mapping exercise is performed offline within the Adobe Acrobat application.
Save the file.
The generated file name indicates the type of mapping, as previously defined in step 2.
Upload the mapped PDF file on the page by selecting the map fileUpload button.
When uploaded to the server, the mapping information is stored in the database along with the PDF form template.
Note: If the PDF template’s field names are the same as the data source's data tag names, then no mapping or uploading of a map file is required.
Note: PDF file security has to allow editing and saving for the mapping to be completed. The ability to perform these functions depends on the Adobe version that you are working with.
Note: If no map file exists for your PDF file, selecting the Preview button on the page will not show any data because the form fields names do not match XML data tag names.
BI Publisher and Adobe
BI Publisher provides the following features within Adobe:
A visual indication of the PDF form fields that have been mapped.
A dark blue outline appears around the mapped form fields.
Display of the mapped field tag name when the cursor hovers over the PDF form field.
A pop-up dialog box containing an XML tag list that you can select from to insert the field tag when you click the PDF form field.
Preparation of the PDF form for uploading to the report definition when you save the file locally by doing a .
Image: Sample PDF file mapping
This example illustrates the mapping of form fields on a PDF file.
BI Publisher for PeopleSoft enables you to develop PDF reports that can be edited and allows the changes to be saved in a database. BI Publisher uses an embedded button to submit the changes to the database.
Note: Only reports generated from PDF templates can be used as submittable reports.
The submittable PDF report functionality is available for delivered self-service reports and for customer-created reports and is mainly used with government delivered PDF templates.
To implement submittable PDF reports you:
Create a PDF template.
Create a custom application class that sets properties, validates data, and saves validated data to the database.
Set properties in the report definition.
Prerequisites for Developing and Using Submittable PDF Reports
To develop and use submittable reports, PeopleSoft Integration Broker must be configured during development and in the production environment.
PeopleSoft provides an activity guide that walks you through the steps of performing a basic configuration of PeopleSoft Integration Broker.
PeopleSoft also provides the Integration Network which provides centralized access the pages to configure Integration Broker, as well as features and configuration settings for developing, managing, monitoring and administering integrations.
If you are setting up Integration Broker solely to meet the prerequisite for creating submittable reports, use the Integration Broker Configuration activity guide. If you are developing and administering integrations, consider using the Integration Network.
See Accessing and Navigating the Integration Broker Configuration Activity Guide and Accessing the Integration Network for more information.
Viewing Requirements for Submittable PDF Reports
The submittable PDF report functionality uses Adobe Reader plug-ins.
If a user’s browser supports Adobe Reader plug-ins, when a user runs a submittable PDF report, he or she views, updates, and submits report changes in the browser in the same PeopleSoft session.
If a user’s browser does not support Adobe Reader plug-ins, the report is downloaded to the user’s machine for viewing and updating in the Adobe Reader stand-alone product. To submit his or her report updates to the system, the user clicks the Submit button on the report. However, since the user has modified the report outside of an active PeopleSoft session, he or she must re-authenticate his or her PeopleSoft credentials. As a result, when the user clicks the Submit button he or she must enter their PeopleSoft user ID and password for the report data to be submitted to the system.
For working with downloaded submittable PDF reports, Adobe Acrobat Reader version 10 or above should be installed on client machines. Further, if the stand-alone Adobe Reader is used to open submittable reports in an HTTPS environment you need to install a trusted root certificate.
|
Browser Support for Adobe Reader Plug-Ins |
Behavior |
|---|---|
|
Yes. |
|
|
No. |
|
Supported Mobile Devices for Submittable PDF Reports
You can submit interactive reports on mobile devices that support Adobe JavaScript. At the time of this writing, only MicroSoft Windows devices support Adobe JavaScript.
Opening submittable PDF reports requires Windows-based devices. You can schedule interactive PDF reports on most other devices.
Submittable PDF Report Processing
The submittable report data is submitted to the application server using PeopleSoft Integration Broker REST services. All service components are provided by PeopleSoft and there is no service set up or configuration required, other than to have Integration Broker configured and running. The default service used for processing is PSXP_PDF_SUBMIT REST and the service operation used for processing is PSXP_PDF_SUBMIT_POST. You can override the default service operation in the PDF Submit Settings property group in the BI Publisher Global Properties or in the Report Definition – Properties page for a report.
Data submitted using submittable PDF report processing is submitted to the application server in XML Forms Data Format (XFDF). The following example show a sample of this format:
All key data required to uniquely identify a row while inserting PDF form data into application database table(s) should exist in the PDF template as fields. It also should exist in the XML data source (Query/Connected Query or XML file).
Development Considerations for Submittable PDF Report Templates
Consider the following points while developing templates for submittable PDF reports:
Use Acrobat Professional to create and update templates.
Templates can use the PDF mapping feature, however the Full Path mapping feature is not supported.
Templates can use embedded Adobe JavaScript for field validation, field calculations, and so on.
All functionality listed in the Document Restriction Summary of a PDF template must be allowed.
To view the document restrictions for a PDF:
Open the PDF template.
Right-click and select Document Properties.
Click the Security tab.
The Document Restriction Summary appears.
All options must be set to Allowed.
Note: If a PDF template was created with restrictions, for example it was provided by a government entity, it must be updated using Adobe Acrobat, resaved and uploaded again to the report definition. In addition, the PDF’s associated mapping file must also be regenerated, re-mapped and uploaded again.
If there are fields that you do not want users to use to submit data, define those fields as read-only in the form editor view of the PDF template. The manner to access the form editor depends on the version of Adobe Acrobat Professional that you are using. The following information is based on using Adobe Acrobat Professional XI.
To define fields as read-only:
Open Adobe Acrobat Professional.
Select
The Create Form dialog box appears.
Choose the appropriate source: From Scratch or Template or From Existing Document, and click the Launch button.
The template appears in the form editor.
Right-click a field to define as read-only and select Properties.
On the General tab, select the Read-Only box.
Select to save the changes.
Using Submit Buttons for Submittable PDF Reports
At run time, BI Publisher inserts embedded Adobe JavaScript into the PDF template to create a Submit/Save button, as well as some additional hidden edit boxes. The Submit/Save button is not be visible in the template but appears in the report presented to the end user.
Alternatively, you have the ability to insert a custom Submit button into the template to enable precise control on the location and appearance of the button. Use the properties in the PDF Submit Settings group on the Global Properties page or the Report Definition – Properties page to customize the button. The report developer should also record the name of the custom Submit button in the report definition properties. See Defining Global Properties for descriptions of the properties that you can set.
In addition, to ensure that the Submit button is invisible if a report is created as a static report, you must define the following settings for this button in the Adobe Acrobat Text Field Properties box:
In General Tab, in Form Field drop-down list, select Hidden.
In Appearance Tab, for the Border Color and the Fill Color options, select No Color.
Securing Submittable PDF Reports
By default inbound/user-submitted PDFs must be sent from systems using basic authentication and SSL. This parameter is set using the Req Verification drop-down list on the Service Operation — General page of the PSXP_PDF_SUBMIT_POST service operation. To access the page select If SSL is used for user authentication, web server SSL should be used as well. The system administrator can change the authentication method on the service operation to basic authentication only, if preferred. However, keep in mind that SSL provides additional security in the form of login data encryption. If SSL is not used for authentication the report developer should record the fact in the report definition properties
See Validating Security on Inbound Integrations for more information about settings.
In addition, the PSXP_PDF_SUBMIT_POST service operation is secured by PeopleTools permission lists.
See Securing Service Operations with Permission Lists for more information.
If the BI Publisher IB Handler is using the HTTPS protocol, the web site used with PeopleSoft software should have SSL feature properly configured.
Performance Considerations for Submittable PDF Reports
Submittable PDF reports are intended to be mostly used by self-service applications running on the application server. The number of application servers required deponds on the number of users simultaneously running submittable reports, but should not be less than three (3) as follows:
One (1) application server for processing.
One (1) application server for PeopleTools debugging as needed.
One (1) application server for Integration Broker.
Performance and scalability depends on:
The number of users running submittable reports at the same time.
The number of application servers being used.
The complexity of reports.
Setting Up Submittable PDF Reports
To set up a submittable PDF report:
Access the Report Definition page. ( and click the Properties tab.)
Select PDF Submit Settings property group and enter values for the properties.
You must set the psxp_submit_enable property to True to enable the feature.
The other properties in the property group enable you to:
Set the size, caption and location of the Submit button or Save button.
Select the network protocol to use during report submission.
Override the default service operations to use for processing.
See Defining Global Properties for a description of properties associated with the PDF Submit Settings property group.
Select the PDF Security property group and set the following properties and values:
Property
Value
pdf-security
False.
pdf-no-changing-the-document
False.
pdf-changes-allowed
2.
Select the PDF Template property group and set the following properties and values:
Property
Value
all-field-readonly
False.
all-field-readonly-asis
True.
This property is required if some fields are read-only and some fields are updatable, in this case 'all-field-readonly' is ignored)
Select the PeopleTools Settings property group and set the folopsxp_pdf_optimized property to False.
Developing Application Classes for Submittable PDF Reports
To implement submittable reports you need to create a custom application class that:
Sets properties mentioned in this section.
Provides data validation.
Saves data to the database.
The application class must implement the delivered IPT_PDFSUBMIT_INT interface.
Upon completion you must register the application class name in the report definition properties.
To register the application class:
Access the Report Definition – Properties page. (Select Reporting Tools, BI Publisher, Report Definition.)
Click the Properties page.
From the Property Group drop-down list, select PDF Submit Settings.
Property settings for submittable PDF reports appear in the property settings grid.
In the psxp_submit_appclass field, enter the name of the custom application class.
Adding Confirmation Pages to Submittable PDF Reports
You have the option to include a confirmation page with submittable PDF reports. A confirmation page is a report that the system merges with the main report into a single output.
The page can let the user know the report was successfully submitted or if an error occurred.
Use the following properties to display an informational page when users submit submittable reports:
|
Property |
Values |
Description |
|---|---|---|
|
ShowSuccessPage |
True: Show confirmation page. False: Do not show confirmation page. |
Use this property to display a confirmation page when users submit a submittable report and the report is successfully saved to the database. In the case of user data input validation errors, a confirmation page with error details always appears. |
|
ConfirmationReportName |
True: Returns the name of the confirmation page based on PDF_SUBMIT_CONFIRMATION data source provided by Oracle. False: The default confirmation report name, PDFSUBMCONF, is used. |
This property provides a name for the report when the success page is shown. |
If including a confirmation or information page with a report, use the following properties to describe the condition of the report, for example, if the report was successfully submitted or has validation problems, as wells as display information, error messages, and other content.
|
Property |
Values |
Description |
|---|---|---|
|
MsgSuccess |
Property string get |
To be used if data was successfully submitted. Informational translated messages to be displayed to the end user |
|
MsgAttention |
Property string get |
To be used if submitted data has validation problems. Informational translated messages to be displayed to the end user |
|
MsgConclusion |
Property string get |
To be used to provide user instructions on the confirmation page |
Making Submittable PDF Reports Static
Use the SetStaticPDFReport property to make a submittable PDF report non-submittable or static after a preset period of time.
This property enables you to deliver a single PDF template when both a submittable and static report are required.
The values for the SetStaticPDFReport are:
True: Static report.
False: Submittable report.