Property Mutation & Mutation Calculator

Ownership Transfer Technical documentation

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

1

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

2

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"
                            ]
                        }
                    ]
                }
            ]
        }
   ]
}

3

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.

4

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).

5

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.

6

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.

Reference Docs

Refer to the parent for external services: Property Services | Doc-Links

Title	Link
API contract for MT calculator	mutation-calculator.yml
API list to create Mutation Slabs mutation/_create, _search, _update	API COLLECTION MT_SLABS
API list for MT-Calculator mutation/_calculate	POSTMAN API COLLECTION - MT-CALCULATE