Update README with full documentation

2026-04-21 15:58:51 +10:00
parent 70f6d38312
commit 9db292857b
1 changed files with 69 additions and 2 deletions
@@ -1,3 +1,70 @@
-# disco-ad-compare-plugin
+# Disco ICT - AD Compare Plugin

-Disco ICT Plugin - Compare Active Directory user details against Disco records
+A plugin for [Disco ICT](https://github.com/garysharp/Disco) that compares Active Directory user details against Disco's stored records to identify mismatches.
+
+## What It Does
+
+This plugin provides:
+
+- **Full Comparison** — Iterates all Disco users and looks them up in AD, comparing core fields
+- **Mismatch Detection** — Identifies differences in Display Name, Surname, Given Name, Email, and Phone Number
+- **AD Status Checks** — Flags users not found in AD or with disabled AD accounts
+- **Web Dashboard** — In-app UI with filtering, searching, and summary stats
+- **CSV Export** — Download comparison results for reporting
+- **Detail Provider** — Stores comparison metadata as UserDetails for other plugins to consume
+- **Photo Sync** — Pulls `thumbnailPhoto` from AD for user photos
+
+## Fields Compared
+
+| Disco Field     | AD Attribute       |
+|-----------------|--------------------|
+| DisplayName     | displayName        |
+| Surname         | sn                 |
+| GivenName       | givenName          |
+| EmailAddress    | mail               |
+| PhoneNumber     | telephoneNumber    |
+
+## Project Structure
+
+```
+Disco.Plugins.ADCompare/
+├── ADComparePlugin.cs                  # Main plugin class
+├── Features/
+│   ├── ADCompareDetailsProvider.cs     # DetailsProviderFeature implementation
+│   └── ADCompareService.cs            # Core comparison logic
+├── Models/
+│   └── UserComparisonResult.cs        # Comparison result models
+├── WebHandler/
+│   └── ADCompareWebHandler.cs         # Web UI and API endpoints
+├── Properties/
+│   └── AssemblyInfo.cs
+├── Disco.Plugins.ADCompare.csproj
+└── README.md
+```
+
+## Web Handler Endpoints
+
+| Action         | Description                                     |
+|----------------|-------------------------------------------------|
+| `Index`        | Dashboard page with comparison UI               |
+| `Compare`      | Runs full comparison, returns JSON               |
+| `CompareUser`  | Compare single user (`?userId=DOMAIN\username`) |
+| `Export`        | Download results as CSV                         |
+
+## Building
+
+This plugin needs to reference the Disco ICT assemblies (`Disco.Models.dll`, `Disco.Data.dll`, `Disco.Services.dll`). Adjust the HintPaths in the `.csproj` to point at your local Disco build output, or add as ProjectReferences if building within the Disco solution.
+
+## Installation
+
+1. Build the project to produce `Disco.Plugins.ADCompare.dll`
+2. Place the DLL in the Disco plugins directory
+3. Restart Disco ICT
+4. Navigate to the plugin configuration in Disco's admin panel
+5. Click "Run Full Comparison" to see results
+
+## Requirements
+
+- Disco ICT (compatible version)
+- .NET Framework 4.7.2
+- Active Directory connectivity from the Disco server