Customer Support & Troubleshooting Guide

For support specialists: how to diagnose, resolve, and escalate user issues

1. Escalation Matrix

flowchart TD
    Issue["User reports issue"] --> T1{"Tier 1:
Self-service / Quick fix?"}
    T1 -->|Yes| Resolve1["Resolve: guide user
through steps"]
    T1 -->|No| T2{"Tier 2:
Configuration / Permission issue?"}
    T2 -->|Yes| Resolve2["Resolve: adjust settings,
permissions, or data"]
    T2 -->|No| T3{"Tier 3:
System / Infrastructure issue?"}
    T3 -->|Yes| Resolve3["Escalate to engineering
with diagnostics"]
    T3 -->|No| Eng["Escalate to engineering
as bug report"]

What to Include When Escalating

• User: email, company name, permission group
• What they tried: exact action (create campaign, run computation, etc.)
• What they saw: exact error message text
• Campaign ID (from URL: /campaign/{campaignId})
• Timestamp of when the issue occurred
• Browser + OS (for frontend issues)
• Health check result: /api/public/health response
• Version: /api/public/version response

2. System Health Checks

Dashboard Rows Quick Guide

3. Error Message Reference

When a user reports an error, find the exact message text below to understand the cause and resolution.

Campaign Errors

Computation Errors

AI / LLM Provider Errors

File Storage & Asset Errors

Authentication & Permission Errors

Validation Errors

Customer App Specific Errors

4. Troubleshooting Scenarios

5. Step-by-Step Guides

How to Create a Campaign (Admin Console)

1. Navigate to Campaigns page
2. Click "Create Campaign" button
3. Enter a unique campaign name
4. (Optional) Select a published template to start from
5. Click Create - the campaign appears in "Not Started" status
6. Add Phases (logical groups, e.g., "Research", "Content")
7. Add Steps within each phase
8. Add Variables (CC Items) within each step - choose types: string, prompt, function, etc.
9. Set up Environment Variables - prompt templates, functions, shared config
10. Assign Document Templates to steps that need rendered output
11. Configure the default AI model for the campaign
12. Click Compute to run the computation engine
13. Review results, override if needed, compute again
14. Generate and publish Assets

How to Fix a Failed Computation

1. Identify which variables failed: look for red "error" state in the campaign grid
2. Click on the failed variable to see the error message
3. Common fixes:
   • Missing prompt key: create the environment variable the prompt references
   • Broken reference: fix the variable key name or path
   • AI error: check API key, model config, and prompt size (see AI errors table)
   • Script error: fix the JavaScript function code
4. After fixing, either:
   • Recompute the single failed variable (right-click -> Compute)
   • Or reset the state to "created" and rerun the full computation
5. If the error persists, check the dependency graph (upstream/downstream views) for circular or broken dependencies

How to Grant Permissions to a User

1. Go to Users page -> find the user
2. Click user -> Company Security tab
3. Select the company
4. Either:
   • Assign a Permission Group (recommended): select a pre-built group like "Campaign Manager" or "Content Editor"
   • Add individual overrides: add Allow overrides for specific permissions
5. User must refresh their browser for new permissions to take effect (session caches permissions)

How to Add / Replace an LLM API Key

1. Go to Model Configs page (or LLM API Keys section)
2. Click "Create"
3. Select the provider (OpenAI, Anthropic, Google, etc.)
4. Paste the API key (OpenAI keys start with sk-)
5. The key enters the "In Pool" state and starts being used immediately
6. If a key is rate-limited, it's auto-disabled temporarily and re-checked every 60 seconds
7. To replace: disable the old key, add the new one

How to Guide a User Through the Customer App

1. Home Page: shows campaign cards. Click "New Campaign" to start, or click an existing card to continue.
2. Step 1 (Fundamentals): campaign name, GTM Foundation (template selection), desired outcomes, timeframe, funnel stage. All required.
3. Step 2 (Audience): select target personas (at least 1), choose segment, add any additional info.
4. Step 3 (Strategy): fill in campaign objective, point of view, content themes, messaging pillars.
5. Step 4 (Execution): describe content strategy, select content formats and distribution channels.
6. Step 5 (Assets): add at least 1 external asset manually. Click "Activate Campaign" to trigger AI generation.
7. After activation: a progress bar shows real-time computation. Wait for completion.
8. Generated state: Steps 1-3 become read-only. Steps 4-5 remain editable with field handlers for incremental updates.
9. AI Assist (if available for the step): click the AI icon to open an embedded chat for help refining content.

6. Known Limitations

Things the System Cannot Do

• No undo/rollback for computations - use audit trail to find previous values and manually override
• No real-time collaborative editing - two users editing the same campaign may overwrite each other's changes (last save wins)
• No automatic AI prompt optimization - prompt quality depends entirely on what the user writes
• No cross-company sharing - campaigns, templates, and storage are isolated per company. Use export/import to transfer.
• No partial rollback after "Start from Template" - once a campaign is created from a template, it's independent. Template changes don't propagate.
• No direct database access for users - all operations go through the REST API
• Cannot publish private storage files - must be in public storage for microsite deployment

7. Admin Console UI Reference

Quick reference of what each main screen shows and what the user can do there.

8. Quick Reference Card

Keyboard Shortcuts

Status Color Coding

Useful URLs