App
This class allows a server script to access data and check permissions, and it provides other functionality specific to App Maker.
var userRoles = app.getActiveUserRoles(); if (userRoles.indexOf(app.roles.Admins) >= 0) { // Create admin-only application settings record. var settings = app.models.Settings.newRecord(); app.saveRecords([settings]); }
This class is only available in App Maker applications. See Apps Script reference for all other general classes available in App Maker applications.
Properties
Name | Type | Description |
---|---|---|
roles |
string[string] |
All user roles defined in this application.
if (userRoles.indexOf(app.roles.Admins) < 0) { throw 'Access denied'; } |
models |
Model[string] |
All data models defined in the application.
var record = app.models.Person.newRecord(); app.saveRecords([record]); |
metadata |
Metadata |
All metadata defined in the application.
var displayField = app.metadata.models.model1.displayField; |
ManagedError |
function(message: String) |
Display a custom error message.
throw new app.ManagedError("Custom message shown to app users"); |
transaction |
Transaction |
Controls transactions in Cloud SQL models.
app.transaction.cloudSql.start(app.transaction.cloudSql.isolation.REPEATABLE_READ); |
Methods
Name | Return Value | Description |
---|---|---|
getActiveUserRoles() |
string[] |
Returns roles of the current user. Also see Session.getActiveUser().
var roles = app.getActiveUserRoles(); if (roles.indexOf(app.roles.Admins) < 0) { throw 'Access denied'; } |
saveRecords(
|
undefined |
Creates new records from drafts (if record's _key field is null ) or updates existing records (_key is not null ). Sets _key field for newly created records.
var record = app.models.Person.newRecord(); app.saveRecords([record]); |
deleteRecords( |
undefined |
Deletes records.
var record = app.models.Person.getRecord(key); app.deleteRecords([record]); |
getRoleMembers(role:string) |
string[] |
Returns all members that belong to a specific role.
var role = app.roles.Admins; var members = app.getRoleMembers(role); Doesn't return individual members of a group that you've added to a role. |
Association
This class represents an association between two records, one in the model on one end of a specific relation, and the other in the model on the other end. (This might be the same model.)
Each association consists of two keys, which identify the records that are associated.
This class is only available in App Maker applications. See Apps Script reference for all other general classes available in App Maker applications.
Properties
Name | Type | Description |
---|---|---|
sourceKey |
string |
The key of the record in the model on the source end of the relation. Use Record._sourceKey to access the record. |
targetKey |
string |
The key of the record in the model on the target end of the relation. Use Record._targetKey to access the record. |
To identify which end of a relation is the source and which is the target, look at the Security tab for a model in the relation. Relation permissions have titles such as Employee + Department. Employee and Department are names of the ends of the relation. The model corresponding to the first relation end is the source model, and the model corresponding to the second relation end is the target model.
Model
This class represents a data model in App Maker. It allows a script to access data records of this model.
This class is only available in App Maker applications. See Apps Script reference for all other general classes available in App Maker applications.
Methods
Name | Return Value | Description |
---|---|---|
deleteRecords(
|
undefined |
Deletes several records by their keys. |
getRecord(
|
Record |
Loads a record by key. |
getRecords(
|
Record[] |
Loads several records by their keys. Can return fewer records if some keys could not be found. Returned records are ordered in the same order as keys were passed. |
newQuery() |
Query |
Creates a query to load records of the current model that match certain criteria.
var query = app.models.Person.newQuery(); query.filters.Name._startsWith = 'John'; query.filters.Age._greaterThan = 20; query.sorting.Name._ascending(); query.sorting.Age._descending(); var records = query.run(); |
newRecord() |
Record |
Creates a new unsaved record (draft record). The _key field of the new record will be null until the record is saved.
var record = app.models.Person.newRecord(); app.saveRecords([record]); |
Query
This class represents a data query in App Maker. It allows a script to control the filtering, sorting, and paging of data records. When a user initiates a query, App Maker applies ownership filters to the query and checks the permissions of results before returning them to the user.
This class is only available in App Maker applications. See Apps Script reference for all other general classes available in App Maker applications.
Properties
Name | Type | Description |
---|---|---|
filters |
Dynamic |
Adds filters to the query. Supported filters: equals, notEquals, lessThan, greaterThan, lessThanOrEquals, greaterThanOrEquals, in, notIn, startsWith, notStartsWith, contains, notContains .
var query = app.models.Person.newQuery(); query.filters.Name._startsWith = 'John'; query.filters.Age._greaterThan = 20; var records = query.run(); Filters Filters Filters When you query directory models, you can use only certain filters. For a complete list, see User fields and query operators. |
limit |
number |
Sets maximum number of records to return for the query. |
offset |
number |
Sets the number of records to skip and not include in query result. |
parameters |
Dynamic |
Provides access to custom parameters in Query Script. |
sorting |
Dynamic |
Adds sorting to the query.
var query = app.models.Person.newQuery(); query.sorting.Name._ascending(); query.sorting.Age._descending(); var records = query.run(); |
prefetch |
Dynamic |
Adds prefetch to the query. Prefetch will ensure that related records are loaded in the same request with the query, instead of loading them on demand later when they're accessed. Prefetch reduces the total number of requests, at the cost of a more expensive initial query, which can improve performance.
var query = app.models.Employee.newQuery(); query.prefetch.Manager._add(); query.prefetch.Manager.Reports._add(); var records = query.run(); for (var i in records) { var manager = records[i].Manager; // No extra call to DB var reports = manager.Reports; // No extra call to DB ... } |
Methods
Name | Return Value | Description |
---|---|---|
run() |
Record[] |
Executes the query, returns the records that match query criteria.
var query = app.models.Person.newQuery(); query.filters.Name._startsWith = 'John'; query.filters.Name._ascending(); var persons = query.run(); |
Record
This class represents a data record in App Maker. It allows a script to access record fields and related records.
This class is only available in App Maker applications. See Apps Script reference for all other general classes available in App Maker applications.
Properties
Name | Type | Description |
---|---|---|
_key |
string |
Record key is only unique within given model. Key is generated when record is saved, and is null for new unsaved records (draft records). |
<field> |
Dynamic |
There is a field for each record field or relation. Any-to-1 relations are represented by simple fields, while Any-to-N relations are represented by arrays.
var person = app.models.Person.newRecord(); person.name = 'John Doe'; person.age = 35; app.saveRecords([person]); var manager = app.models.Person.newRecord(); manager.name = 'Jeff Williams'; manager.age = 45; app.saveRecords([manager]); // You must save new record before using it in relations. person.manager = manager; app.saveRecords([person]); |
Metadata
This class represents all metadata in the application. It allows a script to access the metadata of this application.
This class is only available in App Maker applications. See Apps Script reference for all other general classes available in App Maker applications.
Properties
Name | Type | Description |
---|---|---|
models |
ModelMetadata[string] |
All models defined in the application. |
ModelMetadata
This class represents a metadata model in App Maker. It allows a script to access the metadata of this model.
This class is only available in App Maker applications. See Apps Script reference for all other general classes available in App Maker applications.
Properties
Name | Type | Description |
---|---|---|
description |
string |
The description of the model, as specified in the Model Editor. |
displayField |
Field[string] |
The display field of a model. Can be null. |
fields |
Field[string] |
All fields defined in the model. |
name |
string |
The name of the model, as specified in the Model Editor. |
readOnly |
bool |
Whether a model is read-only. If a model is read-only, data cannot be written to this model. |
relations |
Relation[string] |
All relations coming from a given model. |
type |
string |
The database type of a model: Calculated, Cloud SQL or Directory. |
Field
This class represents a field in App Maker. It allows a script to access a field of this model.
This class is only available in App Maker applications. See Apps Script reference for all other general classes available in App Maker applications.
Properties
Name | Type | Description |
---|---|---|
autoIncrement |
bool |
Whether the field is auto-incremented by the database. |
defaultValue |
Dynamic |
The default value of the field. Can be null. |
description |
string |
The description of the field. Can be null. |
displayName |
string |
The display name of the field. Can be null. |
key |
string |
The key of this field. |
maxLength |
number |
The maximum length of the value in characters. Can be null. |
maxValue |
number|date |
The maximum value of the field. Can be null. |
minLength |
number |
The minimum length of the value in characters. Can be null. |
minValue |
number|date |
The minimum value of the field. Can be null. |
name |
string |
The name of the field. |
possibleValues |
Dynamic[] |
Display all possible values of the field. Can be null. |
regexp |
string |
A regular expression that all valid values must match. Can be null. |
regexpError |
string |
The error message to show to the user if the regular expression does not match the user input. An occurrence of '%s' in the error message will be substituted with the user input. Can be null. |
required |
bool |
Whether the field is required. |
type |
string |
The type of the field: String, Number, Date, or Boolean. |
wholeNumber |
bool |
Whether the number in the field is whole. A number is whole if it does not contain significant decimal places. |
Relation
This class represents one side of a relation from the specified model to another in App Maker. It allows a script to access a relation of this model.
This class is only available in App Maker applications. See Apps Script reference for all other general classes available in App Maker applications.
Properties
Name | Type | Description |
---|---|---|
ascending |
bool |
If the "sort-by" field of the end model is sorted in ascending order. |
count |
string |
The count of a model ("One", "Many"). |
model |
ModelMetadata |
The end model of a relation. |
name |
string |
The end name of a relation. |
owner |
bool |
Whether the end model owns the relation. For example, if an "Invoice" owns its "Items", then |
sortBy |
Field |
The field by which the end model is sorted. Can be null. |
Transaction
Provides access to the Transaction API in App Maker. Available only in applications that have at least one Cloud SQL model.
Properties
Name | Type | Description |
---|---|---|
cloudSql |
CloudSqlTransaction |
Controls transactions in Cloud SQL models. |
TransactionError |
function(message:String) |
Exception that indicates a transaction error has occurred. |
CloudSqlTransaction
This type allows a script to start, commit, rollback, and check the status of database transactions in Cloud SQL models.
Properties
Name | Type | Description |
---|---|---|
isolation |
IsolationLevel |
Enumeration of possible Isolation levels. |
lockOnRead |
LockMode |
Enumeration of possible Lock On Read modes to set via setLockOnRead(). |
Methods
Name | Return Value | Description |
---|---|---|
isStarted() |
bool |
Whether a transaction is currently in progress.
app.transaction.cloudSql.isStarted(); |
start
|
undefined |
Starts a transaction. Throws an error if another transaction is already in progress.
app.transaction.cloudSql.start( app.transaction.cloudSql.isolation.REPEATABLE_READ); Parameter is optional; |
commit() |
undefined |
Commits the current transaction. Throws an error if app attempts to commit before a transaction has started. app.transaction.cloudSql.commit(); |
rollback() |
undefined |
Reverts all changes in the current transaction and releases any database locks. Throws an error if app attempts to rollback before a transaction has started.
app.transaction.cloudSql.rollback(); |
setLockOnRead(
|
undefined |
Applies specified lock mode for all database reads until the transaction is completed or the lock mode is changed with the method.
app.transaction.cloudSql.setLockOnRead( app.transaction.cloudSql.lockOnRead.UPDATE); |
IsolationLevel
Enumeration of possible isolation levels.
Properties
Name | Type | Description |
---|---|---|
READ_UNCOMMITTED |
IsolationLevel |
Current transaction can view unsubmitted changes of other transactions. Learn more. |
READ_COMMITTED |
IsolationLevel |
Current transaction can view submitted changes of other transactions. Learn more. |
REPEATABLE_READ |
IsolationLevel |
Current transaction can view submitted changes of other transactions. Guarantees that all repeatable reads of a record will returns records in the same state. Learn more. |
SERIALIZABLE |
IsolationLevel |
Current transaction is completely isolated from other transactions. Transactions run sequentially. Learn more. |
LockMode
Enumeration of possible locking read modes to set with setLockOnRead()
.
Properties
Name | Type | Description |
---|---|---|
NO_LOCK |
LockMode |
No locks applied. Default mode. |
SHARE |
LockMode |
Other transactions can read data locked by the current transaction, but they can't modify it. |
UPDATE |
LockMode |
Other transactions can't read or modify data locked by the current transaction. |