Roomle Content Project Data Structure

This document is a prescription on how to keep the configurator content data in a unified and easy-to-handle way.

GIT repository structure

The git repository name should match with the tenant. The repository should start with folders matching the catalogues in the relevant tenant account.

The following structure should be used for git content repositories (UPDATED IN 2024):

{project-root}/                           <--- your working folder
├── content/                              <--- folder storing all catalogs (has to be called content)
│   ├── {catalogId}/                      <--- folder with name matching a catalogId
│   │    ├── _responses/                  <--- created by the Download Catalog Data command, optionally git-ignored
│   │    │  ├── catalogId_allItems.json
│   │    │  ├── catalogId_allTags.json
│   │    │  ├── catalogId_catalog.json
│   │    │  ├── catalogId_components.json
│   │    │  ├── catalogId_materials.json
│   │    │  └── catalogId_textures.json
│   │    ├── components/                  <--- folder with component definitios
│   │    │   └── *.json                   <--- component definitions as JSON files
│   │    ├── items/                       <--- folder with component definitios
│   │    │   └── *.json                   <--- item definitions as JSON files
│   │    ├─ materials/                   <--- folder with component definitios
│   │    │   ├── {materialId_1}           <--- folder with the same name as the externalId of the material
│   │    │   │   └── data.json            <--- material definition as JSON file (must be called data.json)
│   │    │   ├── {materialId_2}
│   │    │   │   └── data.json
│   │    │   └   *.csv                    <--- some CSV files you want to store that handle materials, like texture uploaders, translations, sorting, etc.
│   │    └── *.csv                        <--- some CSV files you want to store that handle components, items, catalog tags, additional information, translations, etc.
│   ├── {catalogId}_draft{N}/             <--- draft catalogs are handled as any other catalog
│   │   └── ...
│   ├── {anotherCatalogId}/               <--- another catalog in its own folder
│   │   └── ...
│   └── metadata.json                     <--- data about the project and RLCS server-side settings
└── rubens_content_server/                <--- override RLCS local files and settings
    ├── settings.project.js
    ├── settings.user.js
    └── ...

Explanation of the individual parts follow:

Components

Keep component source files (JSONs) in the /components/ folder and the relevant CSVs outside of that folder.

CSV for importing componentIds

Used for uploading components when included in the ZIP. Example:

"component_id","component_definition"
"product1_master","zip://product1_master.json"
"product1_components","zip://product1_components.json"

Generate this by right clicking a components folder and selecting the Roomle: Make CSV or ZIP for RuAd import right-click context menu item.

Translations

The files components_translations.csv, catalogue1_materials_translations.csv, catalogue1_items_translations.csv are used to hold the RAPI labels of the entires used for translations. Example of the items translations header for a product, which is relevant for English-speaking, German and French markets:

"item_id","label_en","label_de","label_fr"

Categories / Tags

Categories are defined in a CSV with a header and labels.

"tag_id","sort","label_en","label_de","label_fr"

Categories then should apply to materials and items in the catalogue1_materials_categories.csv and catalogue1_items_categories.csv files. To add categories:

"material_id","tag_ids_to_add"

To remove categories, change the tag_ids_to_add to tag_ids_to_remove:

"material_id","tag_ids_to_remove"

If you want to change the categories, first remove, then add.

Sorting

Use catalogue1_items_sort.csv file. Add-ons and planner entries are ascendingly ordered by the value of sort. A good practice is not to use 1,2,3 as sort values, but rather 10, 20, 30, or 100, 110, 120, allowing you to add entries in between (100, 110, 115, 120, 123, 125, 130, etc.) without having to rewrite all sort values.

Commits

• Start the commit subject with the relevant JIRA ticket code

• Describe what changes in the using imperative form. Try to call the commit, so that it answers the question why there is a change or what changes, not WHAT is in the commit (because you can open it and get the answer).

  • Good example: [Ladder] LAD-234 create ladder steps

  • Bad example: lad 234 did cubes in for loop

• Add a HTTP link to the commit description.

• If you had trouble during work, it is probable that someone else also has trouble when they need to fix it. In that case, do a proper description what was difficult, what you tried and failed or why you can't use an obviously simple solution, etc.

Example: BS-123 reorder parameters, in branch bestsofa/BS-123-sort

• Avoid doing too big commits, be clear in the code. Otherwise your changes are not trackable or fixable.

• Stage only what acutally changes, do not stage debug code snippets if you don't need to (like displaying parameters, coordinate system etc.). When you review the changes (Quality Management), you won't be able to check it properly if you see too much lines with changes which are not actual changes!

• Format before you commit. However, if you start working in an unformatted state, pick only what you really change or do not format at all.

Branch strcuture

main

The main branch should always mirror the RAPI status. If you make changes in the main branch, make sure that those changes get updated in the RAPI. On the other hand, if you make changes in RAPI, do not forget to update the main.

If you continue working on a project that has been on halt, always do or let a production overseer do a reinitialization of the main branch. See the chapter how to do it.

dev/main

Use this branch for development. Commit merge requests from individual tickets to dev/main, which should be checked by your internal QM. The state of dev/main should be functional, no half-done work or work with known bugs should be accepted to merge into dev/main.

<product>/main

Use this branch as the main branch for the product or configurator project. For example, we have a product called freistil190 -> the branch is called freistil190/main

<product>/<Jira-code>-<one-word-description>

Each product should have its own branch (same name as the components prefix). The branch name should contain the Jira ticket code and a short, one-word description of the topic of the branch. For example: freistil190/RB-1100-dev.

After the relevant work for the ticket has been finished, make a MR to the products main branch.

If possible, use one of the following one word descriptions:

• 3d (change in the geometry)

• addons (adding, changing addons logic)

• dev (general development of product)

• dock (docking logic fix / specialized development)

• fix (general fix of the product)

• group (grouping change)

• label (labels, changing labels texts)

• lang (changing or adding translation)

• mats (materials)

• params (parameter logic)

• partlist (fixing articleNrs, part list change)

• sort (change in sorting)

If none of these fits, make up your own short and descriptive suffix.

Workflow

Comparing GIT state with RAPI

To be sure that the current online state is being used, you should reinitialize the GIT repository in order to check the GIT vs. RAPI consistency. As the process of merging into main is not currently bound automatically with the upload to RAPI and vice versa, you should make a diff between main and RAPI yourself.

Normally, the main branch should be a mirror of the state that is uploaded to the RAPI. To check, whether this is true, do the following:

1. create a new branch from main - call it reinit/<currentDate>

2. apply formatting on all components

3. make a commit called "apply formatting with v 0.4.3" (the version of your roomle formatter plugin)

4. delete /components/ folder

5. download components.zip from the RAPI and place the /component/ folder instead of the deleted /component/ folder

6. clean all auxiliary files (incoming components.csv)

7. apply formatting on all components

8. make a commit called "reinitialize"

You can see the changes in the "reinitialize" commit. At the end of each project and at the start of every reopening, this reinitialization should be done to see if the GIT repository is consistent with the RAPI.

• In order to easily and quickly apply formatting on all components, select all of them in the file selector of VS Code, right click and open them to the side. Then, apply the command (Ctrl+Shift+P or Cmd+Shift+P) "Format All Open Roomle JSONs".

Workflow during development

Start your work in the dev/main branch and make a new branch product1/JIRA-100-dev. After the development is done, do a merge request to the dev/main branch, which should be checked by your QM. When the quality of the dev, fix or change is good, open a merge request to main assigned to the production overseer of the project.

Creating repo from existing catalogue or tenant

• Repository name should match tenant account name.

• Prepare all subfolders with all catalogues.

• In every of the catalogues, export categories CSV, components ZIP, mateirals CSV and products CSV.

• Rename the CSV files accordingly and store it in the repository.

• Make a commit to main branch of the repo.

• Now you're good to go; you can develop the changes in the repository, test offline and upload to the database when you're ready.