The App Maker editor and user apps will be shut down on January 19, 2021. New application creation is disabled. Learn more

App Maker Server API

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(
  records:Record[])		 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(
  records:Record[])		 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(
  keys:string[])		 undefined Deletes several records by their keys.
getRecord(
  key:string)		 Record Loads a record by key.
getRecords(
  keys:string[])		 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 in and notIn check that the value in the field equals (or doesn't equal) any value in a given array.

Filters startsWith, notStartsWith, contains, notContains are only supported for strings and lists of strings.

Filters lessThan, greaterThan, lessThanOrEquals, greaterThanOrEquals are only supported for numbers, dates, and strings; and for the corresponding list data types.

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 app.metadata.models.Items.relations.Invoice.owner would be true.
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
level:IsolationLevel)		 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; READ_COMMITTED is the default if no value is passed.
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(
lockMode:LockMode)		 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.