Override entity components

Overrides allow users to update designated fields on an entity when they are not the original producer of the 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 it.

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 reference page.

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")))