Skip to main content

Guided Discovery Setup (Frappe + EGI Mobile)

Historical Runbook

This runbook reflects the retired engine-era operating model and is preserved for reference only. It is not part of the current golden path.

Complexity: MEDIUM Time Required: 30-45 minutes Owner: Platform Team

This runbook covers the setup and configuration of the Guided Discovery flow for integration with Frappe and the EGI mobile app.

Overview​

The Guided Discovery module enables structured client discovery sessions through:

  • Frappe DocTypes for template and session management
  • Control Center API integration
  • EGI mobile app interface
  • PostHog analytics tracking

1) Create DocTypes in Frappe​

Create these DocTypes in Frappe Desk → Developer → DocType:

A) EGI Discovery Template​

Required fields (fieldnames must match):

  • template_name (Data) or use the DocType name field
  • version (Data)
  • active (Check)
  • template_json (Long Text)
  • scoring_weights (Long Text) - optional

Optional fields:

  • tags (Data)
  • industry_focus (Data)

Permissions:

  • Read: All users
  • Write: System Manager, Discovery Admin
  • Create: System Manager

B) EGI Discovery Session​

Required fields (fieldnames must match):

  • lead (Link → CRM Lead)
  • opportunity (Link → CRM Deal)
  • customer (Link → Customer)
  • project (Link → Project)
  • template (Link → EGI Discovery Template)
  • template_version (Data)
  • status (Data)
  • assigned_rep (Data)
  • meeting_date (Date)
  • current_section (Data)
  • raw_responses (Long Text)
  • summary (Long Text)
  • next_steps (Long Text)

Permissions:

  • Read: All users
  • Write: Sales Team, Discovery Admin
  • Create: Sales Team

2) Configure Permissions​

Create API User​

  1. Go to Frappe → User
  2. Create new user: egi_discovery_api
  3. Assign roles:
    • Custom Role: Discovery API Access

Grant Permissions​

API user needs access to:

  • EGI Discovery Template (read/write)
  • EGI Discovery Session (read/write)
  • CRM Lead (read/write)
  • CRM Deal (read/write)
  • ToDo (create)
  • Customer (read)
  • Project (read)
# In Frappe console
import frappe

# Grant permissions
for doctype in ["EGI Discovery Template", "EGI Discovery Session", "CRM Lead", "CRM Deal"]:
    frappe.permissions.add_permission(
        doctype=doctype,
        role="Discovery API Access",
        permlevel=0,
        read=1,
        write=1,
        create=1
    )

3) Add Discovery Template​

Create Template Record​

  1. Go to EGI Discovery Template → New
  2. Fill in:
    • template_name: EGI Discovery (Hybrid)
    • version: 1
    • active: ✓ Checked
    • template_json: Paste JSON from template file

Template JSON Location​

# Copy template JSON
cat /Users/elliottgodwin/Developer/egi-engine/docs/templates/egi-discovery-template.json

Validate Template​

# Test template via API
curl -X GET https://{frappe-instance}/api/resource/EGI Discovery Template \
  -H "Authorization: token `{api_key}`:`{api_secret}`"

4) Configure Control Center Environment Variables​

Set these environment variables in Control Center deployment:

Required:

env:
  cc_crm_base_url: "https://{frappe-instance}"
  cc_crm_api_key: "`{api_key}`"
  cc_crm_api_secret: "`{api_secret}`"

Optional Overrides:

env:
  cc_discovery_template_doctype: "EGI Discovery Template"  # default
  cc_discovery_session_doctype: "EGI Discovery Session"    # default
  cc_discovery_stage_field: "status"                       # default
  cc_discovery_stage_value: "DISCOVERY COMPLETE"           # default

Update Helm Values​

# Edit control-center Helm values
helm upgrade control-center ./charts/control-center \
  --set env.cc_crm_base_url="https://{frappe-instance}" \
  --set env.cc_crm_api_key="`{api_key}`" \
  --set env.cc_crm_api_secret="`{api_secret}`" \
  --namespace hq

# Restart control-center to apply changes
kubectl rollout restart deployment/control-center -n hq

Verify Connection​

# Check logs for Frappe connection
kubectl logs -n hq deployment/control-center | grep -i frappe

# Test API endpoint
curl -X GET https://control-center.egintegrations.com/api/discovery/templates

5) Configure Mobile App​

Set Environment Variable​

For Expo mobile app, set:

# In .env file or Expo configuration
EXPO_PUBLIC_FRAPPE_GATEWAY_BASE_URL=https://control-center.egintegrations.com

Rebuild Mobile App​

cd egi-mobile-app

# Update environment
eas update --branch production

# Or full rebuild
eas build --platform all

Test Mobile Integration​

  1. Open EGI mobile app
  2. Navigate to Discovery module
  3. Create test discovery session
  4. Verify session appears in Frappe

Monitoring & Analytics​

Uptime Kuma Monitors​

Create monitors for:

  1. Frappe API Health

    • URL: https://{frappe-instance}/api/method/ping
    • Interval: 5 minutes
    • Alert: Slack #alerts-warning

  2. Control Center Discovery API

    • URL: https://control-center.egintegrations.com/api/discovery/templates
    • Interval: 5 minutes
    • Alert: Slack #alerts-warning

PostHog Analytics​

Track discovery session metrics:

  • Sessions started
  • Sessions completed
  • Average session duration
  • Template usage
  • Completion rate by rep

Create Dashboard:

  1. Log into PostHog
  2. Create dashboard: "Discovery Analytics"
  3. Add insights:
    • Discovery sessions created (count)
    • Session completion rate (percentage)
    • Time to complete session (average)
    • Templates used (breakdown)

Slack Notifications​

Configure alerts for:

  • Discovery session completed → #sales-wins
  • API connection failure → #alerts-warning
  • High session abandonment rate → #sales-ops

Troubleshooting​

Frappe Connection Fails​

Check:

# Verify API credentials
curl -X GET https://{frappe-instance}/api/method/ping \
  -H "Authorization: token `{api_key}`:`{api_secret}`"

# Check Control Center logs
kubectl logs -n hq deployment/control-center | grep -i "frappe"

# Test from Control Center pod
kubectl exec -it -n hq deployment/control-center -- \
  curl https://{frappe-instance}/api/method/ping

Common Issues:

  • Invalid API credentials
  • Firewall blocking requests
  • SSL certificate issues
  • Network connectivity

Mobile App Not Connecting​

Check:

# Verify environment variable
eas env:list

# Check Control Center API
curl https://control-center.egintegrations.com/api/discovery/templates

# Check mobile app logs
# In Expo developer tools

Template Not Loading​

Check:

# Verify template exists in Frappe
curl -X GET https://{frappe-instance}/api/resource/EGI Discovery Template \
  -H "Authorization: token `{api_key}`:`{api_secret}`"

# Check template is active
# In Frappe: EGI Discovery Template → Filters → Active = Yes

# Verify JSON is valid
python -m json.tool template.json

Session Not Creating​

Check:

# Check API permissions
# In Frappe: User → egi_discovery_api → Roles

# Check logs
kubectl logs -n hq deployment/control-center | grep -i "session"

# Test session creation manually
curl -X POST https://control-center.egintegrations.com/api/discovery/sessions \
  -H "Content-Type: application/json" \
  -d '{"template": "EGI Discovery (Hybrid)", "lead": "LEAD-001"}'

Maintenance Checklist​

Weekly:

  • Review discovery session completion rates in PostHog
  • Check for failed API calls in logs
  • Verify templates are up to date

Monthly:

  • Update discovery templates based on feedback
  • Review and optimize session flow
  • Audit API user permissions
  • Update mobile app with latest changes

Security Considerations​

CrowdSec Integration​

Monitor for:

  • Excessive API calls from single IP
  • Failed authentication attempts
  • Suspicious session patterns

Configure rules:

# CrowdSec scenario: Discovery API abuse
type: leaky
name: egi/discovery-api-abuse
description: "Detect excessive discovery API calls"
filter: "evt.Meta.log_type == 'http_access-log' && evt.Parsed.request contains '/api/discovery/'"
leakspeed: "10s"
capacity: 50
labels:
  service: discovery
  remediation: ban

API Key Rotation​

Rotate API keys quarterly:

  1. Generate new API key in Frappe
  2. Update Control Center environment variables
  3. Deploy changes
  4. Revoke old API key
  5. Verify mobile app still working

Future Enhancements​

Planned improvements:

  • Add multi-language template support
  • Implement session analytics in real-time
  • Add automated follow-up task creation
  • Integrate with proposal generation
  • Add voice-to-text for session notes

Last Updated: 2026-03-25 Version: 1.1