The entity is a shared facet

AnalyticsHTTPSDKCLIDashboardentity_facetentity_state_sourceaggregateByFacets

Roles that declare the same entity key form that entity's system. One dial per role, and every analytics query can scope to the whole journey.

The situation

A machine moves between three queues: the fleet queue, an unload station and a service bay. Each queue has its own role. Asking about the machine across all three should not mean listing the roles in every query.

The recipe

curl -X PATCH https://lt.acme.dev/api/roles/machine-fleet \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{ "entity_facet": "serialNumber", "entity_state_source": "subtype" }'

curl -X PATCH https://lt.acme.dev/api/roles/unload \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{ "entity_facet": "serialNumber", "entity_state_source": "role" }'

machine-fleet   entity_facet: serialNumber   states from: subtype  (idle, running)
unload          entity_facet: serialNumber   states from: role
service         entity_facet: serialNumber   states from: role

entity_facet names the metadata key for what moves through the role. entity_state_source says whether the role’s subtypes are states or the role itself is one state.

The guarantee

The system is derived, never maintained: query: { entity: 'serialNumber' } resolves server-side to every role declaring that key and implies exists: ['serialNumber']. An entity key no role declares is a 400 that names the gap. groupBy: { state: true } labels each row by its role’s dial. See Analytics.

Analytics