vnclaw-odoo-skill

Integrate with Odoo 17 via XML-RPC API. Use when: managing projects, tasks, calendar events, time off requests, helpdesk tickets, knowledge articles, documents, or timesheets in Odoo 17. Supports read, create, and update operations only. No delete allowed.

# VNClaw — Odoo 17 Integration Skill

## Execution Rules (MUST follow)

1. **ALWAYS run the command immediately.** Never ask the user to confirm or explain what the command does before running it. Translate the request → pick the command → execute it in one step.
2. **Never say "Would you like me to execute this?"** — just execute it.
3. **Never ask "Do you want me to run this?"** — just run it.
4. **If the command fails**, show the error and try to fix it. Do not ask the user for help diagnosing unless you have exhausted all options.
5. **Credentials**: If env vars are missing, inform the user which variable is missing and stop. Do not ask for the value interactively.

## Path Resolution

**IMPORTANT:** All commands below use `SKILL_SCRIPTS` as shorthand for the absolute path to the scripts directory. The skill may be installed in two locations — resolve it by checking both:

```bash
# Resolve SKILL_SCRIPTS from workspace (.github/skills/) or global (~/.vscode/extensions/ or ~/skills/)
SKILL_SCRIPTS="$(
  # 1. Check workspace: .github/skills/vnclaw-odoo-skill/scripts
  _ws_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
  _ws_path="$_ws_root/.github/skills/vnclaw-odoo-skill/scripts"
  # 2. Global fallback locations
  _global_path="$HOME/.vnclaw/skills/vnclaw-odoo-skill/scripts"
  _global_path2="$HOME/.openclaw/skills/vnclaw-odoo-skill/scripts"

  if [ -d "$_ws_path" ]; then
    echo "$_ws_path"
  elif [ -d "$_global_path" ]; then
    echo "$_global_path"
  elif [ -d "$_global_path2" ]; then
    echo "$_global_path2"
  else
    # Last resort: search filesystem
    find "$HOME" /opt -type d -name vnclaw-odoo-skill -path '*/skills/*' 2>/dev/null | head -1 | sed 's|$|/scripts|'
  fi
)"
echo "SKILL_SCRIPTS=$SKILL_SCRIPTS"
```

Possible install locations:

| Location type | Path |
|---------------|------|
| Workspace skill | `<git-root>/.github/skills/vnclaw-odoo-skill/scripts/` |
| User global (vnclaw) | `~/.vnclaw/skills/vnclaw-odoo-skill/scripts/` |
| User global (openclaw) | `~/.openclaw/skills/vnclaw-odoo-skill/scripts/` |

## Environment Variables (Required)

Credentials are loaded from environment variables. **Never hardcode credentials.**

| Variable | Description |
|----------|-------------|
| `ODOO_URL` | Base URL (e.g., `https://mycompany.odoo.com`) |
| `ODOO_DB` | Database name |
| `ODOO_USERNAME` | Login username (email) |
| `ODOO_API_KEY` | API key or password |

## Common Features (All Modules)

All module scripts share these capabilities:

- **`--my`** — Filter to current authenticated user's records
- **Name-based lookups** — Use `--user "Alice"`, `--project "Website"` etc. instead of IDs
- **Date shortcuts** — `--today`, `--yesterday`, `--this-week`, `--last-week`, `--this-month`, `--last-month`, `--this-year`
- **Custom date range** — `--date-from 2026-03-01 --date-to 2026-03-31`
- **Log notes** — `log-note` action to post internal notes on records (where supported)
- **Notify** — `notify` action to schedule activity notifications by user name (where supported)
- **JSON output** — All scripts output JSON to stdout, logs go to stderr

> **DATE FIELD RULE for tasks.py**: Date shortcuts filter `date_deadline` by default.
> To filter by **when a task was created**, always add `--date-field created`.
> To filter by **when a task was last updated**, use `--date-field updated`.

## Natural Language → Command Mapping

Use this table to translate common user requests into the correct command:

| User says... | Command |
|---|---|
| "my tasks" | `tasks.py list --my` |
| "my tasks this week" / "tasks with deadline this week" | `tasks.py list --my --this-week` |
| "tasks I created this week" / "tasks created this week" | `tasks.py list --my --this-week --date-field created` |
| "tasks created today" | `tasks.py list --my --today --date-field created` |
| "tasks created this month" | `tasks.py list --my --this-month --date-field created` |
| "tasks updated today" / "recently modified tasks" | `tasks.py list --my --today --date-field updated` |
| "my timesheets this week" | `timesheets.py list --my --this-week` |
| "log 2 hours on project X" | `timesheets.py log --project "X" --hours 2 --description "..."` |
| "my timesheet summary this month" | `timesheets.py summary --my --this-month` |
| "my calendar today" / "my meetings today" | `calendar_events.py list --my --today` |
| "my tickets" / "tickets assigned to me" | `helpdesk.py list --my` |
| "my leave requests this year" | `time_off.py list --my --this-year` |

## Quick Decision: Which Script to Use

| User wants to... | Script | Example |
|-------------------|--------|---------|
| List/view/create/update **tasks** | `tasks.py` | `python3 $SKILL_SCRIPTS/tasks.py list --my --this-week` |
| List/view/create/update **projects** | `projects.py` | `python3 $SKILL_SCRIPTS/projects.py list --my` |
| Log/view/update **timesheets** | `timesheets.py` | `python3 $SKILL_SCRIPTS/timesheets.py log --project "Website" --hours 2 --description "review"` |
| List/view/create/update **calendar events** | `calendar_events.py` | `python3 $SKILL_SCRIPTS/calendar_events.py list --my --today` |
| List/view/create/update **helpdesk tickets** | `helpdesk.py` | `python3 $SKILL_SCRIPTS/helpdesk.py list --my --this-week` |
| List/view/create/update **time off requests** | `time_off.py` | `python3 $SKILL_SCRIPTS/time_off.py list --my --this-year` |
| List/view/create/update **knowledge articles** | `knowledge.py` | `python3 $SKILL_SCRIPTS/knowledge.py list --my --published` |
| List/view/create/update **documents** | `documents.py` | `python3 $SKILL_SCRIPTS/documents.py list --folder "HR"` |
| Access **any user-defined / custom model** | `custom_app.py` | `python3 $SKILL_SCRIPTS/custom_app.py list crm.lead --my --this-month` |
| **Test connection** to Odoo | `odoo_core.py` | `python3 $SKILL_SCRIPTS/odoo_core.py test-connection` |

---

## Module: Tasks (`tasks.py`)

Manages `project.task`. Actions: `list`, `get`, `create`, `update`, `log-note`, `notify`, `stages`.

**Date filter field** — use `--date-field` to choose which date to filter on:
- `deadline` *(default)* — filters by `date_deadline`
- `created` — filters by `create_date` (when the task was created)
- `updated` — filters by `write_date` (when the task was last modified)

```bash
# My tasks
python3 $SKILL_SCRIPTS/tasks.py list --my

# My tasks CREATED this week  ← "created" requires --date-field created
python3 $SKILL_SCRIPTS/tasks.py list --my --this-week --date-field created

# My tasks CREATED today
python3 $SKILL_SCRIPTS/tasks.py list --my --today --date-field created

# My tasks CREATED this month
python3 $SKILL_SCRIPTS/tasks.py list --my --this-month --date-field created

# Tasks with a DEADLINE this week (default behavior, --date-field deadline is implicit)
python3 $SKILL_SCRIPTS/tasks.py list --my --this-week

# Tasks assigned to a specific user (by name) created this week
python3 $SKILL_SCRIPTS/tasks.py list --user "Alice" --this-week --date-field created

# Tasks in a project (by name)
python3 $SKILL_SCRIPTS/tasks.py list --project "Website Redesign"

# Search tasks by keyword
python3 $SKILL_SCRIPTS/tasks.py list --search "login bug"

# Overdue tasks
python3 $SKILL_SCRIPTS/tasks.py list --overdue

# Tasks in a stage (by name)
python3 $SKILL_SCRIPTS/tasks.py list --stage "In Progress"

# Tasks by tag
python3 $SKILL_SCRIPTS/tasks.py list --tag "urgent"

# Get task detail
python3 $SKILL_SCRIPTS/tasks.py get 42

# Create a task (project and assignee by name)
python3 $SKILL_SCRIPTS/tasks.py create --name "Fix login bug" --project "Website" --assign "Alice" --deadline 2026-04-01

# Update task stage (by name) and assignee (by name)
python3 $SKILL_SCRIPTS/tasks.py update 42 --stage "Done" --assign "Bob"

# Log an internal note on a task
python3 $SKILL_SCRIPTS/tasks.py log-note 42 --body "Waiting for client feedback"

# Notify a user via activity
python3 $SKILL_SCRIPTS/tasks.py notify 42 --user "Alice" --summary "Please review this task"

# List availa