Roles and permissions

Who can open which page, press which button, and see which people. Everything here is per organisation: a role made at Northwind Tower exists only there.

Two kinds of account

	Admin users	App users
Who	Facilities, operations, security supervisors, IT: people who set Omaya up and read its reports	Cleaners, technicians, guards, receptionists: people who do the work
Where they sign in	The admin console	The mini apps, on the web or in the Omaya app
Made under	System › Admins (/admin/system/admin)	Apps › App Users (/admin/app-users)
What decides what they see	Their role, and the role's permissions	App access: which apps, whether they may configure each, and whose records they see
Gets the gateway and coverage alerts	Yes, every active one	No

The rest of this page is about admin users until App users.

How it fits together

An admin holds exactly one role. A role is a list of permissions, and can also be limited to the people and assets carrying chosen labels (Entity access). A permission is never given to a person directly.

A permission is never given to a person directly: it belongs to a role, and an admin holds one role. A menu item whose permission the role lacks is not shown at all, and a menu heading whose items are all hidden disappears with them.

What a missing permission looks like:

• A menu item disappears. Each item in the menu names the permission it needs, and an item the role lacks is not shown, nor found by the page search. A heading whose items are all hidden disappears too.
• A button is missing or refused. Some buttons are hidden (on Roles, a row click opens the editor and the row has a delete button only for a role with Edit · Roles; anyone else gets a read-only view); others are shown and refused by the server when pressed.
• A settings card is locked. System › Configuration opens for anyone with Manage General Config, but each card checks its own permission and shows Not Permitted — Contact your administrator for access. to a role without it.

Two more things decide what exists at all:

• Your licence. A permission belonging to a module your licence does not include is removed, so it does not appear on the role form.
• Apps switched on. An app's pages appear only once it is switched on under Apps › Your apps, whatever the role.

Platform operators (the people who run Omaya itself) are not limited by roles and have a menu of their own you will not see.

The roles Omaya ships

Role	For	In short
Admin	Whoever owns the system at your organisation: at Northwind Tower, Aisha Rahman	Every permission
Manager	Day-to-day operators: Ravi Kumar	Everything except deleting (admins, spaces, gateways, devices, entities, rules, custom reports), the licence, the organisation's settings and retention, and which app data AI Reporting may read
Viewer	People who need to look, not change: a building owner's representative	The pages that show things (dashboard, monitor, reports, devices, rules) and nothing that changes them; not the Activity Log, Configuration or Connectors

Manager has Edit · Admins, Edit · Roles and Assign · Roles, so a Manager can look after roles and accounts at or below its own level. It cannot climb: see What nobody can give.

You can edit the three shipped roles like any other, but a role of your own is clearer: a name that says what it is for (Security desk, Contractor, Energy reporting) is easier to audit than "Manager, minus three things".

What nobody can give

Whatever permissions a role has, Omaya refuses these, on the Roles and Admins pages, in Single sign-on settings and through the API:

• Nothing you do not hold yourself. You cannot tick a permission on a role, or give anyone a role, that includes a permission your own role does not have. You cannot give permissions you do not hold yourself: … or You cannot give the role "Admin": it has permissions you do not hold (…). The same applies to the default role and group mappings under Single sign-on, since they hand out roles too.
• Not your own role. You cannot edit the role you hold, nor change which role you have. You cannot change the role you hold yourself. / You cannot change your own role. Ask another administrator.
• Nobody above you. A role that has permissions you lack cannot be changed or deleted by you, and an admin whose role has permissions you lack cannot be edited, switched off, deleted, have MFA reset or be taken off their role. … has permissions you do not hold (…), so you cannot change their account. A new password or email would otherwise be a way into their account.
• Permission names are for Admin. The list of permission names (/admin/system/permission) opens only for the Admin role, whatever else a role has. Others see Only the Admin role can view or change permission names.

The message names up to five of the permissions you are missing. Platform operators are not limited by these rules.

So with the shipped roles: an Admin can do everything; a Manager can make roles from its own permissions, give them, Viewer or Manager to others, and edit those people, but cannot touch the Admin role or anyone holding it; a Viewer changes nothing.

Every permission

Grouped as on the role form, under the same headings and with the same labels. A, M and V are Admin, Manager and Viewer as shipped.

Dashboard & Analytics

On the role form	Permission	Unlocks	A	M	V
View Dashboard	view-dashboard	Dashboard	✓	✓	✓
View Analytics	view-analytics	The Reports › Zone compare page (the menu item also needs View Environment Report)	✓	✓	✓

People & Access

On the role form	Permission	Unlocks	A	M	V
View Admins	view-admins	System › Admins: the list, and the panel a row click opens	✓	✓	✓
Create · Admins	create-admins	Add Administrator on Admins	✓	✓
Edit · Admins	edit-admins	Edit (including the role), the On switch on each row, Reset two-step, for admins not above you	✓	✓
Delete · Admins	delete-admins	The delete button on each row, and Delete in the panel	✓
View Roles	view-roles	System › Roles: the list, and the read-only view a row click opens	✓	✓
Create · Roles	create-roles	Add Role on Roles	✓	✓
Edit · Roles	edit-roles	Opening a role's editor from the list: name, access by area, Entity access; not your own role or one above you	✓	✓
Delete · Roles	delete-roles	Deleting a role (the delete button on its row)	✓	✓
Assign · Roles	assign-roles	Add Administrator and removing an admin, inside a role's edit panel; only roles within your own permissions, never your own account	✓	✓
View App Users	view-app-users	Apps › App Users: the list	✓	✓	✓
Create · App Users	create-app-users	New app user, Import admin, Import person, sending a sign-in link	✓	✓
Edit · App Users	edit-app-users	Editing an app user and their app access	✓	✓
Delete · App Users	delete-app-users	Deleting an app user	✓	✓

Devices & Entities

On the role form	Permission	Unlocks	A	M	V
View Devices	view-devices	Device › Sensor	✓	✓	✓
Create · Devices	create-devices	Adding a sensor or tag, and importing them	✓	✓
Edit · Devices	edit-devices	Editing a device, its settings and commands, radar and distance-sensor calibration	✓	✓
Delete · Devices	delete-devices	Deleting a device	✓
Bulk Import Devices	manage-devices	New sensor types and Panic Buttons (Bulk Import itself, the button on Device › Sensor, needs Create · Devices); acting on anomalies; the device commands that need a typed confirmation (power off, factory reset)	✓	✓
View Entities	view-entity	Entity (people and assets)	✓	✓	✓
Create · Entity	create-entity	Adding a person or asset	✓	✓
Edit · Entity	edit-entity	Editing one, binding tags, Label Fields	✓	✓
Delete · Entity	delete-entity	Deleting one	✓
View Device Health	view-device-health	The device health page (/admin/manage/device/health)	✓	✓	✓
View VMS Streams	view-vms	Nothing at present: no page checks it	✓	✓	✓
Manage Custom Device Types	manage-custom-device-types	Button-press frame definitions for custom devices	✓	✓
View Auto-Discovery	view-auto-discovery	Devices heard but not registered (/admin/manage/auto-discovery/found)	✓
Manage Auto-Discovery	manage-auto-discovery	Registering or dismissing them, and the discovery settings	✓

Gateways & Monitoring

On the role form	Permission	Unlocks	A	M	V
View Gateways	view-gateways	Device › Gateway	✓	✓	✓
Create · Gateways	create-gateways	Create on Gateway	✓	✓
Edit · Gateways	edit-gateways	Edit on Gateway, including quiet hours	✓	✓
Delete · Gateways	delete-gateways	Delete on Gateway	✓
View Monitor (overall)	view-monitor	The Monitor menu: Live Monitor, Right Now & Live Alerts, Entity Tracker, Scout (phones)	✓	✓	✓
View Monitor · Devices	view-monitor-devices	The device parts of Live Monitor, and device replay	✓	✓	✓
View Monitor · Gateways	view-monitor-gateways	The gateway parts of Live Monitor	✓	✓	✓

Spaces & Locations

On the role form	Permission	Unlocks	A	M	V
View Spaces	view-spaces	Space (Location, Venue, Zone, Zone Type), Space › Beacon & Wi-Fi Anchors, floor plans	✓	✓	✓
Create · Spaces	create-spaces	Adding a location, venue, zone or zone type	✓	✓
Edit · Spaces	edit-spaces	Editing them, and anchors	✓	✓
Delete · Spaces	delete-spaces	Deleting them	✓
Manage Floorplan Calibration	manage-floorplan	The floor plan designer, drawing zones, calibration walks	✓	✓
View Organisation	view-organisation	The Organisation card on System › Configuration	✓	✓
Edit Organisation	edit-organisation	Saving it, and the Notifications list of who is told	✓
View · Tenants (and Create, Edit, Delete)	view-tenants …	Platform operators only; no effect inside your organisation	✓

Rules & Alerts

On the role form	Permission	Unlocks	A	M	V
View Rules	view-rules	Rules	✓	✓	✓
Create · Rules	create-rules	Saving a new rule, Describe	✓	✓
Edit · Rules	edit-rules	Editing a rule, Run it now on the Rules list (shown while the rule is on)	✓	✓
Delete · Rules	delete-rules	Deleting a rule	✓
Manage Impact Events	manage-impact-events	Reports › Impact Events	✓	✓
View Battery Alerts	view-battery-alerts	Battery alerts on the sensor list	✓	✓	✓
View Anomalies	view-anomalies	Monitor › Anomalies	✓	✓	✓
View Work Orders	view-work-orders	The work-order list in the admin console	✓	✓	✓
Manage Work Orders	manage-work-orders	Creating, changing and closing them; recurring schedules	✓	✓
Manage Data Tables	manage-data-tables	System › Data tables	✓	✓

Reports

Each report's permission opens that report's page. All three shipped roles have every one of them, except where shown.

On the role form	Permission	Unlocks	A	M	V
View Enter/Exit Report	view-report-enter-exit	Enter / Exit	✓	✓	✓
View Footfall Report	view-report-total	Footfall	✓	✓	✓
View Loyalty Report	view-report-loyalty	Loyalty	✓	✓	✓
View Attendance Report (named people's times on site)	view-report-attendance	Attendance, and scheduling or receiving it by email	✓	✓	✓
View Asset Utilisation Report	view-report-asset-utilisation	Asset Utilisation, and scheduling or receiving it	✓	✓	✓
View Dwell Time Report	view-report-dwell-time	Dwell Time	✓	✓	✓
View Movement Flow Report	view-report-flow	Flow	✓	✓	✓
View People Count Report	view-report-people-count	People Count, Room Usage Map, Space Utilisation	✓	✓	✓
View Heatmap Report	view-report-heatmap	Heatmap, Detection Heatmap	✓	✓	✓
View Environment Report (temperature / humidity / noise)	view-report-environment	Environment, Zone compare, compliance reports	✓	✓	✓
View Battery Report	view-report-battery	Battery	✓	✓	✓
View Distance Report	view-report-distance	Distance	✓	✓	✓
View Button Press Report	view-report-button-press	Trigger Event	✓	✓	✓
View Sensor Status Report	view-report-device-status	Sensor Status, Gateway Availability, Sensor Trail, Outdoor Activity, GPS Replay; scheduling or receiving Gateway Availability or Outdoor Activity	✓	✓	✓
View Gender Entry Report	view-report-gender-entry	The gender entry report (no menu item)	✓	✓	✓
View · Report Alerts	view-report-alerts	Monitor › Central Alerts	✓	✓	✓
View Rule & Alert Effectiveness Report	view-report-rule-effectiveness	Rule & Alert Effectiveness	✓	✓	✓
View Panic & Incident Response Report	view-report-incident-response	Panic & Incident Response, Fall & Man-down; scheduling or receiving Panic & Incident Response	✓	✓	✓
View Meeting Room Usage Report	view-meeting-room-usage	The Meeting Room app's usage report	✓	✓	✓
View Custom Report	view-report-dynamic	Custom Reports: the list	✓	✓	✓
Create Custom Report	create-report-dynamic	Making one	✓	✓
Edit Custom Report	edit-report-dynamic	Changing one	✓	✓
Delete Custom Report	delete-report-dynamic	Deleting one	✓
Run Custom Report	execute-report-dynamic	Running one	✓	✓	✓
Schedule Reports	manage-report-subscriptions	System › Schedule Report	✓	✓

AI & Assistant

On the role form	Permission	Unlocks	A	M	V
View OAIA (assistant)	view-oaia	OAIA, when it is switched on for your organisation	✓	✓	✓
Manage OAIA (switch on, Autopilot, keys)	manage-oaia	OAIA's settings	✓	✓
Use AI Reporting	view-report-ai	Reports › AI Reporting	✓	✓	✓
AI Reporting may read Security Watch (and one per app: Meeting Rooms, Facility, Toilet Hygiene, Energy, Visitors, Compliance, Roll Call, Data Centre, Warehouse)	view-report-ai-app-…	Lets AI Reporting answer from that app's data for this role. Without it the assistant says the app's data is not available	✓

Connectors & Integrations

Connectors in the menu needs View Config (below); each connector then needs its own permission, and a connector the role cannot manage is left out of the list.

On the role form	Permission	A	M	V
SMTP (Email) Connector	manage-connector-smtp	✓	✓
SMS Connector	manage-connector-sms	✓	✓
WhatsApp Connector	manage-connector-whatsapp	✓	✓
Telegram Connector	manage-connector-telegram	✓	✓
Webhook Connector (outbound webhooks, ERP)	manage-connector-webhook	✓	✓
MQTT Gateway Connector	manage-connector-mqtt-gateway	✓	✓
HTTP Gateway Connector	manage-connector-http-gateway	✓	✓
TCP Gateway Connector	manage-connector-tcp-gateway	✓	✓
UDP Gateway Connector	manage-connector-udp-gateway	✓	✓
Matter Bridge Connector	manage-connector-matter-bridge	✓	✓
External CMMS Connector (also access control and identity provider)	manage-connector-external-cmms	✓	✓
API Connector	manage-connector-api	✓	✓
Configure S3 Cloud Export	configure-s3-export	✓	✓

Settings & Config

On the role form	Permission	Unlocks	A	M	V
View Config	view-config	Connectors, System › SLA & Uptime, the Labels page	✓	✓
Manage General Config	manage-config-general	The System › Configuration and System › Labels menu items, Device › New sensor types (Custom types tab)	✓	✓
Manage General Settings	manage-settings-general	On Configuration: General Settings, Gateway timing, Indoor Positioning, Fall detection, AI; creating and changing labels	✓
Manage Cron Schedule	manage-settings-cron	The Schedule card on Configuration	✓
Manage Tenant Settings	manage-tenant-settings	Data Retention and Starter Packs on Configuration	✓
Manage System (Queue Monitor)	manage-system	Platform operators' queue monitor	✓
View Platform Usage	view-usage	System › Usage	✓	✓	✓

So a Manager opens System › Configuration and the Labels page but sees most cards locked and cannot add a label: that is the shipped role, not a fault.

Apps & Marketplace

On the role form	Permission	Unlocks	A	M	V
View App Marketplace	view-apps	Apps › Your apps	✓	✓	✓
Manage Tenant Apps	manage-tenant-apps	Turning apps on and off for your organisation, and each app's settings pages (Facility, Meeting Room, Energy, calendars, the mobile app)	✓	✓
View License · Manage License	view-license · manage-license	The License card on Configuration	✓
Manage App Licenses	manage-license-apps	Uploading and retiring app licences	✓
View · Start · End · Manage Roll Call	view-roll-call …	Nothing at present: Roll Call follows each person's app access	✓	View, Start, End

Audit & Permissions

On the role form	Permission	Unlocks	A	M	V
View Audit Trail	view-audit-trail	System › Activity Log; the History on devices, gateways, rules and administrators; scheduling or receiving Access Review	✓	✓
View Permissions	view-permissions	Nothing on its own: the list of permission names at /admin/system/permission (no menu item) opens only for the Admin role	✓	✓

Make a role

Kumar Selvam, the security supervisor, should see the monitor, the people his team looks after, and the panic report, and nothing else.

You need View Roles and Create · Roles, and you can only tick permissions your own role has.

1. Open System › Roles (/admin/system/role). The page is headed Roles, What each role lets an admin see and change, area by area. The tiles Roles, Can change access, Limited to labels and Not used open the matching tab; the list shows each Role, the areas it Can reach, its Entities and who it is Held by.
2. Press Add Role at the top right. The Add Role panel opens on the right.
3. Role Name: Security desk. Pick a name nobody else uses.
4. Access by area: the twelve areas listed above, each set to None, View or Full. View ticks the area's view permissions and nothing that changes things; Full ticks everything in it. To pick permissions one by one, press the chevron at the end of the area's line (Choose permissions one by one); an area set that way shows Custom. Search module… filters the areas; Select All ticks everything. For Kumar, open each area with its chevron and tick View Dashboard, View Monitor (overall), View Monitor · Devices, View Entities, View Panic & Incident Response Report and View Anomalies.
5. Entity access, below the areas: leave All entities, or choose Only entities with these labels and tick the labels (see Limit a role to labels).
6. Press Save. The message says Role created successfully. and the role is in the list.

Check it worked. In the list, the role's Can reach shows the areas it has, an eye on those it can only view, and Held by says Nobody until you give it to someone. Click the role to open it again.

Give someone the role

The role must exist first. There are two ways; use whichever page you are on.

You can give only a role whose permissions you hold yourself, and never change your own.

When you add the person (needs Create · Admins):

1. Open System › Admins (/admin/system/admin) and press Add Administrator at the top right. The Add Administrator panel opens.
2. Active is on: leave it.
3. Username: the name they sign in with, for example kumar.selvam. It must be unused.
4. Role: Security desk.
5. Full Name: Kumar Selvam.
6. Email Address: where notifications and password emails go.
7. Password: at least 6 characters. Tell them separately; they can change it after signing in.
8. Press Save: Administrator created successfully.

They sign in as described in Signing in.

For someone who already has an account (needs Assign · Roles):

1. Open System › Roles and click Security desk. The Edit Role panel opens.
2. Below Save, under Assigned Admins, press Add Administrator.
3. Type part of their username, name or email in Search by username, name or email… and click them: Role assigned successfully. Because an admin holds one role, this replaces the role they had.

Or open System › Admins, click their row, press Edit in the panel, change Role and press Save.

Check it worked. On System › Admins their Role column shows the new role. Ask them to sign out and in again, or just reload: the menu follows the role on the next page they open.

Limit a role to labels

Entity access limits which people and assets an admin with the role can see, by the labels on them. Kumar's team should see only the people labelled Security staff.

1. Label the people first: open Entity, edit each person, and add the label (or create it under System › Labels). The role form lists the labels that can be put on people and assets; with none it says No entity labels yet. Add a label to an entity first.
2. Open System › Roles and click the role.
3. Under Entity access choose Only entities with these labels. The list of labels appears.
4. Tick Security staff. Tick several to allow any of them.
5. Press Save: Role updated successfully.

What it limits, as the form says: Entity, Entity Monitor and the entity pickers for admins with this role. Reports are not limited. Also Live Monitor's people and the dashboard's figures about them. Someone with this role who adds or edits a person must keep one of the role's labels on them. A person outside the labels cannot be opened at all, even by a link.

Choosing Only entities with these labels and ticking nothing means the role sees no people or assets at all. Choose All entities to remove the limit.

Change, rename or delete a role

• Change permissions or the name: click it, change, Save. It takes effect for everyone holding it on their next page. Not possible for the role you hold, or a role with permissions you lack.
• Take someone off a role: click the role, and press the remove button beside them under Assigned Admins: Role removed from admin. They then have no role, so no permissions at all, until you give them another. Not possible for yourself, or for someone above you.
• Delete: press the delete button (Delete role) on its row, then confirm Are you sure you want to delete this? with Delete. The Not used tab lists the roles nobody holds. A role anybody still holds is refused with Cannot delete role. It is still assigned to administrators. Move them first.

App users are different

App users have no role. Their access is set per app, on their own form.

1. Open Apps › App Users (/admin/app-users) and press New app user. With no app switched on the page says No app is enabled for this organisation — enable one on Your apps first.
2. Email, and optionally Full name, Job title, Phone.
3. Linked entity: the person on the Entity page this login belongs to, so the apps can tie what they do to where their tag is.
4. Initial password (optional, min 8 chars) and Confirm password. Leave both blank and they sign in with a link emailed to them.
5. Active: on.
6. Under App access, Role: Member (Cleaner, technician — uses the app, no settings.) or App admin (Can configure the apps they are given.). This only ticks the Configure switches below for you.
7. Tick each app they use. Beside it, choose All records or Their own + unclaimed (hides work assigned to other people, still shows unassigned work to claim), and switch Configure on if they may change that app's settings.
8. Press Save at the foot of the panel.

App users never see the admin console. What they change in an app is recorded in the Activity Log under In the apps, by the name of the action, never with what they typed; see Who did what. An admin who also works in an app can be given an app login with Import admin.

Questions and problems

A colleague says a menu item has gone. Their role lacks the permission in the tables above, or the app is switched off. Compare their role on System › Roles: the Can reach column, or click the role.

They can see the Configuration page but every card says Not Permitted. The role has Manage General Config (the menu item) but not the card's own permission: Manage General Settings, Manage Cron Schedule or Manage Tenant Settings.

A permission is not on the role form. It belongs to a module your licence does not include.

Add Administrator says Admin already has this role. They already hold it.

Saving says You cannot give permissions you do not hold yourself or … has permissions you do not hold. See What nobody can give: ask someone whose role has those permissions, usually an Admin.

A Manager cannot change their own role or permissions. That is deliberate; another administrator has to.

Roles you edited are not reset by an Omaya update. Updates only add new permissions to the shipped roles (Admin, and Manager or Viewer where they ship with it). A permission you took off a role stays off.

A new admin cannot see anything. Their role has no permissions ticked, or they were taken off their role and have none. Give them a role.

Someone with a label-limited role cannot save a person. The person would end up with none of the role's labels. Keep one of them on.

→ Signing in · Who did what: Activity Log and Usage · Administration menu