Set Up Worktops

 

Worktops are a linear feature (like cornices or plinths) generated automatically on base cabinet, corner cabinet and high cabinets. The Kitchen Application will check all the worktop products in the catalog and display them all as possible worktops in the edit panel of the cabinet editor.

Worktop options are editable at two different places depending on the option:

• The Edit Panel of the cabinet for basic modifications: change the material, switch sides if double-sided worktop, add waterfalls, etc.
• The worktop editor for advanced modifications on dimensions, cuts, edges, cut-outs, joints, etc.

❗️ Even if there is no dependency with wall panels 🔗 and wall edge strips 🔗, worktop is a strong driver to these two options.

➡️ Click here 🔗 to open the complete sample to define worktops through API.

---

Definitions

The table below lists all the definitions around worktops.

Term	Definition
Worktop	Can be applied on the top of base cabinets. Worktops can have various colors and materials, they even can be reversible. Adding a worktop allows the customer to access a dedicated editor to define and edit the location of cut-outs, edges (and more) where possible.
Worktop type	Defines type of worktop and pricing calculation method, can be precut (worktop is available in various fixed dimensions with per piece pricing) or custom (worktop is available by the meter with according pricing).
Worktop shape	Shape means any shape that the worktop can have other than a rectangular shape.
Worktop cut	Cut means any cut around the worktop: back, side, split or custom cuts.
Worktop cut-out	Cut-outs on the worktop are for various purposes such as hobs, sinks, water pipes, water taps, etc. Two cut-out shapes are available: rectangle or circle.
Worktop edge	Worktop edges can be managed with joints, various edge cut, specific edge products or colors, or in some cases a waterfall.
Worktop edge compatibility	Based on the worktop, the edge compatibility defines what edge finishes are possible. This requires to define worktop edge products in the catalog.
Worktop default edge finish products	Define the default edge finish products for specific worktop's edges (adjacent to high cabinet, front, back and non visible)
Worktop operation compatibility	Based on the worktop, defines what operations are possible. This requires to define worktop operation products in the catalog. Cuts, cut-outs and joints are considered as worktop operations.

---

Illustrations

Below are illustrations of concepts regarding worktops that are documented hereinafter.

Worktop Operations

Worktop Shapes

Worktop used as waterfall

Worktop types

---

Important Information

Generic worktop products

The worktops must be defined as generic products (with no price) with a list of mapped products (with a price defined)

This is true in all the cases, even if there is only one product mapped to the generic worktop.

All the parameters in this document must be set on the generic worktop product

The only mandatory parameters required in the mapped products are the dimension parameters : width, depth, height (see dimension parameters 🔗 for more details)

Worktop insertion height

If a value is specified on the worktop for the behavior defaultAltitude then when a freestanding worktop is added to the project it will be inserted at this height from the floor.

If no value is specified on the worktop then it will be inserted at 1000mm from the floor.

---

Specify the Basic Information

The minimum information required to create a worktop is common to every kind of products.

Connect to 3DCloud and click Products on the CONTENT menu. Then, click New product.

This is:

1. The name: The name will be displayed in the planner (in the Edit panel) and should be available for all languages. If not, the planner will display the name in the fallback language.
2. Mandatory information: The product reference, the brand and the product type.
3. Product information: This information is not mandatory but highly recommended, especially the short and long descriptions that are displayed in the planner.
4. Product representation: This is where you specify among others the 3D resource, the thumbnail and the parameters.
5. Pricing: This is where you specify the pricing type (regular, discount...).

❗️ Select your product type carefully because it will trigger the applicative rules: the type is "Worktops".

❗️ Worktops are priced via a particular algorithm that finds the best fitting boards from the generic product 🔗 mappings. This dedicated algorithm is applied to all products that have the "Worktops" type.

---

Specify the 3D Resource and the Thumbnail

Worktops are specific products: The required resource is a texture (a .BM3MAT file). No 3D asset (.BMA or .BM3 files) is required, the geometry is automatically generated by predefined shape.

1. Click Upload a 3D model to browse for your .BM3MAT file and add it to the datasheet.
2. Click Upload a picture to specify the bitmap file that will be used as thumbnail in 3DCloud and in the planner. Follow the format and size recommendations.

Case of Reversible Worktops

For reversible worktops only, resources are based on material parameter values topMaterial, bottomMaterial and edgeMaterial. In this case, the texture resource is not mandatory at the worktop product level and the materials targeted by these parameters must be already defined in the database as materials 🔗.

---

Specify the Dimension Parameters

These parameters must be defined for a horizontal board, as follows :

• width is the length along the grain direction
• depth is the length perpendicular to the grain direction
• height is the thickness of the board

📌 Even if the current product is a waterfall product, its dimensions must be defined as a horizontal board
📌 For the mapped worktop products, the default values of width and depth are necessary for price calculation, and for the automatic placement of joints
📌 For the generic worktop products, the default value of height is necessary for the 3D modelisation and the sinks/cooktop placement

❗️ Although the .BM3MAT does not have by definition any dimensions, the default sizes of the worktop must be specified in the datasheet. Indeed, size parameters are mandatory: for precut worktops, width is a strictly mandatory parameter that is taken into account for price calculation.

Parameter	Type	Possible values
width	Discrete length	[0 ;∞]
depth	Discrete length	[0 ;∞]
height	Discrete length	[0 ;∞]

Click Add variable dimension in the Product representation tab to define the default width, depth and height of the worktop.

---

Define the Option Parameters

The option parameters are not strictly mandatory, but they are highly recommended to ensure the behavior in the kitchen planner and that the expected options will be available in the cabinet and worktop editors.

➡️ Refer to the following dictionaries for complete lists of parameters available for worktops 🔗, operations 🔗 and worktop edges 🔗.

Click Add an option In the Product representation tab to define the following parameters.

The worktopType Parameter

worktopType has two usages:

• Define various types to suggest to the customer in the planner;
• Define how the price will be calculated.

❗️ This parameter is thus highly recommended.

Parameter	Type	Possible values
worktopType	Discrete variation	precut / custom

Precut

Used for worktops that cannot be changed by the customer; the same material is used on both sides. It is sold and priced by the unit and the planner calculates the number of units needed from total length of the worktop (in this case the price by unit must be specified).

Custom Used for worktops that have the option to have the same material on both sides or not. In this case, the customer can order the worktop to be single or double sided. They are sold and priced by the meter. The planner calculates the price from total length of the worktop (in this case the price by linear meter must be specified).

The ecoFeeCategory Parameter

ecoFeeCategory has a usage:

• Define to find the same category in the range where the weight of the board lies and to retrieve the ecofee value of that weight.

❗️ This parameter is mandatory to trigger EcoFeeRule.

Parameter	Type	Possible values
ecoFeeCategory	string	any string

The surfaceWeight Parameter

surfaceWeight has a usage:

• Define to calculate the weight of board using width, depth and surfaceWeight and the calculated weight will be returned by EcoFeeRule.

❗️ This parameter is mandatory to trigger EcoFeeRule. PreciselysurfaceWeight should be in kilograms per square meter.

Parameter	Type	Possible values
surfaceWeight	number	[0 ;∞]

The waterfallPossible Parameter

Parameter	Type	Possible values
waterfallPossible	boolean	True / False

waterfallPossible defines whether it is possible to use a worktop in a vertical position as a waterfall or not.

If true, the worktop that can be used as waterfall will appear in the Edit menu in the planner. It will also appear in the Worktop Editor where the customer can add, remove and define the waterfall worktops.

The waterfallType Parameter

This parameter can be specified only if waterfallPossible is set to 'true'.

Parameter	Type	Possible values
waterfallType	string	straight / angled

waterfallType defines whether the waterfall is straight or angled.

Straight waterfall

When the horizontal worktop sits on top of the vertical waterfall worktop. In this case, the worktop is covering the waterfall with an overhang value specified in product as waterfallInsetEnd. If this parameter is not defined then fallback value is retrieved from fromWorktopEnd of waterfallInset application distribution parameter. The depth of the waterfall board is reduced by an inset of value specified in product as waterfallInsetFront. If this parameter is not defined then fallback value is retrieved from fromWorktopFront of waterfallInset application distribution parameter on the front and back sides which are not adjacent to a wall. If the application distribution parameter is not defined, then fallback to 3mm for both values.

Angled waterfall When the horizontal and vertical worktops both meet with a 45 degree joint. In this case the depth of the waterfall board is identical to the worktop depth.

📌The waterfall type can be changed in worktop editor as well as in edit panel.

The waterfallProduct Parameter

This parameter can be specified only if waterfallPossible is set to 'true'.

❗️ To specify this parameter, click Add product replacement instead of Add option.

waterfallProduct defines the product used for the waterfalls, if the waterfall product is different than the worktop product.

This product must be defined as another generic worktop product, with its own board product mapping, parameters, materials, etc.

📌 Only one waterfall product can be added.
📌 If the parameter is not defined, the waterfalls will be priced as worktop boards.

The waterfallJointProduct Parameter

This parameter can be specified only if waterfallPossible is set to 'true'.

❗️ To specify this parameter, click Add product replacement instead of Add option.

waterfallJointProduct defines the joint to use when manufacturing the worktop.

The pricing of the joint can be controlled like the worktop pricing: either by the unit or by the linear meter for example.

📌 Only one joint product can be added per worktop.

The cornerJointPossible Parameter

cornerJointPossible defines whether it is possible to allow continuity joints between two worktops, or not.

If the parameter is set to 'true', the continuity joint can be a "point to point" continuity joint, as follows:

The cornerHandedJointPossible Parameter

cornerHandedJointPossible defines whether it is possible to allow an "on board" continuity joint between two worktops, or not.

If the parameter is set to 'true', the continuity joint can be an "on board" continuity joint, as follows:

Left	Right

The notchOffset Parameter

if notchOffset is defined, and has a value different than 0, it automatically creates a joint with a notch offset of the parameter value. The conditions for transforming a joint to add a notch are :

• the joint is on a corner
• the joint is aligned with one of the corner edges
• the joint is perpendicular to the other corner edge (this implies that the 2 edges of the corner are perpendicular)

The arcOperationPossible Parameter

Parameter	Type	Possible values
arcOperationPossible	Discrete variation	TRUE /FALSE

arcOperationPossible defines whether it is possible to add an arc on a worktop or not.

Typically, an arc is added at the end of a breakfast bar and it usually has a radius of half depth. The arcOperationPossible parameter controls the applicative rule that checks if there is an arc operation, which means that if the parameter is set to true, the check will be triggered.

❗️ This parameter does not control whether an arc operation is shown as an option for a worktop in the planner.

The roundedCutAllowedNumber Parameter

Parameter	Type	Possible values
roundedCutAllowedNumber	Discrete variation	0 / ... / Infinite

roundedCutAllowedNumber defines the number of rounded outer cuts on a worktop. Typically, rounded cuts are limited on specific types of custom worktops, such as quartz, due to worktop strength.

The roundedCutAllowedNumber parameter controls the applicative rule that checks the number of allowed rounded outer cuts on each board of the worktop
The number of rounded corners must match one of the possible values

❗️ This parameter does not control whether a rounded corner cut is shown as an option for a worktop in the planner.

Filtering Parameters

You can create the parameter of your choice to be used by the customer to filter the list of worktops in the edit panel.

Below are two possible filtering parameters.

The worktopMaterial Parameter

The worktopMaterial parameter is a filtering parameter. You can choose (i.e. create) any parameter to filter the list of worktops in the Edit panel. The parameter should be on all worktops to filter and also set in the settings of the Application Distribution to be recognized as a filtering parameter (See the key aggregationsParameter 🔗).

Parameter	Type	Possible values
worktopMaterial	Discrete variation	Either acrylic / laminate / quartz / wood

❗️ This worktopMaterial parameter is a string value with no link to the texture of the panel itself. This texture is defined by the asset resource or material parameters.

⚠️The MinDistanceTapHoleAndSink 🔗 and MinDistanceTapHoleAndWTBackEdge 🔗 Applicative Rules are based on the worktopMaterial parameter (value: quartz) and make this parameter mandatory on the worktop product. In this case, worktopMaterial is not limited to a filtering usage.

The worktopThickness Parameter

The worktopThickness parameter is a filtering parameter. You can choose (i.e. create) any parameter to filter the list of worktops in the edit panel. The parameter should be on all worktops to filter and also set in the application distribution settings to be recognise as a filtering parameter (key in the Application Distribution Settings JSON: aggregationsParameter 🔗).

Parameter	Type	Possible values
worktopThickness	Discrete variation	[0 ;∞]

---

Reversible Worktops

Worktops with different materials on the top and bottom sides are called reversible. To setup a reversible worktop, define a topMaterial and bottomMaterial with different values.

The topMaterial, bottomMaterial and edgeMaterial parameters

Parameter	Type	Possible values	Default value
topMaterial	Material variation	external dbID	external dbID
bottomMaterial	Material variation	external dbID	external dbID
edgeMaterial	Material variation	external dbID	external dbID

topMaterial and bottomMaterial parameters define which materials are compatible to be applied on the two sides of the worktop. These materials should be an existing product coming from the standard material library (see Set Up Materials 🔗 for more details).

⚠️It is possible to set these parameters Visible and Editable, and set multiple possible values.
If a worktop is configured this way, it will not be reversible anymore to avoid confusion : the user can select manually the top, bottom, and edge materials.
This configuration with multiple possible values must be used only for illustration worktops

---

Double-sided option

The action of applying the worktop material to the bottom side of the boards is refered to as double-sided operation. It is not to be confused with reversible worktops.

There are several parameters to setup in order to enable the double-sided operation on your worktops.

The doubleSided and doubleSidedWaterfall parameters

Parameter	Type	Possible values	Default value
doubleSided	boolean	TRUE / FALSE	FALSE
doubleSidedWaterfall	boolean	TRUE / FALSE	FALSE

doubleSided defines whether the worktop horizontal boards are double sided or not. doubleSidedWaterfall defines whether the worktop waterfall boards are double sided or not.

📌 doubleSided must be defined on the worktop generic product. doubleSidedWaterfall must be defined on the waterfall generic product (this can be the same as the worktop product, unless the parameter waterfallProduct is used).

The doubleSidedProduct parameter

Parameter	Type	Possible values	Default value
doubleSidedProduct	Product variation	external dbID	external dbID

If doubleSided is set to 'true' (or if doubleSidedWaterfall is set to 'true' for waterfall boards), the product referenced by doubleSidedProduct is added to the BOM and to the linear export information.

📌 doubleSidedProduct must be defined on all the available worktop board products, not the worktop generic product.

---

Parameters for Worktop Edges

The edgeCompatibility Parameter

edgeCompatibility defines a list of products that can be used as an edge finish for the worktop. This edge should be an existing product available on the current Legal Entity.

❗️ The edge compatibility parameter is available only for "custom type" worktops and should only be used if there is more than one edge option.

Worktop Edge Products

Click Add product replacement to define the edgeCompatibility parameter (product variation with link to an external dbID) and specify the products that can be used as an edge.

📌 For worktop edge products, no 3D asset (BMA or BM3) or texture (BM3MAT) is required as 3D resource.

📌 The type of 2D model supported is SVG (no other types of images are supported) and it is possible to upload it directly to the desired worktop edge (section "Product representation" and "Change 2D Model" in 3DCloud).

To be recognized by the planner as a worktop edge, the corresponding product must belong to the "Countertop edge" type:

Optional Worktop Edge Parameters

The boolean parameters listed below can be defined optionally on worktop edges to enable (or not) some operations.

They relate to worktop edge applicative rules, and can be defined independently of each other.

📌 The parameter name is mandatory for the applicative rules.

Boolean	Description
allowedOnArc	If 'true', the worktop edge product can be applied on an arc.
allowedOnCut	If 'true', the worktop edge product can be applied on a cut.
worktopFront	If 'true', the worktop edge product is priced in a different BOM item if it is on a worktop front edge. (this allows to remove the price of the front edges)
allowedOnNonVisible	If 'true', the worktop edge product can be applied to a non-visible edge (i.e. on the side touching the wall).
allowedOnFront	If 'true', the worktop edge product can be applied to the front of worktop.
otherGrainDir	If 'true', the worktop edge product can be applied neither parallel or perpendicular to the worktop grain.
parallelToGrain	If 'true', the worktop edge product can be applied parallel to the grain direction.
perpendicularToGrain	If 'true', the worktop edge can be applied perpendicular to the grain direction.

Set both parallelToGrain and perpendicularToGrain to 'true' to apply the edge product to every grain direction. These parameters do not exclude each other.

The Default Edge Finish Products Parameters

The product parameters listed below can be defined optionnally on worktop to set edge finish for specific edge types :

Parameter	Type	Description
adjacentEdgeFinish	Product	Edge finish product for edges adjacent to high cabinets.
backEdgeFinish	Product	Edge finish product for back edge.
frontEdgeFinish	Product	Edge finish product for front edge.
nonVisibleEdgeFinish	Product	Edge finish product for non visible edges (next to a wall).

---

Parameters for Worktop Premade Edges

The premadeEdgeManagement Parameter

Parameter	Type	Possible values	Default value
premadeEdgeManagement	boolean	TRUE / FALSE	TRUE

premadeEdgeManagement defines if a worktop has premade edges or not.

if this parameter is not configured, its value is considered true by default

The premadeBackEdgeCompatibility Parameter

Parameter	Type	Possible values	Default value
premadeBackEdgeCompatibility	Discrete length	[0 ;∞]	-

premadeBackEdgeCompatibility must be configured if the worktop boards has 2 premade edges, one on the front and one on the back. This parameter contains the list of depths where a 2nd premade edge must be set on the back of the board

In this example, this worktop is configured to have a 2nd premade edge on the back if the worktop depth is 1250mm only:

---

Parameters for Polished Underside

The polishedUnderside Parameter

| Parameter | Type | Description | | --- | --- | --- | --- | | polishedUnderside | product | Polished Underside product |

polishedUnderside must be configured if the worktop can have polished undersides. If this parameter is set to null, the polished underside feature cannot be used. The polished underside product must be an Parameters for an Operation 🔗 product of type polishedUnderside

To be recognized by the planner as an operation, the products must have the type "Operation":

---

Parameters for Worktop Operations

The operationCompatibility Parameter

operationCompatibility defines a list of products compatible as a cut, cut-out or shape operation for the worktop. This operation should be an existing product available on the current Legal Entity. See operations 🔗.

❗️ If needed for precut worktops, these operation products can also be set up as products without prices.

Worktop Operation Cut and Cut-out

Click Add product replacement to define the operationCompatibility parameter (product variation with link to an external dbID and specify the compatible products.

To be recognize by the planner as an operation, the corresponding products should be set with the "Operation":

📌 By default, for worktop operation no 3D asset (BMA or BM3) or texture (BM3MAT) is required. Except if the operation is used to defined a cut-out definition: thus, a BMA is required (see below).

If the cut-out is defined via a BMA then the cut-out operation should have the following parameters.

Parameter	Parameter type	Possible values	Function
width	Discrete length	[0 ;∞]	Defines the size of the cut-out on the X-axis (from left to right). Mandatory.
depth	Discrete length	[0 ;∞]	Defines the size of the cut-out on the Y-axis (from front to back). Mandatory.
cutElement	Product variation	External dbID	Defines the product relating to the cut-out. This information is required by the manufacturing information 🔗 export feature in the case of automatic cut-out. Mandatory.

For rectangular cut-out operation, it is mandatory to also define the radius. Click Add variable dimension to define it.

Parameter	Parameter type	Possible values
cornerRadius	Discrete variation	[0 ;∞]

cornerRadius defines the corner radius of the cut-out for each angles.

Worktop Operation Shape

A price per shape can be defined for a worktop. It is done by defining operations of type shape for this worktop. See operations 🔗. If one shape among circular, arc end, arc length, mushroom is recognized on the worktop and a correspong operation is declared in operationCompatibility parameters then the operation is added to the BOM. The resulting BOM contains the rectangular board encompassing the shape and the shape operation, both are priced.

---

Parameters for Worktop Priced Articles

Some parameters can be added to the priced worktop board articles, to specify particular characteristics.
For example, if a retailer has a board with a specific shape and dimensions in its catalog, he can specify these information for this article.
In this case, the article will be added in the BOM if, and only if, the board has every characteristic specified in the article

The notchType and notchPos Parameters

If the board that needs to be priced has a joint with a notch, the choice of the corresponding article has to be specific.
there are 4 types of possible articles defined as follows :

Parameter	Type	Possible values	Function
notchType	String	male / female	Defines the type of notch on the board
notchPos	String	left / right	Defines the position of the notch on the board

📌 If a notchType is defined, but not the notchPos, the board is considered compatible, whatever the orientation of the notch

The exactDepth Parameter

If a board has to be added to the BOM only if the board has a specific depth, it is possible to specify this by setting the exactDepth parameter to "true"

Parameter	Type	Possible values	Function
exactDepth	boolean	TRUE / FALSE	if true, the board is added to the BOM only if its depth matches the article depth

The exactShape Parameter

If this parameter has a value, it means that the board has to match the shape and the dimensions of the article. For some shapes, some other parameters might be important

Parameter	Type	Possible values	Function
exactShape	String	squareangle	Defines the shape of the board article (squareangle is currently the only possible value)
shapeDepth	Discrete length	[0 ;∞]	the depth on th side of the board (Mandatory for the "squareangle" shape)
shapeFront	Product variation	external dbID	an edge finish product

⚠ This is not the same thing as the shape parameter on generic worktops, which is a priced operation on a rectangular board Currently, the only exactShape available is the squareangle

The Square Angle shape

This shape is a square board, with a cut on the angle. the front edge needs to be on that specific edge, and the dimensions should match the ones defined in the article product. if the shapeFront is also defined. the board also have to match the front edge

---

Pricing

The pricing depends on the worktop type:

• For "precut" worktops: this is a fixed price on precept worktop, the pricing is 'regular'.
• For "custom" worktops: depends on customer needs, the pricing method is 'linearMeter' or 'linearFeet' in addition to a mapping.

Below is an illustration of the pricing for a custom worktop.

Note that, like every product, worktops support different pricing 🔗 types: regular, reduced, membership, etc.).

Click the Pricing tab to define the price(s).

---

Parameters to Add at Upper Level

Enable worktops on the cabinet top-assembly by defining the worktopOption parameter, and set its default value to 'true'.

Parameter	Type	Possible values	Default value
worktopOption	boolean	TRUE / FALSE	TRUE

---

Other Actions before Deploying

Before being able to deploy the worktop on the application distribution, you have to perform the following actions.

Catalog Update

Add all the products to the catalog 🔗 of the Application Distribution, unless the products will neither be available in Assembly Editor nor in the planner. This includes: the worktop, the worktop edges and the operation products.

Define the Paths

Define the guidelines on the top of the box in Assembly Editor to position the worktop.

➡️ See Define Worktop Position 🔗.