Individuals
Individuals
An individual is one instance of an ontology class, such as a specific pump or a specific floor. The Application Ontology Service stores each individual as an item in the Item Service collection that its class is mapped to. Before a class can hold individuals, it needs a collection mapping. For more information, see Collection mapping.
The service is the way in to the individuals of a class. It checks your permissions, validates every write against the ontology, and then passes the write to the Item Service.
How individuals are stored
An individual has the shape of an Item Service item. Put its display name in _name and its domain data in properties. The service stores any other field as you send it.
When you create an individual, the service adds two fields:
properties._classId, the ID of the individual's class._typeName, the item type. It defaults to the user type of the class's collection binding.
The Item Service assigns the individual's _id. Reads return the item as it's stored, with the stored field names.
You can't create, update, or delete individuals of the platform lifecycle classes State, StateTransition, Event, and Action. The state machine API writes them.
For the individual fields, see Create individuals.
Individuals and ontology versions
Individuals always use the live version of the ontology. Individuals themselves aren't versioned. Until you promote the first version of an ontology, every individual call returns 409. A class that exists only in a draft returns 404. For more information, see Versions and drafts.
Class scope
A read on a class returns the individuals of that class and its subclasses. For example, reading Equipment also returns Pump individuals. To return only the individuals of the exact class, set _includeSubclasses to false when you search. For more information, see Search individuals.
Validation
The service validates every create and update before it stores anything. It checks the following:
- The constraints of the class.
- The required relationships of the class. Each required relationship needs at least one target. On an update without
_relationships, the stored relationships count. - That
_nameis a non-empty string ornull. An empty or blank name fails validation.
If any individual in a request fails, the service stores nothing and returns 422 with the list of violations. A field that no constraint mentions is stored as you send it. Individuals that you write straight to the Item Service collection aren't validated. For more information, see Constraints and Relationships and rules.
External keys
An external key identifies an individual in its source system, such as an asset register or a spreadsheet. It lets an import match incoming data to individuals that already exist.
To define the key, list the fields that form it in the class's _externalKeyFields. You can also send _externalKeyFields on each element of an import. The import builds the key from those fields in the form field=value, joined by | when there are several fields, for example _sourceKey=p-1. The service doesn't store this combined key on the individual. It matches existing individuals on the key fields themselves, so to find an imported individual, search on its key field.
For more information, see Importing individuals and Create classes.
State
An individual's _aostates field holds its current state in each state machine bound to its class. The service sets it when you create the individual, and only events change it after that. You can't set _aostates yourself. For more information, see State machines.
Relationships
Relationships between individuals aren't stored on the individual. To read them, list the individual's relationships. For more information, see Individual relationships.
Permissions
Access to individuals is granted per class, with the INDIVIDUALS_READ, INDIVIDUALS_CREATE, INDIVIDUALS_EDIT, and INDIVIDUALS_DELETE actions. A grant on a class also covers the individuals of its subclasses. A permission on the ontology doesn't give access to its individuals.
Actions match exactly, so INDIVIDUALS_EDIT doesn't include INDIVIDUALS_READ. To update or delete an individual, you also need INDIVIDUALS_READ, because the service reads the individual before it writes.
For more information, see Permissions and Granting permissions.