Entities & queries

Creating entities

Construct an entity from its fully-qualified class name. The entity starts empty; you populate it with the methods below and then persist it.

var order = PSEntity("com.domain.commerce.Order");
order.identifier("ORD-2024-001");

Create a new, unsaved entity of the given class.

Set a stable business identifier — the key you later pass to data$.load.

var idn = "PROCESS_CATEGORY_BUSINESS";
var model = data$.load(idn);
if (model == null) {
    model = PSEntity("com.paradicshift.platform.automation.process.Category");
    model.identifier(idn);
}
model.text("name", "en", "Business");
data$.persist(model);

Fields & values

Set a scalar field (string, number, bool, …). value is an alias of val.

Read a field back; returns null if unset.

order.val("total", 149.99);
order.val("currency", "USD");
order.val("hidden", false);

context$.log("total = {}", order.val("total"));   // 149.99

Multilingual text

Text fields are stored per locale, so a record can carry its name or description in many languages at once.

Set the localized text of a field. The field name and locale are auto-detected by order, so ("name", "en", …) and ("en", "name", …) both work.

Read a localized value back. Reading a locale that was never set is a runtime error, so guard or set it first.

component.text("name", "en", "Execute access");
component.text("name", "fa", "دسترسی اجرا");

GIS geometry

Entities can hold geospatial fields expressed as WKT strings. The geometry is parsed and validated when you set it.

Attach a geometry to a field from a WKT string. gisWkt is an alias.

Supported WKT geometry types include points, lines, polygons and their multi-variants:

e.gis("location", "POINT(%f %f)".formatted(lon, lat));
e.gis("area_1",   "POLYGON((%f %f, %f %f, %f %f, %f %f, %f %f))"
                  .formatted(lon, lat, lon2, lat, lon2, lat2, lon, lat2, lon, lat));
e.gis("path",     "LINESTRING(%f %f, %f %f, %f %f)"
                  .formatted(lon, lat, lon2, lat2, lon3, lat3));

Access control

Grant open access to the entity — useful for shared platform data such as categories and model properties.

Open a specific kind of access (for example "list") without granting everything.

Persisting & linking

Saving, deleting and relating entities is done through data$ (see System objects). An entity also exposes a convenience delete.

data$.persist(subCat);
data$.link(subCat, model, "IN_PARENT_CATEGORY");

PSEntityQuery

Build a read query against a base class, chaining select clauses (what to return), filter clauses (which rows) and traversal clauses (follow relations). Pass the finished query to data$.query().

var q = PSEntityQuery("com.domain.commerce.Order")
            .selectId()
            .selectVal("total")
            .filterVal("currency", "equals", "USD")
            .filterVal("total", "greater_than", 100);

var rows = data$.query(q);

Select clauses

Filter clauses

Traversal

Filter operators

The comparison operator in a filter is given as a string: