Portal Overview

Brief: The ABM Service Web Portal is a web-based service management system for tracking service calls, customers, actions, timesheets, and job management. Support staff are most commonly contacted about login issues, missing data (users cannot see records they expect), and permission problems.

---

What the User Sees

Users log in with an email and password and are presented with a navigation menu tailored to their assigned roles. Depending on their role, they may see sections such as Calls, Customers, Actions, My Timesheet, Job Manager, or Admin. External users see a filtered view of data; internal ABM users see all data without restriction.

---

Data Flow

1. The user logs in with their email and password.
2. The system looks up the user in the WebPortalUsers table by email, validates the password hash, and issues a JWT (JSON Web Token) containing the user's email and roles.
3. Every subsequent request includes this token. The server validates it and uses the email to look up the user's permissions and data filters from WebPortalUsers.
4. Depending on the user type (external or ABM), the system applies different data access rules before querying the underlying business tables (Calls, Customers, Actions, Jobs, TIMESHEETLINES, etc.).

---

Dual Access System

The portal has two separate data access paths that serve the same underlying database but with different levels of restriction:

Access Path	Who Uses It	Data Filtering
ABM (Internal)	ABM staff with the abmuser role	No filtering — full access to all records
External	External customers/partners with the external role	Role-based filters restrict which customers, call types, and call statuses the user can see

The filters for external users are configured per-user in the WebPortalUsers table columns: CustomersFilter, CallTypesFilter, CallStatusFilter, ActiveCallStatusFilter, StaffFilter, and UsersFilter. These are comma-separated ID lists used in SQL IN clauses.

---

Database Tables

Core User Table

Table	Key Columns	Notes
WebPortalUsers	Email, UserName, PasswordHash, Roles, AccessGranted, AccessControlConfigurationJson, TimesheetStaffId, JobManagerUserNo, ABMUserNo, CustomersFilter, CallTypesFilter, CallStatusFilter	Central user configuration table. Every portal user has one row.

Key Business Tables

Table	Purpose
TIMESHEETLINES	All timesheet entries (time records logged by staff)
TIMESHEETSTAFF	Links staff members to the timesheet system; stores default cost centre and location
TIMESHEETTASKS	Lookup table of available timesheet task categories
TIMESHEETLOCATIONS	Lookup table of work locations
JCOSTCENTRES	Cost centre lookup table
JSTAFF	Staff members (used for staff name lookups)
Jobs	Job records with JobCode, JobTitle, ProjectManager, Status
CopyUserList	Internal user list for job manager assignments (UserNo, UserName)

---

Authentication and Roles

How Authentication Works

1. The user submits email and password.
2. The server queries WebPortalUsers for the matching email and compares the bcrypt password hash stored in PasswordHash.
3. On success, a JWT token is issued containing { email, roles }.
4. The token has an expiration time configured in serverConfig.json under the jwt section.
5. All protected operations require a valid token in the request header.

Role System

Roles are stored as a JSON array in the WebPortalUsers.Roles column. A user can have one or more of the following roles:

Role	Access Granted
admin	Full administrative access: manage users, configure the system
external	External user access: filtered views of calls, customers, actions
abmuser	ABM internal user access: unrestricted data views, dashboard
timesheetuser	My Timesheet: create, edit, submit personal timesheet entries
jobmanager	Job Manager: review and approve timesheet entries for assigned jobs

Permission Details (AccessControlConfigurationJson)

Beyond roles, each user has a JSON permissions object stored in AccessControlConfigurationJson. This controls granular permissions like:

• viewCalls, editCalls, addCalls — call access
• viewCustomers, editCustomers — customer access
• viewActions, editActions, addActions — action access

---

Common Support Scenarios

Scenario: User cannot log in

Symptoms: User enters correct email but login fails.

Diagnosis:

-- Check if user exists and has access
SELECT Email, UserName, AccessGranted,
       CASE WHEN PasswordHash IS NULL THEN 'Not Registered' ELSE 'Registered' END AS RegistrationStatus
FROM WebPortalUsers
WHERE Email = 'user@example.com';

Resolution:

• If AccessGranted is 0, the account is disabled. An admin must re-enable it.
• If PasswordHash is NULL, the user has not completed registration. Re-send the registration invitation.
• If the user simply forgot their password, an admin can trigger a password reset.

Scenario: External user cannot see expected records

Symptoms: User reports that certain customers or calls are missing from their view.

Diagnosis:

-- Check the user's data filters
SELECT Email, CustomersFilter, CallTypesFilter, CallStatusFilter
FROM WebPortalUsers
WHERE Email = 'user@example.com';

Resolution: The filter columns contain comma-separated lists of IDs. If a customer or call type is not included in the relevant filter, the user will not see records associated with it. An admin must update the filter to include the missing IDs.

Scenario: User sees the wrong navigation menu items

Symptoms: User expects to see "My Timesheet" or "Job Manager" but the menu item is missing.

Diagnosis:

-- Check the user's roles
SELECT Email, Roles FROM WebPortalUsers
WHERE Email = 'user@example.com';

Resolution: The Roles column is a JSON array like ["external","timesheetuser"]. If the expected role is missing, an admin must update the user record to add it. For timesheet access, also verify TimesheetStaffId is set. For job manager access, verify JobManagerUserNo is set.

Scenario: Timesheet user gets an error when opening the timesheet page

Symptoms: User has the timesheetuser role but gets an error loading the page.

Diagnosis:

-- Check the timesheet staff link
SELECT Email, RTRIM(TimesheetStaffId) AS TimesheetStaffId
FROM WebPortalUsers
WHERE Email = 'user@example.com';

-- Verify the staff ID exists in the timesheet staff table
SELECT StaffId, DefaultCostCentreNo, DefaultLocation
FROM TIMESHEETSTAFF
WHERE StaffId = '<staff_id_from_above>';

Resolution: The TimesheetStaffId in WebPortalUsers must match a valid StaffId in the TIMESHEETSTAFF table. If it is NULL or points to a non-existent staff record, the timesheet page will fail to load. An admin must correct the mapping.

---

Permissions Reference

Role	Menu Items Visible	Data Scope
admin	Manage Users, App Configuration	All users, all settings
external	Calls, Customers, Actions, Calendar, Map	Filtered by user-specific filters
abmuser	Calls, Customers, Actions, Calendar, Map, Dashboard	All data, no filters
timesheetuser	My Timesheet	Own timesheet entries only
jobmanager	Job Manager	Timesheet entries for jobs where user is Project Manager

---

SQL Quick Reference

-- List all portal users and their roles
SELECT Email, UserName, Roles, AccessGranted
FROM WebPortalUsers
ORDER BY UserName;

-- Find users with a specific role
SELECT Email, UserName, Roles
FROM WebPortalUsers
WHERE Roles LIKE '%timesheetuser%';

-- Check a user's full configuration
SELECT Email, UserName, Roles, AccessGranted,
       CustomersFilter, CallTypesFilter,
       RTRIM(TimesheetStaffId) AS TimesheetStaffId,
       JobManagerUserNo,
       AccessControlConfigurationJson
FROM WebPortalUsers
WHERE Email = 'user@example.com';

-- List all registered users who have completed sign-up
SELECT Email, UserName, Roles
FROM WebPortalUsers
WHERE PasswordHash IS NOT NULL AND AccessGranted = 1;

---

Related Documentation

• Timesheet Overview — timesheet system overview
• Job Manager Overview — job manager system overview