G Suite Business customers can preview App Maker. Ask your domain admin to apply for early access.

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;
    

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

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: Drive Tables, 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.