Customizing PDF Receipts & Certificates

Overview

The objective of PDF generation service is to bulk generate pdf as per requirement. This document contains details about how to create the config files which are requires to generate new pdf.

Pre-requisites

Before you proceed with the configuration, make sure the following pre-requisites are met -

Prior knowledge of JavaScript.
Prior knowledge of Node.js platform.
JSONPath for filtering required data from json objects.

Key Functionalities

Provide flexibility to customise the PDF as per the requirement.
Supports localisation.
Provide functionality to add an image, Qr Code in PDF.
Provide functionality to call external service for creating PDF with external service response

Deployment Details

Create data config and format config for a PDF according to product requirement.
Add data config and format config files in PDF configuration
Add the file path of data and format config in environment yml file
Deploy latest version of pdf-service in particular environment.

Configuration Details

Config file: A json config file which contains the configuration for pdf requirement. For any pdf requirements we have to add two configs file to the service.

Format Config file: This config file define the format of PDF. In format config we define the UI structure ex: css, layout etc. for pdf as per PDFMake syntax of pdf. In PDF UI, the places where values are to be picked from request body are written as “{{variableName}}” as per ‘mustache.js’ standard and are replaced by this templating engine. ex: https://github.com/egovernments/configs/tree/master/pdf-service/format-config
Data Config file: This file contains mapping to pick data from request body, external service call body if there is any and the variable which defines where this value is to be replaced in format by the templating engines (mustache.js). The variable which is declared in format config file must be defined in data config file. ex: https://github.com/egovernments/configs/tree/master/pdf-service/data-config

PDF generation service read these such files at start-up to support PDF generation for all configured module.

The data config file contains the following aspects :

Attribute	Description
key	The key for the pdf, it is used as a path parameter in URL to identify for which PDF has to generate.
baseKeyPath	The json path for the array object that we need to process.
entityIdPath	The json path for the unique field which is stored in DB. And that unique field value is mapped to file-store id, so we can directly search the pdf which was created earlier with the unique field value and there will be no need to create PDF again.
Direct Mapping	In direct mapping we define the variable whose value can be fetched from the array object which we extracted using baseKeyPath.
ExternalApi Mapping	The externalApi mapping is use only if there is a need of values from other service response. In externalApi mapping, API endpoint has to be set properly with correct query parameter.
Derived mapping	In derived mapping, the estimation of variable characterize here is equivalent to esteem which acquired from the arithmetic operation between variable of direct mapping and externalApi mapping.
Qr code Config mapping	This mapping is used to draw QR codes in the PDFs. The text to be shown after scan can be combination of static text and variables from direct and externalApi mappings.

Sample structure of variable definition in data config :

{
  “Variable”: “variable_name”,
  “Value”:{
      “path”: “$.propertyId”             -----> jsonpath to obtain value.
  }

}

 {
  “Variable”: “variable_name”,
  “Value”:{
    “path”: “$.propertyId”             -----> jsonpath to obtain value or key to obtain value from localisation.
  },
  “type”:  “label”,                    -----> this field is used to mark this variable as label.       
  “localisation”:{
      “required”: “false”,             -----> if this field is true then  localisation is used for this variable and vice versa.
      “prefix”: “null”,                -----> prefix of the key which is declared in path field.
      “module”: “rainmaker-tl”         -----> the module from which localisation entry is fetched
  }
}

Example to show date in PDF

{
  “Variable”: “variable_name”,
  “Value”:{
    “path”: “$.date”             -----> jsonpath to obtain epoch value of date
  },
  “type”: "date"                  -----> this field is used to mark this variable as date.       
  "format": "YYYY/MM/DD "
}

If the format field in not specified in date variable declaration then in PDF date is shown with default format of DD/MM/YYYY. For more details refer this page Unix-Timestamp

Example of external API calling to MDMS service

Example of adding Qr Code:

For adding Qr code there is separate mapping with the name “qrcodeConfig“ in data config. This mapping can use variables defined in “direct” and “external“ mappings along with static text. The information on QR Code scan will be defined as value. The variable defined in this mapping can directly be used in format config as image. ex:-

Data Config for Qr Code:

The format config file contains the following aspects :

Attribute	Description
key	The key for the pdf, it is used as a path parameter in URL to identify for which PDF has to generate.
Content	In this section, the view of pdf is set. What has to be appear on pdf is declared here, it just like creating a static html page. The variable which are defined in data config are declared here and place in position as per the requirement. We can also create table here and set the variable as per requirement.
Style	This section is used to style the component, set the alignment and many more. Basically it's like a CSS to style the html page.

Example of adding footer in PDF (adding page number in footer)

The position of page number in footer is configurable. For more detail refer this document Header and Footer

Example of adding Qr Code:

Format Config for Qr Code

Integration

For Integration with UI, please refer to the links in Reference Docs

Reference Docs

Doc Links

Title	Link
PDF Generation service technical documentation	PDF Generation Service
Steps for Integration of PDF in UI for download and print PDF	Integration of PDF in UI for download and print PDF
API Swagger Documentation	Swagger Documentation

API List

Title	Link
pdf-service/v1/_create	https://www.getpostman.com/collections/5a9bfd6fd03f9f2a6fad
pdf-service/v1/_createnosave	https://www.getpostman.com/collections/5a9bfd6fd03f9f2a6fad
pdf-service/v1/_search	https://www.getpostman.com/collections/5a9bfd6fd03f9f2a6fad

c

(Note: All the API’s are in the same postman collection therefore same link is added in each row)