# User Permissions and Record-Level Access

User Permissions are how you tell NexWave that a user can only see specific records: a particular **Company**, **Branch**, **Warehouse**, **Territory**, **Cost Center**, **Item Group**, or **Project**.

Roles answer what kinds of records a user can work with. User Permissions answer which actual records they can see, select, report on, and use in transactions. Use this guide when you are setting up restricted users, checking why a record appears in a dropdown, or investigating why a user can or cannot see a report result.

For the wider access-control model, see [Roles, Permissions & User Access](/doc/91ba21d0-ed81-4f08-898f-846f5c1a43d4).

## Before you start

Confirm these points before changing access:

* You can sign in with a role that can edit **User** and **User Permission** records.
* The user's job role is clear: for example bookkeeper, salesperson, warehouse operator, branch manager, or external accountant.
* The record scope is clear: for example one company, one branch, one warehouse, selected territories, selected cost centres, or selected projects.
* The relevant master records already exist and are named cleanly.
* You have a test user or a safe way to confirm the final access before handing it to the staff member.

Do not use User Permissions to compensate for missing roles. Assign the correct roles first, then narrow the records with User Permissions.

## Decide whether you need roles or User Permissions

Use this rule:

| Need | Use |
|------|-----|
| The user needs to create, read, submit, or approve a type of record | Roles or a Role Profile |
| The user needs the same record type, but only for selected companies, branches, warehouses, territories, customers, suppliers, cost centres, projects, or item groups | User Permissions |
| The user needs to see a field that other users should not see | Permission Levels and Role Permissions Manager |
| The user needs a document approval path | Workflow rules |

Common examples:

* A bookkeeper who works only for one company needs **Accounts User** plus a **Company** User Permission.
* A salesperson who should see only their territory needs **Sales User** plus a **Territory** User Permission.
* A warehouse operator who should transact only in one warehouse needs **Stock User** plus a **Warehouse** User Permission.
* A branch manager who should review only their branch needs the relevant sales or stock roles plus a **Branch** User Permission.
* A department head who should review only their department's figures needs the relevant finance role plus a **Cost Center** User Permission.

If the user genuinely needs the whole module, do not add a User Permission. Roles alone are cleaner.

## How User Permissions work

A User Permission says: for this user, when a document links to a chosen record, only allow the selected value.

For example, a **Company** User Permission restricts standard records, link dropdowns, and reports that check access through company-linked fields. A **Warehouse** User Permission usually restricts stock-related dropdowns, stock reports, and transaction rows that use warehouses.

Some shared documents, blank linked values, fields that ignore User Permissions, and custom reports can behave differently. Verify important access changes with the actual list, report, and **Permitted Documents For User**.

 ![Filtered User Permission list for a training user](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC81MjY3MzgyNS1kMDk2LTQ2NWQtOTFhNC05MjNjODg5MTQ1ZDAvMDEtdXNlci1wZXJtaXNzaW9uLWxpc3QucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MjA5MDAsImV4cCI6MTc5MjcwNzMwMH0.s_1Ky8tRQYT2GStDkx0v5XY1f_9PrHQuYDpBOdREaM0)

## The fields you will use most

| Field | What it does |
|-------|--------------|
| **User** | The NexWave user the permission applies to. |
| **Allow** | The type of record being restricted, such as **Company**, **Branch**, **Warehouse**, **Territory**, **Customer**, **Supplier**, **Cost Center**, **Project**, or **Item Group**. |
| **For Value** | The exact record the user is allowed to access. |
| **Apply To All Document Types** | Applies the permission wherever the chosen record type is referenced. This should usually be ticked. |
| **Applicable For** | Limits the permission to one specific document type. Use only when you need a deliberate exception. |
| **Is Default** | Sets the user's default value for that record type. This is especially important for **Company**. |
| **Hide Descendants** | For tree records such as **Territory** and **Item Group**, limits access to the selected node only and excludes child records. |

## Step 1: Confirm the user's roles

Open the **User** record and confirm the user's roles or Role Profile first.

Check:


1. The user has the base role for their work, such as **Accounts User**, **Sales User**, **Stock User**, **Purchase User**, **Projects User**, or **Employee**.
2. Manager roles are assigned only where approval or configuration access is genuinely required.
3. **System Manager** is not used as a shortcut for ordinary staff access.
4. External customer or supplier users do not have **Desk Access** unless they really need back-office access.

If the user cannot open a document type at all, fix the role first. User Permissions only narrow access after the role grants the feature.

## Step 2: Add the User Permission

From the **User** record:


1. Save the User.
2. Choose **Permissions** > **Set User Permissions**.
3. In the **User Permission** list, click **Add User Permission**.
4. Confirm **User** is the staff member you are restricting.
5. Set **Allow** to the record type, such as **Company**, **Warehouse**, or **Territory**.
6. Set **For Value** to the allowed record.
7. Tick **Apply To All Document Types** unless you are handling a deliberate exception.
8. Tick **Is Default** when the selected value should auto-fill on new records.
9. Save.

 ![Company User Permission form](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC8yMDEzYmY4MS05ZTU5LTQ2NTQtODM1NC1kOWJiZjMzMmM1ZmMvMDItY29tcGFueS11c2VyLXBlcm1pc3Npb24tZm9ybS5wbmciLCJ0eXBlIjoiYXR0YWNobWVudCIsImlhdCI6MTc5MjYyMDkwMCwiZXhwIjoxNzkyNzA3MzAwfQ.OBhfMQ9BhAVXxPtXSMWvAh1XqCTGO1Tn4P4zykbOY-U)

The **Add / Update** button on the **User Permission** list opens a guided dialog for creating or updating several User Permissions. In that dialog, **Document Type** maps to **Allow**, and **Document Name** maps to **For Value**.

For most customer sites, start with **Company**, **Branch**, **Warehouse**, or **Territory**. Add more specific permissions only when the business rule is clear.

## Step 3: Test the access

Always test from the user's point of view before closing the setup task.

Use this checklist:


1. Open a list the user works with, such as **Customer**, **Sales Order**, **Purchase Invoice**, **Stock Entry**, or **Project**.
2. Confirm expected records are visible.
3. Confirm records outside scope are not visible.
4. Open a new transaction and check that the restricted field defaults correctly where expected.
5. Open a key dropdown, such as **Company**, **Warehouse**, **Customer**, **Supplier**, **Territory**, or **Project**, and confirm out-of-scope options do not appear.
6. Run one relevant report and confirm the same scope applies there too.

If the user keeps an old browser tab open, ask them to refresh before retesting.

## Step 4: Use the access report

When access is disputed, administrators can use **Permitted Documents For User** instead of guessing. This report is normally an administrator or **System Manager** check, so some managers may need an administrator to run it for them.


1. Search for **Permitted Documents For User**.
2. Select the user.
3. Select the document type you want to check, such as **Customer**, **Sales Invoice**, **Warehouse**, **Project**, or **Bank Account**.
4. Run the report.
5. Compare the result to the business rule.

Use the report for both types of questions:

* "Why can this user not see this record?"
* "Why can this user see records they should not see?"

If the report shows the record, the user has access through their roles and User Permissions. If the report does not show the record, check the role, the User Permission value, and the linked fields on the record.

## Common setup patterns

### Single-company access

Use this for a multi-company group where staff should work in one company only.


1. Confirm the user has the required finance, sales, purchase, stock, or HR roles.
2. Add a User Permission for **Company**.
3. Set **For Value** to the user's company.
4. Tick **Apply To All Document Types**.
5. Tick **Is Default**.
6. Save and test a new transaction.

The user should now see standard records and reports for that company, subject to shared documents, blank linked values, and any custom report exceptions.

### Branch-only visibility

Use this for multi-branch retail, services, or franchise operations.


1. Confirm the user has the correct operating roles.
2. Add a User Permission for **Branch**.
3. Set **For Value** to the user's branch.
4. Tick **Apply To All Document Types**.
5. Tick **Is Default** if new transactions should default to that branch.

If managers should see child branches, leave **Hide Descendants** unticked.

### Salesperson restricted to a territory

Use this when each salesperson owns a defined customer territory.


1. Confirm the user has **Sales User** and **Employee**.
2. Add a User Permission for **Territory**.
3. Set **For Value** to the territory.
4. Tick **Apply To All Document Types**.
5. Decide whether **Hide Descendants** should be ticked.

The salesperson should see customers, sales documents, and sales reports for that territory, subject to the same exceptions noted above.

### Warehouse operator restricted to one warehouse

Use this when a warehouse user should transact only from their assigned warehouse.


1. Confirm the user has **Stock User** and any required manufacturing or purchase roles.
2. Add a User Permission for **Warehouse**.
3. Set **For Value** to the warehouse.
4. Tick **Apply To All Document Types**.
5. Tick **Is Default** if stock entries should default to that warehouse.

Test by opening a new stock transaction and checking the **Warehouse** dropdown.

### Project-only access

Use this for project teams, consultants, or managers who should see selected projects only.


1. Confirm the user has **Projects User** or the required project-related role.
2. Add a User Permission for **Project**.
3. Set **For Value** to the project.
4. Tick **Apply To All Document Types**.
5. Test **Project**, **Task**, **Timesheet**, and any project reports the user relies on.

### Cost Center scoping

Use this when a department head should review only their own cost centre figures.


1. Confirm the user has the required finance or reporting role.
2. Add a User Permission for **Cost Center**.
3. Set **For Value** to the department's cost centre.
4. Tick **Apply To All Document Types**.
5. Decide whether **Hide Descendants** should be ticked if cost centres are organised as a tree.
6. Test journal entries, expense claims, budgets, and reports the user relies on.

## Setting up multiple permissions

A user can have several User Permissions. The rules are:

| Setup | Result |
|-------|--------|
| Same document type, multiple values | The user can access records matching any of those values. |
| Different document types | The record must match all relevant restrictions. |
| One default value | New records use that value where the field supports a default. |
| No default value | The user may need to choose manually, or NexWave may not know which value to use. |

Example: a salesperson with two **Territory** permissions and one **Company** permission can see records in either territory, but only inside the selected company.

## Review and maintenance checks

Review User Permissions when:

* A user changes branch, warehouse, company, territory, cost centre, or project.
* A user is promoted from operator to manager.
* A staff member leaves and later returns.
* A new branch, warehouse, company, territory, cost centre, or project is added.
* A report shows more or fewer records than expected.
* A dropdown shows options from outside the user's working scope.

Disabling a user does not delete their User Permissions. If you re-enable a user later, review their old permissions before they log back in.

## Troubleshooting

| Issue | What to check |
|-------|---------------|
| User cannot see a record they should see | Confirm the user has the required role, then ask an administrator to run **Permitted Documents For User** for the relevant document type. Check whether the record has the expected **Company**, **Branch**, **Warehouse**, **Territory**, **Cost Center**, **Project**, customer, or supplier link. |
| User can see records they should not see | Check for missing User Permissions, unticked **Apply To All Document Types**, shared records, blank linked values, or an extra role that grants broader access than intended. |
| Dropdown shows too many options | Check whether the restricted value is controlled by a User Permission. Then confirm **Apply To All Document Types** is ticked. |
| Dropdown shows too few options | Check whether **Hide Descendants** is excluding child records, or whether multiple restrictions are combining more tightly than expected. |
| Report totals look lower than a manager expects | User Permissions filter reports. Run the same report as a manager or use **Permitted Documents For User** to confirm scope. |
| New records default to the wrong company, branch, or warehouse | Set one matching User Permission as **Is Default**, or update the default on the **User** record where available. |
| User still sees old results after a change | Ask the user to refresh the browser, then retest with **Permitted Documents For User**. |

## What not to do

Avoid these shortcuts:

* Do not give **System Manager** just to bypass an access problem.
* Do not remove all User Permissions from a restricted user without checking the business rule.
* Do not create one-off roles when a normal role plus User Permission is enough.
* Do not use **Applicable For** unless you know why the restriction should apply to only one document type.
* Do not assume reports ignore User Permissions. Standard reports usually honour them, but custom reports should be checked.

## Related documentation

* [Roles, Permissions & User Access](/doc/91ba21d0-ed81-4f08-898f-846f5c1a43d4): the full access-control model, including roles and Role Profiles.
* [NexWave Role Catalogue](/doc/0f187aaa-8901-4c08-8d99-8ab9cb86090c): role descriptions and recommended role bundles.
* [Role Permissions Manager](/doc/a04ce120-aaa1-444a-825e-543dc636d97b): advanced document-type permission tuning.
* [Set Field-Level Permissions with Permission Levels](/doc/276e86d1-6fa8-4e38-a92b-e4448f08f8a5): hide or expose individual fields by permission level.