Mapping content classes to external data #

This page is for integration developers and content architects who decide how records of a PIM, an ERP, a DAM or an event system become content in Exponential. The mapping is the contract of the integration: once data flows, changing it is a migration. Settle it in writing before the first import.

Contents #

1. Design the class for the integration
2. Text formats of the common datatypes
3. Images and files from a DAM
4. Relations between imported records
5. Languages and locations
6. A mapping table

Design the class for the integration #

Ship the class with your extension as a package, so every environment has the same identifiers (Packages). The content model for a whole site is a workshop topic (Content modeling workshops).

Text formats of the common datatypes #

eZContentFunctions::createAndPublishObject() and updateAndPublishObject() take every value as a string and hand it to the datatype's fromString(); toString() gives the same format back. From the kernel's datatypes (kernel/classes/datatypes/<type>/<type>type.php):

When in doubt, read the datatype's fromString(): it is short, and several were hardened in 6.0.15 to refuse invalid values instead of storing them (The eZDataType API).

Rich text. ezxmltext stores its own XML (section, paragraph, header, link ...), not HTML. Convert the source's HTML to that XML in your import, keep the set of allowed elements small, and escape text. The nxc_powercontent extension, used by the REST create route, accepts HTML for ezxmltext attributes (nxc_powercontent). Extension datatypes such as eztags have their own formats; read their fromString().

Images and files from a DAM #

1. Download the file into a directory below var/ of the installation (for example var/import/), never into the web root of another site.
2. Give the path relative to the installation in the attribute value, or pass storage_dir once and file names per record (createAndPublishObject() prefixes storage_dir for ezimage, ezbinaryfile and ezmedia).
3. After the import, remove the downloaded copies; the datatype has stored its own.
4. Compare a checksum of the source file before downloading again, so an unchanged image is not re-imported.

For large media libraries, ask whether the site needs the files at all, or only a link to the DAM's delivery URL (an ezurl or text attribute), which avoids copying.

Relations between imported records #

Relations store object ids, which you only know after both objects exist:

1. Import all records of the related class first (categories before products).
2. Resolve each source reference through its remote id: eZContentObject::fetchByRemoteID( 'pim-category-shoes' ), then use its id in the ezobjectrelationlist value.
3. If a reference cannot be resolved yet, import without it and set it in a second pass.

Languages and locations #

• Languages: one object per record, one translation per language. Pass language (for example ger-DE) to createAndPublishObject() for the first language and to updateAndPublishObject() for each further one. The language must exist in the installation (Content languages).
• Locations: parent_node_id gives the main location. A record that belongs in several places gets more locations (expobject and the content jobs offer adding locations; in PHP the node operations). Decide whether a category change at the source moves the object (eZContentObjectTreeNodeOperations::move()) or adds a location.
• Sections and states: section_id on create; object states for workflow status such as "withdrawn".

A mapping table #

Copy this into the interface specification, one table per class:

Class: product (identifier)          Source: ERP article export, file articles.csv
remote_id scheme: erp-product-<ARTNR>
Parent: node <id> "Products" (main location); category as an extra location

Source field   | Attribute     | Datatype   | Transformation              | Owner  | Required
---------------+---------------+------------+-----------------------------+--------+---------
ARTNR          | sku           | ezstring   | as is                       | ERP    | yes
NAME_EN        | name          | ezstring   | trim                        | ERP    | yes
NAME_DE        | name (ger-DE) | ezstring   | translation                 | ERP    | no
PRICE          | price         | ezprice    | "<PRICE>|1|1"               | ERP    | yes
STOCK          | stock         | ezinteger  | as is                       | ERP    | no
IMAGE_URL      | image         | ezimage    | download to var/import/     | DAM    | no
-              | intro         | ezxmltext  | not imported                | editor | no

Related pages #

• Idempotent imports keyed by remote_id
• Writing an import script
• Content classes for builders
• Interface specification template
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.