Objective :

The objective of PDF generation service is to bulk generate pdf as per requirement.

Requirements :

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

Setup :

Step 1: Write data configuration file and format configuration file as per your requirement.

Step 2: Check-in both the config file to a remote location preferably git hub. Currently we check in the data config file in : https://github.com/egovernments/configs/tree/master/pdf-service/data-config and format config file in : https://github.com/egovernments/configs/tree/master/pdf-service/format-config

Step 3: The file which are created earlier, their absolute path has to mention in dev.yml which is present inhttps://github.com/egovernments/eGov-infraOps/blob/master/cluster/conf/dev.yml Before editing the file create another branch and edit the dev.yml file, mentioned proper file path like

data-config-urls: file:///work-dir/configs/pdf-service/data-config/consolidatedbill.json
format-config-urls: file:///work-dir/configs/pdf-service/format-config/consolidatedbill.json

After editing the file, raise the pull request to DevOPS, so they can merge the branch to master.

Step 4: Before running the PDF generation service, persister and filestore service has to be running. First make sure that pdf-generator.yml persister file is present in https://github.com/egovernments/configs/tree/master/egov-persister If not present then add the file and raise the pull request to Devops. Run the Persister service present in the link given below: https://github.com/egovernments/core-services/tree/master/egov-persister Run the Filestore service present in the link : https://github.com/egovernments/core-services/tree/master/egov-filestore

Step 5: Run the PDF generation service application, use the file-name as path parameters in the URL of the requests for pdf generation service with required request body for which PDF has to generate.

Definitions :

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

API : A REST endpoint to fetch data based on the configuration.

Functionality :

Provide common framework to generate PDF.
Provide flexibility to customise the PDF as per the requirement.
Provide functionality to add an image, Qr Code in PDF.
Provide functionality to generate pdf in bulk.
Provide functionality to specify maximum number of records to be written in one PDF.

Feature List :

Currently supports the generation of payment receipts,bill,certificate and acknowledgement pdf for TL, PT,NOC and BPA.
Functionality to generate PDFs in bulk.
Avoid regeneration.
Support QR codes.
Functionality to specify maximum number of records to be written in one PDF.
Uploading generated PDF to filestore and return filestore id for easy access.
For large request generate PDF in multiple files due to upload size restriction by file-store service.
Supports localisation.

External Libraries used :

PDFMake: (https://github.com/bpampuch/pdfmake ):- for generating PDFs
Mustache.js: (https://github.com/janl/mustache.js/ ):- as templating engine to populate format as defined in format config, from request json based on mappings defined in data config

Impact :

Use by Trade License module for all its PDF.
Use by Property Tax Module for Bill and Payment receipt PDF.
Use by BPA module for Payment Receipt.

Impacted By :

Changes in the format of response from external libraries.
Filestore service request format changes.

Config Details :

As mentioned earlier, We provide two config files for a pdf generation requirement, one defining format as per PDFMake syntax of pdf and other to fill format of pdf to prepare final object which will go to PDFMake and will be converted into PDF. This pdf will be upload to the file store.

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 :

key: The key for the pdf, it is used as a path parameter in URL to identify for which PDF

has to generate.

service name:
version:
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.
mapping: There are three mapping object for variable which are direct mapping, externalApi mapping and derived mapping.
- Direct Mapping: In direction mapping we define the variable whose value can be fetched from the array object which we extracted using baseKeyPath.
- ExternalApi Mapping: We use the externalApi mapping 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.

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 of external API calling to MDMS service

“externalAPI”: [
    “path”: “http://egov-mdms-service:8080/egov-mdms-service/v1/_get”,
    “queryParam”: “moduleName=tenant&masterName=tenants&tenantId=pb&filter=%5B?(@.code=='$.tenantId')%5D”,
    “apiRequest”: null,
    “responseMapping”:[
      {
          “variable”: “address”,
          “value”: “$.MdmsRes.tenant.tenants[0].address”
      },
      {
          “variable”: “phoneNumber”,
          “value”: “$.MdmsRes.tenant.tenants[0].contactNumber”
      }
    ]
  ]

The format config file contain the following aspect :

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.

API Call :

_create :

This API request to PDF generation service is made to generate pdf and return the filestore id and job id.

Endpoint:

/pdf/v1/_create?key={configFileName}&tenantId={tenantId}

Body:

The request body will have requestInfo and another json object depending on the requirement which will be converted to pdf as per requirement.

URL Instance :

https://egov-micro-dev.egovernments.org/pdf-service/v1/_create?key=tlcertificate&tenantId=pb

_createnosave :

This API request to PDF generation service, generate pdf and return the downloadable pdf file as response.

Endpoint:

/pdf/v1/_createnosave?key={configFileName}&tenantId={tenantId}

Body:

The request body will have requestInfo and another json object depending on the requirement which will be converted to pdf as per requirement.

URL Instance :

https://egov-micro-dev.egovernments.org/pdf-service/v1/_createnosave?key=tlcertificate&tenantId=pb

_search :

This API request to PDF generation service, search the already created pdf (based on job Id or entity id) for particular application number. This API can be called before the creation of PDF, and search if the particular pdf is created for that application number or not. If the PDF is created then its filestore id is fetched from DB and based on that filestore id, PDF Is shown.

Endpoint:

/pdf-service/v1/_search?jobid={jobid}

/pdf-service/v1/_search?entityid={entityid}

Body:

The request body will have requestInfo.

URL Instance :

https://egov-micro-dev.egovernments.org/pdf-service/v1/_search?jobid=consolidatedbill1577335538347

https://egov-micro-dev.egovernments.org/pdf-service/v1/_search?entityid=BILL-000676

Steps for running PDF Generation Service locally

Refer this doc :

Steps for locally testing PDF-Generation Service

PDF-Generation Service Technical Document