.model

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.
Things to know
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 .
.getDoc() ☆
To get a single document using its type and name (identifier).
Input
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
Output
RequestResponse<T>
Example
1
RequestResponse<Item> response = await getFrappeModelController()
2
  .getDoc(RenovationReview,"RE-00002");
3
​
4
  if (response.isSuccess) {
5
    // If the document was successfully retrieved
6
    print(response.data);
7
  } else {
8
    // If the document was not retrieved
9
    print(response.error);
10
  }
Copied!
Possible Errors
Non-existing document
HTTP code: 404
type: NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
Wrong input
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
.getList() ☆
To get a list of documents using the doctype, and other optional filters.
Input
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
dynamic
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 fields
withLinkFields
String[]
no
To get the complete document if a field is of type Link (Another document)
Output
RequestResponse<List<T>>
Example
1
RequestResponse<List<Item>> response = await getFrappeModelController()
2
  .getList(User(),{
3
    fields: ["*"]
4
  });
5
  if (response.isSuccess) {
6
    // If the document was successfully retrieved
7
    print(response.data);
8
  } else {
9
    // If the document was not retrieved
10
    print(response.error);
11
  }
Copied!
.getValue()
To get a single value from DB.
Input
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: '[email protected]'
docfield
String
yes
The name of the field to get the value of
Output
RequestResponse<Map<String,dynamic>>
Example
1
RequestResponse<Map<String,dynamic>> response = await getFrappeModelController().getValue(
2
  "User",// doctype
3
  "[email protected]",// docname
4
  "email"//docfield
5
);
6
if (response.isSuccess) {
7
    // Item Name: {"item_name":"Item A"}
8
    print(response.data);
9
  } else {
10
    // If the document was not retrieved
11
    print(response.error);
12
  }
Copied!
Possible Errors
Non-existing document
HTTP code: 404
type: NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
Wrong input
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
.setValue()
To set a single value from DB.
Input
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
dynamic
yes
The value to set the field with
Output
RequestResponse<T>
Returns the whole document with the field modified.
Example
1
RequestResponse<RenovationReview> response =
2
      await getFrappeModelController().setValue(
3
          RenovationReview(), // doctype
4
          "RenovationReview A", // docname
5
          "reviewed_by", // docfield,
6
          "[email protected]" // docValue
7
          );
8
if (response.isSuccess) {
9
    // RenovationReview Name: [email protected]
10
    print("RenovationReview Name: ${response.data}");
11
} else {
12
    print(response.error);
13
}
Copied!
Possible Errors
Doctype Does Not Exist
HTTP code: 404
type: NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
Docname Does Not Exist
HTTP code: 404
type: NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
.newDoc()
To create a new document with default added properties. Also saves the created document in the local cache.
1
 Default fields:
2
 docstatus: 0 // means draft
3
 __islocal: 1
4
 __unsaved: 1
Copied!
Input
property
type
required
description
doc
T
yes
The document object which will be manipulated as a new doc.
Output*
T
Returns the new document including the default values.
Example
1
User user = getFrappeModelController().newDoc(
2
    User()
3
  );// no need to await
4
​
5
// true
6
print(user.unsaved);
Copied!
.saveDoc() ☆
To save the document in the backend.
Input
property
type
required
description
doc
T
yes
The document to be saved
Output
T
Example
1
RequestResponse<RenovationReview> savedDoc = 
2
    await getFrappeModelController().saveDoc(
3
      getFrappeModelController().newDoc(RenovationReview())
4
    );
5
​
6
if (savedDoc.isSuccess) {
7
  // Renovation Review Name: Renovation Review
8
  print(savedDoc.data.name);
9
} else {
10
  print(savedDoc.error);
11
}
Copied!
Possible Errors
Duplicate document found
HTTP code: 409
type: DuplicateEntryError
cause: Duplicate doc found while saving
suggestion: Change the 'name' field or delete the existing document
.submitDoc()
To submit the document in the backend.
Input
property
type
required
description
doc
T
yes
The document to be submitted
Output
RequestResponse<T>
Example
1
RequestResponse<RenovationReview> submitedDoc = 
2
    await getFrappeModelController().submitDoc(
3
      getFrappeModelController().newDoc(RenovationReview())
4
    );
5
​
6
if (submitedDoc.isSuccess) {
7
  // RenovationReview Name: RenovationReview
8
  print(submitedDoc.data.name);
9
} else {
10
  print(submitedDoc.error);
11
}
Copied!
Possible Errors
Doctype Does Not Exist
HTTP code: 404
type: NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
Non-existing document
HTTP code: 404
type: NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
.saveSubmitDoc() ★
To save the document first, then submit, in a single db transaction.
Input
property
type
required
description
doc
T
yes
The document to be saved & submitted
Output
RequestResponse<T>
Example
1
RequestResponse<RenovationReview> savedSubmittedDoc = await getFrappeModelController().saveSubmitDoc(
2
    getFrappeModelController().newDoc(RenovationReview())
3
  );
4
​
5
if (savedSubmittedDoc.isSuccess) {
6
  // Item Name: Test Item
7
  print(savedSubmittedDoc.data.name);
8
} else {
9
  print(savedSubmittedDoc.error);
10
}
Copied!
Possible Errors
Doctype Does Not Exist
HTTP code: 404
type: NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
Non-existing document
HTTP code: 404
type: NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
.copyDoc()
To create a cloned document, with a new local name.
The cloned document is also added to the local cache.
Input
property
type
required
description
doc
T
yes
The document to be cloned
Output
T
Example
1
User clonedDoc = getFrappeModelController().copyDoc(
2
    getFrappeModelController().newDoc(RenovationReview())
3
  );
4
​
5
if (clonedDoc.isSuccess) {
6
  print(clonedDoc.data.name);
7
} else {
8
  print(clonedDoc.error);
9
}
Copied!
.amendDoc()
To clone a document then set amended_from property to the original doc.
Input
property
type
required
description
doc
T
yes
The document to be cloned
Output
T
Example
1
RenovationReview amendedDoc = getFrappeModelController().amendDoc(
2
    getFrappeModelController().newDoc(RenovationReview())
3
  );
4
​
5
if (amendedDoc.isSuccess) {
6
  print(amendedDoc.data.amendedFrom);
7
} else {
8
  print(amendedDoc.error);
9
}
Copied!
.deleteDoc()
To delete a document from the backend.
Input
property
type
required
description
doctype
String
yes
The doctype of the document
docname
String
yes
The document name to be deleted
Output
RequestResponse<String>
Example
1
RequestResponse<String> deletedDoc = await getFrappeModelController().deleteDoc("Renovation Review","RE-00001");
2
​
3
if (deletedDoc.isSuccess) {
4
  print(deletedDoc.data);
5
} else {
6
  print(deletedDoc.error);
7
}
Copied!
Possible Errors
Non-existing document
HTTP code: 404
type: NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
.cancelDoc()
To cancel a submitted document in the backend.
Input
property
type
required
description
doc
T
yes
The document to be cancelled
Output
RequestResponse<T>
Example
1
RequestResponse<String> deletedDoc = await getFrappeModelController()
2
      .deleteDoc("Renovation Review", "RE-00001");
3
​
4
if (cancelledDoc.success) {
5
  print(cancelledDoc.data.name);
6
} else {
7
  print(cancelledDoc.error);
8
}
Copied!
Possible Errors
Doctype Does Not Exist
HTTP code: 404
type: NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
Non-existing document
HTTP code: 404
type: NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
.assignDoc()
To assign a document to a user.
Input
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 docnames instead while using bulkAssign, default = false
Output
Requestresponse<bool>
Example
1
RequestResponse<bool> assignResponse = await getFrappeModelController().assignDoc(
2
    assignTo: "[email protected]",
3
    doctype: "Renovation Review"
4
  );
5
​
6
if (assignResponse.isSuccess) {
7
  // true
8
  print(assignResponse.data);
9
} else {
10
  print(assignResponse.error);
11
}
Copied!
.completeDocAssignment()
To set the assignment as completed.
Input
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
Output
RequestResponse<bool>
Example
1
RequestResponse<bool> completedAssignment = await getFrappeModelController().completeDocAssignment(
2
    assignTo: "[email protected]",
3
    doctype: "Renovation Review",
4
    docname: "RE-00001"
5
  );
6
​
7
if (completedAssignment.isSuccess) {
8
  // true
9
  print(completedAssignment.data);
10
} else {
11
  print(completedAssignment.error);
12
}
Copied!
.unAssignDoc()
To unassign a user from an assignment.
Input
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
Output
RequestResponse<bool>
Example
1
RequestResponse<bool> unassigned = await getFrappeModelController().unAssignDoc(
2
  unAssignFrom: "[email protected]",
3
  doctype: "Renovation Review",
4
  docname: "RE-00001"
5
});
6
​
7
if (unassigned.isSuccess) {
8
  // true
9
  print(unassigned.data);
10
} else {
11
  print(unassigned.error);
12
}
Copied!
.getDocsAssignedToUser() ★
To get the documents that are assigned to a user.
Input
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"
Output
RequestResponse<List<GetDocsAssignedToUserResponse>>
Example
1
RequestResponse<List<GetDocsAssignedToUserResponse>> docsAssigned =
2
      await getFrappeModelController()
3
          .getDocsAssignedToUser(assignedTo: "[email protected]");
4
​
5
if (docsAssigned.isSuccess) {
6
  // Number of docs: 3
7
  print(docsAssigned.data.length);
8
  // Doctype: Renovation Review
9
  print(docsAssigned.data[0].doctype);
10
} else {
11
  print(docsAssigned.error);
12
}
Copied!
.getUsersAssignedToDoc()
To get the users assigned to a document.
Input
property
type
required
description
doctype
String
yes
The target doctype
docName
String
yes
The target document
Output
RequestResponse<List<ToDo>>
Example
1
RequestResponse<List<ToDo>> usersAssigned = await getFrappeModelController()
2
        .getUsersAssignedToDoc(
3
          doctype: "Renovation Review",
4
          docname: "RE-00001"
5
        );
6
​
7
if (usersAssigned.isSuccess) {
8
  // Number of users: 2
9
  print("Number of users: ${usersAssigned.data.length}");
10
} else {
11
  print(usersAssigned.error);
12
}
Copied!
.addTag()
To add a tag to a document.
If the tag exists, a success is returned silently.
Input
property
type
required
description
doctype
String
yes
The target doctype
docname
String
yes
The target document
tag
String
yes
The tag to be added
Output
RequestResponse<String>
Example
1
RequestResponse<String> addedTag = await getFrappeModelController().addTag( 
2
  doctype: "Renovation Review",
3
  docname: "RE-00001",
4
  tag: "test-tag"
5
);
6
​
7
if (addedTag.isSuccess) {
8
  // Tag added: test-tag
9
  print("Tag added: ${addedTag.data}");
10
} else {
11
  print(addedTag.error);
12
}
Copied!
Possible Errors
Doctype Does Not Exist
HTTP code: 404
type: NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
Non-existing document
HTTP code: 404
type: NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
.removeTag()
To remove a tag from a document.
Input
property
type
required
description
doctype
String
yes
The target doctype
docname
String
yes
The target document
tag
String
yes
The tag to be removed
Output
RequestResponse<String>
If the tag doesn't exist, a success is returned silently.
Example
1
RequestResponse<String> removedTag = await getFrappeModelController().removeTag( 
2
  doctype: "Renovation Review",
3
  docname: "RE-00001",
4
  tag: "test-tag"
5
);
6
​
7
if (removedTag.isSuccess) {
8
  // Tag removed
9
  print("Tag removed");
10
} else {
11
  print(removedTag.error);
12
}
Copied!
Possible Errors
Doctype Does Not Exist
HTTP code: 404
type: NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
Non-existing document
HTTP code: 404
type: NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
.getTaggedDocs()
To get all the tagged documents of a certain doctype.
Input
property
type
required
description
doctype
String
yes
The target doctype
tag
String
no
The target tag
Output
RequestResponse<List<String>>
The names of the documents as a list.
Example
1
RequestResponse<List<String>> taggedDocs = await getFrappeModelController().getTaggedDocs( 
2
  doctype: "Renovation Review",
3
  tag: "test-tag"
4
);
5
​
6
if (taggedDocs.isSuccess) {
7
  // Number of documents: 3
8
  print("Number of documents: ${taggedDocs.data.length");
9
} else {
10
  print(taggedDocs.error);
11
}
Copied!
Possible Errors
Doctype Does Not Exist
HTTP code: 404
type: NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
.getTags()
To get all the tags of a doctype.
Input
property
type
required
description
doctype
String
yes
The target doctype
likeTag
String
no
Optionally the tag-like string (Using LIKE of SQL)
Output
RequestResponse<List<String>>
Example
1
RequestResponse<List<String>> tags = await getFrappeModelController().getTags(
2
  doctype: "Renovation Review",
3
  likeTag: "test-"
4
);
5
​
6
if (tags.isSuccess) {
7
  // Number of documents: 3
8
  print("Number of tags: ${tags.data.length}");
9
} else {
10
  print(tags.error);
11
}
Copied!
Possible Errors
Doctype Does Not Exist
HTTP code: 404
type: NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType
.getReport() ★
To get report values of type Renovation Report
Input
property
type
required
description
report
String
yes
The name of the report
filters
dynamic
no
Filters to apply on the report
user
String
no
The target user. Defaults to null
Output
RequestResponse<FrappeReport>
Example
1
RequestResponse<FrappeReport> report = await getFrappeModelController().getReport(
2
  report: "Test Report",
3
  filters: {},
4
  user: null
5
);
6
​
7
if (report.isSuccess) {
8
  // Display the report's data as required in the UI, for instance.
9
  // report.result
10
  // report.columns
11
} else {
12
  print(report.error);
13
}
Copied!
Possible Errors
Non-existing document
HTTP code: 404
type: NotFoundError
cause: Docname does not exist
suggestion: Make sure the queried document name is correct or create the required document
.searchLink()
To search for Link field values.
Input
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
Output
RequestResponse<List<SearchLinkResponse>>
Example
1
RequestResponse<List<SearchLinkResponse>> searchResults =
2
      await getFrappeModelController()
3
          .searchLink(doctype: "User", txt: "@abc.com");
4
          
5
if (searchResults.isSuccess) {
6
  // Search results: 2
7
  print("Search results: ${searchResults.data.length}");
8
} else {
9
  print(searchResults.error);
10
}
Copied!
Possible Errors
Doctype Does Not Exist
HTTP code: 404
type: NotFoundError
cause: DocType does not exist
suggestion: Make sure the queried DocType is input correctly or create the required DocType