Import/Export

Import data in Rubens Admin

Navigate to Dashboard > Catalogs and select an existing catalog. Click on Import/Export in the top menu bar.

On the left side of the page you can find the import fields and import options. You can import data for products, tags, materials, components, prices and meshes. For each type of data a sample file is linked below. Feel free to use it as a starting point for your data import.

You can import some catalog formats into Rubens Admin.

To import multiple static products in one batch you can import a correctly formatted ZIP file in the Import 3D assets import section.

Recommended approach and versioning

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

Guide for the CSV data update:

  1. Open the Rubens Admin catalog Import/Export page

  2. Export 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. Import the changes into Rubens Admin (if you have approval and know what you're doing)

  8. Repeat steps 2, 3, 4

  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.

There are no backups in the database, thus all files and information will be permanently deleted! If an error occurs during the import, no changes will be saved.

CSV format rules

The CSV files must be formatted correctly, otherwise the imports will fail. Adopt the following requirements to your files:

  • The values must be comma-separated. Semicolon, TAB or other characters as separator will not work

"abc_armchair","Armchair","Sessel"

  • The decimal separator must be a dot.

"abc_armchair",10.5

  • Any field may be quoted, so enclosed within double-quote characters

"abc_armchair","10.5"

  • Each of the embedded double-quote characters must be represented by a pair of double-quote characters.

"abc_armchair ""noir""","abc_armchair"

  • Fields with embedded commas or double-quote characters must be quoted

"abc_armchair, left",10.5

  • There must be no empty lines

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

The .csv has to be saved with BOM (byte order mark) encoding set to UTF-8 without BOM or plain UTF-8. Note that UTF-8 with BOM can not be imported. You can check the file encoding with the editor of your choice.

General fields in import CSVs

Id headers

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 tags, components or material, use a different header for the id column:

Entry Type
Id field header

Products

item_id

Tags

tag_id

Materials

material_id

Components

component_id

Import translations

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

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

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

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

Set tags via import

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

To tag, 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 remove tags, use tag_ids_to_remove instead of the tag_ids_to_add.

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

To change tags, do two steps: Remove tags first, then tag again. Use two separate CSVs. In the Git repo, best keep the tagging CSV with all entries with all tags. Then, you can remove the tag from all entries, change the tagging file and tag again.

Import sort values

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

Import products

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""}}

Set product metadata via import

Items (Products) 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"

Batch Upload of Static Products

If you have multiple static products, you can streamline the process by batch uploading them in a ZIP format. Follow these steps to efficiently upload and publish your products:

  1. Navigate to the Import/Export Section.

  2. Upload your ZIP file containing the static products (3D models) to the Import products uploader and click Proceed.

  3. A new draft will be automatically created, with each static file in the ZIP resulting in a separate product in the draft catalog.

  4. Wait for the assets to finish processing. Once processing is complete, navigate to the catalog section and publish the draft to the live catalog. For more details on automatic draft publishing, refer to this section.

If you have your 3D assets hosted somewhere, you can alternatively also upload just one csv file with the following structure in the Import products section.

item_id

label_de

description_de

type

detailType

width

depth

height

sort

layer

scaleable

flipable

colorable

visibilityStatus

manufacturerSKU

tag_ids_to_add

tag_ids_to_remove

configuration

asset_source

For each asset, you need to create a line in the csv file. In the column asset_source you have to insert the location/link of the hosted asset. Uploading the csv file triggers then the same processing as described above as in the case of uploading the 3D assets in a ZIP container.

NOTE: Before uploading, ensure that your data meets the platform's format requirements. This will prevent long wait times for data that does not conform to the necessary standards. Utilize our free Content Analyzer tool at Content Analyzer to verify your products. If your data is compliant, proceed with the upload.

This feature is only available for live catalogs.

Import tags

Prepare the tags in the following structure to import it via Rubens Admin:

"tag_id","label_en","description_en","material_ids","item_ids","png_icon","svg_icon","inspiration_image","global","hidden","sort"

Import components

In order to batch import 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 import the ZIP-file to components.

Unused components: 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.

Import materials

The material import can contain both texture files and meta data. A detailed explanation on how to prepare the texture files correctly can be found in the Roomle materials and texture requirements.

The meta data is imported as a CSV file. It should contain all specifications for each material, such as shading, scaling, material tag, etc. All the information about a single material should be in a single row and each column must have the specification description so that the data is imported correctly. Below is the list of all possible column descriptions.

Import materials CSV columns

"material_id"

This column must always be filled out for an import to be successful. Each material has a unique "material_id" and it is saved to a specific catalog. In the import can be used both existing material ids for updating the meta / texture details, or new ids to create new materials. A material_id can contain small or capital letters, numbers, '-' and '_'; no spaces or special characters are allowed.

"label_<language>"

To define multiple translations for a material, add a column for each language with the description "label_<ISO 639-1 language code>". For example, for English write "label_en", for German "label_de", for Dutch "label_nl" and so on. Languages currently supported by Rubens are listed here.

"description_<language>"

It is possible to add a more detailed description about a material but it is not shown in any of the standard Roomle destinations at the moment.

"thumbnail"

The texture thumbnail will be shown in the configurator menu. It is better to keep this image as small as possible, ideally around 320 px x 320 px. In this column the location "zip://" and the name of the file must be included (e.g.: "zip://thumbnail.jpg"). For a material, that has no texture, there is no need to import a thumbnail because it will be automatically generated.

Still the thumbnail image can be provided by the content creator in the following CSV format:

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

"shading"

The material properties are described in the shading json. The following settings must always be defined for the shading:

  • basecolor - the material base colour is defined with RGB values. For example,

"basecolor": {
    "r":0.2196078431372549,"g":0.21176470588235294,"b":0.21568627450980393
}

  • metallic - specifies how 'metallic-like' a material is.It is always a value from 0 to 1, where 0 is a non metallic material (e.g.: rubber) and 1 is a very metallic material which strongly reflects its environment (e.g.: chrome).

  • roughness - defines how smooth or rough a material is. It is always a value from 0 to 1, 0is perfectly smooth with sharp reflections material and 1is completely matte/dull surface.

  • alpha - defines the opacity of a material. The value can be from 0 - a completely invisible material; to 1 - a completely opaque material (it is the default value).

Optional parameters - those settings can be included in the shading definition or simply omitted when not needed:

  • doubleSided - by default in real-time renderings a back-face culling is applied. This means polygons/triangles are only visible from one