Skip to main content

Analyst Journeys

This document describes the complete workflows for analysts using Traces.

Journey 1: Creating a Connector​

An analyst creates a new connector for a platform.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Provide   │ ──▶ │   Review    │ ──▶ │   Config    │ ──▶ │   Publish   │
│   Doc URL   │     │   Draft     │     │   & Test    │     │             │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Steps​

  1. Provide Documentation URL

    • Navigate to Connectors → New
    • Select "Generate from Documentation"
    • Enter API documentation URL
    • Provide platform name
    • Start generation

  2. Review Draft

    • System parses and analyzes endpoints
    • Review LLM recommendations
    • Toggle endpoints enabled/disabled
    • Add analyst notes
    • Verify categories

  3. Configure & Test

    • In the connector editor, use the left tabs: Config (connector configuration, headers, URL), Bulk (bulk enable/disable endpoints), Auth (authentication), Test (test credentials), Notes
    • For each endpoint, use the vertical tabs: Response, Config, Paging, Headers, AI Guide, Curl (plus History and Examine popouts)
    • Configure pagination for list endpoints
    • Set up dependency mappings
    • Test individual endpoints, then the full dependency chain
    • Group endpoints into execution Phases to control ordering

  4. Publish

    • Verify all configuration
    • Publish creates a new connector version (new UUID) and soft-deletes the previous one for forensic integrity; endpoint references are remapped
    • The connector is live for collections

Connector development happens in the draft editor (/analyst/connectors/drafts/[id]); published connectors are edited at /analyst/connectors/[id]/edit.

Key Decisions​

  • Which endpoints to enable
  • Pagination configuration
  • Dependency order and execution phases
  • Rate limit settings

Journey 2: Configuring Pagination​

An analyst sets up pagination for an endpoint.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Identify   │ ──▶ │  Configure  │ ──▶ │    Test     │ ──▶ │   Verify    │
│    Type     │     │   Fields    │     │   Pages     │     │  Complete   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Steps​

  1. Identify Type

    • Test endpoint to see response
    • Look for pagination indicators:
      • Cursor/token field
      • Has_more flag
      • Total count
      • Link headers
    • Determine pagination type

  2. Configure Fields

    • Enable pagination
    • Select type (cursor, offset, page, link_header)
    • Set parameter names
    • Set response paths
    • Configure stop condition

  3. Test Pages

    • Run test with pagination
    • Verify second page requested
    • Check cursor/offset increments
    • Watch for stop condition

  4. Verify Complete

    • All pages retrieved
    • Data count matches expected
    • Stop condition triggered correctly

Journey 3: Setting Up Dependencies​

An analyst maps dependencies between endpoints.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Test      │ ──▶ │   Select    │ ──▶ │    Map      │ ──▶ │   Test      │
│   Source    │     │   Path      │     │   Target    │     │   Chain     │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Steps​

  1. Test Source

    • Run test on source endpoint
    • View response in JSON viewer
    • Identify field with needed values
    • Example: channels[*].id

  2. Select Path

    • Click on field in JSON viewer
    • Path is highlighted
    • Or type path manually

  3. Map Target

    • Drag path to target endpoint
    • Or use mapping dialog
    • Set parameter name
    • Set parameter location (path/query/body)
    • Choose mode (iterate/first)

  4. Test Chain

    • Click "Test Dependency Chain"
    • System runs endpoints in order
    • Values extracted and substituted
    • Review results

Journey 4: Reviewing a Collection​

An analyst reviews and signs off on a completed collection.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Check     │ ──▶ │   Verify    │ ──▶ │   Review    │ ──▶ │   Sign      │
│   Files     │     │   Hashes    │     │   Logs      │     │   Off       │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Steps​

  1. Check Files

    • Open collection in review queue
    • View file list
    • Check file counts by endpoint
    • Verify expected data present

  2. Verify Hashes

    • All files show hash status
    • Confirm "Validated" for each
    • Flag any validation failures
    • Check hash algorithm used

  3. Review Logs

    • Check API logs for errors
    • Review any failed endpoints
    • Verify rate limits respected
    • Note any anomalies

  4. Sign Off

    • Click "Sign Off"
    • Add notes if needed
    • Provide signature
    • Collection moves to delivery

Review Checklist​

  • All enabled endpoints completed
  • File counts reasonable
  • Hashes validated
  • No unexpected errors
  • Chain of custody complete

Journey 5: Troubleshooting Failed Collection​

An analyst diagnoses and resolves a failed collection.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Check     │ ──▶ │  Identify   │ ──▶ │    Fix      │ ──▶ │   Retry/    │
│   Error     │     │   Cause     │     │   Issue     │     │   New       │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Steps​

  1. Check Error

    • Open failed collection
    • Read error message
    • Check which endpoint(s) failed
    • Note error code

  2. Identify Cause

    • Review API logs
    • Common causes:
      • 401: Credential invalid/expired
      • 403: Missing permissions
      • 429: Rate limited
      • 500: Platform error
    • Check request/response details

  3. Fix Issue

    • Credential issue: Contact customer for new creds
    • Connector issue: Update configuration
    • Transient error: May resolve on retry

  4. Retry or New Collection

    • Transient errors: Retry failed endpoint
    • Credential errors: Create new collection
    • Connector errors: Fix connector, new collection

Journey 6: Reviewing Connector Version History​

Each publish creates a new connector version. Analysts can review what changed.

  • Open a connector and go to its History page (/analyst/connectors/[id]/history) — a dedicated git-style diff view keyed by endpoint method + path (it was previously a modal).
  • Soft-deleted prior versions are reconstructed for the diff via the version API.

The Connectors Workspace​

The analyst connectors list (/analyst/connectors) surfaces two header panels to help prioritize work:

  • Recently Worked On — connectors you touched most recently.
  • Up Next — queued items by priority.

A dedicated Roadmap page (/analyst/roadmap, linked from the nav) tracks planned/in-progress connector work.

Navigation is a slim top bar plus a slide-out drawer (Dashboard, Collections, Connectors, Roadmap, Credentials, Customers) — not a fixed sidebar.

System Events​

Collection State Transitions​

pending
   │
   ▼
validating_creds
   │
   ├──▶ error (invalid credentials)
   │
   ▼
queued
   │
   ▼
in_progress
   │
   ├──▶ paused (manual)
   │      │
   │      ▼
   │    resumed
   │      │
   │      └──▶ in_progress
   │
   ├──▶ error (collection failed)
   │
   ├──▶ partial (some endpoints failed)
   │
   ▼
completed
   │
   ▼
reviewing
   │
   ▼
signed_off
   │
   ▼
delivered

Chain of Custody Events​

EventTriggerData Recorded
collection_createdCustomer submitsRequest details, customer ID
credentials_validatedSystem validatesValidation result, timestamp
collection_startedWorker beginsStart time, worker ID
endpoint_completedEach endpoint doneEndpoint ID, file count
collection_completedAll endpoints doneSummary statistics
analyst_assignedAnalyst takes reviewAnalyst ID
analyst_reviewedReview completedReview notes
analyst_signed_offSign-off submittedSignature, timestamp
zip_createdPackage generatedFile path, size, hash
collection_deliveredCustomer notifiedDelivery method
error_occurredAny errorError details, endpoint

Notification Flow​

EventChannelContent
New collectionIn-appAssignment notice
Collection errorEmailError details
Review requiredIn-appReview queue update
Customer verifiedIn-appNew customer ready