Volume 7 • Service Desk, Stakeholders & Collaboration
Contacts & Stakeholders Directory, Decoupled Multi-Company Architecture, Portal Authentication, Document Routing Matrix & Collaborative Notes
Learn how Keystone X decouples individual human stakeholders (Directors, Procurement Officers, Billing Clerks, and External Accountants) from corporate Customer accounts—enabling single-sign-on across multiple companies, automated multi-recipient CC email routing, granular Client Portal security, and cross-ERP collaborative notes.
In This Article
1. Why Keystone X Decouples "People" from "Customer Companies"
In basic accounting software, a "Customer" record only has one name and one email field. That creates major problems in the real world:
- Problem 1 — Different People Handle Different Documents: Inside a corporate client, the *Procurement Manager* needs to receive **Quotations**, the *Accounts Payable Clerk* needs to receive **Tax Invoices**, the *Financial Director* needs **Monthly Statements**, and the *Site Facilities Manager* needs **Job Card & Support Ticket updates**.
- Problem 2 — One Person Manages Multiple Companies: A Group Financial Director, franchise owner, or external bookkeeper often oversees 3, 5, or 10 separate subsidiary companies (`Customer Accounts`).
Keystone X solves both problems with its **Decoupled Contacts & Stakeholders Architecture** (`/people`):
1. Single Identity, Multi-Company Linking
Each individual person is registered once in `/people` with a unique email address. That single person can then be linked to **multiple Customer accounts** simultaneously. Updating their cellphone number or email address in `/people` automatically updates every linked company!
2. Role-Based Document Routing & CC Matrix
On each Customer account, you can assign specific people to specific routing slots (**Primary Contact**, **Billing & Invoices Contact**, **Quotes & Estimates Contact**, **Statements Contact**, or **General Linked Contact**), plus attach comma-separated **Additional CC Emails** (`additional_emails`) to any person.
3. Granular Client Portal Credentials
Every person in `/people` has their own self-service **Client Portal Login** (`is_active`), encrypted password, last-login timestamp (`last_login`), and 1-click **Email Password Reset Link** (`people/sendResetLink/{id}`).
2. The Contacts & People Master Directory (/people)
Navigate to **CRM & Sales → Contacts / People** (`/people`) to open the **Contacts & Stakeholders Master Directory**.
📸 SCREENSHOT PLACEHOLDER
people-contacts-master-directory.pngHow to capture this screenshot:
- Navigate to
/people. - Capture the Premier Header (with Customers, Customize, and Add New Contact buttons), the 4 KPI Telemetry Cards (Total Directory, Assigned Stakeholders, Unassigned Contacts, Portal Active), the 4 Quick Filter Pills, and the Contacts DataTable.
KPI Cards, Quick Filter Pills & Directory Columns
| Directory Element | Description & Interactive Behavior |
|---|---|
| 4 KPI Telemetry Cards |
|
| 4 Instant Quick Filter Pills | Filter the DataTable without page reloads by clicking **Assigned**, **Unassigned**, **Portal Active**, or **All Contacts**, or type in the instant search bar (`#peopleTableSearch`). |
| Column 1: Contact Person | Initials avatar badge, clickable full name (opens `/people/viewPerson/{id}`), and unique reference ID (`#ID-0001`). |
| Column 2: Email & Routing | Clickable `mailto:` **Primary Email** address plus any configured **CC: Additional Emails** (`additional_emails`) shown directly underneath. |
| Column 3: Telephone | One-click `tel:` links for both **Mobile Cellphone** and **Office Telephone**. |
| Column 4: Linked Accounts | Displays cyan company badges (` Company Name`) for every Customer account linked to this person, or an `Unassigned` pill. |
| Column 5: Portal Access | Green `Active` badge if the contact can sign in to the Client Portal, or red `Disabled` badge if locked out. |
| Column 6: Row Actions | 360 Contact Profile (``) (`/people/viewPerson/{id}`), Edit Contact (``) (`/people/edit/{id}`), and Delete Contact (``) (`people/delete/{id}`). Safety Guardrail: Keystone X blocks deletion of any contact currently serving as an active Customer's primary contact until you reassign that company first! |
3. The 360° Contact Profile & Portal Access Control (/people/viewPerson/{id})
Clicking any person's name or the blue eye icon opens their **360° Contact Profile** (`/people/viewPerson/{id}`), divided into two panels:
📸 SCREENSHOT PLACEHOLDER
people-360-contact-profile.pngHow to capture this screenshot:
- Navigate to
/people/viewPerson/{id}for a contact linked to one or more Customer accounts. - Capture the left-hand Personal Profile & Portal Authentication card (showing Last Portal Login, Disable/Enable Portal Access, and Email Password Reset buttons) and the right-hand Associated Customer Accounts table with role badges.
Left Panel: Personal Profile & Portal Security
- Displays **Primary Email**, **Additional CC Emails**, **Office Telephone**, and **Mobile Cellphone**.
- Last Portal Login Audit: Shows the exact date and time (`DD MMM YYYY, HH:MM`) the stakeholder last signed into the Client Self-Service Portal (or `Never logged in`).
- 1-Click Enable / Disable Portal Access (`people/toggleStatus/{id}`): Instantly lock or unlock a contact's portal sign-in credentials with full audit logging (`UPDATE_PERSON`).
- 1-Click Email Password Reset (`people/sendResetLink/{id}`): Generates a cryptographic 64-character token (`bin2hex(random_bytes(32))`) valid for 1 hour (or your configured Studio expiry window) and emails a direct password reset link (`user/reset_contact/{token}`) to their primary email!
Right Panel: Associated Customer Accounts & Routing Roles
Lists every corporate or individual Customer account where this person is linked, displaying color-coded badges for their exact **Assigned Routing Roles** on each account:
- Primary Contact — Main executive liaison (`primary_contact_id`).
- Billing & Invoices — Receives Tax Invoices, Pro-Forma Invoices, and Receipts (`billing_contact_id`).
- Quotes & Estimates — Receives commercial proposals for approval (`quote_contact_id`).
- Statements — Receives monthly statements and overdue reminders (`statement_contact_id`).
- General Linked Contact — Authorized stakeholder linked via `customer_contacts`.
4. Onboarding & Editing Contacts: Primary vs. CC Emails & Portal Passwords
Clicking **Add New Contact** (`/people/add`) or **Edit Contact** (`/people/edit/{id}`) provides a clean two-card configuration screen:
| Field / Switch | Exact Purpose & System Behavior |
|---|---|
| First Name & Last Name * | The individual stakeholder's personal name (`contact_first_name`, `contact_last_name`). |
Primary Email Address * (contact_email) |
Must be unique across the contacts registry. Serves as both their **Client Portal login username** and the primary destination for welcome emails and password reset links. |
Additional CC Emails (additional_emails) |
Optional comma-separated list of secondary email addresses (e.g., `accounts@acme.com, pa@acme.com`). Whenever this contact is routed an Invoice, Quote, Statement, or Job Card update, Keystone X automatically copies (`CC`) these addresses according to your Studio Routing Matrix! |
| Office Telephone & Mobile Cellphone | Captures landline (`contact_phone`) and mobile (`contact_cellphone`) numbers for click-to-call and WhatsApp quick-sharing. |
| Manual Password / New Password | • On **Add (`/people/add`)**: Leave `manual_password` blank to auto-generate a secure 8-character random password (`bin2hex(random_bytes(4))`), or type a specific initial password. • On **Edit (`/people/edit/{id}`)**: Leave `new_password` blank to keep their existing password unchanged, or type a new password to override it immediately. |
Email Onboarding Link (send_email) |
(On `/people/add`) When toggled on, dispatches the `contact_welcome` email template containing the Client Portal login URL and their initial password to their primary email address. |
Require Password Change (force_reset) |
When toggled on (`requires_reset = 1`), forces the contact to choose a new private password the moment they sign into the Client Portal for the first time. |
5. The 4-Tab Contacts & Portal Stakeholders Customization Studio (/people/settings)
Clicking **Customize** (`/people/settings`) from the Contacts Directory opens the **4-Tab Contacts & Portal Stakeholders Customization Studio**:
📸 SCREENSHOT PLACEHOLDER
people-stakeholders-customization-studio.pngHow to capture this screenshot:
- Navigate to
/people/settings. - Capture the 4 KPI Telemetry Cards at the top, the 4 Studio Navigation Pills (1. Contact Identity & Onboarding, 2. Client Portal Authentication & Security, 3. Document Routing & CC Matrix, 4. Stakeholder Roles & Directory UI), and the active configuration cards.
| Studio Tab | Configurable Governance switches, Security Policies & Routing Matrix |
|---|---|
Tab 1: Contact Identity & Onboarding (?tab=identity) |
|
Tab 2: Client Portal Authentication & Security (?tab=security) |
|
Tab 3: Document Routing & CC Matrix (?tab=routing) |
|
Tab 4: Stakeholder Roles & Directory UI (?tab=roles) |
|
6. The Cross-ERP Collaborative Notes Engine (note/*)
Across Keystone X—inside **Customers**, **Leads**, **Quotes**, **Invoices**, **Projects**, **Tasks**, and **Vendors**—you will find an integrated **Collaborative Notes & Activity Stream** powered by `NoteController` (`note/add`, `note/edit/{id}`, `note/delete/{id}`).
- Polymorphic Entity Linking (`reference_type` + `reference_id`): Every note is cryptographically tied to the exact record where it was written (e.g., `reference_type = 'project'`, `reference_id = 14`), stamping the author's `user_id` and timestamp.
- Inline Editing & Deletion (`note/edit/{id}` & `note/delete/{id}`): Staff with `edit_notes` and `delete_notes` permissions can update or remove notes directly from the record's Notes tab while seamlessly redirecting back (`redirect_to`) to the exact workspace tab they were viewing.