Entities, sites, and assets
Represent persistent Mission objects with domain metadata and checked placement.
A Mission entity has persistent identity, type, and organization ownership. Use it for a Track, site, or asset. Optional metadata includes position, ontology, relationships, and quantity.
Local durability and remote arrival are separate outcomes. Platform storage and replication defines those mechanisms.
Select the domain representation
| Object | Mission meaning | Additional context |
|---|---|---|
| Track | An observed object whose saved state and live telemetry are distinct | External correlation, observation position, detection, and telemetry |
| Cache Management site | A geographic entity with recognized site ontology and team placement | Site type, operational lifecycle, instructions, and inventory |
| Asset | An item or resource | Quantity, owning team, ontology, and containing site |
| Document | A schema-bound structured record | Form fields and optional workflow, not an interchangeable entity |
Cache Management recognizes a geographic entity as a site through site_type: cache or site_type: bdl, lifecycle, and ownership metadata. Coordinates alone are insufficient.
Create with placement
CreateEntityParams specifies the entity identity, organization, type, name, position, affiliation, and optional initial quantity. CreateEntityWithPlacementParams adds encoded ontology, location_id, and team_id.
atlas.app().entities().create_entity_with_placement(...) returns EntityDetail. Retain the returned identity. A local commit does not prove the entity already arrived on another peer.
Use location_id for containment, such as an inventory item located at a site. Use team_id for assignment. Match the metadata's team identifier to the checked placement. Do not create an unprotected entity and patch its ownership afterward as an admission shortcut.
Supply the verified organization, authorized team, initial position, and canonical encoded_site_ontology bytes. Placement remains part of the checked creation operation.
Separate three kinds of state
- Entity fields retain persistent context and the latest saved state.
- Typed Mission notifications report an observation or change through the live event path.
- Telemetry provides continuing samples from a producer.
A durable entity activity record is also distinct from a live notification. For example, Cache Management records cache.established in site activity. That history entry is not the TrackDetected distribution contract.
See events and telemetry for typed payload meaning and links to canonical delivery behavior.
Entity lifecycle and site lifecycle
Entity lifecycle determines whether the object is active, archived, or deleted. Archive hides it from normal lists, maps, and counts while retaining its values and history. Restore returns an archived entity to Active. Delete is terminal.
Archived entities reject ordinary field, position, ontology, and relationship edits. Restore requires the same authority as Archive. Do not replay an old create operation to restore a deleted entity.
A site's ontology lifecycle is separate. Cache Management uses loaded, accessed, emptied, and compromised. An emptied site is not an archived entity. Show the site's operational state without confusing it with entity retention.
Resolve and update
An entity reference identifies an object, not its snapshot. After an early detection, resolve it with mission.entities.resolve(entity_ref, options) under independent entity-read authority and a bounded deadline. Display the authorized observation while resolution remains pending.
Keep the saved view and live view separate. A newer telemetry sample does not prove the durable entity changed. A late durable read must not overwrite a fresher live position on the screen.
For team-assigned non-geographic entities, modification needs the owning team's authority or administrator authority. Protected data also requires its policy access. The SDK makes the final decision for each operation.
Tracks defines continuous observations.