motia-iii/MIGRATION_STATUS.md

Motia Migration Status

Overview

Migrating from old-motia v0.17 (Node.js + Python hybrid) to Motia III v1.0-RC (pure Python).

Old System Analysis

Location

• Old system: /opt/motia-iii/old-motia/
• Old project dir: /opt/motia-iii/old-motia/bitbylaw/

Steps Found in Old System

Root Steps (/opt/motia-iii/old-motia/steps/)

1. crm-bbl-vmh-reset-nextcall_step.py
2. event_step.py
3. hello_step.py

BitByLaw Steps (/opt/motia-iii/old-motia/bitbylaw/steps/)

Advoware Calendar Sync (advoware_cal_sync/):

• calendar_sync_all_step.py
• calendar_sync_api_step.py
• calendar_sync_cron_step.py
• calendar_sync_event_step.py
• audit_calendar_sync.py
• calendar_sync_utils.py (utility module)

Advoware Proxy (advoware_proxy/):

• advoware_api_proxy_get_step.py
• advoware_api_proxy_post_step.py
• advoware_api_proxy_put_step.py
• advoware_api_proxy_delete_step.py

VMH Integration (vmh/):

• beteiligte_sync_cron_step.py
• beteiligte_sync_event_step.py
• bankverbindungen_sync_event_step.py
• webhook/bankverbindungen_create_api_step.py
• webhook/bankverbindungen_update_api_step.py
• webhook/bankverbindungen_delete_api_step.py
• webhook/beteiligte_create_api_step.py
• webhook/beteiligte_update_api_step.py
• webhook/beteiligte_delete_api_step.py

Supporting Services/Modules

From /opt/motia-iii/old-motia/bitbylaw/:

• services/advoware.py - Advoware API wrapper
• config.py - Configuration module
• Dependencies: PostgreSQL, Redis, Google Calendar API

Migration Changes Required

Key Structural Changes

1. Config Format

# OLD
config = {
    "type": "api",  # or "event", "cron"
    "name": "StepName",
    "path": "/endpoint",
    "method": "GET",
    "cron": "0 5 * * *",
    "subscribes": ["topic"],
    "emits": ["other-topic"]
}

# NEW
from motia import http, queue, cron

config = {
    "name": "StepName",
    "flows": ["flow-name"],
    "triggers": [
        http("GET", "/endpoint")
        # or queue("topic", input=schema)
        # or cron("0 0 5 * * *")  # 6-field!
    ],
    "enqueues": ["other-topic"]
}

2. Handler Signature

# OLD - API
async def handler(req, context):
    body = req.get('body', {})
    await context.emit({"topic": "x", "data": {...}})
    return {"status": 200, "body": {...}}

# NEW - API
from motia import ApiRequest, ApiResponse, FlowContext

async def handler(request: ApiRequest, ctx: FlowContext) -> ApiResponse:
    body = request.body
    await ctx.enqueue({"topic": "x", "data": {...}})
    return ApiResponse(status=200, body={...})

# OLD - Event/Queue
async def handler(data, context):
    context.logger.info(data['field'])

# NEW - Queue
async def handler(input_data: dict, ctx: FlowContext):
    ctx.logger.info(input_data['field'])

# OLD - Cron
async def handler(context):
    context.logger.info("Running")

# NEW - Cron
async def handler(input_data: dict, ctx: FlowContext):
    ctx.logger.info("Running")

3. Method Changes

• context.emit() → ctx.enqueue()
• req.get('body') → request.body
• req.get('queryParams') → request.query_params
• req.get('pathParams') → request.path_params
• req.get('headers') → request.headers
• Return dict → ApiResponse object

4. Cron Format

• OLD: 5-field "0 5 * * *" (minute hour day month weekday)
• NEW: 6-field "0 0 5 * * *" (second minute hour day month weekday)

Migration Strategy

Phase 1: Simple Steps (Priority)

Start with simple API proxy steps as they're straightforward:

1. ✅ Example ticketing steps (already in new system)
2. ⏳ Advoware proxy steps (GET, POST, PUT, DELETE)
3. ⏳ Simple webhook handlers

Phase 2: Complex Integration Steps

Steps with external dependencies: 4. ⏳ VMH sync steps (beteiligte, bankverbindungen) 5. ⏳ Calendar sync steps (most complex - Google Calendar + Redis + PostgreSQL)

Phase 3: Supporting Infrastructure

• Migrate services/ modules (advoware.py wrapper)
• Migrate config.py to use environment variables properly
• Update dependencies in pyproject.toml

Dependencies to Review

From old requirements.txt and code analysis:

• asyncpg - PostgreSQL async driver
• redis - Redis client
• google-api-python-client - Google Calendar API
• google-auth - Google OAuth2
• backoff - Retry/backoff decorator
• pytz - Timezone handling
• pydantic - Already in new system
• requests / aiohttp - HTTP clients for Advoware API

Status

Completed

• ✅ Analysis of old system structure
• ✅ MIGRATION_GUIDE.md reviewed
• ✅ Migration patterns documented
• ✅ New system has example ticketing steps
• ✅ Phase 1: Advoware Proxy Steps migrated (GET, POST, PUT, DELETE)
• ✅ Advoware API service module migrated (services/advoware.py)
• ✅ Phase 2: VMH Integration - Webhook Steps migrated (6 endpoints)
• ✅ EspoCRM API service module migrated (services/espocrm.py)
• ✅ All endpoints registered and running:
  • Advoware Proxy:
    • GET /advoware/proxy
    • POST /advoware/proxy
    • PUT /advoware/proxy
    • DELETE /advoware/proxy
  • VMH Webhooks - Beteiligte:
    • POST /vmh/webhook/beteiligte/create
    • POST /vmh/webhook/beteiligte/update
    • POST /vmh/webhook/beteiligte/delete
  • VMH Webhooks - Bankverbindungen:
    • POST /vmh/webhook/bankverbindungen/create
    • POST /vmh/webhook/bankverbindungen/update
    • POST /vmh/webhook/bankverbindungen/delete

Current Status: Phase 2 Complete ✅

VMH Webhook endpoints are now receiving EspoCRM webhook events and emitting queue events for processing. The webhook steps handle batch and single entity notifications and provide deduplication via the event handling system.

Note: The complex sync handlers (beteiligte_sync_event_step.py, bankverbindungen_sync_event_step.py) are NOT yet migrated as they require additional utility modules:

• services/beteiligte_sync_utils.py (663 lines - distributed locking, retry logic, notifications)
• services/bankverbindungen_mapper.py (data mapping between EspoCRM and Advoware)
• services/espocrm_mapper.py (mapping utilities)
• services/notification_utils.py (in-app notifications)

These sync handlers process the queue events emitted by the webhook steps and perform the actual synchronization with Advoware. They will be migrated in Phase 3.

Notes

• Old system was Node.js + Python hybrid (Python steps as child processes)
• New system is pure Python (standalone SDK)
• No need for Node.js/npm anymore
• iii engine handles all infrastructure (queues, state, HTTP, cron)
• Console replaced Workbench