Efficiently Managing Documents with DocTypes and Document Names in Empress

Developers
1

Introduction

In Empress, DocTypes and Document Names play a crucial role in defining, identifying, and managing documents. As a developer, understanding how these features function and interact is key to efficiently utilizing and customizing the Empress system. This guide will delve into the technical functionalities and advantages of DocTypes and Document Names.

DocTypes and Document Names: An Overview

In Empress, a DocType is a specific type of document. Examples of DocTypes include ‘Customer’, ‘Employee’, or ‘Item’. A Document Name, on the other hand, is the unique ID of a Document. Examples include ‘CUST-00001’, ‘EMP-00001’, or ‘ITEM-00001’.

API Endpoints and Their Functionality

Empress provides several API endpoints for interaction with DocTypes and Document Names. Understanding these endpoints is crucial for effective integration and utilization of these features.

GET /api/resource/{DocType}

This endpoint retrieves a list of documents of a specified DocType. The DocType to be received is passed as a parameter in the path. By default, only the ‘name’ field of the documents is returned. However, additional fields can be added using the ‘fields’ parameter. The listing can also be filtered using SQL conditions passed in the ‘filters’ parameter. The listing is paginated, and the page size can be modified using the ‘limit_page_length’ parameter. The ‘limit_start’ parameter can be used to request successive pages.

Here is an example usage of this endpoint:

curl -X GET https://{your frappe instance}/api/resource/Customer?fields=["name"]\
            &filters=[["Customer","phone","=","4915227058038"]]

POST /api/resource/{DocType}

This endpoint is used to create a new document of a specified DocType. The DocType to be created is passed as a parameter in the path. The details of the document to be created are passed in the request body in JSON format.

Here is an example usage of this endpoint:

curl -X POST https://{your frappe instance}/api/resource/Lead \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -d '{"lead_name":"Mustermann"}'

GET /api/resource/{DocType}/{DocumentName}

This endpoint retrieves a specific document by its name (ID). The DocType and Document Name of the document to be retrieved are passed as parameters in the path.

Here is an example usage of this endpoint:

curl -X GET https://{your frappe instance}/api/resource/Customer/CUST-00001

PUT /api/resource/{DocType}/{DocumentName}

This endpoint updates a specific document. Only the parts of the document to be changed need to be sent. The DocType and Document Name of the document to be updated are passed as parameters in the path. The details of the update are passed in the request body in JSON format.

Here is an example usage of this endpoint:

curl -X PUT https://{your frappe instance}/api/resource/Lead/LEAD-00001 \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '{"contact_date":"2018-10-08"}'

DELETE /api/resource/{DocType}/{DocumentName}

This endpoint deletes a specific document. The DocType and Document Name of the document to be deleted are passed as parameters in the path.

Conclusion

Understanding DocTypes and Document Names, and their associated API endpoints, is crucial for developers working with Empress. By effectively utilizing these features, developers can greatly enhance their ability to integrate and customize the Empress system.