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

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

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).

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

<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.