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.
This is:
- 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.
- Mandatory information: The product reference, the brand and the product type.
- Product information: This information is not mandatory but highly recommended, especially the short and long descriptions that are displayed in the planner.
- Product representation: This is where you specify among others the 3D resource, the thumbnail and the parameters.
- 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.
- Click Replace to browse for your .BM3MAT file and add it to the datasheet.
- Click
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 and bottomMaterial.
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 :
widthis the length along the grain directiondepthis the length perpendicular to the grain directionheightis 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
widthanddepthare necessary for price calculation, and for the automatic placement of joints 📌 For the generic worktop products, the default value ofheightis 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 ;∞] |
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 🔗.
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. PreciselysurfaceWeightshould 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
applicative rule.
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
applicative rule on the front and back sides which are not adjacent to a wall. If the applicative rule 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.
| Parameter | Type | Possible values |
|---|---|---|
worktopMaterial | Discrete variation | Either acrylic / laminate / quartz / wood |
❗️ This
worktopMaterialparameter 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 side parameter.
The side parameter
| Parameter | Type | Possible values | Default value |
|---|---|---|---|
side | Discrete variation | -1 / 1 | 1 |
The side parameter controls the flip of the worktop in the kitchen planner: by the default the top side is visible (
value is 1). When flipping to the bottom side the value becomes -1.
topMaterial and bottomMaterial
In addition, define the following two parameters.
| Parameter | Type | Possible values | Default value |
|---|---|---|---|
topMaterial | Material variation | external dbID | external dbID |
bottomMaterial | 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).
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.
📌
doubleSidedmust be defined on the worktop generic product.doubleSidedWaterfallmust be defined on the waterfall generic product (this can be the same as the worktop product, unless the parameterwaterfallProductis 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.
📌
doubleSidedProductmust 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 can be used, but with no pricing.
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 Create parameter 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 corresponding 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
notchTypeis defined, but not thenotchPos, 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
shapeparameter 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.).
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 🔗.