43 lines
1.8 KiB
Markdown
43 lines
1.8 KiB
Markdown
# Quickstart: Entra Group Directory Cache (Groups v1)
|
|
|
|
## Goal
|
|
Populate a tenant-scoped cache of Entra ID groups (metadata only) via background sync runs, enabling safe UI rendering without live directory calls.
|
|
|
|
## Prerequisites
|
|
- Graph integration configured (client credentials / app-only)
|
|
- Database migrated (feature migrations applied)
|
|
- Queue worker running for jobs (required for sync)
|
|
- Scheduler/cron running for periodic sync (optional, if enabled)
|
|
|
|
### Local (Sail) quick commands
|
|
|
|
- Bring containers up: `./vendor/bin/sail up -d`
|
|
- Run migrations: `./vendor/bin/sail artisan migrate`
|
|
- Run the queue worker (separate terminal): `./vendor/bin/sail artisan queue:work`
|
|
- Run the scheduler loop (separate terminal, optional): `./vendor/bin/sail artisan schedule:work`
|
|
|
|
## Operator workflow (manual)
|
|
1. Switch into a tenant workspace.
|
|
2. Go to **Directory → Group Sync Runs**.
|
|
3. Click **Sync Groups** (creates/reuses a run and dispatches a background job).
|
|
4. Open the run and wait for status to complete.
|
|
5. Go to **Directory → Groups** and confirm list/search/detail are populated from the cache.
|
|
|
|
Notes
|
|
- Search is cached-only and typically requires at least 2 characters.
|
|
- If the cache is empty, the Groups list will be empty until a sync completes.
|
|
|
|
## Scheduled sync
|
|
- Ensure the scheduler is running (cron or `schedule:work`).
|
|
- Verify **Directory → Group Sync Runs** shows runs with empty Initiator (scheduled).
|
|
- The dispatcher command is `tenantpilot:directory-groups:dispatch` (configured to run every minute).
|
|
|
|
## Verification
|
|
- UI pages that show group IDs render using cached data only.
|
|
- Unresolved IDs show a clear fallback.
|
|
- Groups not seen for >90 days are eventually purged.
|
|
|
|
Suggested validation checks
|
|
- `./vendor/bin/sail artisan migrate:status | grep entra_group`
|
|
- `./vendor/bin/sail artisan schedule:list | grep directory-groups`
|