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:
Open the Rubens Admin catalog
Import/Export
pageExport the CSV file of the entries you are going to modify
Sort the file by the ids alphabetically
Find the CSV file in Git, make a diff in order to compare the changes
If there are changes, make a commit in the main working branch
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
Import the changes into Rubens Admin (if you have approval and know what you're doing)
Repeat steps 2, 3, 4
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
The decimal separator must be a dot.
Any field may be quoted, so enclosed within double-quote characters
Each of the embedded double-quote characters must be represented by a pair of double-quote characters.
Fields with embedded commas or double-quote characters must be quoted
There must be no empty lines
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:
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:
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:
To remove tags, use tag_ids_to_remove instead of the tag_ids_to_add.
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.
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.
Set product metadata via import
Items (Products) should have their metadata along with the configurations. Store in items_metadata.csv file.
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:
Navigate to the
Import/Export
Section.Upload your
ZIP
file containing the static products (3D models) to theImport products
uploader and clickProceed
.A new draft will be automatically created, with each static file in the ZIP resulting in a separate product in the draft catalog.
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:
Import components
In order to batch import component definitions use:
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:
"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,
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