Export FreeMarker Reference

prodexa evaluates text files, XML, HTML, and CSV export templates using the robust Apache FreeMarker engine (v2.3.23). This page details the context data models, dynamic functions, adapter APIs, and backend domain objects exposed during export.

1. Context Data Model & Global Repositories

When an export job runs, the engine registers a global namespace containing the active product dataset and secondary lookup repositories:

products: A custom Iterator of the filtered product set.

[!CAUTION] Because products is backed by an efficient stream-based cursor database iterator, only a single iteration is possible. Once you loop through <#list products as product>, the iterator is consumed and cannot be traversed again.
product: Represents the current single Product context (when evaluating templates on a per-product basis).
addresses: Accesses the global company Address Repository.
attributes: The Attribute model lookup repository.
attributeSections: Accesses attribute groupings and sections.
classifications: Accesses classifications (e.g., eCl@ss, UNSPSC).
classificationGroups: Lookup mapping for classification nodes.
companies: Accesses global Manufacturer and Supplier profiles.
documents: Document storage metadata repository.
productRelationTypes: Product relation settings repository.
valueLists: Localized Value Lists repository.
valueMappings: Mappings to transform local system values into target platform values.
unitOfMeasures: Global Unit of Measure (UoM) configurations.
helper: Contextual business helpers (e.g., PriceBookDataItemHelper).

2. Custom Global FreeMarker Functions

The prodexa template engine implements several custom directives to simplify complex text formatting, localized terms translation, UUID generation, and unit conversions.

`convertUnit`

Converts numeric values between metric, imperial, and scientific measurement units.

Signatures:
- convertUnit(value, type, fromUnit, toUnit, [formatting], [scale]) (Full conversion)
- convertUnit(value, fromUnit, toUnit, [scale]) (Generic conversion with auto-detected unit type)
Parameters:
- value: The numeric amount (Number or numeric string) to convert.
- type: The measurement category (e.g., "Length", "Volume", "Time", "Temperature", "Mass", "Area", "Pressure", "Energy", "Power", "Angle", "Speed"). Auto-inferred if omitted.
- fromUnit: Case-insensitive source unit code (e.g., "mm", "in", "c", "f", "kg", "lb", "gal", "l").
- toUnit: Target unit code to convert into.
- scale (Optional): Rounding scale integer. Applies HALF_UP rounding. Defaults to raw precision.

Examples:

${convertUnit(100, "Length", "mm", "inch", "none", 2)}  <#-- Returns: 3.94 -->
${convertUnit(32, "f", "c", 1)}                        <#-- Returns: 0.0 -->

`escapeCsv`

Escapes a scalar string to produce a completely valid CSV cell, handling quotes, commas, and linebreaks.

Signature: escapeCsv(text)
Output: Returns double-quoted string with internal quotes doubled.

Example:

${escapeCsv('He said, "Hello"')} <#-- Returns: "He said, ""Hello""" -->

`markdown2html`

Converts structured Markdown text fields (like descriptions) into compliant HTML paragraphs and tags.

Signature: markdown2html(markdownText)

Example:

${markdown2html('**Bold Text**')} <#-- Returns: <p><strong>Bold Text</strong></p> -->

`term`

Retrieves a translation for a static text term identifier based on prodexa’s term translation repository and fallback chains.

Signature: term(termId, languageId)
Details: If termId begins with a prefix indicator like $, it is automatically stripped. Returns the raw term if languageId is omitted.
Example:
```
${term("$msg_order_success", "de-DE")}
```

`toJSON`

Converts any FreeMarker sequence, hash, list, or complex object into its formatted raw JSON string representation.

Signature: toJSON(object)
Example:
```
${toJSON(product.optionAttributes)}
```

`uuid`

Generates UUID strings.

Signature: uuid([seedText])
Details: Called with no arguments, it returns a random Type 4 UUID. If an argument is provided, it returns a deterministic name-based Type 3 UUID derived from that string’s bytes.

Example:

${uuid()}             <#-- Returns: "fbc1dca2-0621-4f40-be84-af2c15420e6c" -->
${uuid("product_1")}  <#-- Returns name-based UUID -->

3. Product-Scoped Methods (ProductAdapter)

When accessing a product instance in FreeMarker, the model is wrapped in a ProductAdapter which injects two extremely helpful instance methods:

`product.valueDescription`

Translates a dynamic attribute value to a Value List Item translation in the target language.

Signature: product.valueDescription(attributeId, languageId)
Details: Handles automatic classification type extensions and fallback rules. If multiple group-specific type extensions conflict, it returns a detailed diagnostic error string.

Example:

${product.valueDescription("Color", "de-DE")} <#-- Returns: "Schwarz" instead of raw "Black" -->

`product.reverseRelations`

Queries reverse relationships targeting this product from other items in the database.

Signature: product.reverseRelations()
Returned Object Fields: Iterates over entries containing:
- catalogId: Catalog ID of the source product pointing to this product.
- productId: Product ID of the source product.
- typeId: The identifier of the Product Relation Type.

Example:

<#list product.reverseRelations() as rel>
  Targeted by ${rel.productId} in ${rel.catalogId} (Relation Type: ${rel.typeId})
</#list>

4. Technical Domain Model Details

The following references list the Java domain classes mapped into the FreeMarker execution data models. You can query these exact bean properties directly inside your templates.

1. Product

The central entity in the prodexa PXM catalog engine, representing items presented, offered, or purchased via the catalog.

Implementation Class: com.prodexa.product.domain.Product

Field	Type	Description
`id`	`Long`	Unique database primary key (read-only).
`productId`	`String`	Identifier inside the product catalog. Together with `catalogId`, this is globally unique.
`catalogId`	`String`	Identifier of Product’s Catalog this product is listed in.
`supplierId`	`String`	Identifier of the Supplier who owns the product.
`statusId`	`String`	Identifier of product status (e.g., `800` for deleted, `400` for confirmed, etc.).
`mfgProductId`	`String`	Manufacturer article identifier.
`manufacturerId`	`String`	Identifier of the Manufacturer of the product.
`manufacturerName`	`String`	The name of the manufacturer of the product.
`extProductId`	`String`	External product ID. Useful when external products are mapped using a different set of IDs.
`productIdExtension`	`String`	Extension to `productId`. Useful in Master/Variants scenarios to store the variant’s ID suffix.
`unitOfMeasureId`	`String`	Identifier of additional UOM for BMECat CONTENT_UNIT.
`salesUnitOfMeasureId`	`String`	Identifier of UOM to be used for this product when ordered. This is also the unit the price is related to.
`keywords`	`String`	Keywords that are used for searching products, separated by whitespace.
`isMainProdLine`	`Boolean`	Defines if the product belongs to the core assortment for a particular customer.
`isPunchout`	`Boolean`	Identification of punch out product. If true, allows jumping to external catalogs instead of direct cart addition. Requires punch out configuration via script exit.
`isConfigurable`	`Boolean`	Flags a product as configurable with PSC.
`validFrom`	`Date`	Valid range from (lifecycle start timestamp).
`validTo`	`Date`	Valid range to (lifecycle expiration timestamp).
`values`	`Map<String, Object>`	Holds the dynamic properties of the product defined by Attributes (Classifications, Groups, Attributes). Entry keys represent attribute IDs; values can be Boolean, Integer, BigDecimal, String, List (multi-value), or Map (multi-language, composite).
`optionAttributes`	`Map<String, List<String>>`	Holds the list of possible option attributes for master/variant identifying attributes (e.g. `{"RAM": [16, 32]}`).
`variantAttributes`	`Map<String, List<String>>`	Holds possible variant attributes that are distinct to variant SKUs but not used to identify the specific physical product.
`variantValues`	`Map<String, Map<String, Object>>`	Holds attribute values per variant ID (e.g. `{"v1": {"RAM": 16, "HD": 512}}`).
`variants`	`List<Variant>`	Collection of variant SKUs of this product.
`productGroups`	`List<ProductGroup>`	Collection of groups assigned to this product.
`productDocuments`	`List<ProductDocument>`	Collection of documents assigned to this product.
`prices`	`List<Price>`	Collection of prices assigned to this product.
`relations`	`List<ProductRelation>`	Collection of relations between this product and other products.
`manufacturer`	`Company`	Injected via Adapter. Full company details of the Manufacturer.
`supplier`	`Company`	Injected via Adapter. Full company details of the Supplier.
`createdBy`	`String`	User who created this product.
`createdOn`	`Date`	Date when the product was created.
`changedBy`	`String`	User who last changed this product.
`changedOn`	`Date`	Date when the product was last changed.

2. Price

Defines the product’s price for a defined contract, valid quantity, currency, valid range, and price type.

Implementation Class: com.prodexa.product.domain.Price

Field	Type	Description
`id`	`Long`	Unique database primary key (read-only).
`catalogId`	`String`	Reference Catalog ID.
`productId`	`String`	Reference Product ID.
`variantId`	`String`	Variant identifier.
`contractId`	`String`	Identifier of Contract.
`statusId`	`String`	Identifier of price Status.
`currencyId`	`String`	Identifier of Currency (ISO 3-letter code).
`priceTypeId`	`String`	Identifier of Price type.
`price`	`BigDecimal`	Value of Price.
`validFromQuantity`	`BigDecimal`	Price is valid from this quantity.
`validFrom`	`Date`	Valid range starting timestamp.
`validTo`	`Date`	Valid range ending timestamp.
`priceUnit`	`Integer`	Price unit (defines scale multiplier).
`description`	`String`	Price description.
`vatPercentage`	`BigDecimal`	Vat percentage.
`isPreferred`	`Boolean`	Flag indicating if this is the preferred price.
`unitOfMeasureId`	`String`	Identifier of UnitOfMeasure for Price.
`productIdExtensionForUom`	`String`	Product ID extension for Unit of Measure.
`altExtProductId`	`String`	Alternative customer-specific product identifier.
`extProductId`	`String`	External product ID. Useful when external products are mapped to a different set of IDs.
`extClassificationId`	`String`	Identifier of customer-specific classification.
`extClassificationGroupId`	`String`	Identifier of customer-specific classification group.
`descShort`	`String`	Short description.
`descLong`	`String`	Long description.
`extGlAccountId`	`String`	Identifier of GLAccount.
`priceQuantity`	`BigDecimal`	A fraction or multiple of the order unit that indicates the quantity to which all specified prices refer. Defaults to `1`.
`quantityInterval`	`BigDecimal`	The minimum incremental amount of the product that may be purchased. Orders must be in a multiple of the lot-size (null or `1.0` indicate whole numbers).
`maxQuantity`	`BigDecimal`	The maximum quantity of the product that may be purchased. Null indicates no maximum.
`minQuantity`	`BigDecimal`	The minimum quantity of the product that may be purchased. Null or `0.0` indicates no minimum.
`leadtimeInDays`	`Integer`	The lead time, in working days, for shipment of this product.
`salesUnitOfMeasureId`	`String`	Identifier of Sales Unit of Measure for the product.
`timePeriod`	`String`	Currently used for information purposes.
`cost`	`BigDecimal`	Cost of the product (used for informational purposes).
`amount`	`BigDecimal`	Amount and unitOfMeasureId together define a quantity (informational purposes).
`discount`	`BigDecimal`	Discount percentage or value applied to products in the contracted catalog.
`statusDate`	`Date`	Last change of status field date.
`companyId`	`String`	Company reference identifier.
`isOEManufacturer`	`Boolean`	True, if this is the original manufacturer of the product.
`competitorProductId`	`String`	Competitor product identifier.
`sortInfo`	`String`	States the order in which Competitive Information is printed in the catalog.
`isActive`	`Boolean`	Indicates if the OE number is still in use by the competitor.
`createdBy`	`String`	User who created this price.
`createdOn`	`Date`	Date when the price was created.
`changedBy`	`String`	User who last modified this price.
`changedOn`	`Date`	Date when the price was last changed.

3. ProductDocument

References a binary file (such as images, catalog PDFs, manual sheets) linked to the product.

Implementation Class: com.prodexa.product.domain.ProductDocument

Field	Type	Description
`id`	`Long`	Unique database primary key (read-only).
`productId`	`String`	Reference identifier of the parent product.
`catalogId`	`String`	Reference identifier of the parent product’s catalog.
`path`	`String`	Path to the external document (e.g. image, pdf) inside the storage area.
`documentViewTypeId`	`String`	Identifier of the document view type (e.g. `"Detail"`, `"Thumbnail"`).
`caption`	`String`	Overridden document caption for the product, in the TextTable format.
`orderNo`	`Integer`	Order number for sorting list outputs.
`languageId`	`String`	Identifier of the language associated with this document.
`description`	`String`	Textual description.
`validFrom`	`Date`	Valid range starting timestamp.
`validTo`	`Date`	Valid range ending timestamp.
`statusId`	`String`	Document status code.
`variantId`	`String`	Variant identifier if the document is SKU-variant specific.
`extDocumentId`	`String`	Document ID in external storage/asset managers like AmazonS3 or Pixelboxx MAM.
`udxText1` / `2` / `3`	`String`	Base User Defined Extension (UDX) text fields.
`udxNum1` / `2` / `3`	`BigDecimal`	Base User Defined Extension (UDX) numeric fields.
`udxSortKey1` / `2` / `3`	`String`	Base User Defined Extension (UDX) sorting keys.
`createdBy`	`String`	User who uploaded/created this document reference.
`createdOn`	`Date`	Date when the document was created.
`changedBy`	`String`	User who changed this document reference last.
`changedOn`	`Date`	Date when the document reference was changed last.

4. Company

Represents manufacturer, supplier, division, partner, competitor, or customer business profiles.

Implementation Class: com.prodexa.company.domain.Company

Field	Type	Description
`id`	`Long`	Unique database primary key (read-only).
`companyId`	`String`	Unique business identifier.
`name`	`String`	Full registered company name.
`abbreviation`	`String`	Short abbreviation name.
`type`	`String`	Business classification category type.
`isSupplier`	`Boolean`	True if the business acts as a supplier.
`isCustomer`	`Boolean`	True if the business acts as a customer.
`isManufacturer`	`Boolean`	True if the business is a manufacturer.
`isPartner`	`Boolean`	True if the business is a partner.
`isCompetitor`	`Boolean`	True if the business is a competitor.
`isDivision`	`Boolean`	True if the company represents a division.
`companyGroupId`	`String`	Company group reference identifier.
`extCompanyId`	`String`	External company identifier.
`extSupplierId`	`String`	External supplier identifier.
`extCustomerId`	`String`	External customer identifier.
`extManufacturerId`	`String`	External manufacturer identifier.
`extPartnerId`	`String`	External partner identifier.
`extCompetitorId`	`String`	External competitor identifier.
`extDivisionId`	`String`	External division identifier.
`contacts`	`Set<CompanyContact>`	Set of company contacts.
`addresses`	`Set<CompanyAddress>`	Set of physical company addresses.
`logo`	`String`	Relative path to company logo image file (Manufacturer-specific).
`dunsNo`	`String`	Globally unique D-U-N-S business identification number (Customer-specific).
`extAccountCode`	`String`	External account code.
`extGlobalId`	`String`	External global ID.
`extName`	`String`	External company name.
`extShortName`	`String`	External short name.
`footerText`	`String`	Footer text for documents.
`headerText`	`String`	Header text for documents.
`information`	`String`	General business information text.
`invToleranceAbs`	`BigDecimal`	Invoice absolute tolerance amount.
`invTolerancePercent`	`BigDecimal`	Invoice percentage tolerance.
`hierarchyCode`	`String`	Hierarchy code representation.
`taxId`	`String`	General tax identification number.
`rowTaxId`	`String`	Regional tax ID.
`rowEuTaxId`	`String`	European Union tax identifier.
`rowLanguageId`	`String`	Default regional language ID.
`currencyId`	`String`	Default billing currency code (Supplier-specific).
`languageId`	`String`	Default language ID.
`methodOfPaymentId`	`String`	Default method of payment identifier.
`statusId`	`String`	Company profile status code.
`termsOfDeliveryId`	`String`	Standard terms of delivery identifier.
`termsOfPaymentId`	`String`	Standard terms of payment identifier.
`createdBy`	`String`	User who created the company profile.
`createdOn`	`Date`	Date when the profile was created.
`changedBy`	`String`	User who last changed the profile.
`changedOn`	`Date`	Date when the profile was last changed.

5. ProductGroup

Represents associations between a product and classification groups (such as standard classification nodes or automotive vehicle compatibility entries).

Implementation Class: com.prodexa.product.domain.ProductGroup

Field	Type	Description
`id`	`Long`	Unique database primary key (read-only).
`catalogId`	`String`	Reference Catalog ID.
`productId`	`String`	Reference Product ID.
`classificationId`	`String`	Identifier of the Classification (e.g. `"eCl@ss"`).
`classificationGroupId`	`String`	Identifier of Group within the Classification.
`compatibilityId`	`String`	Unique identifier of the compatibility association in scope of the Product (required for automotive cases where product is a spare part and group is a vehicle model).
`variantId`	`String`	Variant identifier if the group association is SKU-variant specific.
`orderNo`	`Integer`	Order number used for sorting associations on the UI.
`compatibilityValues`	`Map<String, Object>`	Collection of attribute values / compatibility constraints (e.g. `{"tdc_0020":"2018-08-01", ...}`) indicating model fit limitations.
`createdBy`	`String`	User who created this group association.
`createdOn`	`Date`	Date when the association was created.
`changedBy`	`String`	User who last changed this association.
`changedOn`	`Date`	Date when the association was last changed.

6. ProductRelation

Defines structural relationships (such as accessories, cross-selling, replacements, or spare parts) from one product to another.

Implementation Class: com.prodexa.product.domain.ProductRelation

Field	Type	Description
`id`	`Long`	Unique database primary key (read-only).
`catalogId`	`String`	Identifier of catalog of the source product.
`productId`	`String`	Identifier of the source product.
`variantId`	`String`	Variant identifier of the source product.
`relatedCatalogId`	`String`	Identifier of catalog of the target related product.
`relatedProductId`	`String`	Identifier of the target related product.
`relatedVariantId`	`String`	Variant identifier of the target related product.
`relatedClassificationId`	`String`	Identifier of the classification of the related product.
`relatedClassificationGroupId`	`String`	Identifier of the classification group of the related product.
`typeId`	`String`	Identifier of the relation type (`ProductRelationType`).
`validFrom`	`Date`	Valid range starting timestamp.
`validTo`	`Date`	Valid range ending timestamp.
`quantity`	`BigDecimal`	Relation quantity.
`statusId`	`String`	Identifier of the product relation status.
`seqNo`	`String`	Sequence sorting number.
`udxText1` / `2` / `3` / `4` / `5`	`String`	Base User Defined Extension (UDX) text fields. Localized term strings starting with `$` are automatically resolved.
`udxNum1` / `2` / `3`	`BigDecimal`	Base User Defined Extension (UDX) numeric fields.
`udxSortKey1` / `2` / `3`	`String`	Base User Defined Extension (UDX) sorting keys.
`syncTypeId`	`String`	Synchronization category code.
`isMandatory`	`Boolean`	True if the relation is mandatory.
`selectionGroupId`	`String`	Selection group identifier.
`isDefaultSelected`	`Boolean`	Used to decide whether the related product should be preselected by default inside kits or configurable bundles.
`descriptions`	`Map<String, String>`	Descriptions of the relation, translated per language code (e.g. `{"en-GB": "Spare part description"}`).
`minQuantity`	`BigDecimal`	Minimum quantity allowed. Null or `0.0` represents no minimum.
`maxQuantity`	`BigDecimal`	Maximum quantity allowed. Null represents no maximum.
`increment`	`BigDecimal`	Minimum incremental purchase lot-size step.
`companyId`	`String`	Division company reference identifier.
`exportChannelId`	`String`	Export channel reference identifier.
`bomId`	`String`	External Bill of Materials reference ID.
`groupId`	`String`	Classification group selector for classification “SmartClassification”.
`JSONGenericAttributes`	`String`	Smart Attributes JSON string based on the selected Smart Group.
`createdBy`	`String`	User who created the relation.
`createdOn`	`Date`	Date when the relation was created.
`changedBy`	`String`	User who last changed the relation.
`changedOn`	`Date`	Date when the relation was last changed.

7. Variant

Represents variation SKUs of a master product, sharing master product fields unless overridden specifically by variantId.

Implementation Class: com.prodexa.product.domain.Variant

Field	Type	Description
`id`	`Long`	Unique database primary key (read-only).
`catalogId`	`String`	Reference Catalog ID of the master product.
`productId`	`String`	Reference Product ID of the master product.
`variantId`	`String`	Unique variant identifier of this variation SKU.
`statusId`	`String`	Status ID of this variant (e.g., `400` confirmed, `800` deleted).
`createdBy`	`String`	User who created this variant.
`createdOn`	`Date`	Date when the variant was created.
`changedBy`	`String`	User who changed this variant last time.
`changedOn`	`Date`	Date when the variant was changed last time.

8. ProductAttributeValue

Represents an individual resolved attribute value assignment for a product or variant.

Implementation Class: com.prodexa.product.domain.ProductAttributeValue

Field	Type	Description
`catalogId`	`String`	Parent catalog identifier.
`productId`	`String`	Parent product identifier.
`variantId`	`String`	Variant identifier (if variant-specific).
`attributeId`	`String`	Unique identifier of the attribute.
`languageId`	`String`	Identifier of the language (if the attribute is localized).
`value`	`Object`	Raw resolved value of the attribute (e.g. Boolean, String, BigDecimal, or List).

5. Guide: Writing FreeMarker Loops & Mappings

Use the following structural loop models to navigate prodexa’s multi-valued, multi-lingual, and composite attribute properties inside your export mappings:

1. Simple Values

Product Code: ${product.productId}
Status: ${product.statusId}
Color Code: ${product.values["Color"]!}

2. Multi-Language Values

<#list product.values as attributeId, attrValue>
  <#if attributes[attributeId].isMultiLanguage>
    Attribute [${attributeId}] Localized Values:
    <#list attrValue as locale, localizedText>
      * ${locale}: ${localizedText}
    </#list>
  </#if>
</#list>

Direct specific locale query:

German Short Description: ${product.values["ShortDescription"]["de-DE"]!}

3. Multi-Valued Attributes

<#list product.values as attributeId, attrValueList>
  <#if attributes[attributeId].isMultivalued>
    Attribute [${attributeId}] Options:
    <#list attrValueList as optionValue>
      - ${optionValue}
    </#list>
  </#if>
</#list>

4. Composite Attribute Tables (Nested Rows)

<#list product.values as compositeId, compositeRows>
  <#if attributes[compositeId].type == "composite">
    Composite attribute: ${compositeId}
    <#list compositeRows as nestedAttributesMap>
      --- Row ${nestedAttributesMap?index + 1} ---
      <#list nestedAttributesMap as nestedAttrId, nestedValue>
        Nested Attribute [${nestedAttrId}] = ${nestedValue}
      </#list>
    </#list>
  </#if>
</#list>

5. Text-Tables & Markdown Rendering

<#list product.values as attributeId, attributeValue>
  <#if attributes[attributeId].type == "text-table">
    <div class="rich-text-block">
      ${markdown2html(attributeValue)}
    </div>
  </#if>
</#list>