# When and how to use which CSV template for the PDC data import

Store all relevant CSV data in Git. Keep the data separated, have one csv file for sorting, one for categorizing, one for definitions etc. Use the Git repository structure convention.

Guide for the CSV data update:

  1. open the PDC catalogue Import/Export page
  2. download the CSV file of the entries you are going to modify
  3. sort the file by the ids alphabetically
  4. find the CSV file in Git, make a diff in order to compare the changes
  5. if there are changes, make a commit in the main working branch
  6. branch the main working branch, make a CSV file with your changes
    • delete all unnecessary columns, best also delete all entries you do not want to change
  7. upload the changes into PDC (if you have approval and know what you're doing)
  8. do steps 2, 3, 4 again
  9. commit the change file and the resulting overwritten CSV, do not forget to add a description to the commit (ticket code + reason of the change)

This approach will keep a thorough track of what has been changing in the work.

Warning: Make sure you back up the data (follow the above mentioned steps), so that you can revert in case the result went wrong for any reason.

# Id Headers in the CSVs

The entry is selected by its id. In the following table you can see which id header you should use for which import entry.

If you want to translate categories, components or material, use a different header for the id column:

Entry Type Id field header
Products item_id
Categories tag_id
Materials material_id
Components component_id

# Adding translations

All entries in the PDC can have their labels in different languages. In order to be able to quickly translate multiple entires, use following example:

"item_id","label_en","label_de"
"abc_armchair","Armchair","Sessel"
"abc_1seater","1-Seater","1-Sitzer"

To translate components, materials or categories, use component_id, material_id or tag_id in the header respectively. You can upload label_XX, where XX is any supported language abbreviation.

In the GIT repository, keep this data in files with a _labels.csv suffix.

# Categorizing

This applies for materials and products. The product category will be applied in the add-on list in the catalogue. The material category will then be applied in the material selectors.

To CATEGORIZE, use id and tag_ids_to_add, where you put in one or more tags, for example:

"material_id","tag_ids_to_add"
"leather_brown","leather brown"
"fabric_green","fabric green"

To UNCATEGORIZE, use tag_ids_to_remove instead of the tag_ids_to_add.

To RECATEGORIZE, do two steps: Uncategorize first, then categorize. Use two separate CSVs. In the Git repo, best keep the categorization CSV with all entries with all categories. Then, you can remove the category from all entries, change the categorization file and categorize back.

# Sorting

This applies to products. Items in add-ons lists will be sorted ascending by the sort value.

"item_id","sort"
"abc_armchair","10"
"abc_armchair","20"

Recommendation: do not use 1, 2, 3, but rather 10, 20, 30 as sort values (you can use even higher numbers), so that you do not have to change values in all other entries if you want to move/add one or more items. Keep it in a file suffixed with _sort.csv

# Creating item definitions

This is mostly relevant for content scripters. If you want to make an item add-on, or a thumbnail carrier, use the item_id and the configuration. Use the minimal needed configuration in a items_definition.csv file. Do not forget to use double quotes in the configuration Json.

"item_id","configuration"
"abc_armchair","{""componentId"":""cata:abc_master"",""parameters"":{""elementType"":""armchair""}}
"abc_1seater","{""componentId"":""cata:abc_master"",""parameters"":{""elementType"":""inline""}}

# Setting items metadata

Items should have their metadata along with the configurations. Store in items_metadata.csv file.

"item_id","type","detailType","width","depth","height","layer","scaleable","flipable","colorable","visibilityStatus","manufacturerSKU"

# Uploading components ZIP

In order to batch upload component definitions use:

"component_id","component_definition"
"abc_master","zip://components/abc_master.json"

Path must start with zip:// prefix and be relative to the zip root. Compress the CSV along with the components folder and upload to components.

Warning: You can have unused components JSONs in the zip, but make sure that you compress only the CSV file intended to define the operation you're doing at the moment.

# Uploading materials - shading

Shading specifies:

  • constant or modifier values for material properties (roughness, metallic, specularity)
  • basecolor in RGB (normalized, <0-1>), which is applied if no RGB or RGBA texture is present
  • alpha <0-1> (1 - fully opaque, 0 - fully transparent)
"material_id","shading"
"leather_brown","{""alpha"":1,""roughness"":0.9,""metallic"":0,""specularity"":0,""basecolor"":{""r"":0.9686274509803922,""g"":0.3607843137254902,""b"":0.9686274509803922}}"

# Uploading material thumbnails

PDC does not generate thumbnails for materials. Thumbnail image should be provided by the content creator.

"material_id","thumbnail"
"leather_brown","zip://thumbnails/brownLeather543_small.jpg"

# Uploading textures to materials

We recommend having one file for albedos (basemaps, main textures), one file for normal maps, one file for ORM maps. Some materials might use only some of the maps.

mapping: RGB, RGBA, XYZ, ORM
mmWidht, mmHeight: real-world dimensions of the texture in milimeters (used for UV mapping) tex0_image: path to the texture image file in the zip

tileable: the tileable flag of the texture

"material_id","tex0_mapping","tex0_mmHeight","tex0_mmWidth","tex0_tileable","tex0_image"
"leather_brown","XYZ","100","100","true","zip://textures/brownLeather543.jpg"

# Material properties

To assign custom data to the materials that can be recovered using the GetMaterialProperty function, use following CSV header:

"material_id","property_<property1name>","property_<property2name>",...,"property_<propertyNname>"

See Using GetMaterialPropery Function for details.