Integrations & Drivers

Concept

An Integration represents a destination (e.g., Magento 2). A Driver implements the actual delivery logic. Integrations can be enabled/disabled, filtered by entity type, and configured with per-field priorities and retries.

Discovery

• `App\Services\DriverDiscovery` collects tagged `integration` services from the container.
• Modules should bind the Driver in their ServiceProvider and tag it:

- `$this->app->bind(Magento2Driver::class);`

- `$this->app->tag([Magento2Driver::class], ['integration', 'magento2']);`

Schema & Validation

• Drivers expose `getConfigurationSchema()` with Laravel validation rules. During `integration:register` we validate the given configuration.
• Store driver-specific mapping data under the Integration’s `field_mapping` key (e.g., Magento 2 `field_mapping.websites`). Avoid adding arbitrary top-level keys that don’t exist as DB columns.

Magento 2 Driver

• Location: `Modules/Magento2/app/Magento2Driver.php`
• Handles `created`/`updated` product mutations using a rules-based payload builder.
• Configuration schema:

- `base_url` (url)

- `consumer_key`, `consumer_secret`, `access_token`, `access_secret`

• Client builder: `Modules/Magento2/app/Services/Magento2ClientBuilder.php`

- `buildWithBearerToken(base_url, access_token)`

- Endpoint builder `rest/V1/{resource}`

- Magento REST docs: https://developer.adobe.com/commerce/webapi/rest/

Entity Filters

• Integration-level filters control which entity types this driver processes.
• Configure under `config/integrations.php`:

- `entity_filters = ['product', 'attribute', 'family', 'category']`

- Only listed entities will generate MutationJobs for the Magento 2 driver.

Mapping Service

• `EntityMappingServiceInterface` implemented by `DatabaseEntityMappingService` keeps track of external IDs per integration.
• Drivers should:

- Lookup mapping by (entity_type, entity_uuid, integration_uuid).

- Update/create mappings when external entities are created.

- IEC contracts: see `docs/iec/10-integration-contracts.md`

Priorities

• Integrations define a `priority_map` mapping changed field codes to numeric priorities (lower = higher priority). A wildcard `*` provides a default.
• Example (see `config/integrations.php`):

- `selling_price_scope: 10`, `automated_price: 10` (price updates are immediate)

- `properties: 20`

- `enabled: 30`

- `*: 100`

• IEC resolves queue names via `QueueResolver` to the priority queues:

- `integrations-immediate` (<= 50)

- `integrations-normal` (<= 200)

- `integrations-low` (<= 250)

- Fallback → `integrations-low`