Set up material properties and templates for finish materials

Create finish materials with a color or texture base, manage material templates, and upload textures that attach correctly to materials.

1. The Material Properties modal (used when creating/editing finish materials on SKUs) lets the user pick a base property of Color or Texture. If Texture is selected, an image must actually be uploaded - Save blocks with 'Please upload a texture file' otherwise; switching back to Color clears any uploaded texture map on save. Texture uploads are stored immediately on selection (each upload creates a texture asset), and sliders/inputs control PBR-style properties (roughness, metalness, transmission etc.; some fields like transmission-dependent ones show placeholders until enabling values are set). Quirk worth knowing: the 'lock aspect ratio' toggle for texture width/height is persisted in the browser's localStorage per material - it does not sync across machines or users, so the toggle state may differ between computers. Material Templates (named presets of these properties) are managed separately: template name is mandatory ('Material Template name cannot be empty'), templates can be updated or added, and a restore action reverts edited values to the template's stored ones. Templates matter for CSV bulk-create of Finish/panel-core SKUs, where material_template_id must reference an existing template from the reference sheet.

   ✓ Am 18. Oktober 2026 im Produkt geprüft

2. When the base property is Texture, the material editor also offers optional bump map and normal map slots in addition to the base texture, so depth can be added on top of the uploaded texture.

   ✓ Am 18. Oktober 2026 im Produkt geprüft

3. The template determines which render properties the finish uses.

   ✓ Am 18. Oktober 2026 im Produkt geprüft

4. When a material is created or updated (UI or enterprise API), its properties JSON is validated against the linked material template: the template defines the exact set of allowed property names (colour, opacity, roughness, metalness, the texture map slots, etc.). Any key not defined in the template makes the save fail with PROPERTY_KEY_MISMATCH_WITH_MATERIAL_TEMPLATE_PROPERTY. Missing keys are NOT checked — a material can be saved with only a subset of the template's properties and no warning is given. The classic failure is a client reusing a properties payload written for one template while passing a different material_template_id: keys that were valid for the old template get rejected against the new one. API mechanics that also trip people up: properties must be sent as a stringified JSON object — a non-parseable string fails with MATERIAL_CREATION_FAILURE (or MATERIAL_UPDATE_FAILURE), and sending an array instead of an object fails with INVALID_PARAMS. If the material_template_id does not exist at all, the error is MATERIAL_TEMPLATE_NOT_FOUND. When a client reports one of these errors, have them fetch the template, list its property labels, and trim their payload to exactly those keys.

5. Textures are uploaded as form-data with two fields, file and name; supported formats are jpeg, jpg and png. The upload creates an image record plus a texture record referencing it, and the response returns the texture with its image embedded. Permissions: uploading requires catalogue-manager rights on the store or business unit, but designers are explicitly allowed as well — a designer can add textures from the design app even without catalogue management rights. To use a texture in a material, its id goes into the material's 'map' property. Only that base map is validated when the material is saved: if the map id does not correspond to an existing texture, the save fails (MATERIAL_CREATION_FAILURE / MATERIAL_UPDATE_FAILURE), and on success the texture's image automatically becomes the material's display swatch. The other map slots — normal, ambient occlusion, bump, metalness and roughness maps — accept texture ids but are NOT existence-checked at save time, so a wrong id there saves without any error and simply fails to resolve later. If a client says their normal or roughness map 'does nothing', verify the id points at a real texture before debugging rendering.