A practical guide to every workflow.

For: Administrator

Use a native connection only where it is actually implemented.

Before you start

• A Draft period, registered sites, real evidence properties and an authorised client-system owner.

Steps

1. Open Integrations and choose Evidence API for a client backend/automation export, or HubSpot for the supported read connector.
2. Confirm the source contains the chosen evidence type rather than ordinary unrelated CRM fields.
3. Use CSV or client-managed API automation for systems without a native sign-in adapter.
4. Choose the period, sites and history and preview exact field mapping before enabling updates.
5. Agree who owns source evidence and any optional task/report-link write-back fields.

If you get stuck

• Salesforce, Dynamics and SafetyCulture have no native OAuth adapter here.
• The free alerts scheduler is not an integration worker; plan manual operation or a maintained worker explicitly.

For: Technical maintainer

Assign an owner to each background processing responsibility.

Before you start

• Approved repository/runtime access and the operations/integration guides.

Steps

1. For continuous integrations, run the documented integration worker with the shared database and encryption key, or explicitly use pilot manual mode.
2. Monitor worker process health, oldest pending-job age, retry dates and last successful sync; a scheduled timestamp is not liveness.
3. For alerts, inspect the daily GitHub Actions job and the application's opt-in notification outbox.
4. The scheduler uses a short-lived signed GitHub identity bound to the main workflow, canonical audience and verified immutable repository/owner IDs; no permanent app credential belongs in GitHub.
5. After a host/repository move, update the verified canonical origin/identity allowlist and repeat authenticated scheduling acceptance.

If you get stuck

• Do not run unrelated manual workers against the same signer nonce stream or delete active leases to force progress.
• The free alert job does not process integration reconciliation.

For: Administrator

Validate the exact connector settings before activation.

Before you start

• A supported connection, an available sample and a selected Draft period.

Steps

1. Choose one target evidence type and the actual record date/history property.
2. Map each required target field to an exact source key; transform source-specific enum values in the client workflow if needed.
3. Choose the registered sites and history window. Unchecked sites means all registered sites, not no access.
4. Preview and inspect row values, exclusions and errors; resolve every rejection.
5. Enable within the 15-minute preview approval window. Re-preview if settings or period change.
6. For a new reporting period or changed imported scope, choose a new draft and explicit preview; do not expect automatic monthly roll-forward.

If you get stuck

• At least one valid in-scope record is required.
• Unknown sites reject the batch; use exact registered names.
• A sample preview does not itself import the sample.

For: Administrator

Give the client developer a scoped ingestion contract.

Before you start

• An Evidence API connection activated after a clean mapping/scope preview.
• A secure server-side place for the one-time incoming key.

Steps

1. Save the one-time bearer key privately in the client's backend/automation secret store, never in browser code or a support message.
2. POST JSON to /api/integrations/CONNECTION_ID/ingest with Authorization: Bearer and the saved key.
3. Include a stable eventId and 1–1,000 complete mapped records, within 2 MB; stay within the 60 requests/minute/connection cap.
4. Retry identical batches with the same event ID. Use a new event ID after changing corrected records.
5. Poll the same endpoint with ?jobId=JOB_ID or inspect Integrations until the job completes; reconcile imported/rejected counts.
6. Preserve stable source-record IDs for revisions and published snapshot protection.

If you get stuck

• 202 is queued, not imported. Manual-mode or worker availability determines progress.
• Event ID with changed payload conflicts; organisation/type/period come from the connection, not client-supplied tenant fields.
• Disconnect/rotation invalidates old incoming keys.

For: Administrator

Stop future source/destination access deliberately.

Before you start

• An understanding of pending jobs and any in-flight outbound deliveries.

Steps

1. Open the correct connection in Integrations and inspect current jobs/delivery acknowledgements.
2. Pause to cancel pending work and revoke incoming API access when temporarily stopping the connection.
3. Disconnect to remove saved provider credentials, signing secrets and write-back destination.
4. Revoke the app from the provider account when access is no longer needed.
5. Retain and review imported evidence, revisions and history; re-preview and rotate keys deliberately before re-enabling.

If you get stuck

• In-flight imports or requests can complete before the pause takes effect; reconcile them.
• Disconnect is not a delete-history operation.

For: Administrator · Evidence lead

Make source records and site coverage refer to the same real locations.

Before you start

• An agreed real-site register and Administrator/Evidence lead access.

Steps

1. Open Team & sites and review existing names before adding another site.
2. Enter the exact new site name and select Add site.
3. Use the same spelling in source exports, integration mappings, site-scoped claims and control scope.
4. Check Evidence health for site-source appearances after importing the intended period.
5. For a rename, merge or deletion request, plan an authorised scoped correction with the maintainer; there is no general site-edit/delete workflow.

If you get stuck

• Exact duplicate names are rejected; differently spelled duplicates can still split coverage.
• Adding a site does not impose site-level access controls or prove required activities were supplied.

For: Administrator

Give each person the role their work requires.

Before you start

• Named users and an agreed review/administration responsibility map.

Steps

1. Use Director for board reading, Director Q&A and report acknowledgement.
2. Use Evidence lead for draft evidence, verification, publication, site maintenance and assurance/action management.
3. Use Administrator only for people who also need invitations, access control, organisation settings, integrations or external sharing.
4. Ensure at least two appropriate people are available when an owner needs an independent action/control reviewer.
5. Explain organisation-wide visibility. A site field or help audience filter is not a site-level security boundary.

If you get stuck

• There is no general self-service role-change or multi-tenant membership UI; resolve changes through an authorised administrator/maintainer procedure.
• Technical maintainer and External reviewer are help audiences, not selectable workspace roles.

See the role comparison ↓

For: Administrator · Evidence lead

Keep imports and verification tied to the intended month and cutoff.

Before you start

• Real sites and an agreed reporting month/records-to date.

Steps

1. Open Getting started or Overview → Reporting periods → Create reporting period.
2. Enter the reporting month and records-to cutoff and create the Draft.
3. Use that period's Uploads, Claims & verification and View report links from Overview.
4. Check the month and Draft/Published/Signed label before importing or editing.
5. For later/corrected evidence after publication, create a new draft rather than trying to overwrite the sealed period.

If you get stuck

• The main report may prefer the latest published month while a later draft exists; use explicit period links.
• A new integration period needs its own selection and mapping preview.

For: Administrator · Evidence lead

Fix data before reprocessing rather than suppressing validation.

Before you start

• The preview/job error and the original source record.
• For API imports, an administrator and the client integration owner.

Steps

1. Identify the exact row and field named in the preview or integration job results.
2. Check required columns, ISO dates, allowed status/risk/type values, true/false booleans and exact site names.
3. Correct the source record or mapping; do not change a published period.
4. For CSV, preview the corrected file again. For changed API data, submit a new event ID with complete mapped records.
5. Reconcile imported/rejected counts and rerun draft verification when the import completes.

If you get stuck

• Replay is for a resolved temporary/state failure; it cannot magically correct an invalid payload.
• An API 202 only means queued. Inspect the final job status.

See all eight evidence templates and field formats ↓

For: Administrator · Evidence lead

Preserve the historical report while making later records explicit.

Before you start

• A record of what was imported and which reports used it.

Steps

1. Check whether the original report is Draft or already sealed.
2. Do not repeatedly append overlapping CSV exports to simulate updates. Exact-file protection does not deduplicate every business record.
3. Use the integration stable source-ID/revision workflow for ongoing updates where configured.
4. For published evidence, create a new draft/report and explain the correction; keep the original snapshot.
5. If a mistaken draft upload requires removal, ask the maintainer for an approved scoped correction; there is no general delete-upload button.

If you get stuck

• Closing a follow-up action does not repair imported CorrectiveAction rows or rewrite a finding.
• Do not edit the ledger or historical fingerprints to hide an import error.

For: Everyone

Check evidence quality before verification and board review.

Before you start

• A reporting period with its intended records-to cutoff.

Steps

1. Open Evidence health and select the period.
2. Confirm whether the page is assessing current draft records or a published sealed snapshot.
3. Inspect missing/stale/undated sources, after-cutoff dates, expired/expiring licences and incomplete training rows.
4. Review which registered sites appear in site-based sources. Reconcile coverage with operational owners.
5. Inspect Connection health now separately; administrators can open Integrations for detailed job results.
6. Correct the source or record limitations, then rerun draft verification where relevant.

If you get stuck

• Freshness uses a fixed 30-day pilot threshold for selected dated sources.
• Health does not infer missing workers or certify that every required inspection occurred.

For: Administrator

Connect read-only contacts/company properties that hold evidence.

Before you start

• Registered HubSpot app credentials/callback configured by the technical maintainer.
• A client account authorised to approve the requested provider scopes.

Steps

1. Open Integrations and choose HubSpot.
2. Sign into the correct HubSpot account and inspect the requested read consent before approval.
3. Confirm the connected account and select the supported source object and evidence type.
4. Map the actual evidence properties and choose period/site/history scope.
5. Review a clean preview, enable updates and run a controlled sync; reconcile sample records and final job status against HubSpot.

If you get stuck

• Missing client credentials or provider permissions require maintainer/client action; the UI cannot invent an OAuth app.
• The provider grant may cover all contacts/companies even though import filters are narrower.
• Pagination/provider limits and custom-property availability need client-specific acceptance.

For: Administrator

Distinguish source-data errors from transient delivery problems.

Before you start

• The connection's latest sync/job records and access to the responsible source owner.

Steps

1. Open Integrations and inspect status, last successful sync, row errors, queued jobs and retry dates.
2. For invalid records, correct data/mapping at source and submit a new corrected event ID.
3. For a temporary/provider or draft-state failure, resolve the cause before using Replay and Process now.
4. On the free pilot, use Sync now/Process now as appropriate. Ask the maintainer to verify a worker before expecting continuous reconciliation or timed retries.
5. Reconcile source counts and sample values with final COMPLETE results, then review health and draft verification.

If you get stuck

• A displayed next-sync time is not proof that a worker is alive.
• A changed published record needs a new draft.
• Repeated permanent errors require the maintainer/source owner, not unlimited replay.

For: Administrator

Keep source evidence ownership and outbound approval explicit.

Before you start

• An allowlisted HTTPS receiver configured by the technical maintainer.
• An agreed field-ownership policy and receiver signature/idempotency validation.

Steps

1. Configure the permitted client automation destination and signing arrangement privately.
2. Review the proposed outbound task/report-link payload and its source/period references.
3. Approve only the intended action; no outbound delivery should be inferred from merely creating a proposal.
4. Use Send approved action now in manual mode, or monitor the maintained worker.
5. Have the receiver validate signature/time, deduplicate and update only agreed ZoneProof-owned fields. Confirm the CRM result and retained delivery status.

If you get stuck

• There are no unrestricted native CRM writes.
• A changed destination invalidates pending approvals; an in-flight operation can still finish during a pause.
• CRM task completion is not independent evidence verification.

For: Administrator · Technical maintainer

Keep ownership and capacity decisions explicit.

Before you start

• Access to the approved hosting/database/email/GitHub operations dashboards.

Steps

1. Confirm the web/database services remain on the intended free plans and that quotas/spending controls match the owner's preference.
2. Check application readiness, login and a representative private report/PDF after a cold start or release.
3. Use manual integration controls unless a maintained worker is running; inspect the separate alert scheduler and outbox.
4. Review email, storage, compute and Actions usage before onboarding larger datasets.
5. Plan capacity, backup recovery and an approved paid service or host migration when client needs exceed the pilot.

If you get stuck

• Free compute may sleep or scale down and does not imply production SLAs.
• The alert scheduler is not a generic always-on CRM worker.

For: Technical maintainer

Preserve both records and the secrets needed to use them.

Before you start

• An approved target, backup/retention policy and secure secret-transfer process.
• A staged restoration and rollback plan.

Steps

1. Back up the complete PostgreSQL dataset, including evidence revisions/captures, ledger/anchors, meetings, rooms and notification state.
2. Back up required encryption/auth/signing secrets separately with controlled access; encrypted integration data cannot be recovered from the database alone.
3. Restore to a controlled target and apply the documented versioned migrations through a safe release process.
4. Test login, tenant isolation, reports/PDF, snapshots, proof verification, integrations and the alert scheduler before switching traffic.
5. Update the canonical hostname, DNS and provider callbacks only after validation. Revoke old access after replacement verification and preserve approved recovery records.

If you get stuck

• A successful backup command is not a successful restore drill.
• Moving the domain/repository also requires scheduler audience/identity and OAuth/webhook configuration review.