Renovation
Search…
.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
Last modified 1yr ago