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

​All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

Overview

The DIGIT system supports multiple languages. To add a new language, it should be configured in the MDMS.

Pre-requisites

Before you proceed with the configuration, make sure 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

• Users can view the web page of the DIGIT application in the language of their choice by selecting it from the available languages.

• SMS and Emails of information about the transactions on the DIGIT application can be received in languages based on the selection.

Deployment Details

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

Configuration Details

A new language is added in StateInfo.json In MDMS, the file StateInfo.json, under common-masters folder holds the details of the language to be added.

{
  "tenantId": "uk", //<ReplaceWithDesiredTenantId>
  "moduleName": "common-masters",
  "StateInfo": [
    {
      "languages": [
        {
          "label": "ENGLISH",  
          "value": "en_IN"   
        },
        {
          "label": "हिंदी",     // <ReplaceWithTheRequiredLanguageName>
          "value": "hi_IN"   // <ReplaceWithTheRequiredLanguageKey>
        }
      ]
    }
  ]
}

Language is added as an array element under the array named “languages”. Each language element is a label and value pair. By default English language is added. Other languages can be added as an additional/new language which the system will support. System to support multiple ie., more than one language, those languages are added in StateInfo.json as below.

"languages": [
        {
          "label": "ENGLISH",  
          "value": "en_IN"   
        },
        {
          "label": "हिंदी",     // <ReplaceWithTheRequiredLanguageName>
          "value": "hi_IN"   // <ReplaceWithTheRequiredLanguageKey>
        },
        {
          "label": "ಕನ್ನಡ", // <ReplaceWithTheRequiredLanguageName>
          "value": "kn_IN" <ReplaceWithTheRequiredLanguageKey>
        },
        {
          "label": "language3", // <ReplaceWithTheRequiredLanguageName>
          "value": "language3key" <ReplaceWithTheRequiredLanguageKey>
        }
      ]

In UI the labels and master values that populate in dropdown or textboxes are added as a key for localization. For eg., when a user logs in, at the top of the inbox page, a welcome message in the English language shows as “Welcome User name“. The text “Welcome” in English localization for the Key “CS_LANDING_PAGE_WELCOME_TEXT”.

For all the labels or master value keys, localization should be pushed to the database through the endpoints for all the languages added to the system. The SMS/Email are also added as keys for which values are pushed in all the languages to the database.

Localization format for keys

{
  "code": "unique key referred ",
  "message": "Value to be shown in UI or send in SMS/Email",
  "module": "rainmaker-<modulename>",
  "locale": "<language key>"
}

Sample of localization

In the Hindi language

{
  "code": "CS_LANDING_PAGE_WELCOME_TEXT",
  "message": "आपका स्वागत है ",
  "module": "rainmaker-pgr",
  "locale": "hi_IN"
}

In the English language

{
  "code": "CS_LANDING_PAGE_WELCOME_TEXT",
  "message": "Welcome",
  "module": "rainmaker-pgr",
  "locale": "en_IN"
}

For the languages added in the system if values are not pushed to the database then for the labels or master data, the key will appear in UI. If values for SMS/Email are not pushed, the SMS/Email will not be received.

Any one language from the multiple added language can be set as default. For example, if English, Hindi and Kannada are three languages added in the StateInfo.json and Kannada has to be set as the default language. Set the language key in the text "defaultLanguage" in the StateInfo.json as the value.

{
  "tenantId": "uk",   //<ReplaceWithDesiredTenantId>
  "moduleName": "common-masters",
  "StateInfo": [
    {
      "defaultLanguage": "kn_IN",  //<ReplaceWithTheLanguageKey>
        "languages": [
        {
          "label": "ENGLISH",  
          "value": "en_IN"   
        },
        {
          "label": "हिंदी",     
          "value": "hi_IN"   
        },
        {
          "label": "ಕನ್ನಡ", // <ReplaceWithTheRequiredLanguageName>
          "value": "kn_IN" <ReplaceWithTheRequiredLanguageKey>
        }
      ]
    }
  ]
}

Reference Docs

Doc Links

Details coming soon...

Overview

SMS and Email communicate the necessary information/updates to the users regarding the multiple transactions on DIGIT applications. For example, when a Trade License application is initiated or forwarded or approved or payment is done in the DIGIT system, the applicant and payer (if the payer is other than the applicant) are informed about the status of the Trade License application through SMS/Email. The language for SMS and Email can be set as per requirement/choice.

Pre-requisites

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

• Knowledge of DIGIT applications is required.

• User should be aware of transactional steps in the DIGIT application.

Key Functionalities

• Users can receive Emails and SMS with necessary information/updates in the decided language.

• The language can be decided by the end-users (citizens or employees). End-users can select the language before logging in or after logging in from the inbox page.

• If the language is not chosen by the end-user, then SMS/Email is received in the language of, State requirement-based state-level configured language.

Configuration Details

Sms and Email localization are pushed to the database through the endpoints for all the languages added to the system. Localization format for SMS/Email

{
     "code": "unique key referred for sms or email",
     "message": "sms value or email to be received",
     "module": "rainmaker-<modulename>",
     "locale": "<language key>"
  }

Sample of SMS localisation for Trade License application initiation English localization

{
  "code": "tl.en.counter.initiate",
  "message": "Dear <1>, Your Trade License application number for <2> has been generated. Your application no. is <3> You can use this application number to know your application status. Thank You. NagarSewa.",
  "module": "rainmaker-tl",
  "locale": "en_IN"
}

Hindi localization

{
  "code": "tl.en.counter.initiate",
  "message": "प्रिय <1>, <2> के व्यापार लाइसेंस के आवेदन के लिए आपका व्यापार लाइसेंस आवेदन संख्या <3> है। आप इस आवेदन संख्या का उपयोग अपनी आवेदन स्थिति जानने के लिए कर सकते हैं। धन्यवाद। नगरसेवा।",
  "module": "rainmaker-tl",
  "locale": "hi_IN"
}

The default language for SMS and Email can be set by

• Clicking on the preferred language from the available language button, on the language selection page, which opens before the login page.

• On the citizen or employee inbox page, the language can be selected from the drop-down, available in the right corner of the inbox title bar.

• If the language is not chosen by the citizen or employee, then SMS/Email is received in the default configured language. For example, Hindi, English and Kannada are added as three languages in the system for a specific state. In case the state decides that out of these three languages, Kannada should be configured as the default language. In such case Kannada is set as the default language in the MDMS. So when the end-user does not choose any language then SMS/Email is sent in the Kannada language.

The selected language key is sent as a parameter along with other required transaction parameters to the back-end code.

In the back end, to send SMS/Email logic, the language key is checked and based on the language key and SMS unique key, the message is fetched from the database.

Overview

Persister Service persists data in the database in a sync manner providing very low latency. The queries which have to be used to insert/update data in the database are written in yaml file. The values which have to be inserted are extracted from the json using jsonPaths defined in the same yaml configuration.

Sample Configuration

Below is a sample configuration which inserts data in a couple of tables.

The above configuration is used to insert data published on the kafka topic save-pgr-request in the tables eg_pgr_service_v2 and eg_pgr_address_v2. Similarly, the configuration can be written to update data. Following is a sample configuration:

The above configuration is used to update the data in tables. Similarly, the upsert operation can be done using ON CONFLICT() function in psql.

Variable List

The table below describes each field variable in the configuration.

Overview

This documentation talks about building a new dashboard in the DSS and also it defines the configurations required for the analytics service. Analytics microservice which is responsible for building, fetching, aggregating, and computing the data on ElasticSearch to a consumable data response. Which shall be later used for visualizations and graphical representations.

Pre-requisites

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

• Prior Knowledge of JSON

• Prior Knowledge of Elasticsearch Query Language

• Prior Knowledge of Kibana

• DSS setup

Key Functionalities

1. Adding new roles for dashboards

2. Adding a new dashboard

3. Adding new visualizations in the existing dashboard

4. Adding new charts for visualizations

Configuration Details

1. Adding Roles and Dashboards

• To add a new role, make changes in the RoleDashboardMappingsConf.json (roles node) configuration file as below. In the roles array, every JSON object is unique based on the id. The name of the role is defined in the roleName attribute.

• If we want to assign any dashboard to a particular role, add the id and name of the dashboard in the dashboard array. This dashboard id is unique and it’s referred to as the MasterDashboardConfig.json file configuration.

Below is a sample to add a new role object

2. Adding a new Dashboard

• To add a new dashboard, make changes in the MasterDashboardConfig.json (dashboards node) as below.

• Add the new JSON object in the dashboards array. Add the dashboard name in the name attribute, Id should be unique, which is used for assigning a role for the dashboard. We will talk about visualizations below.

3. Adding new visualizations in the existing dashboard

• To add new visualizations, make changes again in the MasterDashboardConfig.json (vizArray node) as below. Add the visualization name to the name attribute. We will add all the visualizations in the vizArray array. vizArray will contain the name of the visualization, vizType as visual type, noUnit, and charts.

• charts array contains chart API configuration query details. The id is referred to as the chartapiconfig.json file’s key to fetch the required data from elastic search’s index. And the name attribute is referred to as the name of the chart in localization.

4. Adding charts for visualizations

• To add a new chart, chartApiConf.json has to be modified as shown below. A new chartid (key of the JSON) has to be added to the chart node object. The chartid JSON contains the chart name, chart type, valueType, documentType, aggregationPaths and queries attribute.

• Types of the chart: Metric, Pie, Line, Table, and xtable

• AggregationPaths: Query result will take from this path.

• valueType: Based on the value type result will be shown in the UI. Different types of valueType are Amount, percentage, and number.

• queries array will contain the information of the module, requestQueryMap (request param of the API), dateRefField (Based on this field date data will be filtered), indexName, and aggrQuery. We can add multiple module queries in a single chart.

Reference Docs

Doc Links

Overview

A decision support system (DSS) is a composite tool that collects, organizes, and analyzes business data to facilitate quality decision-making for management, operations, and planning. A well-designed DSS aids decision-makers in compiling a variety of data from many sources: raw data, documents, and personal knowledge from employees, management, executives, and business models. DSS analysis helps organizations identify and solve problems, and make decisions

This document explains the steps on how to define the configurations & set up the new dashboard in the DSS.

Pre-requisites

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

• Prior knowledge of Spring boot

• Prior knowledge of Kafka

• Prior knowledge of Elastic Search

• Prior knowledge of Kibana

• Prior knowledge of EQL (Elastic Query Language)

• Prior knowledge of JSON

Key Functionalities

1. Creating a DSS dashboard schema

2. DSS ingest service APIs

3. Ingest service configurations

4. Creating a Kafka sync connector to push the data to elastic search

1. Creating a DSS dashboard schema

When we are going to start indexing the DSS collection v2 index. We should create the schema in the ES using the Kibana query as there in the below file.

2. DSS ingest service API

3. Ingest service configurations

• Transform collection schema for V2

  • This transform collection v1 configuration file is used to map the incoming data. This mapped data will go inside the data object in the DSS collection v2 index.

• Here: $i, the variable value that gets incremented for the number of records of paymentDetails.

  $j, the variable value that gets incremented for the number of records of billDetails.

• Enrichment Domain Configuration

  • This configuration defines and directs the Enrichment Process that the data goes through.

  • For example, if the data which is incoming is belonging to a Collection Module data, then the Collection Domain config is picked. And based on the Business Type specified in the data, the right config is picked.

  • In order to enhance the data of Collection, the domain index specified in the configuration is queried with the right arguments and the response data is obtained, transformed and set.

• Topic Context Configuration

  • Topic Context Configuration is an outline to define which data is received on which Kafka Topic.

  • Indexer Service and many other services are sending out data on different Kafka Topics. If the Ingest Service is asked to receive those data and pass it through the pipeline, the context and the version of the data being received have to be set. This configuration is used to identify as in which Kafka topic consumed the data and what is the mapping for that.

• JOLT Domain Transformation Schema

  • JOLT is a JSON to JSON Transformation Library. In order to change the structure of the data and transform it in a generic way, JOLT has been used.

  • While the transformation schemas are written for each Data Context, the data is transformed against the schema to obtain transformed data.

• Validator Schema

  • Validator Schema is a configuration Schema Library from Everit Bypassing the data against this schema, it ensures that the data abides by the rules and requirements of the schema which has been defined.

• Enhance Domain configuration

  • This configuration defines and directs the Enrichment Process that the data goes through.

  • For example, if the Data which is incoming is belonging to a Collection Module data, then the Collection Domain Config is picked. And based on the Business Type specified in the data, the right config is picked and the final data is placed inside the domain object.

  • In order to enhance the data of Collection, the domain index specified in the configuration is queried with the right arguments and the response data is obtained, transformed and set.

4. Creating a Kafka sync connector to push the data to the Elasticsearch

• Configure the Kafka topics in the environments or Ingest pipeline application properties as shown below.

• To start the indexing we will create a connecter that will take data from the topic and push it to the index we have mentioned in the "transforms.TopicNameRouter.replacement" and mention the ES host in the Kafka connection we have to mention the host URL in “connection.url”.

• To create the Kafka connector run the below curl command inside the playground pod:

Reference Docs

Doc Links

This section provides a step-by-step guide to setting up workflows and configuring the workflows for DIGIT entities.

• Setting Up Workflows

• Configuring Workflows For An Entity

• Workflow Auto Escalation

​All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

This section walks you through the steps to adding a new language or setting up the default language on the DIGIT system.

• Adding New Language

• Setting Up Default Language For SMS & Emails

​All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

Overview

The objective of this functionality is to provide a mechanism to trigger action on applications that satisfy certain predefined criteria.

Sample Configuration

Looking at sample use cases, the majority of use cases can be summarised as performing action ‘X’ on applications in state ‘Y’ and have exceeded the state SLA by ‘Z’ days. We can write one query builder which takes this state ‘Y’ and SLA exceeded by ‘Z’ as search params and then we can perform action X on the search response. This has been achieved by defining an MDMS config like below:

In the above configuration, we define the condition for triggering the escalation of applications. The above configuration triggers escalation for applications in RESOLVED state which have exceeded stateSLA by more than 1.0 day and it will trigger the escalation by performing CLOSERESOLVEDCOMPLAIN on the applications. Once the applications are escalated the processInstances are pushed on the pgr-auto-escalation topic. We have done a sample implementation for pgr-services, where we have updated the persister configuration to listen on this topic and update the complaint status accordingly.

The auto-escalation for businessService PGR will be triggered when the following API is called:

Note that the businessService is a path param. (For example, if the escalation has to be done for tl-services NewTL workflow the URL will be 'http://egov-workflow-v2.egov:8080/egov-workflow-v2/egov-wf/auto/NewTL/_escalate').

These APIs have to be configured in the cron job config so that they can be triggered periodically according to the requirements. Only users with role AUTO_ESCALATE can trigger auto-escalation so first create users with statelevel AUTO_ESCALATE roles first and then add that user in the userInfo of the requestInfo. This step has to be done because the cron job does internal API calls and Zuul won’t enrich the userInfo.

For setting up autoescalation trigger the workflow also needs to be updated. For example to add auto escalate trigger on RESOLVED state with action CLOSERESOLVEDCOMPLAIN in PGR businessService, we will have to search the businessService and add the following action in the Actions array of RESOLVED state and call update API.

Suppose an application gets auto-escalated from state ‘X' to state 'Y’, employees can look at these escalated applications through the escalate search API. The following sample cURL can be used to search auto-escalated applications of the PGR module belonging to Amritsar tenant -

Overview

Workflow is defined as a sequence of tasks that has to be performed on an application/Entity to process it. The egov-workflow-v2 is a workflow engine which helps in performing these operations seamlessly using a predefined configuration. We will discuss how to create this configuration for a new product in this document.

Pre-requisites

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

• egov-workflow-v2 service is up and running

• Role-Action mapping is added for business Service APIs

Key Functionalities

• Create and modify workflow configuration according to the product requirements

• Configure State level as well BusinessService level SLA to efficiently track the progress of the application

• Control access to perform actions through configuration

Deployment Details

1. Deploy the latest version of egov-workflow-v2 service

2. Add businessService persister yaml path in persister configuration

3. Add Role-Action mapping for BusinessService APIs

4. Overwrite the egov.wf.statelevel flag ( true for state level and false for tenant level)

Configuration Details

The Workflow configuration has 3 levels of hierarchy: a. BusinessService b. State c. Action The top-level object is BusinessService, it contains fields describing the workflow and a list of States that are part of the workflow. The businessService can be defined at the tenant level like pb.amritsar or at the state level like pb. All objects maintain an audit sub-object which keeps track of who is creating and updating and the time of it.

Each State object is a valid status for the application. The State object contains information about the state and what actions can be performed on it.

The action object is the last object in the hierarchy, it defines the name of the action and the roles that can perform the action.

The workflow should always start from the null state as the service treats new applications as having null as the initial state. eg:

In the action object whatever nextState is defined, the application will be sent to that state. It can be to another forward state or even some backward state from where the application has already passed (generally, such actions are named SENDBACK)

SENDBACKTOCITIZEN is a special keyword for an action name. This action sends back the application to the citizen’s inbox for him to take action. A new State should be created on which Citizens can take action and should be the nextState of this action. While calling this action from the module assignees should be enriched by the module with the UUIDs of the owners of the application

Integration Details

Reference Docs

Doc Links

API List

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

Do's and Don'ts

• Always define the Yaml for your APIs as the first thing using Open API 3 Standard ().

• 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 a 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 the 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 the POST body also and the POST body should take priority over query params.

• Provide additional detail for objects in _create and _update APIs so that custom requirements can use these fields.

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

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

• Mandatory fields should be the 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. Example -

  • (Citizen/ Employee/ Owner)

  • (Response sent in case of errors)

  • TODO: Add all the models here

• For receiving files in an API, do not 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 these principles.

Overview

This page provides details on how to configure the generic GET and POST SMS gateway interface.

Configuration Details

To use the generic GET/POST SMS gateway, first, configure the service application properties sms.provider.class=Generic

This defines the generic interface to be used. This is the default implementation that works with most SMS providers.

The generic implementation supports -

• GET or POST-based API

• Query params, form data, JSON Body

To configure the URL of the SMS provider use sms.provider.url property.

To configure the HTTP method used configure the sms.provider.requestType property to either GET or POST.

To configure form data or json api set sms.provider.contentType=application/x-www-form-urlencoded or sms.provider.contentType=application/json respectively

To configure which data needs to be sent to the API below property can be configured:

• sms.config.map={'uname':'$username', 'pwd': '$password', 'sid':'$senderid', 'mobileno':'$mobileno', 'content':'$message', 'smsservicetype':'unicodemsg', 'myParam': '$extraParam' , 'messageType': '$mtype'}

• sms.category.map={'mtype': {'*': 'abc', 'OTP': 'def'}}

• sms.extra.config.map={'extraParam': 'abc'}

sms.extra.config.map is not used currently and is only kept for custom implementation which requires data that doesn't need to be directly passed to the REST API call

sms.config.map is a map of parameters and their values

Special variables that are mapped

• $username maps to sms.provider.username

• $password maps to sms.provider.password

• $senderid maps to sms.senderid

• $mobileno maps to mobileNumber from SMS fetched message

• $message maps to the message from the kafka-fetched message

• $<name> any variable that is not from the above list, is first checked in sms.category.map and then in application.properties and then in the environment variable with full upper case and _ replacing -, space or .

So if you use sms.config.map={'u':'$username', 'p':'password'} the API call will be passed <url>?u=<$username>&p=password.

Message Success or Failure

Message success delivery can be controlled using the below properties

• sms.verify.response (default: false)

• sms.print.response (default: false)

• sms.verify.responseContains

• sms.success.codes (default: 200,201,202)

• sms.error.codes

If you want to verify some text in the API call response set sms.verify.response=true and sms.verify.responseContains the text that should be there in the response.

Blacklisting or Whitelisting numbers

It is possible to whitelist or blacklist phone numbers to which the messages should be sent. This can be controlled using the below properties:

• sms.blacklist.numbers

• sms.whitelist.numbers

Both properties will contain a list of separated numbers or number patterns. To use patterns use X to match any digit or * to match the number of digits.

For instance, sms.blacklist.numbers=5*,9999999999,88888888XX will blacklist any phone number starting with 5, or the exact number 9999999999 and all numbers starting from 8888888800 to 8888888899

Prefixing

Few 3rd parties require a prefix of 0 or 91 or +91 with the mobile number. In such a case you can use sms.mobile.prefix to automatically add the prefix to the mobile number coming in the message queue.

Overview

Rainmaker has a reporting 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 the query result has huge data, then it will impact the whole application's performance.

Root Cause

The following are 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 turn returns 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 the required data

Impact

Because of heavy reporting, the following things impact the platform -

• When we execute a complex query on the database, a thread from the connection pool blocks the query execution.

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

• When the max request timeout is crossed, the API gateway returns a timeout error. But still, the connection thread on the database is active. Then all these types of idle threads occupy the database resources like memory, and the CPU which in turn increases the load on the database.

• Sometimes when running huge queries, the time taken by the query leads to a broken pipe issue which causes more memory leaks and out-of-heap memory type issues. Because of this, the service frequently restarts automatically.

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

Overview

Configuring a 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

The 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 permission to edit the git repository to add the report configuration

• User with permission 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 turnaround time is less.

Deployment Details

After adding the new report/ editing the 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

Overview

Each service integrated with the egov-workflow-v2 service needs to first define the workflow configuration which describes the states in the workflow, the action that can be taken on these states, who all can perform those actions, SLA etc. This configuration is created using APIs and is stored in DB. The configuration can be created at either the state level or the tenant level based on the requirements.

Pre-requisites

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

• egov-workflow-v2 service is up and running

• Role Action mapping is added for the BusinessService APIs

Key Functionalities

• Create and modify workflow configuration

• Configure State level as well BusinessService level SLA

• Control access to workflow actions from the configuration

• Validates if the flow defined in the configuration is complete during the creation

Deployment Details

1. Deploy the latest version of egov-workflow-v2 service

2. Add Role-Action mapping for BusinessService APIs (preferably add _create and update only for SUPERUSER. search can be added for CITIZEN and required employee roles like TL__CEMP etc. )

3. Overwrite the egov.wf.statelevel flag ( true for state level and false for tenant level)

4. Add businessService persister yaml path in persister configuration

Configuration Details

Create the businessService JSON based on product requirements. Following is a sample json of a simple 2-step workflow where an application can be applied by a citizen or counter employees and then can be either rejected or approved by the approver.

{
      "tenantId": "pb",
      "businessService": "PGR",
      "business": "pgr-services",
      "businessServiceSla": 432000000,
      "states": [
        {
          "sla": null,
          "state": null,
          "applicationStatus": null,
          "docUploadRequired": false,
          "isStartState": true,
          "isTerminateState": false,
          "isStateUpdatable": true,
          "actions": [
            {
              "action": "APPLY",
              "nextState": "PENDINGFORASSIGNMENT",
              "roles": [
                "CITIZEN",
                "COUNTER_EMPLOYEE"
              ]
            }
          ]
        },
        {
          "sla": null,
          "state": "APPLIED",
          "applicationStatus": "APPLIED",
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": false,
          "isStateUpdatable": false,
          "actions": [
            {
              "action": "APPROVE",
              "nextState": "APPROVED",
              "roles": [
                "APPROVER"
              ]
            },
            {
              "action": "REJECT",
              "nextState": "REJECTED",
              "roles": [
                "APPROVER"
              ]
            }
          ]
        },
        {
          "sla": null,
          "state": "REJECTED",
          "applicationStatus": "REJECTED",
          "isStateUpdatable": false,
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": true
        },
        {
          "sla": null,
          "state": "APPROVED",
          "applicationStatus": "APPROVED",
          "isStateUpdatable": false,
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": true
        }
      ]
    }

Once the businessService json is created add it in the request body of _create API of workflow and call the API to create the workflow.

To update the workflow first search the workflow object using _search API and then make changes in the businessService object and then call _update using the modified search result. (States cannot be removed using _update API as it will leave applications in that state in an invalid state. In such cases first, all the applications in that state should be moved forward or backward state and then the state should be disabled through DB directly)

Integration Details

Integration Scope

The workflow configuration can be used by any module which performs a sequence of operations on an application/Entity. It can be used to simulate and track processes within organisations to increase efficiency and accountability.

Integration Benefits

Integrating with workflow service provides a way to have a dynamic workflow configuration which can be easily modified according to the changing requirements. The modules don’t have to deal with any validations regarding workflows such as authorisation of the user to take an action. If documents are required to be uploaded at a certain stage etc. as they are automatically handled by the egov-workflow-v2 service based on the configuration defined. It also automatically keeps updating SLA for all applications and provides a way to track the processing time of an application.

Steps to Integration

1. To integrate, host of egov-workflow-v2 should be overwritten in the helm chart

2. /egov-workflow-v2/egov-wf/businessservice/_search should be added as the endpoint for searching workflow configuration. (Other endpoints are not required once workflow configuration is created)

3. The configuration can be fetched by calling _search API

Reference Docs

Doc Links

API List

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

__

Overview

Roles define the permissions of a user to perform a group of tasks. The tasks are created as API calls to do certain actions when a request for those calls is sent by the system. For example, the key tasks for a Trade License application include initiate/apply, forward, approve or payment. For Trade License initiate two API calls, “create” and “update” is required. Create API creates and saves the application in the database and returns an application number. Update API saves the required attached documents in the file store and returns the success acknowledgement message of the application created. These create and update API access permission is granted to the roles named Citizen and TL counter employee.

Access permission is granted by mapping roles with APIs. Users assigned with the citizen or TL counter employee roles can initiate/apply the Trade License application.

Pre-requisites

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

• Knowledge of DIGIT applications is required.

• Users should be aware of transactional steps in the DIGIT application.

• 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

In mapping roles with APIs, permission to perform a certain task can be restricted based on the requirement. For example, only the user with Role TL Counter Employee or Citizen can initiate the Trade License applications.

Deployment Details

After mapping roles with APIs, the MDMS service needs to be restarted to read the newly added data.

Configuration Details

APIs are added in actions-test.json and termed as action. In MDMS, file actions-test.json, under ACCESSCONTROL-ACTIONS-TEST folder APIs are added. API Sample:

{
  "tenantId": "uk",
  "moduleName": "ACCESSCONTROL-ACTIONS-TEST",
  "actions-test": [
    {
      "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": ""
     },
     {
      "id": 1686,
      "name": "Update TradeLicense",
      "url": "/tl-services/v1/_update",
      "parentModule": "",
      "displayName": "Update TradeLicense",
      "orderNumber": 0,
      "enabled": false,
      "serviceCode": "tl-services",
      "code": "null",
      "path": ""
    }
   ]
  }   

APIs are added as action array elements with the request URL and other required details for the array "actions-test"

Each action is defined as a key-value pair:

Roles are added in roles.json In MDMS, file roles.json, under ACCESSCONTROL-ROLES folder roles are added. More about roles can be checked in the below link: Adding roles to System

Mapping of roles and APIs/actions is added in roleactions.json, under the folder ACCESSCONTROL-ROLEACTIONS. Sample mapping:

{
  "tenantId": "uk",
  "moduleName": "ACCESSCONTROL-ROLEACTIONS",
  "roleactions": [
    {
      "rolecode": "TL_CEMP",
      "actionid": 1685,
      "actioncode": "",
      "tenantId": "uk"
    },
    {
      "rolecode": "CITIZEN",
      "actionid": 1685,
      "actioncode": "",
      "tenantId": "uk"
    }
  ]
}

Role and API/action mapping is added as an array element under array roleactions. Each mapping is defined with key-value pairs. keys are rolecode, actionid, actioncode and tenantId.

Reference Docs

Doc Links

Videos

Overview

In this document, we are coming to learn how to upload APK to the play store and make it available to the end user to download and use it from the play store.

Pre-requisites

Before starting the process of uploading the apk to the play store the following requirements are a must.

• Make sure that the signed apk (signed apk has a key generated, which is used to release different versions of the apk) is generated for the application that you want to upload to the play store.

• Make sure that you have a Google Play account and agree to the stated terms and conditions. The payment must be completed for the account before it is ready for uploading an apk to the play store.

• two screenshots of your app and they must be at least 320 pixels wide and be in a PNG or JPEG format.

• You must also add your high-resolution app icon. It must be 512 by 512 pixels and it must be in 32-bit PNG format. This icon will be visible on the Google Play app’s page and in search results.

• Upload a feature graphic image, that will be visible at the top of the Google Play app’s page. This image must be 1024 by 500 pixels, and maybe in JPEG or 24-bit PNG format.

• Also, prepare a small description of the app in four to five lines.

Key Functionalities

The use of deploying the apk to the play store is to enable the user to download the apk from the play store and use it whenever needed. By uploading the apk to the play store our app will be available to all end-users around the world at their fingertips.

Deployment Details

Now, we are going to learn step by step procedure of uploading apk to the play store.

Open the Google Play console by entering the URL (https://play.google.com/apps/publish/) and log in with the user credentials.

After login in the following screen can be seen.

Now on the top-right click on the Create Application button and you get a popup to enter the title of the apk. Refer to the screenshot below and click on create.

After clicking the create you will be redirected to the page where we need to enter the product details, graphics assets, categorization ..etc

Under the Product Details section, enter the description that we have prepared in the beginning.

Under the assets section, we need to attach at-least two screenshots of the application, a high-resolution thumbnail icon and a feature graphic image.

Under categorization, select the application type and category.

Coming to the contact section, add the website URL, email and also phone number if you wish to add one.

After next comes the privacy policy section where you can enter the link to the privacy and policy page and save it as a draft.

After saving as a draft on the “right side menu” select the option “App Release”. In the app release page under the “production track” click on Manage. Click on create a release on the next screen. Click on Continue on the next page under the “ App signing by google play”.

In the next page, under android app bundles and APK to add section add your APK generated also enter the release name and add the description inside the <en-US> tag related to that APK and save the entered data.

After that click on the “calculate Rating” then in the click “apply Rating Button”.

Next will be the “Pricing and Distribution” in the “Right side Menu”. In this page we have the option to select the cost of APK to download or free, also select the countries app needs to be available and also answer the questionnaires that are asked and click on the save Drafts.

Finally, again go the “App Release” in the right side menu and click on the “ Edit Release” button in the Production Track section and save the details and at the end click “Start role out to production” and click confirm.

The following screen acknowledges your process is ended.

That is all about uploading APK to the play store. You can check the status of the application on the right side menu under the “ All Application”. It takes some hours to appear in the play store. Wait for the APK to appear in the play store. We can also check the details of the APK in the Dashboard.

Overview

An eGov core application that handles uploading different kinds of files to servers including images and different document types.

Pre-requisites

1. Prior Knowledge of Java/J2EE

2. Prior Knowledge of Spring Boot

3. Prior Knowledge of REST APIs and related concepts like path parameters, headers, JSON etc

4. Prior knowledge of AWS and Azure

Key Functionalities

The filestore application takes in a request object which contains an image/document or any kind of file and stores them in a disk/AWS/azure. Depending upon the configurations, additional implementations can be written for the app interface to interact with any other remote storage.

The requested file to be uploaded is taken in form of a multi-part file then saved to the storage and a uuid is returned as a unique identifier for that resource. This is used to fetch the documents later.

In the case of images, the application creates three more additional copies of the file in the likes of large, medium and small for the usage of thumbnails or low-quality images in the case of mobile applications.

The search API takes the uuid, tenantid as mandatory url params and a few optional parameters and returns the presigned url of the files from the server. In the case of images, a single string containing multiple urls separated by commas is returned representing different sizes of images stored.

Setup And Configuration

The Application is present among the core group of applications available in the eGov-services git repository. The spring boot application needs lombok extension added in your ide to load it. Once the application is up and running API requests can be posted to the URL and ids can be generated.

In case of intellij, the plugin can be installed directly, for eclipse the lombok jar location has to be added in eclipse.ini file in this format -javaagent:lombok.jar.

In case the url is unavailable, please go to the docs folder of egov-services git repo and find the yaml for egov-filestore.

The application needs at least one type of storage available for it to store the files. It can be either file storage, AWS S3 or azure. More storage types can be added by extending the application interface too.

To work any of the file storage there are some application properties that need to be configured.

DiskStorage

The mount path of the disk should be provided in the following variable to save files in the disc. file.storage.mount.path=path.

Following are the variables that needs to be populated based on the aws/azure account you are integrating with.

How to enable Minio SDC

minio.url=http://minio.backbone:9000(Minio server end point)

isS3Enabled=true(Should be true)

aws.secretkey={minio_secretkey}

aws.key={minio_accesskey}

fixed.bucketname=egov-rainmaker(Minio bucket name)

minio.source=minio

How to enable AWS S3

minio.url=https://s3.amazonaws.com

isS3Enabled=true(Should be true)

aws.secretkey={s3_secretkey}

aws.key={s3_accesskey}

fixed.bucketname=egov-rainmaker(S3 bucket name)

minio.source=minio

AZURE

isAzureStorageEnabled - informing the application whether Azure is available or not

azure.defaultEndpointsProtocol - type of protocol https

azure.accountName - name of the user account

azure.accountKey - secret key of the user account

NFS

isnfsstorageenabled-informing the application whether NFS is available or not <True/False>

file.storage.mount.path - <NFS location, example /filestore>

source.disk - diskStorage - name of storage

disk.storage.host.url=<Main Domain URL>

Allowed formats to be uploaded

# the default format of the allowed file formats goes in a set bracket with string inside it - {"jpg","png"} - please follow the same.

allowed.formats.map={jpg:{'image/jpg','image/jpeg'},jpeg:{'image/jpeg','image/jpg'},png:{'image/png'},pdf:{'application/pdf'},odt:{'application/vnd.oasis.opendocument.text'},ods:{'application/vnd.oasis.opendocument.spreadsheet'},docx:{'application/x-tika-msoffice','application/x-tika-ooxml','application/vnd.oasis.opendocument.text'},doc:{'application/x-tika-msoffice','application/x-tika-ooxml','application/vnd.oasis.opendocument.text'},dxf:{'text/plain'},csv:{'text/plain'},txt:{'text/plain'},xlsx:{'application/x-tika-ooxml','application/x-tika-msoffice'},xls:{'application/x-tika-ooxml','application/x-tika-msoffice'}}

The key in the map is the visible extension of the file types, the values on the right in curly braces are the respective tika types of the file. these values can be found on the tika website or by passing the file through the tika functions.

Available features

1. Upload POST API to save the files on the server

2. Search Files GET API to retrieve file based only on id and tenantid

3. Search URLs GET API to retrieve pre-signed urls for a given array of ids

Deployment Details

1. Deploy the latest version of Filestore Service

2. Add Role-Action mapping for APIs

Integration

Integration Scope

The filestore service is used to upload and store documents that citizens add while availing services from ULBs.

Integration Benefits

• Can perform file upload independently without having to add file upload specific logic in each module.

Steps to Integration

1. To integrate, a host of filestore modules should be overwritten in the helm chart.

2. /filestore/v1/files should be added as the endpoint for uploading the file in the system

3. /filestore/v1/files/url should be added as the search endpoint. This method handles all requests to search existing files depending on different search criteria

Postman Collection

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 permission to edit the git repository where reports are configured.

• 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

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

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

• Users 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

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

Overview

The objective of this service is to create a common point to manage all the email notifications being sent out of the platform. Notification email service consumes email requests from the Kafka notification topic and processes them to send it to a third party service. Modules like PT, TL, PGR etc make use of this service to send messages through the Kafka Queue.

Pre-requisites

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

• Prior Knowledge of Java/J2EE

• Prior Knowledge of SpringBoot

• Prior Knowledge of third party API integration

• Prior Knowledge of REST APIs and related concepts like path parameters, headers, JSON etc

• Prior Knowledge of Kafka and related concepts like Producer, Consumer, Topic etc.

Key Functionalities

• Provide a common platform to send email notifications to the users

• Support localised email.

Configuration Details

egov-notification-mail is a consumer that listens to the egov.core.notification.email topic, reads the message and generates email using the SMTP Protocol. The services need that the senders email is configured. On the other hand, if the senders email is not configured, the service gets the email id by internally calling egov-user service to fetch email id. Once the email is generated, the content is localized by egov-localization service after which it is notified to the email id.

Deployment Details

1. Deploy the latest version of the notification email service.

2. Make sure the consumer topic name for email service is added in deployment configs.

Integration

Integration Scope

The email notification service is used to send out email notifications for all miscellaneous / adhoc services that citizens avail of from the ULBs.

Integration Benefits

• Can perform service-specific business logic without impacting the other modules.

• In the future, if we want to expose the application to citizens then it can be done easily.

Steps to Integration

1. To integrate, the client service should send email requests to the email notification consumer topic.

Overview

An eGov core application that provides locale-specific components and translation of text for the eGov group of applications.

Pre-requisites

1. Prior Knowledge of Java/J2EE.

2. Prior Knowledge of Spring Boot.

3. Prior Knowledge of REST APIs and related concepts like path parameters, headers, JSON etc.

4. Prior knowledge of Redis and postgres.

Key Functionalities

The localization application stores the locale data in the format of key and value along with the module, tenantid and locale. Module defines which application of eGov owns the locale data and tenantId do the same for the tenant. Locale refers to the specific location where data is being added.

The request can be posted through the post API with the above-mentioned variables in the request body.

Once posted the same data can be searched based on the module, locale and tenantId as keys.

The Data posted to the localization service is permanently stored in the database and is loaded into the Redis cache for easy access. Each time the new data is added to the application the Redis cache is refreshed.

Deployment Details

1. Deploy the latest version of Localization Service.

2. Add Role-Action mapping for APIs.

Integration

Integration Scope

The Localization service is used to store key-value pairs of metadata in different languages for all miscellaneous / adhoc services which citizens avail from ULBs.

Integration Benefits

• Can perform service-specific business logic without impacting the other module.

• Provides the capability of having multiple languages in modules.

Steps to Integration

1. To integrate, a host of localization-services modules should be overwritten in the helm chart.

2. /localization/messages/v1/_upsert should be added as the create endpoint for creating localization key-value pairs in the system

3. /localization/messages/v1/_search should be added as the search endpoint. This method handles all requests to search existing records depending on different search criteria

Resources

Postman Collection

Swagger Contract

Overview

In a bid to avoid unnecessary repetition of codes to generate ids and to have centralized control over the logic so that burden of maintenance is reduced from the developers. To create a config based application that can be used without writing even a single line of coding.

Pre-requisites

1. Prior Knowledge of Java/J2EE

2. Prior Knowledge of Spring Boot, Flyway

3. Prior Knowledge of REST APIs and related concepts like path parameters, headers, JSON etc.

Key Functionalities

The application exposes a Rest API to take in requests and provide the ids in response in the requested format. The request format varies from current date information, tenantId*, random number, sequence generated number. Id can be generated by providing a request with any of the above-mentioned information.

*TenantId - is the string representing the individual units called tenants in the DIGIT system which can be a city, town or village.

For instance: An Id Amritsar-PT-2019/09/12-000454-99 contains

Amritsar - which is the name of the city

PT - fixed string representing the module code(PROPERTY TAX)

2019/09/12 - date

000454 - sequence generated number

99 - random number

The id generated in the above-mentioned example needs the following format

[city]-PT-[cy:yyyy/mm/dd]-[SEQ_SEQUENCE_NAME]-[d{4}]

Everything in the square brackets is replaced with the appropriate values by the app.

ID-FORMAT COFNIGURATION

By default, the IDGen service reads the configuration from MDMS. DB Configuration requires access to the DB, so the new preferred method for the configuration is MDMS. The configuration needs to be stored in common-masters/IdFormat.json in MDMS

It is recommended to have the IdFormat as a state-level master. To disable the configuration to be read from DB instead, the environment variable IDFORMAT_FROM_MDMS is set to false.

ID-FORMAT-REPLACEABLE

[FY:] - represents the financial year, the string is replaced by the value of starting year and the last two numbers of the ending year separated by a hyphen. For eg: 2018-19 in the case of the financial year 2018 to 2019.

[cy:] - any string that starts with cy is considered as the date format. The values after the cy: is the format using which output is generated.

[d{5}] - d represents the random number generator, the length of the random number can be specified in flower brackets next to d. If the value is not provided then the random length of 2 is assigned by default.

[city] - The string city is replaced by the city code provided by the respective ulb in the location services.

[SEQ_*] - String starting with seq is considered as sequence names, which gets queried to get the next seq number. If the sequence doesn’t start with the namespace containing “SEQ” then the application is not considered as a sequence. In absence of the sequence, the system throws a DB error.

[tenantid] - replaces the placeholder with the tenantid passed in the request object

[tenant_id] - replaces the placeholder with the tenantid passed in the request object. Replaces all `.` with `_`

[TENANT_ID] - replaces the placeholder with the tenantid passed in the request object. Replaces all `.` with `_`, and changes the case to upper case

idName v/s format

When you use both idName and format in a request. IDGEN first checks if the format for the given idName exists. If it does not exist, then the default format is used.

STATE v/s ULB LEVEL SEQUENCES If you want a state-level sequence, then you need to use a fixed sequence name

{

"format": "PT/[CITY.CODE]/[fy:yyyy-yy]/[SEQ_RCPT_PT_RECEIPT]",

"idname": "pt.receipt.id"

}

But if you want a ULB level sequence, the sequence name should be dynamic based on the tenantid as given in the below example

{

"format": "PT/[CITY.CODE]/[fy:yyyy-yy]/[SEQ_RCPT_PT_[TENANT_ID]]",

"idname": "pt.receipt.id"

}

SEQUENCES AND THEIR CREATION

The SEQ_* replaceable used in id generation is by default expected to use the sequence that already exists in the DB. But this behaviour can be changed and controlled using two environment variables while deploying the service.

• AUTOCREATE_NEW_SEQ: Default is set to false. When set to true, this auto-creates sequences when the format has been derived using provided idName. Since the idName format comes from DB or MDMS, it is a trusted value and this value is set to true. This makes sure that DB configuration is not required as long as MDMS has been configured. It is recommended that each service using idgen should generate id using idName instead of just using passing the format directly. This makes sure that DB configuration is not required for creating sequences.

• AUTOCREATE_REQUEST_SEQ: Default is set to false. When set to true, this auto-creates sequences when the format has been derived using the format parameter from the request. It is recommended to keep this setting to false since anyone with access to idgen can create any number of sequences in DB and overload the DB. Though during the initial setup of an environment this variable can be set to true to create all the sequences when the initial flows are run from the UI and to generate the sequences. And afterwards, the flags should be disabled.

Deployment Details

1. Add MDMS configs required for ID Gen Service and restart the MDMS service

2. Deploy the latest version of ID Generation Service

3. Add Role-Action mapping for APIs

Integration

Integration Scope

The ID Gen service is used to generate unique ID numbers for all miscellaneous / adhoc services which citizens avail from ULBs.

Integration Benefits

• Can perform service-specific business logic without impacting the other module.

• Provides the capability of generating the unique identifier of the entity calling ID Gen service.

Steps to Integration

1. To integrate, a host of idgen-services modules should be overwritten in the helm chart.

2. /egov-idgen/id/_generate should be added as the endpoint for generating ID numbers in the system

API Contract

Overview

An API Gateway provides a unified interface for a set of microservices so that clients do not need to know about all the details of microservices internals.

Digit uses Zuul as an edge service that proxies requests to multiple back-end services. It provides a unified “front door” to our ecosystem. This allows any browser, mobile app or other user interfaces to consume underlying services.

Pre-requisites

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

• Java 8

• egov-user service is running

• egov-accesscontrol service is running

Key Functionalities

• Provides easier API interface to clients

• Can be used to prevent exposing the internal micro-services structure to the outside world.

• Allows to refactor microservices without forcing the clients to refactor consuming logic

• Can centralize cross-cutting concerns like security, monitoring, rate limiting etc

Zuul Components

Zuul has mainly four types of filters that enable us to intercept the traffic in different timelines of the request processing for any particular transaction. We can add any number of filters for a particular url pattern.

• pre filters – are invoked before the request is routed.

• post filters – are invoked after the request has been routed.

• route filters – are used to route the request.

• error filters – are invoked when an error occurs while handling the request.

Zuul Features

• Microservice authentication and security

• Authorization

• API Routing

• Open APIs using Whitelisting

• RBAC filter

• Logout filter for finance module

• Property module tax calculation filter for fire cess

• Request enrichment filter:

• Addition of co-relation id

• Addition of authenticated user’s userinfo to requestInfo.

• Error filter:

  • Error response formatting

• Validation Filter to check if a tenant of a particular module is enabled or not.

• Multitenancy Validation Filter. Take the tenant id from Req body or Query Param and validate against additional tenant role or primary tenant role.

• DevOps efficiency: API Response time logging and Send notification if it is taking more time.

• Rate Throttling

Configuration

Routing Property

For each service, the below-mentioned property has to be added in routes.properties

1-zuul.routes.{serviceName}.path = /{context path of service}/** 2-zuul.routes.{serviceName}.stripPrefix = {true/false} 3-zuul.routes.{serviceName}.url = {service host name}

Rate Limiting Property

For endpoints which requires rate throttling, below mentioned property has to be added in limiter.properties

Deployment Details

1. Deploy the latest version of zuul service.

2. Add zuul routing context paths and service hostname in the configuration.

Integration

Integration Scope

The zuul service is used to act as an API gateway for services that citizens avail of from the ULBs.

Integration Benefits

• Can perform service-specific business logic without impacting the other module.

• Provides the capability of routing and authorizing users for accessing resources.

Steps to Integration

1. To integrate, a host of zuul modules should be overwritten in the helm chart.

Overview

The objective of this service is to create a common point to manage all the SMS notifications being sent out of the platform. Notification SMS service consumes SMS from the Kafka notification topic and processes them to send it to a third party service. Modules like PT, TL, PGR etc make use of this service to send messages through the Kafka Queue.

Pre-requisites

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

• Prior Knowledge of Java/J2EE

• Prior Knowledge of SpringBoot

• Prior Knowledge of third party API integration

• Prior Knowledge of REST APIs and related concepts like path parameters, headers, JSON etc

• Prior Knowledge of Kafka and related concepts like Producer, Consumer, Topic etc.

Key Functionalities

• Provide a common platform to send SMS notifications to users

• Support localised SMS

• Easily configurable with different SMS service providers

Interaction Diagram

Configuration Details

The implementation of the consumer is present in the directory src/main/java/org/egov/web/notification/sms/service/impl.

These are current providers available

• Generic

• Console

• MSDG

The implementation to be used can be configured by setting sms.provider.class.

Console

The Console implementation just prints the message mobile number and message to the console.

Generic implementation

This is the default implementation, which can work with most of the SMS providers. The generic implementation supports below

• GET or POST based API

• Supports query params, form data, JSON Body

To configure the URL of the SMS provider use sms.provider.url property To configure the http method used, configure the sms.provider.requestType property to either GET or POST.

To configure form data or json api set sms.provider.contentType=application/x-www-form-urlencoded or sms.provider.contentType=application/json respectively

To configure which data needs to be sent to the API, the below property must be configured:

• sms.config.map={'uname':'$username', 'pwd': '$password', 'sid':'$senderid', 'mobileno':'$mobileno', 'content':'$message', 'smsservicetype':'unicodemsg', 'myParam': '$extraParam' , 'messageType': '$mtype'}

• sms.category.map={'mtype': {'*': 'abc', 'OTP': 'def'}}

• sms.extra.config.map={'extraParam': 'abc'}

sms.extra.config.map is not used currently and is only kept for custom implementation which requires data that doesn't need to be directly passed to the REST API call

sms.config.map is a map of parameters and their values

Special variables that are mapped

• $username maps to sms.provider.username

• $password maps to sms.provider.password

• $senderid maps to sms.senderid

• $mobileno maps to mobileNumber from Kafka fetched message

• $message maps to the message from the Kafka fetched message

• $<name> any variable that is not from the above list, is first checked in sms.category.map and then in application.properties and then in the environment variable with full upper case and _ replacing -, space or .

So if you use sms.config.map={'u':'$username', 'p':'password'}. Then the API call will be passed <url>?u=<$username>&p=password

Message Success or Failure

Message success delivery can be controlled using below properties

• sms.verify.response (default: false)

• sms.print.response (default: false)

• sms.verify.responseContains

• sms.success.codes (default: 200,201,202)

• sms.error.codes

If you want to verify some text in the API call response set sms.verify.response=true and sms.verify.responseContains to the text that should be contained in the response.

Blacklisting or Whitelisting numbers

It is possible to whitelist or blacklist phone numbers to which the messages should be sent. This can be controlled using the below properties:

• sms.blacklist.numbers

• sms.whitelist.numbers

Both of them can be given a , separated list of numbers or number patterns. To use patterns use X for any digit match and * for any number of digits match.

sms.blacklist.numbers=5*,9999999999,88888888XX will blacklist any phone number starting with 5, or the exact number 9999999999 and all numbers starting from 8888888800 to 8888888899

Prefixing

Few 3rd parties require a prefix of 0 or 91 or +91 with the mobile number. In such a case you can use sms.mobile.prefix to automatically add the prefix to the mobile number coming in the message queue.

Error Handling

There are different topics to which the service will send messages. Below is a list of the same:

In an event of a failure to send SMS, if kafka.topics.backup.sms is specified, then the message will be pushed on to that topic.

Any SMS which expires due to Kafka lags, or some other internal issues, they will be passed to the topic configured in kafka.topics.expiry.sms

If a backup topic is not configured, then in an event of an error the same is delivered to kafka.topics.error.sms

Following are the properties in the application.properties file in notification SMS service which are configurable.

Deployment Details

1. Add the variables present in the above table in a particular environment file

2. Deploy the latest version of egov-notification-sms service.

Integration

Integration Scope

Notification SMS service consumes SMS from the Kafka notification topic and processes them to send it to a third party service. Modules like PT, TL, PGR etc make use of this service to send messages through the Kafka Queue.

Integration Benefits

• Provide an interface to send notification SMS on the user mobile number

• Support SMS in various languages

Steps to Integration

To integrate, create the SMS request body given in the example below. Provide the correct mobile number and message in the request body and send it to the kafka topic:- egov.core.notification.sms

The notification-sms service reads from the queue and sends the sms to the mentioned phone number using one of the SMS providers configured.

Reference Docs

Doc Links

Overview

User-OTP service handles the OTP for user registration, user login and password reset for a particular user.

Pre-requisites

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

• Java 8

• egov-user service is running

• egov-localization service is running

• egov-otp service is running

Key Functionalities

The user-otp service sends the OTP to the user on login requests, on password change requests and during new user registration.

Deployment Details

1. Deploy the latest version of user-otp.

2. Make sure egov-otp is running.

3. Add Role-Action mapping for APIs.

Integration

Integration Scope

User-OTP service handles the OTP for user registration, user log in and password reset for a particular user.

Integration Benefits

• Can perform user registration, login, password reset.

• In the future, if we want to expose the application to citizens then it can be done easily.

Steps to Integration

1. To integrate, a host of user-otp modules should be overwritten in the helm chart.

2. /user-otp/v1/_send should be added as the endpoint for sending OTP to the user via sms or email

Reference Docs

Doc Links

API Details

BasePath /user-otp/v1/[API endpoint]

Method

a) POST /_send

This method sends the OTP to the user via SMS or email based on the below parameters:

Producers

• Following are the Producer topic.

  • egov.core.notification.sms.otp :- This topic is used to send OTP to the user mobile number.

  • org.egov.core.notification.email :- This topic is used to send OTP to the user email id.

Overview

Roles define the permissions of a user to perform a group of tasks. For example for a Trade License application initiate, forward, approve or payment are tasks that require permission. Users assigned to the citizen or counter-employee role can perform initiation and payment. TL Document Verifier can forward the application and the only user assigned with the role named TLApprover can approve the application.

Pre-requisites

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

• Knowledge of DIGIT applications is required.

• Users should be aware of transactional steps in the DIGIT application.

• 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

• Roles provide users with permission to perform certain tasks and restrict too based on the requirement. For example, only users with Role TLApprover can approve the Trade License-initiated application.

• While creating an employee in the system from HRMS Admin, the roles can be assigned to the employees based on the requirement. The roles added in MDMS will show in the “roles drop down” in the employee create screen.

• In the DIGIT system workflow for a module is implemented based on roles. For example, the roles for the Trade License module in a Trade License application workflow are - CounterEmployee/Citizen>TLDocVerifier>TLApprover>CounterEmployee/Citizen. The table below lists the Trade License application workflows based on the defined roles.

Deployment Details

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

Configuration Details

Roles are added in roles.json In MDMS, file roles.json, under ACCESSCONTROL-ROLES folder roles are added. Sample roles:

{
  "tenantId": "uk",
  "moduleName": "ACCESSCONTROL-ROLES",
  "roles": [
    {
      "code": "CITIZEN",
      "name": "Citizen",
      "description": "Citizen who can raise complaint"
    },
    {
      "code": "TL_CEMP",
      "name": "TL Counter Employee",
      "description": "Who has a access to Trade License Services"
    },
    {
      "code": "TL_DOC_VERIFIER",
      "name": "Trade License Document verifier",
      "description": "Trade License Document verifier"
    },
    {
      "code": "TL_APPROVER",
      "name": "TL Approver",
      "description": "Who has a access to Trade License Workflow"
    }
  ]
}

A role is added as an array element under the array named “roles”.

Each role is defined with three key-value pairs. keys are “code”, ”name” and “description”.

Localization needs to be pushed for all the roles added in roles.json

Sample Localization for roles In English:

 {
  "code": "ACCESSCONTROL_ROLES_ROLES_TL_CEMP",  // <"ACCESSCONTROL_ROLES_ROLES_" should be appended before role code>
  "message": "TL Counter Employee",             // English Value to be shown in UI
  "module": "rainmaker-common",                 // module is added with rainmaker-common
  "locale": "en_IN"                             // English language key
}

In Hindi:

{
  "code": "ACCESSCONTROL_ROLES_ROLES_TL_CEMP",  // <"ACCESSCONTROL_ROLES_ROLES_" should be appended before role code>
  "message": "टीएल काउंटर कर्मचारी",               // Hindi value to be shown in UI
  "module": "rainmaker-common",                // module is added with rainmaker-common
  "locale": "hi_IN"                            // Hindi language key
}

Reference Docs

Doc Links

Our telemetry service is built upon sunbird telemetry sdk. mSeva’s frontend React app pushes the telemetry JS file along with every response that it sends. Now, whenever a user interacts with any of the mSeva pages in any way, for e.g. entering values in a text box or when the window is loaded etc., the event gets triggered and is recorded.

Telemetry API collection can be found here - https://www.getpostman.com/collections/65d183baffd3972cb925

The telemetry payload consists of an events array. In DIGIT, only 3 event types are used namely START, SUMMARY and END event types. START signifies that events have now started getting collected for a particular page. SUMMARY signifies a collection of all the data that is required to get collected for that particular page for e.g. time spent by the user on that page, times at which the user came into the page, left the page for another tab etc. are all recorded as part of the SUMMARY event. END event signifies the end of collecting events. All these events keep getting collected and are bundled and sent when either the URL changes or the END event occurs.

Now, this event data is captured and pushed onto a Kafka topic and goes into the processing pipeline where we make a topic to topic transfer of the data. So, the format for events payload is checked, then it is pushed to another topic for de-duplicating. Similarly, the messages are unbundled and enriched via topic to topic transfer i.e. pick from one topic and push to another. In this case, there are two sinks, namely the Amazon S3 bucket and ES bucket. To perform this topic to topic transfer of data across the various components of the processing pipeline, Kafka streams (KStreams) are used which are nothing but a consumer and producer coupled together. To push data to S3 bucket, secor service is being used which is a service developed by Pinterest to pick up JSON data and to push it onto configured S3 buckets. Secor does not always create a new JSON file for any new data that it gets. There are two triggers for it, namely, reaching a particular threshold size or reaching a particular time threshold. To push data to the ES sink, Kafka connect is being used. Now, instead of making single API calls every time a message is received, the messages are again combined and persisted onto the ES index via bulk insert.

Overview

Roles define the permissions of a user to perform a group of tasks. The tasks are created as API calls to do certain actions when a request for those calls is sent by the system. Access permission is grated by mapping roles with API. User assigned with the roles to provide access for the API

Pre-requisites

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

• Knowledge of DIGIT applications is required.

• User should be aware of transactional steps in the DIGIT application.

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

• Knowledge of MDMS is required.

• Knowledge on how to create a new API.

• 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

  • 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 POST body only

• For further more information about how new API is developed could be referred in this link

Key Functionalities

• Adding New APIs(actions) and Mapping Roles with that APIs provides permission to perform certain task can be restricted based on the requirement.

Deployment Details

• After mapping Roles with APIs, the MDMS service needs to be restarted to read the newly added data.

Configuration Details

APIs are added in actions-test.json and called as action. In MDMS, file actions-test.json, under ACCESSCONTROL-ACTIONS-TEST folder APIs are added.

API Sample -

APIs are added as action array element with the request url and other required details for the array "actions-test"

Each action is defined as a key-value pair:

Mapping of Roles and APIs/action is added in roleactions.json, under the folder ACCESSCONTROL-ROLEACTIONS. Sample mapping:

Role and API/action mapping is added as an array element under array roleactions. Each mapping is defined with key-value pairs. keys are rolecode, actionid, actioncode and tenantId.

Reference Docs

Doc Links

Overview

• Configuration of the notification messages for a business service based on the channel for the same event.

Key Functionalities

• For a specific action of the user, they get an SMS and email as an acknowledgement.

• Users can get SMS, Event, and email-based on different channels.

• The application allows one to either send different messages across all channels based on their actions.

Enhancement Details

• To have this functionality for different business services, a channel names file was created and added to the MDMS data.

• It contains information about the combination of different actions and channels for a particular business service. Example -

• The Different channels are

  • SMS: ID (Mobile Number)

  • Event

  • Email: ID (Email ID)

• This feature enabled the functionality which would first check for the channels present in the file and send the notification accordingly.

• For SMS event, it would send the SMS notification and log “Sending SMS Notification”, for Event it would log, “Event Notification Sent”, and for Email, it would log, “Email Notification Sent”.

Steps for Enabling/Disabling Channels

To add/delete any particular channel for a business service -

• Restart egov-mdms-service to apply the changes.

• Configure your business service with the steps mentioned below to configure the business service.

Business Service Configuration

• For any record that comes into the topic first, the service should fetch all the required data like user name, property id, mobile number, tenant id, etc from the record that is fetched from the topic.

• Fetch the message content from localization and the service replaces the placeholders with the actual data.

• Place the record in whichever channel’s topic that the SMS/email service is listening to.

Overview

Indexer uses a config file per module to store all the configurations pertaining to that module. Indexer reads multiple such files at start-up to support indexing for all the configured modules. In config we define source and, destination elastic search index name, custom mappings for data transformation and mappings for data enrichment.

Sample Configuration

Below is the sample configuration for indexing TL application creation data into elastic search.

Variable List

The table below lists the key configuration variables.