Pre-requisite

MOSIP issues are maintained in Github. File the issue against the right repository.

Reporting Issues

1. Check if the issue is already reported.

2. Check if the issue is already fixed.

3. If not, just go and file the issue

4. Template for filing new issues

Describe the issue A clear and concise description of what the bug is.

To Reproduce Steps to reproduce the behavior:

Expected behavior A clear and concise description of what you expected to happen.

Actual behavior A clear and concise description of what you see.

Screenshots If applicable, add screenshots to help explain your problem.

Environment (please complete the following information): Hardware and software details such as client OS, Server OS, Browser details etc

Attach logs Helps in faster resolution of data

Additional context Add any other context about the problem here.

Features/Enhancement request guidelines

1. Check if the feature is already reported.

2. Check if the feature is already fixed.

3. If not, just go and file the feature request

4. Template for filing new feature request

What is the current limitation without the feature

Describe the feature request

What would the key benefits of this feature

Do you have any recommendations and solutions that are existing in the field

Any technology/solution recommendation would be highly appreciated

Purpose

The recommended Github work flow here is for developers to submit code and documentation contributions to MOSIP open source repositories.

Setup

1. Fork MOSIP repository of interest from https://github.com/mosip/

2. Clone the fork to your local machine. Eg:

   Copy

   $ git clone https://github.com/<your_github_id>/commons.git

3. Set upstream project as the original from where you forked. Eg:

   Copy

   $ cd commons
   $ git remote add upstream https://github.com/mosip/commons.git

4. Make sure you never directly push to upstream.

   Copy

   $ git remote set-url --push upstream no_push

5. Confirm the origin and upstream.

   Copy

   $ git remote -v

Code changes

1. Create a new issue in MOSIP Jira.

2. You may work on master, switch to a branch (like Release branch) or create a new branch.

3. Make sure you are up-to-date with upstream repo.

   Copy

   $ git pull upstream <branch> 

4. Once you are done with the work, commit your changes referring to Jira number in the commit message. Eg:

   Copy

   $ git commit -m "[MOS-2346] Adding new upload feature in Pre registration module for POA documents"

5. Once again ensure that you are up-to-date with upstream repo as it may have moved forward.

   Copy

   $ git pull upstream <branch> 

6. Build and test your code. Make sure it follows the coding guidelines.

7. Push to your forked repo (origin).

   Copy

   $ git push 

8. Create a pull-request on your forked repo. Direct the pull-request to master or any specific branch on upstream (like a Release branch).

9. Make sure the automatic tests on Github for your pull-request pass.

10. The pull-request shall be reviewed by reviewers.

The Modular Open Source Identity Platform (MOSIP) effort started about 20 months ago as a response to the technology challenge identified by the ID community. MOSIP has launched the 1.1 version on Github and continues to improve the platform with fixes and enhancements. However, there are several additional important modules that need to be built to shape this open-source layer. The MOSIP team has curated a list of modules/ problems that would require the best minds in the technology world to take up and solve for.

To organize this effort to work with technology enthusiasts from around the world, the MOSIP team is proposing the Technology Contributors Coalition (TCC). The TCC is being set-up as a coalition of individuals and organizations who are keen on shaping the evolution of MOSIP. Organizations can encourage their resources to collaborate on specific projects by contributing code and documentation or second their resources to work full time with the MOSIP team.

TCC contributors will work closely with the MOSIP team on identified modules, features, or problems, or suggest new modules and enhancements to MOSIP. The key areas of contribution will include enhancements related to privacy, security, interoperability, service delivery, improved user experience etc. A suggested set of ideas for collaboration are appended below.

#1. Reporting Framework Mosip in its operation generates system data, seed data and transaction data along with audit logs. Reporting and analytics are required to monitor the operations of the system.

Use cases

• Collation of data from numerous sources like master tables, transactional data, audit logs, system health monitors.

• Creation of a live stream of data for real time analytics

• Creation of a data lake to store data for consumption by presentation tools

• Computation and storage of metrics on a periodic basis for trend analysis

• Mechanism to archive or purge data based on time

• Provide reports to support operations (some indicative reports are given below)

  • Report the number of new registrations carried out per day

  • Report the number of UIN update transactions

  • How many registrations happened per registration center on a given day

  • Report the number of UINs allocated age-wise and gender wise

  • How many registrations were approved and rejected end of day centerwise

  • Given a center, the list of registrations that were rejected along with the reasons for rejecting

  • Given a date or date range, list of registration packets that failed processing (for administrators)

  • Packet processing statistical report that includes

    • Number of new registrations, UIN updates, lost UIN, UIN updates via. Resident Services & Re-Prints done every day.

    • Number of packets stuck at processing state or failed for a specific date

#2. Registration App on a Tablet The registration services contain the required functionalities to capture and record demographic and biometric details of individuals. A native UI has been provided as a reference implementation for demo and customization. It is required to provide the same functionality on an iOS and Android tablets.

Use cases

• Use the inbuilt camera to capture photograph

• Work with peripherals for capture of other fingerprint and Iris

• Use MDS specifications for interacting with the devices to capture biometrics securely

#3. Resident Portal Resident portal offers residents to avail self-service features for managing their identity data, controlling and viewing usage of their identity. A set of REST API provided by MOSIP is available for the portal to use. A portal is required with a human-centric design.

Use cases

• Updating ID data

• Managing ID usage (Lock / Unlock)

• Generate virtual id

• View usage logs

• Merge pre-registration features into this portal

• CMS integration for country specific content to be presented

• Login, session management features

• Responsive UI that can work with mobiles and tablets

You can view the features for Resident Services here.

#4. Resident Portal App The resident self-service app offers the same set of features offered in the portal as an app on the phone or tablet. Refer to Problem 3 for use cases.

#5. Log Manager Log manager provides following functionalities:

• Create a logging system reference implementation with stacks such as elk, splunk, kafka etc.

• Logging features should support

  • Supports creation of logs without loss of data with log levels

  • Collates logs from across the application

  • Store generated logs in configured location

  • Manages log size, rotation segregation

  • Support for logger configurations

  • Support addition log level to a particular logger dynamically

• Indexing and searching of log to be supported

• Time based purging of log to be supported for different types of log data

These logs come handy for analyzing the system behavior and debugging. More details can be obtained from our Java Coding Standards.

We need a visual dashboard that would display the logs using tools like Kibana.

#6. Consent Framework MOSIP is a custodian of user’s identity data. A user consent framework is needed that allows users to wield varying degrees of control of different types of their data and their uses.

Consent is required from the user for the following:

• Verification of user identity by an external application

• Verification of user data (Know Your Customer)

• Sharing of user data (Know Your Customer)

• Seeding of authorized systems (Functional ID Linkage)

Consent can be obtained a-priori or instantly for different nature of transactions. Consent can be provided in multiple ways like:

• Authorizing a transaction with authentication (single or multi-factor) (Instant)

• Signing the request with a digital certificate (apriori)

• Providing an OTP (Instant)

• Sharing a generated pass-key (Instant)

• Using a challenge-response mechanism (Instant)

No action is taken without user’s continued consent and knowledge.

A data clearinghouse setup can be set up to facilitate the exchange of information between the functional system based on user consent. This will help keep user information current and relevant and avoid sharing of data via third-party agents or an unsecured procurement chain.

#7. Fraud Analytics The objective of a fraud management system is to ensure frauds in various stages are identified and prevented. Some examples of tagging for possibility of frauds are below.

• Fake supporting documents such as Proof of Identity, Address proof, age proof etc.

• Registration in the name of an individual who is dead

• Registration that happens outside the windows of working time of the registration centers

• Registering a child with invalid introducer (may be with using the operator’s identity)

• Pre-registrations done from outside the country are tagged for fraud analysis.

• Pre-registrations done from a single host many times may be tagged for fraud analysis.

• A registration operator is taking way more time than the standard time may be tagged for further analysis.

• A registration center has been decommissioned however there could be attempted registrations that eventually MOSIP denies, but the data would be useful for further analysis about the activities around the center.

• A registration operator has been disabled, but there could be attempted registrations that are denied by MOSIP, but the data would be useful for further analysis.

• Frequent registrations happening from one or more centers using manual adjudication process regularly could be a case of possible frauds.

#8. System Health Monitoring Users need to monitor the health of various services running on the MOSIP server to manage them efficiently. The foundational ID Systems needs to run 24x7 for long period of time.

Common health monitoring use cases are,

• Health of the services that includes services that are running and the ones that are down

• Requests pending in the queues that have not been clearly for a long time

• One or more services are not reachable since they are not running

• The server may be running but has crashed multiple times over a given period of time rendering the server unhealthy.

• The dependent servers/services such as ABIS, authentication servers, eKYC servers etc might be disconnected or not running and hence the server may not be able to fulfil requests completely.

• The server may be running at suboptimal performance

• Measure system metrics such as network utilization, disk utilization, CPU and memory utilization. The solution would require

• Providing health monitoring APIs using which one could create a health monitoring dashboard

• Providing alerts via SMS and emails.

• Providing mechanisms to register to one or more alerts

• All MOSIP services are embedded into various docker containers orchestrated by Kubernetes. Hence it is possible to measure the following

  • Kubernetes node utilization

  • Monitoring the running pods

  • Utilization of network, memory and CPU in individual pods

Tools sets that may be used could be,

• Heapster can be used to monitor Kubernetes clusters and collect metrics from it.

• InfluxdB can be used to store these collected metrics in time-series database

• Grafana or Prometheus to aggregate the collected information

#9. Homomorphic encryptions for offline validation An offline authentication mode is a powerful way to prove identity with very less traceability by a central system. We would like to avoid any card-based technology in performing such authentication as carrying and keeping its pin safe is specific to the culture of the country. The better model would be to print an ID card themselves (like QR code) who can then take it anywhere for validation without losing the privacy. One example use case is defined below.

• Login to the MOSIP from a internet connected computer.

• Perform a biometric/biographic authentication and receive the ekyc data.

• Print the data (VID + demographic + photo) encrypted with homomorphic in QR form.

• The data is digitally signed.

• Take it to a bank to open an account

• The person who carries the QR code print provides VID (one VID per QR) and demographic data.

• Bank validates if the homomorphic data contains the given information and the photo matches the person standing in front.

• If all is OK then the bank stores the entire QR Code and opens the account.

#10. Transparency of data integrity in custodian’s environment The initial adopters of MOSIP are developing nations with huge aspirations to go digital. While MOSIP plays a vital role in establishing a foundational digital id its essential that MOSIP brings transparency to the demographic and biometric data stored.

• We want to ensure that every individual’s record is updated only after his consent.

• A means of cryptography through which we could ensure that internal hackers cannot alter records and hide the evidence.

• A mechanism for MOSIP to auto-publish a hash (or something similar) which could be used to validate that the data has not tampered.

#11. False Finger/Iris/Face detection While biometric has proven to be unique it also suffers from attacks related to false fingers/non-live photos. It’s important to build a mechanism over which we can detect such fraudulent activities. While the device on the field would bring in liveness validation it would not be enough just to depend on that alone.

All our images are JPEG lossless, so it would be good to have a mechanism to identify false biometrics on the server.

#12. Advanced demographic storage One of the important services in MOSIP is to provide authentication - An online verification. MOSIP plans to federate this service across multiple players. We expect the residents to choose a service provider to whom MOSIP can share data.

MOSIP would like to share this data in an encrypted model where the authentication provider has no access to the original data but still be non-reputable, and is able to provide an online verification service.

Is it possible to use Homomorphic encryption in this case?

--

Please see the Contributor Guide on how to file bugs, contribute code, and more.

You can join the our developer mailing list to get more updates!

1 Introduction

1.1 Context

MOSIP is developed as an open source framework project. The code developed complies with the Java standards and best practices.

1.2 Purpose of this document

This document gives various RESTful webservice standards which have to be followed during the MOSIP development.

1.3 Scope of this document

This document covers the coding standards, which are followed by the RESTful webservice developers.

2 URL structure

2.1 General structure

The syntax of the URL of the RESTful webservice should be as follows for all the modules except Kernel,

https://<IP_ADDRESS>:<PORT>/<MODULE_NAME>/<VERSION>/<RESOURCE_NAME>/<PARAMETERS_AND_VALUES_IF_ANY>

For example,

https://mosip.io/pre-registration/v1/document

Only in case of Kernel modules, the <MODULE_NAME> is not included. The format is as follows,

https://<IP_ADDRESS>:<PORT>/<VERSION>/<RESOURCE_NAME>/<PARAMETERS_AND_VALUES_IF_ANY>

Following URL is an example for Kernel,

https://mosip.io/v1/emailnotifier

The convention is, before <RESOURCE_NAME>, we should have the version number.

The URL is the sentence, the resources are nouns and the HTTP methods are verbs. The URL, before the parameters, should contain only spinal case ( - ). The URL, before the parameters, should not contain snake case ( _ ) or camel case. NOTE: The parameters can contain snake case or camel case.

3 Resources - Usage of nouns and verbs

Use nouns for CRUD operations. Resource GET read POST create PUT update DELETE delete /preenrolments Returns list of pre enrolments Creates a new pre enrolment Bulk updates Delete all preenrolments /preenrolments/123 Returns a particular pre enrolment Updates a specific car Deletes a specific car

For operations, wherever applicable the operations can be added as part of the URL itself. For example, /getAllPreenrolments /createNewEnrolment /deleteAllPreenrolments

4 Resources – Usage of plurals in nouns

Use the plural nouns in the resource names if there is CRUD operations. For example,

https://mosip.io/pre-registration/v1/individuals  Prefer

https://mosip.io/pre-registration/v1/individual  Avoid

In other cases, use singulars in the nouns. For example,

https://mosip.io/pre-registration/v1/OTP

5 Resources – actions in the URL

The actions are added in the URL, wherever applicable. For example,

https://mosip.io/pre-registration/v1/OTP/generator

https://mosip.io/pre-registration/v1/OTP/validator

6 Appropriate usage of the HTTP methods

Use only the intended purpose of the HTTP methods. For example, do not use POST to update a resource or PUT to create a resource.

7 HTTP Status codes

In all the success cases and failure cases, 200 HTTP Status code is returned. Based on the "errors" JSON element in the response, the caller can decide whether the call is success or failure.

8 Identifying a resource

When the caller want to identify the resource, the path param is used. For example,

https://mosip.io/pre-registration/v1/individuals/id1234

9 Filtering

The filter has to be applied via the URL parameters. For example,

https://mosip.io/pre-registration/v1/individuals/id1234?city=someCityName&pincode=473822

10 Sorting

In case if the results have to be sorted, it can be mentioned in the URL parameter named sort. For example,

https://mosip.io/pre-registration/v1/individuals/1234?sort=firstName

11 Pagination

In case of pagination, the page number can be mentioned in the parameter by the name “page”. For example,

https://mosip.io/pre-registration/v1/individuals/1234?page=15

12 Always use SSL

Always use SSL for the services. No services should be exposed without SSL.

13 Versioning

Always version the service. The version have to be mentioned in the URL of the service after the hostname (and port number, if any). For example,

https://mosip.io/pre-registration/v1/individuals/1234 --> Except Kernel module

https://mosip.io/v1/individuals/1234 --> Kernel module

14 Design first approach

Always go with the design first approach. First, define the Swagger specification and publish to the Swagger UI after getting it reviewed. The coding should be started after the design is completed and the specification is completed in Swagger.

15 Request format

There are 3 sections in the Request.

15.1. Request headers: This will contain 3 mandatory fields. They are "id", "version" and "requesttime". The "requesttime" have to be in UTC standard ISO8601 format

15.2. Request meta data: This is an optional field. If the service is expecting any metadata, they can be passed here.

15.3. Request payload: This is an optional field. The request payload goes here.

For example,

Request:

16 Response format

There are 4 sections in the Response.

16.1. Response headers: This will contain 3 mandatory fields. They are "id", "version" and "requesttime". The "requesttime" have to be in UTC standard ISO8601 format

16.2. Response meta data: This is an optional field. If the service is expecting any metadata, they can be passed here.

16.3. Response payload: The response payload goes here.

16.4. Errors: The Errors array goes here. Even, in case of single error, the error have to be in an array. This is an optional field. In case if the service doesn't contains error, this element will not be there in the response.

For example,

Response:

In case, there is no request payload or path params or URL params, only the version will be present in the URL.

References

Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Examples of behaviour that contributes to creating a positive environment include:

• Using welcoming and inclusive language

• Being respectful of differing viewpoints and experiences

• Gracefully accepting constructive criticism

• Focusing on what is best for the community

• Showing empathy towards other community members

Examples of unacceptable behaviour by participants include:

• The use of sexualised language or imagery and unwelcome sexual attention or advances

• Trolling, insulting/derogatory comments, and personal or political attacks

• Public or private harassment

• Publishing others' private information, such as a physical or electronic address, without explicit permission

• Other conduct which could reasonably be considered inappropriate in a professional setting

Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behaviour and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behaviour.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviours that they deem inappropriate, threatening, offensive, or harmful.

Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported by contacting the project team at conduct@mosip.io. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.

Attribution

For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq

Guidelines to implement Authorization and Authentication techniques in the Angular application are detailed in this document.

Before going in to the components let us discuss the following flows of Authorization and Authentication.

Authentication flow:

1. Initially a login request is made passing user credentials to a REST API as specified in the SPECS of that API.

2. In the response of a successful authentication you will receive user details and an auth_token as the value of the header "Authorization".

3. Now the received auth token has to be stored and re-used. For example let us use sessionStorage to store the auth_token under the key "TOKEN".

4. Now any kind of HTTP/HTTPS requests we make from the application has to be sent by adding a header "Authorization" and value of auth_token stored in sessionStorage with key by name "Token" for the purpose of authentication.

5. If the response comes back with a new token which might be because of previous token getting expired or refresh token mechanisms that happen in the backend, we need to replace the old token with the new one in the session storage.

Authorization flow:

1. After successful login the user details are sent to the client(Angular application/ Browser).

2. Now store the userDetails in the sessionStorage for example under the key "UserDetails".

3. Now we need to hide some pages/components/user action elements etc. based on the roles that the user possess.

Implementation of above flows:

To implement the Authentication and Authorization flows mentioned above, all we need to do is implement an Interceptor and a Directive which were mentioned above and detailed below.

Http Interceptor

Tasks to be implemented in a Client/UI Http interceptor are:

1. Append "Authorization" header to the request using the token value stored in the session storage.

2. Replace/Add the session storage token value with the one received in the response "Authorization" headers.

Below code implements the requirements mentioned above:

Roles Directive

Role of the Roles directive is to fetch roles from UserDetails stored in the session storage and verify if the user has required roles to perform some action or read some details and restrict access accordingly.

Below code implements the requirements mentioned above:

Now inject the above interceptor and directive in the app.module.ts as follows

To activate/deactivate => show/hide element all we need to do is add the appRole attribute to the HTML element as shown below:

In the above sample, the add button will only be visible for users with DIVISION_ADMIN or SUPERVISOR role.

MOSIP - Java Development Coding Standard

Repository Structure

In MOSIP, the source code modules are categorized under different repositories:

• Commons - This contains common reusable library modules and service modules

  • Kernel - The collection of common reusable library modules and services

  • ID-Repo - The ID Repository services used by many of the MOSIP modules

• Feature Specific Modules (for example)

  • registration

  • registration-processor

  • pre-registration

  • id-authentication

If a new source code module is planned to be added, and if it is a reusable library / service on which other modules will be depending on, then it should be added under Commons, otherwise, it can be created as a separate repository.

Source Code Organization in a MOSIP Repository

Source code of any feature in MOSIP will be organized as below:

• feature-parent

• feature-core - jar

• feature-common - jar

• feature-service-1 - SpringBoot service

• feature-service-2 - SpringBoot service

Feature-Parent Module

This should be a POM module that aggregates all the sub-modules. This should contain,

• List of all sub-modules

• Common properties such as versions used by all sub-modules

• Common dependencies used by all of the sub-modules

• Common maven-plugins used by all sub modules

Feature-Core Java Library Module

There should be a JAR module that defines core source code files such as,

• APIs (Application Programming Interfaces)

• SPIs (Service Provider Interfaces)

• Common Utility classes

• Helper classes

• DTO classes

• Custom Exception classes

Common Implementation Module

• There can be a JAR module that provides abstract base implementations or common implementations of the APIs and SPIs. Other modules such as service module will be depending on this module using the API/SPI implementations or extending their base implementations.

• Any Service implementation class should have 'Impl' suffix.

Spring Boot Service Modules

• A feature can have one or more Spring Boot Service modules, each will have one or more related services.

• Each Spring Boot Service Modules will be deployed as a separate deployment unit such as a docker container. So each will contain the separate Dockerfile containing the docker build instructions for that module.

• Each Spring Boot Service Modules should be configured with Swagger configuration (except specific cases where) for easy understanding of the feature, easy unit-testing and verification for the developers.

• No Spring Boot Service module should be used as a dependency to any other module. Any such code dependency should be going inside the Common Implementation module.

Classes/Interfaces in MOSIP

• In MOSIP following naming of Class/Interfaces their names should be of Camel cases, without any underscore.

• They should have following suffixes in their names and they should be under appropriate package name based on their category,

  • XyzService - For a Service interface. A service class should not be annotated with @Service. This will be in the core-module. This will be under *.spi.xyz.service package.

  • XyzServiceImpl - For a Spring Service implementation class. This class should be annotated with @Service. This should not be defined in a core-module. It will be defined in a common or service module. This will be under *.spi.xyz.service.impl package.

  • XyzRequestDto - For a Request Data Transfer class in a Service. This will be in the core-module. This will be under *.xyz.dto package.

  • XyzResponseDto - For a Response Data Transfer class in a Service. This will be in the core-module. This will be under *.xyz.dto package.

  • XyzEntity or XyzDao- For an Entity/ Data Access class, which will use JPA annotations for the entity. This will be in the core-module. This will be under or *.xyz.entity or *.xyz.dao package.

  • XyzRepository - For a JPA Repository interface, which will be extending the base MOSIP Repository interface io.mosip.kernel.core.dataaccess.spi.repository.BaseRepository. This will be annotated with @Repository annotation. This will be under *.xyz.repository package.

  • XyzController - For a Spring Controller class, which will be annotated with @Controller annotation. This will be under *.xyz.controller package.

  • XyzConfiguration - For a Spring configuration, which will be annotated with @Configuration. This will be under *.xyz.config package.

  • XyzUtil or XyzUtils - For a utility class. This will expose public static utility methods. This will be under *.xyz.util package.

  • XyzHelper - For a helper class. This will be a Spring Component class annotated with @Component. This will expose public instance helper methods. This will be under *.xyz.helper package.

  • XyzManager - For any management class. Also for any class that will connect external module using REST service calls. This will be a Spring Component class annotated with @Component.

  • XyzConstants - For file storing constants. Please prefer to have a Constants file to define common and related constants used across the classes in a feature. This can be inside the core-module or common-module. This will be under *.xyz.constant package.

  • XyzException - For a custom exception, which will be extending io.mosip.kernel.core.exception.BaseCheckedException and io.mosip.kernel.core.exception.BaseUncheckedException. This will be defined in a core-module. This will be under *.xyz.exception package.

  • XyzExceptionHandler - For the centralized exception handler class in a service-module, annotated with @ControllerAdvice or @RestControllerAdvice annotation. This will be under *.xyz.exception package.

  • XyzFactory - For any class/interface defining Factory design pattern. This will be under *.xyz.factory package.

  • Xyzbuilder - For any class/interface defining Builder design pattern. This will be under *.xyz.builder package.

  • XyzFacade - For any class/interface defining Facade design pattern.

  • XyzImpl - For any implementation class that extends an API/SPI interface.

• A service implementation should be always with a combination of Service Interface and its Spring Service Implementation Class. It should not be without a Service Interface defined in core-module.

• Any Spring Component will be annotated with @Component. A component may or may not be implementing an interface.

• Any dependency injection of a Spring Service should only to be assigned to a variable of its Service Interface type but not to its Implementation class type.

• For dependency injection of a Spring Component should be assigned to a variable its Interface type if any, otherwise to the class type.

Using Lombok for Data classes

• All data classes such as DTOs, Entity classes use Lombok annotations to automatically create appropriate constructors, getters and setters.

• Make sure to setup the IDE used for the development for using Lombok.

MOSIP JPA Repository

• Any JPA repository created in MOSIP should be extending the base MOSIP Repository interface io.mosip.kernel.core.dataaccess.spi.repository.BaseRepository.

• Appropriate database configurations properties should be added to the app configuration file.

Commons/Kernel - MOSIP Common Libraries/Services

• MOSIP has many common libraries and services implemented under Commons/Kernel repository.

• Kernel-Core module contains may common utility classes such as Loggers, DateUtils, StringUtils and Crypto-Core etc… Also many utility services such as Kernel-KeyManager, Kernel-CryptoService, Kernel-Audit-Service, Kernel-Auth-Service, etc... .

• If any common utility needs to be implemented, first check Commons/Kernel if such utility is already present and make sure it is not already implemented in Commons/Kernel. It is always welcomed to contribute any new features/ bug fixes for the existing utilities, instead of creating a new utility.

REST Services Request and Response:

• Any request and response content in a service in MOSIP should be of application/json content type.

• Any byte arrays to be returned in response should be Base-64-URL encoded within the response.

• If any sensitive information is getting transferred in the request/response, the request/response block should be encrypted using the MOSIP public key.

• Any service in MOSIP should never return error code other than 200. One or more errors to be reported in the response be returned as an array as part of "errors" attribute.

• Each of the "error" attribute should under "errors" should have "errorCode", "errorMessage" and an optional "actionMessage". * For any service, possible "errorCode", "errorMessage" and the optional "actionMessage" should be properly listed documented in its API specification.

• Any request/response body should have proper meta-data such as "id, "version" and "requestTime"/"responseTime", etc... .

For example:

Java Coding Standard

Number of lines

The number of lines in the Java files is restricted to 2000 lines. Beyond 2000 lines, the java file is refactored into multiple files.

Class and Interface

Each java file contains one public class or interface.

When some private classes and interfaces are associated, this can be in the same file.

Declare the public class and interface as the first declaration in the file.

Ordering

When a java file is written, the following order is maintained,

Beginning documentation comment

The beginning comment should be in a C-style comment. Following is the format of the comment.

Package statement

The first non-comment line is the package statement.

Import statement

• After a line-break below the package statement, import statements are placed. The import statements are grouped and segregated by a line-break. For example,

• Do not use asterisk symbol while importing packages.

Class or Interface comment for documentation

This comment will be going in to the Javadocs

Public class or interface definition

• Then the public class or interface is defined.

Other related private class or Interface definition

• Then other private class or interface are followed.

Inside a class or interface

Following is the order of elements inside the class declaration

Constant fields

Constant fields (static and final fields) should be on the top inside a Class

Non-final static fields

Then any non-final static fields are followed

Instance variables

The public class variables are followed by the protected and the private variables. These can be final or non-final fields.

Initializing Fields in a class

• Do not initialize non-primitive fields with null in a Class;

• Always initialize non-static fields from constructors in a Class.

• Avoid using static non-final fields in a class. If it required for any specific reason, avoid initializing it in a constructor or a post-construct method.

• Avoid using static initializers to initialize static final/non-final fields, instead create private static methods and call it for initializing static fields.

Constructors

The constructor declarations ordered by the number of parameters.

Method declarations

The methods are ordered by the functionality. The methods need not to be in the order of scope or accessibility.

Indentation

The indentation unit it TAB.

Line length

The number of characters in a line should not exceed 80 characters

Wrapping lines

When the number of characters exceed the limit, the line should be broken into multiple lines. The following standard is used during the line breaks,

• Break the line after the comma

• Break before the operator

• From higher-level breaks go to the lower-level breaks.

• Align the new line with the beginning of the expression at the same level on the previous line.

Comments

There are two types of comments in Java.

1. Implementation comments

2. Documentation comments

Both the comment types are used in the source code of MOSIP.

Implementation Comment

• This is the comment type used for better understanding of the code. Most of the times, the source code will be maintained by different people. The programmer writes these comments so that the other programmers will come to know the functionality of the code in plain English language. Following lines are used.

• Java source code can have their implementation comments in various parts of code blocks/lines with appropriate description about what the code block or line is doing.

• Specifically the if-else if-else conditions can have their descriptions about their various conditional expressions.

• Any complex piece of code such as a regular expression / mathematical expression can be described with appropriate descriptions about it.

Block Comments

When the developer needs to explain in detail about some functionality, block comments are used. Block comments are used anywhere in the code. It can be for the class or interface declarations or it can be within the java methods also. Example of block comments:

Single-Line Comments

Single line comments are used for short description. For example,

Trailing Comments

Trailing comments are given in the same line where the source code resides. For example,

End-Of-Line comments

The end-of-line comments are also used in the source file. For example,

Documentation comments

• Documentation comments are used to generate the javadoc files.

• Every source code file in Java should have proper Java Documentation such as description, Author and Version.

• All Classes, Interfaces, Methods, Fields should have appropriate clear description about each.

• A method documentation should have description about all parameters, exceptions thrown and return value.

• Documentation comments can be of two kinds:

  • Single line documentation comment: /** COMMENT */

  • Multi-line documentation comment:

Example:

Declarations

Number of variables per line

One variable is declared per line.

Placement of variables

Variables are declared at the beginning of the code block. For example,

Class and Interface Declarations

• No space between a method name and the parenthesis "(" starting its parameter list

• Open brace "{" appears at the end of the same line as the declaration statement

• Closing brace "}" starts a line by itself indented to match its corresponding opening statement,

• Except when it is a null statement the "}" should appear immediately after the "{"

• An empty line is there in between the method declarations.

Methods

• A method should follow the "Single Responsibility" principle that will perform only one task. If it seems to do multiple sub-tasks, each sub-tasks should be created as a new method and then be invoked in that method.

• If there is a logic even of a single line getting repeated in more than one place, it should be made as a separate method.

• A method line count should not exceed 80 lines. If required break the blocks of code in the method to separate methods.

• Methods are separated by a blank line.

Method Parameters

1. Never re-assign a parameter value. This may lead to unpredictable bugs.

2. Don't use too many number of parameters. Keep the maximum number of method parameters to 5 for simplicity.

3. Prefer method parameter type to be more generic such as a Super Interface or Super Class. For example, List instead of ArrayList.

Method Return Statement

1. Never return null for an Array return type. Return an empty array of 0 like return new String[0].

2. Never return null for a Set/List/Map collection return types. Return corresponding empty values such as Collections.emptySet(), Collections.emptyList() or Collections.emptyMap();

3. Prefer method return type to be more generic such as a Super Interface or Super Class. For example, List instead of ArrayList.

4. Avoid having multiple return statements in a method. Prefer to provide a single point of exit to a method. For example:
5. Use Optional return type to avoid null checking. When there is possible to return null for a method, return Optional.empty().

6. Use OptionalInt, OptionalLong return types for a method when there is an unknown value of Integer/Long to be returned like -1;

Statements

Simple Statements

Each line should contain at most one statement. Example:

Compound Statements

• Compound statements are statements that contain lists of statements enclosed in braces
• The enclosed statements should be indented one more level than the compound statement.

• The opening brace should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement.

• Braces are used around all statements, even single statements, when they are part of a control structure, such as an if-else or for statement. This makes it easier to add statements without accidentally introducing bugs due to forgetting to add braces. For example:

"return" Statements

• A return statement with a value should not use parentheses unless they make the return value more obvious in some way. Example:

if, if-else, if-else if-else Statements

• Always curly braces are used in the if-else statements. Even though there is a single statement below the if-else statement, curly braces is used. For example,
• If there is a Boolean value to be returned in a method or assigned to a variable based on an if-else condition, the condition itself should be returned or assigned instead of true or false for the condition. For example,
• Prefer "switch" statement when possible over having multiple “if-else if-else if-else” statements.

Conditional Expressions

• If any binary operator is used before "?" in the ternary operator, then parentheses is used.

• Prefer if-else statement over conditional expressions if it gets complex with the condition or the statements.

• Avoid using nested conditional expressions for better readability.

"switch" Statements

• A switch statement should have the following form:

• Every time a case falls through (doesn't include a break statement), add a comment where the break statement would normally be. This is shown in the preceding code example with the /* falls through */ comment.

• Every switch statement should include a default case. The break in the default case is redundant, but it prevents a fall-through error if later another case is added.

White Space

Blank Lines

Only for the following situations 2 blank lines are used,

1. Between 2 different sections of the source file

2. If you have more than one class or interface, use 2 blank lines

Only for the following situations, 1 blank line is used,

1. Between method declarations.

2. Between the variable declarations and the method code.

3. Before the block comment or line comment.

4. To provide a better readability in between logical blocks, an empty line are used, wherever applicable.

Blank Spaces

Under the following circumstances, blank space are used,

1. When a keyword followed by parenthesis, a blank space should be given after the keyword. For example,

1. In the argument list, the parameters are given a space after comma.

Naming Conventions

Package names

Classes

Interfaces

Methods

The method names are always verbs and in camel case. For example

Variables

The variable names are short and meaningful. Any new observer can understand the meaning of the variable. No single letter variable names are used. Camel case is used when declaring variables.

Constants

• The constants are given the name in capital letters. The words in the names are separated by underscore.

• String literals should not be used in the code directly. Declare them as constant in the class.

• Magic Numbers should not be used in code, they should be declared as constants.

• Create XyzConstants class to group related and reused constants within a module/feature.

Programming Practices

Providing Access to Instance and Class Variables

• The instance variables should not be made public unless you have a specific reason.

• Provide the most restrictive access to the fields, methods and Inner Classes such as private, default or protected. Avoid giving public access to them unless it is really required. Avoid using public non-final fields in a Class.

Referring to Class Variables and Methods

Always use the class name to call the static method. For example,

Constants

Numerical values should not be used in the code directly. Declare them and use it in the code. For example,

Variable Assignments

• Avoid multiple assignments in the same line. For example,

• Prefer primitive type variables over boxed types wherever possible. For example, prefer int, boolean and long over their Boxed counterparts such as Integer, Boolean and Long.

• Prefer variable type to be more generic such as a Super Interface or Super Class. For example, List instead of ArrayList.

Optional

• Use Optional return type in a method to avoid null checking. When there is possible to return null for a method, return Optional.empty().

• Use OptionalInt or OptionalLong return type in a method when there is an unknown value of Integer/Long to be returned like -1;

• Avoid getting value from Optional using Optional.get() without checking for Optional.isPresent() condition, otherwise use Optional.orElse() .

• Use primitive optional classes such as OptionalInt or OptionalLong over Optional<Integer> or Optional<Long>.

Lambdas

Lambda Expressions

• Prefer Method Reference over a Lambda Expression

• Keep Lambda Expressions Short and Self-explanatory so that it is easy to understand. . Provide clear understandable name to the parameters in Lambda Expressions.

• Always use parameter type inference. For example,
• Do not use the parenthesis for a single parameter lambda expression.
• Use “Effectively Final” Variables in Lambda Expressions. It is not required to mark every target variable as final.

• Avoid mutating Object Variables in Lambda Expression.

• Avoid using the block lambdas wherever an expression lambda are used. For example:

Functional Interfaces

• Prefer Standard Functional Interfaces over creating a similar one unless it is really required. Use Standard Functional interfaces, which are gathered in the java.util.function package, satisfy most developers' needs in providing target types for lambda expressions and method references.

• On a new Functional Interface declaration always use @FunctionalInterface annotation. This is not only for the documentation purpose but also to avoid accidentally breaking the Functional Interface behavior.

• Instantiate Functional Interfaces with Lambda Expressions instead of creating anonymous inner class instances for that.

• Whenever calling the functional interface, place them at last in the parameter list.

For example:

Streams

• Prefer Streams over for loops. Streams are more readable and functional than the "for" loops, as they support operations such as map, flatMap, filter, reduce and collect.

• Exception handling in the streams are carefully handled.

• Avoid mutating objects within Collection.forEach() or Stream.forEach(), use Stream.collect() instead. For example use Stream.collect(Collectors.toList()) instead of mutating a list for collecting elements to a list.

• Use parallel streams where ever possible to boost performance, whenever it does not involve sort/order/limit intermediate operations.

Exceptions

MOSIP applications should never allow to exit abruptly because of a critical error. Even if there is a critical error there should be a graceful exit with proper information about the error.

Exception hierarchy

• Each feature should be defining their own Checked and Unchecked Exceptions by extending io.mosip.kernel.core.exception.BaseCheckedException and io.mosip.kernel.core.exception.BaseUncheckedException .

• • The Checked and Unchecked exceptions should be used appropriately as needed. Make sure which one to use when based on the exception handling requirement.

Throwing exceptions

Throw specific exceptions in a method, rather than generic exceptions. For example,

Documenting exceptions

The exceptions are documented clearly. For example,

Catching exceptions

• Always prefer to use try-with-resource block when applicable like instantiating a Input or Output stream/reader or Connection, which are AutoCloseable.

• The following example uses a try-with-resources statement to automatically close a java.sql.Statement object:

• A try-with-resources statement can have catch and finally blocks just like an ordinary try statement.

• Always catch specific exceptions over a more generic exceptions like Exception/Throwable class. For example,

• Never leave a catch block empty. Either handle the exception, or say proper reason for doing nothing in it.

• Use multi-catch blocks wherever possible to club common handling of multiple exceptions.

• Always log exceptions to file in a catch block for debugging purpose.

• Error and Throwable are never caught in MOSIP.

Exception handling in a Service module

• Any service module should handle their exceptions in a common place such as a common Exception Handler which can be annotated with @ControllerAdvice or @RestControllerAdvice

• Any service in MOSIP should never return error code other than 200. One or more errors to be reported in the response be returned as an array as part of "errors" attribute.

Logs

Log levels

Logs are classified and logged accordingly. Following are the various log levels used in the MOSIP application.

1. TRACE

2. DEBUG

3. INFO

4. WARN

5. ERROR

The log levels are configured according to the environment such as Development, Testing, UAT or Production. For example, the log levels in production is from WARN. Whereas in Development and Testing environment, it is from TRACE.

MOSIP log component

MOSIP's log component from the core-kernel is used to log entries. The log module in the core-kernel is used to log all the log entries.

• First create a logger utility class under the core module of the feature like below:

• To log any information/error/debug in a class,

  • create a logger instance in that class as below: private static Logger mosipLogger = XYZLogger.getLogger(MyClass.class);

  • In appropriate places invoke the appropriate log method of mosipLogger such as error, debug or info with appropriate parameters passed to it.

MOSIP log format

Every log entry contains the following format,

For example,

No sensitive information is logged

• Never log any sensitive information such as user credentials, individual identity information to the log, mask the data if required before logging.

• Care should be taken, not to log any sensitive information is logged. Modules leads to review the code to ensure that no sensitive information is logged.

Audit Logging in MOSIP

• Any service in MOSIP should invoke Kernel's AuditManager REST Service for audit logging of the status of the services such as

  • Success

  • Failure

  • Exception occurred - the error codes and error messages.

• Define the appropriate Audit Modules and Audit Events for any feature and use pass them appropriately in the Audit Parameters while invoking the Audit REST service.

• Make sure to invoke the Audit REST service Asynchronously to prevent any time lagging in response because of the Audit REST service call.

Common utilities

Apache Commons is used to handle the common utilities like StringUtil, FileUtil, Hashcode, toString, null check etc., are

In case if Apache Commons doesn't have the necessary utilities, the util project from mosip-core is used.

Miscellaneous Practices

Following are the miscellaneous practices which are followed in MOSIP.

Parenthesis

Parenthesis are used in the code liberally to improve the readability and for precedence clarity.

Type Casting

• Never type cast a variable without doing instanceof checking.

• Avoid unnecessary type casting when the type of the value/expression is already assigned to a correct variable type/return type.

Generics

• Avoid using Generic classes without Parameter types. For example:

• Use diamond operator while constructing Generic objects. For example:

Method Calls Chaining

• While chaining multiple method calls, keep one method call per line for better clarity and easy debugging of any issue (especially to get line number in exception stack trace where exactly is the error/exception occurs). For example:

Special Comments

• Special comments are used to give a hint for further development. Following are the special comments used in the MOSIP project,

  • TODO

  • FIXME

  • NOTE

  • OPTIMIZE

• It should be made sure to track the above comments, perform action accordingly, and remove them when they become irrelevant.

References

Where to start?

• Refer to '' for a comprehensive overview of foundational ID systems and MOSIP.

• Get to know the

• Get to know the

• If you do not have a GitHub account, create one .

• Deploy and try MOSIP using the .

• The has some basic ethics that must while operating within the MOSIP community. Make sure you read it completely. If you have any queries/suggestions, direct them to .

• If you are a developer willing to contribute to MOSIP, take a look at .

Congratulations! You've successfully bootstrapped yourself into the world of MOSIP. Welcome aboard!

Areas of contribution?

Curious about where you can contribute? There are plenty of ways to get involved with MOSIP :

Requirements and Design

• Share new requirements and ideas

• Review and provide feedback on design and architecture

Coding

• Fix issues and enhance features

• Review code contributions

• Triage and resolve bugs

Testing

• Run tests on unstable builds

• Create and add new tests

• Fix test scripts and generate test data

Documentation

• Correct and improve documentation

• Test documentation and report any issues

• Fix documentation issues

• Localize documents (French, Arabic, and Spanish are currently in high demand!)

Ready to fix an issue?

Found an Issue or Have an Enhancement Request?

Running and enhancing tests

Getting in touch

We're here to assist you every step of the way!

This document lists out the instructions on how to use the in a Spring Boot application.

• Step 1:

• Step 2:

• Step 3:

Inject required libraries

• Add the Auth Adapter module to your project as a maven dependency

• Add ComponentScan annotation as shown below to your project. This is to create auth adapter bean.

Attach annotations to authorize endpoints

To restrict access to your endpoints, you need to add the @PreAuthorize annotation. Look at the below example for reference.

Note: Now we support only hasRole and hasAnyRole methods.

Use restTemplate for Http calls

To make any kind of HTTP or HTTPS calls to a mosip's micro service that also injected the Auth Adapter, use the standard RestTemplate capabilities as shown below.

• Intially autowire the RestTemplate in the class where you are going to make an API call.

• Now make the call using the autowired restTemplate as shown in the sample below:

Note: Do not create a new instance of the RestTemplate instead use the autowired one.

1. Introduction

1.1 Overview

The MOSIP architecture mainly consists of the following functional blocks/modules

• Pre-Registration - Web application designed in Angular JS A resident can provide his demographic details in this web application and book an appointment for his future registration at a registration center

• Registration Client - A Desktop thick client application developed in JavaFX. A resident is registered through the Registration Client software to generate get a unique identification number. The software captures demographic and biometrics information of the residents. It is connected to scanner devices (finger print, iris), camera and printer to capture resident biometrics information

• Registration Processor - A back-end server application developed using SEDA framework It processes the client packets and generates UIN based on de-dupuplication information from ABIS (Automated Biometrics Identification System)

• IDA (ID Authentication) - A back-end authentication server developed using spring family. It authenticates the resident based on registered set of biometric and demographic information

Test automation is the key to the success of comprehensive test coverage and test data. However in the context of MOSIP testing, where there are external devices and integration with third party software, test automation cannot be exhaustive and comprehensive test coverage can be achieved by testing driven by manual intervention, along with test automation.

In this document we will also talk about utilities for test data generation, tools for test automation and test strategy in general.

1.2 Scope

1.2.1 Test Coverage

• Each of the modules has the following building blocks which are the testable entities, at the module level

• System Integration Testing - This involves testing functional work-flows across the modules, starting from Pre-Reg and ending in IDA

• Test Automation - tools, approach, test code configuration management process, regular usage

1.2.2 Data Coverage

Data utility tools - approach, usage

2. Test Approach

Each module is tested, both manually and through automation software for effective test coverage.

A progressively evolving test approach is being adopted in both cases.

1. Manual Testing starts with module level functional coverage followed by --> integration across modules --> End to end workflow testing

2. Automation Testing starts with the fundamental building blocks like APIs, and grows up the stack.

Individual API verification is followed by --> API Integration testing --> integration across modules --> End to end workflow testing

4. Test Automation User Guides

4.1 Kernel Test Automation Suite - User Guide

4.1.1 About the Kernel Module

A critical interface module of MOSIP, Kernel is the core package on which MOSIP services are built upon and is a platform, which provides higher-level services and functions that shall be reused by other modules of MOSIP.

Kernel provides a foundation to build and run the services by providing several significant necessary technical functions. Kernel makes it easy to build the higher-level services (domain services, batch services and core services) by taking care of fundamental features so that individual services are concerned with specific business functions. Kernel provides an active framework that ensures structure and rules within which the higher-level services operate.

Kernel automation works with Restful and Java API’s.

The test execution module of the Kernel module involving API’s is as depicted below

4.1.2 Pre-requisites for understanding Java API automation

• Knowledge on Java 8

• Basic knowledge on Rest assured tool

• Knowledge on Maven

• Knowledge on TestNg framework

• Knowledge on GitHub

• Good analytical and debugging skill

4.1.3 Procedure to check out the test code from the repository

• Create a workspace in the local system

• Open git bash in the workspace

• Enter the command :- git clone https://github.com/mosip/mosip-functional-tests.git

• MOSIP project shall be cloned

• Import the “automationtests” project into the eclipse.

4.1.4 Pre-configuration information prior to test run

None

4.1.5 Procedure to Add new test cases into the API test suite

1. From the automationtests project, the test suites and cases can be located in the folder [src/main/resources]

2. Every API tests structure (model, api name and test case) are stored in a folder/sub-folder approach. Let us take an example of “Email Notification service” and explain how to add a new test

1. Every test case will have 2 json files named [request.json and response.json] in its sub-folder as shown below

1. In the request.json file, we need to mention the input that needs to be send to the API and response.json file contains the expected result for that particular input.

Based on the test cases, we need to add the test case folders with request and response files.

The readTestCases method from TestCaseReader class will read the folder names and give the test case names and readRequestResponseJson method from TestCaseReader class will read the request and response files from the tests.

4.1.6 Procedure to execute or Run the tests on a new environment

• To run the automation suite of Kernel you will need an xml file named [testngKernel.xml], which will be available under [src/main/resources].

• Add what are the test need to run in that xml file.

• Add the path of the xml file in pom.xml file under maven surefire plugin.

4.1.7 Running a test suite

1. Right click project

2. Select “Run as configuration”

3. Under configuration select Maven build and create new maven build

4. Select current project as workspace

5. Pass the below commands in the Goals:

   Command: clean install -Denv.user= <required environment> -Denv.endpoint=<application URL> -Denv.testLevel=<test level>

   where,

   • Required Environment- In which environment the suite needs to run. (Ex: qa, dev, int)

   • Test Level- Type of tests like (Ex: smoke, regression, smokeAndRegression)

1. Select or Click the button “RUN”

2. Once the execution is completed, Test report will be generated in target/surefire-reports folder with the name MOSIP_ModuleLevelAutoRun_TestNGReport.html

4.1.8 Analyze the test reports

1. Open the report in Internet Explorer

2. The report will give the module name, total number of test case execution with pass, skipped and fail count

3. Report will provide the build version and also execution time

4. Report will show API name and corresponding test case names with execution time

5. For failed test cases, it will show the cause of failure

4.2 Pre-Registration Test Automation Suite - User Guide

4.2.1 About the Pre-Registration Module

This is the web channel of MOSIP, which facilitates capturing individual information, relevant documents and booking an appointment with a registration center. This helps to reduce registration time and optimize the process. The current web application is highly modular by design and with multi language support. This UI can be customized or modified as per the country's requirements. A country can also build a new web/mobile application on top of the back end services that MOSIP provides.

4.2.2 Pre-requisites for understanding Java API automation

• Knowledge on Java 8

• Knowledge on Rest services

• Knowledge on maven

• Good analytical and debugging skill

4.2.3 Procedure to checkout-out the test code from the repository

• Navigate to git repository.

• Copy URI

• Open Git Bash

• Clone repository(git clone “URI”)

4.2.4 Pre-configuration information prior to test run

None

4.2.5 Procedure to Add new test cases into the API test suite

1. From the code repository of the module, the test suites and cases can be located in the folder [src/main/resources]

3. To add new test case we need to create a folder inside test suite folder. You can give folder name same as test case name

5. In the Create_PreRegistartionRequest.json file, we need to mention all folder name(Test Case Name). When we run any class, then it will pick request body from folder and it will pick expected response. We will take request body, as input and it will give response (Actual Response). For Validation, we are doing JSON to JSON comparison.

6. In Pre-Registration module, we have created on class called PreRegistrationLibrary, which is present in io.mosip.util package. In this class, we have created all reusable method, which is used, in Pre-Registration module.

4.2.6 Procedure to execute or Run the tests on a new environment

To run the automation suite of Pre-Registration module you will need an xml file named [Pre-Registration_TestNG.xml], which will be available under [src/main/resources]. In this xml file we need to add class name which we want to run.

4.2.7 Running a test suite

Procedure to execute the [Reg-automation-service_TestNG.xml] xml File:

• Right click the xml file Pre-Registration_TestNG.xml

• Select “Run as configuration”

• Run as Maven

• Select workspace(${workspace_loc:/automationtests})

Here,

• Denv.user indicates environment name.

• Denv.endpoint indicates base URI

• Denv.testLevel indicates types of test case we want to run

• Select or Click the button “RUN”

• Test Suites execution will commence.

• Test report will be stored in [surefire-report] folder under the base directory/project

4.2.8 Running a single test case

• Right click on class, which you want to run.

• Click on run as

• Click on testing

• Select class

• In VM argument pass -Denv.user=qa -Denv.endpoint="eg:https://testenvname.mosip.io" -Denv.testLevel=smokeAndRegression

4.2.9 Analyze the test reports

• Once run is complete, then refresh project and go to target/surefire folder.

• Open MOSIP_ModuleLevelAutoRun_TestNGReport.html report.

• To analyze failure test case check exception message.

4.3 Registration Client Test Automation Suite - User Guide

4.3.1 About the Registration Client Module

An important client interface module of MOSIP, which captures the Biometric and Demographic information of the Individual resident. This module also stores supporting information such as proof documents and information about the guardian or introducer as per the configuration set by the Admin. The packet creation is finished in this module in a secure way using sophisticated encryption algorithm and later send to the server for online mode of processing. The registration client test suites comprises of tests related to UI and Java API’s.

The test execution module of the Registration client module involving Java API’s is as depicted below

4.3.2 Pre-requisites for understanding Java API automation

• Knowledge on Java 8

• Basic knowledge on Spring services and should know annotations

• Knowledge on maven

• Good analytical and debugging skill

4.3.3 Procedure to check out the test code from the repository

Instruction to checkout code from GitHub using Eclipse.

• Open eclipse

• Go to quick access and search “clone git”

4.3.4 Pre-configuration information prior to test run

None

4.3.5 Procedure to Add new test cases into the API test suite

• From the code repository of the module, the test suites and cases can be located in the folder [src/test/resources]

Based on values set inside the condition.properties file test cases will fetch the data from yaml file and then call a data generator code internally which shall add meaningful right or incorrect values as test data into these variables. More information on the Yaml file can be found under appendix

4.3.6 Procedure to execute or Run the tests on a new environment

To run the automation suite of Registration Client module you will need an xml file named [Reg-automation-service_TestNG.xml], which will be available under [src/test/resources].

4.3.7 Running a test suite

Procedure to execute the [Reg-automation-service_TestNG.xml] xml File:

1. Right click the xml file Reg-automation-service_TestNG.xml

2. Select “Run as configuration”

3. Under configuration select [TestNG] and pass the VM argument as
4. Select or Click the button “RUN” Test Suites execution will commence.

5. Test report will be stored in [test-output] folder under the base directory/project

4.3.8 Appendix

1. Java API

Java application programming interface (API) is a list of all classes that are part of the Java development kit (JDK). An application-programming interface (API), in the context of Java, is a collection of prewritten packages, classes, and interfaces with their respective methods, fields and constructors.

2. Yaml master data file

3. How to increase the data coverage inside Yaml file?

To increase the data coverage we can add as many as test data’s into the Yaml file

4. Any dependencies of values in the Database

None

4.4 Registration Processor Test Automation Suite - User Guide

4.4.1 About The Registration Processor Module

Registration Processor processes the data (demographic and biometric) of an Individual for quality and uniqueness and then issues a Unique Identification Number (UIN). The source of data are primarily from

• MOSIP Registration Client

• Existing ID system(s) of a country

4.4.2 Pre-requisites for understanding Rest API automation

• Knowledge on Core Java

• Basic knowledge on Rest assured library

• Knowledge on Maven

• Knowledge on TestNg framework

• Knowledge on Keyword, Data Driven and Hybrid methodology

• Knowledge on GitHub

• Good analytical and debugging skill

4.4.3 Procedure to checkout-out the test code from the repository

• Launch eclipse with new or existing workspace

• Import the automationtests project into the eclipse.

4.4.4 Procedure to Add new test cases into the API test suite

Case 1: For API Level Testing

1. From the automationtests project, the testdata can be located in the folder [src/main/resources]

Case 2: For Stage Level Testing

1. From the automationtests project, the testdata can be located in the folder [src/main/resources]

4. The reg proc automation suite will tweak the values in a valid packet and will generate packets for the above attributes sequentially.

5. There is one more file “StageBits.properties” which has a stage string. The string is used to construct the status string for a packet. For eg if stage string is “111110000” it means that packet should go through first five stage and should fail for last 4 stages.

4.4.5 Procedure to execute or Run the tests on a new environment

1. To run the automation suite of Reg-Proc, build the project and get the uber jar generated under target.

2. Run the jar using the command line “java -Denv.user= -Denv.endpoint= -Denv.testLevel= -jar ”

   Example: java -Denv.user=qa -Denv.endpoint="eg:https://testenvname.mosip.io" -Denv.testLevel=smokeandregression -jar automationtests-refactor-0.9.1-jar-with-dependencies.jar

   Note: env = qa,dev,int | testLevel=smoke,regression,smokeandregression

3. Report will be generated under “< workspace >/testing-report.

4.4.6 Analyze the test reports

1. Report can be opened in any Web browser (i.e. Internet Explorer)

2. The report will consist of module name, total number of test case executed with status as either pass, skipped and fail and their count.

3. Report will also display API name and corresponding test case names with execution time along with build version and execution time.

4. For detailed analysis, refer logs or default testing-report and for failed test cases, the related cause of failure will be highlighted.

4.5 ID Authentication (IDA) Test Automation Suite - User Guide

4.5.1 About the ID-Authentication

MOSIP ID Authentication provides an API based authentication mechanism for entities to validate Individuals. ID Authentication is the primary mode for entities to validate an Individual before providing any service.

4.5.2 Pre-requisites for understanding Rest API automation

• Knowledge on Core Java

• Basic knowledge on Rest assured library

• Knowledge on Maven

• Knowledge on TestNg framework

• Knowledge on Keyword, Data Driven and Hybrid methodology

• Knowledge on GitHub

• Good analytical and debugging skill

4.5.3 Procedure to checkout-out the test code from the repository

• Launch eclipse with new or existing workspace

• Import the automationtests project into the eclipse.

4.5.4 Procedure to Add new test cases into the API test suite

1. From the automationtests project, the testdata can be located in the folder [src/main/resources]

3. Pre-requisites: open runConfiguration.properties file

   Add the following two lines which represents your test case; one for the folder location and another on the test data as below, the array [X], where “X” represents the number of times this tests shall be repeated with different test data

   An example: DemographicAuthentication.testDataPath[6]=ida/TestData/Demo/Name/

   DemographicAuthentication.testDataFileName[6]=testdata.ida.Demo.Name.mapping.yml

   If you want to remove a test, kindly comment the relevant line in this file before the execution of TestNG runner class

5. Please use the TestData keyword defined under in appendix for creating your request.json file. The provided keywords are sufficient for testing the ID Authentication module, however If you ever need you can add an additional attribute to the end of this list

Sample structure of the request.JSON file, which is being created at run time using the attributes defined in the TestData, which reads from the Yaml data file:

4.5.5 Procedure to execute or Run the tests on a new environment

1. To run the automation suite of ID-Authentication, build the project and get the uber jar generated under target.

2. Run the jar using the command line “java -Denv.user= -Denv.endpoint= -Denv.testLevel= -jar ”

   Example: java -Denv.user=qa -Denv.endpoint="eg:https://testenvname.mosip.io" -Denv.testLevel=smokeandregression -jar automationtests-refactor-0.9.1-jar-with-dependencies.jar

   Note: env = qa,dev,int | testLevel=smoke,regression,smokeandregression

3. Report will be generated under “/testing-report

4.5.6 Analyze the test reports

1. Report can be opened in any Web browser (i.e. Internet Explorer)

2. The report will consist of module name, total number of test case executed with status as either pass, skipped and fail and their count.

3. Report will also display API name and corresponding test case names with execution time along with build version and execution time.

4. For detailed analysis, refer logs or default testing-report and for failed test cases, the related cause of failure will be highlighted.

4.5.7 Annexure

Yaml Test Data Format:

The sample structure should be like below:

TestData Keyword repository:

4.6 E2E Test Automation Suite - User Guide

4.6.1 About The End To End Test Rig

End to end system level Test Rig covers the functionality across the modules starting with Pre-Registration and ending in Registration Processor or IDA.

The below diagram depicts the overall design of the end to end suite.

4.6.2 Pre Requisite To Understand The Flow Of E2E Test Rig

• Knowledge on Core Java

• Basic knowledge on Rest assured library

• Knowledge on Maven

• Knowledge on TestNg framework

• Knowledge on Keyword, Data Driven and Hybrid methodology

• Knowledge on GitHub

• Good analytical and debugging skill

4.6.3 Procedure to checkout-out the test code from the repository

• Launch eclipse with new or existing workspace

• Import the e2etestrig project into the eclipse.

4.6.4 Basic Code Structure Of The E2E Rig

1. The E2E rig is a basic parent child maven project

2. It contains 5 child project which are as follows:

   • Pre Registration which will generate list of Pre-IDs

   • Registration Client which will generate list of packets.

   • Registration Processor which will generate UIN for the packets.

   • IDA to perform authentication.

   • E2E to consume the above projects

3. A basic code structure looks as follows:

4.6.4.1 A Code Structure For E2E run

The E2E code has the following prerequisite

• Under src/test/resources we should have an input.json which contains a data to generate the list of preIDs.

• All the module level suites should be up and running.

• A sample pom for e2e looks like the following:

• The pre Reg Automation has the following pre Requisite :

  1. It should have an input.json file which will conation info about the adults and children against whom the preIDs are being generated.

• The Reg Client Automation has the following pre Requisite:

  1. The pre Reg Automation Should have run.

  2. A json file with a list of preIds must have been generated.

• The reg Proc Automation has the following pre Requisite:

  1. The reg Client and pre Reg automation should have run.

  2. A list of packets must have been generated.

• The IDA automation has the following pre Requisite :

  1. The regProc,reg Client,Pre Reg automation should have run.

  2. A list of uin should be present as a property file under src/main/resources which is generated by regProc.

4.6.5 Procedure to execute or Run the tests on a new environment

• To run the automation suite simply select the “EndToEndRun.java” class under the package “io.mosip.e2e.runner”.

• Report will be generated under “/testing-report.

4.6.6 Analyze the test reports

1. Report can be opened in any Web browser (i.e. Internet Explorer)

2. The report will consist of total number of test case executed with status as either pass, skipped and fail and their count.

3. Report will also display applicant type and corresponding test case names with execution time along with build version and execution time.

4. For detailed analysis, refer logs or default testing-report and for failed test cases, the related cause of failure will be highlighted.

4.6.7 Limitations for the test rig

1. The rig is designed to run for only 5 packets.

2. The rig should run on a particular version of each module.

Courtesy : Sasikumar Ganesan

Table Of Content

Test Rig Definition

Test Rig represents a one click automation to build, deploy and test a software module. Successful execution of test rig would ascertain complete setup of the MOSIP platform.

Test-Rig comprises of multiple components starting from:

1. Kubernetes env setup

2. Pulling the source code from the GIT repository

3. Running sonarqube tests for static code analysis

4. Building the application using maven

5. Automated application deployment using Kubernetes

6. Running automated unit tests

7. Running automated tests to verify and validate the application build against the given requirements.

Test Automation

MOSIP platform architecture is mainly based on Micro services and SEDA architecture. Therefore it predominantly comprises of Rest & JAVA APIs. Therefore test automation best serves the purpose of detailed API level testing. Test automation is the key to the successful testing of individual APIs and their interrelation with interdependent APIs. It ensures comprehensive test coverage and test data.

Automation deliverables mainly comprises of individual module level suites for the individual MOSIP modules:

1. Pre-Registration

2. Registration Client

3. Registration Processor

4. IDA

5. Kernel

Additionally there will be an end to end, system level test suite that will cut across all modules covering the functionality

The below diagram depicts the various building blocks of the module level suite.

Salient features

1. The automation suite is configurable to selectively execute tests such as Sanity or/and Regression

2. Each module level suite covers API and inter API automation

The individual module level test suites and the end to end suite are triggered via the CI/CD pipeline and run post application deployment

The user guides listed below detail the usage of individual module level automation suites

End to end system level Test Rig covers the functionality across the modules starting with Pre-Registration and ending in Registration Processor or IDA.

The below diagram depicts the overall design of the end to end suite.