PDF document generation patterns

From PegaWiki
Revision as of 17:23, 2 June 2021 by PAKAV (talk | contribs) (Initial creation)

(diff) ← Older revision | Approved revision (diff) | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search


Curator Assigned
Request to Publish Yes
Description PDF document generation patterns
Version as of 8.6
Application Pega Platform
Capability/Industry Area Case management


Introduction[edit]

To provide stakeholders with crucial information like customer data, regulatory or compliance information etc. generating documents automatically as part of case life cycle plays an important role. Automating document generation increases efficiency and compliance of large organizations. Also, organizations that implement document automation save time and use their resources more wisely, as employees can focus on higher value tasks rather than spending time on manual paperwork.

Generating visually appealing documents with appropriate fonts, styles etc. adds processing overhead to document generation. So, effective generation of those documents without introducing any performance issues is key to any application.

Document generation patterns[edit]

There might be different use cases where creation of PDF documents might be required and out of those use cases the most common ones typically fall into below category

  • Generating PDF documents as part of case life cycle
  • Generating PDF documents from UI (ex: click of button or link)

In a nutshell, Pega utilities convert Pega section rules into HTML stream, adds or removes the necessary styling and sends the HTML+CSS content to generate the PDF bytes. These output bytes will be used to either attach the PDF to case or view/download the context.

Generating PDF documents as part of case life cycle[edit]

For creation of PDF documents as part of case processing, below APIs provided from platform can be used.

  • Create PDF smart shape
  • HTMLtoPDF API

Create PDF smart shape[edit]

OOTB smart shape provided by platform can be used for creation of PDF documents. For the smart shape API, one must pass below parameters for creating the PDF document

  • Section Name
  • Description    
  • Attachment Category
  • PDF orientation (Landscape or portrait)

Section rule is the one which contains the data that needs to be embedded into PDF document. The section can have multiple embedded sections, paragraphs rules etc. for holding the context. The information in the section can have static context fed from paragraph rules, field values etc. and dynamic context read from clipboard during PDF document creation.

Description is the name of the file to be created.

Attachment category can be either any of the OOTB categories like File, Note, Document etc. or can be custom category as well.

The main API invoked via the ‘Create PDF’ smart shape is ‘Work-. pxCreatePDF’.

  • This API accepts “UseCompactStylesforPDF” extra parameter other than the parameters that are exposed via he ‘Create PDF’ smart shape. UseCompactStylesforPDF parameter (Boolean) decides the type of the style sheet used for the PDF document. The usage of this parameter is explained in later part of the document.
  • This API in turn invokes ‘@baseclass.HTMLtoPDF’ activity to generate PDF and attach the PDF to the case.

HTMLtoPDF API[edit]

@baseclass.HTMLtoPDF is the main API used to convert HTML to PDF. The input to the API is an HTMLStream which is used for PDF generation. The API returns the PDF bytes.

When using this API to produce a PDF version of information, one need to make sure that the HTML is being obtained in a way such that the HEAD element includes the styles from the correct skin. Simply sending the HTML stream of a Section rule to this activity will not have the desired effect.

While invoking this API need to make sure to pass the current parameter page to it, as the generated document will be placed onto the parameter page. One need to consume the "PDFDocument" parameter, which is of java type byte[] (byte array) that contains the PDF document. Once document is generated “AttachToWork” can be invoked to attach it to the case.

Generating PDF documents from UI components[edit]

Along with generating PDFs during case processing there might be use cases where a document needs to be generated on click of any UI component like button, link etc. For example,

  • In a price comparison application, one need to generates a PDF of the offers that user selects for comparison.
  • Similarly, in a financial services application one needs to generate a PDF with complete details of the customer for regulatory and compliance purpose.

One can configure an out-of-the-box activity on the UI component to convert case data to a PDF file. Work-.pxCreatePDF or @baseclass.pyViewAsPDF activities are examples of out-of-the-box solutions that can used to generate a PDF and view/download.

One can even build a custom API that matches the business needs and add steps that can generate PDF files. In these scenarios below steps needs to be followed in the wrapper API.

  • Create the HTML fragment for which PDF document must be generated.
  • Call pyViewAsPDF and pass HTML stream and PDF file name as required parameters.

It is recommended to always to use OOTB APIs rather than any custom API to avoid issues during seamless upgrades.

Creating PDF files using eforms[edit]

The smart forms feature supports applications that work with PDF files. Application can process incoming PDF forms, extract field data, and write the data into properties on the clipboard. The Pega Platform APIs can also merge data from the clipboard into a PDF form, generating a new PDF document. For creating PDF documents using PDF forms below steps can be followed.

  • Create a PDF form with fields required as per business needs. This form is like a template for the document that gets generated at run time.
  • Create an eForm rule and upload the PDF form created in step 1.
    • eForm file rules hold uploaded PDF form files that are used as templates when generating new PDF documents
  • Create a Map-eForm rule and map with properties.
    • Map eForm rules specify the relationship between the form fields in a PDF form and properties in application.
  • Create a wrapper rule to
    • Invoke logic (ex: Data transform or data page) to map data onto Map-eForm rule from clipboard etc..
    • Invoke “GenerateEForm” API which is used to populate an eForm document with data from the clipboard.
    • In case there are multiple eforms then invoke to “ConcatenateEForms” API.
      • This API is used to concatenate a collection of eForms into a single eForm.   The documents to be concatenated need to be in the pyEForms java object list property of the primary page of this API as byte[] objects.
    • Invoke “AttachEForm” API which creates a file attachment from an input stream or byte[], saves it and links it with the work object.

Creating PDF files using compact style sheet[edit]

By default, the application CSS and styling gets applied at run time to PDF documents when they are generated either by using ‘Create PDF smart shape’ or by using HTMLtoPDF API. Generally, application styling is heavy and using that for rendering the context for document generation takes significant time.

For accelerating the creation of PDF files and improving rendering, compact style sheets can be used. Compact styling offloads heavy application CSS and uses a simple CSS file with minimum styling that are only applicable for context in the document. This CSS will be included in runtime while PDF is being created.

pyCompactStylesforPDF.css is the compact style sheet that needs to be used for compact styling. The list of elements that compact styling will help the system render in PDF are available https://community.pega.com/knowledgebase/articles/user-experience/85/creating-pdf-files-using-compact-style-sheet

Enabling usage of compact styling[edit]

Compact style sheet can be applied globally at application level or for a specific document generation.

  • To use compact style sheet globally dynamic system setting (DSS) ‘UseCompactStylesforPDF’ needs to be set to ‘true’.
  • To use compact style sheet at a certain point of document generation set the parameter ‘param.UseCompactStylesforPDF’ to true and pass it to ‘Create PDF smart shape’ or ‘HTMLtoPDF’ API.

Custom tools/jars[edit]

Pega uses PD4ML third party tool to generate PDF. These java libraries are shipped with OOTB Pega platform. But not all styling works by default in PDF using PD4ML solution. So, one might need to use custom jars for any extra features, styles that are not supported OOTB. Again, usage of third party tools/jars is strictly not recommended unless business demands them explicitly owing to security and upgrade implications.

References[edit]

Please refer to the following articles on Pega Community for more information

https://community.pega.com/knowledgebase/articles/user-experience/86/generating-pdfs-your-ui

https://community.pega.com/knowledgebase/articles/user-experience/86/creating-pdf-files-using-compact-style-sheet

https://community.pega.com/knowledgebase/articles/reference/86/about-eform-file-rules

https://community.pega.com/knowledgebase/articles/reference/86/map-eform-rules