Entities
- Code: SET-ENT
- Module: Settings
- Type: Master Data
1. Overview
An Entity (party) is the single identity of a person or organization within the tenant. One entity can act as a user, an employee, and/or a supplier at the same time; for example, a staff member who also logs in to the system only needs one entity linked to their user data and employee data. Entities are not created or edited directly from this page; an entity is formed when creating a user, employee, or supplier, and this page is used to view all entities along with their roles, and to synchronize entities with existing data.
Expected outcome: one person or organization is not recorded as several separate identities, so data such as name and contact stays consistent across all roles.
2. Problem
Without a single identity linking a person’s roles, one person can be recorded repeatedly with inconsistent data. As a result:
- The same person can be registered twice, for example as a user and as an employee, with a different name or email.
- Without a single identity, it is hard to know that employee X is the user who logs in with email Y.
- Old data that is already separated needs a way to be unified.
3. Goals & Non-goals
3.1 Goals
- One person or organization only needs one identity, even when performing several roles at once.
- The relationship between a user account, employee data, and supplier data is visible in one place.
- Old data that was recorded separately can be linked without recreating it.
3.2 Non-goals
- Creating, editing, or deleting entities directly from this page; entities are formed from other features.
- Unlinking an entity from its roles.
- Automatically merging two entities based on similar data.
4. Business Rules
Business rules are the set of provisions and constraints that apply to Entities throughout the application, on every screen and action that involves it, whoever performs it. These rules are the single source of truth: if another part of this PRD appears to differ, the rules here prevail.
- BR-01 One entity may only be linked to one user account, one employee record, and one supplier record.
- BR-02 An entity is formed automatically when a user, employee, or supplier is created from scratch. Creating from an entity uses the existing entity, without forming a new identity.
- BR-03 Synchronization is only available for roles not yet linked to that entity.
- BR-04 Every synchronization and entity change is recorded along with its actor and time.
5. Flow
5.1 Main Flowchart
- Entity List — All entities appear along with the roles they already have as a user, employee, or supplier. Roles that are not yet linked are marked so they can be acted on directly.
- Synchronize Entity — The admin chooses the role to link to that entity.
- Choose Target Data — Existing user, employee, or supplier data is searched and then selected as that entity’s counterpart.
- Validation — The link is checked before saving, including making sure the role is not already used by another entity.
- Entity Linked — The entity and its role data now form a single identity, and its data is consistent across all roles.
6. Document Structure
6.1 General
| Field | Type | Required | Default | Rules |
|---|---|---|---|---|
| Full Name | Text | — | Follows the entity data | Set when the user, employee, or supplier is created (BR-02) |
| Category | Enum | — | Follows the entity data | Individual, Organization, or Company |
| Gender | Enum | — | Follows the entity data | Male, Female, or empty |
| Text | — | Follows the entity data | May be empty | |
| Phone Number | Text | — | Follows the entity data | May be empty, displayed with a ”+” prefix |
| As User | Ref. User | — | — | At most one (BR-01) |
| As Employee | Ref. Employee | — | — | At most one (BR-01) |
| As Supplier | Ref. Supplier | — | — | At most one (BR-01) |
7. UI Structure
This section defines how Entities are displayed and operated: the list columns and the layout of the synchronization dialog. This section only governs display and interaction; content and value rules still follow Document Structure.
7.1 Datatable
| Column | Sortable | Sample Value | Component |
|---|---|---|---|
| Full Name | Yes | Budi Santoso | Text |
| Category | — | Individual | Badge |
| Gender | — | Male | Badge |
| As User | — | budi@toko.com, or Link | Badge, or a “Link” Badge if not linked yet |
| As Employee | — | EMP-0042, or Link | Badge, or a “Link” Badge if not linked yet |
| As Supplier | — | SUP-0012, or Link | Badge, or a “Link” Badge if not linked yet |
| Actions | — | Activity Logs | Action Menu |
7.2 Sync Dialog
Two panels: Source Data shows the origin entity’s data (read-only), and Target Data is used to search for and select one target record.
Source Data
| Field | Control |
|---|---|
| Full Name | Read-only |
| Category | Read-only |
| Gender | Read-only |
| Read-only | |
| Phone Number | Read-only |
| As User, Employee, Supplier Status | Read-only |
Target Data
| Role | Search Table Columns |
|---|---|
| User | Name, Email, Roles, Status |
| Employee | Code, Name, Gender, Store, Status |
| Supplier | Code, Name, Gender, Address, Contact, Status |
One row is selected as the target, then the Link button saves the synchronization.
8. User Stories
US-01 - View the entity list
As an admin, I want to see all entities along with their roles, so that I know who plays which role.
| ID | Acceptance criteria |
|---|---|
| AC-01.1 | Columns: full name, category (individual / organization / company), gender, as user, as employee, as supplier. |
| AC-01.2 | Keyword search, pagination, default sort by name A–Z; only the name column is sortable. |
| AC-01.3 | Linked roles appear as badges: user email, employee code, supplier code. |
| AC-01.4 | Entity without an email or phone — shown as ”-” in the dialog. |
US-02 - Synchronize an entity
As an admin, I want to link an entity with an existing user, employee, or supplier, so that one person is not recorded as separate identities.
| ID | Acceptance criteria |
|---|---|
| AC-02.1 | The Link badge only appears on roles that are not yet linked and for users with the sync permission. |
| AC-02.2 | The dialog shows the source data: name, category, gender, email, phone (prefixed with ”+”), and the status of all three roles. |
| AC-02.3 | The target table follows the role: user (name, email, roles, status), employee (code, name, gender, store, status), supplier (code, name, gender, address, contact, status). |
| AC-02.4 | Only one target can be selected; the Link button is disabled until a target is selected. |
| AC-02.5 | On success, a success toast appears, the dialog closes, and the list is reloaded. |
| AC-02.6 | The selected target is already linked to another entity — such targets are not filtered out during selection. Needs confirmation: whether it is rejected or moved to this entity (BR-01). |
| AC-02.7 | The entity’s name or email differs from the target data — synchronization can still be performed. Needs confirmation: which data is used. |
| AC-02.8 | An entity was linked by mistake — there is no unlink action in the UI yet. |
US-03 - Entity activity history
As an auditor, I want to see the entity activity log, so that identity changes can be traced.
| ID | Acceptance criteria |
|---|---|
| AC-03.1 | The log is available for all entities (button in the header) and per entity (row action), with event, actor, and date range filters. |
9. User Scenarios
| Role | Scenario |
|---|---|
| Admin | Sees which employees do not have a login account yet |
| Admin | Links the employee entity “Budi” with Budi’s user account that was created separately |
| Owner | Checks whether a supplier is also registered as an employee |
| Auditor | Views the activity log for one specific entity |
10. Permissions & Actions
10.1 Permission by Action
| Action | Permission | Condition |
|---|---|---|
| View Entity List | settings:party:list:any | — |
| View Activity Logs | settings:party:list:any | — |
| Synchronize Entity | settings:party:sync:any | Role not yet linked |
11. Notifications
This feature does not trigger any notifications.
12. Dependencies
Related PRDs
- Users, Employees — created from scratch or from an entity (
doesnt_havefilter). - Suppliers (Purchasing module) — suppliers are also entities.
- Activity Logs — the source of the activity log.
Effects on other modules
- The “As Employee/User/Supplier” columns in the Users and Employees lists come from the entity relation.
- The employee linked to the logged-in user is used to determine the PIC on Purchase Orders.