SRM Portal

The SRM Portal is an internal web application that manages the full billing lifecycle for contractors and projects. It consolidates timesheet data, purchase order limits, payroll reconciliation, and invoice generation into a single workflow.

Core Capabilities

Technology Stack

• Backend: Node.js / Express.js
• Database: SQLite (srm.db)
• Frontend: HTML5, CSS3, Vanilla JavaScript
• Integrations: QuickBooks Online (Intuit OAuth 2.0)

Logging In

1. Navigate to the portal URL in your browser.
2. Enter your Username and Password.
3. Click Login. You will be redirected to the home screen.

Sessions expire after 8 hours of inactivity. You will be automatically redirected to the login page when your session expires.

The portal enforces three access levels:

All data in the portal is organised by period (typically a calendar month, e.g. 2026-04). The period selector is available in the top navigation bar on all data pages.

Creating a New Period

1. Click the period dropdown in the navigation bar.
2. Select + Add Period.
3. Enter the period key in YYYY-MM format (e.g. 2026-05) and a display label.
4. Click Save. The new period is immediately available across all modules.

Switching Periods

Use the period dropdown in the navigation bar to switch between periods. All module data (timesponge, billing, limit order, reconciling) filters to the selected period.

The Timesponge module imports contractor hours from a CSV file exported from your time-tracking system. This is the primary data input that drives billing.

CSV Format

The upload file must contain the following columns (header names are case-insensitive):

Upload Procedure

1. Select the correct period from the navigation bar.
2. Navigate to the Timesponge page (home / index).
3. Drag and drop your CSV file onto the upload area, or click to browse.
4. Review the preview table. Duplicate entries (same person + project + date) are automatically summed.
5. Click Upload to confirm. The table updates immediately.

Manual Entries

Individual rows can be added manually by clicking + Add Row and filling in the inline form. This is useful for corrections or one-off entries.

PO Match Indicator

Each timesponge row displays a colour indicator showing whether the person + project combination has a matching record in PO Details:

• ● Green – Match found; record will be included in Billing Sync.
• ● Orange – No match; record will not appear in billing until a PO Detail is added.

The Limit Order module imports the available invoiceable value per purchase order from your procurement system (e.g. SAP). This data feeds the Forecast and Billing modules to flag potential PO overruns.

CSV Format

Upload Procedure

1. Select the correct period.
2. Navigate to the Limit Order page.
3. Drag and drop your CSV file onto the upload area, or click to browse.
4. Confirm the preview and click Upload.

Rows can also be added or edited manually using the inline table editor.

PO Details is the master reference table linking employees to projects, clients, and purchase orders. It must be maintained accurately for the Billing Sync to work correctly.

Fields

Adding a PO Detail Record

1. Navigate to PO Details.
2. Click + Add Record to open the modal form.
3. Complete all required fields.
4. Click Save.

Bulk Import via CSV

Multiple records can be imported by uploading a CSV with columns: Employee Code, Person, Project, PO Number, Client.

The Billing Summary is the central operational screen. It aggregates timesponge data with PO Details to produce one billing row per employee + project combination per period.

Syncing Billing from Timesponge

1. Ensure Timesponge and PO Details are up to date for the period.
2. Navigate to Billing Summary.
3. Click Sync from Timesponge.
4. The system aggregates hours and populates/updates billing rows. Existing manual adjustments (expense, adjustment, invoice no, etc.) are preserved.

Key Editable Fields

Invoice Status Values

To-Be-Approved Shortcut

The To-Be-Approved button automatically sets Hours to Invoice to the approved hours for all rows in the current period. Use this at the end of an approval cycle to quickly prepare the billing run.

Column Visibility

Click the Columns button to show or hide specific columns. This preference is saved per browser session.

Connecting to QuickBooks

1. Log in as Admin.
2. Navigate to Billing Summary and click Connect to QuickBooks in the toolbar.
3. You will be redirected to the Intuit authorisation page. Log in with your QBO credentials and approve access.
4. You are returned to the portal. The connection status indicator will show Connected.

The OAuth token is stored securely in the database and refreshed automatically. Re-authorisation is required if the token cannot be refreshed (typically after 100 days of inactivity).

Pushing an Invoice to QBO

1. On the Billing Summary page, locate the billing row you want to invoice.
2. Ensure the Status is set to Ready To Invoice.
3. Verify the Client name exactly matches a Customer name in QBO.
4. Click the Push to QBO button (cloud/upload icon) on the row.
5. The system creates the invoice in QBO and stores the QBO Invoice ID and Invoice No back in the billing row.

What Gets Created in QBO

The following line items are added to the QBO invoice:

VAT is applied at 15% on all items except Expense and Adjustment. The invoice due date is set to the 25th of the current month.

Refreshing Invoice Status from QBO

Click Refresh QBO Status in the toolbar to pull the latest payment and email status from QBO for all rows in the current period. Updated fields include:

• QBO Email Status – NotSet / NeedToSend / EmailSent
• QBO Balance – Outstanding amount (0 = fully paid)
• QBO Total – Invoice total as recorded in QBO

Fetching an Invoice Number

If an invoice was raised manually in QBO and you need to pull the document number into the portal, click Fetch Invoice No on the row (requires the QBO Invoice ID to already be populated).

The Forecast page compares actual hours worked against available PO capacity and planned forecast hours, helping identify potential overruns before invoicing.

Key Columns

Entering Forecast Hours

1. Navigate to Forecast.
2. Click the Hours Forecasted cell for the relevant row.
3. Type the planned hours and press Enter or click away to save.

The Reconciling module matches payroll report data (basic salary paid to contractors) against the billing calculations in the portal to identify discrepancies.

Importing the Payroll Report

1. Select the correct period.
2. Navigate to Reconciling.
3. Click Upload Payroll CSV and select the payroll export file.
4. The system matches records by Employee Code:
   • Matched records appear in the main reconciling table.
   • Unmatched records (employee codes not found in billing) appear in the Unmatched table at the bottom for manual review.

Reviewing Discrepancies

The table shows both the Payroll Report Basic (what was paid) and the Calculated Basic Salary (from billing). Rows where these values differ are highlighted in red.

Investigate and resolve any highlighted rows before finalising the period.

Editable Fields

• Payroll Report Basic – Adjust if the import value was incorrect.
• Net Salaries – Net amount paid after deductions.
• FNB Amount – Bank transfer amount for cross-referencing.

Analytics provides a cross-period view of KPIs, trends, and per-person summaries. All periods are aggregated unless a specific filter is applied.

KPI Cards

The dashboard displays the following metrics:

• Total billing records, unique persons, unique projects, unique clients
• Hours Worked, Hours Approved, Hours to Invoice, Hours Not Approved, Banked Hours, Hours Short
• Basic Salary, Management Fee, Subtotal, Expense, VAT, Total (ZAR)
• Invoice Status breakdown (Need SOW / Need PO / Ready / Invoiced / Emailed)

Charts

• Trend Chart: Line graph of key metrics across all periods.
• Status Breakdown: Pie chart of invoice status distribution.

Person Breakdown Table

Per-person cumulative totals across all periods (hours, salary, invoice totals).

The Contracts module tracks contractor engagement contracts, including rate, start/end dates, and contract document links.

Fields

Status Badges

• Active – End date is in the future (beyond 30 days)
• Ending Soon – End date is within the next 30 days
• Expired – End date has passed

Adding / Editing a Contract

1. Navigate to Contracts.
2. Click + Add Contract or the Edit icon on an existing record.
3. Complete the form and click Save.

Creating a User

1. Navigate to Users.
2. Click + Add User.
3. Enter a Username, Password, and select a Role.
4. Click Save.

Editing a User / Changing a Password

1. On the Users page, click the Edit icon next to the user.
2. Update the username, password, or role as needed.
3. Click Save.

Deleting a User

Click the Delete icon next to the user and confirm. Admins cannot delete their own account.

Changing Your Own Password

Any logged-in user can change their own password via the account menu in the navigation bar, without requiring Admin access.

The following formulas are applied automatically by the system when calculating billing amounts. All monetary values are in South African Rand (ZAR).

Follow this sequence at the start of each billing cycle:

Step 1 – Create the New Period

Admin  Add the new period (e.g. 2026-05) via the period selector.

Step 2 – Update PO Details

Add or update PO Detail records for any new contractors or projects starting this period.

Step 3 – Upload Limit Order

Export the limit order report from SAP and upload it to the Limit Order page for the new period.

Step 4 – Upload Timesponge

Export the timesheet CSV from your time-tracking system and upload it to the Timesponge page.

Step 5 – Sync Billing

Navigate to Billing Summary and click Sync from Timesponge. Review the generated rows.

Step 6 – Review Forecast

Check the Forecast page for any rows with negative Hours Short. Resolve PO overruns with the client before invoicing.

Step 7 – Adjust Billing Rows

For each billing row:

• Verify Hours to Invoice (use To-Be-Approved shortcut if applicable).
• Set the correct Status.
• Add any Expense or Adjustment amounts.
• Confirm SDL %, UIF %, COIDA %, and Management Fee %.

Step 8 – Push Invoices to QBO

For each row with status Ready To Invoice, click Push to QBO. Verify the Invoice No is populated.

Step 9 – Upload Payroll Report & Reconcile

Upload the payroll CSV to Reconciling and resolve any discrepancies highlighted in red.

Step 10 – Refresh QBO Status

Click Refresh QBO Status to pull payment and email status from QBO. Confirm invoices are marked Emailed.

Step 11 – Lock the Period

Admin  Once all invoices are confirmed and reconciliation is complete, enable the Sync Lock for the period to protect the data.

All users of the SRM Portal are responsible for maintaining the security and integrity of the system and the personal and financial data it contains. The following policies apply at all times.

Access & Authentication

• Each user must have their own individual account. Shared accounts are strictly prohibited.
• Passwords must be at least 8 characters and combine uppercase letters, lowercase letters, numbers, and symbols.
• Passwords must never be shared, written down in plain text, or stored in unsecured locations.
• Change your password immediately if you suspect it has been compromised. Notify your administrator.
• Sessions expire after 8 hours. Always log out when leaving your workstation unattended.
• Do not use the portal on public or untrusted networks without a VPN.

Role-Based Access Control

• Users must only be granted the minimum role required to perform their job function (principle of least privilege).
• Admin role must be limited to designated system administrators only.
• User accounts must be deactivated or deleted immediately when an employee or contractor leaves the organisation.
• The user list must be reviewed quarterly by an Administrator.

Data Handling

• Do not export or download data unless required for a specific, authorised business purpose.
• CSV files containing personal or financial data must be stored in secure, access-controlled locations and deleted when no longer needed.
• Do not send sensitive data (payroll figures, personal information, invoice details) via unsecured email or messaging platforms.
• Do not share screenshots or screen recordings of the portal containing personal data.

System & Infrastructure

• The host machine running the portal server must be kept updated with operating system and security patches.
• The SQLite database file (srm.db) must be included in regular, encrypted backups.
• Network access to the portal is protected via a Cloudflare Tunnel (see below).
• QuickBooks OAuth tokens are stored in the database — the database file must never be shared or exposed publicly.
• Any suspected security breach must be reported to the system administrator immediately.

Cloudflare Tunnel Protection

The SRM Portal is published to authorised users over the internet via a Cloudflare Tunnel (cloudflared). This eliminates the need to open inbound firewall ports on the host machine. The layers of protection provided, in order, are:

Incident Response

• If unauthorised access is suspected, the administrator must immediately disable affected accounts and review session logs.
• If personal data is exposed or breached, refer to the POPIA and GDPR breach notification obligations in Sections 19 and 20.

The SRM Portal processes personal information of contractors and employees as defined under the Protection of Personal Information Act 4 of 2013 (POPIA), which governs the lawful processing of personal information in South Africa. All users must comply with the following obligations.

What Personal Information Is Processed

The portal processes the following categories of personal information:

Lawful Basis for Processing

• Processing is necessary for the performance of a contract with the data subject (contractor billing and payroll).
• Processing is necessary to comply with a legal obligation (tax, UIF, SDL, COIDA statutory requirements).
• Processing is necessary for the legitimate interests of the organisation (financial record-keeping and invoice management).

Data Subject Rights (POPIA Section 5)

Contractors and employees have the following rights regarding their personal information:

• Right to be notified – Data subjects must be informed that their information is being processed.
• Right of access – Data subjects may request a copy of their personal information held in the system.
• Right to correction – Data subjects may request correction of inaccurate personal information.
• Right to object – Data subjects may object to processing in certain circumstances.
• Right to deletion – Data subjects may request deletion of personal information where there is no lawful basis to retain it.

Requests must be directed to the designated Information Officer within the organisation.

Data Retention

• Billing and payroll records must be retained for a minimum of 5 years in accordance with the Companies Act and SARS requirements.
• Personal information of contractors who have left the organisation must be reviewed annually and deleted or anonymised once the retention period has expired.
• CSV export files must be deleted from local machines once processed.

Breach Notification

• Any actual or suspected breach of personal information must be reported to the Information Regulator and affected data subjects as soon as reasonably possible (POPIA Section 22).
• The administrator must document all breaches, their scope, and remediation actions taken.

Where the organisation operates in or processes personal data of individuals located in the European Economic Area (EEA), the General Data Protection Regulation (EU) 2016/679 (GDPR) applies in addition to POPIA. Many GDPR principles align with POPIA; the following outlines GDPR-specific obligations.

Lawful Basis for Processing (GDPR Article 6)

Data Subject Rights (GDPR Chapter III)

All rights requests must be responded to within 30 days and directed to the Data Protection Officer (DPO) or designated contact.

Data Minimisation & Purpose Limitation

• Only collect and process personal data that is strictly necessary for billing and payroll purposes.
• Do not use data captured in the SRM Portal for any purpose other than the stated operational purposes.
• Avoid storing sensitive categories of personal data (GDPR Art. 9) in free-text notes fields.

Data Transfers

• Data sent to QuickBooks Online is processed by Intuit Inc. under their Data Processing Agreement. Confirm that your QBO subscription includes appropriate GDPR data processing terms if processing EEA data.
• CSV files must not be transferred to countries outside the EEA (or equivalent adequacy decision countries) without appropriate safeguards in place.

Breach Notification (GDPR Articles 33–34)

• A personal data breach must be reported to the relevant supervisory authority within 72 hours of becoming aware of it.
• If the breach is likely to result in a high risk to individuals, affected data subjects must also be notified without undue delay.
• All breaches must be documented in an internal breach register, including the nature of the breach, categories of data affected, number of individuals affected, and remediation steps.

Data Retention (GDPR Article 5(1)(e))

• Personal data must not be kept longer than necessary for the purpose for which it was collected.
• Retention periods must be documented and enforced. Refer to Section 19 for minimum retention periods applicable under South African law.
• Implement an annual data review to identify and delete or anonymise records that are past their retention period.