Core concepts

Six concepts carry the whole platform. Each maps to concrete operations, linked below.

Tenant

A tenant is the primary isolation boundary. Every authorized operation runs in tenant context. Do not infer tenant access from a URL or a client-supplied value; authorization establishes it. Every operation accepts an optional tenantCode, which falls back to the tenant encoded in the verified token.

Entity

An entity is a business record with a unique identifier, properties, optional relationships, and metadata — a customer, project, ticket, or invoice.

Read one with getById, a page of them with query, and duplicate one with getCopy.

const customer = await entityService.getById(
  { definitionType: "Customer", id: "customer-123" },
  token,
  tenantCode,
);

Entity definition

An entity definition is the schema contract for a class of entities: property names and types, constraints, references, indexes, and display metadata. It is itself a record, so it is readable at runtime.

Read one with getEntityDef, list them with queryEntityDefs, and evolve them with createEntityDef and updateEntityDef.

const definition = await entityDefService.getEntityDef(
  { entityDef: { name: "Customer" } },
  token,
  tenantCode,
);

Property

Properties hold scalar values, structured values, or references. Evolve them through the definition operations rather than relying on undocumented shapes.

Use getCommonPropertyDefs to discover the available data types, then addProperty, updateProperty, and removeProperty.

await entityDefService.addProperty(
  {
    entityDef: { name: "Customer" },
    property: { name: "loyaltyTier", title: "Loyalty tier" },
  },
  token,
  tenantCode,
);

Relationship

Mapped-item operations maintain relationships between entities. Use them when the definition models a relation rather than embedding copied data.

Attach with saveMappedItems, detach with removeMappedItems, and read across a relation with queryMapped or include() on a query.

Workflow

Workflows coordinate longer-running business processes. Start one with startWorkflow when the caller should not wait; use runWorkflow only when the caller needs the outcome inline. A waiting human task is advanced by its assignee with submitWorkflowTask, or programmatically with iterateTask; administrators step a run one activity at a time with iterateOnce.

See the workflows guide for the full lifecycle.

Function

A serverless function is tenant-resident backend code. Execute one with runWfFunction and dry-run one with testWfFunction. See serverless functions.