Override entity components

This page shows how to override a field on an entity without changing the entity at the original data source. Alternatively, see the OverrideEntity API reference (gRPC | HTTP).

Certain fields on the entity data model are annotated as overridable. Overrides let you change the value of a component on an entity. Overrides are a definitive statement from a user or service that the underlying system-produced data on an entity component should be overridden with a different value. When setting an override, the user or service setting the override is asserting that they are certain of the change and the truth behind the change.

note

The user or system that creates the override doesn't have to be the original producer of the entity.

Operators or services generally use overrides when they have new or different information about an entity. For example, an operator might manually mark a track's disposition to hostile according to standard operating procedures (SOPs).

Example use cases

• An autonomous surveillance tower publishes a track with unknown disposition. Following relevant standard operating procedures, an operator determines the track is suspect. The operator overrides the track disposition to suspect in the Lattice UI.
• An operator wants to emphasize the importance of a track to other consumers of the common operational picture. The operator sets an override in the Lattice UI to annotate the track as high priority.

Override system behavior

Setting an override requires an API call to the Entities API. After accepting an override, Lattice persists and shares the data with other nodes in the mesh. These are the key facts of persistence and distribution that you should understand:

• When the Entities API receives an override request, the new value is applied over the underlying system data at the overridden field path. The underlying data is not changed at the source.
• Lattice will distribute the override data to all nodes in the mesh. Each node will independently apply the override data over the overridden field on each entity update.
• The distribution of overrides in the mesh is eventually consistent. If two nodes override the same field at the same time, the last writer wins.

Override provenance and history

Override provenance describes basic information about the source of an override. This can include a user email or other system source identifier. This information is found on the entity in the override.provenance component.

Lattice does not distribute the full provenance history of overrides. Lattice only maintains the most recent override provenance per field path in the overrides component.

Before you begin

Before you can override an entity, you need to set up your Lattice environment. For an extensive list of the overridable fields, see the OverrideEntity API reference (gRPC | HTTP).

Override an entity

To demonstrate how you can override an entity, here is a simple example where we override the aliases.name field of an entity.

Python

from anduril.entitymanager.v1 import EntityManagerApiStub, OverrideEntityRequest, Entity, Aliases, Provenance
from grpclib.client import Channel
from datetime import datetime, timezone
import asyncio

# Set authentication
metadata = {
    'authorization': 'Bearer $YOUR_BEARER_TOKEN'
}

# Override an entity's "aliases.name" field
async def override_entity(entity_id):
    # open secure channel
    channel = Channel(host="$YOUR_LATTICE_URL", port=443, ssl=True)

    # create service instance
    entity_manager_stub = EntityManagerApiStub(channel)

    # create an entity containing the field we want to override: aliases.name
    entity = Entity(entity_id=entity_id, 
                    aliases=Aliases(name="anduril_docs_override_example"))

    # denote the field paths we want to override, ensure the fields listed are marked as overridable
    field_path = ["aliases.name"]

    # additional information about the source of the override
    provenance = Provenance(
        integration_name="Anduril Docs",
        data_type="ANDURIL_DOCS",
        source_update_time=datetime.now(timezone.utc)
    )

    # override the entity
    response = await entity_manager_stub.override_entity(
        OverrideEntityRequest(entity=entity,
                              field_path=field_path,
                              provenance=provenance), 
        metadata=metadata)

    # close the channel
    channel.close()

    return response


if __name__ == "__main__":
    # Replace $ENTITY_ID with the globally unique identifier for the entity you previously published.
    # If you receive an ENTITY_NOT_FOUND error, this means your connection was successful but an entity
    # with the provided ID does not exist. Check to make sure you have set the correct ID.
    print(asyncio.run(override_entity("$ENTITY_ID")))