Quickstart

Create the project

Clone the quickstart repository:

git clone https://github.com/productsupcom/connector-quickstart.git
cd connector-quickstart

Install dependencies:

composer install

Your project structure will look like this:

connector-quickstart/
├── bin/console
├── config/
│   ├── bundles.php
│   ├── packages/
│   │   └── framework.yaml
│   └── services.yaml
├── src/
│   ├── DataSource/
│   │   ├── Command/
│   │   │   └── RunImportCommand.php    # CLI entry point for datasource
│   │   └── Service/
│   │       └── ImportService.php       # datasource business logic
│   ├── Export/
│   │   ├── Command/
│   │   │   └── RunExportCommand.php    # CLI entry point for export
│   │   └── Service/
│   │       └── ExportService.php       # export business logic
│   ├── ContainerApi/
│   │   ├── ContainerApiClientFactory.php
│   │   └── ContainerApiFactory.php
│   └── Kernel.php
├── .env
├── composer.json
└── Dockerfile

This is a standard Symfony console application. The DataSource/ and Export/ folders each contain a CLI command and a service for their respective connector type. ContainerApi/ wires up the Container API client shared by both.

Write the connector

The connector has two key files and a DI binding.

The CLI command — the entry point that CDE executes. It delegates all work to the service:

<?php

namespace App\DataSource\Command;

use App\DataSource\Service\ImportService;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

#[AsCommand(name: 'connector:run:import')]
class RunImportCommand extends Command
{
    public function __construct(
        private readonly ImportService $importService,
    ) {
        parent::__construct();
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        try {
            $this->importService->run();
        } catch (\Throwable) {
            return Command::FAILURE;
        }

        return Command::SUCCESS;
    }
}

The service — fetches products and writes them to the platform. Replace the hardcoded array with your real data source (an API call, a file read, a database query, etc.):

<?php

namespace App\DataSource\Service;

use Productsup\CDE\ContainerApi\ContainerApiInterface;

readonly class ImportService
{
    public function __construct(
        private ContainerApiInterface $containerApi,
    ) {}

    public function run(): void
    {
        $this->containerApi->info('Starting product import.');

        // Replace this with your real data source — an API call, file read, database query, etc.
        $products = [
            ['id' => '1', 'name' => 'Product A', 'price' => '9.99'],
            ['id' => '2', 'name' => 'Product B', 'price' => '19.99'],
            ['id' => '3', 'name' => 'Product C', 'price' => '29.99'],
        ];

        $this->containerApi->appendManyToOutputFile($products);

        $this->containerApi->info('Imported ' . \count($products) . ' products.');

        // Notify the end-user in the Productsup notification panel
        $this->containerApi->sendNotification('success', 'Import completed: ' . \count($products) . ' products imported.');
    }
}

The repository also includes an export connector example under src/Export/ — see the demo connectors page for both.

The DI binding — tells Symfony to inject the Container API client wherever ContainerApiInterface is type-hinted:

services:
    _defaults:
        autowire: true
        autoconfigure: true
        bind:
            Productsup\CDE\ContainerApi\ContainerApiInterface $containerApi: '@container.api'

    App\:
        resource: '../src/'

Create a connector in the Dev Portal

Open the Dev Portal and navigate to the Connectors page.

Click Add connector to open the creation dialog and fill in the fields:

Click Add connector. The connector is created in created state and you'll be taken to the connector setup wizard.

Configure VCS

In the setup wizard, go to the Version Control configuration step. Point it to your connector repository:

Click Save, then Test connection to validate the repository is reachable.

Configure application

In the Application configuration step, tell CDE how to run your connector:

The command and arguments together form what CDE executes inside the Docker container. The health check runs the same binary with --help first to verify the container started correctly.

Build the connector

The quickstart repo includes a ready-to-use Dockerfile:

FROM php:8.3-cli

RUN apt-get update && apt-get install -y unzip && rm -rf /var/lib/apt/lists/*

COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

WORKDIR /app

COPY bin/ ./bin
COPY config/ ./config
COPY src/ ./src
COPY .env composer.json composer.lock ./

RUN composer install --no-dev --no-interaction

CMD ["php", "bin/console"]

In the Dev Portal, navigate to the Release configuration page and click Build:

This:

1. Connects to your Git repository
2. Pulls the code from the configured branch
3. Builds a Docker image using your Dockerfile
4. Runs the health check
5. Pushes the image to the registry

Once the build completes, the connector state moves to built and the next steps become available:

Deploy to dev

The Release configuration page walks you through deploying your connector step by step:

Click Start syncing next to Sync connector with runtime. Once it completes, the Sync connector with dev section expands:

Click Create a new site. This creates a test project and site on the Productsup platform for your connector, syncs the connector to the development environment, and assigns it to the site. The three sub-steps run automatically:

1. Creating a site or ensuring it exists — creates a dev project and site on the platform
2. Synchronizing your connector to development environment — registers the connector so the platform can execute it
3. Assigning the latest version of your connector to a Site — links your connector to the dev site

Once all three complete, the connector is synced with dev:

Assigning the connector to the dev site means it's now available as a data source on that site — you can trigger site runs that execute your connector. Click Open dev site to go to the site on the Productsup platform.

Test it

With the connector synchronized to dev, you can trigger a test run. Navigate to the Runs section in the Dev Portal to:

• See the run status and duration
• View application logs (the messages sent via $this->containerApi->info())
• Check stdout/stderr for debugging
• Verify that product data was written successfully

If everything works, you should see a log message confirming the three products were imported.

Deploy to production

Once you're happy with how the connector works on dev, go back to the Release configuration page and click Start syncing next to Sync connector with prod. This creates a production version of your connector based on its current configuration.

After the sync completes, the Enable access section becomes available:

From here you have two options:

• Change access — makes the connector available to specific accounts, projects, or sites. Use this when the connector is intended for specific customers or internal use.
• Release — makes the connector available globally on the platform for all users.