pictureFrame/.claude/skills/oro-backend-dev/reference-integrations.md

Integration Reference

Patterns for building integrations in OroCommerce.

Oro IntegrationBundle Pattern

For managed integrations visible in System > Integrations:

1. Transport -- implements TransportInterface, handles connectivity
2. Connector -- implements ConnectorInterface, defines sync logic per entity
3. Channel Type -- defines the integration type shown in UI

Transport

class MyTransport implements TransportInterface
{
    public function init(Transport $transportEntity): void { }
    public function getLabel(): string { return 'My Integration'; }
    public function getSettingsFormType(): string { return MyTransportSettingsType::class; }
    public function getSettingsEntityFQCN(): string { return MyTransportSettings::class; }
}

Tag: { name: oro_integration.transport, type: my_integration, channel_type: my_channel }

Connector

class MyConnector implements ConnectorInterface
{
    public function getLabel(): string { return 'My Connector'; }
    public function getType(): string { return 'my_entity'; }
    public function getImportEntityFQCN(): string { return MyEntity::class; }
    public function getImportJobName(): string { return 'my_import_job'; }
}

Tag: { name: oro_integration.connector, type: my_entity, channel_type: my_channel }

API-Based Integration (Middleware)

For external API integrations not using the IntegrationBundle:

1. Create an HTTP client service wrapping Symfony HttpClient
2. Store credentials in system configuration (see system-config pattern)
3. Use MQ processors for async data sync
4. Implement retry/backoff for resilience
5. Use notification alerts for failure reporting

Import/Export Services

services:
    acme.importexport.data_converter:
        parent: oro_importexport.data_converter.configurable

    acme.importexport.processor.export:
        parent: oro_importexport.processor.export_abstract
        calls:
            - [setDataConverter, ['@acme.importexport.data_converter']]
        tags:
            - { name: oro_importexport.processor, type: export,
                entity: 'Acme\Bundle\ExampleBundle\Entity\Example',
                alias: acme_example }

    acme.importexport.processor.import:
        parent: oro_importexport.processor.import_abstract
        calls:
            - [setDataConverter, ['@acme.importexport.data_converter']]
        tags:
            - { name: oro_importexport.processor, type: import,
                entity: 'Acme\Bundle\ExampleBundle\Entity\Example',
                alias: acme_example }

Notification Alerts

Use Oro\Bundle\NotificationAlertBundle to surface integration failures:

$this->notificationAlertManager->addNotificationAlert(
    NotificationAlert::createForIntegration($integration, 'Sync failed: ...')
);