# OGSG Asset Management Onboarding and App Usage Guide

Last updated: 2026-06-28

## Purpose

This guide explains how users are onboarded and how each role should use the OGSG Asset Management application during UAT and pilot operation.

The system uses role-based access for general app areas and assignment-based authority for approvals. There is no standalone `approver` role. A user can approve only when an active approval assignment exists for the correct MDA, approval type, and level.

## Role Summary

| Role | Main purpose | Typical access |
| --- | --- | --- |
| `super-admin` | Technical/platform bootstrap and highest-level administration | Platform user management, central administration, recovery tools, all protected areas through super-admin authority |
| `central-admin` | Central OGSG operations team | MDAs, MDA onboarding codes, central invitations/imports, asset categories, assets, suppliers, budgets, approval assignments, request review, procurement, reports, activity logs |
| `ministry-admin` | MDA administrator | MDA assets, MDA requests, MDA members, MDA invitations, MDA reports, MDA budgets, operational workflows |
| `ministry-accountant` | MDA finance visibility | Assets, financial asset fields, requests, orders, budgets, reports and exports |
| `ministry-member` | MDA operational user | Create/edit/import MDA assets, create/edit requests, view orders |
| `ministry-viewer` | Read-only MDA observer | View MDA assets and requests |
| `supplier` | External vendor | View assigned orders, submit quotations, mark delivery where allowed |

## Onboarding Model

### Central setup for a new MDA

1. Sign in as `super-admin` or `central-admin`.
2. Go to `Admin > MDAs`.
3. Create the MDA with:
   - name
   - code
   - type
   - allowed email domain for first MDA administrator onboarding
4. Open the MDA details page.
5. Generate the internal onboarding code.
6. Send the onboarding link and code to the intended first MDA administrator through an approved internal channel.

Expected result:
- The MDA exists.
- The MDA has an official email domain.
- The onboarding code is shown once after generation.
- No user can self-select an arbitrary MDA without the central onboarding code.

### First MDA administrator onboarding

1. The first MDA administrator opens the onboarding/register page.
2. Select the assigned MDA.
3. Enter the internal onboarding code.
4. Register with an email address that matches the MDA allowed email domain.
5. Verify email if prompted.
6. Complete login and any two-factor challenge.

Expected result:
- The first MDA user is created as `ministry-admin`.
- The user is linked to the correct MDA.
- The user lands on the MDA dashboard.

### Adding more MDA users

1. Sign in as `ministry-admin`.
2. Go to `Ministry > Members` or `Ministry > Invitations`.
3. Invite a user individually or in bulk.
4. Select one of the allowed MDA roles:
   - `ministry-admin`
   - `ministry-accountant`
   - `ministry-member`
   - `ministry-viewer`
5. The invited user opens the invitation link and completes account setup.

Expected result:
- The user is created under the inviting MDA only.
- Removed roles such as `ministry-owner`, `ministry-asset-officer`, and `ministry-request-officer` are not available.

### Supplier onboarding

1. Sign in as `super-admin` or `central-admin`.
2. Go to `Admin > Suppliers`.
3. Create the supplier user with name, email, password, and contact details.
4. Share credentials through the approved operational process.

Expected result:
- The user has the `supplier` role.
- The supplier can access only the supplier dashboard and assigned orders.

## Core Workflows

## 1. MDA and user administration

Central administrators manage MDA records, MDA imports, onboarding codes, and central invitation imports.

MDA administrators manage users inside their own MDA. They cannot manage users in other MDAs.

Use activity logs to verify major user, MDA, invitation, and approval-assignment actions.

## 2. Asset categories

Central administrators manage parent categories and sub-categories from `Admin > Categories`.

Expected controls:
- A category with assets cannot be deleted.
- A category cannot be made its own parent.
- A category cannot use one of its own children as parent.

## 3. Asset registration and management

Central administrators and permitted MDA users can create and update assets.

Common fields:
- asset name
- category
- MDA
- custodian
- location
- purchase/provenance information
- supplier
- serial/reference details
- supporting media

Expected controls:
- Financial/provenance fields are locked after financial lock is applied.
- MDA users can operate only within their MDA scope.
- QR labels and public asset pages expose basic identity only, not internal financial or supplier details.
- Asset import should use the downloaded template.

## 4. Asset lifecycle

Lifecycle actions are workflow-based for sensitive changes:
- transfer
- maintenance
- disposal
- condition report
- physical verification

Expected controls:
- Sensitive lifecycle requests require a valid lifecycle approval assignment.
- The initiator cannot approve their own sensitive lifecycle request unless a super-admin override is explicitly allowed and audited.
- Transfers do not mutate the asset immediately. Approval and receiving-side acceptance are required before the transfer completes.
- Completed lifecycle actions write immutable history.

## 5. Asset requests

MDA users with request permission can create asset requests from `Ministry > Requests`.

Central administrators review requests from `Admin > Requests`.

Expected request path:
1. MDA creates request.
2. Central admin reviews the request.
3. Central admin either fulfills from inventory or forwards to assigned approvers.
4. Assigned approvers approve in sequence.
5. Final approval deducts from the active budget.
6. Approved requests can proceed to procurement if inventory is not used.

## 6. Approval assignments

Approval authority is assignment-based.

Central administrators create assignments from `Admin > Approval Assignments`.

An assignment defines:
- user
- MDA
- approval type
- approval level
- title
- active/inactive status

Expected controls:
- Role membership alone does not grant approval authority.
- The assigned user sees approval work only when an active assignment applies.
- Users can approve only for the assigned MDA/type/level.

## 7. Budgets

Central administrators create and manage budgets. MDA finance users can view budgets according to permission.

Important budget controls:
- One active budget is allowed per MDA/year/organisation/expense-code combination.
- Final request approval deducts the approved amount.
- Duplicate deduction is blocked.
- Insufficient balance blocks final approval.
- Budget extension is restricted to the February closure window.
- Returned-to-treasury values are recorded through the budget status workflow.

## 8. Procurement

Central administrators create procurement orders from approved asset requests.

Supplier flow:
1. Supplier views assigned order.
2. Supplier submits quote.
3. Central admin reviews quote.
4. Central admin confirms, approves variance if required, cancels, or marks delivered.
5. Delivered items create or update asset records as designed by the workflow.
6. Procurement PDF can be downloaded from the order page.

Expected controls:
- Quote totals above approved request amount require variance approval.
- Cancelled or delivered orders should not be edited as active work.
- Supplier can only access assigned supplier portal actions.

## 9. Reports and exports

Central administrators can view and export:
- asset reports
- request reports
- procurement reports

MDA users with reporting permission can view and export MDA-scoped reports.

Expected controls:
- Long-running exports are queued as export jobs.
- Export downloads require authorization.
- MDA report exports must remain scoped to the user's MDA.

## 10. Security and profile

Users can:
- update profile details
- change password
- manage trusted devices
- log out other sessions
- complete email verification
- complete two-factor login challenge where required

Expected controls:
- Login and verification flows are throttled.
- Trusted-device management is available only to the authenticated user.
- Account recovery is restricted to authorized platform administration.

## Pilot Operating Notes

- Use test data only during UAT.
- Do not treat UAT approvals, budgets, or procurement records as official public financial records.
- Record every failed UAT step with screenshot, user role, timestamp, input data, and expected result.
- Run `php artisan app:production-readiness` before any production deployment decision.
- Queue workers and the scheduler must be running in production-like environments for notifications, exports, and operational checks.