Overview

This service is used to issue a license to the user after verification. The service is designed in such a way that it can be used to serve different type of licenses. Currently used to issue trade licenses, perform stakeholder registration and issue lockdown pass. The service is integrated with workflow where we can define the steps for approval of the application. Once the application is approved the license is generated.

Pre-requisites

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

• Java 8

• Kafka server is up and running

• egov-persister service is running and has tl-services persister config path added in it

• PSQL server is running and database is created

Key Functionalities

• Used for license generations in trade licenses, stakeholder registration and issue lockdown pass

• Define roles to applicants on successful application to access Building Plan Approval services at the time of stakeholder registration

• Generate application number and license number

• Support workflows

• Provide notification on various status changes for an application

Interaction Diagram

Deployment Details

1. Add MDMS configs required for Trade License and BPA stakeholder registration and restart MDMS service

2. Deploy the latest version of tl-services service

3. Add tl-service persister yaml path in persister configuration and restart persister service

4. Add Role-Action mapping for API’s

5. Create businessService (workflow configuration) according to trade license and stakeholder registration

6. Add tl-service indexer yaml path in indexer service configuration and restart indexer service

Configuration Details

Following application properties in the Trade License service are configurable.

Integration

Integration Scope

The trade-license service is currently used to issue trade licenses, perform stakeholder registration and issue lockdown pass.

Integration Benefits

• Provide backend support for the different license registration process.

• Mseva and SMS notifications on application status changes.

• The elastic search index for creating visualizations and Dashboards.

• Bpa Stakeholder registration provides new roles to the user to access the Building Plan Approval system.

• Supports workflow which is configurable

Steps to Integration

1. To integrate, host of tl-services service should be overwritten in the helm chart.

2. {servicename}/_create/ _create should be added as the create endpoint for creating any license in the system

3. {servicename}/_search/ _search should be added as the search endpoint. This method handles all requests to search existing records depending on different search criteria

4. {servicename}/_update/ _update should be added as the update endpoint. This method is used to update fields in existing records or to update the status of the application based on workflow.

Reference Docs

Doc Links

API List

In all below endpoints if the service name is BPAREG it is treated as a stakeholder registration application and if it is TL or if it is absent then the application is treated as trade license application.

Stakeholder registration APIs:- https://www.getpostman.com/collections/d18b79ccfb69ee8bb526

Trade-License APIs:- https://www.getpostman.com/collections/99f98723c45f97024831

Overview

Trade License Calculator service is used to calculate the Trade license fees / renewal fees based on the defined billing slabs. This service enables the TL admins to create billing slab with different combination of license type, trade type, structure type and accessory type. The service is designed in such a way that it can be used to serve different type of licenses.

Pre-requisites

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

• Java 8

• Kafka server is up and running

• egov-persister service is running and has tl-calculation-persister & tl-billing-slab-persister config path added in it

• PSQL server is running and a database is created to store TL Application data

• Following services should be up and running:

  • egov-perister

  • egov-mdms

  • tl-services

  • billing-service

Key Functionalities

• TL Admin an Employee of ULB with TL_Admin role can create, update billing slab(s)

• ULB Employee with TL_CREATOR and TL_ADMIN can search billing slab(s)

• TL service internally calls tl-calculator to generate demand.

Deployment Details

1. Deploy the latest version of tl-service and tl-calculator

2. Add tl-calculation-persister.yml & tl-billing-slab-persister.yml file in config folder in git and add that path in persister . (The file path is to be added in environment yaml file in param called persist-yml-path )

Configuration Details

MDMS Configuration

MDMS for Penalty Calculation

MDMS file for Rebate Calculation

Actions & Role Action Mapping

Actions

Role Action Mapping

Integration Details

Integration Scope

tl-calculator will be integrated with tl-services. tl-services internally invoke the tl-calculator service to calculate and generate demand for the charges.

Integration Benefits

Tl calculator application is used to calculate the Trade license Fees based on the different billing slabs in the DB that's why the calculation and demand generation logic will be separated out from TL services. So in future, if calculation logic needs to modify then changes can be carried out for each implementation without modifying the TL services.

Steps to Integration

1. TL application to call /tl-calculator/v1/_calculate to calculate and generate the demand for the TL application

2. ULB Employee can create billing slab calling /tl-calculator/billingslab/_create

3. ULB Employee can update billing slab calling /tl-calculator/billingslab/_update

4. ULB Employee can search billing slab calling /tl-calculator/billingslab/_search

Interaction Diagram

TBD

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

Users can review the list of applications and their status registered under their mobile numbers in the My Applications tab. Each Application for the initial view displays the Application No, Service Category, Owner Name (Multiple with a comma), status, SLA, and Trade Name with the View Details option. If the status is pending for payment the View Details & Pay button is available that enables the users to look up more details about the application.

Once the user clicks on the View Details or View Details & Pay button, the Application Details Page is displayed with all the necessary information about the application.

The user can download the Application Acknowledgement Form (status - pending for payment ) or TL Certificate or the payment receipt using the Download Link button available at the top right corner of the page.

If the status is Pending for Payment for the application or Action required by a citizen (discussed elaborately here), a button will be visible to pay or edit at the end of the page respectively. On clicking on the Make Payment button it will redirect to the common pay screen through which the user can make the payment.

Timeline Component - timeline component is present at the end of the application details which tells about the current status and history of the application being initiated, Applied, Pending for Document Verification, Pending for Field Inspection, Pending approval, Pending payment, Approved etc.

Technical Implementation Details

The link for the Applications and Application Details main code is given below, it can be used to understand the working of the code, Below is the folder link.

The template for My Application List is present under https://github.com/egovernments/digit-ui-internals/blob/main/packages/modules/tl/src/pages/citizen/Applications/Application.js and Application Details page is present inside - https://github.com/egovernments/digit-ui-internals/blob/main/packages/modules/tl/src/pages/citizen/Applications/ApplicationDetails.js .

All the Application lists are retrieved by calling the search API "/tl-services/v1/_search". If the view is set as “bills”, all the application is loaded using the hook useFetchBill which calls the /billing-service/bill/v2/_fetchbill API. SLA value in the Application List Screen is calculated from the data received from workflow API : /egov-workflow-v2/egov-wf/process/_search

Following is the hook used for the trade search API.

const { isLoading, isError, data, error, ...rest } = view === "bills" ? Digit.Hooks.tl.useFetchBill(
    {
      params: { businessService: "TL", tenantId, mobileNumber },
      config: { enabled: view === "bills" }
    }
  ) : Digit.Hooks.tl.useTLSearchApplication({}, {
    enabled: view !== "bills"
  });

To get the Application details in key-value format, in order to make it more compatible, the following hook is being used, which is a common service to be used across modules.

 const { isLoading, isError, error, data: application, error: errorApplication } = Digit.Hooks.tl.useTLApplicationDetails({
    tenantId: tenantId,
    applicationNumber: id,
  });

MDMS

No MDMS data is being used here, all the data is being loaded from Search API/Fetch Bill API.

Localization

For My Applications also the localization keys are added in the ‘rainmaker-tl’ locale module same as other parts of the TL module. Change, update or add any new localization key is done in the same locale module only.

Objective: To provide the facility for the user to create a trade license application for the current year by citizen or counter employee.

Apply for Trade License

Users can apply for a trade license application by clicking on the Apply for Trade License button. Users can add all the information as per the questions asked across the workflow. The summary screen at the end of the flow displays all details for review. Users can click on the submit button after review. The application for a trade license is created for the current financial year.

Apply Flow - The trade license registration screen is displayed after login which helps users identify the documents required to apply for a trade license. A citizen info card at the bottom of the page displays any additional information about the maximum size of the file that can be uploaded.

Trade License Details/Assessment Flow - This flow captures the trade-specific information required for registering the trade.

Trade Name - The user provides the name of the trade. An info card is displayed at the bottom of the screen stating that the license will be issued for the current financial year. The financial year value is retrieved from the MDMS.

Structure Type - The users can select yes or no based on whether the trade has mobility or not. If yes, the next screen prompts you to enter the vehicle type. If no, the next screen moves to the building type page.

Vehicle Type / Building Type - The options for vehicle and building type are fetched from the MDMS. The Building Type screen displays an information card about the pucca or kuccha options.

Commencement Date - It defines the date on which the trade started or will start in the future.

Trade Units - Users must provide the trade category as either goods or services. Based on the selected option the Trade Type is loaded from the MDMS as a drop-down list. The trade sub-type options are loaded based on the selected trade type. The unit of measure and UOM value get pre-populated from the MDMS as per the options selected above.

Users must enter at least one unit to move forward. Clicking on Add More Unit option enables users to enter additional units. Clicking on the delete icon on the top right corner of the unit card removes the unit.

Accessories - The Accessory page inquires if there are any accessories required for the business. Accessories may not be compulsory for all trades. If yes, it will move to the accessory details page. If no, it will skip it altogether and will load the address flow.

Accessory details - The options for accessories are retrieved from the MDMS. The Unit of Measure or UOM is pre-populated and cannot be edited. The users can edit the UOM value and the accessory count. In some cases, these are pre-populated from the MDMS. Clicking on Add More Trade Accessory button allows users to add multiple accessories.

Common PT integration with TL: After entering the trade details, users have the option to either search and integrate the already created property or create new lightweight property data for the trade license. This step can be skipped and users can proceed with the normal address details flow.

Once a property is selected user can see the details of the property on the property details page. Refer to the Common PT document for more details.

Address Details Flow - In the next flow, users have to enter the trade address details. This flow is straightforward, without any conditional routing.

Users can pinpoint the location in the Geo-location map, according to which pin code and city, as well as locality, is auto-filled.

Owner Details Flow - Finally, the users need to enter the trade owner details. Ownership can be Single or Multiple Owners. According to which the details are filled.

In the case of single/multiple owners, the following screen is displayed. The remaining flows remain the same.

Users can add multiple owners by clicking on the add owner button - a similar functionality as in trade units and accessories. The Add Owner button is not visible in case the user selects a single owner on the previous page.

The user must provide the owner's primary address and upload three documents that include address proof, owner identity and owner photograph.

Check Page and Acknowledgement Screen - Users can cross-verify the data entered throughout the flow in the Check page. Clicking on the change option adjacent to the data fields allows users to make any changes or updates to the data. The user is redirected back to a corresponding information page and the entire flow is repeated once again to submit the application.

The Applying of Trade License Create API is called. Create API snippet:1create: "/tl-services/v1/_create"

If the API response is successful, then the Acknowledgement Screen is displayed, otherwise Failed Acknowledgement Screen is displayed.

Clicking on the Download Acknowledgement Form button downloads the PDF copy of the acknowledgement.

Technical Implementation Details

All screens are developed using the new-UI structure followed previously in FSM, PGR and PT, except for multi-component.

Apply Trade License main index link: https://github.com/egovernments/digit-ui-internals/blob/main/packages/modules/tl/src/pages/citizen/Create/index.js

The TL (Trade License) module is segregated into a specified structure. The screen configuration is inside the PageComponent folder, and the configuration for routing of the pages are mentioned under the config folder which is common for both citizen and employees. Below is the snippet for folder structure and routing configuration.

export const newConfig = [
  {
    head: "",
    body: [
      {
        type: "component",
        component: "TLInfoLabel",
        key: "tradedetils1",
        withoutLabel: true,
        hideInCitizen: true,
      }
    ]
  },

The pages folder is where the high-level configuration for controlling the whole flow is mentioned, for citizens and employees. Citizen flows include Create, Edit Trade, Renewal, Applications and Search Trade. The index or the starting point of the entire flow is available in this folder.

In the Accessory-details page, the Billing slab search API "/tl-calculator/billingslab/_search" is called. This returns the array list of all the accessories for which the billing slab has been configured. If the response returns an empty array then the options are curated from the MDMS API mentioned in the MDMS data section.

After completing the flow the user can download the acknowledgement PDF form of the License created. PDF generation config link: https://github.com/egovernments/digit-ui-internals/blob/main/packages/modules/tl/src/utils/getTLAcknowledgementData.js

The Utils folder basically contains all the methods used throughout the TL module. Additional common methods can be imported and added to this folder.

For creating an application the Create API from Trade License is called using the React hooks. This is declared in the hooks/elements/TL as TLService.

MDMS Data

There are multiple pages within the workflows where data is imported from the MDMS. The table below lists the pages .js files for distinct page components.

React Hooks are used to calling MDMS data that is shared across the modules. Below is the code snippet for the MDMS call.

const { isLoading, data: Documentsob = {} } = Digit.Hooks.tl.useTradeLicenseMDMS(stateId, "TradeLicense", "TLDocuments");

Localization

Localization keys are added to the ‘rainmaker-tl’ locale module. In future, if any new labels are implemented in the Trade License (Citizen) it is pushed to the locale DB in the rainmaker-tl locale module. Below is an example of a few locale labels.

API Role Action Mapping

Renewal Flow

This feature allows the user to renew any trade license applications, which either has been expired or had to be renewed for current financial year (Approved and Paid), it also had integration with the payment component, in order to complete the flow all together for renewal.

Renewal can be two types:

• DIRECT RENEWAL

• EDIT RENEWAL

Renewal List

Once the user clicks on Renew Trade License button on the home page, it will redirect to the renewal list page which will display all the applications eligible for renewal corresponding to the mobile number on which the user has logged in. It will show the Trade name, License Number, Owner Name and status whether active or expired.

Once the user clicks on Renew Button, it redirects the user to the summary page just like in edit Trade license, with all the values pre-populated from the search API. The info card will be declared so that the user will understand how to proceed with either direct renewal or edit renewal.

Direct Renewal

If the user just wants to renew the same application without updating any data, it will cross-verify all the values in the summary page and then click on submit button directly at the end of the page, this will lead the application to the next status as pending for payment and user can go through payment flow from the acknowledgement screen also, by clicking on the Make Payment button.

Edit Renewal

If the user before renewal needs to update the application, they can do so by clicking on the change button on the summary screen, this will tell that the flow has been changed from direct to edit renewal, and the user will need to follow the same apply flow in order to complete the editing part of it. the values from the application will be pre-populated in the respective screens, to get the details about the edit flow, one can refer to this link. .

Once the user clicks on submit button it will change the current action of the application to pending for document verification as the data has been updated.

Technical Implementation Details

Renewal Trade main index can be found in the below-given link:

in this, we are calling the trade license search API, In order to get all the applications, through which the sorting is happened to classify which applications are eligible for renewal for the current financial year.

the hook which has been used for the API is:

The data from here then are sorted into the application which doesn’t have any open renewal application for the current financial year or which has a status of approved or expired. the significant method to get the renewal list of applications is mentioned below:

From here the Trade License List Component has been called which displays the list of the renewal application.

Once the user has completed the flow as required or clicked the submit button directly, the method convertToEditTrade is being called, which re-arranges the data for the request body for the updated API /tl-services/v1/_update.

If it is a direct renewal only one update API is being called which updates the financial year only.

but if it is an edit renewal, two updated API is called after the first API successful call the application status gets changed to Initiated but after the second API call it is changed to applied. with the next action pending for document verification.

the code for these can be found in the utils folder index please refer to the below link for the same:

MDMS

MDMS data which is being used here is the same as the Apply flow only, as the flow structure used for edit renew trade is the same as the Apply for Trade License. Please refer to the link for detailed MDMS information.

Localization

For Renew Trade also, the Localization keys are being added in the ‘rainmaker-tl’ locale module. Change, update or add of any new localization key will be done in the same locale module only.

The Inbox page contains 4 react components:-

Application Links

Application Links is a separate component that holds links to other pages of possible navigation from the inbox. This component is common in both mobile and desktop views. Links are conditionally rendered according to the user roles.

Search Application

The Search Application component is a form-based component, that controls the Table component and the search param for Inbox API, it uses FormComposer HOC to render fields.

Validation of these fields is achieved by using controlled component rules

Any number of search fields can be added but by convention, only mobile numbers and application numbers are provided.

Filters

Filters contain input fields to filter the result of API, by sending search params to inbox API.

It contains 3 sections

1. Assigned to Me/ All - It is a radio component to send the assignedToMe param as true or false.

2. Locality - Filter result according to the selected locality by sending locality code in module search params in inbox API.

3. Status - Status filters are achieved by sending the id received from the inbox API response and mapping the name of businessService, status name and count

Table

The table is a react component which uses the React-Table plugin, used in multiple modules

However, in Mobile view are using cards to list all the applications without pagination support.

APIs

API CURL -

Objective

Provide employee purpose workflow actions.

The same screen is used for both application details and trade details.

Based on the conditions, we are showing the details here

Example: If the application is not in an approved state and the business Service New TL, then we are showing application details otherwise we are showing trade details.

Application Details

For workflow action details, please refer to the file below.

Trade Details

Timeline View

The workflow is the same as Old UI only, please refer to the documentation link below.

Role Action Mapping

Search Application and Search License pages are used for searching any application/ license that may or may not be relevant to the workflow action of the logged-in users.

Search Application has 2 components.

Search Fields

A search field component is a form which takes inputs and passes them into tl-search API params. It utilizes SearchForm and SearchField components to create and arrange the form.

Result Table

Result Table uses the Table react component and the result from API is adapted to the table config using a custom hook inside the common parent wrapper and passing the response to individual components.

Search License has a fixed param where the status of the application is “APPROVED”, other than differences in table config

APIs

The API end point for searching trade licenses is {env}/tl-services/v1/_search

API CURL -

curl 'https://qa.digit.org/tl-services/v1/_search?tenantId=pb.amritsar&fromDate=1625077800000&toDate=1627410599000&limit=10&sortBy=commencementDate&sortOrder=DESC&status=APPROVED&_=1627375567840' \
  -H 'authority: qa.digit.org' \
  -H 'sec-ch-ua: " Not;A Brand";v="99", "Google Chrome";v="91", "Chromium";v="91"' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'dnt: 1' \
  -H 'sec-ch-ua-mobile: ?0' \
  -H 'user-agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36' \
  -H 'content-type: application/json;charset=UTF-8' \
  -H 'origin: https://qa.digit.org' \
  -H 'sec-fetch-site: same-origin' \
  -H 'sec-fetch-mode: cors' \
  -H 'sec-fetch-dest: empty' \
  -H 'referer: https://qa.digit.org/digit-ui/employee/tl/search/license' \
  -H 'accept-language: en-US,en;q=0.9,hi;q=0.8' \
  --data-raw '{"RequestInfo":{"apiId":"Rainmaker","authToken":"18158d2b-0a50-4a60-baa3-a83c157e7aad"}}' \
  --compressed

Edit Trade License

This feature allows the user to edit the application already created under their mobile number. After verifying employee can send the application back to the citizen with remarks on any changes that needed to be done, which can be edited by the user using this flow.

Edit Application

On the Application details page, on the employee side, if the application is marked with “Send Back to Citizen”, the edit option will appear dynamically at the end of the application details page, which the user can navigate through my applications.

After this, On clicking the button, the user can edit the trade license details by going through the Create Flow again. First, it will land on the Summary page, where for each section “change” button is there. Clicking on the Change button, the user will be redirected to the particular content, the only exception here will be the values will be pre-populated from the License object received from Trade License Search API, on completing the flow, Update API will be called and License application will get successfully updated.

Technical Implementation Details

Edit Trade License main index can be found in the link given below:

https://github.com/egovernments/digit-ui-internals/blob/main/packages/modules/tl/src/pages/citizen/EditTrade/index.js

Here the main code consists of the function which results in transforming the License object received in Search API to the object structure which is suitable for citizen Apply flow (owner details, units, accessories etc), as the user needs to go through Apply flow again with pre-populated details and update the value of any accordingly. it also consists of the routing for the pages in the Apply flow.

getTradeEditDetails() function is being used so that the License object which is received from the Trade Search API, is converted to the Apply flow relevant structure so that the values can be pre-populated for the user convenience, on completing the flow, the application is updated. The link for the same can be found below:

Similarly, for owners the method which is used to form the new request param array is gettradeownerarray

It is similar to Accessories and Units - the only difference is in UI. Users can’t select multiple owners and only add one owner, it needs to either add more than one owner or select a single owner in the ownership category and proceed. After the successful update, the application's next action will be “Pending for document verification” as there is an update in the data.

On completing the flow, the same object structure which was being used earlier in the flow gets changed into the request body structure for the update API: /tl-services/v1/_update, for this, the method which gets used is declared inside the Utils folder. Method name: convertToResubmitTrade and it can be found in the below link:

MDMS

MDMS data that is being used here is the same as the Apply flow only, as the flow structure used for edit trade is the same as the Apply for Trade License. Please refer to the link for detailed MDMS information.

Trade License - Apply Flow

Localization

For Edit Trade also, the localization keys are added to the ‘rainmaker-tl’ locale module. Change, update or add of any new localization key is done in the same locale module only.

All the fields in this flow are the same as the New TL Application. The difference here is that max fields are having pre-populated data (On Loading the page, search is made for that particular application).

Will get the Renew Trade License option, when the application is in an approved state and the same financial year application is not present in the workflow.

File path: digit-ui-internals/ApplicationDetails.js at main · egovernments/digit-ui-internals

When we click on the Renew Trade License application, it will route to Renew screen

Direct Renewal: There is no change in any fields and directly clicks on submitting an application, an update API call is made for the respective application with respective to Direct Renewal (applicationType: RENEWAL, workflowCode: DIRECTRENEWAL, )and it will go into direct renewal flow.

Edit Renewal: If there is any change in any fields and clicks on submitting an application, an update API call is made with respect to edit renewal (applicationType: RENEWAL,workflowCode: EDITRENEWAL )and update the application and it will go into the edit renewal flow.

Units, Accessories, Owners and documents details in case of Edit/Renewal flow

Acknowledgement Screen

After a successful update call, the user is routed to the acknowledgement screen.

EDIT Flow: It is also the same as renewal flow only, but we are passing the action action: RESUBMIT on the update call with all the changes.

Application/ Trade Details: Application Details/Trade Details

TL Create New Application: New Trade License Application

Role Action Mapping

Objective

The trade license 'apply' is the major feature in TL Module. It allows Citizens or Counter Employees to create TL Applications for the current financial year.

Every application is a part of the workflow. Once the user login with TL_CEMP role, then the User will get the option for creating a New TL Application in the TL card as well as in the inbox.

Clicking on New Application navigates to the New Trade License Application screen.

Technical Implementation Details

Initial MDMS call is being made on page load like old UI.

MDMS Data

Data fetch, load and render

• Clicking on Submit button, tl-services/v1/_create api is called and create the application, after getting success response, we are calling update API tl-services/v1/_update.

Acknowledgement Screen

After the success of creating and updating calls will route to the acknowledgement screen.

Role Action Mapping