Model Module is responsible for handling of CRUD operations of documents in the backend.
In addition, it handles the operations associated with documents such as tagging documents & assign users to documents.
It is recommended for better support of types by code assistance in IDEs to usegetFrappeModelController()
in order to get the instance of FrappeModelController
instead of renovation.model
which is ModelController
if the backend is Frappè, for instance. In this guide we will use Frappé as an example and use getFrappeModelController()
Most of the methods in this controller return and/or have arguments of type T
. This means that the object returned or passed is of a class type that extends a class that extends RenovationDocument
, for instance, FrappeDocument
.
To get a single document using its type and name (identifier).
property | type | required | description |
doctype | T | yes | The doctype of the document, e.g: 'Renovation Review' |
docname | String | yes | The name (identifier) of the document, e.g: 'RE-00021' |
forceFetch | bool | no | Fetch the data from the server even if there is cached data |
RequestResponse<T>
RequestResponse<Item> response = await getFrappeModelController().getDoc(RenovationReview,"RE-00002");if (response.isSuccess) {// If the document was successfully retrievedprint(response.data);} else {// If the document was not retrievedprint(response.error);}
HTTP code:
404
type:
NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
HTTP code:
412
type:
DataFormatError
cause: The input arguments are in the wrong type/format
suggestion: Use the correct parameters types/formats referencing the functions signature
To get a list of documents using the doctype, and other optional filters.
property | type | required | description |
doctype | String | yes | The doctype of the list, e.g: 'User' |
fields | String[] | no | The list of docfield names, e.g: ["name", "email", "full_name"]. Use ["*"] if all fields are required. |
orderBy | String | no | Criteria of ordering ('ASC', 'DESC'),default = "modified desc" |
limitPageStart | int | no | Used for pagination. Select which document to start at. default = 0 |
limitPageLength | int | no | Used for pagination . Selects the number of results in the response. default = 99 |
filters |
| no | Can use SQL-like querying |
parent | String | no | If a child table is to be queried, pass the name of the parent document |
tableFields | Map<String,List<String>> | no | To get the fields of the child table fields. Can specify the fields like |
withLinkFields | String[] | no | To get the complete document if a field is of type |
RequestResponse<List<T>>
RequestResponse<List<Item>> response = await getFrappeModelController().getList(User(),{fields: ["*"]});if (response.isSuccess) {// If the document was successfully retrievedprint(response.data);} else {// If the document was not retrievedprint(response.error);}
To get a single value from DB.
property | type | required | description |
doctype | String | yes | The doctype of the document, e.g: 'User' |
docname | String | yes | The name (identifier) of the document, e.g: 'test@abc.com' |
docfield | String | yes | The name of the field to get the value of |
RequestResponse<Map<String,dynamic>>
RequestResponse<Map<String,dynamic>> response = await getFrappeModelController().getValue("User",// doctype"test@abc.com",// docname"email"//docfield);if (response.isSuccess) {// Item Name: {"item_name":"Item A"}print(response.data);} else {// If the document was not retrievedprint(response.error);}
HTTP code:
404
type:
NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
HTTP code:
412
type:
DataFormatError
cause: The input arguments are in the wrong type/format
suggestion: Use the correct parameters types/formats referencing the functions signature
To set a single value from DB.
property | type | required | description |
doctype | T | yes | The doctype of the document, e.g: 'Sales Invoice' |
docname | String | yes | The name (identifier) of the document, e.g: 'SI-00021' |
docfield | String | yes | The name of the field to set the value of |
docValue |
| yes | The value to set the field with |
RequestResponse<T>
Returns the whole document with the field modified.
RequestResponse<RenovationReview> response =await getFrappeModelController().setValue(RenovationReview(), // doctype"RenovationReview A", // docname"reviewed_by", // docfield,"test@abc.com" // docValue);if (response.isSuccess) {// RenovationReview Name: test@abc.comprint("RenovationReview Name: ${response.data}");} else {print(response.error);}
HTTP code:
404
type:
NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
HTTP code:
404
type:
NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
To create a new document with default added properties. Also saves the created document in the local cache.
Default fields:docstatus: 0 // means draft__islocal: 1__unsaved: 1
property | type | required | description |
doc | T | yes | The document object which will be manipulated as a new doc. |
T
Returns the new document including the default values.
User user = getFrappeModelController().newDoc(User());// no need to await// trueprint(user.unsaved);
To save the document in the backend.
property | type | required | description |
doc |
| yes | The document to be saved |
T
RequestResponse<RenovationReview> savedDoc =await getFrappeModelController().saveDoc(getFrappeModelController().newDoc(RenovationReview()));if (savedDoc.isSuccess) {// Renovation Review Name: Renovation Reviewprint(savedDoc.data.name);} else {print(savedDoc.error);}
HTTP code:
409
type:
DuplicateEntryError
cause: Duplicate doc found while saving
suggestion: Change the 'name' field or delete the existing document
To submit the document in the backend.
property | type | required | description |
doc |
| yes | The document to be submitted |
RequestResponse<T>
RequestResponse<RenovationReview> submitedDoc =await getFrappeModelController().submitDoc(getFrappeModelController().newDoc(RenovationReview()));if (submitedDoc.isSuccess) {// RenovationReview Name: RenovationReviewprint(submitedDoc.data.name);} else {print(submitedDoc.error);}
HTTP code:
404
type:
NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
HTTP code:
404
type:
NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
To save the document first, then submit, in a single db transaction.
property | type | required | description |
doc |
| yes | The document to be saved & submitted |
RequestResponse<T>
RequestResponse<RenovationReview> savedSubmittedDoc = await getFrappeModelController().saveSubmitDoc(getFrappeModelController().newDoc(RenovationReview()));if (savedSubmittedDoc.isSuccess) {// Item Name: Test Itemprint(savedSubmittedDoc.data.name);} else {print(savedSubmittedDoc.error);}
HTTP code:
404
type:
NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
HTTP code:
404
type:
NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
To create a cloned document, with a new local name.
The cloned document is also added to the local
cache.
property | type | required | description |
doc |
| yes | The document to be cloned |
T
User clonedDoc = getFrappeModelController().copyDoc(getFrappeModelController().newDoc(RenovationReview()));if (clonedDoc.isSuccess) {print(clonedDoc.data.name);} else {print(clonedDoc.error);}
To clone a document then set amended_from property to the original doc.
property | type | required | description |
doc |
| yes | The document to be cloned |
T
RenovationReview amendedDoc = getFrappeModelController().amendDoc(getFrappeModelController().newDoc(RenovationReview()));if (amendedDoc.isSuccess) {print(amendedDoc.data.amendedFrom);} else {print(amendedDoc.error);}
To delete a document from the backend.
property | type | required | description |
doctype | String | yes | The doctype of the document |
docname | String | yes | The document name to be deleted |
RequestResponse<String>
RequestResponse<String> deletedDoc = await getFrappeModelController().deleteDoc("Renovation Review","RE-00001");if (deletedDoc.isSuccess) {print(deletedDoc.data);} else {print(deletedDoc.error);}
HTTP code:
404
type:
NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
To cancel a submitted document in the backend.
property | type | required | description |
doc |
| yes | The document to be cancelled |
RequestResponse<T>
RequestResponse<String> deletedDoc = await getFrappeModelController().deleteDoc("Renovation Review", "RE-00001");if (cancelledDoc.success) {print(cancelledDoc.data.name);} else {print(cancelledDoc.error);}
HTTP code:
404
type:
NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
HTTP code:
404
type:
NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
To assign a document to a user.
property | type | required | description |
doctype | String | yes | The doctype to assign to |
assignTo | String | yes | The user to be assigned |
docName | String | no | The specific document assigned to |
docNames | String[] | no | The list of documents to be assigned to |
myself | bool | no | Whether the current logged in user is assigned,default = false |
description | String | no | Description of the assignment |
dueDate | String | no | The due date for the assignment |
notify | bool | no | Whether to notify the user, default = false |
priority | Priority | no | The priority to be set for the assignment. Possible values: "Low" | "Medium" | "High" |
bulkAssign | bool | no | Whether to assign in bulk of documents. Use |
Requestresponse<bool>
RequestResponse<bool> assignResponse = await getFrappeModelController().assignDoc(assignTo: "test@abc.com",doctype: "Renovation Review");if (assignResponse.isSuccess) {// trueprint(assignResponse.data);} else {print(assignResponse.error);}
To set the assignment as completed.
property | type | required | description |
doctype | String | yes | The target doctype |
docname | String | yes | The target document having the assignment |
assignTo | String | yes | The user assigned previously to the document to be completed |
RequestResponse<bool>
RequestResponse<bool> completedAssignment = await getFrappeModelController().completeDocAssignment(assignTo: "abc@test.com",doctype: "Renovation Review",docname: "RE-00001");if (completedAssignment.isSuccess) {// trueprint(completedAssignment.data);} else {print(completedAssignment.error);}
To unassign a user from an assignment.
property | type | required | description |
doctype | String | yes | The target doctype |
docname | String | yes | The target document having the assignment |
unAssignFrom | String | yes | The user to be unassigned |
RequestResponse<bool>
RequestResponse<bool> unassigned = await getFrappeModelController().unAssignDoc(unAssignFrom: "abc@test.com",doctype: "Renovation Review",docname: "RE-00001"});if (unassigned.isSuccess) {// trueprint(unassigned.data);} else {print(unassigned.error);}
To get the documents that are assigned to a user.
property | type | required | description |
assignedTo | String | yes | The target user |
doctype | String | no | The target doctype |
status | Status | no | Whether to query the status is "Open" or "Closed" |
RequestResponse<List<GetDocsAssignedToUserResponse>>
RequestResponse<List<GetDocsAssignedToUserResponse>> docsAssigned =await getFrappeModelController().getDocsAssignedToUser(assignedTo: "test@abc.com");if (docsAssigned.isSuccess) {// Number of docs: 3print(docsAssigned.data.length);// Doctype: Renovation Reviewprint(docsAssigned.data[0].doctype);} else {print(docsAssigned.error);}
To get the users assigned to a document.
property | type | required | description |
doctype | String | yes | The target doctype |
docName | String | yes | The target document |
RequestResponse<List<ToDo>>
RequestResponse<List<ToDo>> usersAssigned = await getFrappeModelController().getUsersAssignedToDoc(doctype: "Renovation Review",docname: "RE-00001");if (usersAssigned.isSuccess) {// Number of users: 2print("Number of users: ${usersAssigned.data.length}");} else {print(usersAssigned.error);}
To add a tag to a document.
If the tag exists, a success is returned silently.
property | type | required | description |
doctype | String | yes | The target doctype |
docname | String | yes | The target document |
tag | String | yes | The tag to be added |
RequestResponse<String>
RequestResponse<String> addedTag = await getFrappeModelController().addTag(doctype: "Renovation Review",docname: "RE-00001",tag: "test-tag");if (addedTag.isSuccess) {// Tag added: test-tagprint("Tag added: ${addedTag.data}");} else {print(addedTag.error);}
HTTP code:
404
type:
NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
HTTP code:
404
type:
NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
To remove a tag from a document.
property | type | required | description |
doctype | String | yes | The target doctype |
docname | String | yes | The target document |
tag | String | yes | The tag to be removed |
RequestResponse<String>
If the tag doesn't exist, a success is returned silently.
RequestResponse<String> removedTag = await getFrappeModelController().removeTag(doctype: "Renovation Review",docname: "RE-00001",tag: "test-tag");if (removedTag.isSuccess) {// Tag removedprint("Tag removed");} else {print(removedTag.error);}
HTTP code:
404
type:
NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
HTTP code:
404
type:
NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
To get all the tagged documents of a certain doctype.
property | type | required | description |
doctype | String | yes | The target doctype |
tag | String | no | The target tag |
RequestResponse<List<String>>
The names of the documents as a list.
RequestResponse<List<String>> taggedDocs = await getFrappeModelController().getTaggedDocs(doctype: "Renovation Review",tag: "test-tag");if (taggedDocs.isSuccess) {// Number of documents: 3print("Number of documents: ${taggedDocs.data.length");} else {print(taggedDocs.error);}
HTTP code:
404
type:
NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
To get all the tags of a doctype.
property | type | required | description |
doctype | String | yes | The target doctype |
likeTag | String | no | Optionally the tag-like string (Using |
RequestResponse<List<String>>
RequestResponse<List<String>> tags = await getFrappeModelController().getTags(doctype: "Renovation Review",likeTag: "test-");if (tags.isSuccess) {// Number of documents: 3print("Number of tags: ${tags.data.length}");} else {print(tags.error);}
HTTP code:
404
type:
NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
To get report values of type Renovation Report
property | type | required | description |
report | String | yes | The name of the report |
filters |
| no | Filters to apply on the report |
user | String | no | The target user. Defaults to |
RequestResponse<FrappeReport>
RequestResponse<FrappeReport> report = await getFrappeModelController().getReport(report: "Test Report",filters: {},user: null);if (report.isSuccess) {// Display the report's data as required in the UI, for instance.// report.result// report.columns} else {print(report.error);}
HTTP code:
404
type:
NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
To search for Link field values.
property | type | required | description |
doctype | String | yes | The name of the doctype |
txt | String | yes | The search txt to search for |
options | Map<String,dynamic> | no | Other options accepted by the API |
RequestResponse<List<SearchLinkResponse>>
RequestResponse<List<SearchLinkResponse>> searchResults =await getFrappeModelController().searchLink(doctype: "User", txt: "@abc.com");if (searchResults.isSuccess) {// Search results: 2print("Search results: ${searchResults.data.length}");} else {print(searchResults.error);}
HTTP code:
404
type:
NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType