# Service configuration export format

The format is used to present articles specified with the Rubens-Configurator in the context of TC. It is the interface between the world of Roomle and the world of TC.
The export document is a JSON-file. It contains a format version, headers, walls and articles. Each article consists of modules, which in turn can consist of modules.
The format should be kept as simple as possible, but as flexible as necessary. The export should be easy to configure in simple cases, but special cases should still be able to be defined. The freedom to define complex use cases should not lead to the need for a verbose and over-complicated specification for simple cases.

# Format specification

Version:

Each export document must contain information about the version with which it was created. Semantic Versioning 2.0.0 (opens new window) is used for versioning. Major version changes mean a general format change and incompatibility. Minor version changes are for extending the format, but remain backwards compatibility. For bug fixes, only the patch version changes.

Header:

not yet defined

Wall:

not yet defined

Article:

An article is a essential part or component of the configuration and planning. An article is composed of modules. Each article must be assigned to a header object and can be assigned to a wall. The article needs to contain general information about position size and type of an object.

Module:

Modules are the components of articles and can be nested. A module can therefore consist of modules. A module contains all the individual information to describe the product and its specification in detail. Because this information is highly dependent on the type of the article and module, it mainly consists of a list of key-value pairs that specify an object's attributes.

# Service export JSON Objects

Document : { 
    "version": String,
    "articles": [ 
        Article* 
    ],
}

Article : {
    "constructionLibrary": "<name>",
    "version": "<version>",
    "moduleId": "<name>",
    "origin": [<x>, <y>, <z>],
    "size": [<width>, <depth>, <height>],
    "attributes": AttributesObject,
    "modules": [ 
        Module* 
    ]
}

Module : {
    "moduleId": "<name>",
    "attributes": AttributesObject,
    "modules": [ 
        Module* 
    ]
}

AttributesObject : {
    ("<key>" : "<value>")*
}

Properties:

name	description
constructionLibrary	The name of the construction library (HOMAG TC)
version	The version of the construction library
articleId	The name of the article (HOMAG TC)
description	Description of the article (HOMAG TC)
orderlineNo	Orderline number of the article (unique)
quantity	Quantity of the article / Default 1
groupId	Group of articles forming a constructive article in the TC
note	Additional text
moduleId	The unique name of the module inside the construction libraray (HOMAG TC)
origin	The origin of the article in the Rubens configuration or plan (*1)
size	The bounding box size the article (*1)

*1) In computer science, it is always about the accuracy of floating point numbers. For example, the value 0.05 cannot be represented exactly as an IEEE-754 floating point number and will be 0.0500000007. 0.0500000007 is not a problem itself as long as it is always treated the same. However, such errors propagate and multiply in the calculation. As a workaround, we round the positions and dimensions of the components to 4 decimal places. Since the unit is always millimetres, 4 decimal places correspond to 0.1 micrometres. This accuracy is still more than enough for furniture manufacturing.

Example:

{
    "version": "1.0.0",
    "articles": [
        {
            "moduleId": "mr_StorageUnit_Single",
            "origin": [-444.8431396484375, -337.25592041015625, 0.0],
            "size": [451.0, 345.00006103515625, 721.0],
            "constructionLibrary": "bathlibrary_ts",
            "version": "2022-11-08_19-23-31.0000000",
            "attributes": {
                "pub_Width": 450.0,
                "pub_Height": 720.0,
                "pub_Depth": 345.0,
                "pub_CarcaseProgram": "?",
                ...
            },
            "modules": [
                {
                    "moduleId": "mf_Dorr",
                    "attributes": {
                        "view": "open",
                        "pub_Width": 450.0,
                        "pub_Depth": 345.0,
                        "pub_Height": 720.0,
                        "pub_FrontHeight": 190.0,
                        "pub_FrontProgram": "?",
                        "pub_FrontColor": "Holz",
                        "pub_FrontEdgeColor": "Alpinweiss",
                        "pub_FrontEdgeThk": 16.0,
                        "pub_FrontHeight_changed": true,
                        "pub_NrOfShelves": 0.0
                    },
                    "modules": [ ... ]
                },
                ...
            ]
        },
        {
            "moduleId": "mr_StorageUnit_Single",
            "origin": [5.1568450927734375, -337.25592041015625, 0.0 ],
            "size": [451.0, 345.00006103515625, 721.0],
            "constructionLibrary": "bathlibrary_ts",
            "version": "2022-11-08_19-23-31.0000000",
            "attributes": {
                ...
            }
        }
    ]
}

# Export

The format definition, the plugin and the export are based on the following rules:

No implicit assumptions
Additional properties must be specified explicitly
A default format export must work without explicit plug-in data specification

PlanComponent and SubPart are objects in the context of Roomle and the Rubens-Configurator that describe the configuration of the components and their assembly. Article and Module are the objects in the export format that provide the configuration specification for the world of CSW.

The objects in the target format are generated from the configuration objects with the following rules:

The root PlanComponent becomes an Article.
All parameters of a PlanComponent become attributes of the Article.
Each Child or SubPart becomes a Module.
All parameters of a SubPart become attributes of the Module.
The SubPart hierarchy is reflected in the Module hierarchy. Nested Children become nested Modules.

Although this specification allows a complete export of a configuration without additional data, these general rules do not cover all practical use cases and are not sufficient for a good external presentation. These rules must be customizable for individual components. Therefore, specific plug-in data can be defined in a component definition. These plug-in data are specified in the following.

# Plug-in data specification

The plug-in data specification is part of the component definition. The "plugin-data" object already exists and was formerly used for IMOS plug-in data ("imos" sub-object). The service export specification is located in the "service-export" sub-object.

# Service export definition JSON Object

The export properties can either be constant values or scripts. All scripts are evaluated only at time of export in arbitrary order. All Roomle script functions can be used in the script and the script has full access to all parameters and variables of the component.

ServiceExport : { 
    "constructionLibrary": string | "<script>",
    "version": string | "<script>",
    "moduleId": string | "<script>",
    "isRoot": false | true | "<script>",
    "ignore": false | true | "<script>",
    "parentRuntimeId": number | "<script>",
    "masterSubComponent": string | "<script>",
    "sortOrder": number | "<script>",
    "excludeParameters": [
        "<pattern>"*
    ]
}

Properties:

key	value	default value	description
constructionLibrary	string or script	catalogueId of the componentId	The name of the construction library (HOMAG TC)
moduleId	string or script	externalId of the componentId	The unique name of the module inside the construction libraray (HOMAG TC)
version	string or script	empty string	The version of the construction library
isRoot	Boolean value or script	false	If this flag is set, the component becomes an article, otherwise the component is a module
grouped	Boolean value or script	false	If this flag is set, the articles from one configuration get the same "groupId"
ignore	Boolean value or script	false	If this flag is set, the component ignores (nonetheless, the children and subparts continue to be processed)
relativeParentId	string or script	---	The relative path to a module's parent article or module. (*1)
parentRuntimeId	number or script	---	The parent article or module of a module. This property has no meaning if no "isRoot" is set. (*2)
masterSubComponent	string or script	---	Internal id of the subComponent which is to completely replace the component. (*3)
sortOrder	number or script	---	An array of modules is sorted by this number.
articleId	string or script	---	The name of the article (HOMAG TC)
description	string	---	Description of the article (HOMAG TC)
excludeParameters	array of patterns	---	Lists of parameters that must be excluded from the export. Each item in the list is a "LIKE" (*4) pattern.

*1) relativeParentId: This property has no meaning if "isRoot" is set and defines the relative subComponent path of the internal IDs to the parent component. The path is defined like a Linux file path. The elements of the path are separated with '/' (slash), '..' addresses the parent element and a name indicates the internal name of a subComponent.

*2) parentRuntimeId: This property has no meaning if "isRoot" or "relativeParentId" is set. If not defined, this will automatically be the runtime ID of the parent component. Override with runtime ID of the actual parent component if the component-subComponent or parent-child hierarchy is not matching the defined module-submodule hierarchy.

*3) masterSubComponent: Internal ID of the subComponent that is to completely replace the component. The component itself is ignored and all other subComponents become modules of the master subComponent.

*4) excludeParameters: "LIKE" pattern:

_ is a placeholder for any single character
% is a placeholder for any string
\_ is the _ character
\% is the % character

Example:

{
    "id": "hbocean:carcass_02",
    ...

    "plugin-data": {
        "service-export": {
            "constructionLibrary": "bathlibrary_ts",
            "version": "1.2.3",
            "moduleId": "mr_StorageUnit_Single",
            "isRoot": true,
            "ignore": false,
            "parentRuntimeId": -1,
            "excludeParameters": [
                "rml_%",
                "view"
            ] 
        }
    }
}

← Plan Interaction Handler List of Errorcodes →