Frappe Server ScriptsPython

How to Create Mapped Documents in Frappe for ERPNext Customizations?

Create Mapped Document

Utilize the Frappe get_mapped_doc API server-side to automate document mapping from source to target DocTypes with custom field maps and value setters.

Introduction

In ERPNext development, automating the creation of documents based on existing records accelerates business workflows and reduces errors. This snippet demonstrates using Frappe's get_mapped_doc function in a server script to map fields from one DocType (such as Meeting Schedule or Sauda Details) to another (e.g., Meetings or Sales Order), handling different field names and custom child table data. This approach is essential when implementing custom buttons or triggers that transform data according to unique business logic within ERPNext.

server_scripts/create_mapped_doc.pypython
frappe.model.mapper.get_mapped_doc official documentation
1// Import below library
2from frappe.model.mapper import get_mapped_doc
3

4@frappe.whitelist()
5def make_meeting(source_name, target_doc=None):
6	
7	doclist = get_mapped_doc("Meeting Schedule", source_name, {
8			"Meeting Schedule":{
9				"doctype": "Meetings",
10				"field_map": {
11					"meeting_from": "scheduled_from",
12					"meeting_to": "scheduled_to"
13				}
14			}
15	}, target_doc)
16	
17	return doclist
18

19// Another Example for mapping different field names
20@frappe.whitelist()
21def make_so(source_name, target_doc=None):
22	def set_missing_values(source, target):
23		ignore_errors=True
24		target.append("items", {
25			"item_code": source.item,
26			"item_name": source.item_name,
27			"description": source.item_name,			
28			"uom": source.uom,
29			"stock_uom": source.stock_uom,
30			"qty":source.available_qty,
31			"rate":source.rate
32		})
33doclist = get_mapped_doc("Sauda Details", source_name, {
34			"Sauda Details": {
35				"doctype": "Sales Order",
36				"field_map": {
37					"name": "sauda_ref",
38					"shipment_to": "delivery_date",
39				}
40			},
41		}, target_doc, set_missing_values)
42return doclist

Understanding This Code

What It Does

Automates creation of a new DocType document by mapping fields from an existing document using get_mapped_doc. Handles custom field mappings and allows custom logic to set additional values.

When To Use

Use in server-side triggers such as @frappe.whitelist methods called from buttons or API endpoints when data from one DocType needs to be transformed and saved as another.

Prerequisites

  • •Frappe server script knowledge
  • •Understanding of ERPNext DocType relationships
  • •Basic Python familiarity

Key Concepts

Important ideas to understand in this code

get_mapped_doc

Frappe API to map and create new documents based on a source document, specifying field mappings and custom callbacks.

Learn more

DocType

The fundamental data model in ERPNext representing forms and database schema.

Learn more

@frappe.whitelist

Decorator to expose server-side Python methods for client-side calls or via REST API.

Learn more

Step-by-Step Tutorial

Follow along to understand how this code works

1

Import get_mapped_doc API

Import the helper method from frappe.model.mapper to utilize its powerful document mapping capabilities.

python
from frappe.model.mapper import get_mapped_doc
Next Step
2

Define the mapping function

Create a whitelisted function that takes a source document name and optionally a target document to populate or create.

python
@frappe.whitelist()
def make_meeting(source_name, target_doc=None):
Next Step
3

Set up mapping rules

Configure the from-to field mapping in a dictionary with the source DocType as key and a mapping with the target DocType and any necessary field maps.

python
doclist = get_mapped_doc("Meeting Schedule", source_name, {"Meeting Schedule": {"doctype": "Meetings", "field_map": {"meeting_from": "scheduled_from", "meeting_to": "scheduled_to"}}}, target_doc)
Next Step
4

Handle advanced mapping with callbacks

For complex transformations like mapping child tables or setting missing values, define a callback function that modifies the target document.

python
def set_missing_values(source, target):
    target.append("items", {
        "item_code": source.item,
        "item_name": source.item_name,
        "description": source.item_name,
        "uom": source.uom,
        "stock_uom": source.stock_uom,
        "qty": source.available_qty,
        "rate": source.rate
    })
Next Step
5

Return the mapped document

Return the mapped document list so it can be saved or further processed.

python
return doclist

Common Issues & Solutions

Troubleshoot problems you might encounter