Generate PDF from Pega – Using Pega APIs
In this blog article, we will see some basic Pega APIs that aid in generating PDF documents.
The article was created using Pega 8.3 version! but the core concept remains the same! Use this blog article to learn the concepts and you can try the entire tutorial in the latest versions as well.
What is PDF?
PDF stands for Portable Document Format. It presents a reliable document independent of software, hardware or operating system.
Invented by Adobe and is now an open stand maintained by ISO.
So, it is one type of file format like Word, Excel etc. To create Excel or Word, we use certain Java libraries, similarly for PDF Pega uses a third-party licensed Java library – pd4ml
What is pd4ml?
It is a PDF generating tool that accepts HTML and CSS as input and generates the PDF as output.
HTML and CSS form the core part of Pega UI. To learn more about the pd4ml features, please checkout some docs on their website https://pd4ml.com/
These Java libraries come with the OOTB Pega platform package and so we don’t need to worry about installation stuff!
Now let’s see how Pega application can generate PDF files using this java library.
I am going to take a simple use case to generate a PDF inside a case cycle.
Pega has introduced a smart shape – Create PDF utility that can create PDF using Pega section as input parameter.
Let’s straightaway get inside the tutorial and the learn step-by-step process.
How to generate PDF inside a case?
Step 1: For demo purpose, I have created a simple case type – Claims and a simple step – collect information that collects the basic details.
And a separate section to display the PDF content. I would recommend having a specific new section for PDF content, because you may need to apply specific styles to the section.
Below is the section rule, I created specific for PDF.
Step 2: Include the Create PDF step in case designer at the right step.
Step 3: Configure the step
Section name – Included the section I created for PDF
Description – Provide a valid description for the PDF
Attachment Category – File
PDF orientation – Landscape or portrait (this will be passed as input parameter to the PDF generation API)
This is all good, run the flow and stop at the step before generating PDF.
Open the trace and click on submit so that you trace the PDF creation activities involved with the smart shape.
You see three main activities are called – pxCreatePDF which calls pyAttachPDF which inturn calls the main activity HTMLtoPDF.
Before going through each individual activity, we will see the PDF document which got attached with the case.
Open the PDF and see the content
Don’t stress your eyes to see the value!! Style is not good.
We will come back to styling a little bit later. First, let’s explore the OOTB APIs.
Important note: The below activity steps may vary based on your Pega version. The current version I use is Pega 8.3
1. pxCreatePDF – This is the main API used in Create PDF smart shape. This utility calls other supporting utility to generate PDf and attach the PDF with the case.
Let’s check the parameter.
This is the first thing I always check when I explore any activity 😉
The description explains a lot!! The first four parameters we already saw in the case designer Create PDF step configuration. All those values get passed to these parameters at runtime.
One UseCompactStylesForPDF– This is one interesting parameter that sets some compact styling to offload heavy styling. Again, we will see about it on the way through this tutorial 😊
In the activity, the first few steps are related to attachments. In the fourth step, you will see the activity sets an important parameter param.HTMLStream to pzcreatePDFHarnessWrapper
This is an OOTB HTML rule. Open the rule and check the configuration.
Tip: If you have issues with opening pz rules, enable the diagnostic features checkbox in your operator preferences.
It wraps the section we pass as parameter value into property value pyTransientText in the step page to the harness pzCreatePDFHarness
You can also open and check the harness rule – pzCreatePDFHarness
There you see the section is included use the step property pyTransientText.
Going back to the pxCreatePDF activity, it then calls the pyAttachAsPDF activity followed by error handling step.
2. pyAttachAsPDF –
First the parameter page.
To save the PDF as an attachment, we need to use pzInskey of the case. Other params are self explanatory!!
In the activity 3rd step – It generates the HTML stream and sets into the parameter – markup using property-set-HTML method.
Note that the HTMLStream parameter – Includes the harness and our section.
In the 6th step it calls HTMLToPDF – the main activity to convert the HTML stream to PDF (using the PD4ML library function)
In the 7th step – It calls AttachToWork activity, which saves an instance of Data-WorkAttach-File.
So, this activity is mainly responsible to generate PDF and attach with the case.
What if your use case says, not to attach with the case, but allow the user to download the PDF on click of the button (this is some kind of most general use case I have seen in projects)
There is another twin activity similar to pyAttachAsPDF called as pyViewAsPDF.
pyViewAsPDF does similar steps to generate the PDF, but it uses Code-Pega-PDF.View activity to provide an option for downloading the PDF instead of attaching.
Please explore on your own.
3. HTMLToPDF
There are around 24 parameters for this activity.
Please check on the description for those parameters.
Going to activity steps – Step 2 to 5 meant for compact styles!!
Let’s see what is compact styling
Compact styling is mostly used when you generate PDF from report browser. It offloads the heavy CSS and uses a simple CSS file with minimum styling, that’s why the name compact styling.
In activity step two, you see Pega has an DSS setting to set the Use of compact styles globally for the application. Use it only when needed, because this will impact the PDF styles throughout the application.
Note: Always prefer to use the parameter UseCompactStyles instead of setting globally!
So, when we need to use compact styles then 3-5 steps are executed.
In the 4th step, you will see, Pega uses an HTML fragment – pzCompactPDFStyles, which inturn uses an available style sheet – pyCompactStylesforPDF.css and sets into Markupstyles parameter using property-set-stream method.
You can open the rule and see some basic styling for layouts, labels etc.
In the 5th step, Pega strips the added CSS files (which gets included by default when rendering document) and replaces it with compact CSS styles using the parameter markupstyles.
Here comes the main step – 8, Pega uses the generate PDF function to generate the bytes for the PDF document.
GeneratePDF is an engine library function, that generates the PDF
From the resources menu, you can click and open the EngineAPI, there you will find the PDF Utils Interface and the GeneratePDF method.
You can also scroll and see all the parameters the function accepts!
In a nutshell, the Pega utilities convert the section into HTML stream, adds or remove 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 or view/download the content.
One interesting parameter to checkout is the HTMLStream, we send into the function in step 8.
Let’s check its contents.
Step 1: Trace open the activity rule – HTMLToPDF from the action button.
Step 2: Execute the case, to generate the PDF document.
Step 3: In the tracer, check the parameter value from step 8
You will the HTML stream is an entire HTML document (this is because we render the section inside the Harness rule)
Step 4: Copy and paste the HTML stream into a notepad
and save it as HTML page.
Now launch the HTML page, and you will see HTML content without any styling. You know the reason because I saved the HTML document in my local machine and the CSS styles sheets are not accessible. Hence naked HTML document.
Step 5: Create a dummy section to test the generated HTML stream. Make it not auto-generated and input the HTML content.
Now Run the section, to see how the content is rendered.
You will see some styles applied with alignment. This is not a plain HTML content 😊
Now you know some basics about how the PDF generation works in Pega. But…….. not all styling works by default in PDF using pD4ML solution, you need to do some customization 😊. We will see about this in another blog article.
