Skip to main content

Portal User Workflow

What it is​

The Portal User workflow covers the complete journey from receiving a compliance requirement set to submitting evidence and obtaining assessment results. This guide walks through each stage of that process.

Scenario: A subcontractor submits compliance evidence for a project requirement set.

When to use​

Use this workflow when:

  • You need to demonstrate compliance with a defined set of requirements
  • You have evidence documents ready to upload
  • You want to identify gaps before formal submission

Do not use when:

  • You are configuring the platform (see Admin Workflow)
  • You need to modify requirements or criteria (Admin function)
  • You are debugging system issues (Admin function)

Prerequisites​

Before starting, ensure you have:

  • Platform access URL
  • Evidence documents in supported formats (PDF, DOCX, XLSX, CSV, TXT, or ZIP)
  • Understanding of which requirements your evidence addresses
  • Sufficient time to upload and wait for processing (🧩 Template: timing varies by deployment and document size)

Step-by-step​

Step 1: Access the portal​

  1. Open your browser and navigate to the platform URL
  2. Navigate to the Portal (served at /cm in this repo)
  3. Verify you see the three-panel layout:
    • Left panel: Requirements list grouped by criteria
    • Center panel: Document management
    • Right panel: AI copilot and assessment details

Step 2: Review the requirement set​

Before uploading evidence:

  1. Expand each criterion in the left panel
  2. Read through the individual requirements
  3. Mentally map which of your documents address which requirements
  4. Note any requirements where you lack evidence

Step 3: Prepare your evidence​

Organize your documents before uploading:

  1. Name files descriptively (e.g., "Access-Control-Policy-v2.1.pdf")
  2. Ensure documents are not password-protected
  3. Verify PDFs have extractable text (not just scanned images)
  4. Consider bundling related documents in a ZIP file

Step 4: Upload evidence documents​

  1. Click Upload in the top toolbar
  2. Select one or more files from your computer
  3. Observe the upload progress indicator
  4. Wait for each document to reach READY status

Processing stages:

  • UPLOADED → EXTRACTED → PARSED → INDEXED → READY

Step 5: Start an assessment run​

Once documents are READY:

  1. Click Run Assessment in the toolbar
  2. Confirm the action when prompted
  3. Monitor the run progress indicator
  4. Wait for the run to reach COMPLETED status

Expected duration: 🧩 Template — Timing varies by deployment, document count, and system load.

Step 6: Review assessment results​

For each requirement:

  1. Click the requirement in the left panel
  2. View the assessment status: COMPLETE, PARTIAL, or MISSING
  3. Read the AI reasoning explaining the assessment
  4. Review citations pointing to specific evidence locations

Step 7: Address gaps​

For requirements marked PARTIAL or MISSING:

  1. Review the AI reasoning to understand what's lacking
  2. Check generated tasks for remediation guidance
  3. Either:
    • Upload additional evidence that addresses the gap
    • Note the gap for remediation before final submission

Step 8: Generate exports (optional)​

Once satisfied with coverage:

  1. Locate the Export option
  2. Select the desired export format
  3. Download the compliance report for submission or records

Example​

Scenario: Uploading an access control policy and running assessment.

Input:

  • File: Access-Control-Policy-v2.1.pdf (12 pages)
  • Requirements: 5 requirements under "Access Management" criterion

Process:

  1. Upload the PDF → Status progresses to READY
  2. Start assessment run → Run completes
  3. Check results: (🧩 Template — example values below)
    • Requirement "Documented access control procedures" → COMPLETE (0.94 confidence)
    • Requirement "Privileged access management" → PARTIAL (0.62 confidence)
    • Requirement "Access review schedule" → MISSING (0.15 confidence)

Output:

  • 1 requirement fully satisfied with high confidence
  • 1 requirement partially addressed—additional detail needed
  • 1 requirement not covered—evidence required

Troubleshooting​

Document processing is slow​

Symptom: Documents take unusually long to reach READY.

Causes and fixes:

  • Large file size: Split into smaller documents
  • Complex formatting: Simplify or re-export as plain PDF
  • System load: Wait and try again during off-peak hours

Assessment confidence seems wrong​

Symptom: AI marks requirement as MISSING but you know evidence exists.

Causes and fixes:

  • Evidence is in an image without OCR: Re-export with text layer
  • Terminology mismatch: The AI looks for specific phrases—check if your document uses different terminology
  • Evidence is indirect: The AI expects explicit statements, not implied compliance

Run fails repeatedly​

Symptom: Assessment runs fail without completing.

Causes and fixes:

  • Service unavailable: Wait and retry
  • Specific requirement causes crash: Report to administrator with details
  • Session expired: Refresh page and re-authenticate

Cannot see previously uploaded documents​

Symptom: Documents you uploaded earlier are not visible.

Causes and fixes:

  • Different tenant context: Verify you're in the correct tenant
  • Documents were deleted: Contact administrator
  • Page not refreshed: Hard refresh the browser

Export fails or produces empty file​

Symptom: Export action fails or downloads an empty file.

Causes and fixes:

  • No completed run: Ensure an assessment run finished successfully
  • Run has no assessments: Check that requirements were evaluated
  • Browser blocking download: Check popup blocker settings

UI is unresponsive​

Symptom: Clicking buttons has no effect.

Causes and fixes:

  • JavaScript error: Check browser console for errors
  • Session timeout: Refresh the page
  • Network issue: Check your internet connection

Wrong requirements displayed​

Symptom: The requirements shown don't match your expected pack.

Causes and fixes:

  • Wrong pack assigned to tenant: Contact administrator
  • Criteria not imported: Contact administrator to verify setup

Assessment shows unexpected citations​

Symptom: AI cites documents that seem unrelated.

Causes and fixes:

  • Vector search matched on tangential content: Review the cited passage for context
  • Multiple documents cover similar topics: This is expected behavior—AI considers all evidence

Gotchas and edge cases​

  1. ZIP files create parent-child relationships: When you upload a ZIP, extracted files show as children of the ZIP. Deleting the parent deletes all children.

  2. Re-uploading the same file: The platform uses SHA256 hashes for deduplication. Identical files won't be reprocessed, but modified versions will.

  3. Running assessment with IN_PROGRESS documents: Only READY documents are included. Documents still processing are excluded from the current run.

  4. Concurrent runs: Only one run can be IN_PROGRESS at a time per tenant. Wait for completion before starting another.

  5. Assessment results are point-in-time: If you upload new documents after a run, those documents won't affect past assessment results. Start a new run to include them.

  6. Image files: PNG/JPG files are processed but typically contain minimal extractable text unless they're scanned documents with OCR.