Scan Management

Overview

A scan is what produces everything else OrgGuard does: assets get discovered, policies get evaluated, findings get created, notifications get sent. Each scan creates a Scan Run record with start/end timestamps, counts, and a status.

Scans run on the schedule you set in the Setup Wizard (default: daily). You can also trigger an on-demand scan from the Scan Run History tab.

Who this page is for

Admins who want to verify scans are working, investigate failed scans, or run an immediate scan after making configuration changes.

---

What you’ll see

Scan Run History

Header: Scan Run History title, a help icon, Trigger Scan button (disabled while a scan is running), and a Refresh button.

Data table (10 rows per page) with columns:

Column	Notes
Name	Auto-generated Name (e.g. SR-0001)
Status	Color-coded: Running = neutral/grey, Completed = green, Partial = amber, Failed = red
Started At	Timestamp of scan kickoff
Completed At	Timestamp of scan end (blank while Running)
Assets Seen	Total assets the scan observed
Assets Upserted	Assets inserted or updated (created + changed)
Findings Created	New findings generated this run
Notifications Sent	Notification records queued this run (not emails delivered — see note below)

Pagination: Previous / Next with a “Showing X–Y of Z” label.

Rows are read-only in this component — open the individual Scan Run record page (via the Scan Runs object tab) for full details and the Error Summary field.

---

Common tasks

Task: Trigger an on-demand scan

Use this after creating a new policy, onboarding new asset types, or when you need fresh data immediately.

Who can do this: OrgGuard Admin. Prerequisites: No other scan is currently running (the button is disabled if one is).

1. Open the Scan Run History tab.
2. Click Trigger Scan (top right, brand variant).
3. A toast confirms the scan has started.
4. The button remains disabled while the scan runs.
5. Expected result: a new row appears at the top with Status = Running. Within typically 2–15 minutes (depending on org size), Status flips to Completed and the counts populate.

Caution

An on-demand scan runs in full — it re-scans every asset type even if only one policy changed. It respects governor limits by chaining work across execution contexts, so very large orgs may take longer.

Task: Watch a running scan’s progress

1. After triggering a scan, stay on the Scan Run History tab.
2. Click Refresh periodically, or navigate to the Inventory Dashboard (which auto-refreshes every 5 minutes).
3. Watch Assets Seen and Findings Created climb as the scan progresses.
4. Expected result: Status flips from Running to Completed (or Partial / Failed) when the scan ends.

Task: Investigate a Failed or Partial scan

1. In the Scan Run History, find the Failed/Partial row.
2. Click the row name to navigate to the Scan Run record page (via the standard Salesforce record link, or open the Scan Runs tab for the full object view).
3. Review the Error Summary long-text field — OrgGuard writes a short reason per failed phase.
4. For detailed logs (OrgGuard Admin only), open Diagnostic Logging and enable Support Mode. If you don’t have Admin access, copy the Error Summary field value from the Scan Run record and email it to support@orgguard.com.
5. Common causes and fixes are listed in Troubleshooting below.

Task: Review yesterday’s overnight scan

1. Open Scan Run History.
2. Sort by Started At descending (default).
3. Click the most recent row (likely from 2:00 AM).
4. Check the counts — if Findings Created spikes, open Findings to see the new issues.

Task: Reschedule scans

Scan scheduling is managed outside this page. See Scheduled Jobs for the full walkthrough; quick version:

1. Setup → Scheduled Jobs → find the OrgGuard discovery job.
2. Delete it, then reschedule via the Setup Wizard or an anonymous Apex System.schedule(...) call.

---

Scan pipeline reference

Each scan runs through four phases in order:

1. Discovery — Scans for all supported asset types:
   • Certificates (outbound, inbound mTLS, and Connected App JWT)
   • Connected Apps
   • Auth Providers
   • Named Credentials
   • External Credentials
2. Policy Evaluation — Every enabled policy is evaluated against the assets discovered in Phase 1.
3. Auto-Resolution — Previously Open findings are re-checked; any whose conditions no longer match flip to Resolved.
4. Notifications — Notification records are queued for new/updated findings, respecting each policy’s dedupe window. The scan does not send the emails itself.

If governor limits approach during any phase, the scan chains to a new execution context automatically. Counts accumulate across chained contexts — no data is lost.

Queued vs. delivered

A scan’s Notifications Sent count reflects the Notification records queued during the Notifications phase, not emails delivered in that scan. Email delivery happens separately: the Notification Scheduler runs hourly, groups pending notifications into a per-recipient digest, and sends them. So a scan can show a non-zero count well before any email lands. See Notifications for the digest behavior.

---

Status reference

Status	Meaning	What to do
Running	Scan is in flight	Wait. Don’t trigger another — the button is disabled until completion.
Completed	All phases succeeded	Review counts; investigate if anything unexpected.
Partial	One or more providers hit errors, but others completed	Open the record and read Error Summary. Re-run if the error was transient.
Failed	Scan could not complete	Open the record, read Error Summary. OrgGuard Admin: capture a Diagnostic Logging bundle (enable Support Mode first). OrgGuard User or Auditor: email the Error Summary to support@orgguard.com.

---

Troubleshooting

Symptom	Likely cause	Fix
Trigger Scan button disabled	Another scan is already Running	Wait for the running scan to finish; check the top row’s Status.
Scan stuck in Running	Apex job died silently	Setup → Apex Jobs → find the OrgGuard job; if it’s errored, delete and trigger a fresh scan.
Status = Partial with certs missing	Current user lacks admin-level permissions to read certificate metadata	Re-run as a System Admin or grant the OrgGuard integration user the required permissions.
Assets Seen = 0 on a first scan	Permission gap — scanning user can’t read metadata	Verify Permission Sets; check Coverage Summary Discovery Confidence column.
Findings Created = 0 on a first scan	No policies exist yet or all are disabled	Create/enable policies (see Policies) and re-run.
Notifications Sent = 0 but Findings > 0	All matching policies have Notify Asset Owner and Notify Admin Group off, or dedupe window is suppressing	Edit the policy to enable at least one notification toggle — see Notifications.
Scan took much longer than usual	Org size grew significantly, or diagnostic logging is set to DEBUG	Expected if asset count grew; if log level is DEBUG, lower it (OrgGuard Admin: see Diagnostic Logging).
Error Summary mentions “CPU time exceeded”	One provider phase couldn’t chain in time	Open a support ticket with the scan run name and the full Error Summary text.

---

FAQ

Can I pause or cancel a running scan? Not from the UI. In rare emergencies, a System Admin can abort the underlying Apex job in Setup → Apex Jobs. This leaves the Scan Run record in an inconsistent state — contact OrgGuard Support for cleanup guidance.

How long does a scan typically take? Small org (< 100 assets): 1–3 minutes. Mid-size (100–1,000): 3–10 minutes. Large (> 1,000): 10–30 minutes depending on asset mix and policy count.

Why are there two asset-count columns? Assets Seen is what the discovery phase observed (includes duplicates and unchanged records). Assets Upserted is what actually landed in the asset inventory (new records or records whose fields changed).

Will a scan re-run if it fails? Not automatically. OrgGuard does not retry failed scans — investigate, fix, then trigger manually.

Can I see what was discovered on a specific run? The Scan Run record has summary counts. Per-asset change details for a specific run are not currently exposed in the UI — contact support@orgguard.com if you need a detailed asset-change export for a historical scan.

Does scanning impact end-user performance? No visible impact for users. The scan runs as an Apex batch job with governor limits scoped to async context; end-user UI and API requests are unaffected.

Can I scan a single asset type instead of all five? Not in OrgGuard Pro 1.0. The pipeline runs all providers every time. Targeted scans are on the roadmap.

Can I delete a scan run record? No. Scan Run records are protected audit evidence — deletion is blocked at the platform level regardless of permission set. They are purged automatically by the data-retention policy (default: 90 days). See Data Retention.

---

Related

• Asset Inventory — what scans populate
• Policies — what scans evaluate against
• Findings — what scans produce
• Notifications — what Phase 4 of the pipeline sends
• Coverage Summary — what scans can’t discover
• Scheduled Jobs — the recurring schedule that triggers scans
• Diagnostic Logging — for deep-dive error context on failed scans