.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

RequestResponse<Item> response = await getFrappeModelController()
.getDoc(RenovationReview,"RE-00002");
​
if (response.isSuccess) {
// If the document was successfully retrieved
print(response.data);
} else {
// If the document was not retrieved
print(response.error);
}

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

RequestResponse<List<Item>> response = await getFrappeModelController()
.getList(User(),{
fields: ["*"]
});
if (response.isSuccess) {
// If the document was successfully retrieved
print(response.data);
} else {
// If the document was not retrieved
print(response.error);
}

.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: 'test@abc.com'

docfield

String

yes

The name of the field to get the value of

Output

RequestResponse<Map<String,dynamic>>

Example

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 retrieved
print(response.error);
}

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

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.com
print("RenovationReview Name: ${response.data}");
} else {
print(response.error);
}

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.

Default fields:
docstatus: 0 // means draft
__islocal: 1
__unsaved: 1

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

User user = getFrappeModelController().newDoc(
User()
);// no need to await
​
// true
print(user.unsaved);

.saveDoc() β˜†

To save the document in the backend.

Input

property

type

required

description

doc

T

yes

The document to be saved

Output

T

Example

RequestResponse<RenovationReview> savedDoc =
await getFrappeModelController().saveDoc(
getFrappeModelController().newDoc(RenovationReview())
);
​
if (savedDoc.isSuccess) {
// Renovation Review Name: Renovation Review
print(savedDoc.data.name);
} else {
print(savedDoc.error);
}

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

RequestResponse<RenovationReview> submitedDoc =
await getFrappeModelController().submitDoc(
getFrappeModelController().newDoc(RenovationReview())
);
​
if (submitedDoc.isSuccess) {
// RenovationReview Name: RenovationReview
print(submitedDoc.data.name);
} else {
print(submitedDoc.error);
}

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

RequestResponse<RenovationReview> savedSubmittedDoc = await getFrappeModelController().saveSubmitDoc(
getFrappeModelController().newDoc(RenovationReview())
);
​
if (savedSubmittedDoc.isSuccess) {
// Item Name: Test Item
print(savedSubmittedDoc.data.name);
} else {
print(savedSubmittedDoc.error);
}

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

User clonedDoc = getFrappeModelController().copyDoc(
getFrappeModelController().newDoc(RenovationReview())
);
​
if (clonedDoc.isSuccess) {
print(clonedDoc.data.name);
} else {
print(clonedDoc.error);
}

.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

RenovationReview amendedDoc = getFrappeModelController().amendDoc(
getFrappeModelController().newDoc(RenovationReview())
);
​
if (amendedDoc.isSuccess) {
print(amendedDoc.data.amendedFrom);
} else {
print(amendedDoc.error);
}

.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

RequestResponse<String> deletedDoc = await getFrappeModelController().deleteDoc("Renovation Review","RE-00001");
​
if (deletedDoc.isSuccess) {
print(deletedDoc.data);
} else {
print(deletedDoc.error);
}

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

RequestResponse<String> deletedDoc = await getFrappeModelController()
.deleteDoc("Renovation Review", "RE-00001");
​
if (cancelledDoc.success) {
print(cancelledDoc.data.name);
} else {
print(cancelledDoc.error);
}

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

RequestResponse<bool> assignResponse = await getFrappeModelController().assignDoc(
assignTo: "test@abc.com",
doctype: "Renovation Review"
);
​
if (assignResponse.isSuccess) {
// true
print(assignResponse.data);
} else {
print(assignResponse.error);
}

.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

RequestResponse<bool> completedAssignment = await getFrappeModelController().completeDocAssignment(
assignTo: "abc@test.com",
doctype: "Renovation Review",
docname: "RE-00001"
);
​
if (completedAssignment.isSuccess) {
// true
print(completedAssignment.data);
} else {
print(completedAssignment.error);
}

.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

RequestResponse<bool> unassigned = await getFrappeModelController().unAssignDoc(
unAssignFrom: "abc@test.com",
doctype: "Renovation Review",
docname: "RE-00001"
});
​
if (unassigned.isSuccess) {
// true
print(unassigned.data);
} else {
print(unassigned.error);
}

.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

RequestResponse<List<GetDocsAssignedToUserResponse>> docsAssigned =
await getFrappeModelController()
.getDocsAssignedToUser(assignedTo: "test@abc.com");
​
if (docsAssigned.isSuccess) {
// Number of docs: 3
print(docsAssigned.data.length);
// Doctype: Renovation Review
print(docsAssigned.data[0].doctype);
} else {
print(docsAssigned.error);
}

.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

RequestResponse<List<ToDo>> usersAssigned = await getFrappeModelController()
.getUsersAssignedToDoc(
doctype: "Renovation Review",
docname: "RE-00001"
);
​
if (usersAssigned.isSuccess) {
// Number of users: 2
print("Number of users: ${usersAssigned.data.length}");
} else {
print(usersAssigned.error);
}

.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

RequestResponse<String> addedTag = await getFrappeModelController().addTag(
doctype: "Renovation Review",
docname: "RE-00001",
tag: "test-tag"
);
​
if (addedTag.isSuccess) {
// Tag added: test-tag
print("Tag added: ${addedTag.data}");
} else {
print(addedTag.error);
}

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

RequestResponse<String> removedTag = await getFrappeModelController().removeTag(
doctype: "Renovation Review",
docname: "RE-00001",
tag: "test-tag"
);
​
if (removedTag.isSuccess) {
// Tag removed
print("Tag removed");
} else {
print(removedTag.error);
}

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

RequestResponse<List<String>> taggedDocs = await getFrappeModelController().getTaggedDocs(
doctype: "Renovation Review",
tag: "test-tag"
);
​
if (taggedDocs.isSuccess) {
// Number of documents: 3
print("Number of documents: ${taggedDocs.data.length");
} else {
print(taggedDocs.error);
}

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

RequestResponse<List<String>> tags = await getFrappeModelController().getTags(
doctype: "Renovation Review",
likeTag: "test-"
);
​
if (tags.isSuccess) {
// Number of documents: 3
print("Number of tags: ${tags.data.length}");
} else {
print(tags.error);
}

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

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);
}

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

RequestResponse<List<SearchLinkResponse>> searchResults =
await getFrappeModelController()
.searchLink(doctype: "User", txt: "@abc.com");
if (searchResults.isSuccess) {
// Search results: 2
print("Search results: ${searchResults.data.length}");
} else {
print(searchResults.error);
}

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