API Specs

Find below the Open API specifications defined for this guide:

Birth Registration

Process Workflow Diagram

Registries

As a part of this guide, we are going to build a single birth registry. We will re-use the user registry from the DIGIT core. This will capture the mother and father details and store them in the user registry. The baby's details will remain in the birth registry.

Services

A single birth service will manage the registry.

System Architecture Diagram

The outputs of the design phase are the inputs to the development phase.

The docs below provide the steps and the resources required to build and design the module.

This section showcases how to create a basic Spring Boot project using an API spec and configure the database.

Follow the steps detailed below:

Overview

The application.properties file is already populated with default values. Read on to learn how to customise and add extra values for your application (if required).

Steps

Kafka topics for the module that need to be added are detailed here.

Include all the necessary service host URLs and API endpoints in the "application.properties" file.

This guide specifically references the User, Localisation, HRMS, IDGen, MDMS, and Workflow services that are operational within the DIGIT development environment.

Configure Application Properties

1. Add the following properties to the application.properties file.

#Localization config
egov.localization.host=https://dev.digit.org
egov.localization.workDir.path=/localization/messages/v1
egov.localization.context.path=/localization/messages/v1
egov.localization.search.endpoint=/_search
egov.localization.statelevel=true

#mdms urls
egov.mdms.host=https://dev.digit.org
egov.mdms.search.endpoint=/egov-mdms-service/v1/_search

#hrms urls
egov.hrms.host=https://dev.digit.org
egov.hrms.search.endpoint=/egov-hrms/employees/_search

#User config
#egov.user.host=https://dev.digit.org
egov.user.host=http://localhost:8284/
egov.user.context.path=/user/users
egov.user.create.path=/_createnovalidate
egov.user.search.path=/user/_search
egov.user.update.path=/_updatenovalidate

#Idgen Config
egov.idgen.host=http://localhost:8285/
egov.idgen.path=egov-idgen/id/_generate

#Workflow config
is.workflow.enabled=true
egov.workflow.host=http://localhost:8280
egov.workflow.transition.path=/egov-workflow-v2/egov-wf/process/_transition
egov.workflow.businessservice.search.path=/egov-workflow-v2/egov-wf/businessservice/_search
egov.workflow.processinstance.search.path=/egov-workflow-v2/egov-wf/process/_search

The following properties must be added for configuring the database and Kafka server. Make sure to use the default values to tune in the Kafka server that can be overwritten during deployment.

1. Include the following properties in the "application.properties" file to configure the database and Kafka for development purposes once you have completed adding the external dependencies to the "pom.xml" file and reloading the Maven changes.

#DATABASE CONFIGURATION
spring.datasource.driver-class-name=org.postgresql.Driver
spring.datasource.url=jdbc:postgresql://localhost:5432/birthregn
spring.datasource.username=birth
spring.datasource.password=birth

Configure Kafka

# KAFKA SERVER CONFIGURATIONS
kafka.config.bootstrap_server_config=localhost:9092
spring.kafka.consumer.value-deserializer=org.egov.tracer.kafka.deserializer.HashMapDeserializer
spring.kafka.consumer.key-deserializer=org.apache.kafka.common.serialization.StringDeserializer
spring.kafka.consumer.group-id={PLACEHOLDER_PUT_KAFKA_CONSUMER_NAME}
spring.kafka.producer.key-serializer=org.apache.kafka.common.serialization.StringSerializer
spring.kafka.producer.value-serializer=org.springframework.kafka.support.serializer.JsonSerializer
spring.kafka.listener.missing-topics-fatal=false
spring.kafka.consumer.properties.spring.json.use.type.headers=false

# KAFKA CONSUMER CONFIGURATIONS
kafka.consumer.config.auto_commit=true
kafka.consumer.config.auto_commit_interval=100
kafka.consumer.config.session_timeout=15000
kafka.consumer.config.auto_offset_reset=earliest

# KAFKA PRODUCER CONFIGURATIONS
kafka.producer.config.retries_config=0
kafka.producer.config.batch_size_config=16384
kafka.producer.config.linger_ms_config=1
kafka.producer.config.buffer_memory_config=33554432

Kafka Topics For Module

Create & Update Kafka Topics For The Module

1. Append Kafka configurations as per the specific requirements of the DIGIT services. Each module may use different configurations to manage its topics.

# Birth registration Kafka config
btr.kafka.create.topic=save-bt-application
btr.kafka.update.topic=update-bt-application
btr.default.offset=0
btr.default.limit=10
btr.search.max.limit=50

This guide provides detailed steps for developers to create a new microservice on top of DIGIT. At the end of this guide, you will be able to run the sample module provided (code provided), test it out locally and also deploy it using CI/CD to your DIGIT environment.

Steps to create a microservice:

• Set up your development environment

• Develop the registries, services, and APIs for a voter registration module that were described in the Design Guide

• Integrate with an existing DIGIT environment and re-use a lot of the common services using Kubernetes port forwarding

• Test the new module and debug

• Build and deploy the new service in the DIGIT environment

The guide is divided into multiple sections for ease of use. Click on the section cards below to follow the development steps.

Access the sample module here. Download and run this in the local environment.

Overview

The pom.xml typically includes most of the dependencies listed below at project generation time. Review and ensure that all of these dependencies are present. Update the pom.xml in case any are missing.

Steps

Models/POJOs of the dependent service can be imported from the digit-core-models library (work on creating the library is ongoing). These models are used to integrate with the dependent services.

These are pre-written libraries which contain tracer support, common models like MDMS, Auth and Auth and the capability to raise custom exceptions.

Once these core models are imported, it is safe to delete the RequestInfo, and ResponseInfo classes from the models folder and use the ones present in the common contract that is imported.

Import Core Models

Before starting development, create/update the following classes as given below.

1. Delete the following classes which have been generated from codegen - -Address -AuditDetails -Document -Error -ErrorResponse -RequestInfo -RequestInfoWrapper -ResponseInfo -Role -User -Workflow After this import the above classes from egov common-service library as follow-\

2. Create the BirthApplicationSearchRequest POJO with the following content -

1. Update BirthApplicationAddress pojo

1. Create the BTRConfiguration class within the configuration package. The MainConfiguration class should already exist inside the config package.

The core models are imported.

Checklist

Before starting development on top of DIGIT make sure:

• To check out the page to learn how to deploy the required tools.

• DIGIT code from DIGIT-OSS, egov-mdms-data, configs etc.. has been forked from GitHub under your organization’s umbrella account.

• You have access to the forked repositories from your GitHub user account. Note that the user account is different from the organization's account.

• Access a DIGIT environment - FQDN, Access keys etc..The DIGIT environment can be a single VM setup for a development environment. Please refer to these docs for the installation of DIGIT.

• Install DIGIT in a development environment (Single VM setup) by following the .

• It is recommended to deploy the following services in the development environment -

Some of the above services can also be port-forwarded using Kubernetes to bypass user authentication.

• Make sure the following DIGIT services are running in the local environment:

  • (optional)

• has been set up for DIGIT. This is a pre-requisite to deploying new DIGIT modules. CD/CI processes will be used to build and deploy the new module that will be developed.

• In addition, knowledge of the following technologies is required for developing on DIGIT: (Refer to the for help with installing and deploying these tools)

  • Java/J2EE

  • Spring Boot

  • REST APIs and related concepts like path parameters, headers, JSON etc.

  • Git

  • PostgreSQL

  • Kafka

Overview

Once PostgreSQL (v10) has been installed and the basic setup is done, we use Flyway to create the tables.

Steps

Enable Flyway Migration

1. Configure the below properties in the application.properties file to enable flyway migration:

1. Add the Flyway SQL scripts in the following structure under resources/db/migration/main:

1. Add the migration files to the main folder. Follow the specified nomenclature while naming the file. The file name should be in the following format:

Example: V20180920110535__tl_tradelicense_ddl.sql

For this sample service, use the following SQL script to create the required tables.

Overview

This page provides detailed steps for generating projects using the given API specifications.

Steps

Build A Microservice

1. Prepare contracts that detail all the APIs that the service is going to expose for external consumption. eGov uses a customised tool.

2. Download the jar file and make sure it is available in the classpath. Use the to generate client SDKs using these Swagger contracts.

Generate API Skeleton

1. Use the generic command below to create an API skeleton for any Swagger contract:

The following sequence is used to generate the API skeleton using codegen jar:

1. Navigate to the folder where you have downloaded the codegen jar.

2. Execute the following command:

OR

1. Rename the output folder to birth-registration.

2. Import it in Eclipse or VS Code.

3. Update the spring-boot-starter-parent to 3.2.2 in pom.xml.

4. Perform a maven update once the spring boot version is updated.

5. Put a slash in front of server.contextPath and add this property to the application.properties file which helps request handlers to serve requests -

1. Add the below external dependencies to pom.xml:

Overview

Follow the steps outlined on this page to setup the DIGIT development environment.

Steps

To setup the DIGIT development environment -

1. Run the Kafka and PostgreSQL on the development machine and re-use other services from the DIGIT development environment. The following tools are required for development:

   • Install Git

     Git for windows

     Git for Linux

   • Install JDK17

     JDK17 for windows

     JDK17 for Linux

   • Install IDE - To create SpringBoot/Java applications it is recommended to use IntelliJ IDE. IntelliJ can be downloaded from the following links -

     IntelliJ for windows

     IntelliJ for Linux

   • Install the Lombok plugins for IntelliJ as we use Lombok annotations in this module.

   • Install Kafka (version 3.2.0 which is the latest version) - To install and run Kafka locally, follow the following links -

     Kafka for windows

     Kafka for Linux

   • Install Postman - To install Postman, follow the following links -

     Postman for windows

     Postman for Linux

   • Install Kubectl - Kubectl is the tool that we use to interact with services deployed on our sandbox environment - kubectl for windows

   https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/

   • Install aws-iam-authenticator - (if the DIGIT development environment is in AWS) - https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html

   • Install PostgreSQL v14 locally

2. Add configuration - Post installation of Kubectl, add the following configuration in the Kubernetes config file to enable access to resources in our sandbox environment. Kubernetes config file is available in the user's home directory (which varies from OS to OS).

   For example, on a Mac, it is available at:/Users/xyz/.kube/config

   Once the config file is created, add the following content to it.

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUN5RENDQWJDZ0F3SUJBZ0lCQURBTkJna3Foa2lHOXcwQkFRc0ZBREFWTVJNd0VRWURWUVFERXdwcmRXSmwKY201bGRHVnpNQjRYRFRJd01EVXhNekV6TlRReE5sb1hEVE13TURVeE1URXpOVFF4Tmxvd0ZURVRNQkVHQTFVRQpBeE1LYTNWaVpYSnVaWFJsY3pDQ0FTSXdEUVlKS29aSWh2Y05BUUVCQlFBRGdnRVBBRENDQVFvQ2dnRUJBTkJyClN6aHJjdDNORE1VZVF5TENTYWhwbEgyajJ1bkdYSWk1QThJZjF6OTgwNEZpSjZ6OS9qUHVpY3FjaTB1VURJQnUKS3hjdVFJRkozMG1MRWg3RGNiQlh2dDRnUlppZWtlZzVZNGxDT2NlTWZFZkFHY01KdDE1RVVCUFVzdlYyclRMcQp6a0ovRzVRUUFXMmhwREJLaFBoblZJTktYN1YzOU9tMUtuTklTbllPWERsZ1g3dW9Wa3I1OFhzREFHWEVsdC9uClpyc3laM2pkMWplWS8rMXlQQzlxbkorT0QwZlRQVGdCV1hMQlFwMHZKdHVzNE1JV2JLdkhlcUZ5eWtGd2V5MmoKSzk5eU1Yb0oraUpCaFJvWGllU3ZrNnFYdG44S2l4bVJtOXZPQk1hcWpuNkwwTjc3UWNCNjVRaHNKb0tWKzBiMQp5VVpJTHVTWWVTY0Yra3h6TzFVQ0F3RUFBYU1qTUNFd0RnWURWUjBQQVFIL0JBUURBZ0trTUE4R0ExVWRFd0VCCi93UUZNQU1CQWY4d0RRWUpLb1pJaHZjTkFRRUxCUUFEZ2dFQkFNdnF3THl6d2RUL05OWlkvanNzb0lmQmIyNDgKZ3oxSHRuSXJ4UGhaY3RrYjBSMExxeTYzRFZBMFNSN0MrWk90aTNNd3BHMkFSVHVzdG1vYm9HV3poUXlXRk16awpVMVNIZSt6S3poeGcweUpjUjliZnlxM1ZtQVVCZlQyTVV5cVl2OVg0aWxpbmV0SURQaFBuWnlPMERQTHJITGoyCkcxZy8vWmZYbmFCT2k3dlZLSXFXUUR6RlltWGkwME9vOEVoalVyMU5sQ3FISnF1dUo3TlRWQWk1cXA0Qm1xWU8KUTBrbTVxTVVHbG9ZdkNmN1lHQWREWTVnWGg4dzFVMVdaNWNub0Q4WWc3aEtlSjRMRzRram1adlNucGZrS3VxNApiVDdUSjEwUEZlWFJkek8xa2FkQ3VMQSttUlg3OEd5WEw0UTZnOFdPUlhOVDYzdXN3MnlpMXVVN1lMTT0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
    server: https://3201E325058272AA0990C04346DA6E82.yl4.ap-south-1.eks.amazonaws.com
  name: eks_egov-dev
contexts:
- context:
    cluster: eks_egov-dev
    namespace: egov
    user: eks_egov-dev
  name: dev
current-context: dev
kind: Config
preferences: {}
users:
- name: eks_egov-dev
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1alpha1
      args:
      - token
      - -i
      - egov-dev
      command: aws-iam-authenticator
      env:
      - name: AWS_ACCESS_KEY
        value: {AWS_ACCESS_KEY_PLACEHOLDER}
      - name: AWS_SECRET_ACCESS_KEY
        value: {AWS_SECRET_ACCESS_KEY_PLACEHOLDER}
      - name: AWS_REGION
        value: {AWS_REGION_PLACEHOLDER}

Once the configuration file is created, access the pods running in the environment by typing: kubectl get pods

This lists all the pods in the development environment.

Overview

The service layer performs business logic on the RequestData and prepares the Response to be returned back to the client.

Steps

Follow the steps below to create the service layer.

1. Create a new package called Service.

2. Create a new class in this folder by the name BirthRegistrationService.

3. Annotate the class with @Service annotation.

4. Add the following content to the class -

   Copy

   package digit.service;
   
   
   import digit.enrichment.BirthApplicationEnrichment;
   import digit.kafka.Producer;
   import digit.repository.BirthRegistrationRepository;
   import digit.validators.BirthApplicationValidator;
   import digit.web.models.BirthApplicationSearchCriteria;
   import digit.web.models.BirthRegistrationApplication;
   import digit.web.models.BirthRegistrationRequest;
   import lombok.extern.slf4j.Slf4j;
   import org.egov.common.contract.request.RequestInfo;
   import org.springframework.beans.factory.annotation.Autowired;
   import org.springframework.stereotype.Service;
   import org.springframework.util.CollectionUtils;
   
   import java.util.ArrayList;
   import java.util.Collections;
   import java.util.List;
   
   @Service
   @Slf4j
   public class BirthRegistrationService {
   
       @Autowired
       private BirthApplicationValidator validator;
   
       @Autowired
       private BirthApplicationEnrichment enrichmentUtil;
   
       @Autowired
       private UserService userService;
   
       @Autowired
       private WorkflowService workflowService;
   
       @Autowired
       private BirthRegistrationRepository birthRegistrationRepository;
   
       @Autowired
       private Producer producer;
   
       public List<BirthRegistrationApplication> registerBtRequest(BirthRegistrationRequest birthRegistrationRequest) {
           // Validate applications
           validator.validateBirthApplication(birthRegistrationRequest);
   
           // Enrich applications
           enrichmentUtil.enrichBirthApplication(birthRegistrationRequest);
   
   //         Enrich/Upsert user in upon birth registration
           userService.callUserService(birthRegistrationRequest);
   //
           // Initiate workflow for the new application
           workflowService.updateWorkflowStatus(birthRegistrationRequest);
   
           // Push the application to the topic for persister to listen and persist
           producer.push("save-bt-application", birthRegistrationRequest);
   
           // Return the response back to user
           return birthRegistrationRequest.getBirthRegistrationApplications();
       }
   
       public List<BirthRegistrationApplication> searchBtApplications(RequestInfo requestInfo, BirthApplicationSearchCriteria birthApplicationSearchCriteria) {
           // Fetch applications from database according to the given search criteria
           List<BirthRegistrationApplication> applications = birthRegistrationRepository.getApplications(birthApplicationSearchCriteria);
   
           // If no applications are found matching the given criteria, return an empty list
           if(CollectionUtils.isEmpty(applications))
               return new ArrayList<>();
   
           // Enrich mother and father of applicant objects
           applications.forEach(application -> {
               enrichmentUtil.enrichFatherApplicantOnSearch(application);
               enrichmentUtil.enrichMotherApplicantOnSearch(application);
           });
   
           // Otherwise return the found applications
           return applications;
       }
   
       public BirthRegistrationApplication updateBtApplication(BirthRegistrationRequest birthRegistrationRequest) {
           // Validate whether the application that is being requested for update indeed exists
           BirthRegistrationApplication existingApplication = validator.validateApplicationExistence(birthRegistrationRequest.getBirthRegistrationApplications().get(0));
           existingApplication.setWorkflow(birthRegistrationRequest.getBirthRegistrationApplications().get(0).getWorkflow());
           log.info(existingApplication.toString());
           birthRegistrationRequest.setBirthRegistrationApplications(Collections.singletonList(existingApplication));
   
           // Enrich application upon update
           enrichmentUtil.enrichBirthApplicationUponUpdate(birthRegistrationRequest);
   
           workflowService.updateWorkflowStatus(birthRegistrationRequest);
   
           // Just like create request, update request will be handled asynchronously by the persister
           producer.push("update-bt-application", birthRegistrationRequest);
   
           return birthRegistrationRequest.getBirthRegistrationApplications().get(0);
       }
   }

Overview

Find the steps to create the Validation Layer and Enrichment Layer on DIGIT.

Validation Layer

All business validation logic should be added to this class. For example, verifying the values against the master data, ensuring non-duplication of data etc.

Steps

Follow the steps below to create the validation layer.

1. Create a package called validators. This ensures the validation logic is separate so that the code is easy to navigate through and readable.

2. Create a class by the name of BirthApplicationValidator

3. Annotate the class with @Component annotation and insert the following content in the class -

package digit.validators;

import digit.repository.BirthRegistrationRepository;
import digit.web.models.BirthApplicationSearchCriteria;
import digit.web.models.BirthRegistrationApplication;
import digit.web.models.BirthRegistrationRequest;
import org.egov.tracer.model.CustomException;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import org.springframework.util.ObjectUtils;

@Component
public class BirthApplicationValidator {

    @Autowired
    private BirthRegistrationRepository repository;

    public void validateBirthApplication(BirthRegistrationRequest birthRegistrationRequest) {
        birthRegistrationRequest.getBirthRegistrationApplications().forEach(application -> {
            if(ObjectUtils.isEmpty(application.getTenantId()))
                throw new CustomException("EG_BT_APP_ERR", "tenantId is mandatory for creating birth registration applications");
        });
    }

    public BirthRegistrationApplication validateApplicationExistence(BirthRegistrationApplication birthRegistrationApplication) {
        return repository.getApplications(BirthApplicationSearchCriteria.builder().applicationNumber(birthRegistrationApplication.getApplicationNumber()).build()).get(0);
    }
}

Enrichment Layer

This layer enriches the request. System-generated values like id, auditDetails etc. are generated and added to the request. In the case of this module, since the applicant is the parent of a baby and a child cannot be a user of the system directly, both the parents' details are captured in the User table. The user ids of the parents are then enriched in the application.

Steps

Follow the steps below to create the enrichment layer.

1. Create a package under DIGIT by the name of enrichment. This ensures the enrichment code is separate from business logic so that the codebase is easy to navigate through and readable.

2. Create a class by the name of BirthApplicationEnrichment

3. Annotate the class with @Component and add the following methods to the class -

package digit.enrichment;

import digit.service.UserService;
import digit.util.IdgenUtil;
import digit.util.UserUtil;
import digit.web.models.*;
import lombok.extern.slf4j.Slf4j;
import org.egov.common.contract.models.AuditDetails;
import org.egov.common.contract.request.User;
import org.egov.common.contract.user.UserDetailResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import java.util.List;
import java.util.UUID;
@Component
@Slf4j
public class BirthApplicationEnrichment {

    @Autowired
    private IdgenUtil idgenUtil;

    @Autowired
    private UserService userService;

    @Autowired
    private UserUtil userUtils;

    public void enrichBirthApplication(BirthRegistrationRequest birthRegistrationRequest) {
       List<String> birthRegistrationIdList = idgenUtil.getIdList(birthRegistrationRequest.getRequestInfo(), birthRegistrationRequest.getBirthRegistrationApplications().get(0).getTenantId(), "btr.registrationid", "", birthRegistrationRequest.getBirthRegistrationApplications().size());
        Integer index = 0;
        for(BirthRegistrationApplication application : birthRegistrationRequest.getBirthRegistrationApplications()){
            // Enrich audit details
            AuditDetails auditDetails = AuditDetails.builder().createdBy(birthRegistrationRequest.getRequestInfo().getUserInfo().getUuid()).createdTime(System.currentTimeMillis()).lastModifiedBy(birthRegistrationRequest.getRequestInfo().getUserInfo().getUuid()).lastModifiedTime(System.currentTimeMillis()).build();
            application.setAuditDetails(auditDetails);

            // Enrich UUID
            application.setId(UUID.randomUUID().toString());

//            Enrich application number from IDgen
            application.setApplicationNumber(birthRegistrationIdList.get(index++));
//             Enrich registration Id
            application.getAddress().setApplicationNumber(application.getId());

            // Enrich address UUID
            application.getAddress().setId(UUID.randomUUID().toString());

        }
    }

    public void enrichBirthApplicationUponUpdate(BirthRegistrationRequest birthRegistrationRequest) {
        // Enrich lastModifiedTime and lastModifiedBy in case of update
        birthRegistrationRequest.getBirthRegistrationApplications().get(0).getAuditDetails().setLastModifiedTime(System.currentTimeMillis());
        birthRegistrationRequest.getBirthRegistrationApplications().get(0).getAuditDetails().setLastModifiedBy(birthRegistrationRequest.getRequestInfo().getUserInfo().getUuid());
    }

    public void enrichFatherApplicantOnSearch(BirthRegistrationApplication application) {
        UserDetailResponse fatherUserResponse = userService.searchUser(userUtils.getStateLevelTenant(application.getTenantId()),application.getFather().getUuid(),null);
        User fatherUser = fatherUserResponse.getUser().get(0);
        log.info(fatherUser.toString());
        User fatherApplicant = User.builder()
                .mobileNumber(fatherUser.getMobileNumber())
                .id(fatherUser.getId())
                .name(fatherUser.getName())
                .userName((fatherUser.getUserName()))
                .type(fatherUser.getType())
                .roles(fatherUser.getRoles())
                .uuid(fatherUser.getUuid()).build();
        application.setFather(fatherApplicant);
    }

    public void enrichMotherApplicantOnSearch(BirthRegistrationApplication application) {
        UserDetailResponse motherUserResponse = userService.searchUser(userUtils.getStateLevelTenant(application.getTenantId()),application.getMother().getUuid(),null);
        User motherUser = motherUserResponse.getUser().get(0);
        log.info(motherUser.toString());
        User motherApplicant = User.builder()
                .mobileNumber(motherUser.getMobileNumber())
                .id(motherUser.getId())
                .name(motherUser.getName())
                .userName((motherUser.getUserName()))
                .type(motherUser.getType())
                .roles(motherUser.getRoles())
                .uuid(motherUser.getUuid()).build();
        application.setMother(motherApplicant);
    }
}

Overview

Methods in the service layer, upon performing all the business logic, call methods in the repository layer to persist or lookup data i.e. it interacts with the configured data store. For executing the queries, JdbcTemplate class is used. JdbcTemplate takes care of the creation and release of resources such as creating and closing the connection etc. All database operations namely insert, update, search and delete can be performed on the database using methods of JdbcTemplate class.

Steps

On DIGIT the create and update operations are handled asynchronously.

The persister service listens on the topic to which service applications are pushed for insertion and updation. Persister then takes care of executing insert and update operations on the database without clogging the application’s threads.

The execution of search queries on the database returns applications as per the search parameters provided by the user.

Implement Repository Layer

1. Create packages - Add thequerybuilder and rowmapper packages within the repository folder.

2. Create a class - by the name of BirthApplicationQueryBuilder in querybuilder folder and annotate it with @Component annotation.

   Insert the following content in BirthApplicationQueryBuilder class -

package digit.repository.querybuilder;

import digit.web.models.BirthApplicationSearchCriteria;
import org.springframework.stereotype.Component;
import org.springframework.util.CollectionUtils;
import org.springframework.util.ObjectUtils;

import java.util.List;

@Component
public class BirthApplicationQueryBuilder {

    private static final String BASE_BTR_QUERY = " SELECT btr.id as bid, btr.tenantid as btenantid, btr.applicationnumber as bapplicationnumber, btr.babyfirstname as bbabyfirstname, btr.babylastname as bbabylastname, btr.fatherid as bfatherid, btr.motherid as bmotherid, btr.doctorname as bdoctorname, btr.hospitalname as bhospitalname, btr.placeofbirth as bplaceofbirth, btr.timeofbirth as btimeofbirth, btr.createdby as bcreatedby, btr.lastmodifiedby as blastmodifiedby, btr.createdtime as bcreatedtime, btr.lastmodifiedtime as blastmodifiedtime, ";

    private static final String ADDRESS_SELECT_QUERY = " add.id as aid, add.tenantid as atenantid, add.type as atype, add.address as aaddress, add.city as acity, add.pincode as apincode, add.registrationid as aregistrationid ";

    private static final String FROM_TABLES = " FROM eg_bt_registration btr LEFT JOIN eg_bt_address add ON btr.id = add.registrationid ";

    private final String ORDERBY_CREATEDTIME = " ORDER BY btr.createdtime DESC ";

    public String getBirthApplicationSearchQuery(BirthApplicationSearchCriteria criteria, List<Object> preparedStmtList){
        StringBuilder query = new StringBuilder(BASE_BTR_QUERY);
        query.append(ADDRESS_SELECT_QUERY);
        query.append(FROM_TABLES);

        if(!ObjectUtils.isEmpty(criteria.getTenantId())){
            addClauseIfRequired(query, preparedStmtList);
            query.append(" btr.tenantid = ? ");
            preparedStmtList.add(criteria.getTenantId());
        }
        if(!ObjectUtils.isEmpty(criteria.getStatus())){
            addClauseIfRequired(query, preparedStmtList);
            query.append(" btr.status = ? ");
            preparedStmtList.add(criteria.getStatus());
        }
        if(!CollectionUtils.isEmpty(criteria.getIds())){
            addClauseIfRequired(query, preparedStmtList);
            query.append(" btr.id IN ( ").append(createQuery(criteria.getIds())).append(" ) ");
            addToPreparedStatement(preparedStmtList, criteria.getIds());
        }
        if(!ObjectUtils.isEmpty(criteria.getApplicationNumber())){
            addClauseIfRequired(query, preparedStmtList);
            query.append(" btr.applicationnumber = ? ");
            preparedStmtList.add(criteria.getApplicationNumber());
        }

        // order birth registration applications based on their createdtime in latest first manner
        query.append(ORDERBY_CREATEDTIME);

        return query.toString();
    }

    private void addClauseIfRequired(StringBuilder query, List<Object> preparedStmtList){
        if(preparedStmtList.isEmpty()){
            query.append(" WHERE ");
        }else{
            query.append(" AND ");
        }
    }

    private String createQuery(List<String> ids) {
        StringBuilder builder = new StringBuilder();
        int length = ids.size();
        for (int i = 0; i < length; i++) {
            builder.append(" ?");
            if (i != length - 1)
                builder.append(",");
        }
        return builder.toString();
    }

    private void addToPreparedStatement(List<Object> preparedStmtList, List<String> ids) {
        ids.forEach(id -> {
            preparedStmtList.add(id);
        });
    }
}

1. Create a class - by the name of BirthApplicationRowMapper within the rowmapper package and annotate it with @Component.

   Add the following content to the class.

   Copy

   package digit.repository.rowmapper;
   
   import digit.web.models.*;
   import org.egov.common.contract.models.Address;
   import org.egov.common.contract.models.AuditDetails;
   import org.egov.common.contract.request.User;
   import org.egov.common.contract.user.enums.AddressType;
   import org.springframework.dao.DataAccessException;
   import org.springframework.jdbc.core.ResultSetExtractor;
   import org.springframework.stereotype.Component;
   
   import java.sql.ResultSet;
   import java.sql.SQLException;
   import java.util.*;
   
   @Component
   public class BirthApplicationRowMapper implements ResultSetExtractor<List<BirthRegistrationApplication>> {
       public List<BirthRegistrationApplication> extractData(ResultSet rs) throws SQLException, DataAccessException {
           Map<String,BirthRegistrationApplication> birthRegistrationApplicationMap = new LinkedHashMap<>();
   
           while (rs.next()){
               String uuid = rs.getString("bapplicationnumber");
               BirthRegistrationApplication birthRegistrationApplication = birthRegistrationApplicationMap.get(uuid);
   
               if(birthRegistrationApplication == null) {
   
                   Long lastModifiedTime = rs.getLong("blastModifiedTime");
                   if (rs.wasNull()) {
                       lastModifiedTime = null;
                   }
   
   
                   User father = User.builder().uuid(rs.getString("bfatherid")).build();
                   User mother = User.builder().uuid(rs.getString("bmotherid")).build();
   
                   AuditDetails auditdetails = AuditDetails.builder()
                           .createdBy(rs.getString("bcreatedBy"))
                           .createdTime(rs.getLong("bcreatedTime"))
                           .lastModifiedBy(rs.getString("blastModifiedBy"))
                           .lastModifiedTime(lastModifiedTime)
                           .build();
   
                   birthRegistrationApplication = BirthRegistrationApplication.builder()
                           .applicationNumber(rs.getString("bapplicationnumber"))
                           .tenantId(rs.getString("btenantid"))
                           .id(rs.getString("bid"))
                           .babyFirstName(rs.getString("bbabyfirstname"))
                           .babyLastName(rs.getString("bbabylastname"))
                           .father(father)
                           .mother(mother)
                           .doctorName(rs.getString("bdoctorname"))
                           .hospitalName(rs.getString("bhospitalname"))
                           .placeOfBirth(rs.getString("bplaceofbirth"))
                           .timeOfBirth(rs.getInt("btimeofbirth"))
                           .auditDetails(auditdetails)
                           .build();
               }
               addChildrenToProperty(rs, birthRegistrationApplication);
               birthRegistrationApplicationMap.put(uuid, birthRegistrationApplication);
           }
           return new ArrayList<>(birthRegistrationApplicationMap.values());
       }
   
       private void addChildrenToProperty(ResultSet rs, BirthRegistrationApplication birthRegistrationApplication)
               throws SQLException {
           addAddressToApplication(rs, birthRegistrationApplication);
       }
   
       private void addAddressToApplication(ResultSet rs, BirthRegistrationApplication birthRegistrationApplication) throws SQLException {
           Address address = Address.builder()
                   .tenantId(rs.getString("atenantid"))
                   .address(rs.getString("aaddress"))
                   .city(rs.getString("acity"))
                   .pinCode(rs.getString("apincode"))
                   .build();
   
           BirthApplicationAddress birthApplicationAddress= BirthApplicationAddress.builder()
                           .id(rs.getString("aid"))
                           .tenantId(rs.getString("atenantid"))
                           .applicantAddress(address)
                           .build();
   
           birthRegistrationApplication.setAddress(birthApplicationAddress);
   
       }
   
   }

1. Create a class - by the name of BirthRegistrationRepository within the repository folder and annotate it with @Repository annotation.

   Add the following content to the class.

package digit.repository;

import digit.repository.querybuilder.BirthApplicationQueryBuilder;
import digit.repository.rowmapper.BirthApplicationRowMapper;
import digit.web.models.BirthApplicationSearchCriteria;
import digit.web.models.BirthRegistrationApplication;
import lombok.extern.slf4j.Slf4j;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Repository;

import java.util.ArrayList;
import java.util.List;


@Slf4j
@Repository
public class BirthRegistrationRepository {

    @Autowired
    private BirthApplicationQueryBuilder queryBuilder;

    @Autowired
    private JdbcTemplate jdbcTemplate;

    @Autowired
    private BirthApplicationRowMapper rowMapper;

    public List<BirthRegistrationApplication>getApplications(BirthApplicationSearchCriteria searchCriteria){
        List<Object> preparedStmtList = new ArrayList<>();
        String query = queryBuilder.getBirthApplicationSearchQuery(searchCriteria, preparedStmtList);
        log.info("Final query: " + query);
        return jdbcTemplate.query(query, preparedStmtList.toArray(), rowMapper);
    }
}

The repository layer is implemented.

Overview

Follow the steps detailed below to add the Kafka configurations.

Steps

Add the below code in application.properties to configure Kafka.

# BTR config
btr.kafka.create.topic=save-bt-application
btr.kafka.update.topic=update-bt-application
btr.default.offset=0
btr.default.limit=10
btr.search.max.limit=50

Overview

Follow the steps detailed below to implement Kafka Producer & Consumer.

Producer

Producer classes help in pushing data from the application to Kafka topics. DIGIT has a custom implementation of KafkaTemplate class in the tracer library called CustomKafkaTemplate. This implementation of the Producer class does not change across services of DIGIT.

Steps

1. Access the producer implementation details here - Producer Implementation.

   The Codegen jar already has created a Producer class. We will continue using it.

2. Make sure the tracer dependency version in the pom.xml is 2.9.0-SNAPSHOT.

Consumer

For our guide, we will be implementing a notification consumer in the following section.

Once an application is created/requested or progresses further in the workflow, notifications can be triggered as each of these events is pushed onto Kafka topics which can be listened to and an sms/email/in-app notification can be sent to the concerned user(s).

For our guide, we will be implementing a notification consumer which will listen to the topic on which birth registration applications are created. Create a customised message and send it to the notification service (sms/email) to trigger notifications to the concerned users.

Steps

1. Open Kafka/NotificationConsumer.java and paste the following code:

package digit.kafka;

import com.fasterxml.jackson.databind.ObjectMapper;
import digit.service.NotificationService;
import digit.web.models.BirthRegistrationRequest;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.kafka.support.KafkaHeaders;
import org.springframework.messaging.handler.annotation.Header;
import org.springframework.stereotype.Component;

import java.util.HashMap;

@Component
@Slf4j
public class NotificationConsumer {

    @Autowired
    private ObjectMapper mapper;

    @Autowired
    private NotificationService notificationService;

    @KafkaListener(topics = {"${btr.kafka.create.topic}"})
    public void listen(final HashMap<String, Object> record, @Header(KafkaHeaders.RECEIVED_TOPIC) String topic) {

        try {

            BirthRegistrationRequest request = mapper.convertValue(record, BirthRegistrationRequest.class);
            //log.info(request.toString());
            notificationService.prepareEventAndSend(request);

        } catch (final Exception e) {

            log.error("Error while listening to value: " + record + " on topic: " + topic + ": ", e);
        }
    }

}

1. Create a POJO by the name of SMSRequest in the web.models package and add the below content to it:

package digit.web.models;

import lombok.*;

@Getter
@AllArgsConstructor
@NoArgsConstructor
@Builder
@ToString
public class SMSRequest {
    private String mobileNumber;
    private String message;
}

1. Create a class by the name of NotificationService under service folder to handle preparation of customised messages and pushing the notifications.

   Add the below content to it -

package digit.service;

import digit.config.BTRConfiguration;
import digit.kafka.Producer;
import digit.web.models.BirthRegistrationApplication;
import digit.web.models.BirthRegistrationRequest;
import digit.web.models.SMSRequest;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;

import java.util.ArrayList;
import java.util.List;
@Slf4j
@Service
public class NotificationService {

    @Autowired
    private Producer producer;

    @Autowired
    private BTRConfiguration config;

    @Autowired
    private RestTemplate restTemplate;

    private static final String smsTemplate = "Dear {FATHER_NAME} and {MOTHER_NAME} your birth registration application has been successfully created on the system with application number - {APPNUMBER}.";

    public void prepareEventAndSend(BirthRegistrationRequest request){
        List<SMSRequest> smsRequestList = new ArrayList<>();
        request.getBirthRegistrationApplications().forEach(application -> {
            SMSRequest smsRequestForFather = SMSRequest.builder().mobileNumber( application.getFather().getMobileNumber()).message(getCustomMessage(smsTemplate, application)).build();
            SMSRequest smsRequestForMother = SMSRequest.builder().mobileNumber(application.getMother().getMobileNumber()).message(getCustomMessage(smsTemplate, application)).build();
            smsRequestList.add(smsRequestForFather);
            smsRequestList.add(smsRequestForMother);
        });
        for (SMSRequest smsRequest : smsRequestList) {
            producer.push(config.getSmsNotificationTopic(), smsRequest);
            log.info("Messages: " + smsRequest.getMessage());
        }
    }

    private String getCustomMessage(String template, BirthRegistrationApplication application) {
        template = template.replace("{APPNUMBER}", application.getApplicationNumber());
        template = template.replace("{FATHER_NAME}", application.getFather().getName());
        template = template.replace("{MOTHER_NAME}", application.getMother().getName());
        return template;
    }

}

Overview

Enabling signed audit for a module ensures that all transactions - creates, updates, deletes - are recorded in a digitally signed fashion. Learn more about the signed audit service here.

Steps

Enable Signed Audit

1. Add the following lines of code to the birth registration persister after the fromTopic attribute under mappings:

isTransaction: true
isAuditEnabled: true
module: BTR
objecIdJsonPath: $.id
tenantIdJsonPath: $.tenantId
transactionCodeJsonPath: $.applicationNumber
auditAttributeBasePath: $.BirthRegistrationApplications

Overview

This page provides the steps on how to add persister configuration.

The persister configuration is written in a YAML format. The INSERT and UPDATE queries for each table are added in prepared statement format, followed by the jsonPaths of values that have to be inserted/updated.

For example, for a table named studentinfo with id, name, age, and marks fields, the following configuration will get the persister ready to insert data into studentinfo table -

serviceMaps:
 serviceName: student-management-service
 mappings:
 - version: 1.0
   description: Persists student details in studentinfo table
   fromTopic: save-student-info
   isTransaction: true
   queryMaps:
       - query: INSERT INTO studentinfo( id, name, age, marks) VALUES (?, ?, ?, ?);
         basePath: Students.*
         jsonMaps:
          - jsonPath: $.Students.*.id

          - jsonPath: $.Students.*.name

          - jsonPath: $.Students.*.age

          - jsonPath: $.Students.*.marks

Steps

Add Persister Configuration

1. Fork the configs repo. Ignore if done already. Clone configs repo in the local environment.