ID Generation Service
Overview
In a bid to avoid unnecessary repetition of codes to generate ids and to have centralized control over the logic so that burden of maintenance is reduced from the developers. To create a config based application that can be used without writing even a single line of coding.
Pre-requisites
Prior Knowledge of Java/J2EE
Prior Knowledge of Spring Boot, Flyway
Prior Knowledge of REST APIs and related concepts like path parameters, headers, JSON etc.
Key Functionalities
The application exposes a Rest API to take in requests and provide the ids in response in the requested format. The request format varies from current date information, tenantId*, random number, sequence generated number. Id can be generated by providing a request with any of the above-mentioned information.
*TenantId - is the string representing the individual units called tenants in the DIGIT system which can be a city, town or village.
For instance: An Id Amritsar-PT-2019/09/12-000454-99 contains
Amritsar - which is the name of the city
PT - fixed string representing the module code(PROPERTY TAX)
2019/09/12 - date
000454 - sequence generated number
99 - random number
The id generated in the above-mentioned example needs the following format
[city]-PT-[cy:yyyy/mm/dd]-[SEQ_SEQUENCE_NAME]-[d{4}]
Everything in the square brackets is replaced with the appropriate values by the app.
ID-FORMAT COFNIGURATION
By default, the IDGen service reads the configuration from MDMS. DB Configuration requires access to the DB, so the new preferred method for the configuration is MDMS. The configuration needs to be stored in common-masters/IdFormat.json in MDMS
It is recommended to have the IdFormat as a state-level master. To disable the configuration to be read from DB instead, the environment variable IDFORMAT_FROM_MDMS is set to false.
ID-FORMAT-REPLACEABLE
[FY:] - represents the financial year, the string is replaced by the value of starting year and the last two numbers of the ending year separated by a hyphen. For eg: 2018-19 in the case of the financial year 2018 to 2019.
[cy:] - any string that starts with cy is considered as the date format. The values after the cy: is the format using which output is generated.
[d{5}] - d represents the random number generator, the length of the random number can be specified in flower brackets next to d. If the value is not provided then the random length of 2 is assigned by default.
[city] - The string city is replaced by the city code provided by the respective ulb in the location services.
[SEQ_*] - String starting with seq is considered as sequence names, which gets queried to get the next seq number. If the sequence doesn’t start with the namespace containing “SEQ” then the application is not considered as a sequence. In absence of the sequence, the system throws a DB error.
[tenantid] - replaces the placeholder with the tenantid passed in the request object
[tenant_id] - replaces the placeholder with the tenantid passed in the request object. Replaces all `.` with `_`
[TENANT_ID] - replaces the placeholder with the tenantid passed in the request object. Replaces all `.` with `_`, and changes the case to upper case
idName v/s format
When you use both idName and format in a request. IDGEN first checks if the format for the given idName exists. If it does not exist, then the default format is used.
STATE v/s ULB LEVEL SEQUENCES If you want a state-level sequence, then you need to use a fixed sequence name
{
"format": "PT/[CITY.CODE]/[fy:yyyy-yy]/[SEQ_RCPT_PT_RECEIPT]",
"idname": "pt.receipt.id"
}
But if you want a ULB level sequence, the sequence name should be dynamic based on the tenantid as given in the below example
{
"format": "PT/[CITY.CODE]/[fy:yyyy-yy]/[SEQ_RCPT_PT_[TENANT_ID]]",
"idname": "pt.receipt.id"
}
SEQUENCES AND THEIR CREATION
The SEQ_* replaceable used in id generation is by default expected to use the sequence that already exists in the DB. But this behaviour can be changed and controlled using two environment variables while deploying the service.
AUTOCREATE_NEW_SEQ: Default is set to false. When set to true, this auto-creates sequences when the format has been derived using provided idName. Since the idName format comes from DB or MDMS, it is a trusted value and this value is set to true. This makes sure that DB configuration is not required as long as MDMS has been configured. It is recommended that each service using idgen should generate id using idName instead of just using passing the format directly. This makes sure that DB configuration is not required for creating sequences.
AUTOCREATE_REQUEST_SEQ: Default is set to false. When set to true, this auto-creates sequences when the format has been derived using the format parameter from the request. It is recommended to keep this setting to false since anyone with access to idgen can create any number of sequences in DB and overload the DB. Though during the initial setup of an environment this variable can be set to true to create all the sequences when the initial flows are run from the UI and to generate the sequences. And afterwards, the flags should be disabled.
Deployment Details
Add MDMS configs required for ID Gen Service and restart the MDMS service
Deploy the latest version of ID Generation Service
Add Role-Action mapping for APIs
Integration
Integration Scope
The ID Gen service is used to generate unique ID numbers for all miscellaneous / adhoc services which citizens avail from ULBs.
Integration Benefits
Can perform service-specific business logic without impacting the other module.
Provides the capability of generating the unique identifier of the entity calling ID Gen service.
Steps to Integration
To integrate, a host of idgen-services modules should be overwritten in the helm chart.
/egov-idgen/id/_generateshould be added as the endpoint for generating ID numbers in the system
API Contract
Last updated