Authored by Vinod Pakalapati

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 efficiently, 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

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 one of the following categories:

• Generating PDF documents as part of a case life cycle
• Generating PDF documents from UI (such as after clicking a button or link)

Pega Platform™ utilities convert Pega section rules into an HTML stream, add or remove the necessary styling, and send 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

For creation of PDF documents as part of case processing, you can use the following APIs provided by Pega Platform:

• Create PDF smart shape
• HTMLtoPDF API

Create PDF smart shape

For the Create PDF smart shape API, pass the following parameters for creating the PDF document:

• Section Name
• Description    
• Attachment category
• PDF orientation (landscape or portrait)

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

Description is the name of the file to be created.

Attachment category can be either any of the default categories, such as File, Note, Document etc., or a custom category.

The main API invoked through the Create PDF smart shape is Work-. pxCreatePDF.

• This API accepts UseCompactStylesforPDF parameter in addition to the parameters that are exposed through the Create PDF smart shape. UseCompactStylesforPDF parameter (Boolean) determines what type of the style sheet to apply for the PDF document. The usage of this parameter is explained in later part of the document.
• This API in turn invokes the @baseclass.HTMLtoPDF activity to generate a PDF document and attach the PDF document to the case.

HTMLtoPDF API

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

When using this API to produce a PDF version of information, ensure that the HTML is being obtained in a way 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 expected effect.

While invoking this API, ensure to pass the current parameter page, as the generated document will be placed on the parameter page. The HTMLtoPDF API sets the document to the PDFDocument parameter in the form of java type byte (byte array). Once document is generated, you can invoke the AttachToWork activity to attach the document to the case.

Generating PDF documents from UI components

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 a button, link etc. Consider the following scenarios:

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

You can configure a default activity on the UI component to convert case data to a PDF file. Work-.pxCreatePDF or @baseclass.pyViewAsPDF activities are examples of default solutions that can used to generate a PDF document for view and download.

You can even build a custom API that matches your business needs and add steps that can generate PDF files. In such scenarios the following steps needs to be followed in the wrapper API:

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

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

Creating PDF files using eForms

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, complete the following steps:

1. Create a PDF form with fields required as per business needs. This form is a template for the document that gets generated at run time.
2. 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.
3. Create a Map-eForm rule and map the rule with properties.
   • Map eForm rules specify the relationship between the form fields in a PDF form and properties in an application.
4. Create a wrapper rule to complete the following actions:
   1. Invoke logic (such as data transform or data page) to map data to Map-eForm rule from clipboard etc.
   2. Invoke the GenerateEForm API which is used to populate an eForm document with data from the clipboard.
   3. If a case includes multiple eForms, 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.
   4. Invoke the AttachEForm API which creates a file attachment from an input stream or byte, saves it and links it with the case.

Creating PDF files using compact style sheet

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

For accelerating the creation of PDF files and improving rendering, you can use compact style sheets. Compact styling offloads heavy application CSS and uses a simple CSS file with minimum styling that is only applicable for context in the document. This CSS will be applied at run time during PDF document creation. You use the pyCompactStylesforPDF.css compact style sheet for compact styling.

Enabling usage of compact styling

Compact style sheet can be applied globally at an application level or for a specific document generation after you perform any of the following actions:

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

Custom tools and jars

Pega Platform uses PD4ML third party tool to generate PDF documents. These Java libraries are shipped with Pega Platform by default. However, not all styling works by default in PDF documents after using the PD4ML solution. So, you might need to use custom jars for any extra features and styles that are not supported by default. Again, usage of third party tools and jars is strictly not recommended unless business demands them explicitly owing to security and update implications.

Document Content Engine

DCE is a pattern for generation of complex documents. It provides a metadata structure of document sections and paragraphs which can be reused in multiple documents.

Document Content Engine is available as a component on Pega Marketplace.

References

Generating PDFs from your UI

Creating PDF files by using a compact style sheet

About eForm file rules

Map eForm rules