SAP PIM mapping.
This guide shows how ULC records emit from a typical SAP landscape.
SAP data model in one page
- SAP MM (Material Management) holds the core material master (MARA, MAKT, MVKE). Every material has a material number (
MATNR). - SAP PLM holds engineering master data, CAD revisions, and change-management workflows.
- SAP MDG is the enterprise governance layer on top, enforcing data quality and approval gates.
- Classification System (CA-CL) holds characteristics (CABN) and classes (KLAH). Luminaire-specific attributes like
BEAM_ANGLE,CCT_K,INPUT_POWER_Wlive here. - Document Info Records (DMS) hold cutsheet PDFs, IES, LDT linked to materials.
- Integration paths: Legacy ECC integration is primarily IDoc-based (XML envelopes). S/4HANA exposes OData (REST/JSON) services for the same master-data domains. Choose OData for new emit integrations; IDocs remain a supported fallback (except on S/4HANA Public Cloud, which restricts integration to released APIs).
Core mapping
Identity (MM material master)
| SAP field (OData) | ULC path |
|---|---|
| Parent configurable material MATNR | product_family.catalog_model |
| Variant configuration MATNR | configuration.catalog_number |
MaterialDescription (MAKT-MAKTX) | configuration.scenario_label |
Brand (Z-field) | product_family.manufacturer.slug |
ProductHierarchy | product_family.catalog_line |
Classification characteristics
SAP characteristics carry typed values with unit of measure. The emitter reads characteristics assigned to a material and maps them to ULC fields:
| SAP characteristic | ULC path |
|---|---|
OVERALL_DIAMETER_MM (NUM, MM) | product_family.physical_dimensions.overall_diameter |
WEIGHT_KG (NUM, KG) | product_family.physical_dimensions.luminaire_mass |
INPUT_POWER_W (NUM, W) | electrical.input_power_w.value |
BEAM_ANGLE_DEG (NUM, DEG) | photometry.beam_angle_deg.value |
TOTAL_FLUX_LM (NUM, LM) | photometry.total_luminous_flux_lm.value |
CCT_K (CHAR enum) | colorimetry.nominal_cct_k |
CRI_RA (NUM) | colorimetry.cri_ra.value |
DRIVER_PROTOCOL (CHAR enum) | electrical.driver_protocol |
The actual characteristic values per material live in the AUSP table (KSSK links class-to-material; AUSP holds the values). Plan the emit to query AUSP for characteristic values, not just KSSK for class assignment.
Two OData services are commonly used for classification data on S/4HANA. API_CLFN_CHARACTERISTIC_SRV ("Classification System Characteristic") exposes characteristic definitions and value-sets directly; use it when the emitter needs to walk the characteristic catalog independent of any one material. API_CLFN_PRODUCT_SRV ("Product Master Data Including Classification") is often a better single-entry endpoint than API_PRODUCT_SRV when characteristic values inline with the product fetch are what the emitter needs; it returns the product master plus assigned classes plus characteristic values in one navigation graph.
Document Info Records (DMS)
| SAP DMS doc type | ULC source_files[].file_type |
|---|---|
CUTSHEET | datasheet_pdf |
PHOTO_IES | ies |
PHOTO_LDT | ldt |
INSTALL_PDF | installation_instructions_pdf |
LAB_REPORT | (referenced via attestations[].source_document_ref) |
Gotchas
- IDoc vs OData. Legacy ECC without S/4HANA exposes data via IDocs (MATMAS, CLFMAS, DOCMAS). Mapping is conceptually identical; the engineer handles XML instead of JSON.
- Language keys. SAP descriptions are per-language (SPRAS). Choose a canonical language key (typically
EN) and record it in the integration config. - Change-master tracking. Skip materials with active engineering change records (AENR, referenced by change-master transaction CC02) from export until the change closes. Gate that draft state by holding the export, not by shipping a thin record: the validator computes the conformance level from whatever the record carries.
- Classification sparseness. Not every luminaire will have every expected characteristic populated. Skip or fail the export when a required characteristic is missing.
- Unit rounding errors. SAP often stores dimensions at coarse precision (integer mm). Preserve decimal precision when computing the Imperial companion.
- IDoc serialization ordering. When emitting a material with classification, callers must send MATMAS first (material master) then CLFMAS (classification); ULC emit pipelines that batch must respect that order.
Full guide with OData endpoint examples, attestation patterns, and ABAP/Python hybrid transform skeleton: github.com/ulcspec/ULC/blob/main/mappings/pim/sap.md