This section contains docs that walk you through the various steps required to configure DIGIT services.

• API Do's And Dont's

• Setting Up Service Locally

• Configuring Reports

• Customizing PDF Notices And Certificates

Details coming soon...

Overview

Rainmaker has report framework to configure new reports. As part of the report configuration, we have to write a native SQL query to get the required data for the report. So if the query takes huge time to execute or query result has huge data, then it will impact on the whole application performance.

Root Cause

The following cases where we can see the application performance issue because of heavy reports.

• Filtering with long date range data or applying fewer filters which in turns return huge data

• Join the multiple tables for getting required data and missing creating index on join columns

• Implementing conditional logic inside the queries itself

• Writing multiple sub-queries inside a single query for getting required data

Impact

Because of heavy reports, the following things will impact the platform

• When we execute a complex query on the database, thread from connection pool will block to execute the query

• When threads from connection pool are blocked completely, the application will become very slow for incoming requests

• When max request timeout is crossed, API gateway will return timeout error, But still, connection thread on the database is active, Then all these types of idle threads will occupy database resources like memory, CPU which in turns increase the load on the database

• Some times when running huge queries, because of time taken by the query will lead to broken pipe issue which causes more memory leaks and out of heap memory type issues. Because of this, the service will frequently restart automatically.

• If a query returns huge data, the browser will become unresponsive and application will become unresponsive.

• Always define the Yaml for your APIs as the first thing using Open API 3 Standard (https://swagger.io/specification/)

• APIs path should be standardised as follows:

  • /{service}/{entity}/{version}/_create: This endpoint should be used to create the entity

  • /{service}/{entity}/{version}/_update: This endpoint should be used to edit an entity which is already existing

  • /{service}/{entity}/{version}/_search: This endpoint should be used to provide search on the entity based on certain criteria

  • /{service}/{entity}/{version}/_count: This endpoint should be provided to give a count of entities that match a given search criteria

• Always use POST for each of the endpoints

• Take most search parameters in the POST body only

• If query params for search need to be supported then make sure to have the same parameters in POST body also and POST body should take priority over query params

• Provide additional Details objects for _create and _update APIs so that the custom requirements can use these fields

• Each API should have a RequestInfo object in request body at the top level

• Each API should have a ResponseInfo object in response body at the top level

• Mandatory fields should be minimum for the APIs.

• minLength and maxLength should be defined for each attribute

• Read-only fields should be called out

• Use common models already available in the platform in your APIs. Ex -

  • Address

  • User(Citizen or Employee or Owner)

  • Role

  • AuditDetails

  • ErrorRes (Response sent in case of errors)

  • TODO: Add all the models here

• For receiving files in an API, don’t use binary file data. Instead, accept the file store ids

• If there is only one file to be uploaded and no persistence is needed, and no additional json data is to be posted, you can consider using direct file upload instead of using filestore id

APIs developed on digit follow certain conventions and principles. The aim of this document is to provide some do’s and don’ts while following those principles

Overview

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

Pre-requisites

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

• All required data and format file path is added in the environment yml file

• pdf-service is up and running

Key Functionalities

• Provide functionality to download and print PDF’s

• Provide functionality to download and print bulk PDF’s

Deployment Details

1. Create data config and format config for a PDF according to product requirement.

2. Add data config and format config files in PDF configuration

3. Add the file path of data and format config in the environment yml file

4. Deploy the latest version of pdf-service in a particular environment.

Configuration Details

For Configuration details please refer to the Customizing PDF Receipts & Certificates document in Reference Docs

Integration

Integration Scope

The PDF configuration can be used by any module which needs to show particular information in PDF format that can be printed/downloaded by the user.

Integration Benefits

• Functionality to generate PDFs in bulk

• Avoid regeneration

• Support QR codes and Images

• Functionality to specify a maximum number of records to be written in one PDF

• Uploading generated PDF to filestore and return filestore id for easy access

Steps to Integration

The following are the steps for integrating TL certificate in UI.

In footer.js file which is present in /frontend/web/rainmaker/dev-packages/egov-tradelicence-dev/src/ui-config/screens/specs/tradelicence/applyResource , Create two object (download and print object) in footerReview function.

Example

In tlCertificateDownloadObject give the proper label name and key for the pdf. In the link function get the object whose mapping is required for PDF, in this case, we want a license object. Call the function downloadCertificateForm (details about this function is described in the next step). Add icon details which we want to use in UI to represent that option. The same thing for tlcertificatePrintObject only difference is we have to call generateReceipt function. Again create the same two object with similar content in downloadPrintContainer function.

Mention the function name “downloadCertificateForm“ and “generateReceipt“ in import , because the functions is define in /frontend/web/rainmaker/dev-packages/egov-tradelicence-dev/src/ui-config/screens/specs/utils/index.js and /frontend/web/rainmaker/dev-packages/egov-tradelicence-dev/src/ui-config/screens/specs/utils/receiptPDF.js

In index.js define the function which is responsible for calling the Create API of PDF service to create respective PDF. In that function, you have to mention the tenant ID and proper key value which is the same as the key mentioned in the data and format config. Also mentioned the URL : /pdf-service/v1/_create and action as get and also call the function downloadReceiptFromFilestoreID which is responsible to call filestore service with filestoreid and return the URL for pdf.

Example of function downloadCertificateForm

Example of function generateReceipt

Reference Docs

Doc Links

API List

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

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 required 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

1. Create data config and format config for a PDF according to product requirement.

2. Add data config and format config files in PDF configuration

3. Add the file path of data and format config in the environment yml file

4. Deploy the latest version of pdf-service in a 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.

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

Sample structure of variable definition in data config

Example to show date in PDF

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 the static text. The information on the QR Code scan will be defined as value. The variable defined in this mapping can directly be used in the format config as an image. ex:-

Data Config for Qr Code:

The format config file contains the following aspects

Example of adding footer in PDF (adding page number in the 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

API List

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

Overview

Configuring Report for a module requires adding the required report configuration as per the standard format and with the minimum development time.

UI can have different types of filters such as date, dropdown etc.. and even the sum of a column can also be easily displayed in UI. Pagination and downloading the report in pdf format, xls format is already present in the report UI.

Type of Reports which can be configured :

1. Count of applications

2. Statewide collections

3. Application status

4. Cancelled receipts

5. Migrated records / Data entry records

Limitation of this framework is for reports having requirements with complex queries with multiple joins as the report uses the query to fetch the data from the database, It is resource-intensive and response might be slow in those scenarios.

Pre-requisites

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

• User with permissions to edit the git repository to add the report configuration

• User with permissions to add action and role action in the mdms

Key Functionalities

• Showcase the data in the required and cleaner format.

• The UI is rendered with the help of configuration in the report and there is no extra effort in building UI for different reports.

• For Implementation specific report requirements, customization is easy and turn around time is less.

Deployment Details

1. After adding the new report/ editing existing report configuration in the respective module, the report service needs to be restarted.

Configuration Details

1. Create a reports.yml file and add report configuration as per standard format.

2. Add the action and role action in the mdms.

3. Add the github raw path of the report.yml file in the report.config file

Reference Docs

Doc Links

Details coming soon...

Overview

Through report service, useful data get shown for a specific module based on some given criteria like date, locality, financial year, etc.

For example, PT dump report of property tax service you have to select from date to date, financial year etc and based on the criteria we can see all the data full filling the criteria. In the response we see all the details of a property which is paid between the given from date and to date, if we selected financial year then we can see the property which is paid for that specific financial year.

Pre-requisites

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

• User with permissions to edit the git repository where Reports are configured and knowledge on YAML.

• Prior Knowledge of YAML.

• Prior Knowledge of SQL queries.

• Prior Knowledge of the relation between the tables for which module you are going to write a report.

Key Functionalities

• User can write queries (like SQL queries) for fetching the real-time data to display in a UI application.

• User can apply filters like from date, to date, financial year, etc based on the report configuration.

• User can download the result in PDF and XLS format.

• User can select or deselect the columns user wants to see.

• User can choose the number of records he/she wants to see on a page.

Deployment Details

1. Once the changes have been done in the report configuration file we have to restart the report service so the report service will read the new configuration.

Configuration Details

• To add a new report first add the file path in the reportFileLocationsv1[https://raw.githubusercontent.com/egovernments/configs/DEV/reports/reportFileLocationsv1.txt] (In this file, the path of the report configuration files get stored).

  • <Module Name>=file:///work-dir/configs/reports/config/<report file name>.yml

  • ex: pgr=file:///work-dir/configs/reports/config/pgr-reports.yml

• Write the report configuration. Once it is done commit those changes.

• Add the role and actions for the new report.

• Restart the MDMS and report service.

Reference Docs

Doc Links