# 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](/local-governance/access/local-governance-stack/property-tax/property-tax-service.md) | 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) | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digit.org/local-governance/access/local-governance-stack/property-tax/property-tax-service/property-mutation-and-mutation-calculator.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.