Overview

An Urban Local Body (ULB) is defined as a tenant. Tenant configuration is done in mdms.

Pre-requisites

Before proceeding with the configuration, the following pre-requisites are met:

• Knowledge of JSON and how to write a JSON is required.

• Knowledge of MDMS is required.

• User with permission to edit the git repository where MDMS data is configured.

Key Functionalities

• For the login page, city name selection is required. Tenant added in MDMS shows in city drop-down of the login page.

• In reports or the employee inbox page, the details related to ULB are displayed from the fetched ULB data which is added in MDMS.

• Modules, that is, TL, PT, and MCS can be enabled based on the requirement for the tenant.

Deployment Details

• After adding the new tenant, the MDMS service needs to be restarted to read the newly added data.

Configuration Details

1. Tenant is added in tenant.json. In MDMS, file tenant.json, under the tenant folder holds the details of the state and ULBs to be added in that state.

{
  "tenantId": "uk",  //<ReplaceWithDesiredTenantId>
  "moduleName": "tenant",
  "tenants": [ {
      "code": "uk.citya", //<state.ulbname>
      "name": "City A",  //<name of the ulb>
      "description": "City A", //<ulb description>
      "logoId": "https://s3.ap-south-1.amazonaws.com/uk-egov-assets/uk.citya/logo.png",  //<ulb logo path - To display ulb logo on login>
      "imageId": null,
      "domainUrl": "", //<ulb website url>
      "type": "CITY",
      "twitterUrl": null,
      "facebookUrl": null,
      "emailId": "complaints.citya@gmail.com",  //<ulb email id>
      "OfficeTimings": {
        "Mon - Sat": "10.00 AM - 5.00 PM"
      },
"city": {
"name": "City A",
"localName": null,
"districtCode": "CITYA",
"districtName": null,
"regionName": null,
"ulbGrade": "Municipal Corporation",
"longitude": 78.0322,
"latitude": 30.3165,
"shapeFileLocation": null,
"captcha": null,
"code": "248430"
},
"address": "City A Municipal Cornoration Address",
"contactNumber": "91 (135) 2653572"
}]}

Note:

• To enable the tenant the above data should be pushed in the tenant.json file. Here "ULB Grade" and City "Code" are important fields. ULB Grade can have a set of allowed values that determines the ULB type, (Municipal corporation (Nagar Nigam), Municipality (municipal council, municipal board, municipal committee) (Nagar Parishad), etc). City "Code" has to be unique to each tenant. This city-specific code is used in all transactions. Not permissible to change the code. If changed we will lose the data of the previous transactions done.

• Naming Convention for Tenants Code

“Code”:“uk.citya” is StateTenantId.ULBTenantName"

• "logoId": "https://s3.ap-south-1.amazonaws.com/uk-egov-assets/uk.citya/logo.png", Here the last section of the path should be "/<tenantId>/logo.png". If we use anything else, the logo will not be displayed on the UI. <tenantId> is the tenant code ie “uk.citya”.

2. Localisation should be pushed for ULB grade and ULB name. The format is given below. Localisation for ULB Grade:

{
     "code": "ULBGRADE_MUNICIPAL_CORPORATION",
     "message": "MUNICIPAL CORPORATION",
     "module": "rainmaker-common",
     "locale": "en_IN"
  }

Localisation for ULB Name:

{
     "code": "TENANT_TENANTS_UK_HALDWANI",    
     "message": "Haldwani",
     "module": "rainmaker-tl",
     "locale": "en_IN"
}

Format of localisation code for tenant name : <MDMS_State_Tenant_Folder_Name>_<Tenants_Fille_Name>_<Tenant_Code>(replace dot with underscore)

1. Boundary data should be added for the new tenant.

Reference Docs

Steps to Setup State/Urban Local Body (ULB):

Adding a Tenant:

In MDMS, the file tenant.json under the tenant folder holds the details of the state and ULBs to be enabled in that state.

{

  "tenantId": "pb",  //<ReplaceWithDesiredTenantId>

 "moduleName": "tenant",

 "tenants": [ {

      "code": "pb.citya", //<state.ulbname>

      "name": "City A",  //<name of the ulb>

      "description": "City A", //<ulb description>

      "logoId": "https://s3.ap-south-1.amazonaws.com/pb-egov-assets/pb.citya/logo.png",  //<ulb logo path - To display ulb logo on login>

      "imageId": null,

      "domainUrl": "", //<ulb website url>

      "type": "CITY",

      "twitterUrl": null,

      "facebookUrl": null,

      "emailId": "complaints.citya@gmail.com",  //<ulb email id>

      "OfficeTimings": {

        "Mon - Sat": "10.00 AM - 5.00 PM"

      },

"city": {

"name": "City A",

"localName": null,

"districtCode": "CITYA",

"districtName": null,

"regionName": null,

"ulbGrade": "Municipal Corporation",

"longitude": 75.5761829,

"latitude": 31.3260152,

"shapeFileLocation": null,

"captcha": null,

"code": "1013"

},

"address": "City A Municipal Cornoration Address",

"contactNumber": "001-2345876"

}]}

Note:

To enable a state and a ULB, the above data should be pushed in tenant.json file. Here "ULB Grade" and City 'Code' are important fields. ULB Grade can have a set of allowed values that determines the ULB type, (Municipal corporation (Nagar Nigam), Municipality (municipal council, municipal board, municipal committee) (Nagar Parishad), etc). City 'Code' has to be unique to each tenant. This city-specific code is used in all transactions. It is not permissible to change the code. If changed, we will lose the data of the previous transactions done.

Localisation should be pushed for ULB grade and ULB name. The formats are given below:

Localisation for ULB Grade

{

            "code": "ULBGRADE_MUNICIPAL_CORPORATION",

            "message": "MUNICIPAL CORPORATION",

            "module": "rainmaker-common",

            "locale": "en_IN"

        }

Localisation for ULB Name

{

            "code": "TENANT_TENANTS_UK_HALDWANI",    

            "message": "Haldwani",

            "module": "rainmaker-tl",

            "locale": "en_IN"

        }

Format of localisation code for tenant name:

<MDMS_State_Tenant_Folder_Name>_<Tenants_Fille_Name>_<Tenant_Code>(replace dot with underscore)

1. Naming Convention for Tenants Code

   • >

   “Code”:“pb.citya” is StateTenantId.ULBTenantName"

2. "logoId": "https://s3.ap-south-1.amazonaws.com/pb-egov-assets/pb.citya/logo.png", Here the last section of the path should be "/<tenantId>/logo.png". If we use anything else, the logo will not be displayed on the UI. <tenantId> is the tenant code ie “pb.citya”.

• citymodule.json file under the tenant folder used to activate modules in specific ulb. Example:

{

  "module": "TL",

  "code": "TL",   

    "tenants": [{ "code": "pb.citya"},   

            {"code": "pb.cityb"}]

            }

Module TL is enabled in ULB City A and City B. Modules mentioned in this file appear in the menu tree of the application. A ULB-level module enable or disable is handled here.

Adding a State

In MDMS, the file StateInfo.json, under the common-masters folder holds the state data.

{ 

"tenantId": "pb"  ,  //<ReplaceWithDesiredTenantId>

"moduleName": "common-masters",

"StateInfo": [   {

"name": "punjab",

"code":"pb"  , //<ReplaceWithDesiredTenantId>  "bannerUrl":https://amazonaws-url/foldername/file.jpg",  <bannerimage file path>

"logoUrl":"https://amazonaws-url/foldername/file.jpg", <state logo image file path>

"hasLocalisation" : true, <if true, enables multilingual support mentioned below. Or else by default english>

      "languages" : [ {   <languages to be supported are listed here>

          "label": "ENGLISH",

          "value": "en_IN"

        }, {

          "label": "हिंदी",

          "value": "hi_IN"

        }  ],

      "defaultUrl" : {

          "citizen" : "/user/register",

          "employee" : "/user/login"

}  } ]

}

Boundary Data Load:

• Boundary is ULB-specific master data. For revenue modules, we use the revenue boundary. It is pushed under each ULB.

The file path would be: https://github.com/egovernments/state-mdms-data/tree/master/data/tenant/ulb/egov-location/boundary-data.json

Boundary Hierarchy : Zone -> Ward -> Locality -> Area

Boundary data json is generated using the implementation kit.

Trade License Master Data Load:

Trade Type Master:

• Trade Types of all ULBs are pushed under the “Trade License” folder of the MDMS repo.

The file path would be:

Example:

{

  "tenantId": "xyz",  //<ReplaceWithDesiredTenantId>

  "moduleName": "TradeLicense",

  "TradeType": [

    {

      "code": "TRADE.INDUSTRY.FM", //<Trade Type Code is mentioned here>

      "uom": null,

      "applicationDocument": [

        "IDPROOF",

        "OTHER"

      ],

      "verificationDocument": [],

      "active": true

    }]

}

For each trade type, sub-types are defined. Each sub-type has mandatory documents to be attached. A unique code will be defined for each trade type, sub-type, and document.

"code": "TRADE.INDUSTRY.FM" // Defines Category -> Trade Type -> Trade Sub Type

TRADE is category

INDUSTRY is a Trade Type

FM is a Trade Subtype (Floor Mill)

Note: Code defines the levels of hierarchy. Dots define the number of hierarchy levels. TRADE.INDUSTRY specifies two levels, which means TradeType INDUSTRY falls under the TRADE category. TRADE.INDUSTRY.FM specifies three levels, which means FM is a sub-type under INDUSTRY.

For all the master data, we are pushing localisation messages. An explanation of inserting localisation for master data is given in the localisation section below:

Trade Rates:

• Trade Rates for each trade subtype are stored in the database. Rest endpoints are available to create trade rates and search existing trade rates. You can use the below curl command to create and search trade rates.

• -------------------------- Search Trade Rates ------------------------------------

curl -X POST \ 'https://APPLICATION-URL/tl-calculator/billingslab/_search?tenantId=state.ulbname' \

• H 'Content-Type: application/json' \

• H 'Postman-Token: 80d84c50-b16e-44dd-9cc5-544def2ecd81' \

"RequestInfo": {

"authToken": "3bad8c62-b769-4a69-bf8b-0c6f008a5f01"

}

}'

• -------------------------- Create Trade Rates ------------------------------------

curl -X POST \ 'https://APPLICATION-URL/tl-calculator/billingslab/_create?tenantId=state.ulbname' \

• H 'Content-Type: application/json' \

• H 'Postman-Token: 59653a46-0a96-4eb0-a1cd-3e6c47f67aa0' \

"RequestInfo": {

"authToken": "796978d5-47d4-48b0-8995-f9e3fbfc32d8"

},

"billingSlab": [

{

"tenantId": "state.ulbname",

"licenseType": "PERMANENT",

"structureType": "IMMOVABLE.SHED",

"tradeType": "TRADE.HOTELS.HL30B",

"accessoryCategory": null,

"type": "FLAT",

"uom": null,

"fromUom": 0,

"toUom": 0,

"rate": 1000

}

]

}’ //<Replacewith proper application URL and the tenantid>

Note: Currently, the delete rate is not supported. To delete any specific rate, updating 'rate' to null using the update endpoint will inactivate the rate for a specific sub-type.

Adding role, and actions to MDMS

• Actions are the features like “Create”, ”Update”, “Search” and so on. Action JSON file maps all the actions, that is, URLs. https://github.com/egovernments/state-mdms-data/tree/master/data/tenant/ACCESSCONTROL-ACTIONS-TEST

Actions-test.json:

{

      "id": 1685,  //<Unique identifier>

      "name": "Create TradeLicense",

      "url": "/tl-services/v1/_create", //<url of the feature>

      "parentModule": "",

      "displayName": "Create TradeLicense",

      "orderNumber": 0,

      "enabled": false,

      "serviceCode": "tl-services",

      "code": "null",

      "path": ""

}

• Role-based actions will have mappings between actions and roles. It specifies which role can perform what actions. Example: A user with a TLCreator role mapped to the “Create Trade License” action/feature, can only perform the create TL application. A user can have multiple roles and multiple actions mapped.

Roleactions.json:

"roleactions": [

    {

      "rolecode": "TL_CREATOR",

      "actionid": 1685,

      "actioncode": "",

      "tenantId": "pb"  //<ReplacewithTenantId> 




    }]

Localisation

• All the master data, labels, notifications, validation/success messages are localised. To support multi-lingual, we use a common code for each field for which messages in different languages will be pushed using endpoints. Create, upsert, and search endpoints are used to create/update localisation messages.

• Need to push localisation messages for newly-added master data.

Localisation code format for Masters: <ModuleName_MasterName_Code>

Example: Trade Type Master -

{

            "code": "TRADELICENSE_TRADETYPE_INDUSTRY",

            "message": "Industry/Factory/Mill",

            "module": "rainmaker-tl",

            "locale": "en_IN"

        }

Trade Sub-Type:

{

            "code": "TRADELICENSE_TRADETYPE_TRADE_INDUSTRY_FM",

            "message": "Flour mill, spice mill,cotton machine",

            "module": "rainmaker-tl",

            "locale": "en_IN"

        }

Use the below rest endpoints to push these data:

• Only boundary localization messages are pushed at the ULB level. Rest all are pushed at the state level.

• -----------------------

Upsert: Update and Insert Localisation

• -------------------------

• --------

This API, updates if code already exists or else inserts newly

• ----------------

curl -X POST \ 'https://APPLICATION-URL/localization/messages/v1/_upsert?tenantId=XYZ&locale=en_IN' \

• H 'Content-Type: application/json' \

• H 'Postman-Token: 39264728-2857-4cb4-825c-53612fce51c0' \

"RequestInfo": {

"api_id": "org.egov.pgr",

"ver": "1.0",

"ts": "16-03-2017 12:09:14",

"action": null,

"did": "4354648646",

"key": "xyz",

"msg_id": "654654",

"requester_id": "61",

"authToken": "8850660e-7d35-4e8e-9d8b-9656c1a91d30"

},

"tenantId": "XYZ",

"messages":[

{

"code": "TL_OWNER_NAME",

"message": "OWNER",

"module": "rainmaker-tl",

"locale": "en_IN"

}

]

}'

• -----------------------Search Localisation--------------------------

curl -X POST \ 'https://APPLICATION-URL/localization/messages/v1/_search?locale=en_IN&tenantId=XYZ' \

• H 'Content-Type: application/json' \

• H 'Postman-Token: 8fae6bd4-17ae-4fa5-afc4-a692f2c74064' \

"RequestInfo": {

"api_id": "org.egov.pgr",

"ver": "1.0",

"ts": "16-03-2017 12:09:14",

"action": null,

"did": "4354648646",

"key": "xyz",

"msg_id": "654654",

"requester_id": "61",

"authToken": "7315d713-773c-4282-97a1-b69b95895711"

},

"tenantId": "XYZ"

}'

Note: Product-level localised messages are attached in this link. Localisation_Messages Use this json to load the labels and the basic master data with the above endpoints.

Employee Creation

HRMS Admin and SUPERUSER

• "CreateNoValidate" api is used to create admin and superuser for the first time when no users exists. This endpoint is for User Creation only.

• For Employee creation, Separate endpoint or UI used. HRMS admin is responsible for employee creation.

• ----------------------

Create No Validate Api to create first time employees

• ---------------------

curl -X POST \

http://localhost:8088/user/users/_createnovalidate \

• H ‘Content-Type: application/json’ \

• H ‘Postman-Token: 3c8eb85e-877e-4b0a-a1db-60676fa5eb45’ \

• H ‘cache-control: no-cache’

{

"RequestInfo": {

  "apiId": "ap.public",

  "ver": "1",

  "ts": null,

  "action": "POST",

  "did": null,

  "key": null,

  "msgId": "8c11c5ca-03bd-11e7-93ae-92361f002671",

  "userInfo": {

    "type" : "SYSTEM",

    "name" : "kiran",

    "id" : 32  },

  "authToken": "{{access_token}}"

},

 "user": {

          "id": 3,

          "userName": "EMP3_SUPER",

          "salutation": "MR",

          "name": "PB_SUPERUSER",

          "gender": "MALE",

          "mobileNumber": "9898989897",

          "emailId": "jamalbhai@maildrop.cc",

          "altContactNumber": "",

          "password": "PBEGOV123",

          "pan": "AITGC5624P",

          "aadhaarNumber": "96a70",

          "permanentAddress": "Dawakhana",

          "permanentCity": "Kaikoo",

          "permanentPinCode": "111111",

          "correspondenceAddress": "correAddress",

          "correspondenceCity": "banglore",

          "correspondencePinCode": "1234",

          "addresses": [

              {

                  "pinCode": "1234",

                  "city": "banglore",

                  "address": "correAddress",

                  "type": "CORRESPONDENCE",

                  "id": 1,

                  "tenantId": "pb.citya",

                  "userId": 1,

                  "addressType": "CORRESPONDENCE",

                  "lastModifiedDate": null,

                  "lastModifiedBy": null

              },

              {

                  "pinCode": "111111",

                  "city": "Kaikoo",

                  "address": "Dawakhana",

                  "type": "PERMANENT",

                  "id": 2,

                  "tenantId": "pb.citya",

                  "userId": 1,

                  "addressType": "PERMANENT",

                  "lastModifiedDate": null,

                  "lastModifiedBy": null

              }

          ],

          "active": true,

          "locale": "string",

          "type": "EMPLOYEE",

          "accountLocked": false,

          "accountLockedDate": 0,

          "fatherOrHusbandName": "Hamaal",

          "signature": "",

          "bloodGroup": "O+",

          "photo": "photo1",

          "identificationMark": null,

          "createdBy": 32,

          "lastModifiedBy": 32,

          "tenantId": "pb.citya",

          "roles": [

              {

                  "code": "SUPERUSER",

                  "tenantId": "pb"

              }

          ],

          "uuid": "1fae1f10-f398-4d05-83f5-7457a946aef9",

          "createdDate": "22-05-2019 12:49:07",

          "lastModifiedDate": "22-05-2019 12:49:07",

          "dob": "03/08/1971",

          "pwdExpiryDate": "20-08-2020 12:49:07"

      }

}

Online Payment Gateway Integration :

Refer to the following link for documentation:

SMS Gateway Integration :

• Set the below configurations in the application.properties file of egov-notification-sms service

• Below configuration holds service provider details.

• ---------------------------

application.properties

• ---------------------------------------

sms.enabled=true

sms.provider.url=http://placeholder

sms.sender.username=placeholder

sms.sender.password=placeholder

sms.sender=placeholder

#Parameter names are kept compatible with sms service provider(SMSCountry gateway).

sms.sender.req.param.name=sid

sms.sender.username.req.param.name=user

sms.sender.password.req.param.name=passwd

sms.destination.mobile.req.param.name=mobilenumber

sms.message.req.param.name=message

sms.extra.req.params=smsservicetype=singlemsg

sms.error.codes=401,403,404,405,406,407,408,409,410,411,412,413,414

#SMS priority settings if available

sms.priority.enabled=false

sms.priority.param.name=

sms.high.priority.param.value=

sms.medium.priority.param.value=

sms.low.priority.param.value=

sms.verify.response = false

sms.verify.responseContains=Message submitted successfully

sms.verify.ssl = false

sms.url.dont_encode_url = true

# POST or GET requests

sms.sender.requestType=POST

• Add the below environment variables to your egov-user deployment. This will enable your login without OTP.

CITIZEN_LOGIN_PASSWORD_OTP_FIXED_VALUE: 123456

CITIZEN_LOGIN_PASSWORD_OTP_FIXED_ENABLED: true

Implementation Kit Usage Steps

Pre-requisites:

• Install the Python 3.7.0 version using the following link (cannot be installed in Windows version older than Windows XP): https://www.python.org/downloads/ Set Python environment variables and Path using the following help doc: https://docs.python.org/3/using/windows.html

• Clone the implementation kit repo using the following link: