Skip to main content

Tasks Setup (Frappe ToDo)

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: LOW Time Required: 10-15 minutes Owner: Platform Team

This runbook covers the setup and configuration of task management using Frappe's built-in ToDo system integrated with the EGI mobile app.

Overview​

The Tasks module enables:

  • Task creation and management via mobile app
  • Integration with Frappe ToDo
  • Custom task lists and categories
  • Assignment and collaboration
  • PostHog analytics tracking

1) Frappe ToDo Configuration​

Built-in ToDo DocType​

Frappe includes a built-in ToDo DocType with standard fields:

  • description (Text Editor) - Task description
  • status (Select) - Open, Closed, Cancelled
  • priority (Select) - Low, Medium, High
  • date (Date) - Due date
  • allocated_to (Link → User) - Assigned user
  • reference_type (Data) - Linked DocType
  • reference_name (Data) - Linked document

No custom DocType creation needed!

2) Add Custom List Field (Optional)​

For enhanced organization with custom lists like "Inbox", "Today", "Urgent", etc.

Create Custom Field​

  1. Go to Frappe Desk → Customization → Custom Field
  2. Click New
  3. Configure:
    • DocType: ToDo
    • Label: EGI List
    • Field Type: Select
    • Fieldname: egi_list
    • Options: 
      Inbox
      Today
      This Week
      Urgent
      Someday
      Projects
    • Insert After: description
  4. Save

Set Default Value​

# In Frappe console
import frappe

# Set default list to "Inbox"
frappe.db.set_value("Custom Field",
    {"dt": "ToDo", "fieldname": "egi_list"},
    "default",
    "Inbox"
)

3) Configure Permissions​

API User Setup​

The mobile app uses the same API user configured for other modules.

Grant Permissions​

# In Frappe console
import frappe

# Grant permissions for ToDo
frappe.permissions.add_permission(
    doctype="ToDo",
    role="All",
    permlevel=0,
    read=1,
    write=1,
    create=1,
    delete=1
)

# Grant read access to User doctype
frappe.permissions.add_permission(
    doctype="User",
    role="All",
    permlevel=0,
    read=1
)

Verify Permissions​

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

4) Mobile App Configuration​

Environment Variables​

Mobile app already configured if Control Center is set up:

# In mobile app .env
EXPO_PUBLIC_FRAPPE_GATEWAY_BASE_URL=https://control-center.egintegrations.com

Test Mobile Integration​

  1. Open EGI mobile app
  2. Navigate to Tasks tab
  3. Create test task:
    • Description: "Test task"
    • List: "Inbox"
    • Priority: "Medium"
  4. Verify task appears in Frappe
  5. Mark task complete in app
  6. Verify status updated in Frappe

5) Advanced Configuration (Optional)​

Task Templates​

Create common task templates in Frappe:

# In Frappe console
import frappe

def create_task_template(name, description, priority="Medium"):
    template = frappe.get_doc({
        "doctype": "ToDo",
        "description": description,
        "priority": priority,
        "status": "Open",
        "egi_list": "Inbox"
    })
    template.insert()
    return template.name

# Create templates
create_task_template("Client Follow-up", "Follow up with client on proposal")
create_task_template("Weekly Report", "Submit weekly progress report")

Recurring Tasks​

Use Frappe's workflow or custom script:

# In Frappe: Create recurring task script
# hooks.py
scheduler_events = {
    "weekly": [
        "egi_mobile.tasks.create_weekly_report_task"
    ]
}

# tasks.py
def create_weekly_report_task():
    import frappe
    frappe.get_doc({
        "doctype": "ToDo",
        "description": "Submit weekly report",
        "priority": "High",
        "egi_list": "This Week",
        "date": frappe.utils.add_days(frappe.utils.today(), 7)
    }).insert()

Monitoring & Analytics​

Uptime Kuma Monitors​

Create monitor for Task API health:

  1. ToDo API Health
    • Type: HTTP(s)
    • URL: https://control-center.egintegrations.com/api/tasks/health
    • Interval: 5 minutes
    • Alert: Slack #alerts-warning

PostHog Analytics​

Track task management events:

// Task created
posthog.capture('task_created', {
  list: 'Inbox',
  priority: 'Medium',
  has_due_date: false,
  user: 'user@example.com'
})

// Task completed
posthog.capture('task_completed', {
  list: 'Today',
  time_to_complete_hours: 3.5,
  was_overdue: false
})

// Task assigned
posthog.capture('task_assigned', {
  assigned_to: 'teammate@example.com',
  assigned_by: 'user@example.com',
  priority: 'High'
})

Create Dashboard: "Task Management Analytics"

Useful insights:

  • Tasks created per day/week
  • Completion rate by list
  • Average time to complete
  • Overdue tasks count
  • Tasks by priority distribution
  • Most active users
  • Peak task creation times

Slack Notifications​

Configure notifications:

  • High priority task created → #tasks-urgent
  • Task overdue → #tasks-reminders
  • Task assigned to you → Direct message
  • Daily task summary → #team-updates

Example notification setup:

# In Frappe: Add notification doctype
# Notification: Task Assigned
{
    "document_type": "ToDo",
    "event": "Save",
    "method": "None",
    "message": "Task assigned: {{ doc.description }}",
    "subject": "New Task Assigned",
    "condition": "doc.allocated_to == frappe.session.user",
    "channel": "slack",
    "slack_webhook_url": "https://hooks.slack.com/services/..."
}

Troubleshooting​

Tasks Not Syncing​

Check API connection:

# Test ToDo endpoint
curl -X GET https://{frappe-instance}/api/resource/ToDo \
  -H "Authorization: token `{api_key}`:`{api_secret}`"

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

# Test from mobile app
# Check network tab in developer tools

Custom Field Not Appearing​

Verify field creation:

# Check via API
curl -X GET "https://{frappe-instance}/api/resource/Custom Field?filters=[['dt','=','ToDo']]" \
  -H "Authorization: token `{api_key}`:`{api_secret}`"

# Or check in Frappe console
import frappe
fields = frappe.get_all("Custom Field",
    filters={"dt": "ToDo"},
    fields=["fieldname", "label"]
)
print(fields)

Reload DocType:

# In Frappe console
import frappe
frappe.reload_doctype("ToDo")
frappe.clear_cache()

Permissions Issues​

Check user permissions:

# In Frappe console
import frappe

user = "user@example.com"
has_permission = frappe.has_permission("ToDo", "create", user=user)
print(f"User `{user}` can create ToDo: `{has_permission}`")

# List user roles
user_roles = frappe.get_roles(user)
print(f"User roles: `{user_roles}`")

Mobile App Not Connecting​

Check environment variables:

# In mobile app directory
eas env:list

# Verify Control Center URL
curl https://control-center.egintegrations.com/api/health

Clear app cache:

  1. In mobile app settings
  2. Clear cache/data
  3. Re-login
  4. Test task creation

Usage Tips​

Task Organization Best Practices​

Lists:

  • Inbox: Default for new tasks
  • Today: Tasks to complete today
  • This Week: Weekly goals
  • Urgent: High priority items
  • Someday: Long-term ideas
  • Projects: Project-specific tasks

Priority Levels:

  • High: Time-sensitive, critical tasks
  • Medium: Important but not urgent
  • Low: Nice to have, flexible timing

Task Writing Tips:

  • Start with action verb (e.g., "Call", "Review", "Send")
  • Be specific about outcome
  • Include relevant context
  • Set realistic due dates
  • Break large tasks into subtasks

Integration with Other Modules​

# Create task linked to project
import frappe

task = frappe.get_doc({
    "doctype": "ToDo",
    "description": "Review project proposal",
    "reference_type": "Project",
    "reference_name": "PROJ-2026-001",
    "allocated_to": "pm@example.com",
    "priority": "High",
    "egi_list": "Projects"
})
task.insert()
# Auto-create follow-up tasks from discovery
import frappe

def create_discovery_followup(session_name):
    session = frappe.get_doc("EGI Discovery Session", session_name)

    # Create follow-up task
    task = frappe.get_doc({
        "doctype": "ToDo",
        "description": f"Follow up on discovery session for {session.customer}",
        "reference_type": "EGI Discovery Session",
        "reference_name": session_name,
        "allocated_to": session.assigned_rep,
        "priority": "High",
        "egi_list": "This Week",
        "date": frappe.utils.add_days(frappe.utils.today(), 3)
    })
    task.insert()

Maintenance Checklist​

Daily:

  • Check task sync status via PostHog
  • Review Slack notifications working
  • Monitor task creation/completion rates

Weekly:

  • Clean up completed tasks (optional archiving)
  • Review overdue tasks
  • Audit task assignments
  • Check analytics trends

Monthly:

  • Review and optimize task lists
  • Update task templates
  • Audit permissions
  • Analyze productivity metrics
  • Update documentation

Performance Optimization​

Index Custom Fields​

-- In Frappe MariaDB console
ALTER TABLE `tabToDo` ADD INDEX idx_egi_list (egi_list);
ALTER TABLE `tabToDo` ADD INDEX idx_status_date (status, date);

Optimize Queries​

# In API endpoint, use efficient filters
tasks = frappe.get_all("ToDo",
    filters={
        "egi_list": "Today",
        "status": "Open",
        "allocated_to": user
    },
    fields=["name", "description", "priority", "date"],
    order_by="priority desc, date asc",
    limit=50
)

Security Considerations​

CrowdSec Integration​

Monitor for:

  • Excessive task creation (potential spam)
  • Rapid task deletion (potential data loss)
  • Suspicious API patterns
# CrowdSec scenario: Task API abuse
type: leaky
name: egi/task-api-abuse
description: "Detect excessive task operations"
filter: "evt.Meta.service == 'tasks-api'"
leakspeed: "10s"
capacity: 30
labels:
  service: tasks
  remediation: ban

Data Privacy​

  • Tasks may contain sensitive information
  • Ensure proper user isolation
  • Implement row-level security
  • Audit task access logs
  • Consider GDPR compliance for task data

Last Updated: 2026-03-25 Version: 1.1