odoo-connector-module-creator

What this skill does

# Odoo Connector Module Creator and Enhancer

## Description

Creates and enhances Odoo 16.0 connector modules that integrate with external systems (e-commerce, logistics, accounting, CRM) using the `generic_connector` framework. This skill handles:

- **New Connector Creation**: Build complete integration modules for Shopify, WooCommerce, Amazon, or any external API
- **Connector Enhancement**: Add features like inventory sync, webhook support, or new entity types to existing connectors
- **Troubleshooting**: Debug sync issues, API errors, authentication problems, and queue job failures
- **Architecture Implementation**: Properly implement binding models, adapters, mappers, and importers/exporters

The skill leverages production-tested patterns from reference connectors (zid_connector_v2, beatroute_connector) and provides automated scripts for generating boilerplate code.

## Overview

Create production-ready Odoo 16.0 connector modules that integrate with external systems using the `generic_connector` framework. Handle creation of new connectors, enhancement of existing connectors, troubleshooting sync issues, and debugging integration problems.

## When to Use This Skill

Use this skill when the user requests:
- **Creating new connectors**: "Create a Shopify connector", "Build WooCommerce integration", "Connect to Amazon API"
- **Enhancing connectors**: "Add inventory sync to zid_connector", "Implement webhooks for orders", "Add product export"
- **Adding entities**: "Add customer sync to the connector", "Import invoices from the external system"
- **Troubleshooting**: "Orders aren't importing", "Webhook signature verification failing", "Fix sync errors"
- **Debugging**: "Why is the API returning 401?", "Products are duplicating", "Queue jobs not running"

## Key Concepts

### Generic Connector Framework

All connector modules extend `generic_connector`, which provides:

1. **Backend Model** - Configuration and orchestration
2. **Binding Models** - Link Odoo records to external entities
3. **Adapter Component** - HTTP client for API communication
4. **Mapper Components** - Data transformation (import/export)
5. **Importer/Exporter Components** - Sync logic
6. **Webhook System** - Real-time event processing
7. **Queue Job Integration** - Async operations

### Reference Code

Three production connectors serve as references:
- `/Users/jamshid/PycharmProjects/Siafa/odoo16e_simc/addons-connector/generic_connector` - Base framework
- `/Users/jamshid/PycharmProjects/Siafa/odoo16e_simc/addons-connector/zid_connector_v2` - E-commerce example
- `/Users/jamshid/PycharmProjects/Siafa/odoo16e_simc/addons-connector/beatroute_connector` - Logistics example

## Workflow

### Creating a New Connector

When the user requests a new connector:

**Step 1: Gather Requirements**
- External system name (e.g., "Shopify", "WooCommerce")
- Connector type: ecommerce, logistics, accounting, crm
- Entities to sync: products, orders, customers, inventory
- Sync direction: import, export, or bidirectional
- Authentication method: API key, OAuth, basic auth
- API documentation URL (if available)

**Step 2: Initialize Module**
```bash
# Use the init_connector.py script
python3 scripts/init_connector.py <connector_name> --path <output_path> --type <connector_type>

# Example:
python3 scripts/init_connector.py shopify --path ~/odoo/addons --type ecommerce
```

**Step 3: Review Generated Structure**

The script creates:
```
shopify_connector/
├── __manifest__.py              # Module metadata
├── __init__.py                  # Python imports
├── models/
│   ├── backend.py              # Backend configuration
│   ├── adapter.py              # API client
│   ├── product_binding.py      # Product sync
│   └── __init__.py
├── views/
│   ├── backend_views.xml       # Backend UI
│   ├── binding_views.xml       # Binding UI
│   └── menu_views.xml          # Menu structure
├── security/
│   ├── security.xml            # Access groups
│   └── ir.model.access.csv     # Access rules
├── wizards/
│   ├── sync_wizard.py          # Manual sync wizard
│   └── __init__.py
├── data/
│   ├── ir_cron_data.xml        # Scheduled jobs
│   └── queue_job_function_data.xml
└── README.md
```

**Step 4: Customize Backend Model**

Edit `models/backend.py`:

1. **Update API configuration fields** to match the external system:
   ```python
   # Example for Shopify
   shop_url = fields.Char(string='Shop URL', required=True)
   api_version = fields.Selection([
       ('2024-01', '2024-01'),
       ('2024-04', '2024-04'),
   ], default='2024-04')
   ```

2. **Implement template methods**:
   ```python
   def _test_connection_implementation(self):
       """Test API connection."""
       adapter = self.get_adapter('shopify.adapter')
       return adapter.test_connection()

   def _sync_orders_implementation(self):
       """Import orders."""
       with self.work_on('shopify.sale.order') as work:
           importer = work.component(usage='batch.importer')
           return importer.run()
   ```

**Step 5: Implement Adapter**

Edit `models/adapter.py`:

1. **Configure authentication** (see `references/authentication.md` for patterns):
   ```python
   def get_api_headers(self):
       headers = super().get_api_headers()
       headers.update({
           'X-Shopify-Access-Token': self.backend_record.api_key,
           'Content-Type': 'application/json',
       })
       return headers
   ```

2. **Add CRUD methods** for each entity type:
   ```python
   def get_products(self, filters=None):
       """Fetch products from Shopify."""
       return self.get('/admin/api/2024-01/products.json', params=filters)

   def create_order(self, data):
       """Create order in Shopify."""
       return self.post('/admin/api/2024-01/orders.json', data={'order': data})
   ```

3. **Handle pagination** (see `references/api_integration.md`):
   ```python
   def get_all_products(self):
       """Fetch all products with pagination."""
       # Implement based on API pagination style
   ```

**Step 6: Create Mapper Components**

Create `components/mapper.py`:

```python
from odoo.addons.generic_connector.components.mapper import GenericImportMapper

class ProductImportMapper(GenericImportMapper):
    _name = 'shopify.product.import.mapper'
    _inherit = 'generic.import.mapper'
    _apply_on = 'shopify.product.template'

    direct = [
        ('title', 'name'),
        ('vendor', 'manufacturer'),
    ]

    @mapping
    def backend_id(self, record):
        return {'backend_id': self.backend_record.id}

    @mapping
    def price(self, record):
        variants = record.get('variants', [])
        if variants:
            return {'list_price': float(variants[0].get('price', 0))}
        return {}
```

**Step 7: Implement Importer Components**

Create `components/importer.py`:

```python
from odoo.addons.generic_connector.components.importer import GenericImporter

class ProductImporter(GenericImporter):
    _name = 'shopify.product.importer'
    _inherit = 'generic.importer'
    _apply_on = 'shopify.product.template'

    def _import_record(self, external_id, force=False):
        # Fetch from external system
        adapter = self.component(usage='backend.adapter')
        external_data = adapter.get_product(external_id)

        # Transform data
        mapper = self.component(usage='import.mapper')
        mapped_data = mapper.map_record(external_data).values()

        # Create or update binding
        binding = self._get_binding()
        if binding:
            binding.write(mapped_data)
        else:
            binding = self.model.create(mapped_data)

        return binding
```

**Step 8: Register Components**

Create `components/__init__.py`:
```python
from . import adapter
from . import mapper
from . import importer
from . import exporter
```

Update main `__init__.py`:
```python
from . import models
from . import wizards
from . import components
```

**Step 9: Test the Connector**

```bash
# Install module
odoo-bin -c