Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The expense calculator is an implementation-specific service that works in tandem with the expense service. This service holds all the specific business logic in computing expenses and calls the billing service with the correct payload to create a bill.
There are three types of bills in Mukta:
Wage bill - auto-generated from an approved muster roll and to be paid to wage seekers on completion of work
Purchase bill - submitted by a JE or ME on behalf of the vendor
Supervision bill - computed on top of wage and purchase bills to be paid to the CBO (community-based organisation).
The calculator performs the calculation for all three types of bills and creates a bill.
DIGIT backbone services
Persister
MDMS
IDgen
Expense
Listens for muster roll approval on a Kafka topic and creates a wage bill based on the muster roll.
Calculates supervision bill (if required) on any bills that have not been included so far and submits it to expense service
Allows update of purchase bill.
Search for meta information related to bills
HeadCodes
ApplicableCharges
LabourCharges
BusinessService
PayerList
API spec
Postman collection
Service specifications for MuktaSoft
This section provides the detailed specifications, deployment and configuration details for MuktaSoft services.
Click on the service links below for details.
Revise Rates Job
To implement a secure bank account search service in Mukta that masks Personally Identifiable Information (PII) in the response based on the user’s role and predefined security policies. PII data - Branch name, Account number, IFSC
The response would be based on the config set in MDMS-V2 which masks the above fields in appropriate patterns.
1. Masking Methodology
Masking is applied to sensitive attributes such as accountHolderName, accountNumber, and ifscCode.
A regular expression-based masking technique is used, replacing parts of the sensitive values with asterisks (*).
Example: For a pattern - (?=.{4}), the value 12345678 would be masked as ****5678.
2. Security Policy:
Role-Based Access Control (RBAC):
Defines which roles can access attributes in plain text.
Example roles: BILL_ACCOUNTANT, MUKTA_ADMIN.
Attribute Visibility Levels:
PLAIN: The attribute is fully visible.
MASKED: Attribute is partially masked.
Policy Configuration Example:
3. Masking Pattern Configuration:
Patterns define how sensitive attributes are masked.
Example configuration:
Pattern Example:
Pattern.(?=.{4}): Masks all characters except the last 4.
Pattern (?<=.{4}).(?=.{2}): Masks characters except the first 4 and last 2.
4. Implementation Details:
The service retrieves security policies and masking patterns from MDMS.
User roles are validated to determine access levels for each attribute.
Masking is applied dynamically to sensitive data if the user’s role lacks plain text access.
5. Code Highlights:
Role Access Check: Ensures attributes are visible in plain text only if the user’s role has access.
Masking Application: Masks attribute values using patterns fetched from the configuration.
Nested JSON Handling: Retrieves and updates attribute values dynamically using JSON paths
Curl:
This bill scheduler is a cronjob scheduler for calculating the supervision bill. It runs based on environment configuration. It triggers multiple APIs to generate the supervision bill.
MDMS
User
Contract
Expense Calculator
It creates supervision bills based on ACTIVE contracts using expense-calculate service /v1/_calculate API.
Create a role in ACCESSCONTROL-ROLES/roles.json
MDMS like this.
Create a SYSTEM
user with BILL_CREATOR and SYSTEM
roles. Find the curl below.
The same username will be used to generate bills BILL_GEN_CRONJOB, it’s defined in the environment config.
Cron job duration will be configured using environment variables from here.
There are two ways to update the configuration of the scheduler:
Add the config in the DevOps environment file, and restart the service. This will trigger the scheduler based on the updated environment configuration and restart the expense-cronjob
service.
Use the commands given below: Change schedule - kubectl patch cronjobs expense-cronjob -p '{"spec" : {"schedule": "*/10 * * * *" }}'
Pause cron job - kubectl patch cronjobs expense-cronjob -p '{"spec" : {"suspend" : true }}' Resume cron job - kubectl patch cronjobs expense-cronjob -p '{"spec" : {"suspend" : false}}' Create a new cronjob scheduler - kubectl create job --from=cronjob/expense-cronjob expense-cronjob
The Mukta Individual Search service is designed to retrieve and handle individual-related data securely. The service masks personally identifiable information (PII) based on configurable patterns and enforces role-based access control to ensure sensitive data is visible only to authorized users.
PII data - Name, Identity number, Father/ husband name, Relationship, Address, Date of birth, Gender, Mobile Number, Social category, Email ID, Photo.
The response would be based on the config set in MDMS-V2 which masks the above fields in appropriate patterns.
Masking Patterns:
Configured in the DataSecurity module.
Patterns define the masking logic for attributes, e.g.,
001: .\*(?=.{4}) masks all but the last 4 characters.
009: (?<=.{4}).(?=.{2}) masks characters except the first 4 and last 2.
Role-Based Security Policies:
Defined in the MaskingUIConfig module.
Specifies the visibility of attributes based on user roles.
Attributes can have PLAIN or MASKED visibility.
Implementation:
Attributes are extracted from the response using JSON paths.
If a user's role does not permit plain text access, the attribute is masked based on the configured pattern.
Curl:
The Mukta Organisation Search service is designed to provide secure and efficient access to organisation data. It incorporates configurable masking patterns and role-based policies to safeguard sensitive information while maintaining accessibility for authorized users.
PII data - Door No, Street Name, Locality, Mobile Number, Email ID, PAN, GSTIN.
The response would be based on the config set in MDMS-V2 which masks the above fields in appropriate patterns.
Role-Based Attribute Access:
Ensures that only authorized roles can access sensitive organisation attributes in plain text.
Configurable access levels for each role.
Configurable Masking Patterns:
Provides flexibility to define masking patterns for each attribute.
Masks sensitive information to ensure data security.
Dynamic Masking Configurations:
Uses MDMS (Master Data Management System) for dynamic retrieval of masking configurations.
For a user without plain text access:
For a user with plain text access:
MDMS Configuration Fetching:
Retrieves masking patterns and role-based policies dynamically from MDMS.
Role-Based Masking Logic:
Determines access levels for each role.
Applies appropriate masking patterns to sensitive attributes.
Dynamic Masking of Attributes:
Masks attributes such as name, registration number, and address based on user roles and configurations.
Handles complex paths within objects (e.g., geoLocation.boundaryCode).
User Request:
The user sends a search request with RequestInfo and SearchCriteria.
Configuration Fetching:
Service fetches masking patterns and role-based policies from MDMS.
Attribute Masking:
Attributes are masked/unmasked based on user roles and configurations.
Response Generation:
Returns the masked/unmasked organisation data to the user.
Curl:
MUKTA Services is an intermediary service that bridges the gap between the API and client requests. It helps Clients/UI gather all the required information from different services.
MDMS
MDMS V2
Estimates
Muster Roll
Contract
Measurement
Bank Accounts
Individual
Organisation
mukta-services/measurement/_search
MB_CREATOR
mukta-services/bankaccount-service/bankaccount/v1/_search
VIEW_DED_UNMASKED
mukta-services/individual/v1/_search
VIEW_WS_UNMASKED
mukta-services/org-services/organisation/v1/_search
VIEW_ORG_UNMASKED
This service handles all the measurement creation criteria and helps the UI consolidate all information. The measurement period is calculated in the mukta-services based on the same criteria.
The measurement response would be based on the config https://github.com/egovernments/egov-mdms-data/blob/UNIFIED-DEV/data/pg/works/MeasurementBFFConfig.json which transforms the final consolidated object of Estimate, Contract, measurement, and Muster roll into the user-requested object.
This service masks the search response before displaying it in the UI. This middleware eliminates the need to make major changes in the backend. The masking is done based on the user roles for sensitive PII data.
Three APIs have been defined under the data privacy controller as follows:
BankAccountSearch: Unmasking Role - VIEW_DED_UNMASKED
IndividualSearch: Unmasking Role - VIEW_WS_UNMASKED
OrganisatonSearch: Unmasking Role - VIEW_ORG_UNMAKSED
The statements service is used to generate and save the statement. The business logic for both types of statements differs based on the request. Hence, there are 4 APIs (2- Create and 2- Search).
MUKTASoft provides two types of statements: Analysis Statements and Utilization Statements.
Analysis Statement
Purpose: Generated for estimates already created and present in the system.
Accessibility: Employees can view the Analysis Statement from the estimate view screen.
Linkage: The statement is linked to the specific estimate for which it is generated.
Utilization Statement
Purpose: Generated for measurement books already created and present in the system.
Accessibility: Employees can view the Utilization Statement from the measurement view screen.
Linkage: The statement is linked to the specific measurement for which it is generated.
DIGIT backbone services
Persister
MDMSV2
IDgen
Rate Analysis
Estimate
Measurement Book
Contract
The service generates rate analysis for SOR (Schedule of Rates) compositions using four APIs:
Job Management:
Create Job API: Creates a new job.
Search Job API: Searches for existing jobs.
Rate Analysis:
Generate Rate Analysis API: Generates rate analysis.
Create Rate Analysis API: Saves the rate analysis.
To save the rate analysis per unit, the scheduler/create API is triggered. This internally calls the Create API and computes the rates generated with the help of the Calculate API.
This streamlined process ensures accurate rate analysis for SOR compositions.
DIGIT backbone services
Persister
MDMSV2
IDgen
The Rate Analysis Save API internally calls the existing MDMSv2 API to save the rates, eliminating the need for a new database design. The Rate Analysis Create API generates the rate analysis in real-time.
The client should call the Scheduler Create API to save the generated rate analysis. This API creates a job that includes a list of SORs requiring rate revisions (even a single SOR is passed as a list).
Works-PDF is an intermediary service that bridges the gap between the pdf-service and client requests. Within works-pdf, there are several APIs available for producing various PDFs. This service gathers data from multiple sources, amalgamates it, and then forwards the request to the PDF service for PDF generation.
Further, Works PDF can produce an Excel file when a payment is initiated. It actively listens to the "expense-payment-create" topic, capturing relevant payment data to trigger this process.
MDMS
Project
Estimates
Muster Roll
Contract
Organization
Localization
Expense
Expense calculator
Bank account
Filestore
The system retrieves data from various sources to create multiple PDFs such as estimates, muster reports, and project documents.
When a payment is generated, it produces Excel files corresponding to the payment bills. This is triggered by a payment creation event communicated through a topic.
Users also have the option to recreate the Excel files for a specific payment using the same payment ID. This functionality allows for the regeneration of payment-related Excel documents.
Add all pdf configurations under pdf-service data config and format config
Add file type 'application/zip' under xlsx
format in egov-filestore
allowed-file-formats-map
.
Create accounts for purchase and wage bills, for head codes where the category is deduction.
Example: Below is the head code object:
Where tenantId is pg.citya
The format of referenceId is Deduction_{tanentId}_{headcode}
Then create a bank account with the field referenceId
value Deduction_pg.citya_LC
This page describes the integration with the Integrated Financial Management System of Odisha state
Integration with Odisha IFMS (Integrated Financial Management System) is via the Just-in-Time (JIT) APIs provided by the Odisha treasury.
The following pieces of information are shared offline:
clientId
clientSecret
publicKey from JIT systems
All other master data is configured inside the ifms
folder at a state level as well as a ifms
folder inside a ULB level.
Head of accounts to be used for the Mukta scheme at the state level - to be provided by HUDD
Spending unit details specific to each ULB are to be provided by HUDD.
The IFMS Adapter does not use the persister service. The adapter interacts directly with the DB and has sync blocks on certain transactions to preserve data integrity.
expense service
expense-calculator service
bank-account service
individual service
organisation service
audit-log service
IDGen service
MDMS service
encryption service
IFMS adapter manages funds summary based on the head of accounts and SSU codes. It creates sanctions for each head of accounts and SSU details based on ULB tenant ID.
There are three types of transactions that can be received from the JIT VA API -
Initial Allotment - A new sanction will be created only if AllotmentTxnType is Initial Allotment.
Additional allotment - For this type of transaction it will update the amount of existing sanction.
Allotment withdrawal - It deducts the transaction amount from the sanction for this type of transaction.
When a bill is approved this service creates payment using the expense service.
There are consumers who keep listening to the payment create Kafka topic and generate payment instructions (PI) using payment and bill details and post the PI to the IFMS system using JIT API.
A new PI will be generated when enough funds are available for any head of accounts for that tenantId.
Before posting the PI there were multiple enrichments like bankaccount details, org and individual details, etc.
After creating the PI it deducts the available balance from the funds summary.
If a PI is created for any payment then the user can not generate a PI again till the PI fails.
It keeps a log of each status call of PI and saves it in the DB
IFMS adapter connects JIT with two APIs -
authentication - webservices/jitfs/v1.0/authenticate
service request - webservices/jitfs/v1.0/get-jit-service-data
There are multiple cronjobs for the IFMS adapter, all jobs are built using a single codebase with multiple charts, these charts are required to configure cronjobs with multiple configurations.
All cronjobs uses ifms/scheduler?serviceId={SERVICE_ID} API, the business logic is defined for each service code.
Service codes are -
ifms-cronjob-pa
PA
It is used to create payment for approved bills, uses expense service API
ifms-cronjob-va
VA
It fetches the allotment details using JIT API's.
ifms-cronjob-pis
PIS
After PI creation it fetches whether the payment instruction's sanction is generated or not.
ifms-cronjob-pag
PAG
After receiving the PIS response it fetches for payment advice generation using JIT API.
ifms-cronjob-pd
PD
After receiving the PAG response it keeps fetching data for the PD service JIT API. The response will be received when payment is processed.
ifms-cronjob-fd
FD
It uses JITs bulk failure API and returns failed payments of the last 72hrs.
ifms-cronjob-ftps
FTPS
This same as PD - it is used for the revised transaction.
ifms-cronjob-ftfps
FTFPS
After receiving the response from FTPS API it keeps fetching data of failedrequests transactions of revised transactions.
All requests and responses are logged in an encrypted fashion in two indexes in ES.
ifms-request-logs
ifms-error-logs
Use this index to see a history of all successful requests to JIT.
Each request that is sent to JIT will be logged in the ifms-request-logs
index. The index name is configurable in application.properties, Helm chart and environment file. There are multiple fields for the request:
id - uuid of the request
serviceId - Contains service ID of jit request like VA, PI, PIS etc
jitBillNo - Contains bill number for which it’s calling the JIT API, it’s applicable for PI, PIS, PAG, PD, FTPS, and FTFPS. Note: For Auth request jitBillNo will be AUTH
encRequest - Contains request body which is encrypted using ifms.request.enc.secret value. You can decrypt this using the same secret.
decryptionRek - Contains decryption rek which helps to decrypt the JIT response received from JIT.
encResponse - Response received from JIT.
createdtime - The time when the request was sent to the JIT system
Use this index to see all failing requests to and back from the JIT IFMS APIs.
When the user sends any request to JIT and gets an error response, then it will store the details in ifms-error-logs index. It has multiple fields
serviceId - Contains service ID of jit request like VA, PI, PIS etc
requestId - This is uuid of ifms-request-logs index
statusCode - Status code of Network response
jitEncRequest - Encrypted request which is sent to the JIT, we can not decrypt this request.
errorMsg - Error response which was received from JIT
encryptionRek - Encryption rek using which request is encrypted
decryptionRek - Contains decryption rek which helps to decrypt the JIT response
authToken - Auth token which request was sent to the JIT
sekString - sek which was received from the login
createdtime - The time when the request was sent to the JIT system
Estimates PDF - ,
Muster Roll PDF - ,
Project PDF - ,
Work order PDF - ,
/egov-pdf/download/estimate/estimates
ESTIMATE_CREATOR
ESTIMATE_VERIFIER
TECHNICAL_SANCTIONER
ESTIMATE_APPROVER
ESTIMATE_VIEWER
/egov-pdf/download/musterRoll/muster-roll
MUSTER_ROLL_APPROVER
ORG_ADMIN
MUSTER_ROLL_VERIFIER
/egov-pdf/download/project/project-details
PROJECT_VIEWER
/egov-pdf/download/workOrder/work-order
ORG_ADMIN
WORK_ORDER_VIEWER
WORK_ORDER_APPROVER
/egov-pdf/bill/_generate
BILL_ACCOUNTANT
/egov-pdf/bill/_search
BILL_ACCOUNTANT