DIGIT consists of several reusable building blocks on top of which one can develop a citizen service delivery solution. Read on to learn more about the microservice building blocks architecture.

Microservice - Building Blocks

The DIGIT platform design is based on the following key principles:

1. Single Source of Truth - Shared data registries ensure data is updated and reused without duplicating transactional data. DIGIT registries offer standard API access that multiple service providers can leverage.

2. Security and Privacy - DIGIT is designed to be secure by default featuring configurable role-based access. Personally Identifiable Information (PII) is encrypted and inaccessible by analytical systems.

3. Scalability - DIGIT is built for scale. Its event-driven asynchronous microservices architecture enables DIGIT to handle millions of service requests with ease.

4. Flexible - DIGIT adopts a multi-user approach. Users (agencies or service providers) have the provision to configure their master data and workflows. They also have the flexibility to develop and implement custom service versions.

5. Modular - DIGIT components are designed as modular microservices with interoperable APIs. Each service can be scaled, updated and deployed autonomously independent of others.

6. Interoperable - API first design and use of Open Standards wherever possible ensures DIGIT is interoperable with other systems. Data can be exchanged seamlessly as and when required.

7. Ease of Access - DIGIT enables easy access to all stakeholders including citizens, employees, administrators, developers or system administrators. Data available through API can be routed to specific applications on the web, mobile, or chat.

8. Open - DIGIT is open source and uses open source technologies and standards to ensure that data and core services are never vendor locked-in. MIT License gives rights to any agency or its partners to copy the source code and deploy it for their needs.

DIGIT core services are developed using the following technologies -

Click the links below to learn more about the open-source tools and API gateways used in DIGIT.

Deployment Diagram

01 - Accelerated Reforms

Governments have used DIGIT to transform the way they deliver public services.

By establishing a digital public infrastructure (DPI), multiple states have built capacity, removed administrative burdens and improved governance for faster, better, and cheaper delivery of public services.

Governments face multiple challenges in transformation initiatives. Capacity issues, emergent needs and behaviours, variance in context and requirements at a different scale.

DIGIT was designed ground-up to address such challenges and has evolved over multiple years of implementations to solve for accelerated reforms.

02 - Trustworthy Data For Effective Decision Making

Timely and trustworthy data for effective decision-making at different administrative levels and to fix accountability. DIGIT comes ready with data dashboards to enable decision-making at all levels of government, right from administrators to frontline workers.

DIGIT makes possible:

• interoperability

• Easy sharing of data

• Single source of truth

This ensures that products built on DIGIT enhance visibility, increase trust and reduce the cost of coordination across multiple departments and programs.

03 - Improved Productivity & Faster Adoption

Reduce overheads for technology teams and learning curve for the final product users.

Single login for multiple applications and a standardised user interface make adoption quicker and easier. Role-based access takes away the overheads of multiple environments for different systems and multiple user accounts for each system.

For employees, it removes having to do tedious, repetitive tasks by automating processes, improving productivity, and allowing them to focus on more meaningful aspects of their jobs.

04 - Sustainable Impact At Scale & Speed

Scalability is at the core of the DIGIT platform. It has been deployed as a digital public infrastructure serving large-scale sub-national and national populations.

What makes it possible? A technologically robust platform with open and freely available specifications and standardised APIs that have proven its performance at massive deployments at the population scale.

DIGIT's source code is open source, data is stored in shared registries and data stores are owned by the government, mitigating the risks associated with vendor lock-ins, and allowing digital transformation initiatives to move ahead with speed at scale.

05 - Enhanced Citizen Access To Public Services

Products built on DIGIT can be accessed by multiple channels. So that, services can be delivered to citizens via mobile, web, WhatsApp, chatbots, through intermediaries or over the counter in physical offices. All are seamlessly connected.

It comes ready with a well-defined design system with a standardised user interface that has been created considering the realities of population-scale digital products. The user interface is straightforward, minimal and follows a guided approach for citizens using these digital products.

06 - Quick Development, Easy Deployment

All products on DIGIT are designed to be configured, customised, and extended to suit the needs of the local context. These changes can be made at different levels of government.

A federated architecture supports the different realities of each unit of governance.

A set of reusable building blocks can be leveraged by market players to build products and services rapidly. Well-defined specifications, documentation, guides, and training materials make deployment quick and easy for teams. Thus, making it possible to build products for different programs and services, urgent needs and take them to the ground as fast as possible.

07 - Strong Network Of Trusted System Integrators

The DIGIT team works actively with partners and has created a robust ecosystem of application developers and system integrators that are trained and certified in DIGIT.

Open training sessions on design, development, deployment and implementation are held regularly. In addition to that, DIGIT provides certifications to trained personnel.

08 - Continued Platform Support

For governments using DIGIT as their technology platform, the DIGIT team offers:

• Advisory support in vendor selection

• Product design review, architecture design review

• Enablement of system integrators selected by the government

• Open training sessions | Certifications | Implementation guidance | Platform performance review

DIGIT promises long-term support of the platform for all its core components and also underwrites the performance of the core platform.

9 - Designed For Global Challenges, Recognised Globally

DIGIT has the capabilities needed to rapidly develop digital applications to address global development challenges. From its origin in solving for urban governance, the platform has rapidly evolved to address challenges in areas of sanitation, public health welfare, public finance, rural governance and legal case management among others.

DIGIT is certified as a Digital Public Good (DPG) by the Digital Public Goods Alliance (DPGA). The DIGIT team sits on the technical advisory committee of the Govstack that works to identify and support the advancement of digital public goods with relevance to the whole of the government transformation approach.

Digital Infrastructure for Governance and Inclusive Transformation (DIGIT) is an open-source, scalable, interoperable platform for responsive public service delivery and good governance. It enables government agencies to digitize public service delivery - providing unified interfaces for citizens, front-line employees and administrators to exchange information with each other in a seamless and trusted manner. DIGIT is an open-source platform built for scale. DIGIT is multi-tenant and can enable the digital transformation of multiple government agencies at speed and scale using a common shared infrastructure.

Motivation

Government agencies deliver and manage a host of public services. Each of them are increasingly leveraging information technology to automate and manage delivery of these services. Inadvertently, they endup building systems have common functionality and also end up duplicating similar data sets that are all out of synch. This leads to several challenges in the long term.

1. Lack of Single Source of Truth - Multiple systems with similar datasets leads to multiple sources of truth.

2. Siloed - These systems often don't talk to each other hence citizens have to run pillar to post to get same data in multiple systems updated to receive services and benefits. Administrators also struggle to get access to data to identify areas of improvement. Employees have to learn to work with multiple systems to deliver services.

3. Scalability - Many of these systems are built for internal users and cannot be opened up for direct access to citizens. This makes it difficult for citizens to access their own data.

4. Vendor Lock-In - Often these systems have been developed by external vendors and government agencies do not have capacity to take these over leading to vendor lock-in.

Multiple other challenges like security concerns and limited technical capabilities hinder the government's ability to effectively utilise technology for large-scale public service delivery.

DIGIT platform is developed using sound architectural principles to enable multiple government agencies to deliver public services is an inclusive and accessible to all citizens and business in at scale and speed. DIGIT provide a shared infrastructure consist of shared data registries and common services like authentication, authorisation, workflow, notification, payments etc. that enable agencies to develop and deliver services in a secure, scalable and cost effective manner.

Typical Public Service Design

A typical public service delivery starts with a citizen applying for a service or a service connection. The diagram below abstracts the typical information exchange flow required to enable the delivery of a service.

A digital system offers the following capabilities to improve citizen experience:

1. Register/Login - Citizens can register, sign in, or authenticate themselves. Single sign-on capability streamlines access to digital services.

2. Apply/Upload - Citizens can request services by completing an application form and uploading necessary documents. Services should be accessible through multiple channels and in various languages.

3. Pay/Bill - Citizens can make payments for services and download bills. Multiple payment options, including digital and cash, should be available..

4. Inform/Track - Citizens can track service progress or receive updates via SMS, email, or app notifications.

5. Support/Feedback - Citizens can raise support requests or provide feedback on service closure. The system should allow configuring surveys and feedback forms, with the ability to analyse responses for corrective action.

The following capabilities support the employee and management experience:

1. Assign - Employees or vendors can assign service applications or trigger workflows tailored to different user/agency local requirements.

2. Search/View - Employees or vendors can search for and view applications based on multiple attributes.

3. Update/Comment - Employees can update and comment on service applications, facilitating structured and unstructured data exchange between parties.

4. Deliver/Verify- Employees or vendors can deliver services, such as setting up a new connection, or verify and certify information provided by citizens. Offline-capable apps are crucial in low mobile coverage areas, with data synchronization capabilities to handle load spikes.

5. Monitor/Improve - Administrators can monitor service performance and identify areas for improvement. All transactions should generate data events in an analytical database for comprehensive performance monitoring.

6. Plan/Budget - Administrators and policymakers can plan and budget for service improvement, linking expenditures to outcomes.

DIGIT Service Design

All services are built on DIGIT emits micro-level transactional data into an analytical database. This is key for real-time monitoring and auditing of the operations. It facilitates planning, budgeting and policy decision-making.

DIGIT is proven and well-supported serving over 1000 cities. Ecosystem partners including System Integrators are using DIGIT to build and deliver services. DIGIT Core LTS 2.9 version comes with long-term support. This implies that any technical issues like security or performance reported on any of these services in the DIGIT Core 2.9 LTS version will be fixed by the DIGIT team.

Contact Us

Platform Tools

Dev Stack Tools

DevOps Stack Tools

DIGIT offers several API collections that help integrate services on the platform. The table below enlists the DIGIT Core Service APIs and the link to related service configuration docs.

24. • MDMS-client

    • Services-common

Overview

DIGIT is an API-based platform where each API denotes a DIGIT resource. The primary job of Access Control Service (ACS) is to authorise end-users based on their roles and provide access to the DIGIT platform resources. Access control functionality is essentially based on the following points:

Actions: Actions are events performed by a user. This can be an API end-point or front-end event. This is the MDMS master.

Roles: Roles are assigned to users. A single user can hold multiple roles. Roles are defined in MDMS masters.

Role-Action: Role actions are mapped between Actions and Roles. Based on roles, the action mapping access control service identifies applicable actions for the role.

Pre-requisites

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

• Java 17

Key Functionalities

• Serve the applicable actions for a user based on user roles.

• On each action performed by a user, access control looks at the user's roles and validates actions that map with the role.

• Support tenant-level role action - For instance, an employee from Amritsar can have the role of APPROVER for other ULBs like Jalandhar and hence will be authorised to act as APPROVER in Jalandhar.

Deployment Details

Configuration Details

Define the roles:

Add the actions (URL)

Add the role action mapping

Integration Details

Integration Scope

Any service that requires authorisation can leverage the functionalities provided by the access control service.

Integration Benefits

To add a new service to the platform, simply update its role action mapping in the master data. The Access Control Service will handle authorisation each time the microservice API is called.

Integration Steps

2. The service needs to call /actions/_authorize API of Access Control Service to check for authorisation of any request.

Interaction Diagram

Reference Docs

Doc Links

API List

Overview

The objective of the audit service is listed below -

1. To provide a one-stop framework for signing data i.e. creating an immutable data entry to track activities of an entity. Whenever an entity is created/updated/deleted the operation is captured in the data logs and is digitally signed to protect it from tampering.

Pre-requisites

1. Prior knowledge of Java/J2EE

2. Prior knowledge of SpringBoot

3. Prior knowledge of PostgreSQL

4. Prior knowledge of REST APIs and related concepts like path parameters, headers, JSON etc.

Setup & Key Functionalities

The audit service will be parsing all the persister configs so that it can process data received by the persister and create audit logs out of it.

Setup

Step 1: Add the following metrics to the existing persister configs -

isAuditEnabled: true
module: PGR
objecIdJsonPath: $.id
tenantIdJsonPath: $.tenantId
transactionCodeJsonPath: $.transactionCode
auditAttributeBasePath: $.service

Step 2: If a custom implementation of ConfigurableSignAndVerify interface is present, provide the signing algorithm implementation name as a part of audit.log.signing.algorithm property. For example, if the signing algorithm is HMAC, the property will be set as follows -

audit.log.signing.algorithm=HMAC

Step 3: Set egov.persist.yml.repo.path this property to the location of persister configs.

Step 4: Run the audit-service application along with the persister service.

Definitions

1. Config file - A YAML (xyz.yml) file which contains persister configuration for running audit service.

2. API - A REST endpoint to post audit logs data.

Functionalities

1. When audit-service create API is hit, it will validate request size, keyValueMap and operationType.

2. Upon successful validation, it will choose the configured signer and sign entity data.

3. Once audit logs are signed and ready, it will send it to audit-create topic.

4. Persister will listen on this topic and persist the audit logs.

Deployment Details

1. Add the required keys for enabling audit service in persister configs.

2. Deploy the latest version of the Audit service and Persister service.

3. Add Role-Action mapping for APIs.

Integration Details

Integration Scope

The audit service is used to push signed data for tracking each and every create/modify/delete operation done on database entities.

Integration Benefits

• Can be used to have tamper-proof audit logs for all database transactions.

• Replaying events in chronological order will lead to the current state of the entity in the database.

Integration Steps

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

2. audit-service/log/v1/_create should be added as the create endpoint for the config added.

3. audit-service/log/v1/_search should be added as the search endpoint for the config added.

API Details

1. URI: The format of the API to be used to create audit logs using the audit service is as follows: audit-service/log/v1/_create

Body: The body consists of 2 parts: RequestInfo and AuditLogs.

Sample Request Body -

{
    "RequestInfo": {
        "apiId": "asset-services",
        "ver": null,
        "ts": null,
        "action": null,
        "did": null,
        "key": null,
        "msgId": "search with from and to values",
        "authToken": "83a1cfb3-6fde-4406-9ee1-622b3ecc7dab"
    },
    "AuditLogs": [
        {
            "userUUID": "11b0e02b-0145-4de2-bc42-c97b96264807",
            "module": "PGR",
            "tenantId": "pb.amritsar",
            "transactionCode": "PGR.CREATE",
            "changeDate": 1657104693726,
            "entityName": "eg_pgr_service",
            "objectId": "c8c901da-61e9-4cd5-89f7-7560997922b7",
            "keyValueMap": {
                "id": "89651651-841a-4b8c-a503-f5d4bb10f4d5",
                "tenantId": "pb.amritsar",
                "assemblyConstituency": "AMC",
                "applicationNumber": "c8c901da-61e9-4cd5-89f7-7560997922b7",
                "applicantId": null,
                "dateSinceResidence": 1590825279,
                "createdBy": "11b0e02b-0145-4de2-bc42-c97b96264807",
                "lastModifiedBy": "11b0e02b-0145-4de2-bc42-c97b96264807",
                "createdTime": 1657104693312,
                "lastModifiedTime": 1657104693312
            },
            "operationType": "CREATE"
        },
        {
            "userUUID": "11b0e02b-0145-4de2-bc42-c97b96264807",
            "module": "PGR",
            "tenantId": "pb.amritsar",
            "transactionCode": "PGR.CREATE",
            "changeDate": 1657104693732,
            "entityName": "eg_pgr_address",
            "objectId": "c8c901da-61e9-4cd5-89f7-7560997922b7",
            "keyValueMap": {
                "id": "84cbe5d1-6ee8-4379-a0c4-0e2a5c94689d",
                "tenantId": "pb.amritsar",
                "doorNo": "1010",
                "latitude": null,
                "longitude": null,
                "buildingName": "Avigna Residence",
                "addressId": null,
                "addressNumber": "34 GA",
                "type": "RESIDENTIAL",
                "addressLine1": "KP Layout",
                "addressLine2": "",
                "landmark": "Petrol pump",
                "street": "12th Main",
                "city": "Amritsar",
                "locality": "New Amritsar Locality",
                "pincode": "143501",
                "detail": "",
                "registrationId": "89651651-841a-4b8c-a503-f5d4bb10f4d5"
            },
            "operationType": "CREATE"
        }
    ]
}

2. URI: The format of the API to be used to search audit logs using audit-service is as follows: audit-service/log/v1/_search

Body: The body consists RequestInfo and search criteria is passed as query params.

Sample curl for search -

curl --location --request POST 'https://dev.digit.org/audit-service/log/v1/_search?offset=0&limit=10&tenantId=pb.amritsar&objectId=c8c901da-61e9-4cd5-89f7-7560997922b7' \
--header 'Content-Type: application/json' \
--data-raw '{
    "RequestInfo": {
        "apiId": "asset-services",
        "ver": null,
        "ts": null,
        "action": null,
        "did": null,
        "key": null,
        "msgId": "search with from and to values",
        "authToken": "83a1cfb3-6fde-4406-9ee1-622b3ecc7dab"
    }
}'

Reference Documents

Overview

The signed audit service provides a one-stop framework for signing data i.e. creating an immutable data entry to track activities of an entity. Whenever an entity is created/updated/deleted the operation is captured in the data logs and is digitally signed to protect it from tampering.

Observations and Results

1. Infra configuration -

• Number of concurrent users - 15000

• Duration of bombarding service with requests ~ 17 minutes

• Number of signed audit pod(s) - 1

Overview

Boundary service provides APIs to create Boundary entities, define their hierarchies, and establish relationships within those hierarchies. You can search for boundary entities, hierarchy definitions, and boundary relationships. However, you can only update boundary entities and relationships.

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 Git.

5. Advanced knowledge of operating JSON data would be an added advantage to understanding the service.

Key Functionalities

1. Create Boundary entity: It introduces functionality to define your boundary entity with all validations and properties supported by GeoJson. Currently, only the geometry type of Polygon and Point is supported by it.

2. Search Boundary entity: It has APIs to search boundaries based on the tenantid & codes, both being mandatory.

3. Update Boundary entity: This allows updating the geometry details of a boundary entity.

4. Create Boundary Hierarchy-definition: It allows defining boundary hierarchy definitions against a particular tenantId and hierarchyType which then can be referenced while creating boundary relationships.

5. Search Boundary Hierarchy-definition: boundary-service supports searching for hierarchy definitions based on tenantId and HierarchyType where tenantId is mandatory. In case the hierarchyType is not provided, it returns all hierarchy definitions for the given tenantId.

6. Create Boundary Relationship: It supports defining relationships between existing boundary entities according to the established hierarchy. It requires tenantId, code, hierarchyType, boundaryType, and parent fields. Where tenantId and code uniquely combine to determine a boundary entity, tenantId and hierarchType combine to define the hierarchy used in establishing the relationship between the boundary entity and its parent. It verifies if the parent relationship is already established before creating a new one. It also checks if the specified boundaryType is a direct descendant of the parent boundaryType according to the hierarchy definition.

7. Search Boundary Relationship: This functionality supports searching the boundary relationships based on the given params -

   1. tenantId

   2. hierarchyType

   3. boundaryType

   4. codes

   5. includeChildren

   6. includeParents

where tenantId and hierarchyType are mandatory and the rest are optional.

1. Update Boundary Relationship: This allows updating the parent boundary relationship within the same level as per the hierarchy.

API Details

1. /boundary/_create - Takes RequestInfo and Boundary in the request body. boundary has all attributes which define the boundary.

2. /boundary/_search - Takes RequestInfo in the request body and search criteria fields (refer to the functionality above for exact fields ) as params and return the boundary based on the provided search criteria.

3. /boundary/_update - Takes RequestInfo and Boundary in the request body where the boundary has all the info that needs to be updated and returns the updated boundary.

4. /boundary-hierarchy-definition/_create - Takes RequestInfo and boundary hierarchy definition in the request body where BoundaryHierarchy object has all the information for the hierarchy definition being created.

5. /boundary-hierarchy-definition/_search - Takes RequestInfo and BoundaryTypeHierarchySearchCriteria in the request body to return boundary hierarchy definition based on the provided search criteria.

6. /boundary-relationships/_create - This API takes RequestInfo and BoundaryRelationship in the request body where BoundaryRelationship has all the info required to define a relationship between two boundaries.

7. /boundary-relationships/_search - This API takes RequestInfo in the request body and search criteria fields (refer to functionality for the exact fields) are passed as params to return master data based on the provided search criteria and return the response.

8. /boundary-relationships/_update - This API takes RequestInfo and BoundaryRelationship in the request body to update the fields given in the BoundaryRelationship and returns the updated data.

Postman Collection for Boundary Service APIs:

Overview

Rate limiting in gateways is a crucial configuration to manage traffic and ensure service availability. By implementing a rate limiter, we can control the number of requests a client can make to the server within a specified time frame. This protects the underlying services from being overwhelmed by excessive traffic, whether malicious or accidental.

The configuration typically involves -

1. Replenish Rate: The rate at which tokens are added to the bucket. For example, if the replenish rate is 2 tokens per second, two tokens are added to the bucket every second.

2. Burst Capacity: The maximum number of tokens that the bucket can hold. This allows for short bursts of traffic.

3. KeyResolver: A KeyResolver is an interface used to determine a key for rate-limiting purposes.

Configuration Use Cases

Example 1: Basic Rate Limiting

Let's say we have a rate limiter configured with:

• replenishRate: 2 tokens per second

• burstCapacity: 5 tokens

This means:

• 2 tokens are added to the bucket every second.

• The bucket can hold a maximum of 5 tokens.

Scenario: A user makes requests at different intervals.

1. Initial State: The bucket has 5 tokens (full capacity).

2. First Request: The user makes a request and consumes 1 token. 4 tokens remain.

3. Second Request: The user makes another request and consumes 1 more token. 3 tokens remain.

4. Third Request: The user waits 1 second (2 tokens added) and then makes a request. The bucket has 4 tokens (3 remaining + 2 added - 1 consumed).

Example 2: Handling Burst Traffic

Let's consider a scenario where a user makes multiple requests in quick succession.

Configuration:

• replenishRate: 1 token per second

• burstCapacity: 3 tokens

Scenario: A user makes 4 requests in rapid succession.

1. Initial State: The bucket has 3 tokens (full capacity).

2. First Request: Consumes 1 token. 2 tokens remain.

3. Second Request: Consumes 1 token. 1 token remains.

4. Third Request: Consumes 1 token. 0 tokens remain.

5. Fourth Request: There are no tokens left, so the request is denied. The user must wait for more tokens to be added.

After 1 second, 1 token is added to the bucket. The user can make another request.

Example 3: Applying Rate Limiting In Spring Cloud Gateway

Here’s a practical example using Spring Cloud Gateway with Redis Rate Limiting.

Configuration: In Routes.properties you can set rate limiting as

Explanation:

• Replenish Rate: 5 tokens per second.

• Burst Capacity: 10 tokens.

Behavior:

• A user can make up to 10 requests instantly (burst capacity).

• After consuming the burst capacity, the user can make 5 requests per second (replenish rate).

Example 4: Real-World Use Case

API Service Rate Limiting

An API service wants to ensure clients do not overwhelm the server with too many requests. They set up rate limits as follows:

• Replenish Rate: 100 tokens per minute.

• Burst Capacity: 200 tokens.

Scenario:

• A client can make 200 requests instantly.

• After the burst capacity is exhausted, the client can make 100 requests per minute.

• If any client tries to make more requests than allowed, they receive a response indicating they are being rate-limited.

Rate Limiting - Benefits

1. Prevents Abuse: Limits the number of requests to prevent abuse or malicious attacks (e.g., DDoS attacks).

2. Fair Usage: Ensures fair usage among all users by preventing a single user from consuming all the resources.

3. Load Management: Helps manage server load and maintain performance by controlling the rate of incoming requests.

4. Improved User Experience: Prevents server overload, ensuring a smoother and more reliable experience for all users.

Conclusion

Rate limiting is crucial for traffic management, fair usage, and server resource protection. By setting parameters like replenishRate and burstCapacity, you can regulate request flow and manage traffic spikes efficiently. In Spring Cloud Gateway, the Redis Rate Limiter filter offers a robust solution for implementing rate limiting on your routes.

Overview

We are updating our core services to remove outdated dependencies and ensure long-term support for the DIGIT platform. The current API gateway uses Netflix Zuul, which has dependencies that will soon be obsolete. To address this, we are building a new gateway using Spring Cloud Gateway.

What is Spring Cloud Gateway and how is it different from Zuul?

Spring Cloud Gateway and Zuul both function as API gateways but differ in architecture and design. Spring Cloud Gateway is ideal for modern, reactive applications, while Zuul is better suited for traditional, blocking I/O environments. The choice between them depends on your specific needs.

Navigating the new Gateway codebase

The new Gateway codebase is well-organized, with each module containing similar files and names. This makes it easy to understand the tasks each part performs. Below is a snapshot of the current directory structure.

Config: It contains the configuration-related files for example Application Properties etc.

Constants: It contains the constants referenced frequently within the codebase. Add any constant string literal here and then access it via this file.

Filters: This folder is the heart of the API gateway since it contains all the PRE, POST, and ERROR filters. For those new to filters: Filters intercept incoming and outgoing requests, allowing developers to apply various functionalities such as authentication, authorisation, rate limiting, logging, and transformation to these requests and responses.

Model: contains the P.O.J.O required in the gateway.

Producer: contains code related to pushing data onto Kafka.

Rate limiters contain files for initialising the relevant bean for custom rate limiting.

Utils: contains the helper function which can be reused across the project.

The above paragraphs provide a basic overview of the gateway's functionality and project structure.

When a request is received, the gateway checks if it matches any predefined routes. If a match is found, the request goes through a series of filters, each performing specific validation or enrichment tasks. The exact order of these filters is discussed later.

The gateway also ensures that restricted routes have proper authentication and authorization. Some APIs can be whitelisted as open or mixed-mode endpoints, allowing them to bypass authentication or authorization.

Upon receiving a request, the gateway first looks for a matching route definition. If a match is found, it starts executing the pre-filters in the specified order.

Pre-Filter

1. RequestStartTimerFilter: Sets request start time

2. CorrelationIdFilter: Generate and set a correlationId in each request to help track it in the downstream service

3. AuthPreCheckFilter: Checks for if Authorisation has to be performed

4. PreHookFilter: Sends a pre-hook request

5. RbacPreFilter: Checks if Authentication has to be performed or not

6. AuthFilter: Authenticate the request

7. RbacFilter: Authorise the request

8. RequestEnrichmentFilter: Enrich the request with userInfo & correlationId

Error-Filter

This filter handles all the errors shown either during the request processing or from the downstream service.

Gateway Routes & Properties Configuration

There are two ways to configure Rate Limits in Gateway

1. Default Rate Limiting

2. Service Level Rate Limiting

Default Rate Limiting

Default rate limiting sets a standard limit on the number of requests that can be made to the gateway within a specified time frame. This limit applies to all services unless specific rate limits are configured at the service level.

Service Level Rate Limiting

Service level rate limiting allows you to set specific rate limits for individual services. This means each service can have its request limits, tailored to its unique needs and usage patterns, providing more granular control over traffic management.

Note: We currently provide two options for keyResolver and if none of them is specified the spring cloud will take a default go PrincipalNameKeyResolver which retrieves the Principal from the ServerWebExchange and calls Principal.getName().

1. ipKeyResolver : Resolves key based on ip address of the request

2. userKeyResolver : Resolves key based on use UUID of the request

To enable gateway routes, a service must activate the gateway flag in the Helm chart. Based on this flag, a Go script runs in the Init container, automatically generating the necessary properties for all services using the gateway.

NOTE: Restart the Gateway after making changes in service Values.YAML so that it can pick up the changes.

Overview

The objective of this service is to create a common point to manage all the email notifications being sent out of the platform. The notification email service consumes email requests from the Kafka notification topic and processes them to send them 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 user

• Support localised email.

Configuration Details

The egov-notification-mail is a consumer which listens to the egov.core.notification.email topic reads the message and generates email using SMTP Protocol. The services need the senders' email configured. On the other hand, if the senders' email is not configured, the services get the email id by internally calling egov-user service to fetch the 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 Details

Integration Scope

The email notification service is used to send out email notifications for all miscellaneous/ad-hoc services which citizens avail from ULBs.

Integration Benefits

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

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

Integration Steps

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

Reference Documents

Overview

This documents highlights the changes need to be done in a module to support the user privacy feature.

Pre-requisites

• Prior Knowledge of Java/J2EE.

• Prior Knowledge of Spring Boot.

• MDMS Service

• Encryption Service

• Prior Knowledge of React Js / Javascript

Backend service changes

Update the pom.xml file.

• Upgrade services-common library version.

<dependency>
    <groupId>org.egov.services</groupId>
    <artifactId>services-common</artifactId>
    <version>1.1.1-SNAPSHOT</version>
</dependency>

• Upgrade tracer library version.

<dependency>
    <groupId>org.egov.services</groupId>
    <artifactId>tracer</artifactId>
    <version>2.1.2-SNAPSHOT</version>
</dependency>

Demand generation changes:

At service level or calculator service level where demand generation process take place, there payer details value must be pass in plain form. And these user details must get through SYSTEM user.

Create a system user in the particular environment and make sure that system user has role INTERNAL_MICROSERVICE_ROLE. Use the curl mentioned below:

curl --location --request POST 'http://localhost:8081/user/users/_createnovalidate' \
--header 'Content-Type: application/json' \
--data-raw '{
    "RequestInfo": {
  "apiId": "Rainmaker",
  "authToken": "81a67bd9-3ff6-402c-ae59-d9209c9dfb3d",
  "userInfo": {
    "id": 29836,
    "uuid": "d8854322-a078-41f8-90b5-6f3a1aee9454",
    "userName": "qeroo",
    "name": "QARoo",
    "mobileNumber": "8339358368",
    "emailId": "",
    "locale": null,
    "type": "EMPLOYEE",
    "roles": [
      
      {
        "name": "Employee",
        "code": "EMPLOYEE",
        "tenantId": "pb.amritsar"
      },
      {
        "name": "Super User",
        "code": "SUPERUSER",
        "tenantId": "pb.amritsar"
      }
    ],
    "active": true,
    "tenantId": "pb.amritsar",
    "permanentCity": null
  },
  "msgId": "1653559822522|en_IN"
},
    "user": {
        "userName": "INTERNAL_MICROSERVICE_USER",
        "password": "eGov@123",
        "salutation": null,
        "name": "Internal Microservice User",
        "gender": null,
        "mobileNumber": "8888888880",
        "emailId": null,
        "altContactNumber": "",
        "pan": null,
        "aadhaarNumber": null,
        "permanentAddress": null,
        "permanentCity": null,
        "permanentPincode": null,
        "correspondenceCity": null,
        "correspondencePincode": null,
        "correspondenceAddress": null,
        "active": true,
        "dob": null,
        "pwdExpiryDate": null,
        "locale": "string",
        "type": "SYSTEM",
        "signature": null,
        "accountLocked": false,
        "fatherOrHusbandName": "null",
        "bloodGroup": null,
        "identificationMark": null,
        "photo": null,
        "otpReference": null,
        "tenantId": "pb",
        "roles": [
           {
                    "code": "INTERNAL_MICROSERVICE_ROLE",
                    "name": "Internal Microservice Role",
                    "tenantId": "pb"
            }
        ]
    }
}'

Mention the uuid of the system user in the environment file and in the application.properties file of service example:

Environment file:

egov-internal-microservice-user-uuid: b5b2ac70-d347-4339-98f0-5349ce25f99f

Application properties file:

egov.internal.microservice.user.uuid=b5b2ac70-d347-4339-98f0-5349ce25f99f

Create a method/ function which call the user search API to get the user details in plain form, in that call pass the userInfo of the user with INTERNAL_MICROSERVICE_ROLE

For reference follow the below code snippet

private User getPlainOwnerDetails(RequestInfo requestInfo, String uuid, String tenantId){
		User userInfoCopy = requestInfo.getUserInfo();
		StringBuilder uri = new StringBuilder();
		uri.append(configs.getUserHost()).append(configs.getUserSearchEndpoint()); // URL for user search call
		Map<String, Object> userSearchRequest = new HashMap<>();
		tenantId = tenantId.split("\\.")[0];

		//Creating role with INTERNAL_MICROSERVICE_ROLE
		Role role = Role.builder()
				.name("Internal Microservice Role").code("INTERNAL_MICROSERVICE_ROLE")
				.tenantId(tenantId).build();

        //Creating userinfo with uuid and role of internal micro service role
		User userInfo = User.builder()
				.uuid(configs.getEgovInternalMicroserviceUserUuid())
				.type("SYSTEM")
				.roles(Collections.singletonList(role)).id(0L).build();

		requestInfo.setUserInfo(userInfo);

        // Setting user search criteria
		userSearchRequest.put("RequestInfo", requestInfo);
		userSearchRequest.put("tenantId", tenantId);
		userSearchRequest.put("uuid",Collections.singletonList(uuid));
		User user = null;
		try {
			LinkedHashMap<String, Object> responseMap = (LinkedHashMap<String, Object>) serviceRequestRepository.fetchResult(uri, userSearchRequest);

			List<LinkedHashMap<String, Object>> users = (List<LinkedHashMap<String, Object>>) responseMap.get("user");
			String dobFormat = "yyyy-MM-dd";
			
			// parsing the user response and coverting object into User.class pojo
			notificationUtil.parseResponse(responseMap,dobFormat);
			user = 	mapper.convertValue(users.get(0), User.class);

		} catch (Exception e) {
			throw new CustomException("EG_USER_SEARCH_ERROR", "Service returned null while fetching user");
		}
		requestInfo.setUserInfo(userInfoCopy);
		return user;
	}

Report Configuration Changes:

For the report where PII data is present and decryption is required, such report definition must have UUID values from user table in the query result. And the Source column section of the report definition must have mention of the UUID column and for that entry, showColumn flag should be set as false.

 - name: uuid
    label: reports.{moduleName}.uuid
    type: string
    source: eg_user
    showColumn: false

And the base sql query in the report config should be written in such a way that in the query it must have the user uuid.

Example:

SELECT emp_data.id as id,
      emp_data.name as name,
      emp_data.uuid as uuid,
      desigmap_def.code as designation,
      deptmap_def.code as department,
      emp_data.employeestatus as status
    FROM emp_data ehe
    inner join eg_user eu ON ehe.uuid = eu.uuid

In the report config where PII data is present and decryption is required, add this new filed in the report config decryptionPathId. And in the Security Policy mdms file, must have the model configuration from the particular report. And the value of key model in Security Policy mdms file and decryptionPathId in a report must be same. \

Example:-

{
  "model": "EmployeeReport",
  "uniqueIdentifier": {
    "name": "uuid",
    "jsonPath": "uuid"
  },
  "attributes": [
    {
      "name": "name",
      "jsonPath": "name",
      "patternId": "002",
      "defaultVisibility": "PLAIN"
    }
  ],
  "roleBasedDecryptionPolicy": [
    {
      "roles": [
        "CEMP"
      ],
      "attributeAccessList": [
        {
          "attribute": "name",
          "firstLevelVisibility": "MASKED",
          "secondLevelVisibility": "PLAIN"
        }
      ]
    }
  ]
}

Searcher Configuration changes:

For the searcher result where PII data is present and decryption is required, such searcher definition must have UUID values from user table in the query result. The base sql query in the searcher config should be written in such a way that in the query it must have the user uuid.

I searcher result, where data are coming from user table and to get those value in decrypted form, then in searcher config these following filed decryptionPathIdmust be present. And the Security Policy mdms file, must have the model configuration from the particular searcher config. And the value of key model in Security Policy mdms file and decryptionPathId in searcher config must be same.\

Frontend Changes:

To Do

Overview

The enc-client library is a supplementary java library provided to support encryption-related functionalities so that every service does not need to pre-process the request before calling the encryption service.

Pre-requisites

• MDMS Service

• Encryption Service

• Kafka

Important Note

The MDMS configurations explained below are fetched by this library at boot time. So after you make changes in the MDMS repo and restart the MDMS service, you would also need to RESTART THE SERVICE which has imported the enc-client library. For example, the report service is using the enc-client library so after making configuration changes to Security Policy pertaining to any report, you will have to restart the report service.

Key Functionalities

• Encrypt a JSON Object - The encryptJson function of the library takes any Java Object as an input and returns an object which has encrypted values of the selected fields. The fields to be encrypted are selected based on an MDMS Configuration.

  • This function requires the following parameters:

    1. Java/JSON object - The oject whose fields will get encrypted.

    2. Model - It is used to identify the MDMS configuration to be used to select fields of the provided object.

    3. Tenant Id - The encryption key will be selected based on the passed tenantId.

• Encrypt a Value - The encryptValue function of the library can be used to encrypt single values. This method also required a tenantId parameter.

• Decrypt a JSON Object - The decryptJson function of the library takes any Java Object as an input and returns an object that has plain/masked or no values of the encrypted fields. The fields are identified based on the MDMS configuration. The returned value(plain/masked/null) of each of the attribute depends on the user’s role and if it is a PlainAccess request or a normal request. These configurations are part of the MDMS.

  • This function required following parameters:

    1. Java/JSON object - The object containing the encrypted values that are to be decrypted.

    2. Model - It is used to select a configuration from the list of all available MDMS configurations.

    3. Purpose - It is a string parameter that passes the reason of the decrypt request. It is used for Audit purposes.

    4. RequestInfo - The requestInfo parameter serves multiple purposes:

       1. User Role - A list of user roles are extracted from the requestInfo parameter.

       2. PlainAccess Request - If the request is an explicit plain access request, it is to be passed as a part of the requestInfo. It will contain the fields that user is requesting for decryption and the id of record.

  • While decrypting Java object, this method also audits the request.

Configurations

All the configurations related to enc-client library are stored in the MDMS. These master data are stored in DataSecurity module. It has two types of configurations:

1. Masking Patterns

2. Security Policy

Masking Patterns

{
    "patternId": "001",
    "pattern": ".(?=.{4})"
}

The masking patterns for different types of attributes(mobile number, name, etc.) are configurable in MDMS. It contains the following attributes:

1. patternId - It is the unique pattern identifier. This id is referred to in the SecurityPolicy MDMS.

2. pattern - This defines the actual pattern according to which the value will be masked.

Security Policy

The Security Policy master data contains the policy used to encrypt and decrypt JSON objects. Each of the Security Policy contains the following details:

1. model - This is the unique identifier of the policy.

2. uniqueIdentifier - The field defined here should uniquely identify records passed to the decryptJson function.

3. attributes - This defines a list of fields from the JSON object that needs to be secured.

4. roleBasedDecryptionPolicy - This defines attribute-level role-based policy. It will define visibility for each attribute.

Visibility

The visibility is an enum with the following options:

1. PLAIN - Show text in plain form.

2. MASKED - The returned text will contain masked data. The masking pattern will be applied as defined in the Masking Patterns master data.

3. NONE - The returned text will not contain any data. It would contain string like “Confidential Information”.

It defines what level of visibility should the decryptJson function return for each attribute.

Attribute

{
  "name": "mobileNumber",
  "jsonPath": "mobileNumber",
  "patternId": "001",
  "defaultVisibility": "MASKED"
}

The Attribute defines a list of attributes of the model that are to be secured. The attribute is defined by the following parameters:

1. name - This uniquely identifies the attribute out of the list of attributes for a given model.

2. jsonPath - It is the json path of the attribute from the root of the model. This jsonPath is NOT the same as Jayway JsonPath library. This uses / and * to define the json paths.

3. patternId - It refers to the pattern to be used for masking which is defined in the Masking Patterns master.

4. defaultVisibility - It is an enum configuring the default level of visibility of that attribute. If the visibility is not defined for a given role, then this defaultVisibility will apply.

Unique Identifier

This parameter is used to define the unique identifier of that model. It is used for the purpose of auditing the access logs. (This attribute’s jsonPath should be at the root level of the model.)

{
  "name": "uuid",
  "jsonPath": "uuid"
}

Role-Based Decryption Policy

{
  "roles": [ "PGR_LME", "GRO" ],
  "attributeAccessList": [
    {
      "attribute": "name",
      "firstLevelVisibility": "MASKED",
      "secondLevelVisibility": "PLAIN"
    },
    {
      "attribute": "mobileNumber",
      "firstLevelVisibility": "MASKED",
      "secondLevelVisibility": "PLAIN"
    }
  ]
}

It defines attribute-level access policies for a list of roles. It consists of the following parameters:

1. roles - It defines a list of role codes for which the policy will get applied. Please make sure not to duplicate role codes anywhere in the other policy. Otherwise, any one of the policies will get chosen for that role code.

2. attributeAccessList - It defines a list of attributes for which the visibility differs from the default for those roles.

   1. There are two levels of visibility:

      1. First level Visibility - It applies to normal search requests. The search response could have multiple records.

      2. Second level Visibility - It is applied only when a user explicitly requests for plain access of a single record with a list of fields required in plain.

Second level visibility can be requested by passing plainAccessRequest in the RequestInfo.

Plain Access Request

{
  "RequestInfo": {
    "plainAccessRequest": {
      "recordId": "d5ee3d45-13a1-4aa5-bd86-9b8dae34b900"
      "fields": [ "name", "mobileNumber" ]
    }
  }
}

Any user will be able to get plain access to the secured data(citizen’s PII) by requesting through the plainAccessRequest parameter. It takes the following parameters:

1. recordId - It is the unique identifier of the record that is requested for plain access.

2. fields - It defines a list of attributes that are requested for plain access.

Audit Service

Every decrypt request is audited. Based on the uniqueIdentifier defined as part of the Security Policy, it lists out the identifiers of the records that were decrypted as part of the request.

Each Audit Object contains the following attributes:

AuditObject {  
    private String id;      // Audit object's unique identifer

    private String userId;  // The user that has requested for decryption

    private Long timestamp; // The time at which the decryption was requested

    private String purpose; // The purpose of the decryption request

    private String model;   // The model that is requested to decrypt

    private List<String> entityIds; // A list of ids of the entity that were decrypted

    private PlainRequestAccess plainRequestAccess;  // The parameters that were passed as part of the decryption request

    private JsonNode additionalInfo;  // A space for storing any additional information
}

Overview

Encryption Service is used to secure sensitive data that is being stored in the database. The encryption services uses envelope encryption.

Pre-requisites

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

• Java 17.

• Kafka server is up and running.

Key Functionalities

Encryption Service offers following features :

1. Encrypt - The service will encrypt the data based on given input parameters and data to be encrypted. The encrypted data will be mandatorily of type string.

2. Decrypt - The decryption will happen solely based on the input data (any extra parameters are not required). The encrypted data will have identity of the key used at the time of encryption, the same key will be used for decryption.

3. Sign - Encryption Service can hash and sign the data which can be used as unique identifier of the data. This can also be used for searching gicen value from a datastore.

4. Verify - Based on the input sign and the claim, it can verify if the the given sign is correct for the provided claim.

5. Rotate Key - Encryption Service supports changing the key used for encryption. The old key will still remain with the service which will be used to decrypt old data. All the new data will be encrypted by the new key.

Configuration Details

Following are the properties in application.properties file in egov-enc-service which are configurable.

Deployment Details

Integration

Integration Scope

The Encryption service is used to encrypt sensitive data that needs to be stored in the database. For each tenant, a different data encryption key (DEK) is used. The DEK is encrypted using Key Encryption Keys (KEK). Currently, there are two implementations of encrypting the data encryption keys available. The first one is using AWS KMS service and the second one is using a master password. For any custom implementation, the MasterKeyProvider interface in the service should be extended. Based on the master.password.provider flag in appication.properties you can enable which implementation of MasterKeyProvider interface to use

Integration Benefits

• Can perform encryption without having to re-write encryption logic every time in every service.

Steps to Integration

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

2. /crypto/v1/_encrypt should be added as an endpoint for encrypting input data in the system

3. /crypto/v1/_decrypt should be added as the decryption endpoint.

4. /crypto/v1/_sign should be added as the endpoint for providing a signature for a given value.

5. /crypto/v1/_verify should be added as the endpoint for verifying whether the signature for the provided value is correct.

6. /crypto/v1/_rotatekey should be added as an endpoint to deactivate the keys and generate new keys for a given tenant.

Reference Docs

Doc Links

API List

a) POST /crypto/v1/_encrypt

Encrypts the given input value/s OR values of the object.

b) POST /crypto/v1/_decrypt

Decrypts the given input value/s OR values of the object.

c) /crypto/v1/_sign

Provide signature for a given value.

d) POST /crypto/v1/_verify

Check if the signature is correct for the provided value.

e) POST /crypto/v1/_rotatekey

Deactivate the keys for the given tenant and generate new keys. It will deactivate both symmetric and asymmetric keys for the provided tenant.

Overview

An eGov core application which handles uploading different kinds of files to server 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 storages.

The request file to be uploaded is taken in form of multipart file part then saved to the storage and a uuid will returned as a unique identifier for that resource, which can be used to fetch the documents later.

Incase of images, the application will create three more additional copies of the file in the likes of large, medium and small for the usage of thumbnails or low quality images incase 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 case of images a single string containing multiple urls separated by commas will be 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 but 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.

• NOTE : 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.

For the API information please refer the swagger YAML

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

&#xNAN;IMPORTANT : To work work any of the file storage there are some application properties which needs 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:

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

• 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 files is the use of set brackets with strings inside it - {"jpg", "png"}. Make sure to follow the same.

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 in tika website or by passing the file through tika functions.

Features

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

2. Search Files GET API to retrieve files 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 Details

Integration Scope

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

Integration Benefits

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

Integration Steps

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

2. /filestore/v1/files should be added as the endpoint for uploading files 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

Indexer uses a config file per module to store all the configurations pertaining to that module. The 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 names, 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.

ServiceMaps:
  serviceName: Trade License
  version: 1.0.0
  mappings:
  - topic: save-tl-tradelicense
    configKey: INDEX
    indexes:
    - name: tlindex-v1
      type: licenses
      id: $.id, $.tenantId
      isBulk: true
      timeStampField: $.auditDetails.createdTime
      jsonPath: $.Licenses
      customJsonMapping:
        indexMapping: {"Data":{"tradelicense":{},"ward":{},"tenantData":{}, "history":{}}}
        fieldMapping:
        - inJsonPath: $
          outJsonPath: $.Data.tradelicense
        externalUriMapping:
        - path: http://egov-location.egov:8080/egov-location/location/v11/boundarys/_search
          queryParam: hierarchyTypeCode=REVENUE,boundaryType=locality,codes=$.tradeLicenseDetail.address.locality.code,tenantId=$.tenantId
          apiRequest: {"RequestInfo":{"apiId":"org.egov.pt","ver":"1.0","ts":1502890899493,"action":"asd","did":"4354648646","key":"xyz","msgId":"654654","requesterId":"61","authToken":"d9994555-7656-4a67-ab3a-a952a0d4dfc8","userInfo":{"id":1,"uuid":"1fec8102-0e02-4d0a-b283-cd80d5dab067","type":"EMPLOYEE","tenantId":"pb.amritsar","roles":[{"name":"Employee","code":"EMPLOYEE","tenantId":"pb.amritsar"}]}}}
          uriResponseMapping:
          - inJsonPath: $.TenantBoundary[0].boundary[0]
            outJsonPath: $.Data.ward
        - path: http://egov-workflow-v2.egov:8080/egov-workflow-v2/egov-wf/process/_search
          queryParam: businessIds=$.applicationNumber,history=true,tenantId=$.tenantId
          apiRequest: {"RequestInfo":{"apiId":"org.egov.pt","ver":"1.0","ts":1502890899493,"action":"asd","did":"4354648646","key":"xyz","msgId":"654654","requesterId":"61","authToken":"d9994555-7656-4a67-ab3a-a952a0d4dfc8","userInfo":{"id":1,"uuid":"1fec8102-0e02-4d0a-b283-cd80d5dab067","type":"EMPLOYEE","tenantId":"pb.amritsar","roles":[{"name":"Employee","code":"EMPLOYEE","tenantId":"pb.amritsar"}]}}}
          uriResponseMapping:
          - inJsonPath: $.ProcessInstances
            outJsonPath: $.Data.history
        mdmsMapping:
        - path: http://egov-mdms-service.egov:8080/egov-mdms-service/v1/_search
          moduleName: tenant
          masterName: tenants
          tenantId: pb
          filter: "[?(@.code == $tenant)]"
          filterMapping:
          - variable: $tenant
            valueJsonpath: $.tenantId
          uriResponseMapping:
          - inJsonPath: $.MdmsRes.tenant.tenants
            outJsonPath: $.Data.tenantData

Variable List

The table below lists the key configuration variables.

Overview

The Internal Gateway is a simplified Zuul service which provides an easy integration of services running different namespaces of a multistate instance, the clients need not know about all the details of microservices and their namespace in the K8s setup.

Pre-requisites

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

• Java 17

• API Gateway

Key Functionalities

• Provides an easier API interface between services running in different tenants(namespaces) where direct access between microservices is blocked by default.

• Allows refactoring microservices independently without forcing the clients to refactor integrating logic with other tenants.

Zuul Components

Route filter - a single route filter enables the routing based on tenatId from the HTTP header of the incoming requests.

Configuration Details

Routing Property

For each service, the below-mentioned property has to be added in internal-gateway.json

{
  "/egov-mdms-service/.*": {
    "in.statea": "http://egov-mdms-service.statea:8080",
    "in.stateb": "http://egov-mdms-service.stateb:8080",
    "in": "http://egov-mdms-service:8080"
  },
  "/pt-calculator-v2/.*": {
    "in.statea": "http://pt-calculator-v2.statea:8080",
    "in.stateb": "http://pt-calculator-v2.stateb:8080",
    "in": "http://pt-calculator-v2.digit:8080"
  },
  "/property-services/.*": {
    "in.stateb": "http://property-services.digit:8080",
    "in.statea": "http://property-services.digit:8080"
  },
  "/billing-service/.*": {
    "in.stateb": "http://billing-service.digit:8080",
    "in.statea": "http://billing-service.digit:8080"
  },
  "/egov-searcher/.*": {
    "in.statea": "http://egov-searcher.statea:8080",
    "in.stateb": "http://egov-searcher.stateb:8080"
  },
  "/dashboard-analytics/.*": {
    "in.statea": "http://dashboard-analytics.statea:8080",
    "in.stateb": "http://dashboard-analytics.stateb:8080"
  }
}

Sequence Diagram

Open

User Service stores the PII data in the database in encrypted form. So whichever service is reading that data directly from the database will have to decrypt the data before responding to the user. As of now, to the best of our knowledge following services are reading the user data from the database:

1. User Service

2. Report Service

3. Searcher Service

Enc-Client Library is a supplementary library with features like masking, auditing, etc. The above services call the functions from the library to decrypt the data read from the database.

Overview

In a bid to avoid unnecessary repetition of codes which generate ids and to have central control over the logic so that the burden of maintenance is reduced from the developers. To create a config-based application which 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 and 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, and sequence generated number. Id can be generated by providing a request with any of the above-mentioned information.

For example:

The Id Amritsar-PT-2019/09/12-000454-99 contains

• Amritsar - which is the name of the city

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

• 2019/09/12 - date

• 000454 - sequence generated number

• 99 - random number