# Property Mutation & Mutation Calculator ## **Overview** The mutation service enables property ownership changes due to sale or inheritance. It uses a configurable workflow to manage approvals and helps municipalities collect payments smoothly. The mutation APIs and flows are part of the **property-services** codebase and rely on configured values and integrated external services to control the mutation process. ## **Pre-requisites** * Prior knowledge of Java/J2EE. * Prior knowledge of Spring Boot. * Prior knowledge of REST APIs and related concepts like path parameters, headers, JSON etc. * Prior knowledge of Git * Prior knowledge of the demand-based systems. * The following services should be up and running: * user * MDMS * Persister * Location * Localization * Id-Gen * Billing-service * URL-shortener ## **Key Functionality** Enables the user to create a mutation and transfer the ownership to the new owner. ## **Configuration Steps** {% stepper %} {% step %} ### Configure Mutation Workflow The mutation workflow controls how ownership transfers are managed. **➤ Key Mutation Config Values** | Config Key | Value Type | Purpose | | ------------------------------ | ------------- | -------------------------------------- | | `is.mutation.workflow.enabled` | `true/false` | Enable/disable the mutation workflow | | `mutation.workflow.name` | `PT.MUTATION` | Workflow identifier for mutation flows | **✔ What to Do** 1. In your PT service configuration (environment YAML/properties), add the mutation workflow keys. 2. Ensure `mutation.workflow.name` is set to **PT.MUTATION**. 3. The service will use this when a mutation request enters the system. 4. **Important:** In a mutation request payload, include `"creationReason": "MUTATION"` so the service treats it as a mutation request. Otherwise, it won’t trigger the mutation workflow. Sample config ``` "workflow": { "tenantId": "pb.amritsar", "businessService": "PT.MUTATION", "action": "OPEN", "moduleName": "PT" }, "additionalDetails": { "documentDate": 1580722677000, "marketValue" : 1000, "documentValue": "1897", "documentNumber": "Xar34", "reasonForTransfer": "Sale", "isPropertyUnderGovtPossession": true "govtAcquisitionDetails": "" "isMutationInCourt":true, "caseDetails": "", } ``` To add {% endstep %} {% step %} ### Provide Additional Details in Mutation Request ``` { "RequestInfo": { "apiId": "Rainmaker", "action": "", "did": 1, "key": "", "msgId": "20170310130900|en_IN", "requesterId": "", "ts": 1513579888683, "ver": ".01", "authToken": "{{Auth_Token}}" }, "BusinessServices": [ { "tenantId": "pb", "businessService": "PT.MUTATION", "business": "PT", "businessServiceSla": null, "states": [ { "tenantId": "pb", "sla": null, "state": null, "applicationStatus": "INWORKFLOW", "docUploadRequired": false, "isStartState": true, "isTerminateState": false, "actions": [ { "tenantId": "pb", "action": "OPEN", "nextState": "OPEN", "roles": [ "CITIZEN", "EMPLOYEE" ] } ] }, { "tenantId": "pb", "sla": null, "state": "OPEN", "applicationStatus": "INWORKFLOW", "docUploadRequired": false, "isStartState": true, "isTerminateState": false, "actions": [ { "tenantId": "pb", "action": "VERIFY", "nextState": "DOCVERIFIED", "roles": [ "PT_DOC_VERIFIER" ] }, { "tenantId": "pb", "action": "REJECT", "nextState": "REJECTED", "roles": [ "PT_DOC_VERIFIER" ] }, { "tenantId": "pb", "action": "SENDBACKTOCITIZEN", "nextState": "CORRECTIONPENDING", "roles": [ "PT_DOC_VERIFIER" ] } ] }, { "tenantId": "pb", "sla": null, "state": "DOCVERIFIED", "applicationStatus": "INWORKFLOW", "docUploadRequired": false, "isStartState": false, "isTerminateState": false, "actions": [ { "tenantId": "pb", "action": "FORWARD", "nextState": "FIELDVERIFIED", "roles": [ "PT_FIELD_INSPECTOR" ] } ] }, { "tenantId": "pb", "sla": null, "state": "FIELDVERIFIED", "applicationStatus": "INWORKFLOW", "docUploadRequired": false, "isStartState": false, "isTerminateState": false, "actions": [ { "tenantId": "pb", "action": "PAY", "nextState": "PAID", "roles": [ "CITIZEN", "PT_CEMP" ] } ] }, { "tenantId": "pb", "sla": null, "state": "REJECTED", "applicationStatus": "INACTIVE", "docUploadRequired": false, "isStartState": false, "isTerminateState": true, "actions": null }, { "tenantId": "pb", "sla": null, "state": "PAID", "applicationStatus": "INWORKFLOW", "docUploadRequired": false, "isStartState": false, "isTerminateState": false, "isStateUpdatable": false, "actions": [ { "tenantId": "pb", "action": "APPROVE", "nextState": "APPROVED", "roles": [ "PT_APPROVER" ] } ] }, { "tenantId": "pb", "sla": null, "state": "APPROVED", "applicationStatus": "ACTIVE", "docUploadRequired": false, "isStartState": false, "isTerminateState": true, "isStateUpdatable": false, "actions": null }, { "tenantId": "pb", "sla": null, "state": "CORRECTIONPENDING", "applicationStatus": "INWORKFLOW", "docUploadRequired": false, "isStartState": false, "isTerminateState": false, "isStateUpdatable": true, "actions": [ { "tenantId": "pb", "action": "REJECT", "nextState": "REJECTED", "roles": [ "CITIZEN", "PT_CEMP" ] }, { "tenantId": "pb", "action": "REOPEN", "nextState": "OPEN", "roles": [ "CITIZEN", "PT_CEMP" ] } ] } ] } ] } ``` {% endstep %} {% step %} ### Integrate with Mutation Calculator Mutation fees aren’t hard-coded — they’re calculated dynamically via a **mutation calculator** that the property service calls during the workflow. **💡 How It Works** * The **mutation calculator** service evaluates a fee based on the **property’s usage type** and **its current market value**. * The workflow can invoke this service at the right point in the mutation flow to generate a fee demand. {% endstep %} {% step %} ### Mutation Fee Logic & Billing Slabs The mutation fee calculation considers multiple factors: **🔹 Criteria Used** * **Usage Type** (e.g., Residential / Non-Residential) * **Current Market Value (CMV)** * **Billing Slabs** (tiered ranges of values) * **Calculation Type**: * **FLAT** → a fixed fee * **RATE** → a percentage of CMV | Usage type | Minimum Market value | Maximum Market Value | Rate Percentage | Fixed amount | Calculation Type | | ---------------- | -------------------- | -------------------- | --------------- | ------------ | ---------------- | | Residential | 0 | X lacs | A% of CMV | INR G | FLAT | | Non -Residential | 0 | X lacs | E% of CMV | INR Q | RATE | | Residential | X+1 Lacs | Y Lacs | B% of CMV | INR H | FLAT | | Non -Residential | X+1 Lacs | Y Lacs | B% of CMV | INR H | RATE | | Residential | Y+1 Lacs | >Y+1Lacs | D% of CMV | INR L | FLAT | | Non -Residential | Y+1 Lacs | >Y+1Lacs | C% of CMV | INR I | RATE | **🧮 Fee Determination** 1. Find the slab where the property’s CMV falls. 2. Match the usage type. 3. Apply the slab’s calculation type: * *If FLAT* → use the slab’s fixed amount. * *If RATE* → calculate fee as `X% of CMV` (where X is the slab’s configured rate). {% endstep %} {% step %} ### Rebate & Penalty Rules To make mutation work in your system, follow these integration steps: 1. Use an existing **active propertyId** from the system. 2. Call the **property/update** API (`/property/_update`) including updated owner info and workflow details. 3. Ensure mutation workflow fields are part of the request so the system knows this is a mutation request. {% endstep %} {% step %} ### Configure Integrations To make mutation work in your system, follow these integration steps: 1. Use an existing **active propertyId** from the system. 2. Call the **property/update** API (`/property/_update`) including updated owner info and workflow details. 3. Ensure mutation workflow fields are part of the request so the system knows this is a mutation request. {% endstep %} {% endstepper %} ## **Reference Docs** Refer to the parent for external services:[ Property Services | Doc-Links](https://docs.digit.org/local-governance/access/local-governance-stack/property-tax/property-tax-service) | Title | Link | | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API contract for MT calculator | [mutation-calculator.yml](https://raw.githubusercontent.com/egovernments/municipal-services/master/docs/property-services/property-mutation-fees-calculator_API_Contract.yml) | | API list to create Mutation Slabs mutation/\_create, \_search, \_update | [API COLLECTION MT\_SLABS](https://www.getpostman.com/collections/02965abc6345b5e1a633) | | API list for MT-Calculator mutation/\_calculate | [POSTMAN API COLLECTION - MT-CALCULATE](https://www.getpostman.com/collections/e044d1f64feeafe82f70) |