Links

Object classes

To store data in a solution you need to create object classes to describe the types of data you'd like to store. It is common to set up some foundational object classes with a few initial properties as the first step in a new solution. Object classes are defined in the Global data model and are exposed to the apps and services in your solution using data sources.

Usage

To add an object class to your data model:
  • Hover over the + icon in the bottom-right of the data model designer.
  • Click Create Object Class.
An object class is a structured definition of a single business object, for example a Project. Each object class is assigned properties which are individual fields for storing data, such as Title, Status, or Created Date. Each property has a data type, such as string, boolean, or datetime which determines the format of the value allowed in the database. Object classes can also reference each other, allowing you to connect a Task to a Project.
Best practice
Use the singular when naming an object class (Project, not Projects) since it does not contain any data but is a definition of how a single object is structured.
An example of an object class Project, which is referenced by another object class, Task.
To read and modify objects in an object class you must first create a data source in an app or service. You can then use action nodes to create an object within an object class, assign values to the properties you have defined, and persist (store) the data in the database.
Good to know
Every solution has one built-in object class called User. This object class represents the users of your apps. The User object class cannot be modified, but it can be referenced in the same way as any other object class.

File object class

To store files such as documents and images in the database, there is a special type of object class called a File object class. For example, PDFs created using the Generate document action node or files and images uploaded by end-users should be stored in file object classes. For static files used in your apps, you should use Files.
To add a file object class to your data model:
  • Hover over the + icon in the bottom-right of the data model designer.
  • Click Create File Object Class.
File object classes have additional built-in properties to store file metadata.

General properties

These general properties describe an object class and are not to be confused with object class properties that are used to store data.
Property
Description
Name
A descriptive name for the object class. Use the singular (Project, not Projects).
Display Property
A string property that may be used to represent an object, for example in Developer tools.
Description
A longer description of the object class. For your own reference.
Icon
An icon from the built-in icon library to represent the object class throughout Appfarm Create.
Tags
Add tags.

Meta Data

You can enable additional built-in object class properties. When any of the properties below are enabled, these properties will be stored for each new record.
Property
Description
Created By
Add a read-only property to every object with a reference to the User that created the object.
Updated By
Add a read-only property to every object with a reference to the User that last updated the object.
Random Identifier
Add a read-only string property to every object with an automatically generated unique, random identifier.
This property is useful when you need to publicly expose a unique reference to an object, for example, when sharing URLs on social media or generating ticket references. Note: If you enable this property when objects have already been created in an object class, only the new objects will be automatically assigned a random identifier. For existing objects, it is necessary to perform a mutation via the GraphQL interface.
Sequential Identifier
This will generate a sequential identifier on each object (often also referred to as a sequential counter). The value will be set when the object is stored in the database. That is, when persisting a runtime object or creating an object in a database connected data source. Example: The Object Class Order has Sequential Identifier enabled, with a Starting Value of 10000. The last Order in the database has a Sequential Identifier of 12003. This means the next Order will get a Sequential Identifier of 12004. In this case, we may use the Sequential Identifier as the Order number. Note: If you enable this property when objects have already been created in an object class, only the new objects will be assigned a Sequential Identifier.
Starting Value
Only applicable when Sequential Identifier is enabled. This is the starting value of the Sequential Identifier. The default is 1, but you may choose a higher starting value (for example, if you want to generate order numbers starting at 10000, you may set Starting Value to 10000)

Concurrency Control

By default, when 2 different users update the same object, the last write wins.
Example - Last Write Wins
Users John and Paula both read company ThirtyFifty Inc into a runtime only data source.
  1. 1.
    John updates the Status to Inactive, Paula updates the Status to Prospect. Both at the same time. The changes has not yet been saved.
  2. 2.
    John clicks Save. The entry in the database is updated to Inactive.
  3. 3.
    Paula clicks Save. The same entry is the database is updated to Prospect.
The outcome: ThirtyFifty Inc's Status is updated to Prospect. The last write (Paula) wins.
The built-in Object Class Property Strict Object Versioning allows you to enable first write wins.
Example - First Write Wins
Users John and Paula both read company ThirtyFifty Inc into a runtime only data source.
  1. 1.
    John updates the Status to Inactive, Paula updates the Status to Prospect. Both at the same time. The changes has not yet been saved.
  2. 2.
    John clicks Save. The entry in the database is updated to Inactive.
  3. 3.
    Paula clicks Save. An exception is thrown (ConflictError (34013)), and the entry is not updated.
The outcome: ThirtyFifty Inc's Status is updated to Inactive. The first write (John) wins.
Enabling Strict Object Versioning also enables a built-in integer property Version No for the objects of this Object Class. The Version No is automatically incremented every time the object is successfully updated.
Please note
  • It is not recommended to use Subscribe to updates with Strict Object Versioning since this might break the strict versioning control.
  • Components dispatching frequently updates might not work in conjunction with Strict Object Versioning as subsequent updates might be dispatched with the old version number.
  • Data connectors or updates using GraphQL cannot be used in conjunction with Strict Object Versioning .

GraphQL

Exposure of an object class via GraphQL must be explicitly enabled. The specific types of queries and mutations that should be available must also be enabled.
In addition to these properties, to successfully run those queries and mutations, you need to have a role with the appropriate permissions, and GraphQL must be enabled for the environment.
Property
Description
Enable GraphQL
Expose this object class via a GraphQL endpoint.
Endpoint Name
The name of the GraphQL endpoint. This is generated automatically based on the Collection Name of the object class. Warning: If the GraphQL endpoint is used in Production and this name is changed, existing queries will need to be altered.
Enable Read
Query data within objects in this object class.
Enable Aggregate
Run aggregation queries such as count.
Enable Create
Create a new object in this object class.
Enable Update
Update (edit) data within objects in this object class.
Enable Delete
Delete objects in this object class.

GDPR

To maintain an overview of the personal information you are storing, you can assign a GDPR classification and describe why this information is collected and stored and how this information is used. Please refer to your subscription agreement for further information about your obligations around data privacy.
Property
Description
GDPR Classification
A privacy classification for the data stored in this property. The options are:
  • None: This property does not store personal information.
  • Personal: This property stores personal information. For example name, address, phone number, email address, social security number, or profile picture.
  • Sensitive: This property stores sensitive personal information. For example ethnic origin, political views, religion, health information, or sexual orientation.
GDPR Details
A description of why this information is collected and stored and how it is used. For your own reference.

Permissions

Object class permissions form a key part of your solutions' security. They determine which roles can access and modify data in that object class. By default, the built-in roles Owners, Maintainers, and Developers get full read and write access to each object class when it's created.
When editing an object class you can grant and revoke permissions for the built-in roles as well as for each custom role. You can also edit these rules for all object classes under Permissions. Changes to object class permissions require a deploy to come into effect in an environment.
Permission
Description
Create
Create a new object in this object class.
Read
Read data within objects in this object class.
Update
Update (edit) data within objects in this object class.
Delete
Delete objects in this object class.
Aggregate
Run aggregation queries such as count via GraphQL.

Object class properties

Data in an object is stored within properties, for example Name, Quantity or Created Date. Every object class has some built-in properties and you can add your own properties.
To add a property to an object class you can either:
  • Right-click on an object class, in either the table or diagram view of the data model designer and select Add property
  • Click the Add property button when an object class is expanded in the table view of the data model designer.
Each property has a data type, which determines the format of the value allowed in the database. Data types include string, boolean, datetime, and references to other object classes and enums.
Additionally, a property can either be a value or a function. Most properties are values. Values are stored in the database while functions calculate a value at runtime which is never stored in the database.
Warning
Once you have data stored in an object class, it is not recommended to change Node Name or Data Type. Doing so can cause inconsistency in your data.

Built-in properties

These properties are added to each object class and the values are populated when an object is created or updated.
Property
Description
ID
A read-only property with an automatically generated unique identifier. Note that ID values are sequential and therefore guessable. If you need to expose a unique reference to an object, considering using the Random Identifier property.
Created Date
A read-only datetime property containing the date and time an object was created. When you create a new runtime object the Created Date (and Created By) properties will be set client-side. When the object is persisted these values will be overwritten server-side and the client will be updated to reflect the actual values stored in the database.
A database-connected object will be persisted immediately, so the difference between the client-side Created Date and the server-side Created Date should be negligible. After a refresh of the object the server-side Created Date will be visible in the client.
The Updated Date (and Updated By) properties are treated in the same way. The values are set client-side when an object is modified with the Update object action node, or when changed using a UI component. For database-connected data sources the values will also be set server-side during this operation, while for a runtime data source the values will be updated on persist.
Update Date
A read-only Datetime property containing the date and time an object was last updated.

Built-in properties for file object classes

There are additional built-in properties for objects created in a file object class to store file metadata. These are populated automatically when you use the Create file object action node or other action nodes that create objects in file object classes.
Property
Description
File Content URL
A read-only internet URL property containing the URL of the file. Unless the file has been set as Public upon creation, a File Content URL will expire 12 hours after first being loaded into an app. If a file has been set as Public, the URL will not expire.
File Size
A read-only integer property containing the size of the file in bytes.
Is Public
A read-only boolean property indicating if the file is available to unauthenticated users. This property can be set through the Create file object action node.
Mime Type
A read-only string property containing the MIME type (external link) of the file.
Original File Name
A read-only string property containing the file name. This property can be overwritten through the Create file object action node.
Upload Complete
A read-only boolean property indicating if the file has been uploaded in full. A file created in a runtime data source is not considered uploaded until it has been persisted.
Upload Progress
A read-only float property indicating the progress of the file upload as a percentage. A file created in a runtime data source is not considered uploaded until it has been persisted.

General properties

Property
Description
Property Name
The name used throughout Appfarm Create to refer to this property. This name can be changed at any time without technical consequences.
Node Name
The name used by the database to store data for this property. This name should consist only of letters or digits. Warning: Once you have data stored in an object class, it is not recommended to change this value. Doing so can cause inconsistency in your data.
Description
A longer description of the property. For your own reference.
Data Type
The type of data allowed to be stored in this property. See data types. Warning: Once you have data stored in an object class, it is not recommended to change this value. Doing so can cause inconsistency in your data.
Property Type
A property can be either a primitive value or a function.
  • Value: A primitive value stored in the database.
  • Function: A function that calculates a value at runtime and which is not stored in the database. For example, a function that concatenates first name and last name properties and returns a full name.
Value on Create
Available for Value property type. A default value to set for the property when a new object is created.
Function
Available for Function property type. A function that calculates and returns a value at runtime.

Data types

All properties must be assigned a data type, defining what kind of data they store.
Data type
Description
Boolean
A truth value true or false. Can also be undefined.
String
Text with support for all types of characters.
Integer
A whole number.
Float
A floating point number with a decimal point.
Datetime
A timestamp in ISO 8601 format: YYYY-MM-DDThh:mm:ss:fffZ.
Duration
In integer number for holding a duration (in ms).
Internet URL
A website URL.
Image URL
An image URL.
Rich Text
Formatted text for use with the Rich text editor component.
Enum
A custom or built-in enum.
Reference
A reference to another object class. This creates a one-to-many relationship between the property's object class and the reference object class.

Boolean labels

Available for Boolean data type. For boolean properties you can define text labels for the true, false, and undefined/null values. You can then bind the property in a Text, Select, or Table component and the appropriate label will be displayed based on the value. Boolean labels can help reduce complexity in the UI designer and can replace the use of enums in some cases.
Property
Description
Label True
A text label to display when the value is true.
Label False
A text label to display when the value is false.
Label Undefined
A text label to display when the value is undefined (empty) or null.

Example

Label a boolean object class property
You have an object class Event with a boolean property Open for registration. You want to display text in the UI based on the value of that property for each event.
Assign the following boolean labels:
Label True: Open for registration
Label False: Closed for registration
Label Undefined: Not yet open for registration
Then, bind the property to a Text component on an Event details view in the Ul. The appropriate label will be displayed based on the property's value for that event.

Data validation

You can apply data validation checks to a property. These checks are run when data is persisted. If a check fails, an exception will be thrown. In order to handle this scenario you should use the catch exception action node.
We also recommend enforcing the same validation in your UI in order to provide the best possible user experience.
Property
Description
Read Only
If selected, the property can only be assigned a value using the Create object action node or the Value on Create property.
Required
A value must always be provided for this property.
Unique
The value provided must be unique across all objects of this object class.
Maximum Length
Available for String data type. The maximum number of characters allowed.
Regular Expression
Available for String data type. A regular expression that the string must match.
Minimum Value
Available for Integer and Float data types. The minimum value allowed.
Maximum Value
Available for Integer and Float data types. The maximum value allowed.
Delete Rule
Available for Reference data type. Control the effect of objects deleted in the referenced object class. The options are:
  • None: Objects in the referenced object class can be freely deleted. This means that objects of this object class may have orphan references pointing to objects that no longer exist. For example, if there are Order Line objects that reference an Order object and that Order object is deleted, the Order Line objects will remain with a reference to an Order that no longer exists.
  • Delete Constraint (default): If an attempt is made to delete a referenced object, an exception will be thrown. For example, if there are one or more objects in Order Line with a reference to an Order object, it will not be possible to delete that Order object.
  • Cascade Delete: If a referenced object is deleted, so will all objects in this object class that reference the deleted object. For example, an object deleted in Order will also delete objects in Order Line that reference that Order object.
Best practices
The Delete Rule Cascade Delete can remove complexity from your logic and ensure data consistency, but it should be used with caution. When an object is deleted and the rule is triggered, it will automatically delete all objects that reference the deleted object.
It is typically used when you have a structure with a parent object class and a child object class. When the parent is deleted, you also want to delete all the children. For example, you have two object classes Order and Order Line. Each order line object has a reference to an order object, its parent. In this case Cascade Delete will ensure that when an order is deleted, all the associated order lines are deleted.
Not all parent-child relationships warrant the use of Cascade Delete though, particularly when you want to retain history. For example, an Employee may be referenced by many Project objects as the Project owner. If the employee leaves the company and their associated object is deleted, you probably don't want to also delete all their projects which are important company records.
If you're unsure about the which rule to use, keep it set to Delete Constraint. You can always begin by using action nodes to first delete the child objects and then delete the parent. Then, when you are confident in your data model, you can switch to deleting only the parent and using Cascade Delete.

GDPR

Property
Description
GDPR Classification
A privacy classification for the data stored in this property. The options are:
  • None: This property does not store personal information.
  • Personal: This property stores personal information. For example name, address, phone number, email address, social security number, or profile picture.
  • Sensitive: This property stores sensitive personal information. For example ethnic origin, political views, religion, health information, or sexual orientation.
GDPR Details
A description of why this information is collected and stored and how it is used. For your own reference.