Insert a document via the API

Oct 13, 2025 by wbrum.org 134 views

Description of the Issue

In Frappe, the mandatory_depends_on field is expected to enforce mandatory validation dynamically based on conditions during document insertion or saving. However, when inserting a document via the API using frappe.new_doc(), the condition inside mandatory_depends_on is not evaluated properly, allowing documents to be inserted with missing required fields. This issue can lead to inconsistencies in data and potentially cause errors in downstream processes.

Steps to Reproduce the Issue

To reproduce this issue, follow these steps:

Define a field with mandatory_depends_on: Create a field with the mandatory_depends_on attribute, for example, "mandatory_depends_on": "eval:doc.status == 'complete'". This field will be dependent on the status field and will be mandatory only when the status is set to 'complete'.
Insert a document via the API: Use a custom function to insert a document via the API using frappe.new_doc(). Here's an example function:

@frappe.whitelist(methods=["POST"]) def insert(doctype, data): doc = frappe.new_doc(doctype) doc.update(data) doc.insert() return doc

3. **Observe the result**: When you insert a document with the `status` set to `'complete'`, the dependent field should be mandatory. However, the system does not trigger validation, and you can save an incomplete document.

### Observed Result

The observed result is that the dependent field is not evaluated properly, and the document is inserted with missing required fields. This is a critical issue, as it can lead to data inconsistencies and errors in downstream processes.

### Expected Behavior

The expected behavior is that the system should evaluate `mandatory_depends_on` before inserting or saving the document. If the condition is met, a validation error should be raised if the required field is missing. This ensures that the document is complete and valid before it is inserted or saved.

### Proposed Fix

To fix this issue, ensure that `mandatory_depends_on` is evaluated before saving or inserting a document, especially when inserting via API. The evaluation logic should be triggered within `doc.insert()` and `doc.save()`, preventing incomplete documents from being inserted. Here's an updated version of the `insert` function:
```python
@frappe.whitelist(methods=["POST"])
def insert(doctype, data):
    doc = frappe.new_doc(doctype)
    doc.update(data)
    if doc.mandatory_depends_on:
        # Evaluate mandatory_depends_on condition
        if eval(doc.mandatory_depends_on):
            # Check if required field is present
            if not doc.required_field:
                # Raise validation error if required field is missing
                frappe.throw("Required field is missing")
    doc.insert()
    return doc

In this updated function, we first evaluate the mandatory_depends_on condition. If the condition is met, we check if the required field is present. If the required field is missing, we raise a validation error.

Conclusion

The mandatory_depends_on field is not evaluated properly when inserting a document via the API using frappe.new_doc(). This issue can lead to data inconsistencies and errors in downstream processes. To fix this issue, we need to ensure that mandatory_depends_on is evaluated before saving or inserting a document, especially when inserting via API. The evaluation logic should be triggered within doc.insert() and doc.save(), preventing incomplete documents from being inserted.

Recommendations

To avoid this issue, we recommend the following:

Always evaluate mandatory_depends_on before saving or inserting a document.
Use the eval function to evaluate the mandatory_depends_on condition.
Check if the required field is present before saving or inserting a document.
Raise a validation error if the required field is missing.

Q: What is the purpose of the `mandatory_depends_on` field in Frappe?

A: The mandatory_depends_on field is used to enforce mandatory validation dynamically based on conditions during document insertion or saving. It allows you to specify a condition that must be met before a field is considered mandatory.

Q: Why is the `mandatory_depends_on` field not evaluating properly when inserting a document via the API?

A: The mandatory_depends_on field is not evaluating properly when inserting a document via the API because the condition inside mandatory_depends_on is not being triggered properly. This is a critical issue, as it can lead to data inconsistencies and errors in downstream processes.

Q: What is the expected behavior of the `mandatory_depends_on` field?

A: The expected behavior of the mandatory_depends_on field is that it should evaluate the condition before inserting or saving the document. If the condition is met, a validation error should be raised if the required field is missing.

Q: How can I fix the issue with the `mandatory_depends_on` field not evaluating properly?

A: To fix the issue, you need to ensure that mandatory_depends_on is evaluated before saving or inserting a document, especially when inserting via API. The evaluation logic should be triggered within doc.insert() and doc.save(), preventing incomplete documents from being inserted.

Q: What is the proposed fix for the issue with the `mandatory_depends_on` field?

A: The proposed fix is to update the insert function to evaluate the mandatory_depends_on condition before inserting the document. If the condition is met, the function should check if the required field is present. If the required field is missing, the function should raise a validation error.

Q: How can I avoid this issue in the future?

A: To avoid this issue in the future, you should always evaluate mandatory_depends_on before saving or inserting a document. You should use the eval function to evaluate the mandatory_depends_on condition, and check if the required field is present before saving or inserting a document.

Q: What are the best practices for using the `mandatory_depends_on` field?

A: The best practices for using the mandatory_depends_on field are:

Always evaluate mandatory_depends_on before saving or inserting a document.
Use the eval function to evaluate the mandatory_depends_on condition.
Check if the required field is present before saving or inserting a document.
Raise a validation error if the required field is missing.

Q: Can I use the `mandatory_depends_on` field with other fields in Frappe?

A: Yes, you can use the mandatory_depends_on field with other fields in Frappe. The mandatory_depends_on field can be used to enforce mandatory validation based on conditions involving other fields in the document.

Q: How can I troubleshoot issues with the `mandatory_depends_on` field?

A: To troubleshoot issues with the mandatory_depends_on field, you should:

Check the condition inside mandatory_depends_on to ensure it is correct.
Verify that the mandatory_depends_on field is being evaluated properly.
Check if the required field is present before saving or inserting a document.
Use the eval function to evaluate the mandatory_depends_on condition.

By following these best practices and troubleshooting steps, you can ensure that the mandatory_depends_on field is working correctly and that documents are inserted or saved with complete and valid data.