Generic Products

Overview

The concept of Generic Product is the abstract grouping of several products having the same general shape, but different dimensions, colors, descriptions, prices, etc.
An archetypal use-case is to represent a family of kitchen fronts existing in different widths and heights. It is obviously possible to create all family members as distinct ByMe Products, but the Generic Product provides the following benefits:

• Use of a common parametric 3D resource shared between all the members of the family, which can result in some cases in better performance and easier Range Management,
• Ability to reference the family rather than the members, which can create lean user experiences, such as better grouping of products in displayed catalogs.

Defining Generic and Mapped Products

To create such a family in the ByMe platform, the process is:

1. Create one ByMe Product carrying the 3D representation - a parametric BMA or scalable BM3 - with common attributes defined as parameters. It is called the Generic Product.
2. Create several "Mapped Products" carrying the specific information of each variation of the Generic Product:
   • description, reference, prices, thumbnail.
3. Create the mapping relationships between the Generic Product and the Mapped Products, often referred to as "the Mappings" - this is done on the Generic Product.

This can be achieved either using the ByMe API or by using 3DCloud.

Mapping Relationships

The Mapping relationship is defined by:

• The list of parameters used in the relationship. These are the parameters whose values are different between the various mapped products.
• The mapping table; each row is a mapping, constituted of:
  • a set of logical conditions on product parameter(s) (mandatory)
  • a reference to the mapped product (mandatory)
  • a priority (optional)

Figure - Mapping example as shown in 3DCloudByMe

Note:

• The parameters used in the mapping table must be parameters declared on the Generic Product.
• It is possible to define the same combination of parameter values in different mappings.
  The one with the highest priority will be selected when it comes to solving the mapping.
• On the contrary, it is not possible to use the same Mapped Product on several parameter combinations. If you need different conditions to map on the same mapped product, you can group them with an || (OR) operator. See the sample below.
• Avoid useless conditions, like a condition that is always true. It will not affect the result and might slow down the solving algorithm.
• The current UI of 3DCloud only supports a simple list of && (AND) operators in the mappings and the "EQUAL" comparison. If you need to use a more complex mapping, you have to use the API directly (see below).

Mapping JSON Object in Detail

Structure definition

The mappings structure is defined as an array of mapping objects. Each mapping object is defined as follows.

Key	Description
conditions	An object containing a single conditions key. /!\ this "conditions" attribute is nested inside another "conditions" attribute. See below for more details.
priority	The priority for the mapping. If several mappings are valid, the one with the highest priority is used. Default value if not given is 0.
referenceProduct	The resulting product to use when the mapping is used.

The conditions.conditions attribute defines the logical conditions for the mapping to be valid. It is an array of elements that can be of 3 sorts:

• a comparison block with
  • param: name of the parameter
  • value: value for the condition
  • comparison: a comparison operator between EQUAL (==), EQ (==, same as EQUAL), GT (>), GTE (>=), LT (<) or LTE (<=)
• an operator block with a single operator attribute defining the chosen logical operator. Supported values are && ( AND) and || (OR).
• an array with the same structure as conditions.conditions. It is used to group comparisons together as it is done with parenthesis in maths. It can be necessary to group conditions because they are not evaluated in the order they are defined (from top to bottom), but rather using the Javascript operator precedence ( See this document)

Example

Here is an example of the mappings structure to provide when creating mappings through the API.

[
    {
        "conditions": {
            "conditions": [
                {
                    "param": "width",
                    "value": 400,
                    "comparison": "EQUAL"
                },
                {
                    "operator": "&&"
                },
                {
                    "param": "height",
                    "value": 400,
                    "comparison": "EQUAL"
                }
            ]
        },
        "referenceProduct": "2026"
    },
    {
        "conditions": {
            "conditions": [
                {
                    "param": "width",
                    "value": 600,
                    "comparison": "EQUAL"
                },
                {
                    "operator": "&&"
                },
                [
                    {
                        "param": "height",
                        "value": 600,
                        "comparison": "GTE"
                    },
                    {
                        "operator": "||"
                    },
                    {
                        "param": "height",
                        "value": 800,
                        "comparison": "LTE"
                    }
                ]
            ]
        },
        "priority": 10,
        "referenceProduct": "2028"
    }
]

Runtime Behavior of the Generic Product

Generic Product as a Reference

When the Generic Product is used as a parameter value, it behaves as a reference to the Generic Product, not to any of its mapped products.
If the Generic Product is displayed - for example as a possible choice, in the edit panel of an enclosing product - only the information of the Generic Product is displayed, including the description, which should not carry any variant-specific mention (no dimension, etc.).

Generic Product as an Instance

When the planner needs to create a piece of furniture and all its components, the products are instantiated, and in this context, the ByMe platform attempts to resolve the mapping declared in the Generic Product.
As for all parametric products in the ByMe Platform, the execution context provides values for each of the Product’s parameters - either the default values, or those set by the enclosing assembly, or set by the user in an Edit panel of the application.
When a Generic Product is instantiated in the ByMe platform,

• The values of the parameters required in the mapping table are obtained from the runtime context; if the required parameters are not defined, the mapping is unresolved (see below).
• The ByMe platform performs a lookup of the mapping parameter values in the mapping table of the Generic Product, which designates a particular Mapping Product. It fails if the parameter value combination is not in the mapping table, in this case the mapping is unresolved (see below).
• If the mapping is resolved, the ByMe Platform makes both the Mapped and the Generic Products available to the Application. The general rules are:
  • The scene in the 3D planning application mostly uses the Generic Product, its 3D representation, description, thumbnail, etc.
    • In this context, the only attribute used in the Mapped Product is the price, in order to calculate the total price of the project; all other attributes of the Mapped Product are ignored, including the 3D representation if any.
  • Some behaviors exist outside of the 3D scene, such as the BOM generation, and make extensive use of both the Mapped and the Generic product. These are application-specific, meaning they can be different for Kitchen or Home.
  • As an example, the BOM generation would probably use the variant-specific reference, description and prices information, and not this of the Generic Product.
• If the mapping is unresolved, the 3D scene works well, but the price calculation as well as the BOM are affected. Unresolved mappings should be avoided.

Exposure of the Parameters of a Mapped Product

Parameters of a mapped product are not exposed to a containing entity.
For example, let Front be a Generic Product. In a containing assembly, the expression Front.type is evaluated with Front being the Generic Product, and not the Mapped Product.

This need would arise from situations beyond the design intent of Generic Products - Mapped Products should be limited to: Commercial Information (name, reference, description...), prices, thumbnail, but not parameters nor 3D Representation.