π SystemAdminController Documentation
Welcome to the comprehensive documentation for SystemAdminController.cs in the IrbyImaging.UI.Controllers namespace. This guide covers every aspectβfrom architecture and dependencies to API endpoints, view models, helper utilities, and usage examples.
Table of Contents
- Overview & Purpose
- Dependencies & Technologies
- Class Diagram (Mermaid UML)
- Key Functional Areas
- API Endpoints Overview
- View Models & Data Models
- Helper Methods & Utilities
- Error Handling & Return Types
- Third-party Integrations
- Sample Code Blocks & Usage Examples
- Conclusion
1. Overview & Purpose
SystemAdminController is the central MVC controller responsible for administrative tasks within the IrbyImaging UI:
- π User / Employee Management: CRUD operations, filtering, partial views.
- π₯ Role Management: Create, edit, delete roles; assign/remove users and permissions.
- π Permission Management: Create, edit, delete permissions; link to roles.
- π’ Department Management: Organize employees into departments.
- π Reporting & Auditing: Generate audit logs, access reports, and export data.
It leverages Entity Framework Core (IrbyContext) for data access and integrates with Azure AD, Blob Storage, and several internal services.
2. Dependencies & Technologies
| Category | Technology / Package |
|---|---|
| Framework | ASP.NET Core MVC |
| ORM | Entity Framework Core (Microsoft.EntityFrameworkCore) |
| Caching | Microsoft.AspNetCore.OutputCaching |
| Cloud Storage | Azure Blob Storage (Azure.Storage.Blobs) |
| Authentication / AD | MailKit.Search, internal AzureADRead |
| Config & Environment | Microsoft.Extensions.Configuration, IWebHostEnvironment |
| JSON Serialization | Newtonsoft.Json |
| UI Models & Services | IrbyImaging.UI.Models, IrbyImaging.UI.Services |
| Domain & Business Logic | IrbyImaging.DomainClasses, IrbyImaging.BusinessLogic |
| Utilities | IrbyImaging.Utility, SKiaSharp.HarfBuzz |
3. Class Diagram (Mermaid UML)
classDiagram
class SystemAdminController {
- IrbyContext _context
- Employee _employee
- IHttpContextAccessor _httpContextAccessor
- IUploadService _uploadService
- IWebHostEnvironment _hostingEnvironment
- BlobServiceClient _blobServiceClient
- IConfiguration _configuration
+ SystemAdminController(...)
+ AdminMenu()
+ ViewEmployees()
+ AuditReport()
+ ViewEmployeeDetails(Guid)
+ AccessReport()
+ Filter(string, bool?)
+ FillUsersTable(RoleBasedAccess)
+ UserDetails(Guid)
+ UserEdit(Guid) [GET/POST]
+ DeleteUserRole(...)
+ ... (many more)
}
SystemAdminController --> IrbyContext
SystemAdminController --> IHttpContextAccessor
SystemAdminController --> IWebHostEnvironment
SystemAdminController --> IUploadService
SystemAdminController --> BlobServiceClient
SystemAdminController --> IConfiguration
SystemAdminController ..> Employee
SystemAdminController ..> Role
SystemAdminController ..> Department
SystemAdminController ..> Permissions
SystemAdminController ..> LinkUserRole
SystemAdminController ..> LinkRolePermission
4. Key Functional Areas
4.1 Employee Management π₯
-
View & List
ViewEmployees()β Displays active employees.Filter(string FilterBy, bool? showTerminated)β Search by LastName or GUID, optional include terminated.
-
Details & Edit
ViewEmployeeDetails(Guid Id)β Full profile with Dept/Role/Job and linked roles.UserDetails(Guid id)/UserEdit(Guid id)β GET/POST edit forms.
-
Partial Updates
filter4Users(string surname)/filterReset()β AJAX filtering.DeleteUserReturnPartialView(Guid userId)β Marks user record modified.
4.2 Role Management βοΈ
-
CRUD Operations
RoleIndex(),RoleDetails(Guid),RoleCreate(),RoleEdit(Guid),RoleDelete(Guid).
-
Assignment
AddUser2RoleReturnPartialView(Guid roleId, Guid userId)DeleteUserFromRoleReturnPartialView(Guid roleId, Guid userId)
-
Export
ExportRole(Guid)β JSON dump of a roleβs permissions and assignments.
4.3 Permission Management π
-
CRUD Operations
PermissionIndex(),PermissionDetails(Guid),PermissionCreate(),PermissionEdit(Guid),PermissionDelete(Guid).
-
Linking to Roles
AddPermission2RoleReturnPartialView(Guid roleId, List<string> permissionIds)DeletePermissionFromRoleReturnPartialView(Guid roleId, Guid permissionId)
-
Reverse Linking
AddRole2PermissionReturnPartialView(Guid permissionId, Guid roleId)DeleteRoleFromPermissionReturnPartialView(Guid permissionId, Guid roleId)
4.4 Department Management π’
-
CRUD & Details
DepartmentIndex(),DepartmentDetails(Guid),DepartmentCreate(string, string, List<string>),DepartmentEdit(Guid).
-
Modals
departmentModalRole(Guid),departmentModalEmployee(Guid)
4.5 Reporting & Analytics π
-
Audit Trail
AuditReport()β SQL-based audit log with join on Employee, Role, Department.
-
Access Reports
AccessReport()β Per-user permission summary.GetEmployeeRolesAndPermissionsReport()β Exportable list.GetRolesAndPermissionsReport()β Global view by role/permission.
5. API Endpoints Overview
| Action Method | HTTP Verb | Route (convention) | Description |
|---|---|---|---|
| AdminMenu() | GET | /SystemAdmin/AdminMenu | Landing page for admin menu. |
| ViewEmployees() | GET | /SystemAdmin/ViewEmployees | List non-terminated employees. |
| AuditReport() | GET | /SystemAdmin/AuditReport | Audit trail report. |
| ViewEmployeeDetails(Guid id) | GET | /SystemAdmin/ViewEmployeeDetails/{id} | Detailed employee profile. |
| AccessReport() | GET | /SystemAdmin/AccessReport | System access summary per user. |
| Filter(string, bool?) | GET | /SystemAdmin/Filter | Employee search/filter. |
| RoleCreate(), RoleEdit(), RoleDelete() | GET/POST | /SystemAdmin/{RoleAction} | Role CRUD operations. |
| PermissionCreate(), PermissionEdit(), PermissionDelete() | GET/POST | /SystemAdmin/{PermissionAction} | Permission CRUD. |
| DepartmentCreate(), DepartmentEdit(), DepartmentDelete() | GET/POST | /SystemAdmin/{DepartmentAction} | Department CRUD. |
| ExportRole(Guid id) | GET | /SystemAdmin/ExportRole/{id} | Download role JSON. |
| PartialViewResult β¦ReturnPartialView(...) | GET | AJAX | Dynamic partial views for UI updates. |
6. View Models & Data Models
| Model / DTO | Purpose |
|---|---|
Employee |
Domain entity for staff. |
Role |
System role with description. |
Permissions |
Individual permission. |
Department |
Organizational unit. |
LinkUserRole |
Junction table for extra role assignments. |
LinkRolePermission |
Junction table for role-permission links. |
UserAccessReport |
DTO for AccessReport view. |
SystemAccessList |
DTO for exportable roles/permissions report. |
RoleBasedAccess |
Container for users table filtering. |
7. Helper Methods & Utilities π
-
SetViewBagData(Guid userId)
PopulatesViewBagwith select lists for roles, departments, boolean flags. -
List_boolNullYesNo()
Returns aList<SelectListItem>for tri-state filters: Not Set / Yes / No. -
GetFilteredUserList(string surname)
Safely queries employees byLastName. -
Dispose(bool disposing)
EnsuresIrbyContextis properly disposed.
8. Error Handling & Return Types
- Try/Catch Blocks: Used in partial view updates to swallow exceptions and maintain UI stability.
- ModelState Validation: On POST edits for
RoleandPermissions, validating required fields. - Return Types:
ActionResult: Full-page views & redirects.ViewResult: Strongly-typed views.PartialViewResult: AJAX partial updates.IActionResult/FileResult: File downloads & JSON returns.
9. Third-party Integrations π
- Azure AD via
AzureADReadfor retrieving current user details. - Azure Blob Storage through
BlobServiceClient(future file uploads). - MailKit (imported but not directly used here) for email-related searches.
- SKiaSharp.HarfBuzz (imported but reserved for future graphical operations).
10. Sample Code Blocks & Usage Examples π
10.1 Calling the Audit Report
// Controller action:
public IActionResult AuditReport()
{
var records = _context.AuditReport
.FromSqlInterpolated($"SELECT ... ORDER BY ActivityDate DESC")
.ToList();
ViewBag.datasource = records;
return View();
}
10.2 Filtering Users by Surname via AJAX
// JavaScript fetch:
fetch(`/SystemAdmin/filter4Users?surname=Smith`)
.then(res => res.text())
.then(html => document.querySelector('#usersTable').innerHTML = html);
10.3 Exporting a Role as JSON
public ActionResult ExportRole(Guid id)
{
var json = AccessControl.ExportRole(id, _context, out var name);
return File(Encoding.UTF8.GetBytes(json), "application/json", $"{name}.json");
}
11. Conclusion
The SystemAdminController orchestrates the administrative backbone of the IrbyImaging UIβmanaging employees, roles, permissions, departments, and critical reports. Its modular design with clean separation of view models, helper utilities, and partial views allows for scalable enhancements and responsive UI updates.
Use this documentation as your go-to reference for extending, debugging, or integrating new features into the System Administration area. Happy coding! π