Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,110 of 9,110 pages
About the help in other languages
All help pages

Building an integration as an extension

Packaging an integration as an Exponential extension - the directory layout of a typical integration, settings with secrets kept in settings/override, classes, commands, cronjob parts, workflow events, schema, tests…

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/help/integrators/building-an-integration-as-an-extension.md

On this page

Building an integration as an extension

This page is for integration developers. Everything an integration needs fits into one extension: settings, classes, commands, cronjob parts, workflow events, login handlers, REST controllers, server functions, tables and tests. An extension is versioned in its own Git repository, installed with Composer, activated with one line, and can be released and contributed back. The complete guide to extensions is Extension development: the book.

Contents

  1. The layout of an integration extension
  2. Settings and secrets
  3. Tables of your own
  4. Metadata and Composer
  5. Activating and deploying
  6. One extension or several

The layout of an integration extension

extension/myintegration/
    composer.json                       package name, requirements, license
    ezinfo.php                          name, version, license, website (the about page)
    extension.xml                       the same metadata in XML
    README.md, CHANGELOG.md, LICENSE
    settings/
        myintegration.ini               your settings with safe defaults, no secrets
        site.ini.append.php             [Event] Listeners[], [UserSettings] ExtensionDirectory[] ...
        cronjob.ini.append.php          [CronjobSettings] ExtensionDirectories[], [CronjobPart-...]
        workflow.ini.append.php         [EventSettings] ExtensionDirectories[], AvailableEventTypes[]
        ezjscore.ini.append.php         [ezjscServer_...] for server functions or an expservices domain
        rest.ini.append.php             [ApiKeySettings] RouteScopes[] for REST routes of your own
    classes/                            the work: client of the other system, mapping, importer, sender
        runnable/cronjobs/              cronjob parts as classes
    bin/php/                            commands (ext:myintegration:<name>), including the monitoring check
    cronjobs/                           one-line files that call the cronjob classes
    eventtypes/event/<type>/            workflow event types
    login_handler/                      login handlers, if any
    share/db_schema.dba, sql/<engine>/  tables of your own
    tests/                              unit tests without a database, test fixtures
    doc/                                the integration's documentation and runbook

Only the parts the integration uses are needed. Names follow the kernel's rules: classes myIntegration... in files of the same name in lower case (Autoloads and class naming). New names use your own prefix, never ez.

Settings and secrets

KindWhere
Defaults that are safe to publish (endpoint of the test system, batch sizes, parent node identifiers)extension/myintegration/settings/myintegration.ini
Values per installation (production endpoint, node ids)settings/override/myintegration.ini.append.php or a siteaccess's settings
Secrets (API keys, passwords, signing secrets)settings/override/myintegration.ini.append.php, outside Git; or environment variables

Read them with eZINI::instance( 'myintegration.ini' )->variable( 'Block', 'Name' ). Document every setting in the shipped INI file with a comment line above it (Settings in an extension).

Tables of your own

Outbox, inbox, watermarks and mappings live in tables of your extension, defined once in share/db_schema.dba (and sql/<engine>/schema.sql where needed), with a small install command that creates them idempotently (Database schema and dba files). Access them through eZPersistentObject classes or eZDB with cast ids and escaped strings.

Metadata and Composer

  • ezinfo.php and extension.xml state the name, the version (the same in both, raised with every release), the license and the website; the about page reads them (ezinfo.php, extension.xml).
  • composer.json names the package, its type, the license and its requirements on the kernel and other extensions (composer.json for extensions).
  • A customer-specific integration lives in a private repository; a reusable connector can be published (Contributing integrations back).

Activating and deploying

# settings/override/site.ini.append.php
[ExtensionSettings]
ActiveExtensions[]=myintegration
php bin/php/ezpgenerateautoloads.php -e
php bin/php/console exp:velocity deploy --allow-root-user     # or: clear the INI cache, reload PHP-FPM, restart Velocity

Activate integration extensions globally (ActiveExtensions) when cronjobs and commands need them on every siteaccess; an access extension (ActiveAccessExtensions) is seen only by the siteaccesses that list it, and every cron line must then name such a siteaccess with -s (Activating an extension).

One extension or several

One extensionSeveral
One customer, one other system, one teamA reusable connector (for example "a CRM client") used by several customer extensions
Simple release and handoverThe generic part is published; the customer part stays private

Splitting the generic connector from the customer mapping is what makes contributing back possible.

Become an Exponential Partner

Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x