People and assets (entities)

Overview

Menu path: Choose Entity (/admin/manage/entity).

A tag is a MAC address. An entity is the forklift, the contractor or the oxygen cylinder: the thing named in a sentence. Omaya keeps the two apart on purpose: the hardware is replaceable, and the thing it is attached to is what is actually followed.

Following entities once they are set up is described in Monitoring people and assets.

Characteristics of an entity

One row exists per thing that is followed. The entity form contains, top to bottom:

Field	Purpose
Active	The switch at the top. An inactive entity keeps its history but drops out of the Entity Tracker. To take its tag off Roll Call as well, unbind the tag or set the device inactive.
Name	What people call it: "Forklift 3", "Siti Nur", "Cylinder O2-114". Must be unique within the organisation.
Entity Type	Person or Asset. The type has effects: Security Watch judges people against their habits, Roll Call expects people at the muster point, Footfall counts people's tags (as staff or visitors) and keeps asset tags apart, and the privacy tools treat a person's trail as personal data.
Identifier	Optional. The number the outside world uses: staff ID, badge, plate, asset tag. A data-subject request is searched by it.
Bound Sensors	The tag or tags it carries now. See Tags and history.
Labels	Groups such as Night shift, Contractors or IT Equipment. They drive filters, rules, Label Fields and what a limited role can see. See Labels.
Label fields	Appear under the labels when a chosen label has fields defined. See Label Fields.
Advanced Settings	Folded away: Description (notes), Photo (JPG, PNG or WebP up to 10 MB, stored as WebP, for recognising it in a list) and Extra Fields (JSON), free key-value pairs for the organisation's own use.

Tags and history

Tags get swapped. A tag's battery dies, it gets lost, or it goes back in the drawer and comes out on a different pallet. If the name lived on the tag, "Forklift 3" would quietly become "Pallet 12" and every report about it would be about the hardware.

With an entity, the tag is replaced and the history is kept. An entity can hold more than one tag at a time (a vehicle with one on the dash and one on the trailer). Omaya also records which entity held each tag and when, so a tag's past stays with the entity it was on.

Reports, the Entity Tracker and the Timeline all say "Forklift 3" for the whole week, across both tags. Tag 01's later days belong to Pallet 12, because that is what it was bound to when they were recorded.

The entity is also what turns reports into answers. The trail, Attendance, the Entity Tracker and the alerts all show the entity's name; a tag with no entity shows as its device name or its MAC address.

Creating an entity

Applicable versions / plans

SPECIFICATION

• Permissions (System > Roles): view-entity, create-entity, edit-entity, delete-entity. As shipped, Admin holds all four, Manager can view, create and edit (not delete), and Viewer can only view.
• Add Entity is shown only to a role with create-entity.
• A role can be limited to some labels: see Limiting a role to some labels.

Requirements

At Northwind Tower, Aisha Rahman sets up the cleaners for Toilet Hygiene and Roll Call: Person, Siti Nur, identifier NW-0112, bound to the white badge tag she clips to her lanyard, label Cleaning team. She does the same for a second cleaner. Then she sets up the equipment Daniel Lim keeps losing: Asset, Floor scrubber 2, bound to the tag screwed under its handle, label Cleaning equipment.

• Each cleaner is a named Person entity with a staff identifier.
• The floor scrubber is an Asset entity with its own label.
• Each entity appears on the Entity Tracker within a few minutes.

Restrictions

• Name: required, at most 120 characters, unique within the organisation.
• Identifier: at most 100 characters.
• Photo: an image file of at most 10 MB.
• Bound Sensors: only registered devices that are not bound to another entity are offered.
• A role limited to some labels must leave one of its labels on the entity.

Configuration roadmap

(1) Register the tag under Device > Sensor.

(2) Open Entity and start a new entity.

(3) Set the name, type, identifier, tag and labels, and save.

(4) Confirm that the entity is heard.

Procedure

1. Register the tag first under Device > Sensor. A model Omaya does not know yet goes through Sensor onboarding first. An entity can hold only registered devices.

2. Choose Entity and click Add Entity at the top right. The form opens on the right.

3. Set the fields as follows.

   Configuration Item	Value	Note
   Active	On	Default on.
   Name	Siti Nur	Required.
   Entity Type	Person	Required. Person or Asset.
   Identifier	NW-0112	Optional. Staff ID, IC number, asset tag or other reference code.
   Bound Sensors	The badge tag	Search by name or MAC. Only devices not already bound to another entity are offered.
   Labels	Cleaning team	Pick an existing label or type a new one.
   Label fields	—	Fill in any fields that appear for the chosen labels.
   Advanced Settings	—	Description, Photo, Extra Fields (JSON): optional.

4. Click Save.

Verification

• The form closes with Entity created successfully. and the entity is listed in the grid.
• Walk the tag past a gateway. Click the row to open its panel: the Live tab shows where its tag was last heard.
• Choose Monitor > Entity Tracker: within a minute or two the entity is on a card under On site.
• If the name is taken, the form shows An entity with this name already exists.
• If a chosen tag is already bound elsewhere, the form shows The following sensors are already bound to another entity: followed by the device names.

Labels

Overview of labels

A label is a name put on records to group them. The same label can go on venues, zones, gateways, devices and entities: System > Labels lists them all, and each label's Used for ticks state which kinds of record it can go on. Only labels used for Entity are offered on the entity form.

A visit to System > Labels is rarely needed first. A new name typed into Labels on the entity form is created for entities on save; a name that already exists for entities is reused.

Uses of labels on entities

• Finding things. The Label filter above the grid, the All labels filter on the Entity Tracker, and the top-bar search all match label names.
• Reports. Dwell Time, Heatmap, Flow, Button Press and Outdoor Activity have a Label filter that keeps the tags of the entities carrying it; Attendance has Group (tag) for the same.
• Staff and visitors. One label can be chosen as the one that marks staff. Footfall then counts a person carrying it as staff, any other person as a visitor, and a tag bound to nobody as unassigned. See Staff, visitors and unassigned tags.
• Rules. A rule can watch a Label: every device carrying it, and every device bound to a person or asset carrying it, each judged on its own. With Tools on forty tools, one rule reports when any of them leaves Level 5. See Rules.
• Label Fields and role limits, described below.

Label Fields

Overview of label fields

Some things need a few more facts than a name: a serial number on IT equipment, a service date on a forklift, a company on a contractor. Label Fields, at the top right of the Entity page beside Add Entity, defines them once per label, and every entity carrying that label shows them on its form.

Where the values show

• The entity's panel. The Label Fields row on the Overview tab.
• Searching the grid. Label fields (any) searches every field's value, and each field can also be searched on its own by its name.
• Rules. Label field (person / asset) reads one field, on a schedule (daily by default). A date is read as days from today, negative once it has passed, so "service due within 7 days" is less than 8. An entity whose field is empty is skipped. See Rules.
• The Omaya API. An integration can read and write the values, and filter entities by one. See Reading data out.

Label fields are not shown on reports, the Entity Tracker or the mini apps.

Behaviour of shared and removed fields

• Same name, one value. A field with the same name on two labels is one field: an entity carrying both labels fills it in once. The definition listed first decides its type and choices, so give such fields the same type on both labels.
• Removing a field keeps the values. They are hidden, not deleted: when a field with the same name is added back to the label, they reappear.
• Taking a label off an entity keeps the values too. Its fields disappear from the form; when the label is put back, the values are still there.
• Visibility. Anyone who can see the Entity page sees the fields' values on each person and asset.

Adding fields to a label

Applicable versions / plans

SPECIFICATION

• The Label Fields button is shown only to a role with edit-entity, the same permission as editing an entity.
• A role limited to some labels sees and changes the fields of those labels only.

Requirements

At Northwind Tower, Daniel Lim looks after the IT store. He adds two fields to the label IT Equipment: Serial No (Text, Required) and Warranty ends (Date).

• Every laptop cart with that label asks for both values.
• A daily rule on the label can email him a month before any warranty ends.

Restrictions

• The label must exist first: give at least one entity the label, or create it under System > Labels with Entity ticked under Used for.
• At most 40 fields on one label. A field name is at most 80 characters; a Dropdown has at most 50 choices of at most 80 characters each.
• A Dropdown needs at least one choice.

Type	What can be typed
Text	Up to 255 characters
Number	Any number, decimals allowed
Date	A date from the date picker
Dropdown	One of the choices, or nothing

Procedure

1. Choose Entity and click Label Fields.

2. Under Label, select the label. The list shows how many fields each label has already, and the line under it states how many entities carry it. With no entity labels yet, the list shows No labels yet — add a label to an entity first.

3. Click Add Field. Each field is one row:

   Configuration Item	Value	Note
   (field name)	Serial No	Rows left with no name are dropped on save.
   (type)	Text	Text, Number, Date or Dropdown.
   (applies to)	Any type	Any type, Person only or Asset only.
   Required	Ticked	Every entity with the label must then have a value.
   (choices)	—	For a Dropdown only: the choices, separated by commas, for example New, Good, Needs repair.

4. Repeat Add Field for each fact. The order of the rows is the order on the entity form.

5. Click Save Fields.

To change a field, change its row and click Save Fields again. Renaming a field keeps the values already typed. To remove one, click the × at the end of its row, then Save Fields.

Verification

• Fields saved. is shown, and the label in the Label list shows its number of fields.
• Open an entity with that label and click Edit in its panel: the fields are under Labels, each with the label's name beside it.

Message	Action
"Warranty status" needs at least one choice.	A Dropdown has no choices. Type them, separated by commas.
Could not save the fields.	The fields were not saved. Try again; if it keeps failing, ask an administrator whether the role has edit-entity.

Filling in label fields

Restrictions

• A field appears only while one of the labels it belongs to is chosen on the form.
• A field set to Person only or Asset only appears only for that type.
• A required field added to a label that entities already carry does not change them at once. Each of them must have it filled in the next time it is edited and saved.

Procedure

1. Click the entity's row and click Edit in its panel (or Add Entity for a new one).
2. Select its Entity Type and its Labels. The fields of the chosen labels appear under Labels as soon as they are chosen.
3. Fill them in. A field marked with a red * is required.
4. Click Save.

Verification

• Click the entity's row. On the Overview tab, the Label Fields row lists each field with its value, or — where it is empty.
• If a value does not fit its field, the field is outlined in red and the message under it reads Serial No is required. or Serial No is not valid. (with the field's own name). Nothing is saved until it is corrected.

Limiting a role to some labels

Applicable versions / plans

SPECIFICATION

• Set under System > Roles by a user who can edit roles.

Restrictions

• A limited role sees only entities carrying one of its labels on the Entity page, the Entity Tracker, the dashboard's entity figures, the people named on Right Now, and every entity picker.
• When a limited role adds or changes an entity, it must leave one of its labels on it, so that the entity does not vanish from its own view.

CAUTION

The limit keeps a contractor firm's supervisor to their own crew; it is not a privacy wall. Reports and the API are not limited, so do not give a limited role report permissions it should not have.

Procedure

1. Choose System > Roles and open the role.
2. Under Entity access, select Only entities with these labels (the default is All entities).
3. Tick the labels and save the role.

Verification

• A user with the role sees only the entities carrying the ticked labels.
• Saving an entity without one of the role's labels is refused with Add at least one of your labels (…) so the entity stays visible to you. A role with no labels ticked is refused with Your role has no labels assigned, so it cannot add or change entities.

Entity panel

Click a row to open the entity's panel. Its header has buttons for where the entity is now (Entity Tracker), where it has been (Sensor Trail, last 3 days), its report, and Edit (for a role with edit-entity). The panel has five tabs:

Tab	Content
Overview	The details, its label fields and extra fields, the number of sensors and labels, and when it was last updated
Live	Its status, each bound tag with where it was last heard and a Monitor link to Live Monitor, and the floor plan
Sensors	Each bound tag, with its name, MAC and type
Reports	Visits today, in the last 7 days and this month, its average dwell, and its top places this month, with links to My Live Activity and My Full Trail
Trail	Movement Trail: select a date range and click Apply for every stay, with Arrived, Left, Dwell, Path and RSSI; the download button saves it as CSV

NOTE

For day-to-day watching, the Entity Tracker is the better page: its Timeline and Movement Replay are built for reading a day, and it shows every entity at once.

Counting people, visitors and unbound tags

How a tag is set up decides how it is counted:

The tag is	Footfall counts it as	Right Now and the Entity Tracker show it as
Bound to a Person carrying the staff label	Staff	The person, by name
Bound to any other Person, such as a visitor given a badge at check-in	Visitor	The person, by name
Bound to an Asset	An asset tag, kept apart from people	The asset, by name
Registered but bound to nobody	Unassigned	A tag, not assigned to anyone

Right Now calls a zone's count people only when every tag in it is bound to a person or asset; otherwise it says tags and how many are not assigned to anyone. Binding each badge to its person turns tags into named people on every page.

The Visitor Management app does this for visitors: a badge handed out at check-in is bound to the visitor's own Person entity for the length of the stay, so the visitor is named on every page and counted as a visitor. Because Omaya records who held each tag and when, the visit stays with that visitor after the badge goes back to reception.

Swapping a tag

Restrictions

• A tag bound to one entity is not offered to another. To put the old tag on something else, remove it from this entity first.

Procedure

1. Click the entity's row and click Edit in its panel.
2. Under Bound Sensors, remove the old tag and add the new one.
3. Click Save.

Verification

Nothing else changes, including rules that watch the entity. From that moment, sightings of the new tag count for the entity; what the old tag recorded while it was bound stays with the entity. Reports about past days ask who held a tag at the time, so moving a tag from a person to a trolley does not turn the person's past days into the trolley's.

Deleting an entity

Deleting an entity requires delete-entity (only Admin as shipped).

1. Choose Entity and click the entity's row. Its panel opens.
2. Click the bin button (Delete) at the top of the panel, beside Edit. The panel closes and the Delete Entity window opens.
3. Click Delete.

Verification. The window states This action cannot be undone. The entity's trail history will be preserved. After Delete, the list reloads without the entity and Entity deleted. is shown. To take an entity out of use without deleting it, switch Active off and unbind its tags instead.

WARNING

Deletion cannot be undone. The entity's trail history is preserved.

Where entities appear

• Monitor > Entity Tracker: every active entity on one page, where each one is now and for how long, with a five-day Timeline and Movement Replay. Monitoring people and assets describes it.
• Reports: Attendance lists people by name; Asset Utilisation lists assets; Footfall counts people's tags, split into staff, visitors and unassigned tags once a staff label is chosen, and shows asset tags apart; the Sensor Trail names the entity on every row; GPS Replay plays an entity's journey outside across all its tags. See People-count reports and Indoor and outdoor tracking.
• Rules: a rule can watch one Person / asset (through whichever tag it carries now) or a Label, and fire when it enters or leaves a place. See Rules.
• Roll Call: a muster expects every active tag bound to a Person entity, plus every active tag whose device carries the label staff, employee, human or visitor. If there are none of either, it falls back to every active tag not bound to an asset, and the board says so. It shows the entity's name; a tag bound to nobody shows its device name, or its MAC. See Roll Call.
• Security Watch: incidents about a person name the entity, and the AI's "out of habit" judgement is about that person's usual pattern, not the tag's. See Security Watch.
• App users: a mini-app user (a cleaner signing in to the app) can be linked to a Person entity, so the app knows where its user is; the user sees the link on their own profile.
• Privacy requests: a request from a person is searched by name, identifier or email across everything the platform holds; erasing a Person entity removes the record's details and deletes their location trail.

Troubleshooting

Symptom	Cause	Action
The entity never moves.	The tag on it is not reporting. An entity with a silent tag is a silent entity.	Check the tag's Last Seen under Device > Sensor. On the Entity Tracker the entity appears under Offline with where and when it was last heard; see Troubleshooting.
The required tag is not offered under Bound Sensors.	It is bound to another entity, or it is not registered yet.	Remove it from the other entity first, or register it under Device > Sensor.
Save shows An entity with this name already exists.	Names are unique.	Add the identifier or a qualifier ("Forklift 3 (night)").
Save shows Add at least one of your labels … so the entity stays visible to you.	The role is limited to some labels.	Keep one of them on the entity, or ask an administrator.
The required label is not in the Labels list.	It exists but is not used for entities.	Tick Entity under Used for under System > Labels, or type the name on the form to create an entity label of the same name.
A label field does not appear on the form.	Fields follow the labels chosen on the form, and a field can be limited to one type.	Choose the label first. Check that the field is not set to Person only or Asset only for the other type.
Roll Call expected 40, but there are 55 staff.	Fifteen staff have no active tag, or their tags are not bound to a Person entity and their devices carry none of staff / employee / human / visitor.	Bind each badge to its person: that alone puts it on the muster.
A report shows two names for one MAC.	The tag was moved from one entity to another during that period.	None. Each name owns the part of the period it was bound for.
The wrong tag was bound last week.	Rebinding fixes it from now on, but sightings recorded under the wrong tag stay with this entity; the page cannot move past history.	Contact the operator of the platform if the history matters.
Renaming the device changed nothing.	Names on reports come from the entity, not the device.	Rename the entity.
The entity is missing from the Entity Tracker.	It is not Active, or the role is limited to labels the entity does not carry.	Switch Active back on, or check the role's Entity access.