# Combeenation Docs

> Create configurators at rocket speed

This file contains all documentation content in a single document following the llmstxt.org standard.

## AI skills

AI skills give your AI agent in-depth knowledge of the Combeenation platform. They follow the open [Agent Skills](https://agentskills.io) format, which is supported by many agents such as GitHub Copilot, Claude Code and Cursor.

With the skills installed, your agent can:

- assist you in [Custom Code](/docs/configurator-ui-ux/custom-code/custom-code-) development, taking both the code in your project and the configurator behind it into account
- answer questions about the platform, for example about [Hive](/docs/configurator-logic/hive-language)

The skills are maintained in the [Combeenation skills repository](https://github.com/Combeenation/skills) and evolve over time.

### Install

Run this command in your project folder:

```bash
npx skills add combeenation/skills
```

### Prerequisites

- Connect the [MCP server](/docs/ai/mcp-server), so your agent can access your configurator.
- For Custom Code projects, link your project to its configurator: in the Custom Code section of the configurator editor, use "Connect to local IDE". This creates a `cbn.config.json` file in your project, which tells your agent which configurator to work with.

---

## Getting started with AI

You can make use of AI tools in several ways: through assistants built into the Combeenation platform, through your own AI agent connected to Combeenation, and through AI tools that read this documentation.

### AI assistants on the platform

Combeenation comes with AI assistants built into various areas of the platform. Currently, AI code assist helps you write code for [PDF assets](/docs/asset-management/pdf-asset) and [workflows](/docs/integrations-and-api/workflows/workflow-in-depth).

We are working on bringing AI assistance to more areas, including a platform-wide assistant.

### Work with your own AI agent

If you use an AI agent such as GitHub Copilot, Claude Code or Cursor, you can connect it to Combeenation:

- The [MCP server](/docs/ai/mcp-server) gives your agent live access to the platform. It can explore your configurator and make changes to its drafts.
- The [AI skills](/docs/ai/ai-skills) give your agent in-depth knowledge of the platform, such as Hive and Custom Code.

We recommend using both: the skills tell your agent _how_ to work with Combeenation, and the MCP server lets it actually do so.

### Use these docs in any AI tool

This documentation is available in a format optimized for AI tools. Point your AI tool to one of these files or paste the URL into a chat:

- [llms.txt](https://docs.combeenation.com/llms.txt): an index of all pages with short descriptions
- [llms-full.txt](https://docs.combeenation.com/llms-full.txt): the complete documentation in a single file

The documentation is also available on [Context7](https://context7.com/llmstxt/combeenation_llms_txt).

---

## MCP server

The Combeenation MCP server connects your AI agent to the Combeenation platform via the [Model Context Protocol](https://modelcontextprotocol.io). With it, your agent can explore your configurator and make changes to its drafts.

### Connection details

| Setting        | Value                                 |
| -------------- | ------------------------------------- |
| URL            | `https://portal.combeenation.com/mcp` |
| Transport      | HTTP                                  |
| Authentication | `Authorization: Bearer <token>`       |

`<token>` is a Combeenation API token. See [here](/docs/integrations-and-api/integrations#bearer-token-authentication) for how to create one.

An API token belongs to a single company. Use the token of the company that owns the configurator you're working on.

### Setup in VS Code

The MCP server is configured per project in the file `.vscode/mcp.json`:

1. Open your project in VS Code.
2. Run the command **MCP: Open Workspace Folder MCP Configuration** from the command palette.
3. Add the following configuration:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "combeenation-api-token",
      "description": "Combeenation API token",
      "password": true
    }
  ],
  "servers": {
    "cbn-mcp": {
      "type": "http",
      "url": "https://portal.combeenation.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:combeenation-api-token}"
      }
    }
  }
}
```

4. Start the server: run the command **MCP: List Servers**, select your server and then **Start Server**. VS Code asks for your API token and stores it securely.

With this setup, the file contains no secret and can safely be committed to version control.

:::info[Token prompt not working]
The `inputs` approach may not work in VS Code. If you aren't asked for your token or the server fails to authenticate, replace `${input:combeenation-api-token}` with your actual token and remove the `inputs` section.

The file now contains a secret and **must be removed from version control**:

1. Add `.vscode/mcp.json` to your `.gitignore` file.
2. If the file is already tracked, run `git rm --cached .vscode/mcp.json`.
:::

:::danger[Never commit your API token]
Anyone with access to your repository could use a committed token to access your company's data. Removing the token later doesn't help, as it stays in the git history. If a token was ever committed, revoke it immediately and create a new one.
:::

### Setup in other agents

Some agents, such as Claude Code or Cursor, don't read `.vscode/mcp.json` or can't prompt for the token. Add the [connection details](#connection-details) to the agent's own MCP configuration instead. Refer to your agent's documentation for the exact format.

As the configuration then contains your token, store it in one of these places:

- **Project-level configuration** (recommended): a configuration file in your project that is listed in `.gitignore`.
- **User-level configuration**: applies to all your projects. As a token belongs to a single company, this doesn't work if you work on configurators of several companies.

### Check the connection

1. Make sure the server is running. In VS Code, run the command **MCP: List Servers** and check the status of `cbn-mcp`.
2. Check that the Combeenation tools are available in your agent's tool list.
3. Ask your agent something like "List the components of my configurator".

For the best results, also install the [AI skills](/docs/ai/ai-skills).

---

## Basic workflow

#### 1. Upload 3d file

You can upload `.glb` and `.babylon` files to create a 3d asset.

**GLB** is a default format for 3d models and widely known across the web.  
Most 3d tools support exporting in GLB format, and 3d model exchange platforms typically offer models in GLB format as well.

**Babylon** files are representing Babylon.js scenes in JSON format.  
These kind of files are more powerful than GLB files, as additional Babylon.js specific features and technologies can be provided within the files.  
Babylon files are typically created by exporting manipulated scenes from Babylon.js tools like the [sandbox](https://sandbox.babylonjs.com/) or the [playground](https://playground.babylonjs.com/).

**Material extraction**

The system automatically extracts material definitions from the uploaded 3d file and creates new material assets inside a folder called `Materials3d`.

If a material asset with the same name already exists in the `Materials3d` folder, the existing material will not be overwritten. Instead, the existing asset will be linked to the uploaded 3d asset.

![](<https://docs.combeenation.com/assets/images/image%2851%29-f246d6f6732451bfa572ccb9f498bb63.png>)

:::info
The uploaded 3d file may only contains these kind of materials:

- [PBRMaterial](https://doc.babylonjs.com/typedoc/classes/BABYLON.PBRMaterial)
- [PBRMetallicRoughnessMaterial](https://doc.babylonjs.com/typedoc/classes/BABYLON.PBRMetallicRoughnessMaterial)
- [PBRSpecularGlossinessMaterial](https://doc.babylonjs.com/typedoc/classes/BABYLON.PBRSpecularGlossinessMaterial)
- [StandardMaterial](https://doc.babylonjs.com/typedoc/classes/BABYLON.StandardMaterial)
- [BackgroundMaterial](https://doc.babylonjs.com/typedoc/classes/BABYLON.BackgroundMaterial)
- [NodeMaterial](https://doc.babylonjs.com/typedoc/classes/BABYLON.NodeMaterial)

The editor warns the user if they try to upload a 3d file containing unsupported material types and rejects the uploaded data completely.
:::

#### 2. View and adjust data of 3d asset

The 3d asset UI displays specific data about the model, helping the user get an impression of the 3d file's content.

- **Nodes**: the structure of meshes and transform nodes
- **Materials**: list of material assets that are assigned to nodes within the 3d asset
- **Tags**: list of tags that are assigned to nodes within the 3d asset
- **Animations**: animation groups that are defined in the 3d asset, see [Babylon.js docs](https://doc.babylonjs.com/features/featuresDeepDive/animation) for detailed information about animations
- **Decals**: overview of “decals”, which represent mesh details, created on the Combeenation platform, see “[Decals](/docs/asset-management/3d-and-material-assets/decals)” for detailed information

When selecting a certain node, you will see specific data of this node.

- **Material**: link to material asset
- **Tags**: list of assigned tags
- **Transformation**: position, rotation and scaling information of the node
- **Morph targets**: technology for interpolating mesh geometry, see [Babylon.js docs](https://doc.babylonjs.com/features/featuresDeepDive/mesh/morphTargets) for detailed information about morph targets

![](<https://cdn.document360.io/4cfaaa8a-dd58-4746-a4dc-1e7902de9417/Images/Documentation/image(52).png> 'image(52).png')

**Material assignment**

The material-to-node assignment is established during the **initial** upload when creating a new 3d asset. The user can then manually change this material assignment by selecting a different material asset.

Each subsequent file upload will not overwrite the existing material assignment to preserve the user's changes. However, if new nodes are present in the upload, material assignments will still be created for these new nodes.

**Tag assignment**

"Tags" are a concept of Babylon.js for **grouping** objects like nodes or materials, see [Babylon.js docs](https://doc.babylonjs.com/features/featuresDeepDive/tags) for detailed information about tags.  
These tags can then be used as parameter subject of the viewer controls “[set parameter values](/docs/configurator-ui-ux/controls/3d-viewer-control#set-parameter-values)” slot or in the viewers “[parameter manager](https://3dviewer.docs.combeenation.com/classes/ParameterManager.html)” API.

Similar to materials, tags are extracted from the 3d file only during the **initial** upload to preserve any changes made by the user. Users can modify tags within the node editor by adding, removing, and creating new tags.

#### 3. Adjusting material assets

As mentioned previously, material assets are automatically extracted and created when uploading a 3d model.  
But material assets can also be created manually by clicking the “**+ New**” button, however this feature only supports **PBR material**s.

For a quick setup, you can choose from a variety of material templates.

![](<https://docs.combeenation.com/assets/images/image%2878%29-69d59536be56bd4c77f1996bbc74b03b.png>)

There are 2 editors, “**Basic**” and “**Expert**”.

The “Basic” editor offers a UI for the most common material properties, available exclusively for **PBR materials**. This is because material properties vary significantly across different types of materials, and PBR materials are by far the most common ones in use.

![](<https://docs.combeenation.com/assets/images/image%2856%29-0bb57dd4b7d520578543368a9fcfc28b.png>)

The “Expert“ editor represents the “raw” JSON description of the material.  
The user has full power to add, remove or modify certain properties to tweak the material.  
Some properties like `id`, `name` or `customType` are ignored though, as they will be overwritten by the system in a later step.

Since the user modifies the JSON string directly, it's possible that the string could become invalid, such as by removing commas or colons. In such cases, the material becomes invalid and cannot be saved. However, the editor helps identify where JSON errors occur, and you can still click “Discard changes” anytime if you encounter issues.

![](<https://docs.combeenation.com/assets/images/image%2857%29-18b8e0e58ed05ce0dace79ccf60313eb.png>)

**Upload texture images & use them in materials**

If your uploaded 3d model contains materials with **textures,** you will most likely receive some warnings in extracted material assets after the model upload.  
These warnings indicate that the images, which represent the dedicated textures, are not uploaded yet.  
You can easily do this by clicking the “Upload image” button in the corresponding texture channel.

This action will automatically create an **image asset** in the `Textures3d` folder and links this image asset to the material texture channel.  
You can also upload your images manually into the `Textures3d` folder and select them in the material texture channel dropdown menu.

![](<https://docs.combeenation.com/assets/images/image%2853%29-ccfc39fb0f72ea72e1888c79843aeebc.png>)

#### 4. Assign bundle to configurator

See [How to assign bundles to configurators](/docs/asset-management/assign-asset-bundles-to-configurators#how-to-assign-an-asset-bundle) for detailed description.

#### 5. Use 3d & material assets in configurator

After assigning the asset bundles to the configurators, 3D and material assets can be utilized within the configurator. You'll need to create a [viewer control](/docs/configurator-ui-ux/controls/3d-viewer-control) to visualize these assets.

If no further action is taken, you may encounter two outcomes:

- If there is exactly **one** 3d asset among all assigned asset bundles, that model will be visible immediately.
- If there are multiple 3d assets, all models will be hidden by default, requiring manual handling of model visibility.

Handling model visibility and applying parameter can be done in 2 ways.

**Hive**

Use viewer controls “[set parameter values](/docs/configurator-ui-ux/controls/3d-viewer-control#set-parameter-values)” slot.  
This is the go-to solution for simple projects, as it eliminates the need to set up a custom code environment.

**Custom Code**

For more advanced requirements you can establish a [custom code](/docs/configurator-ui-ux/custom-code/custom-code-) setup where you have the full power of the [combeenation viewer](https://3dviewer.docs.combeenation.com/) API, Babylon.js and Typescript in general.  
Tey components for interacting with 3D and material assets include the [ModelManager](https://3dviewer.docs.combeenation.com/classes/ModelManager.html) and [ParameterManager](https://3dviewer.docs.combeenation.com/classes/ParameterManager.html) though.

#### 6. Upload & use viewer environment file

In terms of 3d scene customization the user has the possibility to define an “environment”, which is responsible for image based lighting (IBL).  
See [Babylon.js docs](https://doc.babylonjs.com/features/featuresDeepDive/materials/using/HDREnvironment) for further info about environments and IBL in general.

The environment file (.env) is represented by a **file asset**.  
You can then create a component which provides the URL of the uploaded environment file e.g. using the following Hive rule:

```hive
// "Cups3d" = Name (or alias) of bundle assigned to configurator
// "env" = Folder name in which "studio" is located
// "studio" = Asset name
Cups3d.env.studio.url
```

This component can be added to the environment [parameter](/docs/configurator-ui-ux/controls/3d-viewer-control#environment-url) or [slot](/docs/configurator-ui-ux/controls/3d-viewer-control#set-environment-url) in the viewer control.

---

## Decals

"Decals" are used to create details, like **badges** or **logos** on existing meshes.

![](https://docs.combeenation.com/assets/images/image-1733397612213-34c276199e0a64c86d7e023030cca377.png)

Although such details can also be created inside the 3d model itself, having a customizable editor on the Combeenation platform provides certain advantages:

- Change decal configuration like **position** or **size** without having to re-upload the 3d model
- Works with any 3d model, no need for special preparation
- Integrates smoothly into other parts of the Combeenation 3d framework, such as material assets and tags

The basis for this feature is the "[Mesh Decal](https://doc.babylonjs.com/features/featuresDeepDive/mesh/decals#mesh-decals)" functionality from Babylon.js.  
The output of such a decal is just a **mesh**.  
Now you can assign [material assets](/docs/asset-management/3d-and-material-assets/basic-workflow#3-adjusting-material-assets) to that mesh or use it in the 3d viewers [parameter system](/docs/configurator-ui-ux/controls/3d-viewer-control#set-parameter-values) to bring life into that decal.  
You may also want to have a look at [this chapter](/docs/configurator-ui-ux/controls/3d-viewer-control#how-to-draw-dynamic-content-on-the-3d-model) for drawing dynamic content on the decal mesh.

### How to create a decal

First navigate to the "Decals" tab of your 3d model and press "New decal".

![](https://docs.combeenation.com/assets/images/image-1733400785513-4e3081e98a04829607b1efe8f118bcf6.png)

This action will open a new modal dialog, where you can enter the **name** of the decal, the "**p\*\***arent mesh**" and the associated **material\*\*.  
The parent mesh setting is important, as it defines on which mesh the decal geometry will be created.

You can choose an existing material, or add a new one.  
Since decals often use textures with transparent areas, it is typically a good starting point to create a material from the "**Transparent SVG**" template.

![](https://docs.combeenation.com/assets/images/image-1738653626849-dc4471c171a690ddf44d8f063db8f707.png)

You can still change all of these settings in the editor at a later step.

The decal geometry is the result of the intersection between the parent mesh and a fictive box, that can be tweaked by the editor in the "**Geometry**" section.  
When opening the "Geometry" section you will see a box with blue edges appear. This box can be used to adjust the geometry data in an interactive way, since finding the correct data for the box geometry can be very tricky.

![](https://docs.combeenation.com/assets/images/image-1733401209009-8e4bed2b2c1bd0a887b2bbda59ea3319.png)

Anyway here is an overview of the **geometry settings**:

- **Position:** center of the box
  - this is **not** necessarily the position of the final decal
  - you can change the position interactively by dragging the box in the scene
  - use "Pick position in model" to define the box position via mouse click, this is typically a good starting point
- **Size:**size of the box
  - use the gizmos on the corners and areas of the blue overlay box to adjust the size interactively
- **Normal:**"main" (= z) direction of the box
  - required to indicate the first intersection area if "**Cull back faces**" is active
  - the front side, which is pointing towards the normal vector, is indicated by the red plane
  - use the gizmos on the edges of the overlay box to adjust the rotation of the box
  - use "Auto-detect normal" to align the decal box normal vector with the normal vector on the intersection area, this leads to undistorted intersection areas
- **Rotation angle**: rotation around the normal vector in degree
  - edge gizmos may also affect the rotation around the normal vector
- **Offset**: distance from the parent mesh
  - if the decal would be located exactly on the intersection surface, "clipping" effects would occur, therefore the decal has to be positioned slightly **in front** of the parent mesh
  - each vertice of the decal is shifted along its normal vector, so that round surfaces will be scaled as well
  - in praxis this value will be very low (e.g. 0.001), since too high offsets will be visible as gaps between the parent and the decal mesh

##### Additional settings

- **Capture UVs**:
  - _false_: creates a "standard" UV mapping across the decal mesh![](https://docs.combeenation.com/assets/images/image-1733403021306-25ac6a298728b27897c34189bb60890c.png)
  - _true_: uses the UV mapping of the parent mesh on the intersection area![](https://docs.combeenation.com/assets/images/image-1733403104422-581238a27f1b1a4fda469e0d0e72275d.png)
- **Cull back faces**:
  - _true_: decal is only created on the first intersection with the parent mesh
- **Local mode**:
  - _true_: creates decal mesh as **child** of the associated parent mesh, in this way transformation of the parent mesh will also be applied on the decal mesh
  - _false_: creates decal mesh in world space (without parent mesh)
  - **NOTE:** this setting has NO effect on the initial position of the decal
- **Use glTF side orientation**:
  - activate this flag if the decal will be created underneath a "glTF root node", which has a negative scaling in z direction
  - otherwise the faces will be flipped, leading to invisible decals
  - **CAUTION:** this flag directly relates to "**Local mode**", as "Local mode" decides if the decal is created underneath a parent hierarchy or not

---

## Assign asset bundles to configurators

To use an asset in a configurator, you must first allow the configurator to access it.  
This is done by **assigning** the asset bundle that contains the asset to your configurator.

You always assign a **specific version** of a bundle. Thus you are always in control over which data your configurator uses – you choose when it should use a newer version and can go back to using an older version whenever you please.

Assignments work with draft versions of both the configurator and asset bundle as well, with only 1 limitation: a published configurator can only use a published asset bundle. This is to prevent any last-minute changes to an asset bundle draft from breaking a live configurator.

### How to assign an asset bundle

Open a configurator draft and look for the asset bundle assignment dialog at the top of the page:

![Asset assign overview](img/assign-asset-bundles-to-configurators/Untitled (1)(1).png)

Now, select the **bundle** you are interested in from the first dropdown.

- A list of **versions** of that bundle will be shown.
- Click the "**+**" button of the version you want to use. Usually that would be the newest version.
- **Only one version** of a particular bundle can be assigned to the same configurator at a time. However, you can assign **multiple bundles** to the same configurator.

You can click an assigned bundle version to see a few more details, such as the person who has assigned the bundle or the timestamp of the assignment.

![Assigned bundle info](img/assign-asset-bundles-to-configurators/Untitled (2)(1).png)

#### Alias name

You may have observed that an alias name is typically set automatically when assigning a bundle to a configurator. This alias name is usually the same as the asset bundle name, but it can be customized as needed.

This alias name is useful for resolving naming conflicts with other assigned bundles or for clearly identifying the bundle you are using, without altering the original asset bundle name.

### Usage

Once you have assigned an asset bundle to your configurator, you can use all the assets of that bundle.  
Simply type the name of the asset in any Hive rule to access it.

Example: if you have an image asset with the name `SomeImageAsset` you can access its Url like this:

```hive
SomeImageAsset.url
```

As mentioned above ([alias name](/docs/asset-management/assign-asset-bundles-to-configurators#alias-name)) you can also use the alias name to access the contents of a bundle. Especially useful if there are assets with the same names in multiple bundles.

```hive
AilasName.SomeImageAsset.url
```

**Data source** assets can currently only be used in **table** components.

---

## Basics

A data source contains tabular data that can be selectively loaded and filtered in a configurator with a table component.

### Supported File Types

A data source can be created or updated with files of these types:

- Microsoft Excel **.xls** or **.xlsx**
- CSV files **.csv**
- JSON files **.json**

While you can create a single data source asset from such a file, we strongly recommend that you instead upload the file as a file asset first. This will allow you to create **multiple** data sources based on it and **update them all at once** whenever you upload a newer version of your file. We will walk you through this process in the next section.

### **Create a new data source**

1.  **Create a new file asset**  
    Upload the file that contains the data for your data source as a file asset (make sure that the Asset Type is set to “File”). It must be a file with [one of the supported file types](/docs/asset-management/data-source-asset/basics#supported-file-types).

    ![](<https://docs.combeenation.com/assets/images/image%2872%29-3ff075fc662f30230b46e319384748a7.png>)

2.  Select the file asset, click on **Create data source** and enter a name for your new data source.

    ![](<https://docs.combeenation.com/assets/images/image%2873%29-73c09f3269ff45b456207b657dfd7539.png>)

You now have a data source that is **linked** to the file asset and will be updated automatically when you update the file asset.

Now we have to configure which data will be extracted from the file. The asset manager will analyze the file and tries to create a starting point for you to work with. The exact process depends on the type of file: a CSV file already contains tabular data and should result in a faithful representation. The same is true for an Excel file, provided that it also contains tabular data – the asset manager will use the first worksheet it finds, but you can choose which one to use in the **import configuration**, which we will look at next.

### Adjust the Import Configuration

The **import configuration** describes which part of the raw data should be read and how it should be interpreted. When you create a new data source, an initial import configuration will be created automatically as a starting point.

While some parts of the import configuration are the same for all data sources, other parts depend the type of file that is used as source. For instance, an Excel-based data source allows you to choose the worksheet from which to load data. **JSON-based** data sources require more setup and are [explained in a separate article](/docs/asset-management/data-source-asset/json-based-data-sources), but the following general points also hold true for it.

Each import configuration contains a list of **column definitions**, which allow you to describe the columns that you want your data source to have. If the underlying file contains tabular data, then these _can_ be a close match to the columns found in there, but they don’t have to be. You may only be interested in a subset of the data, or may want to interpret it differently – for instance, you can indicate that the texts found in one column are actually URLs or a list of values separated by a specific character.

- Each column must have a unique **name**, which you can freely choose. Keep in mind though that the name must be a valid Hive identifier, since you will use it to access the data in your configurator. This name can be identical to the column name found in the underlying file (if it contains tabular data and column names), but it doesn’t have to be – though it’s usually a good idea to keep the names the same.
- The column **type** indicates what kind of data it holds. The asset manager will try to convert the raw file contents so that they fit the column type and displays an error if a column value cannot be used.
- The **default value** of the column will be used when the underlying file doesn’t contain a value for it (e.g. if an Excel cell is empty).

Other settings of the import configuration depend on the underlying file. For CSV files, you can e.g. choose the character that is used to separate column values. Both CSV- and Excel-based data sources allow you to ignore conversion errors and use the column’s default value instead, e.g. if a Number column contains letters.

You can change the import configuration at any time to alter how data is read and interpreted. Each time you do, the contents of the underlying fille will be read again and interpreted according to the updated import configuration. This process also happens automatically when the underlying file comes from a file asset that has just been updated. If there are any conversion errors, they will be displayed prominently in the asset manager.

### Advanced Topics

#### Linked Asset Columns

There is a convenient way to associate a data source column with other assets by using one of the **LinkedAsset** column types. Let’s say you have a `products` data source: you can link each product with a thumbnail, 3D model, material or PDF document so that you can easily access them in your configurator. To do so, place all assets that can be linked to in an asset folder and create a LinkedAsset column. Configure the column to use your asset folder and optionally select one of the assets as a fallback, which will be used if a linked asset is missing.

The column values in the underlying file must be of type **Text**, specifically they must be the **names** of the assets in your asset folder. When the data source is imported, the asset manager will look for an asset with that name and use the configured fallback asset if none can be found. A hint will be displayed to inform you about the missing asset.

The data source will be **linked** to each folder and fallback asset that is used in a Linked Asset column. If the folder is moved or deleted, it will result in an error to notify you about the compromised data source.

#### Interaction with linked file asset

- There is no limit on how many data sources you can link to a file asset
  - Each data source can only be linked to 1 file asset though.

- If linked, you cannot update the contents of a data source directly; you have to update the file asset instead (which will update all linked data sources).
- You can **copy** a linked data source. The copy will be linked to the same file asset but has an independent import configuration that you can change (e.g. select a different Excel worksheet).
  - When you copy a file asset, any linked data sources will _not_ be copied, nor will the new file asset be linked to any data sources.

- If you **delete** a file asset, all links from it to data sources will be removed. The data sources still function, but cannot be updated until you upload a new file into _each_ data source separately.
  - There is currently no way to re-create a data source link, which is why we do not recommend you delete a file asset with data source links.
  - You **can delete** a data source that is linked to a file asset without affecting the file asset or any other linked data source. Only the deleted data source and its link will be removed.

#### Automation

You can update the contents of data sources automatically, e.g. by loading data from an external service on a fixed schedule, by using a [workflow](/docs/integrations-and-api/workflows/workflow-templates).

---

## JSON-based data sources

A [JSON](https://json.org/) document does not contain tabular data, unlike a CSV or XLS file, which is why data sources based on them work a little different.

You have fine-grained control over which parts of the JSON document end up in your data source by using [JMESPath](https://jmespath.site/) expressions. JMESPath is a powerful tool to select and transform JSON data, but the syntax needs some getting used to.

On this page we demonstrate how to set up a simple data source with JMESPath expressions, followed by some in-depth examples.

:::info[Try it yourself]
You can download the file below to play around with the examples yourself.

Upload it as file assetA file asset can be used to upload any file format. Max file size is 100MB.
in the asset manager and then create a data source based on it. You can then edit the structure of the data source and fill in the JMESPath expressions explained below.
:::

Download: [products.json](data/json-based-data-sources/products-1.json)

### Define a source

Firstly, we have to define which part of our JSON document contains the data that we are interested in.

Depending on the document, that may be fairly obvious – for instance if the document is one large JSON array. However, oftentimes a JSON document may be the output of an API endpoint or an export from an external system and hence contains a lot more information besides what we are interested in.

To create a data source, we need an **array** or **object** and we can select (or create) one from our document with a JMESPath expression. The system will then create a data source row for each item in the array resp. property value of the object (as defined by the column expressions).

Let's look at an example document:

```json
{
  "products": [
    {
      "id": 21,
      "title": "Cucumber"
    },
    {
      "id": 22,
      "title": "Dog Food"
    },
    {
      "id": 23,
      "title": "Eggs"
    }
  ],
  "categories": ["ingredients", "furniture", "pets"]
}
```

Here we are only interested in the products property, which holds an array of objects. The JMESPath expression to get it is fairly simple – it’s just the name of the property:

```plaintext
products
```

This will return the array of objects associated with the `products` property. For each item in the array, a data source row will be created.

### Define columns

Now that we have our source, we must define which parts of it we want to convert into data source columns.

Let’s say each product object from the example above is a bit more complex and looks like this:

```json
{
  "id": 21,
  "title": "Cucumber",
  "description": "Crisp and hydrating cucumbers, ideal for salads, snacks, or as a refreshing side.",
  "category": "groceries",
  "price": 1.49,
  "discountPercentage": 11.44,
  "rating": 4.71,
  "stock": 22,
  "tags": ["vegetables", "onsale"],
  "sku": "6KGF2K6Z",
  "weight": 9,
  "warrantyInformation": "5 year warranty",
  "shippingInformation": "Ships overnight",
  "availabilityStatus": "In Stock",
  "reviews": [
    {
      "rating": 4,
      "comment": "Very satisfied!",
      "date": "2024-05-23T08:56:21.620Z",
      "reviewerName": "Elijah Hill",
      "reviewerEmail": "elijah.hill@x.dummyjson.com"
    },
    {
      "rating": 5,
      "comment": "Fast shipping!",
      "date": "2024-05-23T08:56:21.620Z",
      "reviewerName": "Liam Garcia",
      "reviewerEmail": "liam.garcia@x.dummyjson.com"
    },
    {
      "rating": 4,
      "comment": "Excellent quality!",
      "date": "2024-05-23T08:56:21.620Z",
      "reviewerName": "Ella Cook",
      "reviewerEmail": "ella.cook@x.dummyjson.com"
    }
  ],
  "returnPolicy": "30 days return policy",
  "minimumOrderQuantity": 7,
  "images": ["https://cdn.dummyjson.com/products/images/groceries/Cucumber/1.png"],
  "thumbnail": "https://cdn.dummyjson.com/products/images/groceries/Cucumber/thumbnail.png"
}
```

As you can see, each product contains nested data and we may not be interested in all of it and we have to bring it into a tabular form.

To do so, we create as many column definitions as we need, each one defined by a unique name and type (as with other data sources). The data for each column can come from anywhere in the object, it doesn’t have to be a top-level property.

Here are some examples for column definitions:

- Column: **Id**  
  Type: **Number**  
  Path: `id`  
  Result: `21`
- Column: **Title**  
  Type: **Text**  
  Path: `title`  
  Result: `Cucumber`
- Column: **Reviews**  
  Type: **List\**  
  Path: `reviews[*].comment`  
  Result: `[ "Very satisfied!", "Fast shipping!", "Excellent quality!" ]`

Note how in the last column we are able to pick the `comment` from each object in the `reviews` array and get a single list of strings as a result, which we can store in a `List<Text>` column in our data source.

JMESPath allows us to select and transform data in a myriad of ways – here are a few more advanced examples:

- Get the URL of the first image (or `null` if the `images` array is empty or missing):  
  Path: `images[0]`  
  Result: `https://cdn.dummyjson.com/products/images/groceries/Cucumber/1.png`
- Combine all items in the `tags` array into 1 string:  
  Path: `join(',', tags)`  
  Result: `vegetables,onsale`
- Get the average rating across all reviews of the product:  
  Path: `avg(reviews[*].rating)`  
  Result: `4.333333333333333`

### Advanced Scenarios

In this section we tackle a few more in-depth problems that you may run across in your data sources. We recommend that you familiarize yourself with [JMESPath](https://jmespath.org/) a bit before diving into these samples.

:::info[JMESPath Community Edition]
The [JMESPath Community Edition](https://jmespath.site/) enhances JMESPath with a number of useful features that we will make use of in the examples below. You won’t find information about these features on the official JMESPath website. Both sites are a valuable source of information and examples, but please keep in mind that only the Community Edition contains information about the newer features.

You can try the examples yourself by using the below JSON file for your data source.
:::

Download: [products_options.js](data/json-based-data-sources/products-options.json)

Here is an excerpt from that file so you can get an idea of what we’re dealing with:

```json
{
  "products": {
    "p1": {
      "title": "Snare Boot",
      "productType": "Boots",
      "options": [
        {
          "name": "Color",
          "optionValues": [
            {
              "name": "Black"
            },
            {
              "name": "Blue"
            }
          ]
        }
      ]
    }
  }
} // collapsed for brevity
```

This example showcases 2 common scenarios you may come across:

1.  inside `products` the property names are used as unique keys to identify each product (`“p1"`)
    1.  compare this to the simple example above, where we have an `id` property in each product object, which is easier to access as we’ll soon learn

2.  the `options` array can contain multiple objects which are identified by their `name` property
    1.  this makes the `“Color"` option more difficult to access, as we’ll see

#### Property names as keys

Let’s assume that we want to store the product IDs (`“p1"`, `“p2"` etc.) as an `id` column in our data source. We can use `products` as our source expression, which seems good at first but unfortunately, only the property values inside `products` will be available to our column expressions – the property names will be lost.

- We can use `items(products)` instead, which will turn each property name/value pair into an array `[ <name>, <value> ]` instead
- With that, we can go to our column definitions and use `[0]` to get the property name (`“p1"`) and `[1]` to access the property value (e.g. `[1].title` would yield `“Snare Boot"`)
- While this works, it makes all our column definitions unwieldy, as most will have to start with `[1]`

Fortunately, we can transform the source even more to make our column definitions easier:

```plaintext
map(&merge({id: [0]}, [1]), items(products))
```

Let’s break down what happens in this expression:

- as before, we use `items(products)` to get an array of `[ <name>, <value> ]` arrays
- this array is passed to the `map` function as its 2nd argument. `map` applies an expression to each item of an array, thus transforming it. These function-like expressions start with `&`
- the expression we want to apply to each item is `merge({id: [0]}, [1])` which takes the product object (`[1]`) and merges it with another object that we create in place
- This in-place created object is used to store our property name in an “id” property:  
  `{id : [0]}`

The result of this expression is an array of objects that now contain the product id as an easy-to-access property:

```json
{
  "id": "p1",
  "title": "Snare Boot",
  "productType": "Boots",
  "options": [
    {
      "name": "Color",
      "optionValues": [
        {
          "name": "Black"
        },
        {
          "name": "Blue"
        }
      ]
    }
  ]
}
```

#### Filtering to find objects

Let’s continue the previous example by creating a column definition to hold all colors of a product as a `List<Text>`.

As we outlined in the introduction, the `options` array contains a number of objects that are identified by their `name` property, which makes it more difficult for us to access the `“Color"` object. Let’s look at the final expression again and then break it down:

```plaintext
options[?name=='Color'].optionValues[*].name[]
```

- JMESPath allows us to filter arrays by writing a filter expression: `[? name == ‘Color’]` will return all objects from the array that have a `name` property with the value `“Color"`
- Next we need to access the `optionValues` to get to the actual color names; `optionValues[*].name` will do that for us
- We now get an array of names inside an array as a result: `[["Black", "Blue"]]` (due to how projection and filters work in JMESPath)
- The flatten operator `[]` will collapse these nested arrays into a single array `["Black", "Blue"]` which we can finally use for our column

#### Get all Colors across all Products

You may want to create a data source that contains all possible product colors, e.g. to allow users to filter products by their preferred color. Unfortunately, our source JSON doesn’t list all available colors explicitly. Each product indicates in which colors it is available, but it is our job to combine all these options into a single table.

We can use the filter expression from the previous example, but apply it to all products:

```plaintext
products.*[].options[?name=='Color'].optionValues[][].name
```

As you can see we have to use the flatten operator `[]` several times here – it’s best if you just copy the expression and take it apart yourself to see the individual results and what each subsequent expression does.

While this solves our problem, we do get duplicate color names. If we only want distinct color names in our data source, we have to augment the above expression even further. We can use the `group_by` function to group all our color objects by their `name` (thus eliminating any duplicates) and then use the `keys` function to return only the property names. Again, we recommend you play around with the expression yourself to see the in-between steps

```plaintext
keys(group_by(products.*[].options[?name=='Color'].optionValues[][], &name))
```

#### Create a Permutation / Cross-Join Table

Let’s say we want to create a data source as shown below, where we list each product in each color it is available:

![](<https://docs.combeenation.com/assets/images/image%2874%29-6ba75cd26561973de3a25758cc62dd8a.png>)

One use case for a table such as this is to filter by product title, to end up with all available colors for that product. Note that you would usually want to use a product ID and not a title for something like this, but since the ID isn’t easily accessible in this scenario (as demonstrated in the 1st example), we will use `title` for simplicity. You can of course combine the 1st example with this one to use the product ID instead of the title.

Here is the source expression to arrive at this table:

```plaintext
map(&let $product = @ in options[?name=='Color'].optionValues[*].{ title: $product.title, color: name}[], values(products))[]
```

- We are using the `map` function again so that we can process each product individually
- The key trick in this example is to introduce a **variable** with the `let` expression, which allows us to store the current object `@` in the variable `$product` so that we can use it further on.
- In JMESPath, there is no way to access a ‘parent’ object once we navigated down to e.g. the Color level in an object. We can store such an object in a variable though and thus have access to it at that level.
- The `Color` filter has already been showcased in previous examples, the last noteworthy action here is the in-place creation of a new object which holds the product title and color name: `{ title: $product.title, color: name}`

---

## Tips for translation data sources (i18n)

If you want your configurator to be available in multiple **languages**, we recommend to store **translations** in a data source.

The text content that must be translated is often interwoven with regular product data. If you are free to choose the structure of your data sources, you can take our below recommendations as a starting point.  
In general, you should keep these points in mind when designing a data source:

1.  **Ease of data maintenance**. How much effort is it to add new languages to the data source?
2.  **Ease of configurator maintenance**. What must be done to the configurator to add new texts or languages?
3.  **Performance**. Sending too much data at once can degrade the user experience.

The below recommendations try to strike a balance between these general points.  
We use **Microsoft Excel** in our examples, but the underlying concepts can be transferred to similar file types.

:::info
The term **internationalization**, or i18ni18n is an abbreviation for "internationalization", where 18 is the number of letters between i and n. Internationalization is the process of localizing an application or document for a target audience that varies in culture, region, or language. This encompasses e.g. translating text into a target language.
for short, is commonly used in documents that talk about localizing a configurator.
:::

### Static Text / UI Controls

This is a recommendation for the translation of static text content, as found e.g. in the user controls of your configuraor (labels, button text, tooltips etc.)

- Unless you have a huge amount of texts, we recommend to keep all translations in one file / worksheet.  
  This makes it simpler to e.g. hand that file over to professional translators, who then have all translations available as reference and for additional context.
- Create a **column** for each text that must be translated and a **row** for each language
  - This is the simplest way to access each text in the configurator.
  - All texts of a language will be contained in a single record, which can be connected to UI controls with Signals and Slots
  - Maintaining the data in the worksheet will be a bit cumbersome for longer texts, but the ease of access in the configurator offsets that downside. You can try to split the data among several worksheets to improve ease of maintenance.
- The **first column**, the key column, should identify the language.
- Create a single data source from this file (we'll call ours `StaticTextDataSource` in this example)
- Now you can load just the texts of the desired language in a table component:

  ```hive
  from StaticTextDataSource
  select all
  filter .Language = CurrentLanguage
  ```

- The table will contain just one record, which you can obtain with the `GetFirst()` method.
- Finally, connect the columns of the record with Signals and Slots to your UI controls.

### Product Data

This is a recommendation for the translation of a **variable number** of items, which is usually the case for product data. (e.g. categories, products, parts, …) The [Static Text recommendation](/docs/asset-management/data-source-asset/tips-for-translation-data-sources#static-text--ui-controls) does not work here, as the number of columns would be variable, and you can't use Signals and Slots on columns that may or may not exist.

We assume you have a worksheet that contains arbitrary product data, where each row is a "product" and each a column an attribute of that product. Some columns contain text that must be translated.  
An Excel file will work best here, because we'll create multiple data sources and want to be able to update them all at once.

Here is what we suggest:

- For each text column that must be translated, create one column per language.
  - example: if you have a `Name` column, create a `NameEN`, `NameDE`, `NameFR` etc.
- Upload your Excel document as file asset. Create the following data sources based on that file asset.
- Create a data source for the first language, e.g. `ProductEN`
  - open the import configuration of the data source and remove all columns that belong to different languages
  - rename all translation columns (of your data source) to have a neutral name, e.g. rename `NameEN` to `Name`
- Copy the data source for the next language, e.g. `ProductDE`
  - change each translation column to point to a German column instead, e.g. `Name` should target the `NameDE` column
  - repeat this step for each language. In the end you should have one data source per language.
- In your configurator, create a value component `ProductData` that points to the data source of the current language:

  ```hive
  // if you have many languages, you may want to use a record component instead
  if CurrentLanguage = "de" then ProductDE else ProductEN end
  ```

- Now you can create table components that target the `ProductData` component and thus get your product data in the current language:

  ```sql
  from ProductData
  select all
  filter … // you can use any filter you want
  ```

- When the product data changes, you can update all data sources at once by re-uploading your Excel document in the file asset.
  - you can also add additional worksheets for other product data to the same Excel document. That way you only have to upload one file to update all your data sources at once.
- Adding a new language requires:
  - adding new columns in the worksheet (e.g. `NameXY`, `DescriptionXY`)
  - creating a new `ProductXY` data source for that language
  - selecting the new data source in the `ProductData` value component when the language is "XY"

This pattern makes it easy to import updated data and to process it in the configurator, as all translated texts are stored alongside the general product data. However, maintaining the data in the Excel file can become a challenge if you have to support many languages.

---

## Getting started with assets

Assets are files that you can use when building a configurator. Images are one of the most common assets. Another common kind is the data source, which contains tabular data from e.g. a MS Excel or CSV file.

Typically, assets are imported from files you already have, such as images, documents or 3D models. However, some assets can also be created and edited directly in the asset editor, or imported automatically with [workflows](/docs/integrations-and-api/workflows/workflow-basics).  
When you upload a file, you may be asked what kind of asset you'd like to create with it. Each asset serves a particular purpose: images can be displayed, files downloaded and data source filtered. Other assets are used for 3D visualization and more will be added over time.

### Asset Bundles

Assets are organized into **asset bundles**, which must be [**assigned**](/docs/asset-management/assign-asset-bundles-to-configurators) to a configurator to allow it to use those assets. You can further organize the assets in a bundle with **folders**.

An asset bundle can be assigned to multiple configurators, thus ensuring that the same data is used in all of them. If you have multiple configurators that share a common data set, this is a great way to prevent inconsistencies and simplify maintenance.  
On the other hand, you can also assign multiple asset bundles to a single configurator. This may be useful when you have a lot of assets and want to organize them into separate bundles.

### Versioning

Asset bundles are **versioned**. You control when the changes you make to an asset bundle go live. You can edit the assets of a bundle for as long as you want, without affecting any of your configurators. Only once you **publish** your changes will a new version of your asset bundle be created. You decide which configurators should use that new version, allowing you to update your configurators one by one – or all at once, the choice is yours!  
Of course, you can also **revert** to an **earlier version** of your asset bundle at any time. The **version history** of an asset bundle allows you to assign any past version to your configurator.

Any changes you make to an asset bundle are automatically collected into a **draft**. You can either publish a draft or delete it, if you want to discard those changes.  
You can also **assign** a bundle draft to a configurator draft to test your changes. When you later publish the bundle draft, you can choose to have the configurator draft be published automatically as well. (also works the other way around!)

:::tip
Assign an asset bundle draft to your configurator while you are still working on it. That way, you can make changes to both with the least hassle and keep your version histories tidy.
:::

### Errors and Warnings

Assets within a bundle can have errors or warnings to make you aware of any issues (e.g. missing materials, folders, assets). They are visualized directly in the tree view of the asset manager, simply click on the asset to get more details about them.  
Currently, we have the following types of errors and warnings:

| Icon                                                         | Type    | Name                           | Cause                                                                                                                             |
| ------------------------------------------------------------ | ------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| ![](img/getting-started-with-assets/image-1709632532014.png) | Warning | Missing material               | A [babylon asset](/docs/asset-management/3d-and-material-assets/basic-workflow) is linked to a material which is not existing.    |
| ![](img/getting-started-with-assets/image-1709632532014.png) | Warning | Missing texture image          | The given texture of a material asset is linked to an image which is not existing.                                                |
| ![](img/getting-started-with-assets/image-1709632568382.png) | Error   | Missing linked folder          | This [data source](/docs/asset-management/data-source-asset/basics) contains a column with a linked folder which is not existing. |
| ![](img/getting-started-with-assets/image-1709632568382.png) | Error   | Missing linked default asset   | This data source contains a column with a linked asset (i.e. default value) which is not existing.                                |
| ![](img/getting-started-with-assets/image-1709632568382.png) | Error   | Invalid data source value      | A value of a column in a data source cannot be read.                                                                              |
| ![](img/getting-started-with-assets/image-1709632568382.png) | Error   | Invalid data source list value | An item of a list column in a data source cannot be read.                                                                         |
| ![](img/getting-started-with-assets/image-1709632568382.png) | Error   | Empty data source list value   | An item of a list column in a data source is empty.                                                                               |

:::warning
Errors prevent you to publish an asset bundle (and potentially break a configurator) to improve stability and robustness.
:::

---

## PDF asset

A PDF asset can be used to build PDFs based on HTML Liquid templates. [Liquid](https://shopify.github.io/liquid/) is an open-source template language created by Shopify.

### How it works

You define the PDF structure with the template code, which is HTML + Liquid.  
Liquid makes it possible to access data from the context. The context is represented by a JSON object and can contain data from a configuration.

The template code and the context together result in the **final HTML**, which will be converted to a PDF by choosen [technology](#the-tech-under-the-hood).

![image.png](<https://docs.combeenation.com/assets/images/image%2880%29-a4f65fdab421038daee2ee8a96a0242a.png>)

:::warning
Textual data which is injected via the context is HTML encoded by default. This means if you want to inject `HTML` or `SVG` into the PDF asset, then you have to disable this encoding.  
For this, simply use the `raw` filter (e.g. `{{ svg | raw }}` or use a `{% raw %} ... {% endraw %}` section as described [here](https://shopify.dev/docs/api/liquid/tags#raw).
:::

### The tech under the hood

We currently offer two technologies to generate a PDF from the generated HTML (can be changed in the PDF asset settings tab).

#### Headless browser

In this approach, a headless browser is started which loads the HTML and creates the PDF.

**➕ Pros**

- What you see is what you get - the output matches the preview with no surprises
- Uses standard web CSS - no special syntax required
- Fast rendering for simple to medium complexity documents
- Easy to debug using browser developer tools
- Supports modern web layouts and flexbox/grid

**➖ Cons**

- Limited support for advanced print-specific features
- No CMYK color profile or PDF/A compliance support
- Headers and footers have limitations (no page breaks, limited styling)
- Resource URLs in header & footer must be base64 encoded (see warning below)
- Less control over pagination and print layout

:::warning
Resource URLs (e.g. images, fonts, ...) in header & footer won't be resolved by Puppeteer. They need to be embedded via base64 encoding. For more information, see [`data_uri` filter](/docs/asset-management/pdf-asset#filters).
:::

#### Prince XML

With this approach, we use the [PrinceXML](https://www.princexml.com/doc/intro-userguide/) library to convert the generated HTML to a PDF.

**➕ Pros**

- Professional print features including CMYK color profiles, bleed margins, and crop marks
- Advanced CSS Paged Media support for precise pagination control
- PDF/A compliance for archival-quality documents
- Superior handling of complex multi-page layouts
- Extensive control over PDF metadata and document properties
- Better for print-ready, production-quality output

**➖ Cons**

- Requires knowledge of print-specific CSS
- The live preview might not accurately reflect the final PDF output
- You must generate the PDF after making changes to see the actual result
- Some CSS features may render differently than in browsers
- Requires understanding of PrinceXML-specific syntax for advanced features

### How to create a PDF asset

1.  Got to the asset manager
2.  Click on the (+) button to create a new PDF asset  
    ![new-pdf-asset.png](<https://docs.combeenation.com/assets/images/new-pdf-asset%281%29-6671f7d5df2b0c3244766273cb7610aa.png>)
3.  Select a name, folder, template and click on `Create asset`.

### Template language: Liquid

If you want to inject flexible data into your HTML sections, then simply use the context in combination with several Liquid statements.
The most common ones are described in this documentation, for more details visit the official [liquid documentation](https://shopify.github.io/liquid/basics/introduction/).

#### Objects

For example, if you define the following Context with a `company` object and a `name` property, then you can inject this data into
your HTML section as described here.

![image.png](<https://docs.combeenation.com/assets/images/image%2881%29-3e272f8f71afe8b197916a5082b45d31.png>)

**Context**

```json
{
  "company": {
    "name": "Acme Solutions Ltd."
  }
}
```

**Input**

`{{ company.name }}`

**Output**

Acme Solutions Ltd.

#### For-loops

In addition, it's possible to iterate over a list of objects using for-loops.

**Context**

```json
{
  "lineItems": [
    {
      "position": 1,
      "description": "Service A description",
      "price": "40,00 €"
    },
    {
      "position": 2,
      "description": "Service B description",
      "price": "25,00 €"
    }
  ]
}
```

**Input**

```html
<table class="main-table">
  <thead>
    <tr>
      <th class="pos-column">Pos.</th>
      <th>Description</th>
      <th class="price-column">Price</th>
    </tr>
  </thead>
  <tbody>
    {% for item in lineItems %}
    <tr>
      <td>{{ item.position }}</td>
      <td>{{ item.description }}</td>
      <td class="price-column">{{ item.price }}</td>
    </tr>
    {% endfor %}
  </tbody>
</table>
```

**Output**

| Pos. | Description           | Price   |
| ---- | --------------------- | ------- |
| 1    | Service A description | 40,00 € |
| 2    | Service B description | 25,00 € |

#### Filters

##### Built-in Liquid filters

For the official filters, check out the [Liquid documentation](https://shopify.github.io/liquid/).

###### Math

:::warning
**Important:** When using `divided_by`, ensure you're using the correct data type.
The `divided_by` filter produces a result of the same type as the divisor.
If you divide by an integer, the result will be an integer. If you divide by a float (a number with a decimal), the result will be a float.
:::

**Example:**

```liquid
{% assign netTotalPriceFloat = netTotalPrice | times: 1.0  %}
{% assign sumDiscountPercentage = 100.0 | divided_by: netTotalPriceFloat | times: sumDiscounts | round: 2 %}
```

###### Date and time

:::warning
Unfortunately, the `date` filter works differently and the `time_zone` filter does not exist at all in the live preview.
Please always check the resulting PDF to verify the correct time zone is applied.
:::

If you have a string-based date, then you can use the `date` filter to format it.
For example:

```liquid
{{ "2024-06-15 13:41:36 +02:00" | date: "%d.%m.%Y" }}   // Result: "15.06.2024"
```

UNIX timestamps represent a point in time in UTC.
To display a UNIX timestamp in a specific time zone, use the `time_zone` filter and then format the result with the `date` filter.

:::info
**Important:** To ensure a correct time zone, please always provide it directly with the string as shown in the above example or use a
UNIX timestamp with a `time_zone` filter.

The recommended pattern is:
**UNIX timestamp (UTC) → time_zone → date**
:::

For example:

`{{ Timestamp | time_zone: 'Europe/Vienna' | date: '%Y-%m-%d %H:%M:%S' }}`

The Timestamp with `1784288496` results in `2026-07-17 13:41:36`, because Europe/Vienna (CEST) is +02:00 ahead of UTC.

:::warning
The date filter determines how the timestamp is displayed. When **no format is specified**, the result is displayed using the
default **ISO 8601 format** which is always shown as UTC time, regardless of the time zone you have specified.
:::

For example:

`{{ 1784288496 | time_zone: 'Europe/Vienna' | date }}`

produces an `ISO 8601` value:

`2026-07-17 11:41:36Z`

To display the date and time in a specific format with a given time zone, then **always** provide the format explicitly:

`{{ 1784288496 | time_zone: 'Europe/Vienna' | date: '%Y-%m-%d %H:%M:%S' }}`

which results in:

`2026-07-17 13:41:36`

##### Combeenation filters

We extended the Liquid template language with custom filters for Combeenation-specific functionality.

The following filter can be used in combination with Assets:

- `url` ... to retrieve the URL of an image, text or file asset

To directly embed images or fonts into the header/footer:

- `data_uri` ... to retrieve the base64 encoded data of a URL  
  We support the following media types:
  - Images: Png, Gif, Jpg, Svg, Bmp, Webp, Ktx2
  - Fonts: Ttf, Woff, Woff2

For a PDF (e.g. quote) which contains several prices, the following custom filter can be used:

- `money` ... to convert any number to a formatted price  
  The money filter accepts several parameters which controls the formatted output.

```liquid
{{ discount.adjustment.price | money:"de-de", "EUR", "symbol" }}   // 4.711,02 €
```

Plain text

- `"de-de"` ... the locale which affects the formatting of the resulting price
- `"EUR"` ... optional currency code according to [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)
- `"symbol"` ... is an optional parameter to decide if a currency symbol or code should be used,  
  possible values: `"symbol"`, `"code"`; default: `"code"`

It's of course also possible to use context parameters, for example `currency` from the context object instead of `"EUR"`.

##### Asset access

Two recommended ways to access the image asset in your template code:

- Direct access (blue arrow): Use the full asset path as a string (e.g. `folderName.assetName`.) before the above mentioned filter
- Context-based injection (green arrow): Pass the full asset path via the context. This is preferred when the asset is dynamic and selected during the configuration process

![image.png](<https://docs.combeenation.com/assets/images/image%2882%29-b130ffd740d3fd8424a245995ea203ad.png>)

If the given asset is not valid or is missing, then a corresponding asset error is shown.

**Asset**  
There must be one asset named `logo`.

**Context**

```json
{
  "company": {
    "logo": "MyFolder.Logo"
  }
}
```

**Input**

```html
<img src="{{ company.logo | url }}" style="height: 2cm" /> <img src="{{ company.logo | url | data_uri }}" style="height: 2cm" />
```

**HTML Output**

```html
<img src="https://cbnpeuwstassets.blob.core.windows.net/public/COMBEENATION/0Dxez2x2M09.png" style="height: 2cm" />
<img
  src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAfQAAACOCAYAAADHGPqZAAAEtmlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNS41LjAiPgogPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgeG1sbnM6dGlmZj0iaHR0cDovL25zLmFkb2JlLmNvbS90aWZmLzEuMC8iCiAgICB4bWxuczpleGlmPSJodHRwOi8vbnMuYWRvYmUuY29tL2V4aWYvMS4wLyIKICAgIHhtbG5zOnBob3Rvc2hvcD0iaHR0cDovL25zLmFkb2JlLmNvbS9waG90b3Nob3AvMS4wLyIKICAgIHhtbG5zOnhtcD0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wLyIKICAgIHhtbG5zOnhtcE1NPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvbW0vIgogICAgeG1sbnM6c3RFdnQ9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZUV2ZW50IyIKICAgdGlmZjpJbWFnZUxlbmd0aD0iMTQyIgogICB0aWZmOkltYWdlV2lkdGg9IjUwMCIKICAgdGlmZjpSZXNvbHV0aW9uVW5pdD0iMiIKICAgdGlmZjpYUmVzb2x1dGlvbj0iMzAwLzEiCiAgIHRpZmY6WVJlc29sdXRpb249IjMwMC8xIgogICBleGlmOlBpeGVsWERpbWVuc2lvbj0iNTAwIgogICBleGlmOlBpeGVsWURpbWVuc2lvbj0iMTQyIgogICBleGlmOkNvbG9yU3BhY2U9IjEiCiAgIHBob3Rvc2hvcDpDb2xvck1vZGU9IjMiCiAgIHBob3Rvc2hvcDpJQ0NQcm9maWxlPSJzUkdCIElFQzYxOTY2LTIuMSIKICAgeG1wOk1vZGlmeURhdGU9IjIwMjQtMDQtMDRUMTY6MTI6MTIrMDI6MDAiCiAgIHhtcDpNZXRhZGF0YURhdGU9IjIwMjQtMDQtMDRUMTY6MTI6MTIrMDI6MDAiPgogICA8eG1wTU06SGlzdG9yeT4KICAgIDxyZGY6U2VxPgogICAgIDxyZGY6bGkKICAgICAgc3RFdnQ6YWN0aW9uPSJwcm9kdWNlZCIKICAgICAgc3RFdnQ6c29mdHdhcmVBZ2VudD0iQWZmaW5pdHkgUGhvdG8gMS4xMC42IgogICAgICBzdEV2dDp3aGVuPSIyMDI0LTA0LTA0VDE2OjEyOjEyKzAyOjAwIi8+CiAgICA8L3JkZjpTZXE+CiAgIDwveG1wTU06SGlzdG9yeT4KICA8L3JkZjpEZXNjcmlwdGlvbj4KIDwvcmRmOlJERj4KPC94OnhtcG1ldGE+Cjw/eHBhY2tldCBlbmQ9InIiPz7lCWFcAAABgWlDQ1BzUkdCIElFQzYxOTY2LTIuMQAAKJF1kc8rw2Ecx1+GyDDFwcFhaZw2zWhxcZgYhcNMGS7bd7/Ufnz7fifJVbmuKHHx68BfwFU5K0Wk5LwzcWF9fb7bakv2PD3P5/W8n8/n0+f5PGAJppS03uSGdCanBfw++3Joxd5SoElmJ1ZGw4quzi9OB6k7vp5oMO2Dy8xV3+/fYY3GdAUaWoUnFFXLCc8Iz23mVJP3hXuUZDgqfCns1KRA4UdTj5S5YHKizD8ma8HAJFi6hO2JGo7UsJLU0sLychzp1IZSqcd8SXsss7Qotl9WHzoB/PiwM8sUk3gZZlx2Ly48DMmJOvHuUvwCWYlVZFfZQmOdBElyOEXdkOwxsXHRYzJTbJn9/9tXPT7iKWdv90Hzm2F8DEDLHhTzhvF9ahjFM2h8hZtMNT57AmOfouermuMYbDtwdVvVIgdwvQu9L2pYC5ekRlmWeBzeL6AjBN330LZa7lnlnvNnCG7LV93B4REMir9t7RdTHGfdYF9jwgAAAAlwSFlzAAAuIwAALiMBeKU/dgAAIABJREFUeJztnXmcXeP9x98z2fdEJIKIIRRFiNrXY6eKsdZWPfSHoq2lNKpa1L7vanfsO2lrV5zUTqh9KZGxJJZEFrJOJjO/Pz7ndM6cu8xdzt0m3/frdV/kzr3nee5Znu/z3euoNI5XBwwCNgNOBw7Gd9+v7KQMwzAMo7aor+jojrcUsA9wE3AP8BPgBByvX0XnZRiGYRg1Rl1FRnW8PsDOwGHABsDQyF+nAIcCLwHD8d1J5Z+gYRiGYdQW5dfQHW9V4O9II9+JjsIcYHng52iz8X843rrlnaBhGIZh1B7l0dBlQl8X+CVwCNC9k2/MAnYHvgUuBy4CnsJ3W0s5TcMwDMOoVUor0B2vJwp2+zkysa+Qx5hPAXsBpwC7AmcDd5pQNwzDMIxUSiPQFbm+GnASsD0wgvzN+y3Ar4APgFuAZYFzgYvx3UXJTdYwDMMwap9kBbrj9QCWBn4D/BYYUOQRJyEN/0TgOGABcA5wKb47p8hjG4ZhGEaXIRmBLo18bWQaPwQYnchxJcBPQ0F0TyKT/TzgSuACfHd6QuMYhmEYRk1TvEB3vFWQafynwOpAz6KP2ZGJwMHAVsDfgvcWAeOBcfju5ITHMwzDMIyao3CB7njdgAOBM1CqWbeE5hSnFfniLwMmABtH3n8WOMJy1Q3DMIwlnWLy0NtQ+tkISifMQXM8CuWrnwfMiby/LXATjrdmYPY3DMMwjCWSwgVx0/g2GhpBpvDhSU0oA4OBvsDtyKy/Ou3WhRWBLYDPaWj8lKbxbSWei2EYhmFUHcVWivsIeBtp66XGRalwdwEzYn9bG7gC2A/H66xojWEYhmF0OYoT6L47D0WfL0xkNtnpA4xDBWdeT/P3lYCrgL1xvMo2nTEMwzCMMpOE4HsC+C6B4+TC+shvfiYwN83fBwE3AsfgeEPKNCfDMAzDqDjFB7M1jZ9DQ+No1DWt1PRFc74FCe8N03ymB/Lr96Oh8S2axlsBGsMwDKPLk5Rp+jLK40evA3ZBm4dzgc8yfK43iow/H8crtlqdYRiGYVQ9yaV6Od4zwNaJHS87LwM7oBKzfyV797bHUd/1KfiuRcAbhmEYXZIkg8duAxYneLxsbIxasf4DeKeTz+4E3AlsHBTDMQzDMIwuR5IC/SXg0wSP1xm/RxuI+1Ap2GxsiiLgNy/1pAzDMAyjEiQp0KcAzyd4vM5YATWCuRaY1slnuwFjgfE4XrpAOsMwDMOoaZIT6L77A/Ac8ENix8xONxQgtxLKT8+lR/pg4Fkcz8Xx+pdycoZhGIZRTpIuwPIC8EXCx8zGasBewEPA0zl+py+qCf8bHK9vqSZWU4R18B2vAcf7LY63ktXGNwzDqC2SXbQVdHYDKtNaLqYBGwENSLAPyvF7c4CbgOPx3XIF81UPjtcb5euvC3jIevEgOo+TgauB6/DdlgrN0DAMw8iD5LUwx9sBpYqVU8O7G6WwXYR6p+cz9l3A74Dvumxam7TtXkB/5KI4ENgTWADsinrY34Qq8UV5F/gj8G989/uyzdcwDMPIm1II9F7AW8gcXi4WI396HRJMy+bx3UXAeODP+O5HJZhb5ZBLYRXgx8iKEWrkrSiA8WhUhOciYEvS3w9z0QbtdiTY441xDMMwjCog+bzspvGLaWisB3ZO/NiZqUd92W9AGug6eXy3G/AjYAwNjS/SNL5rCCzHWwE4DTgOWS22on2j82/gWOA9YBgqzNMEzETCvi/txXp6og3BDsC6NDTOoaHxM5rGL3luCsMwjCqmNGZxNUaZBJSzQcr3yHT+EvA++W9W2lCTmZ3x3YkJz628KJbhN8CFpFbR+wDYHpiK77YF5vj62Ks3sDKwFmpNG/53BLJoPAYch+82lfy3GIZhGDlRKoHeE7geaYbl5HHgV8iUfBKFRfFPQtrrE/huLqlw1YfjrYHazC4feXcRMAHYD98trDue4w0GRgOrIm3/aeBdfLe1qPkahmEYRVMqgV4H7AZcBwwvyRjpmYeasjyOBNraBR5nEnA24NWcsHK8QcD9wHaRdxehMrnj8N1JFZmXYRiGUVKSzkMXihZ/CmnL5Qw064uKzPwAXAM0F3ic0cAFwCk4Xo+E5lZ6tJE6Btgm9pcngOMpb2lewzAMo4wknYdeh/yv+6G66WeiPPFLgQOCv5Ujne0vqCGLR3H125uBS4Czgkp41Y3jbQ7cAYwK3lmMNlZ74LsLKjYvwzAMo+QkF+UuTXZ9VIXtZFQ7fWtgBoo+fwdYDhhJ6YX6GCTQ5wZzyNZeNRvdgPWAQTQ0vk7T+HkJzS95HG8ocCpqRFOH3A93A4fju3MqOTXDMAyj9CQj0BUEdxRwBrAF7ab8ZVC6UwOKjH4ARaOvjbT1UtEbRa3fCDh0DA7Llx5IqK9OQ+NEmsbPLH56JaCh8QAU5d8baea3AKfiu99WdF6GYRhGWSheU3a8lVDHsy3ILKRbUY33vyCtcQvgMmDNosfPzGQUZd8HeDKB47UBrwC/wnffT+B4yeF4y6BiPssE79wEHGOauWEYxpJD4Rq64/WjoXF35KfegOxm7TpUK7wR5Tf/E1UeG4LaoPYpeB6ZGYLMzjegwihrFHm8OuQu+AkNjW/S0Pg1TeOLPGQCOF4/dC7HIhfDtcBR+G6hAYGGYRhGDZK/hq7AtzWBw4FfIEGdL+8CVwH3IpP8kcAmyLydJNOBnyEXwAPkVxI2G++iOIFHK9rYxfG6A0cAFwMLUUOV8/Dd6nQLGIZhGCUjPw1dvvJ9UUrXbhSuWQ9H0efrIhP8/SiifBOSTaXrC6wIXIkC8tYnmYC84aj2+WwaGt+haXxlctUbGtdBcQvLoWDEi0yYG4ZhLJnkLtwUxX4OCrxKUpOeheqN34lqsN+FzPJJRsLvC3wN3IoC9JLie+D3qABNeduMqv3pRUhDPxnfPb+s4xuGYRhVRefasOP1C1qiPoeEV9Jm8cHIVHw10tK3D/4/yejsE1HzkUcTPCbAQJRjf1xQv76cbI/cCSejXHnDMAxjCSa7yd3xhiFheCrFB5VlI0wN2xKYg6K0X0fNQFakeG19MDAFaf/7I1N8UvREqXGDaWh8m6bxpe8b7nijgb+hanjX47vzSz6mYRiGUdVkFuiOtxHyb+9O+bqmDUNCfTWUR30PCvYaiwRnofRE2vT9wFck39q1G3IXrEhD43M0jZ+b8PHbURzDJagi3C34bunGMgzDMGqGVM3X8ZYCfol6aQ8s83yiTEd1yR9FQv5C5P8u1OTfilqK3oDyyccWP8W0PAm4wNdBTfvkcLx6YEegHt99JNFjG4ZhGDVNu0BXD+2Ngd8irbyUldxypRlZCa4GpqLguZ+jqO5C+BgVtdkJuAIYkMAc0/EqcALwYqJpbY7XF+XCf4bvLkzz937Aj4A++O6LiY1rGIZhVD0yuavP9W9RM5UtKLz2edJ0A9ZCGnozcDnwHxQFP7KA4w1FG5VbkM9+lWSmmcJyqNjOZBoaP6VpfDKaekPjYmBmSp92x2ugofFA1FHtcGBZmsZXQdUbwzAMo1zU4XjDgeuBXUiyWUvytAI+8GtURvavSGPPd/PRDGyGqsddSem0dIDvgH3w3WcTP7KKyuwMHI2C8nrQnrXwAAr+I0X4G4ZhGF2SOhzvOuTzrZW+358gS8KjyEVwErAhuQv2NhRQdiIy529VgjlGmY989/cV1YK13dy+OnIZ7E5m18NDwB9QZsJTqOPcRHx3WsHjVwtyDfVFlpZwA9qCzvN8fLcyRX4MwzAqTB2ONwoVKNmd2hHq84HxKHVrOnAQ8H+oglsuTAEOQ7XPH6c0teSjzELlWa/Ad2fl/C0Jr1VRS9SNUaW71el8vv9APvyzgD+jkrc7A5fju1PynXzFcbz+KItgbWAl1IRmEO336wJgNvAN8CnwHvAevlv6FMIlCQVlro9KP4fxN/OA+8teWMkwjBTqgtrsYXnUXSo8n3xoQx3VrkCR6z9BAizsB56NVlSZ7reoZOrhpZvm/5iDGtkc06kWqSI1O6EKd2NQOl8+roFHgGNRZbwPkHC/GFgaOKAoS0E5cbw+aLN2MBLkg9FmJlNBpFa0SZsNfIk2Njd0CctENaCgywuAA2l/xlqA0VZy2DAqTzTKfSgSBBuQbD31cvAYMmvPRS1aDwb6d/KdBaja2jfIN19o5Hy+/B34FTDjf2ltyi3vh/LvfwXsgQL4CuVxtFm5FWn2m6AiPdehCny7oUj56jRPO14vNO+rUaxDMcxHKY/XolTCyjXTqXUcbwBqqvSL2F+Wxne/q8CMDMOI0C649UDujPyvtdZ6c2fgX8BewOlIq5uAhHYmeiONfgaKei9X8NhuwM3AmjheHY63Mmqw8izwEnIdFCPMQb7l1uBVh8zur6PyvWsi68SmgUm/ulCQ5smoxW6xwhyk0f8JxVwcguNVsraCYRhGyegYSOa7M3G83yPhtnfK36ublYCzkdZ9LnAIKpBzLPK3pmNz9DvvQ73aS1neNqQObUAGoUY3c5BffK0Ex+iGXBIhmyBXxCUoVmJDpGmdgILmqgNF7v8VmXSzWVhmoYp/c9GmdCCKE+iX4fP1yHVxETrPxyY0Y8MwikEb7Ggl0rnAd3kX5VLQ8LDIO/OD4yxRFrlU07rvfoYqtCWfalV6BiGB9TgyW1+EIrzfyfD5etRw5jtkCi8X3VG+/+PAUsBRJNs4ph4J9NCkPgQV5PkEWSNCAfcAjrdnguMWy7nI5ZBOmDcjs/lWqH7AxujaOih+YmVgW9Qs55sMxx9I5nvBMIzycy/wVuT1AIXVBzkrdpzHUSDtEkV6Ddx3v8Xx9kXpXdtRXB31clOHgqfOBTZCF3o7YBzS/JaJfX4F5BP8G9Lq438v5TxHoMCto5Cp/TJkki+2eUx3JNDDXW4dslxsiMzPP0Ua7QDgpqAJz2347rwixy0MBWbujjZXcWaiGvx/wXe/znKU74FngGdwvHHAnuicboAEeSvwIL57Y5JTNwyjKMKMlZClKCzraETsOEMLPE5Nkzn4TelVh6IdVGqZ0eqnB4oSfwAJ8itR7/CnUGRuSG/ke++PhH65TTQjkCl8D3S+L0YWg2IITe5Rs9UAVIhnNtq8hOdgEDJzHxv0vK8EyyGrUJyZyP9/fCfCvCO+24zv3o2u/7HAi8CbaHNnGIbRJeksmv1b4I8o57s6I6I7ZxVUiOYKVGHuEBQJPz3ymbWRUL+byrgaVkT+/z8hgX4G0jgLJTS5x/1QW6AKcuOBdyPvD0cFeq4OUpPKzZbAumnePw+4Ed+dU9BRfXcGvnsz2tDtj/LTDcMwuiTZBbrvtuG7XyLT5QRqV6j3RTn2E1BA2sVIgH+ENPLuSEPsi7TlSrQkXQoJ9DOBG1GJ22xR+tlIp6GDfucFKKDsYTpG9g9A1/nGIIWxPGgDsSVyk0R5CTgf3y30HLTju0347n+tDK5hdFk+R+t2+JqOAo6XKHLLN5eGtBvqT178Als5+qNc7NuRydlBQVRfIIF6CTLNPkblNi+Horzp55Af+P0C5pJJoIMC5I5CqWtNaf6+J3AFjleqxjVxBqHqY1GagbMTbz9rGEZX5SS0toWvDfHdtyo7pfKTe1qa787B8U5A/vQDqK1AuSh1SGitjQqvnAc8jfzL+yNBdwewDRLy5aY3cguMQPXmjw7muAGdV8ALySbQ69HvH49S1y6N/T2MPRiO4x2P776d7w/Ik4GooE6Uj1FXvepA+fojUABPf3QOlRYDU/Dd+QmPV4fuvTDQpyeyJIUV8GbmtNnRcYahAMiB6L6YD0wDpiZi/Ug/bi8UbLo0CkxahOIhvsR3Z5dkTI3bE/3W4SiFsRX4AbVenlayQkoadwV0rnujazULXatZiW9MNd5wFPjVn/b7Yx7STKeUxBqlcUdExu2Gru1sVE47+d+aKxo3md+sWKLofQQdn5vkY8r0zITXtB/t1zS0NkzJpbxyrgIiOvDSwDXIZF3rLAQmosCpT1EJ2J8AR6LiLz+r3NRoA95GjXPmouC+tXP87nsoqv2W4L9xWoDTUDva50if3tGGBOuh+O4Lecw7PxxvW1QUKMo9wBElXfxzwfHWQLUMdkALWdjRrg4JixZk1nsNxV88VXCmgOP1Rq6Hn6KaAcsF43WjPSZiMbpnP0TBqvel7Q0gl8kvUW2FldHi0C0271no2t8OPJ9Tvm62SnESJtui9MjNkPuqe2TuLcjy8kEw94cSqS6nTcv6wZy2DuYSjgs6Z83IGvUPwMN3v01g3O7oeh2ELH3x3xteq49Qlsb9+O70tMfqfKxuwFiUrRN2iuwTjBde1zBNtQVdixfRmvFwwXX2dW6XQ+7KHdA60Z/23xmOuxgJvA/Qb70z5+fA8f5Dx/iZT4BTgP9m+MYC4JM0LaS3CuYYyrQv0POR2znXb90A3UcOqfdRuGGYBbyAnvcJBW+ctGlYHz0zmyKlpi+6numu6VzgeVQz5Sl8N23xt/wFuibTFy0Eu1C7mnqUr5CAuw8t3IvQLulFik8hK5Y3UVnbd4C70A3Qq5PvfIAsDLegmzwdHwM7ok3CvVmO+SEqI/tMSTQcxzsIuC327qXAyYlrvrnNpzewHupWtxu5PyNtyD1yNvA4vjsjh7GGoKDNg5AgzDdlcnIw3gPogV8FNR06gtxTdlpQ6eMzgJczLRTBfDMJ9FPQBmLV3KfOFFQn4k4K0Z7bywP/kY4LeWcsQBkv1wKfFjDuQBRceipakHMddwpy6d0OfJtVk5VwGQqMRtayvYFRec2znc+Ac4AHgemdatBqwDMYCe+jUcxRvmvgN6hi5z2dPgepAr0z2oBN8d2XY8e5A1mOQz4DDuxUGZEs2xzdR04e82hF1TfPQmtj9v4YOq9D0TO6P8pqWp7CZPBH6Ll/mJi1rrCa7dp9HYpM1nPQDm1REa9mtJst5LWgiNe84DUImbUvQabJpsD/chXpzdblZF20+GyNAuVuQbvhbMTz0NOxKvKlP4+KMGRidWSR+XmglSRNuqj6uZQ/fTAUWH9AG7vdye9hq0NldW8BrsPxNgwe4kxjDUR1B55BFQMLqX+wEqp3f3Uw74dQcGc++bfdkeZ3P/AHHK8QN9OZ5CfMQYvZxWiT6uR1b8kCcTKy5OxIftepN3A82kg0BsIz13FXQvUt7iE/Fxjo914YfHfrTn7vMPTMPRvMtVBhDsqguQy4Hm1UM6NzsSVabx5FVthCFJpl0GbtchxvhQK+n4060iuR8Wet82vjeMuilN07yU+Yh+NtEHz3EhyvszLVo9A1nYAUpJE5zTE9q6HreS0qEPY/Cl+gfXcWjncy8jf3pPggsmIEZ6HfTfe96bT/lvOReWU4uknTvQZS+mY2a6KLdya6AaehBS3TDZHNhx7lcGQ6uguZ8pbO8LnRKO1vGqnm8WJJd+5ymXuySJhfhwR5MQUpuqPd9wpIUL+S4XNDkWbZWROhzugB7Ic2xcVYy4ahnP+hON6pZWw9uxWyih2FLAXZkTC/BFk0Cv294WJ8FdrM35zDuP3RM7AdnVvIsrElcnX9Dsd7NoPGvCyyAiRVGKUXsCvQgOPth+9+mOFz9cgasBeFC5uQPui+XAbH27fquvFpo3EtckkWo6j0RdUtG3C84/DdTJUoV0CFvZKq9dGTcJ1xvL2DbLQia7WrLaVf9NSqFd+djuM9ArSl9TFqR9sf7b5WBBrSvJam+IcDtHk4F13I01GaxlWkv4aZ8tDjDEQbhP1REFo6f3vI00ib7HrIR3kOWoDS8QUyWT4f/P8idF3XQw/V+nTcmNSjh/cCHG+XDOa4OtLfF23IXPgU2gx8ioKOuqON1U5owY1bNtIJtyZU0vgFdL8sRpvTzZApd3RsDj2Ryf4dHM8rwMWyGMWkjAdeRedqITpXayEX3Z50vGfrUQ+Fm3C8tbL6XuV3PA5dp/jCGMZ83B/83m+CzzSgc7YbHWuGgzYSZ+F4k/Ddf2cZtw5tejO1l34Lad6vI4Wgd/Cbdg2+E/29oSXnQuQ+y1fQTQdeRnEbH6GAvznoty6P7sW9SA00rUdm9H/geOun3bD57mIc7z50jZaN/bUFWQwmoBoWXwXvDUI+/T3QZiV6XbqhDdDpaHObFMUFv2lzdja6L+LPYHgfPYRSZ6cG7w1Hm8C90PWLKyLbAqfgeL8uYPMyDbl3J6JrGvap6Ik0+Y3Q87pi7Hvdgr89ElzTRbXUfKW8SGPbAT2sV+F4Y9Aike41jfbgqH8jk3j4akM3fVTLHxH5/7DUYfjqHft3dKHuhwRwX2S+WYx8eXGzVq4aOuiG2AppH1uTukFYgEzQh1Vtu9Vi0GL9U7SIxXkb+VvvziCUn8TxzkOL6Dh0v0T71m8BjMPx/pxj9G8ruh5vZ/BlvwrcheP9CWnT+6FNWZQ56B68Bng6g4B8FMc7E2m5JyLhEy5s/VBQ6JMoSjsXmlDr5RuAd9Jsfj8H3gBuxfGWQ+6BA+loEVoJuBnHOzhLFPGGwfeiQqMNBYGeDzyQ5ve+DNyN441Eps5DY+OOAI7E8d5N6+/V/XEwqcK8BW3wzgOeSHN9X0Q1HRqQf3ZvOmbNjAX+iOONy/HemIncC+90kp3wEI53avDZ45EpOSp8VkJVIc/OECz3CrqOf0Br20soRuOxLAWensXxrkHBXaejdSTKz3C82/HdV7P9wIBPg2N8kuHvC+lYFCs/5AbbDV3PqDBvRQL1IhRImOm5OQud03FoYxy1ouyBnptcy0t/jJ7B97LErryCem6MQ0Gux6FmW9F1egxwDI53sQn0dOiiH412lfujG/wO9PCnI0yP+T7Na3bw3xnBayYS/OH//4AWpf5ocQ5fgyL/HYIWg/AVBmvdHBz/Qjru3vIR6ENQMMnxKAo4Ktha0E71TyVJ1agOBgL7kHptX0LBiP/JuuDqb6/heEeghftIOvodf4f8bO/nMJc2fHdip5/y3S9xvOPRvfMbOpqAJwP7dRqko4BDD8f7L/LBRzMdxiKBkOvCdCSKvO087sF3p+J4pyArxJl0PFd7oM3lkxm+vS/SuKO8CByZxdQZjvtlsBF6G5nsw85cdUiLHEN6a+MySKDHNbkJwNH47kedjNsUdLD8Am2eohuwI9DakimiO8o8fPe1HD5HIKgfwfE+RHEKu0X+2h1l79yddlzfXRAI5+/RJuzlnCLWde2fw/H+D1krorUllge2xfHeyCHifh7wZgnTZfugTV3UWtOGLFm/x3cnZ/225v8vHO8dFEh6MO3PXw+0Sbs/xwydafhubum5vtuG441HAc+Xk2pN3Qe4v9S+31rFQQJ9GeRn/jcSbJmoR4J3BWSO2QQtiPug6mvHoXKzF6A66rejG+hfaJf/FNKojgm+NwqZXCYGnz0DCdzD0AZjTxR89W0wr5+hm/REpDHciYTxbDqPbagPxhwTjB9Ng5qAWqzmqqnVIsuQanr7BjgG330j57xapWCdi8yuUQaghz5ZfHcuErjxcrarkrmNbDpeQb7EqPbVDd23ufJaTsI8RJreNaiAU5TuwIGBC6QjCiKLu0Smofs9N41Ni/G9yFUVfS6WRs9AOsaS2lZ5DvDrToV5+7hz0CIcj7geiDS00uC7k9D69XnsL2sQC6aKfW8qcCm++0zeaZi++yna2EbPb0/knsrUxrqcrIFcA1HeB87oVJhH8d1v0L0X33iMJr21r3hUufVDtIGOu0xWAdY3gR7H8YbTHoVYj8yxmyABn6ktZ2eEkZn9UErIMJTf2YAW4HWQufYQVP71auSHfA0J0xlo4X4YLQzHoZtmC6AXvvsuvnszvnshvnsSvnsivjsb3z0QbTL2RJuJF5BPaAYdI8mHBL/vK7S4Lwo+uwe+O7VixSLKwyZ07KMM2iTlolF3RDmvl6f5y3Y4Xik6P32INn3R69MbpRrlhgTxv5CpM8pGQc2J0iALwWl0zGaoQwtu3FcIMm8Oj733KvBKXven8oYfBSbF/rJNymdlqVud1AyEW/DdTCbhTON+j9w3cXbImg1RLBI8V9LxHukPjA0KxWT6XmG56+INUjeaq1AdAn0fOrpsWpG7KH8zvjZM95GqNO1T6OTyGPdvsXeXAtYygZ7KfnTM3R6MBGgLyjksf260NgOjkI9qX6Stn44CX7JrRhLID+G7f8B3N0c7813RpuUipLE8hzYWWyHt/jrgoE7Ntl2DjWL/nocERaGtZJ8gtYb0YFJNxcUjQTaRjt0DQZuUfJhMahngOlRkqXT47rukLqTDSZ+mtXns3y3Bd6cVMPJkUs3Na6SxDPRCPufoOtkG/LOAMUEm/bhmNYzUjUrS+HS0vIE2TqWqIdKMNptRlqHyNT1ASlCUWcjCVGig3ROkCvS1KX2TqwfQeY4y2gR6FMdbEwWDxG+8zZAG+yASfpUmrPTm5e3b9t3v8N0XA41+HEq5+GXw+ho9iCcjH+eSwEqxf89C5R0Ls0poExQ3xfYmc0pgsXxG6oKSXx1+aWNxjRVKsQlJJe4XHkSqxQRSf9Mi4LMCr9NM5K6KMoDUKPiepF63eRT6bMh8/UHs3V4ohbGUzCB1zstTbJZTZlpI3Wj1J7mUrWKI10uYQ3Fr3UekRt2HZVxLyVeoWFGUURYUFyKT6L3oRo/TDUWTq3Sk0hfiD3+5aEOR7pfn5bfMhPx7c5DWEpK5WljXI24GbKZ4K0xcWHRDQr0UhEGVUQopDpMu1SbeAa8UfBH7dx/S5+bHo/kXU2g3LaVnzUEboahSM4iObZXrSc0Fn0dxaVPxcrelvDdC5tPxd4HWr1IpdG0oGj1KWDa50sSf90UU05XNdxfieD/Q8T6pp/TWiGakgEUVkpEm0CEsI/lHUoNfovRAZu4jUT5maQIfsrMQbSiuSESYG5BMjYBcKOXimcRY6Y5TjnMTT8GqR0Iul7mUI7YjXZ5yrRHWlY/Si1yvr5SdoWhT1S94hc1ZmtGmMlp9s4XqLQmeqZBVMaQLPC71s9NKquKwefJVAAAUuElEQVQxxAR6e7nDdKkpcbZEKS5/Rb6YdKbBUvIwcA7pGnIYxpKFOtIVXlq00Ap96rzneIVasUqtjedKLqVRh6H1bmOUvdOAfOH9Yt9vQ0J9JjK1T6M87polnZSNiAl0mSePIbU4S6bPHoqaU5yG0l/KxcvAsWGJP8NYwumD4l2OKPD7IyjMkjEIWckKFejF1GUvDwoO3Af4PUrDGkT2c1VHe/2MdBkKRplYsgW6tPODyFzSMU4dSm9pRPnh+5B/Uf98aUOd1nY2zdww/kc9indJF/NSSrqTb9BhLaGyqH9CmTTVajY3MrBkC3Tlgh9NanBMZ/wZ1Ta/EpmiSmV6D4X5kSbMDcMoKdLMj0UpremE+Xcounom8sm3IhdET2QxGYC09CFUj2thiWLJFOgq5NANBXH8DhV22Rz5xXMpfjACVQk6EuUhHkBpgp6+RsF6udRArlXSBZTUU75gNaN2aSa5NrsLyC3aOYzgTio47ntU5Kka2BjV3IjnUDchi+TLqNDVTHS+ogK9HxLog1HKlov870YZWXIEuoT4qqhM6i4o3P8lVNP4WlSdrR+6CfdHpvVsu8ztgtclqOXmgCyfLYRFqPzmE108oj3dYhZG0BpGJuYiH/oDCR2vjdyK1HyH1o+k6jS0kFr0pVKcS2rK46tIcXkn5+Iryhr6CSbQy07XFOgqaTg4eK2GKr9thwR6VFA0IOE9HTWECNs+Ph58bgdUVW0MKjAxOPL9fkjgHoyE+ikUpqUvQItT+JoKvIm6Gz1dwPFqjbA9YVQjH4k2U5WoymeUl3RrUC7abxvwfVDatJy0At9VYNzS4nijSa3GNw34C777RgFHrMX0vpqn6wh0xxsI/AjVXl4TCeExKGimM/Pt0shsfgAyKU0MXm8BJwWfWRftOtcB1kbRqhugtoiXoO43nZXcXITqwX+Jqvx8iRonNAWvz4AZXbx2epwpyOwYdXWsjSwe+fYVLoR42dRMfcrzIf5ctZGcabirEdcIm0nNTYfKCYj4uF3VFbRemvfeRTU3uhItdFTq6ijeGhiPN6jY817bAl15kpuh/rvr0d5jPF5VKh9GBq9dkeY+FTUaeBKZ5puBZdGmYScU6X4v6oh2B+0V5NqQQPoAPRjvovrR01EXNL0KryHcVfgelU/cMPLeSmhzFO8SVQrim4beFO8+iUdet1A9ftJq40exf88jtd45pJ6/egrPJc+VVlILsvSha7qD0rWGfitLn+6kiMfQJCFgszGdjs9naM0tDMcbQGrMQSvFVJ8rgtoS6EozWwEJ271Rs5JSpVZ0o32DMBalty1ErVQ91JHrLlRBbiBqg3oJ0txfQP75SUV2LVoSmI3cHFGB3h04Fcd7MLENj+6dOnw3voDEm3QsBYzC8eoKspSoQ1m84uB8UsvBGmqJGjfzziL9uYp3g+sFrFyKaUVYRGqp1v7IVZdLD/NaIp0QLYeWGd+o9aW0G7UP6CjQB6Bc+3hr21wZQ6ocnY8CmstONdTWzQ3HWw2lhx2Geos7lD9Pshcyrd+B0jceQv2GVwcW47tn4LuH4bsevvuRCfMcUMOKCaiBRJQ1gHMDV0pxON4IlFd7Mo4XbxDxPB0Xrh7oGue/a1fgpUuqWXYKqTXLDRVoivdEmEpq5zeQ6Te6weoGrF9EpThwvL443qpp+6+LBcAnpLpl3CzfyWXcITjesiVtm5o/6WICxuJ4pU4/i1vhhgENwQa8FDwe+/dAYKtA084PxWrtRaocfa5SltdquqEyowX5ZhSEdiPKHX+zonPSzm5X4FJkci9e8Cy5PAe8nub9I4ATcLzCulE5Xh8crxG4HtXhPxndQ1HeIrXT2LbAHgWMOBb1tI/zjzKYLmsLx1sdVSKL0oasNemizV8hNbJ8faCxIMHoeCujqO7rSW2pKWTNeYdUbWt3Crs/QsXkIlRlMp2Zu1K8lea9McC2JRSuAP+J/bs/cmWWSkv/Jx2zCuqAn6KsptzROdkU3Qvx83NrEfMritoQ6PBzFIB2CnoYXkXV2u4gdfdcbuqQtm4m1cL5Frgwzfv9gBOAW3G8H+d8NMfrhuPtCvwduAmlKvZD/s+zcLyomfcr9JBHtb8BwMU43i9zXswUJXw+yqqIMg24Jee5Lwk43ihUxyHummgBbkvjFgHfXQDcFnt3ACrBvG8eY9cHm7z7UDrWFsA4HG9khm+8SmrP9r7AJTjebnncH31xvCOBf6HMmN2By6tIS/+IVKE+FPWtSBcwlxTPo7iJKHsC+5VovM9J7Wc/ArgSx9sqj+P8GMmihtj7L6L+8xWh+n3ojrcsusDdg9eeKNL8EFTV6GPgN5Su33Qu3JV2ETJyQ77qJ3G8P6Oyk1EzXx+0g94Zx3sELcSvoaCT8JzXI4H9Y7TT3o3MtfkHA0fjeK/huwvx3QU43r3AzsH3QwahIMgtcbwrUUbCAiR02pDJtxfSJHZE7XXjwXALgOPx3XJE61eS03G8+5Cfez4KHG2h/fqExUf6ouIlpwFrxY6xGLgU330nyzj3oI38WrRrRUsBd+F4OwBXINdGeJ1Aa0ZPdJ02QGvFVnTUqnZEQvbslBF993sc7/LgO9EWmSNRLM01ON4NKBZkQfA76oJxewW/edtg3HXpqETthaqyXZblN5cHtZT9M3q+egXv1iFh/iSOdyFwP+1V4sLnIPytPYLvDUSaa67C8TNkodsx8l5vdF5XBW5A7riWYKzw/M0saM3V835TML9oXf2RwL9wvEvRdf2G9usZPu+90fqxN1qn4mb6WcAplQx0rm6Brt2rg9KYooxGu6yLkSn+TWS+24Ty/6b5qE+6UTznoIX3CFJ92HVI0/4ZClaaTvvOvh/SJuL+8ThtaDNwFx17Wk9EFoJL6eg66YWa8ewFvI0E1iz0kPdDi8A6pE+NnI/uzfs7mVNX4Gjg18j//Wnw31noHLShc7UcygwZneb7i4FHkVskGx8hrehCUjfwhyAzeOhCmR28PxBdpx+j65ROI55KagxHlCdQFsvJdDQFD0GVHA9HLqPPUNexenT/jkJrV6bS0JNJ7VNeSR5DVpCD6RiftBTa7JyAXBBN6PqGbVIHouDhUShQMR+/+zRU3GtDOsZT1AfjHQy8jzYS3WjPMnDRJrsQXkabqDPo2Le8ezCmi573Jtrvo/6o8cwY9Fvjz/uc4JgVrepZ3QJdC8GepAbOgDSoccBGqGLUr5DG7lL65vJR3sQCnpJBWsK5yGd5ChLS6eiBUgfzYSYyv18P/LdDBLvvtuJ4dyABdAmpvs1ByDSb3teaSgsqlXl2YCruSmSK/O+GrCL5BqktRoFKf8B3s6f2+W5LYE0BLZ7xMs2DkeaVj+n0LWRdeTLLuK043kXBXMeRmjs/FBWhypUW4CkkJF/K43ulRef3LCSgQ6tolKXI//x2NuZiHG88sp4cFftrHe2ZRnFGUKhAl5Z+PboOZ5OadrY0+fnU25B16MpO7+ESUy3+m0ysisynmeiLTKWvItPQscGrnEn9Eyi8laIRR01oLkfpTIWmksR5Bi2444Lsg1ShpKC1e1Cg438ovJDJAlQP+yh8d0qBx6hW5qJo8yS1ypuBX+C7H+b0ad+dj4KOtqC4wNh5yCK0KQpazF6VUPfHRSiospgqcfOAE4F98d3nq66ss+82IWvHBaTvs1Aok0lfXyB85o9B5bfLg+/+gITwLshtWyjTkGXoFHy34taW6tXQlRZyCp2nptUhwX4DquR2JfLTXYx2faVMu5gLvGrFYRJGvrEPcbxt0IbtIGQyHYa0sEym9cXomsxAWv4ryJz3Sk455frMRBxvu2DMfZDGOYzMVp9mpP1PRb7Aq/DdXHKUFyDzdHRH/0MO34szJzhO1L/7SQHH+RotulE6Ci5dFy/wl2+D/J5jUDOOwcin2IfM1dQWIxPmN0gYX4fv+nnPVNfpHRxve3Sd9kVm9aXpeB5C2tD5DruF+chak35zl3ncxcBDON5LKKBup8i46dapNnR9pyMr3hPADTmUjZ2HrkX03ohfm3xYFIwfPUYTmRQfpZKejOPdjX7nxkgjHkK7fz0drWjuPyCT/HRkAXkCpXLNzvhNWQd+i56hw1Fw6TCyP+tRvkDPQXjvfU5nxZx07SfgeA6y7O6OXENDSX8fgeIHZqBU1KeAa/HdXOr6z0HnPCor4tk1+dBC6jX9qnrLGDreFigiNJ9c82akjV2IfuhRyB9bqhSIt5F28XaJjm9AmO+5CnrIRyFz+2DaN2vNaPc/DQnWyajwx7Siyug63iDkI/8REuxDkXmuHgmImUhATEa+xc9z1rgUHzKGjhuFWfju+3nOsQcKtooufF/ju/FCLJ0dZwipUefvZ23bqwjvgSjSdwV0XYYh02x/tPjXo+sTCvLPkE/0Y3w3XoWtMDT3sXS8Tr2RQJ2HBMsUtIC+h+8WX/RDv30Euj9WRf75sG3oYrSATwvG/Rj95tzKOqvgztp0FCrT8N3CNEndayvS0U01C21ost+vUqxGoQ11A/rNS6H7th4JlgXo+ZuJfvPXSNg04bv5V0xTBdD1UH2Pkei89gzGWojO7Tn47ozId5YP5hnKtDnoHsu9H4SKQq2L1pqRkd9J8BtDQT4JZT5MyXl9UcOaNej4vE/JcTOQ7njd0PWIuiNmVKdA1w39IDJ/FsIU5Au9DfnYr0YXKGkeBNzAfGOUAy2kPdADHrZZXYx2vs0lq4OvB6gXsmqFYzYDi5aw2vvZkfDoEbzKd33axw+jrUN34mJgYcmLPGnT2RPFErQRCp9qM6kXi85v+DvrkFbeiq5vss+CnvXwvNbTXiO9JbHNYOaxo78TwjLAVW6NrVaBvg1wJ+mDIXJlEfLP/RlpVdeiiPnOIqFzpRk4Dd89J6HjGYZhGEbBVF9QnOP1RUEGxeaV90C+mAeRKe7XKKglqcCFBaiuu2EYhmFUnOoT6PJH7UByHXc2Q+ViD0BRjYegqPhiTUNfUfnys4ZhGIYBVKdA3wUJ9SRZHjV0uQ5FUf4cFfwoxr/1cKVzDg3DMAwjpLoEujreHEZpfPs90GbhXVSx6mjgLKRp56utt6KGLIZhGIZRFVSXQFe944YSjzES5aD+DvgbKhQxgY75gZ3xKfBG8lMzDMMwjMJIyk9dPMojvJXylG3th4rObAw8gLTtPqgdYy7chu8+WqK5GYZhGEbeVIeGrnxDl9QayaWkD0pjexrlqv8O+AUqgJHNBN9Kavs9wzAMw6go1SHQVcUoXaP4cjAEmd7PQGlou6AKdZnqs39EcWUYDcMwDCNxKi/QVVlqO1Tmr1IMQu1XPVTK8miUsz4vzWdfRzWhDcMwDKNqqLxAV03uPUltFl9uugNbo5z1nYDzUIGbqDbejILh0ncNMgzDMIwKUQ0CfV1g20pPIsKyqA78+cB7QCPqldwMfAu8ZbW7DcMwjGqjslHuasLyN1SatZqoR61YN0NdtG4C5qPUtptoGm8FZQzDMIyqotL90LdDkebVyoaoU9v1wDlIe59W0RkZhmEYRhoqJ9DVjvIUkut+ljRtSDt/DPVYX4jvflLZKRmGYRhGeiqpoe8M/LiC44fMQx3YpqEysK+j5i1vIBP7Qnx3TuWmZxiGYRidUxmB7ngDUQT5oAqMvhiYBHwQvP6LItknIz/5asAawDbAW0hDN4FuGIZhVDWV0tDXQP7zckXZf4O6rP0beAHlkc8BFgJrAVsBJyBh3h9p5ucDj+C7M8o0R8MwDMMomPILdBWS2R0YlfCRW4EFSMuei0znzwDPIo28F9AbWAHYF2ngmyMBHj3Gu6jIzDP4bmvCczQMwzCMklAJDX0ZVDO9WNqAGcAXwOfIZP4uCmT7BJV0XQE1XPkF0sTXJvNG4jvgQeB8C34zDMMwao1KCPRjUAvTQpiHBPYbwH9QG9Ovg9cgVKRmVyS8lwVGBK+eWY7ZBryP0tIexHfnFzg3wzAMw6gY5W2G4ngjkfk7m4CN0oq07SeD10vI970Ymc+3AnYMXsujDUo38iuY46Oe6JPNxG4YhmHUKuXT0JV3fjTphfkCYBYwEwWwvYGE96vAD6je+1LA9sAmwWtdCp9/K0pRuw44F9/N1FnNMAzDMGqCcprcVwV+Gvx/CzAFpYz9F/g4eH2C+pGPCj5/aPDfVYL/DklgHm0oWO4i4Gl8d1ECxzQMwzCMilIega7I9vWQ0L4HeA34Emnl84CVgU2Bg1Ab1SFIKx9IsqltzcCFqH78VDOxG4ZhGF2F8vnQZXLvgUzuy6K0se1RLfckNO9stAJNwDH47sMlHsswDMMwyk65NPQBwIGoTeq6wEqUr9PbfOCfwLnAm2Ua0zAMwzDKSrl86L2BnwG7lGm8kE+Rif1efPe7Mo9tGIZhGGWjXKVXZwNvl2ksUODbi6gi3HUmzA3DMIyuTjl96AcDVwIDSjzSd8ADwEn47swSj2UYhmEYVUE509Y+Ar6ldAK9BZgIXArcZxHshmEYxpJEuUzuoHzzb0p4/FuBQ4D7TZgbhmEYSxrlLv16DXBEgkdsQ/75o/HdOxM8rmEYhmHUFOXU0EE9yZOiGXgcRc7fleBxDcMwDKPmKHe3tedQkZdiNxLTgMuA2/Ddz4uelWEYhmHUOOUW6F+g9qfrFHGMN4BjgVesqYphGIZhiPKa3H23DXiowG/PA+4GGvHd50yYG4ZhGEY75fahA/wdmd1zpRVp9ScCh+K7X5RkVoZhGIZRw5Tb5A7wAfA50JDDZ1vQBuA8YGKg4RuGYRiGEaMSAn0R8BKdC/RW4C/AxfjuwlJPyjAMwzBqmUoI9LDO+n6kz4Ofg+q+/wXffbqcEzMMwzCMWqX8At1323C894GZwFKo9vqkyOtTlN42qexzMwzDMIwapRIaOsiPfgLwFfAZ0srnEAbL+e7sCs3LMAzDMGqSSkS5g+9+BdyCBPs6KIL9aWAGMLYiczIMwzCMGqZSGjrAIOBiYM/Ie3NR4RjDMAzDMPKgMho6EPQqPwG1PA15Ht/9vkIzMgzDMIyapXICHcB3JwP/B0wN3vl7BWdjGIZhGDVLZQW6eA84FZgOPFbhuRiGYRhGTVJ5ge67LcB9wFmogpxhGIZhGHny/1nX9W6QEm3gAAAAAElFTkSuQmCC"
  style="height: 2cm"
/>
```

**Output**  
![](https://cbnpeuwstassets.blob.core.windows.net/public/COMBEENATION/0Dxez2x2M09.png)

#### Header, footer, page numbers (Headless browser)

:::info
These CSS classes only work in the header & footer! They have no effect inside the body.
:::

Specific CSS classes can be used to inject auto-generated values into the PDF.  
To use them, simply create an HTML tag with one of the CSS classes listed below.

###### Available CSS classes

- `date` - Formatted print date
- `title` - Document title
- `url` - Document location
- `pageNumber` - Current page number
- `totalPages` - Total pages in the document

###### Example usage

```html
<span class="pageNumber"></span> of <span class="totalPages"></span>
```

See also [Puppeteer PDFOptions.headerTemplate](https://pptr.dev/api/puppeteer.pdfoptions)

#### Header, footer, page numbers, watermarks (Prince XML)

For detailed guides on using Prince XML features, see:

- [Headers & footers](https://www.europdf.eu/features/pdf-headers-footers/)
- [Page numbers](https://www.europdf.eu/features/pdf-page-numbers/)
- [Watermarks](https://www.europdf.eu/features/pdf-watermarks/)

### How to use a pdf asset

A PDF asset can finally be used to create a PDF based on any data during a configuration. The required data can be dynamically passed via the `Context` object. As a result, it's possible to create a PDF using Custom Code.

Basically, the PDF is created via the PDF asset and a dynamically passed Context object. This generated PDF is saved as a "configuration file" and be used as described [here](/docs/configurator-logic/file-upload-and-handling).

#### Example "Create and merge PDFs"

:::info
Function can be used if all assets are in the same bundle and you just want to create a PDF and optionally merge it with others
:::

```typescript
// creating the context
const myContext = {
  company: {
    logo: 'MyFolder.MyFinalLogo'
  }
};

const urlResult = await CfgnFiles.createPdfFromAssets(
  'MyBundle',
  [
    {
      type: CreatePdfTaskTypes.Asset,
      assetPath: 'Pdf1'
    },
    {
      type: CreatePdfTaskTypes.PdfAsset,
      assetPath: 'quotePdfAsset',
      context: myContext
    },
    {
      type: CreatePdfTaskTypes.Asset,
      assetPath: 'Pdf2'
    }
  ],
  'Output',
  'My cool PDF'
);
```

#### Example "Create PDF with dynamic convert document endpoint and merge it with static pdfs"

Similar to the previous one, but the dynamic `convertDocument` endpoint supports all types of convert tasks.

```typescript
// creating the context
const myContext = {
  company: {
    logo: 'MyFolder.MyFinalLogo'
  }
};

// Example "Creating the PDF based on the context and a PDF asset"
const urlResult = await CfgnFiles.convertDocument([
  {
    type: DocumentConvertTaskTypes.PdfAsset,
    name: 'HtmlToPdfTask',
    bundleAliasName: 'MyBundle',
    assetPath: 'MyPdfAsset',
    context: myContext
  },
  {
    type: CreatePdfTaskTypes.Asset,
    name: 'Pdf1Task',
    bundleAliasName: 'MyBundle',
    assetPath: 'Pdf1'
  },
  {
    type: CreatePdfTaskTypes.Asset,
    name: 'Pdf2Task',
    bundleAliasName: 'MyBundle',
    assetPath: 'Pdf2'
  },
  {
    type: CreatePdfTaskTypes.Merge,
    name: 'MergeTask',
    inputTaskNames: ['Pdf1Task', 'HtmlToPdfTask', 'Pdf2Task']
  },
  {
    type: DocumentConvertTaskTypes.OutputToCfgnFile,
    name: 'OutputPdfTask',
    inputTaskName: 'MergeTask',
    cfgnFileName: 'Output',
    cfgnFileExtension: 'pdf',
    cfgnFileDisplayName: 'My cool PDF'
  }
]);
```

#### Example "If you only need to create a temporary PDF"

```typescript
const urlResult = await createTempPdfFromAssets('MyBundle', [
  {
    type: CreatePdfTaskTypes.PdfAsset,
    assetPath: 'MyPdfAsset',
    context: myContext
  },
  {
    type: CreatePdfTaskTypes.Asset,
    assetPath: 'Pdf1'
  }
], 'My cool PDF');
```

---

## Text asset

A text asset can contain large amounts of textual data.  
You can work with its text content in a configurator (unlike the contents of a file asset).  
As such, it's useful as a container for e.g. HTML print templates or SVG images (if you want to process them as text).

### How to create a text asset

You have two options to create a text asset: you can either create an empty text asset or upload a text file.

#### Create empty text asset

1.  Click on the (+) button to create a new empty text asset  
    ![empty-text.png](https://docs.combeenation.com/assets/images/empty-text-830e23e2f1a0dccf0ea0fa848b10dc16.png)
2.  Select a name, folder, format and click on `Create asset`.  
    ![empty-text-dialog.png](<https://docs.combeenation.com/assets/images/empty-text-dialog%281%29-8363c0e1719badc25417fc15e0646339.png>)

#### Upload existing text file

1.  Click on `Upload Files` to upload one or more text files.  
    ![upload-text.png](https://docs.combeenation.com/assets/images/upload-text-46f0a1a1d5f26fabf6b3967fae2a3ccc.png)
2.  Select the `Text` asset type. Keep in mind, a text file can also be uploaded as file asset.  
    ![upload-text-dialog.png](https://docs.combeenation.com/assets/images/upload-text-dialog-cf03816b74a8f9ece698c0df728447e2.png)

#### Change text content

After creating or uploading a text asset, it is possible to change its content. Similar to other assets, you can also rename, copy, move and delete a text asset.

![image.png](<https://docs.combeenation.com/assets/images/image%2820%29-3cf1a3cd9c1a7d063f9afcb6710a83e8.png>)

### How to use a text asset

A text asset can be used in the configurator. For this, initially assign the asset bundle which contains your text asset to your configurator as described [here](/docs/asset-management/assign-asset-bundles-to-configurators).

:::info
Keep in mind that retrieving text content requires time.  
This means, loading a large number of texts can slow down your configurator – so only use what you really need.
:::

#### URL

You can get the URL of the text content in the configurator with the following hive rule:

```hive
MyBundle.MyText.url
```

#### Content

Retrieve the content of a text asset in the configurator with the following hive rule:

```hive
MyBundle.MyText.getText()
```

If your asset contains valid JSON, you may use the `getJson()` method instead, which returns a [JSON value](../configurator-logic/hive-types/json-type.md):

```hive
MyBundle.MyText.getJson()
```

### Supported formats

Currently, text assets support the file formats listed below.  
The asset editor provides appropriate syntax highlighting and error notifications for them.  
If you create an empty text asset, the format must be explicitly defined. If you upload a text file, the format is detected based on its file extension.

Note that the format cannot be changed in a subsequent step.  
For this, please re-upload the file with the desired file extension or create an empty text asset.

:::info
The format has no significant impact for the usage in the configurator.  
The content of a text assest will always be a text in hive.
:::

| Format | Maximum size |
| ------ | ------------ |
| txt    | 512 KB       |
| svg    | 512 KB       |
| html   | 512 KB       |
| xml    | 512 KB       |
| json   | 512 KB       |

---

## Insights

We collect insights data for each [configuration](/docs/fundamentals/configurations) a user creates when they open the configurator

### Inspect insights data

Go to the dashboard, select your desired configuration and click "Open" on the configurations area.

You can filter your insights and view details about your insights by clicking on the respective insights entry.

When you select a value for a filter property, conditions are connected using AND logic, meaning all conditions must be met. If you select multiple values within a single filter property, these values are connected using OR logic, meaning any of the selected values can apply.

##### Example

This example shows all configuration insights, which have been created in the last 7 days **AND** were the type is Configuration **OR** Finish.

![](<https://docs.combeenation.com/assets/images/image%2859%29-4f6c9d9d4864718bdf8ba08c5198fb71.png>)

### Data collection

#### Generic information

- Creation date
- User who created the configuration (if it is a logged in Combeenation user) - for more info see [personal configurations](/docs/configuration-insights/personal-configurations)
- Type of the configuration
- On which version the configuration is based on
- Preset id

#### Information about the configuration

- When a [configuration checkout](/docs/integrations-and-api/checkout) will be performed, we store:
  - Checkout type
  - Used shop name
  - Price (if the price property of the checkout component is set)

- Custom insights fields

  Custom fields allow you to track specific values that are important to your use case.
  You can also use them in filters to find all configurations with a specific custom field value.

#### User and device metadata

We are also collecting device information from the client:

- Height & width of the viewed device (correctly speaking the iframe in which the configurator is embedded)
- Browser
- Mobile detection
- Country & City
  - Based on the IP address of the user, we try to roughly locate the country and city of the user. This is not 100% accurate.
  - Coming soon: Deactivate this location feature, if you don’t want to collect location information about your users

---

## Personal Configurations

A personal configuration belongs to a specific user on the Combeenation platform and can only be opened and edited by that user. The user must be a member of the Company that owns the configurator.

Users can organize their personal configurations on the Configurator Insights page and use them e.g. as templates or as a living document to assist in the sales process.

Information about the current user is available in Hive and can be used to augment the configurator to e.g. show sensitive data or unlock advanced features (for more details see the [User](/docs/configurator-logic/user-variable) and [Custom Fields](/docs/fundamentals/custom-fields#user-fields) docs).

### Creating a personal configuration

A personal configuration is created automatically when a configurator is opened by a user that is already signed into the Combeenation platform.

If a user is currently not signed in, the configuration will be anonymous i.e. not tied to any particular user. This is the default for configurators that are made available to the general public on the internet. Note that anonymous configurations are still protected by an [authentication token](/docs/configurator-logic/configuration-variable#the-authorization-token-authtoken) so that even if a copy of such a configuration is shared, the original cannot be edited without the authentication token.

Users can log in after they opened a configurator in order to create a personal configuration. In this case, a copy of the original configuration will be created and attributed to the signed-in user, while the original one remains anonymous.

### Add Combeenation Login to your configurator

By using Combeenation Login, you can provide a convenient and secure way for your users to sign into a configurator to unlock advanced features or gain access to sensitive data. Each user must have an account on the Combeenation platform.

Follow these 3 simple steps to use Combeenation Login:

- create a `Button` control
- add a Signal & Slots connection to your button: set the signal to `Clicked` and for the slot choose the `Configurator` control and then select the `User login` slot
- finally, to hide the button when a user is already signed in, select the `Visible` property, click the “Enable Hive” button and paste the following rule into it:

  ```hive
  If user.isLoggedIn then Visibility.PluggedOut else Visibility.Show end
  ```

That’s it! Now when a user clicks the button, they are automatically taken to the Combeenation Login and afterward redirected back to the configurator. If the login has been successful, a personal configuration will be created for the user.

---

## Components overview

There are five different component types:

- Value component
- Record component
- Resource component
- Graphic component
- Table component

To add a component, use the `+` at the top. To add a group you first have to add a component and during this process, you are able to add the component to a new group.

There are two more components, that are added to the configurator automatically and cannot be deleted: the design component and the checkout component. These two can also not be renamed nor can you place them in another group. As the names suggest in the checkout component you can create the different checkouts you need and in the design component, you can create the UI design of the configurator.

### Properties

| Name    | Description                   |
| ------- | ----------------------------- |
| name    | name of the component         |
| group   | group of the compoet          |
| records | records of a record component |

#### Group and name

Each component has the following properties: `group` and `name`. To access the value of these properties you use the `#` operator (escape operator), the name of the component and the name of the property. Example:

- \#TestRecord.Group
  - name of the group which contains the record component “TestRecord"
  - in this case "TestGroup"
- \#TestRecord.Name
  - contains the name of the component
  - in this case "TestRecord"

#### Records

To access any property of a record component, you have to use the escape operator. For example, to access the Records property you have to write `#testComponnet.Records`. This will show the whole record table.

On the plus side, `testComponent.Name` will always refer to the `"Name"` column (if there is one), meaning you don't have to write `testComponent.Value.Name`.

---

## Graphic component

The graphic component allows you to create dynamic visualizations in the Scalable Vector Graphics (SVG) format and export them as JPG or PNG images.

### Properties

| Name           | Description                                            |
| -------------- | ------------------------------------------------------ |
| width          | the width of your graphic                              |
| height         | the height of your graphic                             |
| archive        | controls if and how the graphic will be exported       |
| url            | the URL to the exported graphic (depends on `archive`) |
| value          | gets the generated SVG of the graphic                  |
| visuals        | a map of the component's composed visuals              |
| dynamicVisuals | a map of the component's dynamic visuals               |

### Width and Height

Defines the width and height of your graphic. You can give it a fixed size or make it dependent on a rule or even an Input.

### Archive and Url

Archive determines whether the graphic should be saved to a file and which format and other settings to use.

To accomplish this you must provide a graphic archive value, for example:

```hive
GraphicArchive.Svg
```

This will save the graphic as an SVG image. The name of the GraphicComponent will be used as file name.

The Url property returns the URL of the saved image. If the Archive rule is empty or set to GraphicArchive.None, the Url will return an empty Text "".

### Value

Returns the raw SVG generated by the graphic component.

It is not recommended to modify the raw SVG directly, but if you have to hand it to an external system (like a shopping cart) you can convert it to Text with the toText() function to be able to put it in a XML or JSON document:

```hive
DefaultView.Value.toText()
```

### Visuals and dynamic visuals

These two properties are maps that contain all the composed visuals / dynamic visuals of the graphic component.

You can use them for example to obtain a visual by name (see the map documentation for further details):

```hive
// get the visual with the name "myVisual", or Empty if it doesn't exist
Defaultview.Visuals.Get("myVisual")
```

### The GraphicArchive type

To use the Archive property of a graphic component you must provide a GraphicArchive value. This section introduces you to the various archive settings that are currently available.

#### None

No image will be generated and saved. It is recommended to use this setting when you don't need an exported image to reduce resource consumption.

```hive
GraphicArchive.None
```

#### Svg

An SVG image will be saved. If the SVG format works for your use case, you should consider using this option.  
Pure SVG images can be enlarged without loss of quality and exporting in this format is also faster.

```hive
GraphicArchive.Svg
```

#### Png(width, height)

A PNG image with the specified width and height will be saved.  
If you can't use SVG and need transparency in your image, you should use this option.

```hive
// saves a 400 pixel wide and 400 pixel high PNG image
GraphicArchive.Png(400, 400)
```

#### Jpg(width, height, quality)

A JPG image with the specified width, height and quality will be saved.  
The quality setting accepts a number between 1 and 100. The higher it is, the better your image will look – but it will also take up more space and thus take longer to load.  
The width and height also play a role in the image's size and appearance (if you use raster images in your graphic component, they may look blurry if they are enlarged).

```hive
// saves a 600 pixel wide and 300 pixel high JPG image at 60% quality
GraphicArchive.Jpg(600, 300, 60)
```

:::warning
The larger a JPG or PNG image is, the longer it will take to generate!  
Larger images also take longer to download or send and take up more space. You should make your image just large enough to be suitable for your use case. For JPG images, the quality also affects the file size.
:::

#### Properties

When you create a graphic archive in any of the ways shown above or work with the Archive property of a graphic component, you can access its properties:

**Name**

**Description**

| Name | Description                         |
| ---- | ----------------------------------- |
| type | gets the type of the GraphicArchive |

#### Type

Gets the type of the graphic archive. You can use this information for example to figure out which kind of graphic archive is being used by a graphic component.  
You must compare this value with a graphic archive type, which has the properties None, Svg, Png and Jpg as you would expect.

```hive
// do something when a PNG image is used
if DefaultView.Archive.Type = GraphicArchiveType.PNG then
```

---

## Record component

A record component holds whole data sets in a tabular form. The structure of a record component can be defined by the user, i.e. any number/names of rows or columns can be added.

Typical application cases for a record component are:

- mapping of the possible characteristics of a product
- color tables
- everywhere where the user can make a selection from several possibilities

A record component consists of so-called records, where one record represents a row in the record component. There is always one selected record, which is defined by the selected key. Therefore each record must have a unique key.

The first column in a record component always serves as a key column and, as already mentioned, must be unique. The column does not necessarily have to be called "key" and the type does not necessarily have to be of type number - but in most cases, it makes sense to keep this scheme.

The value of a record component is the selected record, i.e. a row including all column information.

### Properties

| Name        | Description                              |
| ----------- | ---------------------------------------- |
| Records     | the table of records                     |
| selectedKey | the key of the reocrd to choose as value |
| value       | contains the selected record             |

### Records

The table of records, from which one can be chosen as the Value.

A table looks like this:

```hive
{
   { Key=Number, Name=Text, Price=Number }
   { 1,          "Apples",    10           }
   { 2,          "Oranges",   20           }
   { 3,          "Bananas",   30           }
}
```

The first row of this table determines which columns it has, all subsequent rows contain values for these columns. A column definition must always consist of a name (like "Key" or "Price") and a type (like "Number" or "Text").

Note that the first column in a table is special: it is used to look up a record with the get function. While generally referred to as the "Key" column, you can give it any name you want. Because it is used to look up records, it must not contain a value that can change over time. In fact, you can only use literal values in a "Key" column, such as Numbers or Text. If you try to use a different value, you will get an error.

For a better overview keep your table well structured. You can use the shortcut `strg+b` to automatically format your table.

The examples below assume that there is a record component with the name "fruits" that looks like the one above.

To access the Records of a record component in a different component, you need to use the escape operator:

```hive
// Note the # at the beginning of the next line
// Without it, you can't access the 'Records' property
#fruits.Records.GetFirst()

// Without the #, 'fruits' refers to the selected record
// You can access the columns of the selected record directly
fruits.Price
```

##### Tipp

You have a product with a top color and a bottom color. Both have the same selection of colors. You create the record components for both. You fill the first record component with your color table. In the second record component, instead of writing the whole table again, you just write `#TopColor.Records` and you have the same color table in there. If a new color needs to be added, you only have to add it in the first record component and not in both. This way the data is more maintainable in the editor.

### Selected Key

The key of the record that should be selected as the Value. It is always of the same type as the Key column. In many cases, you will want to use a rule like the following (assuming the Key is of type number)

```hive
Input or 1
```

You can connect controls like the dataview to a record component, which will automatically write the Key of a selected item to the selected key property.

Note that by itself, the selected key property has no effect on which record will be chosen – it's not even necessary to use it at all in some situations. In order for it to have an effect, you need to use it in the Value rule, which we will look at next.

### Value

Contains the selected record. The default rule for this property looks like the following:

```hive
Records.Get(SelectedKey) or Records.GetFirst()
```

This rule does two things: it first uses the get function to look up the record that has the same key as the selected key. If no such record can be found, it uses the getFirst function to return the first record from the records property.

### The Table Type

The value produced by the Records property is called a Table.

#### Functions

| Name             | Description                                                                    |
| ---------------- | ------------------------------------------------------------------------------ |
| get(key)         | gets the record with the specified key                                         |
| getFirst         | gets the first record of the table                                             |
| add(table)       | produces the union of two tables (unique rows from both tables)                |
| intersect(table) | produces the intersection of two tables (only rows that appear in both tables) |

##### get(key)

Returns the record with the specified key, or `empty` if none of the records has that key.

| Example                  | Result               |
| ------------------------ | -------------------- |
| `#fruits.Records.get(1)` | `[1, "Apples", 10]`  |
| `#fruits.Record.get(3)`  | `[3, "Bananas", 30]` |
| `#fruits.Record.get(9)`  | `Empty`              |

---

##### getFirst

Returns the first record of a table, or `empty` if there are no records.

```hive
#fruits.Records.getFirst()  // returns [ 1,"Apples", 10]
```

---

##### add(table)

Produces the union of two tables: returns a table that contains all records from both tables.

```hive
#fruits.Records.add(#vegetables.Records)
```

A few things to keep in mind when using `add`:

- Both tables must be of the same type, which means they must have the same columns
- If both tables contain a record with the same `key`, only the first one will be taken. The "first" record is that of the table on which you call the `add` function – in the example above, that would be `#fruits.Records`.

##### intersect(table)

Produces the intersection of two tables: returns a table that contains only records that appear in both tables.

```hive
#fruits.Records.intersect(#vegetables.Records)
```

A few things to keep in mind when using intersect:

- Records are identified by their key (the first column of the record), the other columns do not affect which records are picked
- All records that make it into the result are taken from the first table (_fruits_ in the example above).
- If one of the two tables is empty, the resulting table will also be empty
- The second table (_vegetables_ in the example above) only has to contain the key column, all other columns will be ignored
  - it can be of the same type as the first table, but it doesn't have to be

---

## Resource component

To access resources in the configurator, it is also necessary to store them in a component. There are the following 4 resource types that can be uploaded:

- Image - e.g. product images
- JavaScript - Custom code which should be executed additionally when opening the configurator.
- Document - e.g. PDF
- 3D Assets - 3D models or environment files

If a configurator offers the possibility to individualize the product by uploading a custom image, it is necessary that the option "User can upload his own resources" is activated. User uploads are stored in a separate resource component just like normal product images.

### Properties

| Name   | Description                                                                             |
| ------ | --------------------------------------------------------------------------------------- |
| url    | url to the resource                                                                     |
| width  | width of the resource (available for image resource)                                    |
| height | height of the resource (available for image resource)                                   |
| type   | datatype of the resource (e.g png, available for image, document and 3D asset resource) |
| size   | size of the resource                                                                    |
| dpix   | resolution x (available for image resource)                                             |
| dpiy   | resolution y (available for image resource)                                             |

### Value

When referring to a resource, in another value component for example, you get all the properties for the resource. The example below represents an image resource.

```hive
{
  "Url": "https://combeepublic.blob.core.windows.net/resources/0C6fxtWT3dA.png",
  "Width": 3040,
  "Height": 2943,
  "Type": "Png",
  "Size": 135915,
  "DpiX": 118.11,
  "DpiY": 118.11
}
```

---

## Result visualization

The result panel automatically converts the output data in a human-readable format.

### Bottom toolbar buttons

- Toggle raw data: In case the original data is needed (e.g. for using the result as component input elsewhere) you can activate the raw data toggle.
- Expand / Collapse all: Expand or collapse all inner tables recursively.
- Copy result: Copies the whole content into the clipboard. Is only available when raw data is displayed.

### Record data

The result visualization for the record table data renders columns based on it's type. You get several expand and collapse features that enable easy navigation through big data sets.

#### Column rendering

- Nested data: (Expandable) inner table
- Logic datatype is displayed as checked/unchecked box
- Image datatype directly loads the image url. If the overall size is too large for efficient loading, it will show only an icon. You can hover over the image for a larger preview.

#### Pan / Navigate

The right mouse button can be used to pan inside larger tables. Holding the right mouse button will hide the cursor and you can move in any direction until it's released.

#### Minimize / Maximize columns

Every column can be minimized by moving over it's header and clicking the `-` icon.

#### Collapse all columns except the clicked one

It's possible to focus on one column by clicking on the header with any modifier key held down (ctrl, alt, shift). To reverse the action and expand all columns again, click on the focused column again with any modifier key.

#### Expand / Collapse nested data

When a component contains nested data (e.g. record inside record-column) it's collapsed by default. The nested data can be expanded individually per row and nesting.

### JSON

Plain text which is parsable as JSON gets automatically formatted.

---

## Table component

A Table component is used to load tabular data from a [data source](/docs/asset-management/data-source-asset/basics) as well as filtering and modifying that data.  
This data is organized in a table of records. A record corresponds to one row of the data source and consists of multiple columns, where each column can be a number, text or other value. A table is a grouping of records and provides functions to access a specific record.

You can use a table to:

- fill a ComboBox or DataView control, to allow users to see and choose one record
- access individual records and use its values in your product logic

### Properties

A Table component has 2 properties: Query and Value.

- The Query property is where you write a query to load data from a data source.
- The Value property holds the resulting table. It's used automatically when you refer to the table component in other rules, you typically don't need to access it directly.

### Using a table component

A typical use case is to select a particular record from a table; this could e.g. be the record that a user selected in a ComboBox or DataView control.

Let's assume we have a table component with the name `parts` and that it has 3 columns `partNumber`, `name` and `price`.  
To select one part from this table, create a value component with the name `part` and enter this code:

```hive
parts.Get(Input or 0) or parts.GetFirst()
```

You also have to change the **Input type** of the value component to `Number`.  
When you now type a part number into the **Input** field of your value component, you should see a part record in the result panel. Try typing different part numbers into the Input field to view different parts!

This value component can now be connected to UI controls to hold a part selected from the parts table.  
Let's break down what the code above does:

1.  We try to look up a part with a particular number with `parts.Get(…)`
2.  As part number, we want to use `Input`, which can be connected to a UI control to automatically update
    - To prevent errors, we supply a default value for the Input with `Input or 0`.
    - Instead of `0` you could use the number of a part you want to be selected by default.
3.  In case the `Input` contains a part number that cannot be found in the table, we use the first record of the table as fallback
    - We get the first record of the table with `parts.GetFirst()`
    - Now our component will always select a part record, no matter what we type into the Input box!

### Queries

To load data from a data source, we can use a so-called query in our Hive code, written into the Query property.  
Let's assume our data source is called `BikeParts`, then the simplest query we could write is:

```hive
from BikeParts select all
```

This will load all records from the data source and include all its columns.

Queries support filtering, sorting, limiting and reshaping (projecting) the data they load – see the [Hive Queries](/docs/configurator-logic/hive-queries) page for the full syntax and examples.

---

## Value component

Different data types can be stored in a value component. The most simple of these are numbers, text, and logic. These can be simply selected in the dropdown menu on the top right. Also, more complex data types like lists or the values of other components can be stored here.

A list, for example, cannot be selected in the dropdown menu. In order to use the list data type for your value component you can write `List<Number>` into the input type textbox. Instead of number you can use the needed datatype.

When referring to a resource, the type of the resource defines the data type of your value component e.g. image or document. While referring to a record component, the input looks like this: `Record<{Key=Number,Name=Text}>` - every existing column in the record is mentioned here.

### Parts of a value component

A value component always consists of three areas: input type, rule, and result.

The input is a value that can be used to calculate or which is saved in the value component e.g. a user input from a text box. The input data type is the one that is defined for the component as mentioned before

The rule contains calculations, rules, or mappings to other components. The syntax which is used for these calculations is Hive. A multitude of operations (addition, multiplication, ...) can be performed in components using Hive. It is possible to access a value of another component and perform cross-component calculations. As in other programming languages, an [if / else condition](/docs/configurator-logic/the-if-expression) can be mapped in Hive. Hive also provides some auxiliary functions, e.g. to round a number commercially.

The result area shows the calculated result of the rule.

When a value is needed to be available after a configuration is finished, you can check the "archive" checkbox on the right side of a value component. Now this value will be shown in the results page for each configuration in the configurations menu.

---

## Configuration variable

Every time one of your customers uses your configurator or you try out a draft of it, a configuration is created. This configuration is used to automatically save the user's progress, it can be copied or edited at a later time, shared on social networks or put in a shopping cart.

You can interact with the currently active configuration via the configuration variable.

### Properties

| name                                                                                           | description                                                                                                                 |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| id                                                                                             | the unique ID of this configuration                                                                                         |
| [authToken](/docs/configurator-logic/configuration-variable#the-authorization-token-authtoken) | the authorization token for this configuration                                                                              |
| [isFinished](/docs/configurator-logic/configuration-variable#isfinished)                       | will be `false` for new configurations and `true` for configurations that have already been finished                        |
| [isViewMode](/docs/configurator-logic/configuration-variable#isviewmode)                       | will be `true` when the configuration is opened in a read-only mode                                                         |
| hasQuote                                                                                       | will be `true` if a quote is linked with this configuration, otherwise `false`                                              |
| editUrl                                                                                        | a URL with which this configuration can be edited                                                                           |
| copyUrl                                                                                        | a URL that will create a copy of this configuration                                                                         |
| viewUrl                                                                                        | a URL for viewing this configuration in a read-only [view mode](/docs/configurator-logic/configuration-variable#isviewmode) |
| insightsUrl                                                                                    | a URL to the insights of this configuration                                                                                 |
| insightsOverviewUrl                                                                            | a URL to the insights overview page of this configurator                                                                    |
| leadUrl                                                                                        | a URL to an already created lead of this configuration, otherwise empty                                                     |
| leadOverviewUrl                                                                                | a URL to the leads overview page                                                                                            |
| quoteUrl                                                                                       | a URL to an already created quote of this configuration, otherwise empty                                                    |
| quoteOverviewUrl                                                                               | a URL to the quotes overview page, includes the correct quote hub name if a quote has already been created                  |

### Functions

| name                                                                                   | description                                                                                        |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [getParameter(name)](/docs/configurator-logic/configuration-variable#getparametername) | returns the value of a URL parameter                                                               |
| getImage(name)                                                                         | returns the Image which was uploaded under the given name (or `Empty` if nothing was uploaded yet) |
| getFile(name)                                                                          | returns the File which was uploaded under the given name (or `Empty` if nothing was uploaded yet)  |

### The Authorization Token (AuthToken)

Every configuration is protected with an authorization token. Only those that can provide this secret text are allowed to edit the configuration.

The AuthToken is part of the EditUrl of a configuration.

If you want to enable your users to continue a configuration at a later time or after they have put it into a shopping cart, we recommend you use the EditUrl of the configuration.

It should be pretty rare that you have to directly work with the AuthToken yourself.

### isFinished

Once a configuration has been put into a shopping cart or, more generally speaking, has been completed (or "finished"), you may want it to behave slightly differently when edited again. For example, you may want to change the text of a button from "order now!" to "save changes" when a customer opens a configuration from his shopping cart.

You can use the configuration.isFinished property to this end, as it will return true when the current configuration has already been completed at some point in the past.

### isViewMode

Configurations can be opened in a read-only mode that allows users to view the configuration, but not modify it in any way.
Component values can be changed in this mode, but the changes will not be saved.

Certain actions like finish, share or uploading files are not allowed in view mode.
If attempted, a warning dialog will be displayed that provides the option to create a copy of the configuration instead, which can then be edited.

Configurations on the [Insights](/docs/configuration-insights/configuration-insights-), [Leads](/docs/quote-management/how-to-work-with-quotes#leads) or [Quotes](/docs/quote-management/getting-started-with-quotes) pages will by default open in view mode.
Within a configurator, you can obtain the URL for viewing a configuration with `configuration.viewUrl`

You may rely on `isViewMode` as an indicator to display the configurator in a read-only state, e.g. hiding certain controls or optimizing the UI for viewing instead of editing.
If you would like to provide users with a way to continue editing, you can [restart the configuration](/docs/configurator-ui-ux/controls/configurator-control#restart-configuration) to create an editable copy of it.

### getParameter(name)

When you embed your configurator in your website, you can add URL parameters to the embed URL. These parameters can then be used to alter how the configurator looks or works. For example, you could pass the SKU of a product, the current language of the website or shop-system specific information to your configurator.

In your configurator, you can obtain the value of an URL parameter with the getParameter function. This function will either return a text value or empty if the parameter has not been used:

```hive
// pass language by parameter, use "en" when parameter is not used
configuration.getParameter("language") or "en"

// pass ID of a shopping cart by parameter
// be sure to provide a fallback value if the parameter is not used (e.g. "")
// ToNumber() might also return Empty if the parameter is not a number
(configuration.getParameter("cartId") or "").toNumber() or 1
```

---

## Configurator & presets variable

Everything you create in the configurator editor is either directly or indirectly connected to your configurator. With the configurator variable you can access all these things and additional information about your configurator.

### Properties

| name        | description                                                                                                |
| ----------- | ---------------------------------------------------------------------------------------------------------- |
| isDraft     | will be `true` inside a draft preview and `false` in a published or staged configurator or preview thereof |
| isPreview   | `true` in a configurator preview, `false` anywhere else                                                    |
| isStaging   | `true` in a staged configurator, `false` anywhere else                                                     |
| isPublished | `true` in a published configurator, `false` anywhere else                                                  |
| startUrl    | the URL for starting a new configuration based on the default preset                                       |
| components  | a map of all the components you have created                                                               |
| owner       | the owner of this configurator, can represent the company or a distributor                                 |
| company     | the company that owns this configurator, regardless of the current owner                                   |

You can access these properties like so:

```hive
configurator.isPublished
```

`owner` and `company` both hold tenant data (see the properties table below), but they are not the same thing: the `owner` is the company or distributor that the configurator is currently opened as, while `company` always refers to the company, even when a distributor is the current owner.

Once you have obtained the owner of the configurator, you can use its properties (e.g. for applying custom styles or similar). But keep in mind, the owner depends on the tenant (company or distributor) where the configurator is opened and is not connected with the currently active user. For this, please utilize the [user](/docs/configurator-logic/user-variable) variable.

| name          | description                                                                     |
| ------------- | ------------------------------------------------------------------------------- |
| name          | the reference name of the company or distributor                                |
| displayName   | the display name of the company or distributor                                  |
| isCompany     | `true` if the owner is a company, otherwise `false`                             |
| isDistributor | `true` if the owner is a distributor, otherwise `false`                         |
| logo          | the `FileUrl` of the company or distributor logo, `Empty` if no logo is defined |

You can access these properties like so:

```hive
configurator.owner.name
```

```hive
configurator.owner.logo?.url
```

### Methods

| name              | description                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------------- |
| getUsers()        | lazily loads all users of the company, returned as a map of users keyed by user `id`          |
| getDistributors() | lazily loads all distributors of the company, returned as a map of distributors keyed by name |

```hive
configurator.getUsers().get("some-user-id")
```

The users and distributors returned by these methods have the same properties as the [user](/docs/configurator-logic/user-variable) variable and `configurator.owner`/`company`, with two exceptions: a user returned by `getUsers()` doesn't have `isLoggedIn`, and a distributor returned by `getDistributors()` doesn't have `isCompany`/`isDistributor`.

### Accessing components

In addition to the properties above, you can also access any of your components with the configurator variable. For example, configurator.Price would refer to a "price" component. Of course, you can also just write price to work with that component – usually.

You may end up in a situation where something else is also called "price" and simply writing price will return that thing. This can happen for example in a graphic component, when you give one of your visuals the name "price". Inside that component, "price" will then refer to your visual and not the price component. To fix that problem, you can write configurator. Price to get to your component.

:::warning
Super special case: if you end up in a situation where something else is called configurator, the solution above won't work. You can't use the configurator variable because that other thing is also called "configurator".
:::

The best way to avoid this problem is not to call anything "configurator" – but in case you have to, there's a special keyword to help you out: @top. This rarely used keyword is always reachable and enables you to access things "at the top", like the configurator variable. For example, @top.configurator.Price will always refer to the "price" component, no matter what.

### Presets

You can work with the presets that you have created for your configurator by using the presets variable. Similar to configurator, you can access any preset by name by writing presets.MyPreset (where "MyPreset" is the name you've given your preset). However, in this case the presets variable is mandatory – "MyPreset" alone will not return your preset.

Additionally, the presets variable has these built-in properties:

| name    | description                                                    |
| ------- | -------------------------------------------------------------- |
| current | returns the preset on which the current configuration is based |
| default | returns the default preset of your configurator                |
| all     | returns a map of all the presets you have created              |

Once you have obtained a preset, you can use its properties:

| name     | description                                                         |
| -------- | ------------------------------------------------------------------- |
| id       | the unique identifier of this preset                                |
| startUrl | the URL for starting a brand-new configuration based on this preset |

### Example

To get the URL to start a new configuration based on the same preset as the current configuration:

```hive
presets.Current.StartUrl
```

:::info
Just like configurator, the presets variable also lives "at the top" – meaning you can use @top.presets to always reach it, even if something else is called "presets".
:::

---

## Editor basics

### Components and groups

On the left side of your configurator, you will find a list of components and groups. Each component is part of a group. For a better overview of your configurator, split your components into useful groups. Always use meaningful and unique names for your components and their groups.

Components are basically like variables in programming - they contain values and logic. The values can be of different types and can also contain resources such as images or 3D files. There are also different types of components for all the different use cases. Components are the heart of a configurator since all data and logic are maintained there.

:::info
The user interface for the configurator is also built within one specific component - the design component.
:::

### Signals and Slots

To connect components and UI controls we use signals and slots - also known as SigSlos. For example, you can display the data you get from your component in a control in the UI. It also works the other way around - data that the user puts into controls in the configurator will be saved in components if the corresponding SigSlo exists.

An example of a SigSlo: if you click on a button, a value of a component should be changed.  
Signal: click on the button  
Slot: change the value

If you create a SigSlo always think if there is a SigSlo in the other way back. If the value of the component can be changed at any other point, has it any effect on the button?

You get a list of all your SigSlos on the right side of your design component. This is also the only place where you can create a SigSlo. To add SigSlo's you can use the button at the right top of the Design Page or you click on a control and open the SigSlo window from there.

:::info
SigSlos can connect a component with a control, a control with a component, and also two controls with each other. You cannot connect two components with a SigSlo.
:::

### Presets

Within the editor, you can open the preset menu at the top of the page. There you can add predefined configurations which can be used as starting points for your configurator. These presets can be accessed through URL parameters.

A possible use case could be that all different models of a product get their own preset. The different links are then integrated into the customer's website. Configurator users can now start their configuration with a predefined model if they want to.

### Publishing

On the top of the editor page, you can also find the "publish" button. With this button, you can publish your configurator draft. When clicking on this button, a pop-up window will show where you can add notes. In these notes, you should summarize the changes that you implemented to the configurator. They will be shown in the history and help to define the different versions of a configurator.

:::info
When you publish a draft, it will be added to the history automatically and will no longer appear in the draft table in the dashboard.
:::

### Published link and preview

While editing a configurator in a draft you can check your changes in the preview link. It is marked with a thin orange header section and it cannot be used for integration on a website. Checkouts cannot be tested in a preview.

On the other hand the published link has the full range of functions and is used for the integration. It is not marked in any way and just contains the actual configurator design. Checkouts can be executed in this link. Another difference is the configuration ID, which is only generated for configurations in a public link. While opening a preview link no ID will be generated and the configurations will not be saved in the configurations table.

---

## File upload & handling

### General

You can allow users of your configurator to upload files. These files will be permanently linked to the current configuration and can be accessed in Hive or Custom Code and viewed in the [Configuration Insights](/docs/configuration-insights/configuration-insights-).

Files that are uploaded into a configuration are called "Configuration Files" or `CfgnFiles` for short.  
They can either be uploaded with Signals & Slots (SigSlos) or with Custom Code.

### File Upload with SigSlos

Uploading a file is very easy to achieve:

![image.png](<https://docs.combeenation.com/assets/images/image%2865%29-5cb6fa713ae3140f8e72d1e7964bf4d5.png>)

1.  Select any `Signal`. E.g. `Clicked` of a `Button`
2.  As slot choose `Configurator` which is the top-most element of the controls
3.  Select one of the Upload slots
    - `Upload image`: Only images are allowed. Unsupported formats will not be uploaded
    - `Upload file`: Any file can be uploaded
4.  Enter a unique name for your file
5.  [Optional] Enter a `Download name`, which will be the filename when someone downloads the file

Afterwards you can test it right away in the Preview of your configurator.

1.  Upload an image with the button
2.  Open the watches on the right
3.  Enter `Configuration.getImage("myImage")`
    - `myImage` has to be name you entered in the SigSlo `Name` parameter
4.  Afterwards you should see an JSON object below with the `Url` and some metadata (width, height, etc.)

### Using files in Hive

Hive provides two functions to retrieve the uploaded file:

- `configuration.getImage("myImage")`
- `configuration.getFile("myFile")`

If no file has been uploaded yet (or there is none with that name) `Empty` will be returned. Therefore it's required to do an empty check before accessing properties like the url.

```hive
var myImage = configuration.getImage("myImage");
if myImage is empty then
  "url empty"
else
  myImage.url
end
```

Alternatively, you can also obtain a table of all files with `configuration.GetFiles()`.  
This table will contain all files that have been uploaded so far and will update automatically.
You may also query the table inside a `TableComponent`, e.g. to only return files with a specific name or prefix.

```hive
from configuration.GetFiles() select all
filter .name.take(4) = "img_"
```

A CfgnFile has the following properties:

- `DisplayName` is the display (or "download") name that you specify when uploading the file
- `Size` holds the file size in bytes
- `Extension` holds the file extension as text (e.g. `jpg`)
- `Url` holds the URL of the file

Files returned by `getImage()` have an additional `Image` property that contains a Hive image.

If you upload a file as an image, then you can only access it with the `getImage` function.  
Trying to access an image with `getFile` will result in an error (and vice versa).

If you upload a file with the name `myFile` then `getFile("MyFile")` will not return it.  
You must use the exact same name: `getFile("myfile")`

### File Upload with Custom Code

Custom code allows you to upload programmatically created files like screenshots from a 2D or 3D preview, datasheets or similar.  
The available functions can be found under the namespace `CfgnFiles`.  
All functions can be awaited and will directly return the url of the uploaded file.  
Besides that, files are also available in Hive as explained in the previous chapters.

##### Example - Upload screenshot

```ts
const uploadResult = await CfgnFiles.uploadImages({
  screenshotTopView: { file: myScreenshotFile, displayName: 'top-view-2024-09-16' }
});

if (uploadResult.success) {
  console.log(uploadResult.urls.screenshotTopView);
}
```

##### Example - Upload dummy file

```ts
await CfgnFiles.uploadFiles({
  fileText: {
    file: new File(['Lorem ipsum'], 'dummy.txt')
  }
});
```

#### Creating PDF files

With the function `CfgnFiles.createPdfFromHtml()` you can create a PDF file from any HTML string.

For details on how to create the HTML see: [Create PDF from HTML content](/docs/configurator-ui-ux/customjs/create-pdf-from-html-content#creating-the-html)

##### Example - Create PDF from HTML

```ts
const resultUrl = await CfgnFiles.createPdfFromHtml('bomPdf', '<html><body>Hello world content</body></html>', 'cfgr-bom-' + Date.now(), {
  displayHeaderFooter: true,
  headerTemplate: '<html><body>My Header</body></html>'
});
console.log('url is: ', resultUrl);
```

##### Example - Create PDF from asset

The latest and suggested way of creating a PDF is based on a [Pdf asset](/docs/asset-management/pdf-asset). You can configure the PDF in the asset editor and pass flexible context data to the final PDF creation method.

```typescript
const context = {
  company: {
    logo: 'MyFolder.MyFinalLogo'
  }
};
const resultUrl = await CfgnFiles.createPdfFromAsset('MyBundle', 'MyFolder.MyPdfAsset', context, 'MyCfgnFileName', 'MyCfgnFileDisplayName');
console.log('url is: ', resultUrl);
```

### Configuration Insights

Insights are only available for published or staged configurators.  
Configurations of a preview can't be found under Configuration Insights.

All the uploaded files of a configuration are permanently stored and can be viewed in the `Configuration Insights` afterwards.  
To view them, simply open the `Configuration details` of a Configuration and expand the `Files` section.

![image.png](<https://docs.combeenation.com/assets/images/image%2866%29-632b59110a5a9ae11408aa856369963d.png>)

### Temporary configuration files

Configuration files have an upper limit per configuration. If you only need files temporarily during a configuration - and they don't need to persist after it ends - use **temporary configuration files**.

With them you can upload up to 10x of your regular cfgn file limit within a single configuration session.

**Example use case:** You want to take multiple screenshots of your 3D model and embed them in a generated PDF. Since the PDF already contains the images, the original screenshot files don't need to be persisted.

##### Example upload multiple files

```ts
const myFiles = [new File(['Hello World'], 'hello.txt'), new File(['Hello World2'], 'hello2.txt')];
uploadTempFiles(myFiles);
```

##### Example upload file from file dialog

```ts
const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
fileInput.addEventListener('change', async () => {
  if (!fileInput.files) return;
  const result = await uploadTempFiles(Array.from(fileInput.files));
  // result: contains the uploaded file URLs in the same order as the input files
  console.log(result);
});
```

---

## Hive introduction

Hive is the language that is used to express the rules and logic of every Combeenation configurator. Hive was specially developed for mapping product logic in our platform. It can be used in almost all properties of a component to determine a suitable value for the property - these expressions are also called rules.

A Hive rule can be a simple constant value or an extensive formula. All components and their properties can be used in hive rules.

### Why a separate programming language?

Why can't product logic be expressed in a widely used language such as JavaScript? By developing our own language, we can seamlessly integrate it into our components and adjust and optimize the syntax - the grammar and rules that make up the language. The goal here is to make the mapping of product logic as simple as possible. Tabular data can be displayed directly with Hive expressions.

Another important aspect of Hive is how rules are translated internally. Unlike in common programming languages, when writing Hive rules, you don't have to worry about when to execute them. The system automatically detects which rules are affected (directly or indirectly) by user input and executes them in the correct order. This is not only convenient but also efficient.

:::info
Rules that are not affected by a current change are not executed.
:::

---

## Hive language

### Types

Each value in Hive is of a certain type, which determines what you can do with that value. It is a statically typed language, unlike JavaScript for example. In short, this means that the language is very strict about which expressions you can combine. For a subtraction like `100 - 50`, only numbers may be used - if you try to replace an operand with a text, the system shows an error. The aim here is to avoid mistakes and to point out a problem to the user immediately so that it is not discovered during the live operation of the configurator. These are some of the most essential types in Hive:

- Number
- Text
- Logic
- List
- Record

:::info
Each of these types has its own article, with use cases and detailed descriptions.
:::

### Comments

Comments allow you to write down helpful information directly in your rules. They have no effect whatsoever on a rule itself, but they can help you or others better understand what the rule is all about.

To write a comment, start with two slashes `//` and then write whatever you want. This kind of comment takes up the remainder of the line.  
To write a comment over multiple lines, start with `/*` and end with `*/` when you're done

```hive
// this is a single-line comment

/*
this comment
spans over
multiple lines
*/
```

### Variables

Use the `var` keyword to assign a name to an arbitrary value in order to re-use it in your rules:

```hive
var myValue = Input or 1;
if myValue> 10 then
  10
else
  myValue
end
```

At present, the value of a variable cannot be changed after the variable was initialized.

The declaration of a variable must be separated with a semicolon `;` from the next expression.

#### Scope

A variable can only be used in the “scope” it is declared in, or any nested scopes. For instance, a variable declared in one rule cannot be used in another rule.

The `then` and `else` branches of an `if` expression each form their own scopes, which means that a variable declared in one of these scopes is not available outside the `if`.

A variable declared in an inner scope will have higher precedence than other named entities from outer scopes. What this means is that a variable with the name “x” will hide other variables (or components) that are also called “x”.

```hive
var x = 1;
if true then
  var y = 2;
  y
else
  var x = 2; // this is allowed; x now has a different meaning in the else-scope
  x + y // ERROR! y is not available here, it belongs to the then-scope
end;
x  // this is the x defined in the first line, it's still set to 1
```

### Input and empty

Some components allow the use of a special variable in their Hive rules: `input`. This primarily refers to user input. For example, if you connect a value component with a UI element such as a text box, the text that a user writes in this text box ends up in the `input` variable. The value of a component cannot be changed directly, only its `input` can. The `input` value is also saved automatically, so we don't have to worry about that.

By default, the type of `input` is identical to that of the component. For example, if a component produces a number, then its `input` will have the type number too.  
The [value component](/docs/configurator-logic/components/value-component) allows you to choose a specific type for `input`.

The simplest possible way to store a value in a configurator is to create a value component with just this code:

```hive
input
```

However, unless you assign an initial value to `input`, it will be `empty`.  
The `empty` value is similar to `null` in other programming languages and represents the absence of a meaningful value. It cannot be processed further in a meaningful way and essentially just exists to signal that a real value is missing.

:::warning
In almost all cases, you should strive to avoid rules that return `empty` !
:::

There are multiple ways to check if something is `empty`, the simplest being the `or` operator. It checks if the left operand is `empty` and if it is, it returns the right operand as result:

```hive
input or 1
```

This will return the `input` value unless it is `empty`, in which case `1` will be returned. You can use any value as the right operand, as long as it is of the same type as the left operand. For example, if `input` is a text, the above example would not work – but `Input or "hello"` would.

You can also check for `empty` with the [if expression](/docs/configurator-logic/the-if-expression):

```hive
if input = empty then
  "No value here yet!"
else
  input
end
```

### Global Scope and Naming Conflicts

There are a number of global variables that you can use in your rules: [configurator](/docs/configurator-logic/configurator-and-presets-variable), [presets](/docs/configurator-logic/configurator-and-presets-variable#presets), [configuration](/docs/configurator-logic/configuration-variable) and [user](/docs/configurator-logic/user-variable).

Should you find yourself in a situation where one of these variables is hidden by a component or local variable of the same name, you can use the `@top` keyword to access it:

```hive
@top.user.mail
```

Similarly, you may be unable to access one of the built-in types like [Math](/docs/configurator-logic/hive-types/math-type) or [Viewer3d](/docs/configurator-logic/hive-types/viewer3d-type) if you used their name for something else.  
These types belong to the `Hive` module, so you can explicitly access them by prefixing the module name:

```hive
Hive.Math.Pi
```

### Optional chaining operator (?.)

The optional chaining operator (also known as conditional access operator) `?.` allows you to access a property or function of something that could potentially be `empty`, without causing an error:

```hive
// instead of this:
if MyRecord <> empty then MyRecord.Name else "" end

// you can write:
MyRecord?.Name or ""
```

The `?.` operator checks if the left operand is `empty` and if so, returns `empty` itself. Otherwise it returns the field (or calls the function) on its right-hand side.

---

## Hive Queries

A query lets you load, filter, sort and reshape a collection of data with Hive code. Queries are most commonly used to load data from a [data source](/docs/asset-management/data-source-asset/basics) via a [table component](/docs/configurator-logic/components/table-component), but they can also run standalone in any rule, directly against a list or map.

Let's assume our data source is called `BikeParts`, then the simplest query we could write is:

```hive
from BikeParts select all
```

This will load all records from the data source and include all its columns. The same syntax works on a list or map component, or standalone in any rule – the result always has the same kind of collection as the source, i.e. a table stays a table, a list stays a list and a map stays a map.

We can choose to only load specific records and columns too:

```hive
from BikeParts select {
  .partNumber,
  .name,
  .price
}
filter .partNumber > 100
```

This will produce a table that only has 3 columns – `partNumber`, `name` and `price` – and it will only contain parts that have a `partNumber` of 100 or greater.

:::note
Each column name must start with a period (`.`)
:::

### The query item

Every query works with a "query item" – the single record, list item or [MapEntry](/docs/configurator-logic/hive-types/map-type#mapentry) that is currently being looked at while filtering, sorting or projecting.

By default, the query item is named `all`, i.e. `from source` is short for `from all in source`. This is why you can write `...all` or `all.column` – you're simply referring to the query item by its default name.

You can also give the query item your own name:

```hive
from item in BikeParts select [ item.name ]
```

Here we named the query item `item`; note that `all` is not available anymore in this case, you have to use `item` instead.

The ambient member syntax (`.column`) is a shorthand for `all.column` (or whatever name you've given the query item). It works no matter what kind of source you query – a record's columns in a table, the item itself in a list, or `.key`/`.value` of a [MapEntry](/docs/configurator-logic/hive-types/map-type#mapentry) in a map.

### Filtering Data

The filter of a query has no fixed syntax; you can write any Hive code you want, as long as it results in either `true` or `false`.  
The filter will be run for each item of the source. When it results in `true`, the item will be loaded, otherwise it won't.  
You can access all columns of the query item in your filter, but also components (though there are some limitations for components).

Here is an example of a more advanced filter:

```hive
from BikeParts select all
filter
  if BikeCategory <> "" then .category.toLower() = BikeCategory else true end
  and .netWeight + AccessoryWeight < MaxWeight
```

A few things to note:

- a filter can be made optional by using an `if/then/else` expression
  - in the example we only filter by `.category` when the `BikeCategory` component is not an empty text
  - by using `true` or `false` in the `else` branch of an `if`, we can include or exclude the record
  - we could also rewrite the category filter to not require an `if/then/else` expression like this:
  - `(BikeCatogery = "" or .category.toLower() = BikeCategory)`
- you can call functions on column values or use them in calculations:
  - we convert the `.category` to lower-case before comparing it with `BikeCategory`
  - we calculate the sum of `.netWeight` and the `AccessoryWeight` component and compare the result with `MaxWeight`

:::warning
**Limitations:** there are some types of components (or Hive values, more general) that cannot be used in queries, or only in specific ways. See the [Limitations](/docs/configurator-logic/hive-queries#limitations) section for details.
:::

### Projecting Data

Data can not only be filtered, it can also be molded to fit your use case: the `select` clause determines both the contents and the kind of collection that is produced.

- `select { ... }` produces a **table**, e.g. `select { .nr = .partNumber, .name }`
- `select [ expr ]` produces a **list**, e.g. `select [ item * 3 ]`
- `select [ key : value ]` produces a **map**, e.g. `select [ .id : .name ]`

#### Table projections

```hive
from BikeParts select {
  .nr = .partNumber,
  .name,
  .price = .price * if .onSale then 0.8 else 1 end,
}
```

A few things to note:

- if you want to use a different name for a column, you can just assign that column to a new one
  - in the example, we create a column `nr` that will hold the value of the `partNumber` column
  - **Note:** column names of the resulting table must be unique; you cannot have 2 columns with the same name
- you can adjust the value of a column; in the example we lower the `price` by 20% when the `onSale` column is true
  - **Note:** modified columns are not available in filters or when modifying other columns. For instance, you cannot use `.nr` in a filter or the `.price` calculation (you must use `.partNumber`). Similarly, when you type `.price` you will receive the value stored in the data source, not the lowered price! (_this might become available in a future update_)
- when adjusting a column value, you can use any Hive feature you want (\*) – there is no specialized syntax
  - (\*) the same limitations as for filters apply, see the [Limitations](/docs/configurator-logic/hive-queries#limitations) section

If you want to use all columns of the source and add your own, you can use the spread operator (`...`):

```hive
from BikeParts select {
  ...all,
  .formattedPrice = .price.toNumber("0.00 EUR"),
}
```

The spread operator can target any expression, not just `all` – for example `... .value` to spread a map's values, or `...item.field` to spread a field of an object in a list. It only works in table projections.

A field introduced by a spread can be overridden by an explicitly declared column, or by a later spread – the overriding column always wins and determines the field's name, type and value, even if it appears before the spread in your code. The **position** of the field in the resulting table is always determined by whichever spread or column introduced it first; spread fields simply "fill the gaps" between your explicitly declared columns.

#### List projections

```hive
from item in BikeParts select [ item.name ]
```

This produces a list of the `name` column of every part.

#### Map projections

```hive
from BikeParts select [ .partNumber : .name ]
```

This produces a map, using `partNumber` as key and `name` as value.

### Sorting Data

You can change the order in which items are returned by a query by sorting them by one or more values:

```hive
// sort first by category, then by net weight
from BikeParts select all
sort by .category, .netWeight desc
```

The `sort by` statement must come after a `filter` (if there is one).  
By default, values are sorted in ascending order. You can add `desc` after a sort expression to sort in descending order (you can also add `asc` to clarify your intent).

While the value to sort by will typically involve a column, you can also write more complex expressions.

```hive
// sort first by rounded weight, then sort so parts without a description come at thet end
from BikeParts select all
sort by
  .netWeight.round(),
  (if .Description = "" then 0 else 1 end) desc
```

Note that a sort value must be a `Number`, `Text` or `Logic` value.  
Furthermore, you must put complex sort expressions in parenthesis `()`, as in the example above (a column name or function call works without `()`, but anything more advanced requires them).

:::tip
`Text` is sorted in a case-sensitive manner, but you can achieve a case-insensitive ordering by converting the text to all-upper or all-lower case first: `sort by .myTextColumn.toUpper()` .
:::

### Limiting the number of rows

You can optionally restrict how many rows can be returned by a query or skip over a number of records:

```hive
// ignore the first record, then return up to 1000 records
from BikeParts select all
sort by .category
skip 1
take 1000
```

**NOTE:** this feature is best used in combination with `sort by`, as the order of rows in your data source may be subject to how it is imported. If you e.g. use a workflow to automatically update a data source, the order of rows may not be guaranteed.

Both `skip` and `take` expect a `Number`. This can be a literal value like `1` or an expression that involves a component like `MaxRows` – but you cannot use columns, as the limits affect the entire query and a column value belongs to a specific record.  
Similar to `sort`, you must put complex expressions in parenthesis `()`.

### Limitations

When talking about what is permitted in a query (i.e. in the filter or when calculating a column value), we must differentiate between 2 areas:

- the parts of a query that involve a column and are evaluated by the query engine – **these have limits**
- the parts of a query that do _not_ involve a column, which are evaluated beforehand – **these are limitless**
  - we call these parts "**query parameters**"

For instance, it's currently not allowed to use a record component in a filter, because sending an entire record table to the query engine would often be expensive and slow down your query. However, a record component can still be used in a query parameter – consider these two cases:

```hive
// not allowed
// a column value is used in Get(), thus the entire component is needed to evaluate the query
filter myRecordComponent.Get(.partNumber).Price < MaxPrice

// allowed
// everything to the right of (>) is a query parameter, as it doesn't involve a column value
// the query parameter is a simple number that can be calculated before the query itself is run
filter .price > myRecordComponent.Get(SelectedPartNumber).Price
```

The **key takeaway** is that you don't have to worry about limits in query parameters, only in code that directly involves column values. The system automatically tries to run as much code of the filter as possible before the query is started (i.e. turning those parts into parameters).  
💡 If your query results in an error due to limits, try to restructure it so that the parts highlighted by the error do not depend on column values.

**These types and features can currently be used in filters:**

- Number: all operators (`>`, `>=`, `<`, `<=`, `=`, `<>`, `+`, `*`, `-`, `/`, `mod`, `^`) and functions (`toText`, `round`, `floor`, `ceiling`, `truncate`, `atLeast`, `atMost`)
- Text: all operators (`+`, `=`, `<>`, `~=`, `*`) and functions (`length`, `contains`, `skip`, `take`, `replace`, `toUpper`, `toLower`, `toNumber`)
- Logic: all operators (`not`, `and`, `or`, `=`, `<>`)
- Lists: all functions (`length`, `get`, `contains`)
- `if`/`then`/`else` expressions
- variables
- optional chaining operator `?.`

---

## Hash type

The hash type provides functions for generating hash codes with various hashing algorithms.

### Usage

To use any of the functions described on this page, you must prefix them with the hash type name:

```hive
Hash.computeSha256("some value")
```

### computeSha256 function

Generates the SHA256 hash of the given text (first parameter). The second parameter defines in which format the generated hash will be returned.  
Syntax: computeSha256(value, isBase64Encoded)

If it is true (which is the default value) the hash will be returned base64 encoded.  
If it is false the hash will be returned hex (base16) encoded.

```hive
Hash.computeSha256("")                  // 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Hash.computeSha256("some value")        // qz0H8xacy9DtbEtF3iFRn5+TjHLSQSSZiquUnOg7tRs=
Hash.computeSha256("", false)           // e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Hash.computeSha256("some value", false) // ab3d07f3169ccbd0ed6c4b45de21519f9f938c72d24124998aab949ce83bb51b
```

### computeHmacSha256 function

Generates the HMAC SHA256 hash of the given text (first parameter) with the given. The second parameter is the secret text which is used to generate the hash. The third parameter defines in which format the generated hash will be returned.  
Syntax: computeHmacSha256(value, secret, isBase64Encoded)

If it is true (which is the default value) the hash will be returned base64 encoded.  
If it is false the hash will be returned hex (base16) encoded.

```hive
Hash.computeHmacSha256("", "")                             // thNnmggU2ex3L5XXeMNfxf8Wl8STcVZTxscSFEKSxa0=
Hash.computeHmacSha256("some value", "some secret")        // gcOIOIoay4FP/bY7cDX/3xf8JheKkEwUWmL1cyVTdLg=
Hash.computeHmacSha256("", "some secret", false)           // f6ea2d6efc05da393de3fa47d17eda28ae5e25197501e889e4d995f8e53ea8f6
Hash.computeHmacSha256("some value", "some secret", false) // 81c388388a1acb814ffdb63b7035ffdf17fc26178a904c145a62f573255374b8
```

---

## JSON type

The JSON type allows you to store arbitrary JSON content, e.g. for use in Custom Code or to pass it on to external APIs.

:::info
Currently, there is no way to interact with the JSON content. We plan to add `parse()` functions to convert JSON content to objects, lists, etc.
:::

### JSON literal

To create a JSON value in a Hive rule, use the JSON literal:

```hive
json`{
  "sku": "12345",
  "color": "red",
  "price": 19.99,
  "tags": [
    "clothing",
    "sale",
    "new"
  ],
  "availability": {
    "in_stock": true,
    "quantity": 50
  }
}`
```

Inside the backticks, you can write or paste raw JSON without having to make any formatting changes.

:::info
At present, there is no way to access components inside the JSON literal, but we plan to add an interpolation feature for this.
:::

### Usage

To store arbitrary JSON content, create a new `ValueComponent` with an `Input or` rule and use a JSON literal as fallback value:

```hive
Input or json`{}`
```

JSON values can also be part of typed objects, allowing you to create semi-structured models.
For example, you can store a JSON value in an object passed to [`OnFinish.SetOutput`](../../integrations-and-api/configuration-finish):

```hive
OnFinish.SetOutput({
  color: SelectedColor,
  price: unitPrice * Amount,
  pdfContext: if user.isLoggedIn then MyJsonComponent else json`{}` end
})
```

---

## List type

A list contains multiple values of the same type. To create a list you just have to wrap a number of values in square brackets.

a list of numbers: `[ 1, 2, 3 ]`  
a list of text: `[ "red", "green", "blue" ]`

You can declare lists in any of your rules. If you want to use the same list in various places, you can for example put it in a value component.

:::info
The items of a list are ordered and can be accessed by their index / position in the list.  
**The first item has the index 1.**
:::

### Input

A list can also be used as input for a rule. It works the same for them as for any other value:

```hive
Input or [1, 2, 3]
```

In this example, if `input` contains a list, that list is used – otherwise the list `[1,2,3]` is used.

**This example only works** when `input` is a list. By default, the `input` is of the same type as the rule, so the easiest way to change the type of `input` is to change the outcome of the rule. For example, start with the rule `[1, 2, 3]` to turn the rule (and its `input`) into a list, then you can change the rule to `Input or [1, 2, 3]` .  
In a value component, you also have the option to change the type of the `input` directly with the input type field. In this example, the required type would be `List<Number>`

Input lists can be modified with signals & slots in various ways: you can add, remove or change items or replace the entire list.

:::info
Signals & slots can only modify an `input` list, not a list declared in a rule.

If the `input` is `empty`, it is not considered a list and thus you cannot add items to it. Therefore, if you want to be able to modify a list `input` with Signals & slots, you should provide a default `input` list – an empty list `[]` works too.
:::

### Empty Lists ([])

You can create a list without any items in it with a pair of square brackets (`[]`).

:::info
Empty lists only work in places where the type of the list can be inferred!
:::

A common use case is to use an empty list as starting point of a value component. First, ensure that the component returns a list of some kind, e.g. the rule `[1]` would produce a list of numbers. Now that the component and its `input` are lists, you can use the empty list syntax in your rule:

```hive
Input or []
```

The empty list will be of the same type as the `input`, a list of numbers in our example. This also works in more complex scenarios, for example if you are working with a list of records the following pattern may be useful:

```hive
Input or
if false then
  // sample format
  [
    {
	  id: "item-1",
	  name: "this is an example for a list of records",
	  price: 13.37,
	  description: "these values will never be used (due to 'if false'), they are just examples",
	  options: [ 3, 4, 5],
	  language: [ "de", "en" ],
	  parts: [{
		id: "part-1",
		name: "nested lists and records also work",
		price: 0.815
	  }]
	}
  ]
else
  []
end
```

In this example, we have a list of records that describe some imaginary products. The list is meant to store all records (products) that a user chooses, so we have to use the `input` variable for that. As starting point, we want to use an empty list. Now we have to describe the record in some way. We could directly write the type into the input type field (which would start like this: `List<Record<{id=Text,name=Text,price=Number,...`) but that is not very convenient.

Instead, we can provide an example record that will not be used, but allows the system to infer the type of the record and list that we want to use. To achieve this, we can simply put the example record into an `if false then` expression. The empty list in the `else` case will then automatically be a list of such records too.

Initially, or when we want to add new columns to our record, or change existing ones, we can simply change the example record and the type of the empty list and the rule itself will update automatically. **There is one caveat though**: we must temporarily remove or comment the first line in the example (`Input or`), so that the type of the `input` variable can be updated too. Otherwise it will remain set to the current type and cause an error.

### Functions

| name                                                                         | description                                        |
| ---------------------------------------------------------------------------- | -------------------------------------------------- |
| [length](/docs/configurator-logic/hive-types/list-type#length)               | gets the number of items in the list               |
| [get(index)](/docs/configurator-logic/hive-types/list-type#getindex)         | gets the item at the specified index               |
| [contains(item)](/docs/configurator-logic/hive-types/list-type#containsitem) | returns true if a list contains the specified item |
| [concat(list)](/docs/configurator-logic/hive-types/list-type#concatlist)     | combines two lists                                 |

#### length

Returns the number of items in the list.

| Example              | Result |
| -------------------- | ------ |
| `[1, 2, 3].length()` | 3      |

---

#### get(index)

Returns the item at the specified index.

| Example             | Result               |
| ------------------- | -------------------- |
| `[1, 2, 3].get(0)`  | 1 (same as `get(1)`) |
| `[1, 2, 3].get(2)`  | 2                    |
| `[1, 2, 3].get(-1)` | 3                    |
| `[1, 2, 3].get(99)` | 3                    |
| `[1, 2, 3].get(-9)` | 1                    |

Any numerical index returns a list item, based on these rules:

- The first item has index 1, but 0 also returns it.
- When the index is negative, items are counted from right to left.
- When the index is greater than the number of items in the list, it is automatically capped.
- If the list contains no items, `Empty` is returned. Check the length of the list to explicitly handle this case.

---

#### contains(item)

Returns true if a list contains the specified item.  
When looking for items, `contains` uses the default equality operator as defined by the type of items in the list.  
In the example, the list contains text items and by default texts are compared in a case-sensitive fashion. That is why "Blue" cannot be found, but "blue" can.

| Example                                       | Result  |
| --------------------------------------------- | ------- |
| `[ "red", "green", "blue" ].contains("red")`  | `true`  |
| `[ "red", "green", "blue" ].contains("Blue")` | `false` |

#### concat(list)

Combines two lists. This does not modify the existing list, but instead returns a new one.

| Example                                 | Result                       |
| --------------------------------------- | ---------------------------- |
| `[ "red", "green" ].concat([ "blue" ])` | `[ "red", "green", "blue" ]` |

---

## Locale type

A locale is used to customize an application for a specific culture or region, in terms of language and formatting of texts, numbers etc. In Hive, a locale is identified by the two-letter language code as defined by the [ISO-639](https://www.loc.gov/standards/iso639-2/php/code_list.php) standard:

```cs
Locale.en
```

A locale can be optionally passed to a function such as [Number.toText()](/docs/configurator-logic/hive-types/number-type#totextformatlocale) to adjust how it is formatted.

The following list of locales is currently supported:

- `ar` Arabic
- `da` Danish
- `de` German
- `el` Greek
- `en` English
- `es` Spanish
- `fi` Finnish
- `fr` French
- `hi` Hindi
- `hu` Hungarian
- `it` Italian
- `ja` Japanese
- `ko` Korean
- `nl` Dutch
- `pl` Polish
- `pt` Portuguese
- `ru` Russian
- `sv` Swedish
- `uk` Ukrainian
- `zh` Chinese

---

## Logic type

A value of type logic is either true or false. It can be used to represent "yes or no" questions in your configurator (on/off, with/without, etc.)

#### Operations

| name                   | example          | result  | description                                                             |
| ---------------------- | ---------------- | ------- | ----------------------------------------------------------------------- |
| equal to               | `true = false`   | `false` | Returns `true` if two logic values contain the same value               |
| not equal to           | `true <> false`  | `true`  | Returns `true` if two logic values do not contain the same value        |
| logical negation       | `not true`       | `false` | Returns the inverse of a value.                                         |
| logical conjunction    | `true and false` | `false` | Returns `true` if both values are true and false if either one is false |
| logical disconjunction | `true or false`  | `true`  | Returns `true` if either value is true and false if both are false      |

#### Functions

| name   | description              |
| ------ | ------------------------ |
| toText | converts a logic to text |

#### toText

Converts a logic to Text.

| example         | result   |
| --------------- | -------- |
| `true.toText()` | `"true"` |

---

## Map type

A map contains multiple values, each of which can be looked up by a key stored alongside it. In other words: keys are mapped to values, which is where the name "map" comes from.

Values can be of any type, so long as they all have the same type. Keys are currently limited to either Number or Text:

- a map with number keys: `[ 15 : "value" ]`
- a map with text keys: `[ "one" : 1, "two" : 2 ]`

:::info
The items of a map are ordered and can also be accessed by their index / position in the map, in addition to their key.  
**The first item has the index 1.**
:::

### Input

A map can also be used as input for a rule. It works the same for them as for any other value:

```hive
Input or [ "one" : 1 ]
```

In this example, if `input` contains a map, that map is used – otherwise the map `[ "one" : 1 ]` is used.

### Empty Maps ([])

You can create a map without any items in it with a pair of square brackets (`[]`) – the same syntax used for [empty lists](/docs/configurator-logic/hive-types/list-type#empty-lists-).

:::info
Empty maps only work in places where the type of the map can be inferred!
:::

```hive
Input or []
```

### MapEntry

When you access an item of a map by its index (e.g. with [getEntryAt](#getentryatindex)), you get back a `MapEntry` – a value that holds both the `key` and the `value` of that item: `{ key: …, value: … }`.

### Functions

| name                                                                              | description                                   |
| --------------------------------------------------------------------------------- | --------------------------------------------- |
| [length](/docs/configurator-logic/hive-types/map-type#length)                     | gets the number of items in the map           |
| [get(key)](/docs/configurator-logic/hive-types/map-type#getkey)                   | gets the value for the specified key          |
| [getAt(index)](/docs/configurator-logic/hive-types/map-type#getatindex)           | gets the value at the specified index         |
| [getEntryAt(index)](/docs/configurator-logic/hive-types/map-type#getentryatindex) | gets the key and value at the specified index |

#### length

Returns the number of items in the map.

| Example                             | Result |
| ----------------------------------- | ------ |
| `[ "one" : 1, "two" : 2 ].length()` | 2      |

---

#### get(key)

Returns the value for the specified key, or `Empty` if the map contains no such key.

| Example                                 | Result |
| --------------------------------------- | ------ |
| `[ "one" : 1, "two" : 2 ].get("one")`   | 1      |
| `[ "one" : 1, "two" : 2 ].get("three")` | Empty  |

When looking for a key, `get` uses the default equality operator as defined by the type of the keys in the map. Text keys are compared case-sensitive.

---

#### getAt(index)

Returns the value at the specified index.

| Example                              | Result                 |
| ------------------------------------ | ---------------------- |
| `[ "one" : 1, "two" : 2 ].getAt(0)`  | 1 (same as `getAt(1)`) |
| `[ "one" : 1, "two" : 2 ].getAt(2)`  | 2                      |
| `[ "one" : 1, "two" : 2 ].getAt(-1)` | 2                      |

`getAt` behaves the same way as [List.get(index)](/docs/configurator-logic/hive-types/list-type#getindex):

- The first item has index 1, but 0 also returns it.
- When the index is negative, items are counted from right to left.
- When the index is greater than the number of items in the map, it is automatically capped.
- If the map contains no items, `Empty` is returned. Check the length of the map to explicitly handle this case.

---

#### getEntryAt(index)

Returns the [MapEntry](#mapentry) (key and value) at the specified index. Use this when you need the key of an item you only know by its index. Indexing rules are the same as for [getAt](#getatindex).

| Example                                  | Result                     |
| ---------------------------------------- | -------------------------- |
| `[ "one" : 1, "two" : 2 ].getEntryAt(0)` | `{ key: "one", value: 1 }` |

---

## Math type

The math type provides trigonometric and other advanced mathematical functions and constants. For commonly used, simple mathematical functions take a look at the number type.

### Usage

To use any of the functions described on this page, you must prefix them with the math type name.

```hive
Math.sin(90)
```

### Constants

| name | description                             |
| ---- | --------------------------------------- |
| `pi` | the number pi                           |
| `e`  | the number e (natural logarithmic base) |

### Functions

| name                                                                                      | description                                     |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [abs(number)](/docs/configurator-logic/hive-types/math-type#absnumber)                    | gets the absolute value of a number             |
| [sqrt(number)](/docs/configurator-logic/hive-types/math-type#sqrtnumber)                  | gets the square root of a number                |
| [max(number1, number2)](/docs/configurator-logic/hive-types/math-type#maxnumber1-number2) | gets the greater of two numbers                 |
| [min(number1, number2)](/docs/configurator-logic/hive-types/math-type#minnumber1-number2) | gets the lower of two numbers                   |
| [log(number)](/docs/configurator-logic/hive-types/math-type#lognumber)                    | gets the natural logarithm (base e) of a number |
| [log2(number)](/docs/configurator-logic/hive-types/math-type#log2number)                  | gets the base 2 logarithm of a number           |
| [log10(number)](/docs/configurator-logic/hive-types/math-type#log10number)                | gets the base 10 logarithm of a number          |

#### Trigonometric Functions (in degrees)

These functions assume that angles are measured in degrees, see the next section for corresponding functions that take radians.

| name         | description                                          |
| ------------ | ---------------------------------------------------- |
| sin(angle)   | gets the sine of the specified angle                 |
| cos(angle)   | gets the cosine of the specified angle               |
| tan(angle)   | gets the tangent of a specified angle                |
| asin(number) | gets the angle whose sine is the specified number    |
| acos(number) | gets the angle whose cosine is the specified number  |
| atan(number) | gets the angle whose tangent is the specified number |

#### Trigonometric Functions (in radians)

These functions assume that angles are measured in radians, otherwise they behave exactly like their degree counterparts.

| name          | description                                          |
| ------------- | ---------------------------------------------------- |
| sinr(angle)   | gets the sine of the specified angle                 |
| cosr(angle)   | gets the cosine of the specified angle               |
| tanr(angle)   | gets the tangent of a specified angle                |
| asinr(number) | gets the angle whose sine is the specified number    |
| acosr(number) | gets the angle whose cosine is the specified number  |
| atanr(number) | gets the angle whose tangent is the specified number |

#### abs(number)

Returns the absolute value of a number.

| example            | result  |
| ------------------ | ------- |
| `Math.abs(-13.37)` | `13.37` |
| `Math.abs(5)`      | `5`     |

#### sqrt(number)

Returns the square root of a number.

| example        | result |
| -------------- | ------ |
| `Math.sqrt(4)` | `2`    |

#### log(number)

Returns the natural logarithm (base e) of a number.

| example       | result              |
| ------------- | ------------------- |
| `Math.log(2)` | `0.693147180559945` |

#### log2(number)

Returns the base 2 logarithm of a number.

| example        | result |
| -------------- | ------ |
| `Math.log2(2)` | `1`    |

#### log10(number)

Returns the base 10 logarithm of a number.

| example         | result              |
| --------------- | ------------------- |
| `Math.log10(2)` | `0.301029995663981` |

#### max(number1, number2)

Returns the greater of two numbers.

| example            | result |
| ------------------ | ------ |
| `Math.max(3, 5)`   | `5`    |
| `Math.max(-7, -2)` | `-2`   |

#### min(number1, number2)

Returns the lesser of two numbers.

| example            | result |
| ------------------ | ------ |
| `Math.min(3, 5)`   | `3`    |
| `Math.min(-7, -2)` | `-7`   |

---

## Number type

Numbers are used for all kinds of calculations. There are literal numbers, like `7` or `1.5`, but a component or variable can also be of type number. Both kinds can be used interchangeably and everything described on this page applies to either kind.
For example, you can call a function like `round()` on a component: `price.round()` or on a literal number: `13.5.round()`.

### Operations

| name           | example       | result | description                                             |
| -------------- | ------------- | ------ | ------------------------------------------------------- |
| negate         | `-price`      | `-5`   | gets the inverse of a number                            |
| add            | `price + 2`   | `7`    | adds two numbers                                        |
| subtract       | `2 - price`   | `-3`   | subtracts one number from another                       |
| multiply       | `2 * price`   | `10`   | multiplies two numbers                                  |
| divide         | `2 / price`   | `2.5`  | divides one number by another                           |
| exponentiation | `price ^ 2`   | `25`   | raises a number to the power of another number          |
| modulo         | `price mod 2` | `1`    | divides one number by another and returns the remainder |

### Comparing numbers

In addition to the above, there are also six operators for comparing numbers.

| name                  | example       | result  | description                                                               |
| --------------------- | ------------- | ------- | ------------------------------------------------------------------------- |
| greater than          | `price > 5`   | `false` | returns `true` if the first number is greater than the second             |
| greater than or equal | `price >= 5`  | `true`  | returns `true` if the first number is greater than or equal to the second |
| less than             | `4 < price`   | `true`  | returns `true` if the first number is less than the second                |
| less than or equal    | `4 <= price`  | `false` | returns `true` if the first number is less than or equal to the second    |
| equal to              | `price = 5`   | `true`  | returns `true` if one number is equal to another                          |
| not equal to          | `price <> 19` | `true`  | returns `true` if one number is not equal to another                      |

### Functions

| name                                                                                        | description                                                                            |
| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [round(digits)](/docs/configurator-logic/hive-types/number-type#round)                      | rounds a number to the nearest integer or to the specified number of fractional digits |
| [floor](/docs/configurator-logic/hive-types/number-type#floor)                              | gets the largest integer less than or equal to the specified number                    |
| [ceiling](/docs/configurator-logic/hive-types/number-type#ceiling)                          | gets the smallest integer greater than or equal to the specified number                |
| [truncate](/docs/configurator-logic/hive-types/number-type#truncate)                        | calculates the integral part of a number                                               |
| [atLeast(min)](/docs/configurator-logic/hive-types/number-type#atleastmin)                  | gets a number that is greater than or equal to the specified threshold                 |
| [atMost(max)](/docs/configurator-logic/hive-types/number-type#atmostmax)                    | gets a number that is less than than or equal to the specified threshold               |
| [toText(format,locale)](/docs/configurator-logic/hive-types/number-type#totextformatlocale) | converts a number to text                                                              |

:::info
For additional mathematical functions check out the article about the math type.
:::

#### round

Rounds a number to the specified number of fractional digits, away from zero.  
If no parameter is used, or the number of digits is zero, rounds to the nearest integer.

| example          | result |
| ---------------- | ------ |
| `price.round()`  | 4      |
| `price.round(1)` | 4.4    |
| `price.round(2)` | 4.45   |

:::info
If you specify a negative number of digits, its positive inverse will be used, i.e. `round(-2)` is the same as `round(2)`.
:::

---

#### floor

Returns the largest integer that is less than or equal to the specified number.

| example          | result |
| ---------------- | ------ |
| `1.1.floor()`    | 1      |
| `1.9.floor()`    | 1      |
| `(-1.1).floor()` | -2     |

---

#### ceiling

Returns the smallest integer that is greater than or equal to the specified number.

| example            | result |
| ------------------ | ------ |
| `1.1.ceiling()`    | 2      |
| `1.3.ceiling()`    | 2      |
| `(-1.1).ceiling()` | -1     |

---

#### truncate

Calculates the integral part of a number by rounding it to the nearest integer towards zero.

| example             | result |
| ------------------- | ------ |
| `1.1.truncate()`    | 1      |
| `1.9.truncate()`    | 1      |
| `(-1.9).truncate()` | -1     |

---

#### atLeast(min)

Compares a number to a specified threshold and returns it if it is greater than or equal to the threshold, otherwise returns the threshold.

| example         | result |
| --------------- | ------ |
| `5.atLeast(10)` | 10     |
| `5.atLeast(3)`  | 5      |

---

#### atMost(max)

Compares a number to a specified threshold and returns it if it is less than or equal to the threshold, otherwise returns the threshold.

| example        | result |
| -------------- | ------ |
| `5.atMost(2)`  | 2      |
| `5.atMost(10)` | 5      |

---

#### toText(format,locale)

Converts a number to text. You can optionally customize the conversion with the format parameter and specify the desired locale.

| example                              | result         |
| ------------------------------------ | -------------- |
| `price.toText()`                     | `"4.445"`      |
| `price.toText("€ 0.##")`             | `"€ 4.45"`     |
| `1337.toText("$ 0,0.00")`            | `"$ 1,337.00"` |
| `1337.toText("€ 0,0.00", Locale.de)` | `"€ 1.337,00"` |

You may use a combination of the following characters to customize the conversion of numbers to text.

#### zero placeholder (O)

Replaces the zero with the corresponding digit if one is present; otherwise, zero appears in the result text.  
`123.456.toText("0000")` becomes `0123`  
`123.toText("000.00")` becomes `123.00`

#### digit placeholder (#)

Replaces the hash sign with the corresponding digit if one is present; otherwise, no digit appears in the result text.  
`123.456.toText("####")` becomes `123`  
`123.toText("###.##")` becomes `123`

#### decimal placeholder (.)

Determines the location of the decimal separator in the result text.  
`0.1234.toText("0.00")` becomes `0.12`

#### group separator placeholder (,)

Inserts a localized group separator between each number group in the integral part of the output.  
`12345678.toText("##,#")` becomes `12,345,678`

#### percentage placeholder (%)

Multiplies a number by 100 and inserts a percentage symbol in the result text.  
`0.35.toText("0%")` becomes `35%`

#### section separator (;)

Defines sections with separate format strings for positive, negative and zero numbers.  
`(-13.37).toText("##.##;(##.##)")` becomes `(13.37)`

#### Other characters

All characters that have not been mentioned above will simply be copied to the result text:  
`24.toText("0 degrees")` becomes `24 degrees`

In order to use placeholder characters literally, you can precede them with a backslash:  
`13.37.toText("\# 00.0")` becomes `# 13.4`

You can also use single quotes `'` or double quotes `"` to enclose literal text that should be copied to the result:  
`13.37.toText("00.0'% of total'")` becomes `13.4% of total`

#### Rounding

If the formatted value contains more significant digits than are present in the format text, the value will be rounded to the nearest digit and away from zero.  
`10.5.toText("#")` becomes `11`  
`0.25.toText("0.0")` becomes `0.3`

---

## QR code type

### Usage

To use any of the functions described on this page, you must prefix them with the QRCode type name:

```hive
QRCode.generate("some text")
```

### Generate function

Generates the QR code of the given text and returns the SVG representation of it.  
Syntax: generate(text, darkColor, lightColor, errorCorrectionLevel)

- The first parameter is required and is the text of which the QR code gets generated (type: text, max length: 500 characters)
- The second parameter is optional and defines the main color of the QR code (type: color, default value: #000)
- The third parameter is optional and defines the background color of the QR code (type: color, default value: #FFF)
- The fourth parameter is optional and defines the error correction level of the QR code (type: number, default value: 0). Possible values:
  - \<=1 - Level L (Low) - 7% of codewords can be restored
  - 2 - Level M (Medium) - 15% of codewords can be restored
  - 3 - Level Q (Quartile) - 25% of codewords can be restored
  - \>=4 - Level H (High) - 30% of codewords can be restored

```hive
QRCode.generate("some text a")
QRCode.generate("some text b", "#F00".toColor())
QRCode.generate("some text c", "#012".toColor(), "#ABC".toColor())
QRCode.generate("some text d", "#00D".toColor(), "#F0F".toColor(), 3)
```

The SVG QR code scales to any width/height needed. If you put the SVG into a visual in a graphic component and set the height/width, it will scale to this size accordingly.

Tips for improving the readability of the QR code:

- Always leave a space between your QR code and the content or design around it. The QR code should always stand alone in the background and the foreground should not touch other elements.
- Make sure there is enough contrast when using other colors than black and white.
- Don’t put too much content into a QR code. Use a low error correction level for smaller QR codes.

---

## Text type

In Hive, a text (often called “string” in other programming languages) must be surrounded with quotation marks (`”`). All the operations and functions described on this page work with literal texts, components, and variables alike:

```hive
var t = "Hello, ";
t.toUpper() + "world!".toUpper()   // returns "HELLO, WORLD!"
```

### Formatted Text

Start and end your text with three quotes (`”””`) instead of one to create a formatted text. A formatted text can span over multiple lines (preserving each new line), you can use quotation marks without having to escape them and embed code fragments in it:

```hive
var answer = 42;
"""The answer is of course "{=answer}".
What else?"""
```

This will create a multi-line text:

```hive
The answer is of course "42".
What else?
```

If you want to use a quotation mark in a regular text, you must escape it with `\`. A regular text cannot contain line breaks either, instead requiring you to write `\n`.  
The example above can be written as a regular text like this:

```hive
"The answer is of course \"" + answer + "\".\nWhat else?"
```

Not very convenient. Therefore, when you are dealing with text that contains quotation marks or line breaks, we recommend you use formatted text. However, there is one caveat: an opening curly brace (`{`) must be written as two curly braces in formatted text:

```hive
"""This is a curly {{brace}"""
```

Plain text

This will create this text: `This is a curly {brace}`

### Operations

| name       | example          | result      | description                      |
| ---------- | ---------------- | ----------- | -------------------------------- |
| add text   | `"awe" + "some"` | `"awesome"` | combines two texts               |
| add number | `"high " + 5`    | `"high 5"`  | combines a text and a number     |
| repeat     | `"$" * 3`        | `"$$$"`     | repeats a text a number of times |

### Comparing Text

| name         | example        | result  | description                                               |
| ------------ | -------------- | ------- | --------------------------------------------------------- |
| equal to     | `"up" = "UP"`  | `false` | returns `true` if two texts are equal, case sensitive     |
| equal to     | `"up" ~= "UP"` | `true`  | returns `true` if two texts are equal, case insensitive   |
| not equal to | `"up" <> "UP"` | `true`  | returns `true` if two texts are not equal, case sensitive |

There is no case insensitive version of the `<>` operator, but you can negate the outcome of the `~=` operator to achieve the same goal: `not("up" ~= "UP")` returns `false`, for example.

:::warning
Whitespace characters such as spaces, tabs, or line breaks are significant when comparing text. The expression `"a " = "a"` is `false` because there is a space in the second text that is not present in the first.
:::

### Functions

| name                                                                              | description                                                            |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [length](/docs/configurator-logic/hive-types/text-type#length)                    | gets the number of characters in a text                                |
| [contains(text)](/docs/configurator-logic/hive-types/text-type#containstext)      | returns `true` if a text contains a specific text                      |
| [toUpper](/docs/configurator-logic/hive-types/text-type#toupper)                  | converts a text to upper case                                          |
| [toLower](/docs/configurator-logic/hive-types/text-type#tolower)                  | converts a text to lower case                                          |
| [take(amount)](/docs/configurator-logic/hive-types/text-type#takeamount)          | gets a subset of a text that contains a specified number of characters |
| [skip(amount)](/docs/configurator-logic/hive-types/text-type#skipamount)          | gets a text with a specified number of characters omitted              |
| [replace(old, new)](/docs/configurator-logic/hive-types/text-type#replaceold-new) | replaces all occurrences of a text with a different text               |
| [encodeHtml](/docs/configurator-logic/hive-types/text-type#encodehtml)            | gets an HTML-encoded copy of a text                                    |
| [decodeHtml](/docs/configurator-logic/hive-types/text-type#decodehtml)            | decodes an HTML-encoded text                                           |
| [encodeUrl](/docs/configurator-logic/hive-types/text-type#encodeurl)              | gets an URL-encoded copy of a text                                     |
| [decodeUrl](/docs/configurator-logic/hive-types/text-type#decodeurl)              | decodes an URL-encoded text                                            |
| [encodeJson](/docs/configurator-logic/hive-types/text-type#encodejson)            | gets a JSON-encoded copy of a text                                     |
| [toNumber(locale)](/docs/configurator-logic/hive-types/text-type#tonumberlocale)  | converts a text to a Number                                            |
| [toColor](/docs/configurator-logic/hive-types/text-type#tocolor)                  | converts a text to a Color                                             |
| [isBase64](/docs/configurator-logic/hive-types/text-type#isbase64)                | returns `true` if it is a valid base64 string                          |
| [isEmail](/docs/configurator-logic/hive-types/text-type#isemail)                  | returns `true` if it is a valid mail address                           |

#### length

Returns the number of characters in a text.

| example              | result |
| -------------------- | ------ |
| `"123".length()`     | 3      |
| `"awesome".length()` | 7      |

---

#### contains(text)

Returns true if a text contains a specific text.

| example                      | result |
| ---------------------------- | ------ |
| `"awesome".contains("some")` | `true` |

---

#### toUpper

Returns a copy of the text with all characters converted to upper case.

| example                | result       |
| ---------------------- | ------------ |
| `"Awesome!".toUpper()` | `"AWESOME!"` |

#### toLower

Returns a copy of the text with all characters converted to lower case.

| example                | result       |
| ---------------------- | ------------ |
| `"Awesome!".toLower()` | `"awesome!"` |

---

#### take(amount)

Returns a subset of a text that contains a specified number of characters.

- If a negative number is used, characters will be taken from the end of the text towards the beginning.
- If the number is greater than the number of characters in the text, the same text will be returned.
- If the number is zero, an empty text will be returned.

| example               | result      |
| --------------------- | ----------- |
| `"awesome".take(3)`   | `"awe"`     |
| `"awesome".take(-4)`  | `"some"`    |
| `"awesome".take(100)` | `"awesome"` |
| `"awesome".take(0)`   | `""`        |

---

#### skip(amount)

Returns a text with a specified number of characters omitted.

- If a negative number is used, characters will be skipped from the end of the text toward the beginning.
- If the number is greater than the number of characters in the text, an empty text will be returned.
- If the number is zero, the same text will be returned.

| example               | result      |
| --------------------- | ----------- |
| `"awesome".skip(3)`   | `"some"`    |
| `"awesome".skip(-4)`  | `"awe"`     |
| `"awesome".skip(100)` | `""`        |
| `"awesome".skip(0)`   | `"awesome"` |

:::info
This function is the exact opposite of `take`. You can use either one and accomplish the same goal, but often it is easier to reason about a problem when combining the two.
:::

Example: Imagine you wanted to extract `123` from an inventory number like `ST-123-XYZ`.
The most straightforward way to accomplish this probably is `inventoryNumber.skip(3).take(3)`.
But you could just as well write `inventoryNumber.take(6).take(-3)`. The choice is yours!

---

#### replace(old, new)

Replaces all occurrences of a text with a different text.

- If the searched text isn't found, the function will return the original text
- All occurrences of the searched text will be replaced, not just the first one.

| example                               | result              |
| ------------------------------------- | ------------------- |
| `"awesome".replace("esome", "ful")`   | `"awful"`           |
| `"a;divided;text;".replace(";", " ")` | `"a divided text "` |

---

#### encodeHtml

Returns a text with all characters replaced that have special meaning in HTML, so that it can be safely used.  
Note: while the text may look strange, your browser will still display it correctly.

| example                           | result                      |
| --------------------------------- | --------------------------- |
| `"I <3 Hive & HTML".EncodeHtml()` | `"I &lt;3 Hive &amp; HTML"` |

---

#### decodeHtml

The opposite of EncodeHtml: converts an HTML-encoded text back to its original form.

| example                                  | result               |
| ---------------------------------------- | -------------------- |
| `"I &lt;3 Hive &amp; HTML".DecodeHtml()` | `"I <3 Hive & HTML"` |

---

#### encodeUrl

Similar to EncodeHtml, returns a text with all characters replaced that have special meaning in URLs, so that it can be safely used.

| example                          | result                   |
| -------------------------------- | ------------------------ |
| `"I <3 Hive & HTML".EncodeUrl()` | `"I+%3C3+Hive+%26+HTML"` |

---

#### decodeUrl

The opposite of EncodeUrl: converts an URL-encoded text back to its original form.

| example                              | result               |
| ------------------------------------ | -------------------- |
| `"I+%3C3+Hive+%26+HTML".DecodeUrl()` | `"I <3 Hive & HTML"` |

---

#### encodeJson

Returns a text with all characters replaced that have special meaning in JSON – or that could pose a security risk via injection attacks. The returned text can be safely embedded in a JSON document.

**Note:** use this on a text that will be _embedded_ in a JSON text, not on a text that contains JSON content itself!

| example                                                                 | result                                                             |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `"Dangerous text: \" \\ + <>".encodeJson()`                             | `"Dangerous text: \u0022 \\ \u002B \u003C\u003E"`                  |
| `"""{ "example": "{= "Dangerous text: \" \\ + <>".encodeJson() }" }"""` | `"{ "example": "Dangerous text: \u0022 \\ \u002B \u003C\u003E" }"` |

#### toNumber(locale)

Converts a text to a number. If the text cannot be converted, for example because it contains non-numerical characters, `Empty` will be returned.  
You can optionally specify a [locale](/docs/configurator-logic/hive-types/local-type) to support different number formats, the default is `Locale.en`

Always provide a fallback value in case the conversion fails. We made it easy to do so with the `or` operator.

| example                       | result  |
| ----------------------------- | ------- |
| `"13.37".toNumber()`          | 13.37   |
| `"13$".toNumber()`            | `Empty` |
| `"13$".toNumber() or 1`       | 1       |
| `"13,37".toNumber(Locale.de)` | 13.37   |

---

#### toColor

Converts a text in hexadecimal color format to a color. If the color format is invalid, an error will be returned.

| example               | result                              |
| --------------------- | ----------------------------------- |
| `"#0000ff".ToColor()` | 6-digit format: `#RRGGBB`           |
| `"#f00".ToColor()`    | 3-digit format: `#RGB`              |
| `"#ff00".ToColor()`   | ! ERROR ! invalid format (4 digits) |

---

#### isBase64

Returns true if the given text is a valid base64 string.

| example                 | result  |
| ----------------------- | ------- |
| `"".isBase64()`         | `true`  |
| `"=".isBase64()`        | `false` |
| `"a=".isBase64()`       | `false` |
| `"Zm9vYmE=".isBase64()` | `true`  |

#### isEmail

Returns true if the text is a valid mail address.

| example                            | result  |
| ---------------------------------- | ------- |
| `"john.doe@example.com".isEmail()` | `true`  |
| `"john doe@example.com".isEmail()` | `false` |
| `"john.doe@example".isEmail()`     | `false` |

To be considered valid, a mail address must satisfy the following regular expression:

```javascript
^[\w-]+(?:[\.+][\w-]+)*@(?:[\w-]+\.)+[a-zA-Z0-9-]{2,}$
```

---

## Viewer3d type

The `Viewer3d` type provides helper functions which can be used with slots of the [Viewer 3d control](/docs/configurator-ui-ux/controls/3d-viewer-control).

### Usage

To use any of the functions described on this page, you must prefix them with the `Viewer3d` type name:

```hive
Viewer3d.modelParameter(Models3d.CoffeeCup, "visible", true)
```

:::warning
`Models3d.CoffeeCup` is the preferred syntax to refer to a babylon asset for `Viewer3d.modelParameter()`. This term will generate the valid string (`"Models3d/CoffeeCup"`) for our 3d viewer. In order to avoid future breaking change, DO NOT construct this string on your own.
:::

### Functions

- `modelParameter(modelName, parameterName, parameterValue)`
- `tagParameter(tagName, parameterName, parameterValue)`
- `nodeParameter(nodeName, parameterName, parameterValue)`
- `materialParameter(materialName, parameterName, parameterValue)`

All these functions can be used to create records with parameter descriptions that can be passed to the viewer 3d control's [Set parameter value](/docs/configurator-ui-ux/controls/3d-viewer-control#set-parameter-values) slot.

See the [Set parameter value](/docs/configurator-ui-ux/controls/3d-viewer-control#set-parameter-values) docs for more details on how to use these functions and what values to pass to them

---

## The if expression

The if expression allows you to perform different actions based on one or more conditions. In the example below, we calculate the price of a product. If the customer buys at least 5 units of our product, we grant him a discount. Price refers to a component named price and amount to the component named amount.

```hive
if Amount >= 5 then
  Price * 0.9
else
  Price
end
```

Plain text

To break this down: Writing an if expression follows these rules:

- Every if expression begins with the keyword if and an arbitrary logic expression: the condition.
- If the condition is true, the expression that follows the then keyword will be executed.
- If the condition is false, the expression that follows the else keyword will be executed instead.
- Every if expression ends with the keyword end. This is to distinguish the else expression from any subsequent ones. We will see why this is necessary in the next example.

:::warning
All if expressions must have an else expression. Many other programming languages do not have this requirement, so if you're a programmer then this might feel a bit unusual.
:::

### Multiple conditions

You can also define more than one condition in an if expression. Let's look at a more complex example. Imagine we wanted to give customers an additional discount if they buy more than 9 units, and let's also add some shipping costs to the price:

```hive
if Amount > 9 then
  Price * 0.8
elif Amount >= 5 then
  Price * 0.9
else
  Price
end
+ ShippingCosts
```

Let's break it down again:

- We first check if the amount is greater than 9. We must check for this first because only one condition in an if can be true, and conditions are looked at one after another. If the greater-than-5 condition would come first, any number greater than 9 would also satisfy it and we'd never reach the next condition.
- Subsequent conditions start with the elif keyword (that's a combination of else and if). Aside from the queer name, it's basically the same as the initial if.
- You can use as many elif expressions as you like, but there can only be one if and one else expression.
- Every if expression results in a value that can be processed further. In this case, we add the ShippingCosts to whatever price was calculated by the if.
- This is also the reason why every if must have an else expression: without it, there is no guarantee that the if would return a value. In our example, an amount of 3 would satisfy neither of our two conditions.

---

## User variable

The `user` variable contains information about the current user, provided they are signed into the Combeenation platform. Otherwise, the current user is considered anonymous and the variable will contain fallback values.

### Properties

| name          | description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isLoggedIn`  | `true` if the user is signed into the Combeenation platform and is a member of the CompanyOn the Combeenation platform, a company means exactly what it describes: a company. For the most part, these are customers who have ordered a configurator from us. However, there are also internal companies that we use for best practice examples, for testing or for internal configurators. that owns the configurator, `false` otherwise |
| `id`          | the unique identifier of the user                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `firstName`   | the first name of the user or an empty text if not set or the user isn’t signed in                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `lastName`    | the last name of the user or an empty text if not set or the user isn’t signed in                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `mail`        | the mail address of the user or a fallback value if the user isn’t signed in (currently `anonymous@combeenation.com`) **Note** the fallback mail address does not exist, mails cannot be sent to it. It's intended to assist in debugging, not for actual use!                                                                                                                                                                                                                                                                                             |
| `distributor` | the name of the distributor the user belongs to, or an empty text if they belong to the company                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `avatar`      | the `FileUrl` of the user's avatar image, or an empty text if none is set                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `fields`      | Container for all [custom field](/docs/fundamentals/custom-fields#user-fields) values, provided any have been created in the CompanyOn the Combeenation platform, a company means exactly what it describes: a company. For the most part, these are customers who have ordered a configurator from us. However, there are also internal companies that we use for best practice examples, for testing or for internal configurators.     |

---

## Accessibility

### General

Accessibility ensures that web applications like your configurator, are usable by everyone, including people with disabilities. This includes individuals with visual, auditory, motor, and cognitive impairments. By following accessibility best practices, the configurator can create an inclusive experience that allows all users to interact with the configurator without barriers.

To get an overview and an understanding of what accessibility is, we can recommend the following resources:

- [How to review for accessibility](https://web.dev/articles/how-to-review?utm_source=lighthouse&utm_medium=devtools)
- [A11ycasts! - Youtube Playlist](https://www.youtube.com/watch?v=HtTyRajRuyY&list=PLNYkxOF6rcICWx0C9LVWWVqvHlYJyqw7g&index=3)
- [WebAIM](https://webaim.org/)

#### European Accessibility Act (EAA)

The European Accessibility Act (EAA) is a directive aimed at improving accessibility across digital and physical products and services within the European Union. Starting **June 28, 2025**, businesses offering digital solutions, including configurators, must ensure compliance with accessibility standards.  
It has to align with the **WCAG 2.2 Level AA** standards for web accessibility.

##### Legal note

By ensuring compliance with the EAA, businesses not only avoid legal risks but also create a more inclusive experience for all users.

### Tools

Besides the built-in features from browsers or the OS in general, there are helpful tools and extensions:

- [Chrome Lighthouse](https://developer.chrome.com/docs/lighthouse/overview?hl=de)
- [WebAIM - Wave browser extension](https://wave.webaim.org/extension/)
- [NVDA Screenreader (NV Access)](https://www.nvaccess.org/download/)

### Configurator editor

:::info
While the configurator editor aids in accessibility implementation, using these features does not automatically guarantee full compliance with accessibility standards (e.g., WCAG, EAA, ADA).  
**Final compliance should be verified through audits and real-world testing.**
:::

#### aria-label

Form controls like a `Textbox`, `Checkbox` or `Button` should always have a describing label. The configurator automatically chooses the "best fitting property" for the label.

##### Example

A button is only displayed as icon without any visible text.

- For a visually impaired user it might be impossible to grasp what this button does
- Entering an `aria-label` would solve this, but it might still be hard to understand for non-impaired users, solely by the icon  
  Solution: The best option is to enter a `Tooltip text` as it shows a describing text when navigating to it (mouse hover or keyboard) and the configurator will also automatically set this text as `aria-label`.  
  ![image.png](<https://docs.combeenation.com/assets/images/image%2877%29-813d80de49b6b7b9b7c4631e51a67f5f.png>)

##### Automated check

By default the editor will check if every input control has a corresponding label and will show a warning otherwise.

![image.png](<https://docs.combeenation.com/assets/images/image%2876%29-e55626caf9884e350e29b3e79f22f05b.png>)

#### Custom CSS Styles

Because the CSS can be fully customized it is up to the configurator creator to provide an accessible styling.

- Text size
- Color contrast
- Outline (keyboard navigation)
- etc.

See also [WCAG Checklist](https://webaim.org/standards/wcag/checklist)

---

## 3d viewer control with custom code

If you need more functionality than the [3d viewer control](/docs/configurator-ui-ux/controls/3d-viewer-control) provides out of the box in the configurator editor, you can use [custom code](/docs/category/custom-code) to extend it by adding custom parameter observers, adjusting the viewer settings and much more.

### Basic setup & usage

- Set the 3d viewer control's [viewer version property](/docs/configurator-ui-ux/controls/3d-viewer-control#viewer-version) to `Injected`
- Install the viewer in your custom code with `npm i @combeenation/3d-viewer`
- Use the viewer control's [injectViewer](https://custom-code.docs.combeenation.com/classes/Cbn-1.ctrls.Viewer3d.html#injectViewer) method to pass the viewer to the control:

  ```js
  import { Viewer } from '@combeenation/3d-viewer';
  // ...
  CfgrUtils.onCfgrReady(() => {
    // ...
    CtrlUtils.getViewerCtrl('viewer3d').injectViewer(Viewer);
    // ...
  });
  ```

- Use the viewer control's [getViewer](https://custom-code.docs.combeenation.com/classes/Cbn-1.ctrls.Viewer3d.html#getViewer) to get access to the viewer instance and the [Babylon.js scene](https://doc.babylonjs.com/typedoc/classes/BABYLON.Scene).

  ```js
  const viewerCtrl = CtrlUtils.getViewerCtrl('viewer3d');
  const viewer = await viewerCtrl.getViewer();

  // E.g. create custom skybox from JPGs
  const scene = viewer.scene;
  const customReflection = new CubeTexture('', scene, null, null, files);
  const customSkybox = scene.createDefaultSkybox(customReflection, true, 10000);
  ```

### Common use cases

When extending the viewer control's capabilities in custom code, there are almost no limits in what you can do. If you want to, you can have direct access to the underlying [Combeenation 3d viewer](https://3dviewer.docs.combeenation.com/) & [Babylon.js](https://www.babylonjs.com/) core which power the viewer control.

In the following chapters we'll explore some common use cases and explain how to best deal with them.

#### Add custom parameter observer

The viewer comes with some [built in parameters](https://3dviewer.docs.combeenation.com/variables/BuiltInParameter.html) which you can use with the control's [set parameter values](/docs/configurator-ui-ux/controls/3d-viewer-control#set-parameter-values) slot but you can also add your own, custom parameters using custom code.

These observers should be added **before** the initial viewer parameter update, as this update would not trigger the custom observers then.  
Since [getViewer](https://custom-code.docs.combeenation.com/classes/Cbn-1.ctrls.Viewer3d.html#getViewer) is awaiting this initial parameter update, we have to access the observer in a different way.  
For this case we can use the `onAfterViewerCreated` parameter of [injectViewer](https://custom-code.docs.combeenation.com/classes/Cbn-1.ctrls.Viewer3d.html#injectViewer).

This example shows, how to add a custom parameter named `ShowBoundingBox` with which you can show or hide a meshs bounding box:

```js
CtrlUtils.getViewerCtrl('viewer3d').injectViewer(Viewer, {
  onAfterViewerCreated: (viewer: Viewer) => {
    viewer.tagManager.setParameterObserver('ShowBoundingBox', async ({ nodes, newValue }) => {
      nodes.filter(node => node instanceof AbstractMesh).forEach(node => (node.showBoundingBox = newValue));
    });
  }
});
```

You can set & change the value of all custom parameters with the control's `set parameter values` slot like with all built in parameters.

#### Adjust viewer settings

The viewer control automatically creates a viewer instance which comes with a set of default values. You can customize these viewer settings **before** the viewer instance is **created**, using the `onBeforeCreateViewer` parameter of [injectViewer](https://custom-code.docs.combeenation.com/classes/Cbn-1.ctrls.Viewer3d.html#injectViewer).

```js
CtrlUtils.getViewerCtrl('viewer3d').injectViewer(Viewer, {
  onBeforeCreateViewer: (viewerSettings: ViewerSettings) => {
    viewerSettings.useParallelShaderCompile = false;
    viewerSettings.engineOptions.useHighPrecisionMatrix = true;
  }
});
```

#### React on parameter application

There are cases where you want to execute code right **after** viewer parameters, set by the [set parameter values](/docs/configurator-ui-ux/controls/3d-viewer-control#set-parameter-values) slot, have been applied.  
For example changing light setup or moving the camera to show the adjusted scene in a better way.  
There is the `onAfterParametersApplied` parameter of [injectViewer](https://custom-code.docs.combeenation.com/classes/Cbn-1.ctrls.Viewer3d.html#injectViewer) to achieve this.

```js
CtrlUtils.getViewerCtrl('viewer3d').injectViewer(Viewer, {
  onAfterParametersApplied: async (modelVisibility: ModelVisibilityEntry[], parameterValues: ParameterValues) => {
    // e.g. center camera if model has been changed
    if (modelVisibility.length) {
      await centerCamera();
    }
  }
});
```

---

## 3d viewer control

The 3d viewer control gives you the power to **showcase your 3d models** in the configurator. It allows you to dynamically compose the shown scene & change it at runtime so that the user always sees what he's about to buy.

Amongst other things, the 3d viewer gives you the following options to **dynamically adjust the scene**:

- Show & hide complete models
- Show & hide specific nodes of a model
- Changing certain aspects of specific nodes of a model:
  - Reposition, rotate & scale nodes
  - Change shown materials & adjust material details like color, roughness, metallness etc.
- Draw dynamically generated content like text or images onto nodes

Once the user is happy with what he sees, he can use the control's built in **[AR mode](/docs/configurator-ui-ux/controls/3d-viewer-control#start-ar)** to experience the customized model in an very engaging manner.

### How to show models

After creation, the 3d viewer control shows all [3d assets](/docs/asset-management/3d-and-material-assets/basic-workflow) from all asset bundles which are [assigned to your configurator](/docs/asset-management/assign-asset-bundles-to-configurators).

You can use the [set parameter values](/docs/configurator-ui-ux/controls/3d-viewer-control#set-parameter-values) slot to overwrite this behavior and actively define which models it should show or not.

### How to alter 3d models

You can use the [set parameter values](/docs/configurator-ui-ux/controls/3d-viewer-control#set-parameter-values) slot to control most dynamic aspects of the scene like which models & nodes are shown, which materials & colors are used etc.

### Properties

Besides the general control properties like `width`, `height`, `background` etc., the 3d viewer control comes with some special properties:

#### Viewer version

The 3d viewer control is powered by our own [3d viewer](https://3dviewer.docs.combeenation.com/) and we give you the freedom to chose the exact version which should be used by the 3d viewer control.

When first creating the control, we automatically set this to use the latest available version so you don't have to touch this at all.

Please consult the [3d viewer release notes](https://3dviewer.docs.combeenation.com/pages/release-notes/releases/index.html) when changing the viewer version to get an idea of what might change with the new version.

The option `Injected` is used when extending the viewer control's capabilities by custom code. See [3d viewer control with custom code](/docs/configurator-ui-ux/controls/3d-viewer-control-with-custom-code) for more details on how to use this.

#### Load in editor

When set to `false`, no 3d content will be loaded when inside the design editor. This can be helpful in situations where you're working on things which are not related to the shown 3d content like overall configurator layout or logic.

This setting only affects the design editor & does not change the 3d viewer control's behavior in preview or published configurators.

#### Autofocus model

Defaults to `true`, which automatically autofocuses the camera after the visibility of a certain model has been changed. The camera will be zoomed in as far as possible while the whole scene content remains visible.

This behaviour is benefitial for simple projects, as the user won't get lost in the scene after switching models. However it is more of a hinderance if the camera is controlled via custom code.  
In this way the user can deactivate the autofocus behaviour by setting this flag to `false`.

If this flag is set, the viewer control will also automatically adapt the **ground size** and mesh list for **shadow generation** according to the scene content, defined by the currently visible models.  
This only takes effect if dedicated ground meshes and shadow lights are available, which is the case if the "Grounded" scene asset is selected.

#### Scene asset

A "scene asset" represents a collection of settings that define the appearance of a scene.  
It includes:

- light elements, shadow configuration and environment
- camera limits and settings
- environment meshes like ground or skybox
- global scene settings like background color

You can choose a "**Grounded**" scene asset or "**-**", if none should be used.

##### Grounded

The "Grounded" scene asset comes with a ground mesh, that receives shadows from the currently visible models.  
These shadows are created by a directional light, which serves as an additional lighting source to the environment texture.  
Also the camera can not move underneath the ground, making the scene appear more realistic.

#### Environment URL

This property is deprecated and will be ignored if the "**scene asset**" property is used, as the environment texture is part of the scene asset.

The environment is responsible for reflections and indirect lighting of the 3d scene. Without it and without any other lights, all materials in the 3d scene are rendered completely black.  
See [Babylon.js docs](https://doc.babylonjs.com/features/featuresDeepDive/materials/using/HDREnvironment) for further info about environments and IBL in general.

This property defaults to a [environment asset](https://assets.babylonjs.com/environments/environmentSpecular.env) provided on the Babylon.js server.  
You can change the property either via providing a static url or a hive value.  
The latter is the preferred one, as you can access environment files from the [asset editor](/docs/asset-management/3d-and-material-assets/basic-workflow) and adjust the environment at runtime in this case.

### Slots

You can use the following slots the 3d viewer control to interactively change the 3d scene and its shown 3d content at runtime:

#### Set parameter values

The `set parameter values` slot is the central piece of the 3d viewer control which lets you adjust the scene to your likings & change it based on the users input in the configurator.

This slot lets you:

- Define which 3d models are visible or not
- Use the viewers [parameter system](https://3dviewer.docs.combeenation.com/classes/ParameterManager.html) to show or hide nodes & set other parameters like used materials, color, position etc.

##### Basic usage

The `set parameter values` slot needs to be connected to a [value component](/docs/configurator-logic/components/value-component) which creates a list of records from the [Viewer3d type](/docs/configurator-logic/hive-types/viewer3d-type) parameter functions `modelParameter`, `tagParameter`, `nodeParameter` or `materialParameter`.

E.g.:

```hive
[
  // Set visibility of 3d models
  //
  //                      3d asset path,          parameter name, value
  Viewer3d.modelParameter(Models3d.CoffeeCup,     "visible",      true),
  Viewer3d.modelParameter(Models3d.CoffeeCoaster, "visible",      false),

  // Set parameter values using the tagging system
  // Here: Show all nodes which contain the tag "Handle" and hide all nodes
  // which contain the tag "Cap"
  // Also set "metallic" value to 1 for all materials which contain the tag "Metal"
  //
  //                    Tag name, parameter name,   value
  Viewer3d.tagParameter("Handle", "visible",        true),
  Viewer3d.tagParameter("Cap",    "visible",        false),
  Viewer3d.tagParameter("Metal"   "metallic",       1),

  // Set parameter values using the node system
  // Here: Hide the node with the name "Spoon" & set a material for it which
  // will be applied once the value of the "visible" parameter is changed to
  // `true` at a later point
  //
  //                     Node name, parameter name, value
  Viewer3d.nodeParameter("Spoon",   "visible",      false),
  Viewer3d.nodeParameter("Spoon",   "material",     "SilverMat"),

  // Set parameter values using the material system
  // Here: Set color red and roughness 0.1 to material "matHandle"
  //
  //                         Material name, parameter name, value
  Viewer3d.materialParameter(Materials3d.matHandle,   "color",        "(255, 0, 0)"),
  Viewer3d.materialParameter(Materials3d.matHandle,   "roughness",    0.1)
]
```

In real live, you'll usually get the parameter values from other components whose result changes based on some user input or product logic:

```hive
[
  // "CupIsVisible" & "HandleColor" are components
  Viewer3d.modelParameter(Models3d.CoffeeCup, "visible", CupIsVisible),
  Viewer3d.tagParameter("Handle", "color", HandleColor)
]
```

JavaScript

##### Available 3d models

With `Viewer3d.modelParameter` you can show or hide all 3d assets from all asset bundles which are assigned to your configurator.

##### Available tag, node and material parameters

With the tag, node and material parameter functions you can either use the viewers [built in parameters](https://3dviewer.docs.combeenation.com/variables/BuiltInParameter.html) or you can use custom parameters which are defined & handled by custom code.

The available built in parameters for **nodes** are the following:

- visible
- material
- position
- rotation
- scaling
- influence

The available built in parameters for **materials** are the following:

- color
- roughness
- metallic

Some parameters require an advanced parameter value structure.  
You can use built-in Hive functions, which return the value in the expected stringified structure:

```hive
[
  // move node to position x=1, y=0, z=0
  Viewer3d.nodeParameter("Spoon", "position", Viewer3d.vector3(1, 0, 0)),
  // set rotation around y to 90 degrees
  Viewer3d.nodeParameter("Spoon", "rotation", Viewer3d.vector3(0, 90, 0)),
  // invert scaling in z direction
  Viewer3d.nodeParameter("Spoon", "scaling", Viewer3d.vector3(1, 1, -1)),
  // set color to "red" (FF0000)
  Viewer3d.materialParameter(Materials3d.matHandle, "color", Viewer3d.color3(255, 0, 0)),
  // set morph target influence value of morph target "morphTarget1" from node "node1" to 0.6
  Viewer3d.tagParameter("node1", "influence", Viewer3d.morphTarget("morphTarget1", 0.6))
]
```

In addition to the "basic" material parameters mentioned above, you can also use **texture parameters** for materials. Texture parameters are available for multiple "channels" (e.g. `albedoTexture`, `bumpTexture`) in the material, therefore the parameter configuration has to be defined as **dotted path**.

```hive
[
  // assign checker texture to albedo channel of material "matBox"
  Viewer3d.materialParameter(Materials3d.matBox, "albedoTexture.image", Textures3d.Checker),
  // update "uScale" value depending on a component value
  Viewer3d.materialParameter(Materials3d.matBox, "albedoTexture.uScale", uScale)
]
```

The available **texture channels** are the following:

- albedoTexture
- metallicRoughnessTexture
- bumpTexture
- emissiveTexture
- opacityTexture
- ambientTexture
- lightmapTexture
- detailmapTexture

Built in **parameters** for these texture channels are the following:

- image: supports **url** and **svg** strings
- uOffset
- vOffset
- uScale
- vScale
- uAng
- vAng
- wAng
- clampU
- clampV
- uvSet

According to the underlying Babylon.js engine, "detail maps" require an additional flag for activation.  
This flag can be adjusted with the `useDetailmap` parameter.

```hive
[
  Viewer3d.materialParameter(Materials3d.matBox, "detailmapTexture.image", Textures3d.Checker),
  Viewer3d.materialParameter(Materials3d.matBox, "useDetailmap", true)
]
```

Tags can be used for nodes and materials alike, therefore `viewer3d.tagParameter` supports all built in parameters in general.

##### Custom parameters

When using custom parameters, you pass the name defined by [setParameterObserver](https://3dviewer.docs.combeenation.com/classes/ParameterManager.html#setParameterObserver) to `Viewer3d.tagParameter`, `Viewer3d.nodeParameter` or `Viewer3d.materialParameter`.

See [3d viewer control with custom code](/docs/configurator-ui-ux/controls/3d-viewer-control-with-custom-code) to get more information about how to define them in custom code.

#### Set environment URL

Allows you to use an environment from the asset editor and/or change the environment dynamically at runtime.

Usually you use an environment from the asset editor by creating a value component which provides the URL of the environment file using the following Hive rule:

```hive
// "Cups3d" = Name (or alias) of bundle assigned to configurator
// "env" = Folder name in which "studio" is located
// "studio" = Asset name
Cups3d.env.studio.url
```

You can then connect this component to the `Set environment URL` slot.

See [environment URL](/docs/configurator-ui-ux/controls/3d-viewer-control#environment-url) property for more details about environment files in general.

#### Auto focus camera

This slot can be used to move the camera to a position where all active nodes in the scene are visible.

Calling this slot with default parameter values also adjusts the cameras panning sensibility as well as its pinch & wheel precision to provide a good usability regardless of the size of the shown models.

The slot accepts the following optional parameters to adjust this default behavior to your likings:

- `Alpha`, `Beta` & `Radius factor` to adjust the final camera position.
- `Adjust panning sensibility`, `Adjust pinch precision` & `Adjust wheel precision` to define whether those camera settings should be auto adjusted or not.
- `Exclude tags` & `Exclude nodes` to exclude the given nodes from the calculation.  
  Both those parameters expect a coma separated list of node or tag names like `tagName1, tagName2, tagName3`.

See the viewers [autofocusActiveCamera](https://3dviewer.docs.combeenation.com/classes/CameraManager.html#autofocusActiveCamera) for more details about the parameters.

#### Start AR

The AR mode can be activated with the `Start AR` slot.

The viewer automatically detects if the device is capable of showing the model in an augmented reality environment. The minimum requirement for an AR capable device is that it comes with a camera (mobile phones, tablets), but also some browser and operating system limitations are considered.

Have a look at Googles AR core [documentation](https://developers.google.com/ar/devices) for more details about AR capabilities.

##### AR capable devices

If the device is AR capable, the augmented reality scene will be entered automatically.  
The user will be redirected to the corresponding app, which is responsible for showing the configured 3d model in the AR environment.

##### Non AR capable devices

If the configurator is started from a PC or if the used mobile device doesn't match the AR requirements, the viewer will show a QR code instead, which can then be scanned by an AR capable mobile device.

![image.png](<https://docs.combeenation.com/assets/images/image%2823%29-601f4fec7dd0e4d4a449b146b60e7784.png>)

The QR code will lead to the exact same AR endpoint that would be reached when starting the AR journey from an AR capable device directly.

##### Slot parameter

- `QR subtitle`, `QR description`: Customizable text for QR code layer ("See the product at home" & the text below in the screenshot above).
- `Preparation text`: Customizable text for the load mask which is shown whilst the 3d model is being prepared for the AR scene
- `Popup blocked title`, `Popup blocked description`, `Popup blocked link text`: Customizable text that will be shown if the AR endpoint can't be reached due to a popup blocker
- `Exclude tags`, `Exclude nodes`: Filter for hiding certain nodes in the AR scene
- `Environment`: HDR environment for the AR viewer on the mobile device
- `Loading screen logo`: Image URL for logo on the AR loading screen

### How to draw dynamic content on the 3d model

You can use **texture parameters** for drawing images on certain meshes.  
Check out the "[Decals](/docs/asset-management/3d-and-material-assets/decals)" chapter to find out how to create such meshes on the Combeenation platform. You can also target existing meshes as basis for the texture parameter.

Anyway in most cases `albedoTexture.image` is the preferred option, but other texture channels can be used as well.  
For example `bumpTexture.image` works well for engravings.  
Here are some tips and tricks for practical usage of these parameters.

1.  Use `GraphicView.Value.ToText()` to use the content of a [Graphic component](/docs/configurator-logic/components/graphic-component) as texture image

    ```hive
    [Viewer3d.materialParameter(Materials3d.matPaintable, "albedoTexture.image", PaintableGraphic.Value.ToText())]
    ```

2.  Use additional texture settings parameter like `uScale`/`vScale` to scale or invert your texture and `uOffset`/`vOffset` for tweaking the position on the desired mesh

    ```hive
    [
      // negative UV scaling for inverting the image
      Viewer3d.materialParameter(Materials3d.matPaintable, "albedoTexture.uScale", -1),
      Viewer3d.materialParameter(Materials3d.matPaintable, "albedoTexture.vScale", -1)
    ]
    ```

3.  Create individual components for texture image parameters with large string values (eg: SVGs)

    :::info
    The **whole component** value will be updated by the server, whenever a change within the component has been detected.  
    This can lead to larger network load if large string values are involved, which can be the case when using SVGs or data strings in the texture image parameter.
    :::

    It can be avoided, if the parameters are split across multiple components.  
    Each of these parameter components has to be linked as an individual `"set parameter values"` slot though.

    ```hive
    // ❌ Don"t: Single component "ParameterValues"
    [
      Viewer3d.tagParameter("Handle", "visible", HandleVisible),
      Viewer3d.tagParameter(Materials3d.matHandle, "color", HandleColor),
      Viewer3d.materialParameter(Materials3d.matPaintable, "albedoTexture.image", PaintableGraphic.Value.ToText())
    ]
    // If component "HandleVisible" changes, the whole content of the component
    // "ParameterValues" will be updated, even if the graphic component
    // "PaintableGraphic" didn"t even change
    // => 🔥 Lots of unnecessary network load
    ```

    ```hive
    // ✅ Do instead: Split into 2 components with 2 SigSlos:
    // Component "StandardParameterValues"
    [Viewer3d.tagParameter("Handle", "visible", HandleVisible), Viewer3d.tagParameter(Materials3d.matHandle, "color", HandleColor)][
      // Component "PaintableGraphicParameterValue"
      Viewer3d.materialParameter(Materials3d.matPaintable, "albedoTexture.image", PaintableGraphic.Value.ToText())
    ]
    // If component "HandleVisible" changes, only the component
    // "StandardParameterValues" will be updated
    // Component "PaintableGraphicParameterValue" stays untouched
    // => 👍 Less network load
    ```

4.  Be cautious when interacting with other properties of the affected material

4.1 Albedo Color

The materials [albedoColor](https://doc.babylonjs.com/typedoc/classes/BABYLON.PBRMaterial#albedoColor), which is set by the "color" parameter, will be layered with the "albedoTexture" from the albedo texture parameter.  
The resulting texture will be a mixture of "albedoTexture" and "albedoColor" .  
If this is not desired, make sure to set the "albedoColor" to white, in this case the paintables original color will be preserved.

Texture with **turquoise** color, albedo color is set to **white**.  
Original turquoise color is preserved.  
![image25](<img/3d-viewer-control/image(25).png>)

**Turquoise** texture overlapped with **red** albedo color.  
Original turquoise color is altered.  
![image.png](<img/3d-viewer-control/image(26).png>)

This also works the other way around. If you want to control the paintables color via the "albedoColor" property you have to make sure, that the original albedo texture image is completely **white** as well.

4.2 Transparency Mode

You may face the issue that transparent areas of albedo texture images appear black.  
![image.png](<https://docs.combeenation.com/assets/images/image%2827%29-3a599d2c5e5841e4a6d943004354b8d6.png>)

This can be fixed by tweaking some material settings:

- set [transparencyMode](https://doc.babylonjs.com/typedoc/classes/BABYLON.PBRMaterial#transparencymode) of the desired material to **2**, which is "alpha blend".
- activate [useAlphaFromAlbedoTexture](https://doc.babylonjs.com/typedoc/classes/BABYLON.PBRMaterial#usealphafromalbedotexture)
- activate [albedoTexture.hasAlpha](https://doc.babylonjs.com/typedoc/classes/BABYLON.Texture#hasalpha)

![image.png](<https://docs.combeenation.com/assets/images/image%2828%29-278d712b1c51a8846283f4f775403e08.png>)

:::info
These properties are automatically set when creating a material asset from the "**Transparent SVG**" template.
![image.png](<https://docs.combeenation.com/assets/images/image%2879%29-e383cd154b12d41f22113b7c9bc382d8.png>)
:::

### Extension with custom code

If you need more functionality than the 3d viewer control provides out of the box, you can use custom code to extend it by adding custom parameter observers, adjusting the viewer settings and much more.

See [3d viewer control with custom code](/docs/configurator-ui-ux/controls/3d-viewer-control-with-custom-code) for more details on how to do this.

---

## 3d viewer docs

For detailed description of the 3D viewer api see the dedicated [3d viewer documentation](https://3dviewer.docs.combeenation.com/).

---

## Combobox

The combobox control allows you to present tabular data in an interactive dropdown list, showing a variety of options of which the user can chose one.

Here is an example of such a combobox showing a list of products:

![image.png](<https://docs.combeenation.com/assets/images/image%2847%29-088fb8fe25771efad04ee8fdfd3cc45f.png>)

### Basic usage

The usage of the combobox is mostly similar to the [dataview](/docs/configurator-ui-ux/controls/dataview). The most notable difference is that the combobox only comes with a **default layout** and provides **no custom layout** like the dataview.

See the following sections of the dataview for more details:

- [Quick start](/docs/configurator-ui-ux/controls/dataview#quick-start)
- [How to connect the data](/docs/configurator-ui-ux/controls/dataview#how-to-connect-the-data)
  - [How to prepare the table component](/docs/configurator-ui-ux/controls/dataview#how-to-prepare-the-table-component)
  - [Minimize the data](/docs/configurator-ui-ux/controls/dataview#minimize-the-data)
- [How to handle user selections)](/docs/configurator-ui-ux/controls/dataview#how-to-handle-user-selections)

---

## Configurator control

The configurator control is a static control which exists by default in every configurator and cannot be deleted or renamed. It has no visual representation and mainly serves as a hub for Signals and Slots which neither belong to a control nor a component.

### SigSlos

#### IFrame size

The size of the configurator itself can be observed with the `Size changed` signal and adjusted with the slots `Set IFrame width` & `Set IFrame height`.

E.g. you can create the following `SigSlo` to write the current width of the configurator into the `CfgrWidth` components `input` every time the configurators size changed:

```none
Configurator.SizeChanged -> CfgrWidth.SetValue(Configurator.ConfiguratorWidth)
```

:::info
The `Size changed` `SigSlo` also works in the design editor.  
Therefore one advantage of implementing different layouts based on the configurator size saved in a component like `CfgrWidth` & `CfgrHeight` versus using CSS media queries is that the former allows easier testing and editing for different sizes live within the design editor.
:::

The `Set IFrame width` & `Set IFrame height` slots allow you to set a dedicated width & height for the IFrame on the [parent page](/docs/integrations-and-api/embedding-and-whitelist) in which the configurator is embedded. Those slots won't do anything if the configurator is opened "full screen" (not embedded in parent page).

:::warning
We can't guarantee that the slots `Set IFrame width` & `Set IFrame height` are working as expected under all circumstances. For example, the parent page could interfere by defining the IFrame's size using some very strong CSS rules etc.
:::

#### Load mask

You can show & hide a system load mask with some text of your choice with the slots `Show load mask` & `Hide load mask`.

#### Restart configuration

The configurator control's `Restart configuration` slot can be used to restart a running configuration.

The slot takes 2 paramters:

- `Preset ID`: The preset ID from which the components `input` values should be copied from. If not given (an empty string), the preset of the currently open configuration is used.
- `Copy configuration values`: True to copy all component `input` values to the newly created configuration. False to create a completely new configuration.

Possible use cases for this slot:

- Start a new configuration after the checkout succeeded to allow the user to configure a second product.
- Reset configurator to start afresh.

#### Redirect parent page

Allows the configurator to change the URL of the parent page. This requires the correct embedded Combeenation plugin on the [parent page](/docs/integrations-and-api/embedding-and-whitelist).

#### Fire analytics event

Forwards certain event data into the "[data layer](https://developers.google.com/tag-platform/tag-manager/datalayer?hl=de)", which can then be interpreted by the [Google Tag Manager](https://developers.google.com/tag-platform/tag-manager?hl=de).

If the configurator is embedded in an IFrame, the event data will be forwarded to the data layer of the parent page instead.  
This requires the correct embedded Combeenation plugin on the [parent page](/docs/integrations-and-api/embedding-and-whitelist).

The slot takes 2 parameters:

- `event`: Key for event identification
- `eventData`: Optional metadata for the event. By default this is a string, valid JSON notation like `{ "price": 10 }` will be interpreted and forwarded as object.

---

## Control DOM & CSS classes

### Common classes for all controls

- cfgr-ctrl
- cfgrctrl-disabled

### Label

    div.cfgr-label

    div.cfgrctrl-innerlabel

### Buttons

- Button
- Checkout Button
- Share Button
- Wizard navigator button

  {"button"}
  {".cfgr-btn"}
  {".cfgr-checkoutbtn"}
  {".cfgr-sharebtn"}
  {".cfgr-wizardbtn"}
  {".cfgrctrl-pressed"}

    {"div.cfgrctrl-innerlabel"}

:::info
The inner structure of an upload button differs a little.
:::

### Textbox

    {"div.cfgr-textbox"}

      {"label.cfgrctrl-caption"}

      {"input.cfgrctrl-field.cfgrctrl-input"}

:::info
The `input` element is a `textarea` for multiline textboxes
:::

### Checkbox & Radiobutton

- Checkbox
- Radiobutton

    {"div"}

      {".cfgr-checkbox"}

      {".cfgr-radiobutton"}

      {".cfgrctrl-pressed"}

    {"label.cfgrctrl-caption"}

      {"div.input-wrapper"}

        {"input.cfgrctrl-input.cfgrctrl-field"}

          {":checked:disabled"}

        {"label.custom-bckgr"}

### Panel, Layer & Wizard Page

- Panel
- Layer
- Wizard Page

    {"div.cfgr-container"}

      {".cfgr-panel"}

      {".cfgr-layer"}

      {".cfgr-wizardpage"}

      {".cfgrctrl-withheader"}

      {".cfgrctrl-collapsible"}

        {".cfgrctrl-expanded"}

        {".cfgrctrl-collapsed"}

      {"div.cfgr-container-header"}

          {"label.cfgr-container-headerlabel"}

          {"div.cfgrctrl-collapse-icon"}

      {"div.cfgr-container-inner"}

      {"Child controls"}

![](https://docs.combeenation.com/assets/images/panel-bd92efbb8fcbb499632f6fcc95a56de9.png)click to expand

### Wizard & Wizard Navigator

- Wizard
- Wizard navigator

    {"div.cfgr-container.cfgr-panel"}

      {".cfgr-wizard"}

      {".cfgr-wizardnavigator"}

      {"div.cfgr-container-inner"}

        {"Wizard page"}
      {" "}

        {"Wizard navigator button"}

### Dataview

:::info
The divs for the image (".cfgr-dataview-item-img") and label are not there when using a [custom layout](/docs/configurator-ui-ux/controls/dataview#layouting) with your dataview.
:::

    {"div.cfgr-panel.cfgr-dataview"}

      {"div.cfgr-dataview-view"}

        {"div.cfgr-dataview-item"}

          {".cfgrctrl-hover.cfgrctrl-selected"}

          {"div.cfgr-dataview-item-img"}

          {"label"}

![](https://docs.combeenation.com/assets/images/dataview-595686af0d8db880d4b4e489bc609db5.png)

### Combobox

    {"div.cfgr-combobox"}

    {"label.cfgrctrl-caption"}

      {"div.input-wrapper"}

        {"div.x-form-item"}

          {"div.x-form-item-body"}

            {"div.x-form-trigger-wrap"}

                {"div.x-form-text-wrap"}

                {"input.cfgrctrl-field"}

              {"div.x-form-trigger"}

    {"div.cfgr-combobox-list"}

      {"div.cfgr-combobox-list-list-ct"}

        {"ul.x-list-plain"}

          {"div.cfgr-combobox-item"}

            {".cfgrctrl-hover.cfgrctrl-selected"}

            {"label"}

            {"div.cfgr-combobox-item-img"}

![](https://docs.combeenation.com/assets/images/combobox-e386b8d3b3f771b70ca0c69716a43a10.png)

The inner structure of `div.cfgr-combobox-item` may vary depending on the value of the comboboxs Layout property.

The `div.x-form-trigger` is hidden in most themes since they implement the "drop down icon" using CSS after & before pseudo selectors.

### Graphicview

    {"div.cfgr-graphicview"}

    {"svg"}

### External content

- External content
- ShapeDiver 3d

    {"div.cfgr-externalcontent"}

      {".cfgr-shapediver3d"}

    {"iframe.cfgr-iframe"}

### Slider

    {"div.cfgr-slider"}

      {"div.slider"}

        {"div.noUi-base"}

          {"div.noUi-origin"}

          {"div.noUi-handle"}

![](https://docs.combeenation.com/assets/images/slider-e312b81082b4ba8548b8add9b91928a4.png)

### Viewer 3d

    {"div.cfgr-viewer3d"}

    {"canvas"}

      {"div.viewer-load-mask"}

      {"div.viewer-load-mask-icon"}

      {"div.viewer-load-mask-text"}

      {"div.viewer-error-text"}

        {"span"}

        {"span.viewer-error-text-hide-icon"}

#### Augemented reality layer

The viewers augmented reality layer is implemented in the "cfgr parent" control, to ensure that the layer is shown across the whole configurator an not only above the viewer control.

The layer still consists of viewer CSS classes and can be adapted accordingly.

    {"div.viewer-ar-layer"}

      {"div.viewer-ar-layer-content-panel"}

      {"div.viewer-ar-layer-exit-icon"}

      {"div.viewer-ar-layer-qr-code"}

      {"span.viewer-ar-layer-sub-title"}

      {"span.viewer-ar-layer-description"}

      {"a.viewer-ar-layer-link"}

---

## Dataview

The dataview control allows you to present tabular data in a visually appealing and user-friendly interface. You can seamlessly showcase information with diverse layouts, allowing for customization based on specific needs.

The dataview usually allows your users to select 1 item from a set of different options.

Here is an example of such a dataview showing a list of vertically stacked products, where the second one is currently selected and the last one is disabled as it is out of stock at the moment:

![image.png](<https://docs.combeenation.com/assets/images/image%2844%29-5652db2513c703612bd2c98efc9cd815.png>)

### Quick start

The data shown in a dataview usually comes from a [table component](/docs/configurator-logic/components/table-component). It can also come from a [record component](/docs/configurator-logic/components/record-component) but that is an older approach which is not recommended anymore.

Each record (or row) in the connected table component is represented by 1 entry (or item) in the dataview. The example dataview shown above, is connected to a table component which consists of 4 records.

The usual workflow to populate the dataview with data looks like this:

1.  Create a table component which queries the data you'd like to show from a [data source](/docs/asset-management/data-source-asset/basics).  
    When using the dataviews default layout, you need to ensure that your query results in at least 2 columns named `value` & `text`.  
    You can rename the columns of your data source if it does not come with a `value` & `text` column. See [projecting the data](/docs/configurator-logic/hive-queries#projecting-data) in the Hive Queries documentation for more details on how to rename columns in a query.
2.  Enable Hive for the dataviews `entries` property by clicking on the code icon next to the properties input field.
3.  Get the data from the table component by writing a simple script like `NameOfTableCmp` in the `entries` property.

See [how to connect the data](/docs/configurator-ui-ux/controls/dataview#how-to-connect-the-data) and [how to handle user selections](/docs/configurator-ui-ux/controls/dataview#how-to-handle-user-selections) for more details on how to properly prepare the connected table component etc.

### Layouting

You can either use the **default layouting** options which allows you to show exactly **1 text and 1 image** per item (or entry) or you can use a **[custom layout](/docs/configurator-ui-ux/controls/dataview#custom-layouts)** which gives you the freedom to provide your **own HTML layout** and show **arbitrary data**.

The dataview uses the default layout when the `custom layout` property is not set. You can find a set of customization options for the default layout within the `item layout` section in the dataviews property list. Those properties allow you to show/hide the text, position it, change the font, adjust spacings & sizes etc.

You can always use [custom CSS](/docs/category/custom-css) to further customize the look of your dataview but you cannot change the shown content with a default layout which is where the `custom layout` comes into play.

### How to connect the data

The `entries` property is where your dataview **receives its data to show from**. You usually connect it to a [table component](/docs/configurator-logic/components/table-component) which queries data from a [data source](/docs/asset-management/data-source-asset/basics) like an Excel file.

You usually want to directly reference the records of a table component which you can do by **first activating Hive** for the `entries` property and then simply writing the name of the table component into the property.

You can also write [queries](/docs/configurator-logic/hive-queries) directly into the `entries` property, e.g. to only return relevant columns or adjust column values.

#### How to prepare the table component

##### Default layout

When using the default layout (i.e. when property `custom layout` is not set), your table component **needs to provide columns** with the following names:

- `value` (required)
- `text`, `imageUrl`, `itemTooltip` & `itemDisabled` (all optional)

If your data source comes with columns of **different names**, you can **rename those columns** within the table component query.

Here is an example of how that could look like for a data source named `ProductsData` which comes with columns named `Id`, `Name` & `InStock`:

```hive
from ProductsData select {
  // Rename column `Id` to `value`
  .value = .Id,
  // Rename column `Name` to `text`
  .text = .Name,
  // Rename column `Name` to `itemTooltip`
  .itemTooltip = .Name,
  // Rename column `InStock` to `itemDisabled` and invert its value
  .itemDisabled = not .InStock
}
```

See [projecting the data](/docs/configurator-logic/hive-queries#projecting-data) in the Hive Queries documentation for more details.

##### Custom layout

When using a custom layout, you can use **arbitrary column names**. See the [custom layouts](/docs/configurator-ui-ux/controls/dataview#custom-layouts) section for more details on how to structure & use the data in a custom layout.

There are only 2 **columns with special meaning** when working with a custom layout:

- The **first column** is always considered the **unique value** of a given record. The dataview uses this value to decide which item to select & when writing selection changes back to the components. See [how to handle user selections](/docs/configurator-ui-ux/controls/dataview#how-to-handle-user-selections) for more details on this.
- A column named `itemDisabled` can be used to [disable items in a dataview](/docs/configurator-ui-ux/controls/dataview#how-to-disable-items).

#### Minimize the data

All data within your table component will be transmitted to the configurator. Including data which is not needed by the dataview **can make the configurator slow**, especially for users with slow internet.

A good rule of thumb is to **only include the columns** in your query which you actually **want to show in your dataview**.

When using the default layout, this is only columns named `value`, `text`, `imageUrl` & `itemDisabled`. When using a custom layout, you should only include the columns which are actively referenced in your custom layout template and nothing else.

You can always check which data is transmitted to the configurator by selecting the dataviews `entries` property. All data shown in the result view is transmitted to the configurator.

#### How to use data from a record component

Accessing data from a record component pretty much works the same as accessing data from a table component. The only difference is that you need to write `#NameOfRecordComponent.Records` (note the `#`) into the `entries` property instead of just the component name like with table components.

### How to handle user selections

The dataviews `value` property is used to tell the dataview **which item to select** and can be used to write selection changes back into a component using the dataviews `value changed` slot.

When using a **default layout**, you usually set this property to the value of the **`value` column** in your connected table component. When using a **custom layout**, you set it to the value of the **key column** which is always the **first column** in a table component.

Dealing with user selections in a dataview usually consists of the following parts:

- A **table component** which is connected to the `entries` property and provides the data to show (see [how to connect the data](/docs/configurator-ui-ux/controls/dataview#how-to-connect-the-data)).  
  Let's call this component `ProductsTable` here.
- A **value component** which holds the record of the selected entry e.g. named `SelectedProduct`.  
  Use the "Create selection component" button in the table component editor to let the system create this component with a sensible default rule for.
- Reflecting `SelectedProduct` as **selection in the dataview**:  
  To achieve this, simply activate Hive for the dataviews `value` property and write `SelectedProduct.value` into the rule.  
  When working with custom layouts, the name `value` could vary and is the name of the first column in your connected table component.
- **Updating `SelectedProduct`** when the dataview selection changes using SigSlo:  
  Signal `dataview.ValueChanged`, slot `SelectedProduct.SetValue` given the `value` property of the dataview.

If the `value` property is not set or set to some invalid value, no item is selected.

The selection is usually represented by some highlighting like a different colored border, different background etc. for the selected item.

When using the default layout, you can use the properties within the `item layout` section to customize this highlighting.

If you need more flexibility, you can always use custom CSS to customize all items which match the selector `.cfgr-dataview-item.cfgrctrl-selected` within your dataview. This also works for custom layouts!

### Custom layouts

With the default layout, the dataview can show exactly 1 text and 1 image and gives you a few basic options to customize the layout (position of text & image etc.).

The `custom layout` property gives you the freedom to provide **your own HTML** layout and **show arbitrary data**.

#### How to define the layout

Within the `custom layout` you can write pure HTML with the additional option to access data coming from the `entries` property (i.e. data from a table component).

Since we also allow you to [access data from your table component](/docs/configurator-ui-ux/controls/dataview#how-to-access-the-data) in this HTML, this is not strictly HTML but actually a HTML template which is why we'll be referring to this HTML as "template" from now on.

The template you write here is automatically repeated for every entry in the dataview. Also, each entry is automatically wrapped inside a `div` with the class `.cfgr-dataview-item` which is the same as for entries in a default layout. This `div` is needed because it also provides you helper classes like `.cfgrctrl-selected` & `.cfgrctrl-hover` with which you apply different styles to selected & hovered items in your custom layout as well.

See [control DOM & CSS classes](/docs/configurator-ui-ux/controls/control-dom-and-css-classes) for more details on those automatically added classes we just mentioned.

For example, when using the template `<div>hello!</div>` and connecting `entries` to a table component with 3 records, you'll see the text "hello!" repeated 3 times in your dataview and the final HTML in the configurator will look like this:

```html
<div class="cfgr-dataview-item"><div>hello!</div></div>
<div class="cfgr-dataview-item"><div>hello!</div></div>
<div class="cfgr-dataview-item"><div>hello!</div></div>
```

Obviously, it doesn't make much sense to repeat the same static content over and over again which is why the next section will explain how to put actual data into your template.

#### How to access the data

In order to inject data from the connected table component into your HTML template, you can add **template blocks** starting with `{[` and ending with `]}` to your template. Within those blocks you can **write JavaScript code** which is executed at runtime, when rendering the dataviews entries.

Access to all **data from the connected table component** is provided through an object named `values` which you can use within the template blocks. All columns from the connected table component are accessible as properties of this `values` object.

E.g. if the connected table component consists of columns named `Key`, `Title`, `Size` & `PricePerLiter`, you can access the corresponding data using `{[ values.key ]}`, `{[ values.title ]}`, `{[ values.size ]}` & `{[ values.priceperliter ]}` within the `custom layout` template.

The properties accessed within the `values` object need to be written all lower case, no matter how they're actually named in the table component.

E.g. the column named `PricePerLiter` needs to be accessed using `values.priceperliter`.

If the column value you're accessing is not of a primitive type like `number`, `text` or `boolean`, but a more complex object like an `image`, you have to use the correct casing to get its sub properties.

Imagine a column named `Thumbnail` which is of type `image`. This `image` is an object which consists of properties like `Url`, `Width` & `Height`. If you'd like to get the URL of the image, you have to write `values.thumbnail.Url` where `thumbnail` is all lower case and its property `Url` is still camel cased.

#### Debugging tip

If you're unsure how the properties within your `values` object are actually named or structured, you can use the following trick:

Use the template block `{[ console.log('values:', values) ]}` anywhere within your template. This will print the values of each record to your console whenever the dataview renders new content which allows you to investigate the `values` object in detail.

Remember: Within the template blocks `{[ ... ]}` you can write any kind of JavaScript code which is executed at runtime!

#### How to disable items

The dataview automatically disables all items whose corresponding record in the connected table component has a value of `true` in a column named `itemDisabled`.

Those disabled items come with a default styling (reduced opacity). If you'd like to adjust this styling, you can do so by providing your own styles in custom CSS for elements with the classes `.cfgr-dataview-item.cfgrctrl-disabled` within your dataview.

#### How to add a tooltip

Similar to "disabling items" it's also possible to add a tooltip.  
To do so, simply add a column named `itemTooltip` with the desired text in the connected table.

#### Usage example

Imagine a table component named `ProductsTable` with the following query:

```hive
from Products select {
  .Id, .Title, .DetailText, .Size, .PricePerLiter, .Thumbnail, .itemDisabled
}
```

Now you'd like to show this data in the following form:

![image.png](<https://docs.combeenation.com/assets/images/image%2844%29-5652db2513c703612bd2c98efc9cd815.png>)

You can achieve this layout using the following property values:

- Entries: `ProductsTable` (activate Hive for the property!)
- Custom layout:

  ```html
  <div class="products-dv--background" style="background-image: url({[ values.thumbnail.Url ]});"></div>
  <div class="products-dv--title">{[ values.title ]}</div>
  <div class="products-dv--priceWrapper">
    <div class="products-dv--priceTotal">€ {[ (values.priceperliter * values.size).toFixed(2) ]} *</div>
    <div class="products-dv--pricePerLiter">€ {[ values.priceperliter.toFixed(2) ]}/Liter *</div>
  </div>
  ```

As you can see in the custom layout template above, you can write fully functional JavaScript inside the template blocks (`{[ ... ]}`). This means that you can also perform calculations, formatting etc. there if needed.

E.g. `values.priceperliter * values.size).toFixed(2)` is vanilla JavaScript.

Obviously, this also needs some custom CSS to look like the dataview shown above but I leave this as an exercise to the reader.

Hint: You can provide your own classes in the template (like `products-dv--background` in the `custom layout` above) and use those classes to style the entries.

#### Adding interactive elements to the template

You can also add interactive elements like buttons to the template. One use case of this would be to show a plus and a minus 1 button on each element which adds or removes items from a cart.

Whilst you cannot interact with those buttons directly in Hive or via SigSlo, you can always use [custom JS](/docs/configurator-ui-ux/customjs/custom-js) to deal with button clicks etc.

Here's a very simple example, showing how you can add such buttons & how to react on clicks in custom JS:

**Template:**

```html
<div>{[ values.title ]}</div>
<button class="add-button" data-item-id="{[ values.id ]}">+1</button>
<button class="remove-button" data-item-id="{[ values.id ]}">-1</button>
```

HTML

**Custom JS:**

```js
CfgrUtils.onCfgrReady(() => {
  // ...

  $('.cfgr-dataview').on('click', '.add-button', event => {
    // Get info about clicked row from `data-item-id`:
    const itemId = event.currentTarget.dataset.itemId;
    // ...
  });

  // ...
});
```

There are 2 things to be especially aware of:

- Ensure that the click listener is installed after the control has surely been rendered. E.g. in callback to [CfgrUtils.onCfgrReady](https://cjs.docs.combeenation.com/classes/cfgrutils.html#oncfgrready).
- Don't install the click event on the button itself but use event delegation on the dataview to "get to the button".  
  In the example above, this is why we're using `$('.cfgr-dataview').on('click', '.add-button', () => ...)` instead of `$('.cfgr-dataview .add-button').on('click', () => ...)`.  
  Events installed directly on the button would probably work initially but won't work anymore after the items in the dataview change at runtime as all dataview items are destroyed & re-created on such updates.

#### More advanced use cases

The templates for our custom layouts are powered by a technology called `XTemplates` from `ExtJS`. Therefore you can also use most of the features they're providing in your templates as well.

Since we couldn't do a better job in explaining them, then the ExtJS team itself, we don't even try and refer you to their excellent docs to find out more about what is possible:

[https://docs.sencha.com/extjs/6.2.0/classic/Ext.XTemplate.html](https://docs.sencha.com/extjs/6.2.0/classic/Ext.XTemplate.html)

---

## Social Share

The Share-Control is essentially a button with a fixed click behaviour. Based on the chosen platform it changes it's default design and opens the respective 'Share window' when clicked.

:::info
The share functionality is only available in published configurators.
:::

### Styling

#### Default buttons appareance

![SocialShareButtons.png](<img/social-share/SocialShareButtons(1).png>)  
It's recommended to use the default styling to preserve it across all platforms and be safe for future updates.

#### Small design changes

Some changes are specifically supported without the need to overrule the CSS:

- Text only: Set `Show icon` to false
- Icon only: Remove `Value`
- Width/Height: The content stays centered and the icon resizes to some extent

Also the whole hover effects can be disabled by simply removing the CSS class `default-hover`.

#### Blank button

If a totally different design is required, a blank button can be aquired with the following steps:

- `Value`: remove content
- `Show icon`: set to false
- `CSS Class`: remove class "default-hover"

Afterwards it can be designed like any other button with background images, custom css-rules, etc.

### Share options

By default all the relevant values in the properties are provided as so called "Open Graph Meta Tags" or in short "og-Tags". Most platforms process those tags but the result can differ between every platform.  
It's recommended to fill all properties with valid content to get the best result, even though some properties aren't visible to the user (like author).

**Graphic**: Name of a Graphic-Component

**Embed Url**: Base Url where the Configurator is embedded. The Share-Link will be appended automatically.

#### Known behaviour

The behaviour highly depends on the implementation of the respective platform. This means that the following table may not be up to date or it gets changed from time to time.

✓ Part of the post/message (maybe shown a second time in the preview)

○ Visible but not directly in the post/message (e.g. as part of the preview)

✖ Not Visible

| Platform  | Title | Description | Graphic/Preview         |
| --------- | ----- | ----------- | ----------------------- |
| Facebook  | ○     | ○           | ✓                       |
| Pinterest | ✕     | ✓           | ✓                       |
| Twitter   | ✓     | ✓           | ✓ (may load with delay) |
| LinkedIn  | ○     | ✕           | ✓                       |
| WhatsApp  | ✓     | ✓           | ✓ (may load with delay) |

---

## Tooltips for controls

Tooltips can be set for most of the controls in the configurator editor to provide additional information to the user.  
To get started, simply create a control like a `Button`, go to `Properties > Tooltip > Tooltip text` and enter your value.  
Afterwards you instantly can see your tooltip, when hovering over the control.  
![image.png](<https://docs.combeenation.com/assets/images/image%2867%29-1f30e6c8b97e9f150b9214555c415965.png>)

### General tooltip properties

Under the top-most control `Configurator` you can find some general settings which will be applied to every tooltip. (e.g. don't show the arrow which is pointing at the target control).

Other properties can also be set with Custom Code:  
`CtrlUtils.Tooltips.updateGeneralProperties({ trigger: 'click' });`

#### Property "Touch hold behavior"

By default the tooltips have a basic support for touch devices, by holding the control.  
It's recommended to show the tooltip only after a brief amount of time, so that the user doesn't immediately see a tooltip when he just wants to press a button or similar.

Available options:

- Hold 0.1s: Touch and hold 100ms to show the tooltip
- Hold 0.5s: Touch and hold 500ms to show the tooltip
- Hold: Instantly show the tooltip (even when the user touches/clicks very fast)
- Disabled: Never show tooltips on touch

### CSS styling and themes

In the `CSS Styles` tab of the `User interface` you can easily style your tooltips.

#### Quick start

1.  Go to the the `CSS Styles` editor
2.  [Recommended] Create a dedicated module called `Tooltip`
3.  Enter `.tippy-snippet` in the code editor to get a snippet-suggestion
    - Press Enter or Tab to insert the snippet
4.  Overwrite the colors or extend the CSS as needed

![image.png](<https://docs.combeenation.com/assets/images/image%2864%29-64402d67596035bd5d4c8848d7ec93dd.png>)

#### Themes (multiple tooltip styles)

If a configurator requires different designs of tooltips, it's also possible to add additional themes.  
As a quick starting point we also provide the code snippet `.tippy-snippet-theme` for that.

1.  Insert the snippet
2.  Enter your theme name (e.g. `[data-theme~="light"]`)
3.  Enter the identical name `light` under the property `Tooltip > Theme` of your control

#### DOM structure and further styling

The tooltips we provide are based on tippy.js.  
Please see the [official docs of tippy.js](https://atomiks.github.io/tippyjs/v6/themes/) for details about the structure and required CSS selectors.

### Dataview control

It's also possible to add tooltips to the individual items of the Dataview.  
If the entries are static or connected to a `Table Component` a field/column named `itemTooltip` is required in the property `Entries`.  
For details see [Dataview - Connect data](/docs/configurator-ui-ux/controls/dataview#how-to-prepare-the-table-component).

##### SigSlo restriction

If a `Table Component` is connected by a SigSlo it's not possible to map a tooltip.  
However, it's possible by using `Hive in controls` for the property `Entries` as explained above.  
In general this is also the recommended way, as the SigSlo may be phased out in the future.

For `Record Components` the mapping is possible and can be chosen in the SigSlo dialog.

### Custom code

With Custom code you can get full access to the tippy.js instances of existing tooltips and also create new ones.  
Simply retrieve a control with one of the functions under `CtrlUtils` and  
Besides that, general functions can be found under the namespace `CtrlUtils.Tooltips`.

```ts
// Set custom content/text
const btn = CtrlUtils.getButton(CtrlNames.button1)!;
btn.setTooltipContent('My <b>new</b> content!');
```

```ts
// Change `placement` and add custom `onShow` function
const btn = CtrlUtils.getButton(CtrlNames.button1)!;
const btnTooltip = btn.getTooltip();
btnTooltip.setProps({
  placement: 'right',
  onShow: function () {
    console.log('onShow');
  }
});
```

See the [official docs of tippy.js](https://atomiks.github.io/tippyjs/v6/all-props/) for a full list of all the available properties and the API in general.

### FAQ

#### How can I change text dynamically (e.g. for i18n)

The text property of tooltips allows `Hive in controls`.  
Simply click the icon next to the property and enter your Hive rule which outputs your translated text.

#### Why can't I set a specific property in the editor which exists for tippy.js

The main intention was to keep it as simple as possible and that the editor doesn't get cluttered with rarely used properties.  
With Custom code we also provide full control over the general settings and individual instances of tippy.js, so you can customize it in any possible way.

Feel free to contact us, if you still think that additional properties would be helpful.

---

## Custom code

:::info
Custom code is based on TypeScript and fully replaces the (now deprecated) CustomJS projects.  
It provides all the features from CustomJS in a more sophisticated manner.
:::

With custom code you can **extend your configurators capabilities** in many ways. It allows you to write TypeScript which then runs in your configurator.

The following are just a few examples of the countless possibilities which open up with this feature:

- Extend functionalities for existing **components** and **controls** (see [custom code utils](https://custom-code.docs.combeenation.com/))
- Extend functionalities for the **viewer control** (see [3d viewer](https://3dviewer.docs.combeenation.com/))
- Add **new controls** like a date time picker etc.
- **Fetch data** from external services like **real-time** prices calculated on your servers or real-time inventory from your CMS etc.
- Send **live analytics** to external services like [Google Tag Manager](https://tagmanager.google.com/) etc.

### How to get started

#### Setup a TypeScript project

We provide a starter project which comes with our recommended configuration (build tools, config, pre-installed packages etc.) and gives you everything you need to get started quickly.

:::info
All of the following assumes that you have a current version of Node.js & npm (or some equivalent) installed on your computer.
:::

- Open a terminal (e.g. command line in windows) in the folder where you want to create your project
- Run `npm create @combeenation/custom-code@latest`
- Follow the instructions of the script to create a starter project using TypeScript

### How to use it

#### Where to start writing code

The main starting point is usually the callback to [CfgrUtils.onCfgrReady](https://custom-code.docs.combeenation.com/functions/CfgrUtils.onCfgrReady.html#onCfgrReady) within `src/index.ts` in which you have the guarantee that you can safely access all components & controls.

You can either write all your TypeScript logic within this function or spread it over as many functions/modules/files as you like.

:::info
Always ensure that you only access components & controls **after** the callback to [CfgrUtils.onCfgrReady](https://cjs.docs.combeenation.com/classes/cfgrutils.html#oncfgrready) was called. Otherwise there is no guarantee that all components and controls are fully bootstrapped and you could run into undefined behavior or errors.
:::

#### How to run & debug during development

There are 2 ways to run & debug your application during development:

- Debugging in **Chrome dev tools**:
  - Run `npm run dev` which will start a local dev server
  - Open the preview of your configurator draft
  - Click the "TS icon" in the upper right to connect to the local instance
    - As alternative you can also add the URI parameter `&localcts=true` manually
  - Debug in browser dev tools (`F12`)
- Debugging in **VS Code**:
  - Open the view "Run and debug" in VSCode & select "Start dev" in dropdown at the top (this is only needed once).
  - Press F5 to start debugging. This will automatically open a new Chrome window and run `npm run dev` in the background.
  - Open the preview of your configurator draft
  - Click the "TS icon" in the upper right to connect to the local instance
    - As alternative you can also add the URI parameter `&localcts=true` manually
  - Debug directly in VSCode

:::info
The steps above won't persist your custom code in the configurator but will load it from the hard drive of your computer.

If you'd like to share the configurator with someone else or want to publish it, you always have to upload your custom code to the `CustomJS` component as explained in [how to upload custom code to the configurator](/docs/configurator-ui-ux/custom-code/custom-code-#how-to-upload-custom-code-to-the-configurator).
:::

#### How to upload custom code to the configurator

Uploading your custom code to the configurator is always required when you want to share your configurator with someone else or want to publish it.

- Run `npm run build` in your custom code project on your computer
- Open the configurator editor of your draft and expand "Custom Code" in the header bar
- Upload or replace the script with the newly built file in your project folder under dist/cfgr.js

#### Update component typings

The required typings to work with Components can be retrieved in your Configurator editor or the preview.  
The recommended way is to run the development server (as explained above) as it allows you to directly connect this local environment with your Configurator.  
The UI controls should automatically be available as soon as you open a preview which is connected to the local TS.  
**Configurator Preview**  
![image.png](<https://docs.combeenation.com/assets/images/image%2849%29-354b61b24600fcf7df0fc751dbb1a829.png>)

**Configurator Editor**

- If you aren't connected to your local IDE yet, ensure that your dev server is up and running with `npm run dev`
- Expand "Custom Code" in the header bar and click "Connect"
- On a successful connection you get a new toolbar in the Components list on the left:  
  ![image.png](<https://docs.combeenation.com/assets/images/image%2868%29-e6c08a26b363efd8ad8ae492b1b2319b.png>)

**Update them manually**

- Open your configurator draft
- Expand the menu of the `Components` list on the left
- Select `Download custom code definitions`
- Save/Replace the file in your code project

#### How to access components & controls

The [custom code utils](https://www.npmjs.com/package/@combeenation/custom-code-utils) package is mandatory to interact between your custom code and the configurator.

It allows you to read values from components, write new input values to them and interact with the controls in your configurator and many other features.  
To work with a component ensure that your "configurator definitions file" is up to date (see previous step).  
This file basically represents your components list.  
If you want to access a component simply import the variable which has the identical name as your component.  
This variable then provides all the available functions and properties you need.

```ts
const myValue = await MyCmp.getValue();
MyCmp.setInput('myNewString');
```

TypeScript

See the [utils API documentation](https://custom-code.docs.combeenation.com/) for more details on how to use them.

The custom code utils come pre-installed with our [TypeScript start project](/docs/configurator-ui-ux/custom-code/custom-code-#setup-a-typescript-project).

You can also install them manually using `npm install @combeenation/custom-code-utils`.

#### How to interact with the 3d viewer

Combeenation has built its own 3d viewer, which is used in the [3d viewer control](/docs/configurator-ui-ux/controls/3d-viewer-control).

If the functionality of this 3d viewer control and its SigSlos is not sufficient, it can be extended in custom code using the API of the 3d viewer package itself.

See [3d viewer control with custom JS](/docs/configurator-ui-ux/controls/3d-viewer-control-with-custom-code) for more details.

### FAQ

#### What is the config file `cbn.config.json`?

This file can hold information specific to the Combeenation platform.  
One of its usages is, that it can create a link between your code project and the configurator. This way, the typings (`cfgr-defs.generated.ts`) can be automatically transferred during development.

#### How can I upload files into the configuration?

With version 1.1.0 the so called `Configuration Files` were introduced.  
In Custom code you can find the respective functions under the [namespace CfgnFiles](https://custom-code.docs.combeenation.com/modules/CfgnFiles.html).

PS: It's recommended not to use `Resource components` anymore, as they will be phased out in the future.

---

## Quick start

### Prerequisite

The following guide assumes that the following prerequisites are met. Otherwise please see the more detailed guide about [Custom Code](/docs/configurator-ui-ux/custom-code/custom-code-).

- A Combeenation configurator with basic functionality (some Components, Design, etc.)
- `Node.js` & `npm` (or some equivalent)
- Visual Studio Code (our recommended IDE, but not mandatory)
- Basic knowledge about these tools

### Setup

- In a terminal navigate to the folder where your project should be created
- Run `npm create @combeenation/custom-code@latest`
- Follow the instructions of the script

### Local development

After the setup is done:

- Run `npm run dev` inside your code project
- In the browser, open the preview of your configurator draft
- On the top right click the TS-icon (Toggle local custom TS)
  - This will simply add the query parameter `&localcts=true` to your URI

### Coding

#### [Optional] Create a test Component

In your configurator create a simple Value Component called `MyTestCmp` with the rule

```hive
Input or "Hello World"
```

Plain text

We will refer to this Component in the upcoming snippets.

#### Get Components in code

At this point, our code is runnable but it has no knowledge about the Components yet. To communicate with them, we provide an auto-generated typescript-file which can be easily synced with our tools.

The required UI controls are automatically available as soon as you open a preview which is properly connected to the local environment.  
**Configurator Preview**  
![image.png](<https://docs.combeenation.com/assets/images/image%2849%29-354b61b24600fcf7df0fc751dbb1a829.png>)

**Configurator Editor**  
![image.png](<https://docs.combeenation.com/assets/images/image%2861%29-4228df1b3417404771c2a77e8745dff9.png>)

Simply click on one of the "Sync buttons" and your Components will instantly be available in your IDE.  
With every change in the Components you can click this button again to update them.

At its core, this feature updates the file under `src\typings\cfgr-defs.generated.ts`.

#### Entry point

Inside the `index.ts` you will find the following:

```ts
CfgrUtils.onCfgrReady(() => {});
```

This is the main entry point of the configurator which ensures that your configurator is fully up and running.  
Any kind of initialization code which communicates with the configurator should happen in here.

#### Read the value of a Component

```ts
// See above how to get Components
import { MyTestCmp } from './typings/cfgr-defs.generated';

CfgrUtils.onCfgrReady(async () => {
  const myValue = await MyTestCmp.getValue();
  console.log('RESULT: ', myValue);
});
```

#### Write (set input) of a Component

```ts
// See above how to get components
import { MyTestCmp } from './typings/cfgr-defs.generated';

CfgrUtils.onCfgrReady(() => {
  MyTestCmp.setInput('Hello from custom code!');
});
```

#### Listen to a Component change

```ts
// See above how to get components
import { MyTestCmp } from './typings/cfgr-defs.generated';

CfgrUtils.onCfgrReady(() => {
  // MyTestCmp.setInput('Hello from custom code!');

  MyTestCmp.onValueChanged(newValue => {
    console.log('value updated: ', newValue);
  });
});
```

#### Communicate with controls

The controls can be accessed via their unique name.  
To prevent hard-coded strings inside the code, we recommend to extend the `enum CtrlNames {}` which is already pre-defined under `src\constants.ts`.

```ts
// constants.ts
export enum CtrlNames {
  JS_DummyBtn = 'JS_DummyBtn'
}
```

```ts
// index.ts
import { CtrlNames } from './constants';

CtrlUtils.onCtrlClicked(CtrlNames.JS_DummyBtn, () => {
  // your code
});
```

#### Other utils & helpers

For a full documentation of the available functions see [custom-code.docs.combeenation.com](https://custom-code.docs.combeenation.com/)

Quick overview of other, often used, functions:

- Listen to multiple components at once (e.g. to prevent multiple calls of the handler-function)  
  `CmpUtils.onAnyCmpValueChanged(_update3dModel, [Cmp1, Cmp2, Cmp3]);`
- Create PDF from HTML which is directly stored/uploaded as "Configuraton File"  
  `CfgnFiles.createPdfFromHtml('bom', htmlContent);`

---

## CSS properties (variables)

All browsers which are [officially supported browsers](/docs/integrations-and-api/supported-browsers) also support [CSS properties (variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/--*). Therefore you can basically use them as you wish in your custom CSS.

See [Can I use](https://caniuse.com/#feat=css-variables) for more details on browser support.

### Organizational tip

It is recommended to declare all CSS variables in a dedicated custom CSS module named `Variables` or something the like instead of spreading them all over different modules. This helps you keep an overview of all available variables.

### Changing variable values at runtime

The values of CSS variables declared in custom CSS can be changed dynamically at runtime using the following Signals and Slots:

```hive
CssVars.ValueChanged -> Configurator.updateCssVariables(CssVars.Value)
```

The value which is given to the `updateCssVariables` slot needs to be the value of a record component with column names representing the names of the CSS variable without the leading `--`.

If you want to change CSS variable values dynamically via SigSlo you have to use names which are also allowed in Hive. E.g. you couldn't use names like `label-text-color` but would have to stick to `labelTextColor` etc.

#### Example

Configurator `CssVariables` in company `Combeenation College`:  
[Published demo](https://portal.combeenation.com/Cfgr/College/CSSVARIABLES)

```css
/* Custom CSS */
:root {
  --cfgrBckgrColor: #dd0060;
  --labelTextColor: yellow;
  --labelBckgrColor: #37a58c;
}

.cfgr-parent {
  background: var(--cfgrBckgrColor) !important;
}

.cfgr-label {
  color: var(--labelTextColor);
  background: var(--labelBckgrColor);
}
```

```hive
/* Record component "CssVars" */
{
  { Theme=Text, cfgrBckgrColor=Text, labelTextColor=Text, labelBckgrColor=Text }
  { "Colorful", "#DD0060",           "yellow",            "#37A58C" }
  { "Light",    "white",             "white",             "rgba(0, 0, 0, 0.6)" }
  { "Dark",     "black",             "black",             "rgba(255, 255, 255, 0.6)" }
}
```

---

## Load mask styles

The configurator automatically displays a load mask in several situations to inform users that background tasks are in progress.

By default, these load masks are designed to be unobtrusive and generic, ensuring they blend well with most configurators. However, if you prefer a more distinctive look that aligns closely with your configurator's design, you can easily customize the load masks using custom CSS.

### General purpose configurator load mask

This load mask is designed to inform users when tasks are in progress, during which interaction with the configurator is not possible. By default, it displays a loading spinner icon accompanied by descriptive text:

![2024-12-02_10h57_34.png](https://docs.combeenation.com/assets/images/2024-12-02_10h57_34-9aeb8d4d06763aa4f9ea458c2dcafc62.png)

This type of load mask is displayed in the following situations:

- When a configuration is being prepared for sharing
- During file uploads
- When the configurator is reconnecting to the server, such as in cases of poor internet connectivity
- When the "Show load mask" slot of the configurator is activated
- When custom code invokes [CtrlUtils.showLoadMask](https://custom-code.docs.combeenation.com/functions/CtrlUtils.showLoadMask.html)

#### How to customize

Here is a code snippet, showing how to customize certain parts of the load mask which should give you a good starting point for your own customizations:

```css
/* Change the load masks background which covers the whole configurator */
.cbn-page-mask {
  background-color: rgba(0, 64, 160, 0.4);
}

/* Remove the background of the box in the middle */
.cbn-page-mask .x-mask-msg {
  background: transparent;
}

/* Change font family & color of the description text */
.cbn-page-mask .x-mask-msg .x-mask-msg-text {
  color: white;
  font-family: Inter;
}

/* Hide the default loading spinner icon */
.cbn-page-mask .x-mask-msg .x-mask-msg-text {
  background: none;
}

/* Show a custom pulsating icon */
.cbn-page-mask .x-mask-msg .x-mask-msg-text:after {
  content: '';
  position: absolute;
  left: calc(50% - 16px);
  top: -38px;
  width: 32px;
  height: 32px;
  background: url(https://path/to/your/logo.png) no-repeat center / 32px;
  animation: pulse 1.5s ease-in-out infinite;
}

@keyframes pulse {
  0% {
    transform: scale(1);
  }
  50% {
    transform: scale(1.2);
  }
  100% {
    transform: scale(1);
  }
}
```

All of the above would lead to the following load mask:

![image.png](<https://docs.combeenation.com/assets/images/image%2870%29-1886cdae3d7f65818b1c4291eb0e0026.png>)

### 3d viewer load mask

There are two types of load masks displayed in the 3D viewer:

- A **large load mask** which covers the entire 3d viewer and includes descriptive text to let the user know what is currently happening.  
  ![2024-12-02_10h55_15.png](https://docs.combeenation.com/assets/images/2024-12-02_10h55_15-8bbdd2c461130f85414dd118ae6a3a36.png)
- A **small load mask** which only shows a subtle loading spinner icon located in the bottom right corner of the 3d viewer, without any accompanying text.  
  ![2024-12-02_10h55_31.png](https://docs.combeenation.com/assets/images/2024-12-02_10h55_31-7ed20092b81ca6403a3279cc9eff1efe.png)

The **large load mask** is shown when initially bootstrapping the viewer and when preparing the scene to be [viewed in AR](/docs/configurator-ui-ux/controls/3d-viewer-control#start-ar).

The **small load mask** is shown when new data is being loaded in the background which can be the case when loading a new 3d model into the scene or when changing shown materials & textures.

#### How to customize

Here is a code snippet, showing how to customize certain parts of both, the small & the large viewer load mask, which should give you a good starting point for your own customizations:

```css
/* Make the large load mask cover the whole configurator, not just the 3d viewer, and change its background color */
.cfgr-viewer3d .viewer-load-mask {
  position: fixed;
  background-color: rgba(0, 64, 160, 0.4);
}

/* Change font family & color of the shown description */
.cfgr-viewer3d .viewer-load-mask .viewer-load-mask-text {
  color: white;
  font-family: Inter;
}

/* Hide the default loading spinner icon of the small & large load mask */
.cfgr-viewer3d .viewer-load-mask .viewer-load-mask-icon:before {
  display: none;
}

/* Show a custom pulsating icon for the small & large load mask */
.cfgr-viewer3d .viewer-load-mask .viewer-load-mask-icon {
  width: 32px;
  height: 32px;
  background: url(https://path/to/your/logo.png) no-repeat center / 32px;
  animation: pulse 1.5s ease-in-out infinite;
}

/* Show a background for the small load mask & move it to the top left */
.cfgr-viewer3d .viewer-load-mask.viewer-load-mask-small {
  left: 16px;
  top: 16px;
  width: 52px;
  height: 52px;
  background: #0040a0;
  border-radius: 52px;
}
```

All of the above would lead to the following load masks where the large one resembles the appearance of the customized configurator load mask [shown above](/docs/configurator-ui-ux/custom-css/load-mask-styles#how-to-customize):

![image.png](<https://docs.combeenation.com/assets/images/image%2871%29-977bebc0a69e2abad0b09805eee132bf.png>)

---

## Create PDF from HTML content

:::warning
This is no longer the recommended way to create a pdf during a configuration.  
Please refer to [PDF assets](/docs/asset-management/pdf-asset) for the preferred approach.
:::

### General

The custom-js-utils function [CfgrUtils.convertHtmlToPdf](https://cjs.docs.combeenation.com/classes/cfgrutils.html#converthtmltopdf) allows you to create a fully custom PDF, based on any valid HTML input.  
This can be useful for creating offers, a bill of material or similar.

### Minimum requirements

- [Resource component](/docs/configurator-logic/components/resource-component) of type `Document` with a pdf, which acts as a placeholder and will be overwritten
  - When creating the component, the checkbox `User can upload his own resources` must be checked
- `custom-js` project (based on the `.template-project` in your repository)
- A string with valid html
  - Can be generated anywhere, as long as it's available in custom-js afterwards. (components & hive rules, custom-js function, etc.)

### Creating your first PDF

1.  Create a resource component of type `Document` and check `User can upload his own resources`
2.  Add a placeholder pdf to the `Documents`  
    ![image.png](<https://docs.combeenation.com/assets/images/image%2815%29-37ad6cbbbfb0283353b0d4415769a48d.png>)
3.  Create a value component which holds the url of the pdf
    - Rule: `OfferPdf.myPdf.Url`
4.  Add the following code inside the `CfgrUtils.onCfgrReady` of your custom-js project
    - Change the component & resource names as needed

```ts
CfgrUtils.onCfgrReady(async () => {
  const myResourceName = 'myPdf';
  const myHtml = '<!DOCTYPE html><html><body>Hello World!</body></html>';
  CfgrUtils.convertHtmlToPdf(CmpNames.OfferPdf, myResourceName, myHtml);
});
```

#### Result

When you run this project, a pdf is immediately created and you can retrieve and open the url from the value component we created earlier.

![image.png](<https://docs.combeenation.com/assets/images/image%2817%29-9548f778538c791ef2df4a596c04766d.png>)

### Retrieve the updated pdf url

Although the `CfgrUtils.convertHtmlToPdf` returns a `Promise` it's not guaranteed that the url of the pdf got updated yet.  
Instead, the recommended way is to create a component whose rule returns the url of the pdf and we wait for this component to change.

```ts
CfgrUtils.convertHtmlToPdf(CmpNames.OfferPdf, myResourceName, myHtml);
await CmpUtils.waitCmpValueChanged(CmpNames.OfferPdfUrl);
// ... retrieve the new url
```

:::info
With the introduction of `Custom code` and `CfgnFiles` this was simplified. [File upload & Handling](/docs/configurator-logic/file-upload-and-handling#creating-pdf-files)
:::

### Creating the HTML

#### Understanding the tech

At it's very base the generated PDF is very similar to the result of the "Print" feature in your browser.  
This also means that you can build and preview your basic layout simply by editing a html-file in a text-editor, then open it in the Chrome browser and press `Ctrl+P` (shortcut for Print).

![image.png](<https://docs.combeenation.com/assets/images/image%2818%29-5224c0a98f8329f242ca06acd695712b.png>)

#### Page layout

CSS provides special selectors & rules to format your html specifically for printing.  
Because there exist plenty of articles on the internet we only list some keywords and links here:

- [@page](https://developer.mozilla.org/en-US/docs/Web/CSS/@page): Overall page formatting like size, margin, etc.
- `page-break-*`: Control where a page should (or should not) break and start a new page

##### Html2PdfOptions

It's also possible to provide options like format, margin, etc. when calling `CfgrUtils.convertHtmlToPdf`.  
For details see [Html2PdfOptions](https://cjs.docs.combeenation.com/interfaces/cbn.cfgnclient.html2pdfoptions.html).

#### Header & Footer

To show a header or footer on every page you can pass individual html-strings to the `convertHtmlToPdf` function.  
The body, header and footer don't share their styles and must be defined individually!

```ts
CfgrUtils.convertHtmlToPdf(CmpNames.OfferPdf, 'pdf', bodyHtmlString, {
  displayHeaderFooter: true,
  footerTemplate: footerHtmlString,
  headerTemplate: headerHtmlString
});
```

#### Page numbers and similar

:::info
These only work in the header & footer! They have no effect inside the body.
:::

Specific css classes can be used to inject auto-generated values into the PDF.  
To do so, simply create a html-tag with one of the css classes stated below.

##### Possible values (css classes)

- `date` - formatted print date
- `title` - document title
- `url` - document location
- `pageNumber` - current page number
- `totalPages` - total pages in the document

##### Example usage

```html
Page <span class="pageNumber"></span> of <span class="totalPages"></span>
```

See also [Puppeteer PDFOptions.headerTemplate](https://pptr.dev/api/puppeteer.pdfoptions)

### Troubleshooting

#### Puppeteer

This whole feature is based on the library [Puppeteer](https://pptr.dev/).  
In case of any troubles or unclear results you may find answers by searching their docs or using the keyword `Puppeteer` in your search engine.

#### Images or fonts inside the header or footer aren't working

External links aren't supported. Instead they have to be inserted directly into the html.

- If the image is available as SVG, simply add it like any other tag
- Other images can be converted to a base64 string and be inserted like this:
  - Example: `<img src="data:image/png;base64, iVBORwAAAAUAFCAYAAA......."/>`
  - For larger base64 strings it's recommended to store them inside a [TextAsset](/docs/asset-management/text-asset)

---

## Custom JS

:::warning
CustomJS is fully replaced by [Custom Code](/docs/configurator-ui-ux/custom-code/custom-code-).  
If you're starting a new project please use Custom Code as it provides a far better experience when extending our configurators.
:::

With custom JS, which is short for custom JavaScript, you can **extend your configurators capabilities** in many ways. It allows you to write JavaScript (or TypeScript) which then runs in your configurator.

The following are just a few examples of the countless possibilities which open up with this feature:

- Extend functionalities for existing **components** and **controls** (see [custom JS utils](https://cjs.docs.combeenation.com/))
- Extend functionalities for the **viewer control** (see [3d viewer](https://3dviewer.docs.combeenation.com/))
- Add **new controls** like a date time picker etc.
- **Fetch data** from external services like **real-time** prices calculated on your servers or real-time inventory from your CMS etc.
- Send **live analytics** to external services like [Google Tag Manager](https://tagmanager.google.com/) etc.

### How to get started

#### 1. Prepare your configurator

:::info
It is important that you use the exact same names that we're using in this guide when you create your components etc.
:::

- [Create a new configurator](/docs/fundamentals/creating-a-configurator) if you don't already have one.  
  Preferably use one of our templates which mentions "custom JS" in its name or description.
- See if your configurator has a component `CustomJSCmps`.  
  If yes: You can skip the following steps and go to the [next section](/docs/configurator-ui-ux/customjs/custom-js#2-setup-a-typescript-or-javascript-project).
- Create a value component named `CustomJSCmps` and paste the following into the rule of the component:

  ```hive
  // In this component, you have to tell the server which components you're
  // accessing (reading or writing to) in your custom JS.
  //
  // By default the server only sends the result value of the listed components to
  // the client. If more data like the list of all records etc. is needed, a "+"
  // needs to be prepended to the name.

  // Examples for how to use this. Replace with real cmp names...
  [
    #DefaultView.Name,

    // Retrieve all records of a component
    "+" + #MyRecords.Name
  ]

  // Why do we need this?
  //
  // In published configurators, the server optimizes the used network bandwidth
  // and only sends information about components to the client when actually
  // needed.
  //
  // Since the server has no way of knowing which components are used in custom JS,
  // we need to give him this information manually here so that he can optimize
  // properly.
  ```

  See [What is the CustomJSCmps component](/docs/configurator-ui-ux/customjs/custom-js#what-is-the-customjscmps-component) down below for some more details.

#### 2. Setup a TypeScript or JavaScript project

Theoretically you can upload **any** `.js` file to your configurator.

However, we provide a starter project which comes with our recommended configuration (build tools, config, pre-installed packages etc.) and gives you everything you need to get started quickly.

:::info
All of the following assumes that you have a current version of Node.js & npm (or some equivalent) installed on your computer.
:::

- Open a terminal (e.g. command line in windows) in the folder where you'd like your code to reside
- Run `npm create @combeenation/custom-ts@latest`  
  This will create a starter project using TypeScript. If you prefer to write your code in JavaScript, see [this section](/docs/configurator-ui-ux/customjs/custom-js#how-to-setup-a-javascript-project) further down below.

### How to use it

#### Where to start writing code

The main starting point is usually the callback to [CfgrUtils.onCfgrReady](https://cjs.docs.combeenation.com/classes/cfgrutils.html#oncfgrready) within `src/index.ts` in which you have the guarantee that you can safely access all components & controls.

You can either write all your JavaScript logic within this function or spread it over as many functions/modules/files as you like.

:::info
Always ensure that you only access components & controls **after** the callback to [CfgrUtils.onCfgrReady](https://cjs.docs.combeenation.com/classes/cfgrutils.html#oncfgrready) was called. Otherwise there is no guarantee that all components and controls are fully bootstrapped and you'll run into undefined behavior.
:::

#### How to run & debug during development

There are 2 ways to run & debug your application during development:

- Debugging in **Chrome dev tools**:
  - Run `npm run dev`
  - Open the preview of your configurator draft and append the URI parameter `&localcts=true`
    - Use `&localcjs=true` when working with the JavaScript starter
  - Debug in browser dev tools (`F12`)
- Debugging in **VS Code** (this only works with the TypeScript starter):
  - Open the view "Run and debug" in VSCode & select "Start dev" in dropdown at the top (this is only needed once).
  - Press F5 to start debugging. This will automatically open a new Chrome window and run `npm run dev` in the background.
  - Open the preview of your configurator draft and append the URI parameter `&localcts=true`.
  - Debug directly in VSCode.

:::info
The steps above won't persist your custom JS in the configurator but will load it from the hard drive of your computer.

If you'd like to share the configurator with someone else or want to publish it, you always have to upload your custom JS to the `CustomJS` component as explained in [how to upload custom JS to the configurator](/docs/configurator-ui-ux/customjs/custom-js#how-to-upload-custom-js-to-the-configurator).
:::

#### How to upload custom JS to the configurator

Uploading your custom JS to the configurator is always required when you want to share your configurator with someone else or want to publish it.

- Run `npm run build` in your custom JS project on your computer
- Open the configurator editor of your draft and expand "Custom Code" in the header bar
- Upload or replace the script with the newly built file in your project folder under `dist/cfgr.js`

#### How to access components & controls

The [custom JS utils](https://www.npmjs.com/package/@combeenation/custom-js-utils) package is a set of helper functions which simplify the interaction between custom JS and your configurator.

Besides others, it allows you to read values from components, write new input values to them and interact with the controls in your configurator.

See the [utils API documentation](https://cjs.docs.combeenation.com/) for more details on how to use them.

The custom JS utils come pre-installed with our [TypeScript or JavaScript start projects](/docs/configurator-ui-ux/customjs/custom-js#2-setup-a-typescript-or-javascript-project).

You can also install them manually using `npm install @combeenation/custom-js-utils`.

#### How to interact with the 3d viewer

Combeenation has built it's own 3d viewer, which is used in the [3d viewer control](/docs/configurator-ui-ux/controls/3d-viewer-control).

If the functionality of this 3d viewer control and its SigSlos is not sufficient, it can be extended in custom JS using the API of the 3d viewer package itself.

See [3d viewer control with custom JS](/docs/configurator-ui-ux/controls/3d-viewer-control-with-custom-code) for more details.

### What is the CustomJSCmps component

In this component, you have to tell the server which components you're accessing (reading or writing to) in your custom JS.

You'll get a warning in the configurator preview if you access components which are not listed here. Always ensure that you list all required components as **published configurators will fail silently if components are missing**.

See [this section above](/docs/configurator-ui-ux/customjs/custom-js#1-prepare-your-configurator) for an example of how the content of this component has to look like.

### How to setup a JavaScript project

- Navigate to [https://github.com/Combeenation/custom-js-template](https://github.com/Combeenation/custom-js-template)
- Click "Use this template" and "Create a new repository" to do so:  
  ![image.png](<https://docs.combeenation.com/assets/images/image%2837%29-566a6cad6f2951db7b313b5856bee598.png>)

If you don't have a GitHub account or if you want to use a different or no source code management tool at all, you can also just download the code as a **zip**-file:  
![image.png](<https://docs.combeenation.com/assets/images/image%2840%29-654a430c4fb185434909a2364d9b37e4.png>)

Ensure that you have [prepared your configurator](/docs/configurator-ui-ux/customjs/custom-js#1-prepare-your-configurator) and see [how to use it](/docs/configurator-ui-ux/customjs/custom-js#how-to-use-it) for some info on how to proceed.

---

## Headless configurator

If you want to provide all the configurator UI using your own tooling, frameworks & libraries instead of using our built in UI editor, you can do so by starting a headless configurator project.

You can connect your self-built configurator UI to your configurator logic (component values, inputs, assets etc.) using our publicly available [configurator-client](https://www.npmjs.com/package/@combeenation/configurator-client).

Expect more info to come or [contact support](https://community.combeenation.com/c/questions/6) if you have any questions.

---

## User input sanitization

:::info
Always leave the SigSlo parameter [Sanitize Value](/docs/configurator-ui-ux/user-input-sanitization#sigslo-parameter-sanitize-value) at its default value `true` or use [Hives encodeHtml()](/docs/configurator-ui-ux/user-input-sanitization#mixed-content) when displaying user text input in the configurator!
:::

### SigSlo parameter `Sanitize Value`

To prevent [Cross-Site Scripting (XSS) attacks](https://owasp.org/www-community/attacks/xss/) we've introduced a new paramter `Sanitize Value` for a wide range of `SigSlo` slots like `Button.setValue`, `Label.setValue`, `DataView.setEntries` etc.

This parameter comes with a default value of `true` which ensures that HTML code which is given to the slot is not rendered as such but only shown as raw text.

### Imaginary XSS attack scenario

- Imagine a configurator where the user can enter some text which is then shown in a label.  
  E.g. a custom name for his configuration.
- This configuration name is saved to a component `CfgnName` via the following `SigSlos`:
  - `CfgnNameTxtbox.ValueChanged -> CfgnName.setValue(CfgnNameTxtBox.Value)`
  - `CfgnName.ValueChanged -> CfgnNameLbl.setValue(CfgnName.Value, false)`  
     **Note** that the second parameter `Sanitize Value` is `false` here!
- A user can now enter HTML in the `CfgnNameTxtbox` which is saved in the `CfgnName` component and in turn rendered to the `CfgnNameLbl` via its `setValue` slot. This HTML code can potentially include JavaScript that is executed on rendering.
- An evil user could do the following:
  - Create a new configuration in the published & embedded configurator.
  - Enter some HTML in the `CfgnNameTxtbox` which renders an unsuspiciously looking name but also executes some JavaScript. The JavaScript could add a dialog to the configurator that asks users for credit card information before checkout and sends it to the evil user.
  - This HTML is saved in the `CfgnName` component by the `SigSlos` shown above.
  - The evil user can now send a copy link to this configuration to anyone, promising a fake discount of 80% to anyone who buys a product via this link.
  - Everyone who performs checkout via this copy link is presented with the malicious credit card dialog and unknowingly sends his credit card information to the evil user...

### Mixed content

If you have to write HTML in Hive which includes text from user input AND shall be rendered as HTML you can use Hives  
[encodeHtml](/docs/configurator-logic/hive-types/text-type#encodehtml) method to sanitize the user input.

#### Example

Imagine that the configuration name from the imaginary attack scenario above shall be shown in a "configuration overview" label whose content contains complex HTML to allow some fancy styling via custom CSS:

```hive
/* Component "CfgnOverview" */
"""
<div class="CfgnOverview">
  <div class="CfgnOverview__name">{=CfgnName}</div>
  <div class="CfgnOverview__text">{=CfgnOverviewText}</div>
  <div class="CfgnOverview__price">{=CfgnPrice.toText("€ 0.00")}</div>
</div>
"""
```

```hive
/* SigSlos */
CfgnOverview.ValueChanged -> CfgnOverviewLabel.setValue(CfgnOverview.Value, false)
```

You can't set the `Sanitize Value` parameter to `true` here since that would destroy the beautiful HTML rendering that you actually require here, which leads to this code being open to [XSS attacks](https://owasp.org/www-community/attacks/xss/).

**Solution:** Encode the user input via Hives [encodeHtml](/docs/configurator-logic/hive-types/text-type#encodehtml) method when embedding it in the HTML code:

```hive
/* Component "CfgnOverview" */
"""
<div class="CfgnOverview">
  <div class="CfgnOverview__name">{=CfgnName.encodeHtml()}</div>
  <div class="CfgnOverview__text">{=CfgnOverviewText}</div>
  <div class="CfgnOverview__price">{=CfgnPrice.toText("€ 0.00")}</div>
</div>
"""
```

---

## 3D/AR Viewer

To display a 3D model with an included AR experience, the Combeenation platform offers a free 3D/AR viewer.

### Prerequisites

- 3D model in `glb` or `babylon` format
- Combeenation account ([Register now](https://www.combeenation.com/en/platform/registration/))

### How to create a 3D/AR Viewer

- Once you have a Combeenation company, go to your asset manager (1)
- Create a new asset bundle (2)
- Upload your 3D model by clicking on `+ New` button and selecting `Upload files ...` (3)
  ![3D Viewer Preview](<https://docs.combeenation.com/assets/images/image%2829%29-3612667c79a5e0345ede7269b3da6da5.png>)
- Once the upload is completed and your 3d model is displayed correctly, click the `Create 3D/AR Viewer` button  
  ![image.png](<https://docs.combeenation.com/assets/images/image%2830%29-0c7ac119d048b8565f003a21550b53c6.png>)
- After successful creation, you should be redirected to the embed page. Here, you can view your newly created viewer and proceed with embedding it in your website or shop system.

### Update your 3d model

- If you want to update your 3d model, go to your asset manager (1)
- Select the babylon asset and upload your new updated 3d file
- Once the upload is completed and your 3d model is displayed correctly, click the `Publish` button.
- In order to also update your 3d viewer configurator, make sure both checkboxes are checked for your configurator and hit `Publish & Update assignments`

### Limits

- The sole purpose of those configurators is displaying 3D objects
- Interactions are limited to:
  - Enter AR mode
  - Reset camera
- No further UI elements can be added
- Feel free to contact us, if you want to upgrade this 3D/AR Viewer to a configurator
- You can only create a 3D/AR Viewer for babylon assets, which are in an asset bundle which is published OR which has no connection to another configurator yet.

---

## Configurations

A configuration is created each time a user opens a configurator and is used to save the user's progress. This is done by saving all the user input values, which are used to compute the result values. The configuration is identified by a unique ID. All configurations which were made in any configurator within a company are listed in the configuration table. You can access the table by clicking on configuration" in the top right corner of the configuration metrics on the dashboard.

You can filter all configurations by type, ID, configurator name, and configurator version and also select a time period for your search.

By clicking on one configuration entry in the table you get a bunch of information on the right side including the preset it was based on, the configurator name and version, and the creation time. You can copy and edit the configuration.

Below the basic information, you get to see the "input values" and "result values". Within the input values table, you can see the inputs that were made by the user. The result values show all results that the user interaction triggered.

### Shared configuration

If a configuration is shared on social media a shared configuration is created. Besides some additional metadata needed for the social media platform, this is basically a normal configuration.

### Finish

A Finish is created when a checkout is performed. Besides the input values, the result values are stored in a finish. Those values can be used by the company for further processing (e.g. production). Each finish can also contain a price, which will be set via the shop property price. The price will be used for the calculation of the total revenue in the metrics. overview.

### Configuration metrics

Every configurator has its own configuration metrics. The metrics include data about the number of configurations, finishes, shared configurations, total revenue and the conversion rate. Definitions for those wordings are listed below. These metrics can be viewed for predefined time periods and also for custom time periods. You can also compare two periods of time.

| metrics data type | description                                                                                 |
| :---------------- | :------------------------------------------------------------------------------------------ |
| finishes          | Configurations which have been completed through a checkout (mail, add to cart, …)          |
| shared            | Configurations which have been shared via social sharing (Facebook, Instagram, WhatsApp, …) |
| total revenue     | Sum of shopping cart value of all finished configurations                                   |
| conversion rate   | Ratio of configurations & finishes (finishes / configurations \* 100)                       |

---

## Copying Configurators and Asset Bundles

### Overview

The export/copy functionality enables you to duplicate configurators and asset bundles for use in other companies where you are a member.

### Guide

You can start your export to a different company by visiting the `Export` menu. By clicking on the `Start` button, the copy operation can be configured and started.

![export_1.png](https://docs.combeenation.com/assets/images/export_1-5f2cbcf2b5748dfa1e8bd89768382657.png)

You can copy multiple entities to a different company with the following three steps described below.

#### Select source entities to copy

Please select the source configurators which you would like to export to a different company. All required (assigned) asset bundles will be automatically selected as well. You can copy a configurator without assigned asset bundles, but keep in mind that the configurator will very likely contain errors if any assigned asset bundles are missing in the target company.

You can of course also just copy an asset bundle without selecting any configurators.  
By clicking `Reset selections` you can revert your settings and start from scratch.

![export_2.png](https://docs.combeenation.com/assets/images/export_2-468759cdfa929645a7ec24740879af52.png)

#### Specify the source versions (advanced)

After clicking on `Confirm selection` you can choose which version of the selected configurators and asset bundles should be copied. By default, the published version of each configurator will be selected. For asset bundles, the pre-selected versions are those that are assigned to a configurator.

In most cases the default selection should be sufficient. To proceed, click on `Prepare for copy`.

![export_3.png](https://docs.combeenation.com/assets/images/export_3-968839f79f765d63f34381ac2299c833.png)

By clicking on `Edit versions`, you can select additional versions of an asset bundle which should also be copied.

:::warning
Deselecting a required asset bundle version could potentially break your new configurator.  
Also selecting other bundles instead will not re-assign them to the configurator.
Warnings will inform you about potential problems of your selection.
:::

#### Define your target company

After the target company is selected, you will get an overview over which entities are pending to be copied. You can optionally update the target names of your configurators or asset bundles. The auto-publish option enables you to additionally publish your configurators and asset bundles.

If a name is already taken in the target company, you can decide if you want to add it to the existing one or create a new one.

![export_4.png](https://docs.combeenation.com/assets/images/export_4-753e1832bd962dec0c09d3f24cf2a675.png)

With the `Start copy` button, the copy operation is started in the background.  
You don't need to stay on this page to wait for it to complete.  
You will be notified as soon as the copy process is completed, in the notification area in the top-right corner of the page.

![export_5.png](https://docs.combeenation.com/assets/images/export_5-100ff57a58dc5d148e3cedf25e3a5150.png)

### Important Considerations

#### Copying a configurator without assigned asset bundles

If you copy a configurator and unselect the assigned asset bundles, the configurator will probably not work as intended.  
This is because any assets that it uses will be missing.  
You will have to either manually fix any errors resulting from these missing assets, or upload new assets that you wish to use instead. You can also copy the original asset bundle belatedly.

#### Asset bundle aliases

If you decide to change the name of an assigned asset bundle during the copy process e.g. from `BikeAssets` to `MyBikeAssets`, the platform will use the old name ( `BikeAssets`) as [alias name](/docs/asset-management/assign-asset-bundles-to-configurators#alias-name) to avoid potential errors in your configurator.

Such errors could occur if the configurator uses the asset bundle name to refer to assets. For instance, the code `BikeAssets.MyThumbnail` would no longer work if the new asset bundle is called `MyBikeAssets`. By using `BikeAssets` as alias name, this problem can be avoided.  
Alternatively, you could update all uses of the old asset bundle name, e.g. change `BikeAssets.MyThumbnail` to `MyBikeAssets.MyThumbnail`.

:::info
If you changed the name of an asset bundle, consider updating your assignments (aliases) after the copy process.  
E.g. change the alias name to `MyBikeAssets`, so that it matches the name of your new asset bundle.  
Use of the old name may be confusing for other users working on the configurator.  
Note that if you do this, you must manually update all uses of the old asset bundle name as described above.
:::

![export_6.png](https://docs.combeenation.com/assets/images/export_6-21a9cbd4d32c8d5097d783c0bbe69c5a.png)

---

## Create a basic 3D configurator

The goal is to create a basic 3D Mokapot configurator. The user should be able to

- change the color of the upper and lower part
- open and close the lid
- set a individual motive for the bottom part
- view the Mokapot in AR mode

![2024-04-29_10h21_41](https://docs.combeenation.com/assets/images/2024-04-29_10h21_41-0fe7745301a23dd216787e4076dba8d6.png)

Link to the finished [configurator](https://portal.combeenation.com/Cfgr/COMBEENATIONACADEMY/CREATEMOKA).

### Needed content

For the implemenatation you need the following files

:::note[Downloads]
[moka-pot.glb](data/create-a-basic-3d-configurator/moka-pot.glb)  
[Graphics.zip](data/create-a-basic-3d-configurator//Graphics.zip)
:::

### Steps to reproduce

To achieve the functionalities mentioned, the following steps must be implemented.

<details>
<summary>First steps</summary>

1.  Create a new configurator based on the `Mokapot step by step example` template.
    - `Name`: Use a meaningful name of your choice
    - `ID` and `Asset bundles` are prefilled correctly

:::warning
If the assigned bundles are changed/renamed, it cannot be guaranteed that the following example can be implemented without any problems.
:::

![create-cfgr](https://docs.combeenation.com/assets/images/create-cfgr-eb08ccd70a5b090a63f27e83407621fd.jpg)

2. Use the asset manager to upload the `mokapot.glb` file.

   **Asset bundle**: Assets3DMoka  
   **Folder**: Models3d

   ![2024-06-04_15h23_22](https://docs.combeenation.com/assets/images/2024-06-04_15h23_22-7f84d75c345644367143cbd2d04ba365.png)  
   See the [documentation](/docs/configurator-ui-ux/controls/3d-viewer-control#how-to-show-models) for detailed information.

:::info
The bundle already contains some textures (see folder Textures3d) which will automatically be linked with the respective material when uploading your model. In general, textures need to be uploaded separately as GLB files encode textures into base64 strings, which might lead to warnings in your Materials3d folder. If such warnings occur, just select the detected asset and set the Image in Channels to `-` and save the changes. It's best practice to save your textures separately when exporting your models to GLB (e.g. in Blender or Autodesk Maya). That way you won't run into the described issues with textures being encoded to base64.

![2024-06-04_15h23_22](https://docs.combeenation.com/assets/images/asset-warning-168913d5df9234b945f150bd56c5fe78.png)
:::

3.  Add the following line of code to the `ViewerParams` value component.

    ```hive
    Viewer3d.modelParameter(Models3d.mokapot, "visible", true)
    ```

    To gain more information about this component, have a look at our [documentation](/docs/configurator-ui-ux/controls/3d-viewer-control#slots).

4.  To make the 3D model visible in the viewer, connect the viewer control with the viewer parameters component. Add the following SigSlo.

    ![2024-06-04_15h33_30](https://docs.combeenation.com/assets/images/2024-06-04_15h33_30-353c81ae9c4bae41ce491b84efc64843.png)

</details>

<details>
<summary>Change colour individually</summary>

1.  Go to the Asset Editor and create data source `Colours` based on the file asset `Moka_ProductData` (see [Create data source](/docs/category/asset-management))

    ![2024-06-04_15h40_36](https://docs.combeenation.com/assets/images/2024-06-04_15h40_36-6bcf48980df14a07eab3522a12bf52c0.png)

2.  Back in the configurator backend, create a table component named `Colours_Tbl`.
3.  Load the colours into the component (see [Queries](/docs/configurator-logic/hive-queries)). To do this, add the following query to your table component:

    ```sql
    from ProductData.Colours select all
    ```

4.  Connect the table component and dataview for the top colour

    <details>
    <summary>Solution</summary>
    1.  Set the entries of the dataview

        -   Open the SigSlo editor.
        -   As Signal, select your  `Colours_Tbl`  component.
        -   As Slot, select your dataview  `TopColours_dv`  with the option  `Set entries`.
        -   Set the source type of the entries-parameter to  `Control or Component`  and select your  `Colours_Tbl`  component, for property select  `Value`.

            ![2024-06-04_15h48_36](https://docs.combeenation.com/assets/images/2024-06-04_15h48_36-0350ed8fe122370ec064449551cee513.png)

        -   Edit the mapping-parameter so that  `Text`  and  `Value`  is mapped to  `ID`  and  `Image background`  to  `HEX_CODE`.

            ![2024-06-04_15h49_01](https://docs.combeenation.com/assets/images/2024-06-04_15h49_01-8176dad17434a7018887b527b86283cf.png)

    2.  Write selection changes from the dataview back to the value component
        - Create a value component with the name `TopColour`.
        - Add the following code to the component

          ```hive
          Colours_Tbl.Get(Input or 0) or Colours_Tbl.GetFirst()
          ```

        - Set the input type of the component to `Number`.

          ![2024-06-05_14h05_50](https://docs.combeenation.com/assets/images/2024-06-05_14h05_50-2d8a4ceea494c025bb02b63747801181.png)

        - Open the SigSlo Editor
        - As Signal use the `TopColours_dv` with the `Value Changed` signal
        - The Slot is your created `TopColour` value component with the option `Set value`
        - Set the source type of the entries-parameter to `Control or Component` and select your control `TopColours_dv`, for property select `Value`.

          ![2024-06-04_15h54_25](https://docs.combeenation.com/assets/images/2024-06-04_15h54_25-47a8a14007aa816f86bdb3fa632c6663.png)

    3.  Write selection changes from the value component back to the dataview.
        - Go to the `TopColours_dv` dataview and enable Hive for the dataviews value property, by clicking on the code icon next to the input field
        - Open the Editor by clicking on the Value label
          ![2024-06-04_15h56_37](https://docs.combeenation.com/assets/images/2024-06-04_15h56_37-7ecb7e3773d7b6345954ae22e86986b9.png)
        - Get the data from the value component `TopColour` by writing a simple script like
          ```hive
          TopColour
          ```

    </details>

5.  Connect the table component and dataview for the lower colour

    To do this repeat step 4. When creating value or table components use the word `Lower` instead of `Top`.

    Following components and controls are needed: `Colours_Tbl`, `LowerColour`, `LowerColours_dv`

6.  Make colour changes visible in 3D

    Adapt the viewer parameters in the `ViewerParams` component. Add the following lines of code

    ```hive
    Viewer3d.materialParameter(Materials3d.matPaint_top, "color", TopColour.HEX_CODE),
    Viewer3d.materialParameter(Materials3d.matPaint_bot, "color", LowerColour.HEX_CODE)
    ```

</details>

<details>
<summary>Open/Close lid</summary>

1.  Create a new value component named `LidOpened`, to store if the lid should be opened or closed.
2.  Set the input type of the component to `Logic` and add the following script

    ```hive
    if Input is Empty then false else Input end
    ```

3.  To store the user input, connect the checkbox with the value component. To do this, create a SigSlo (the button with the node-like icon in the top right corner of the Controls panel) with the shown settings below.

    ![2024-06-05_08h08_40](https://docs.combeenation.com/assets/images/2024-06-05_08h08_40-2efe9b35df4c878bde62712bebe649e7.png)

4.  You also need a connection in the other direction. If the value in `LidOpened` changes, the checkbox has to be updated.  
    For that, enable Hive for the checkbox value property by clicking on the code icon next to the input field.

    ![2024-06-05_08h10_08](https://docs.combeenation.com/assets/images/2024-06-05_08h10_08-2f8bb1c61b937706ef164731584a0bf2.png)

5.  Set the position of the opened/closed lid. To do this, you have to adapt the `ViewerParams` component. Add the following line of code to make the animation visible in 3D.
    `hive Viewer3d.nodeParameter("Toplid", "rotation", if LidOpened then "(-45,0,0)" else "(0,0,0)" end) `

</details>

<details>
<summary>Display an individual motive on the bottom part</summary>

1.  Upload the images `graphic1.svg`, `graphic2.svg`, `graphic3.svg` and `graphic4.svg` as **text assets** in the asset manager. Make sure that the uploaded SVG files do not contain any `DOCTYPE` or `xml` tags as they must only include the pure `svg`.

    **Asset bundle**: ProductDataMoka  
    **Folder**: Visualization  
    **Asset type**: Text

    ![2024-06-05_08h18_52](https://docs.combeenation.com/assets/images/2024-06-05_08h18_52-686770d8bb0b75463277cbcfc2af4306.png)

    The corresponding data is already available in the configurator (components `Graphic_Tbl` and `LowerGraphic`).

2.  Create a new Graphic component named `TextureView`.

    ![2024-06-05_08h24_05](https://docs.combeenation.com/assets/images/2024-06-05_08h24_05-edc2ee843c1bf60fe0ef873e4d24785a.png)
    - Set the size to 1024 x 1024px. Please click on the texts (Width, Height) to bring up the component editor rather than entering the values directly into the input field.
    - Add a new Visual of type `Single Visual` → `SVG` and name it `Graphic`.
    - To show the chosen image, set the `Texture.Source` to

      ```hive
      """<svg xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg"  version="1.1" viewBox="5 -25 100 512">
          {=LowerGraphic.VIS_IMG.getText()}
      </svg>"""
      ```

:::info
Nesting the motive within a parent svg element is necessary in this example as we want the motives to have a certain size, which is given by the outer svg's viewBox attribute.
:::

3.  To display the motive on the mokapot use a so called [paintable](/docs/configurator-ui-ux/controls/3d-viewer-control#how-to-draw-dynamic-content-on-the-3d-model).  
    Add the following line of code to the `ViewerParams` component.

    ```hive
    Viewer3d.materialParameter(Materials3d.matLogo_2, "paintable", { src: TextureView.Value.ToText(), uScale: 1, vScale: -1 }.ToText())
    ```

:::info
The paintable will most likely just show a black surface instead of the expected motive. If so, head over to the Asset Editor, go to the Materials3d folder and select the **matLogo_2** material. Head over to the Transparency section and set the Transparency mode property to **Alpha blend and test**.
:::

</details>

<details>
<summary>AR mode</summary>

To make the AR button work, you have to create a SigSlo with the `Start AR` slot.

![2024-06-05_08h28_11](https://docs.combeenation.com/assets/images/2024-06-05_08h28_11-7d4764fbd243ddeab47561592d75a9e7.png)

Adjust the parameters below. These parameters are essentially texts displayed in the User Interface. By default, those values are static and filled with texts in English. If you want this texts to be dependent on the currently selected language, you might want to link to a component containing translations. In our example that's the **GeneralUI** component which holds dedicated columns for those AR-related texts.

| Parameter        | Source    | Property      |
| ---------------- | --------- | ------------- |
| QR sub title     | GeneralUI | qrSubtitle    |
| QR description   | GeneralUI | qrDescription |
| Preparation text | GeneralUI | arPrepText    |

For detailed information about the AR mode have a look at the [documenation](/docs/configurator-ui-ux/controls/3d-viewer-control#start-ar).

</details>

<details>
<summary>Auto focus camera</summary>

The auto-focus camera is used to find a default position, where all nodes are visible in the scene. To make the `CenterCamera_btn` work you have to create a SigSlo with the following settings.

![2024-06-05_08h30_58](https://docs.combeenation.com/assets/images/2024-06-05_08h30_58-c7d67c00d977a743881e87a25b6da2b6.png)

For a good camera perspective, adjust the parameters as follows

- `Alpha` to `180`,
- `Beta` to `90` and
- `Radius factor` to `1.4`.

See [auto focus camera](/docs/configurator-ui-ux/controls/3d-viewer-control#auto-focus-camera) for detailed information.

</details>

---

## Creating a configurator

As it is possible on the [welcome](welcome) page, you can also create a configurator by simply clicking on the `+ New configurator` button in your configurator section. You will get a pop-up in which you can select a template and choose a name for your configurator or optional required asset bundles.

### Drafts

When you add a new configurator, a draft is created automatically.  
**A draft is an unpublished version of a configurator.** In a draft you can edit your data and the configurator design. You can preview your changes in your draft and can decide when your draft is ready to be published.  
As soon as your draft is published, you have a live configurator, ready to be used and embedded on your website.  
Deleting a draft will not be available until one published version exists.

### Published configurator (link)

If there is a **published** version of the configurator, it can be accessed by everyone through a link. The link can be found on the dashboard or on the embed page. The structure of the link looks something like:  
`portal.combeenation.com/Cfgr/{CompanyName}/{ConfiguratorName}`

If the configurator isn't used anymore, it can be **unpublished** through the button in the drafts page. This action will delete the published version of the configurator, but it will not delete anything from the history.

### Configurator history

Each draft that has ever been published is archived in the history. If something doesn't look good in your published configurator, you can always access the previous version in the history (preview the configurator as well as entering the editor in readonly mode).

In order to find the desired history version, you can enter a description text each time you publish the configurator.

### Draft management

Besides the initial draft which gets created upon configurator setup, you can of course create a new draft by clicking the `+ New draft` button in the drafts page. (Tip: This also gives you the option to create a new configurator based on an existing draft).

**By default, a new draft is based on the published configurator version**.  
You can also create a draft based on another draft or a stage (if available).

There is a limit of 10 drafts that can exist at the same time per configurator. This means there can be 10 different unpublished versions of a configurator. To avoid chaos we recommend the following naming conventions for drafts:

draft naming

usage

`dev {your name}`

In a "dev" draft you work productively on a configurator. There should never be more than one dev draft.

`del {your name}`

This draft can be deleted and is only used for looking up things in the configurator or for test purposes.

`hotfix {bug}`

A "hotfix" draft is for small changes and should be published quickly. The draft should always be named with a short description explaining its purpose.

`review {your name}`

This draft is used when someone reviews the development of the configurator.

Instead of your name, you can also describe the changes or adaptions that you will implement in this draft. e.g.: "dev price calculation"

You have several interaction possibilities with drafts (see three dot menu):

- Edit draft ... this will enter the configurator editor and allows you to make changes
- View draft in editor … this also opens the configurator editor, but you cannot make any changes here, only view the internals of the configurator.
- Preview draft ... will preview the draft configurator in a new tab, so you can test the changes you made while you are working. Do **not embed** a preview on your website, only embed the published (or staged) version of your configurator!
- Duplicate draft ... creates a new draft (or configurator) based on the selected draft
- Delete draft … removes the draft. Deleted drafts can be restored within a period of time (see the [next section](/docs/fundamentals/creating-a-configurator#restore-deleted-drafts))

:::warning
Previews don't support the **Share** and **Checkout** features.  
These are only available in published or staged configurators.
:::

#### Restore Deleted Drafts

If you have accidentally deleted a configurator draft you can recover it **within 30 days** of it being deleted.  
Expand the "**Deleted drafts**" section at the bottom of the drafts page and find the draft you wish to restore.  
One click on the "**Restore**" button and you have your draft back.

Keep in mind that you cannot exceed the maximum number of drafts this way – so if you already have 10 drafts, you first have to publish or delete one of them before you can create or restore more.

### Configurator Stages

A stage is a version of a configurator that can be embedded in a website to test all features of a configurator before publishing it. Stages are a powerful tool that unlock more sophisticated development workflows and are typically embedded in a dedicated QA environment, not on your actual production website or shop.

A stage can be created in one of two ways:

1.  by opening a draft in the configurator editor and pressing the "Stage" button
2.  by staging an already existing history version of the configurator (mostly as a starting point for further development)

:::info
You can only create a limited number of stages, which depends on your subscription.  
Contact us if you are interested in (more) stages!
:::

A staged version of a configurator works in almost the same way as a published configurator.  
Unlike a preview, a stage supports all features of a configurator to allow you to make end-to-end tests of a configurator before publishing it.  
Keep in mind though that a stage does not replace a published configurator! While it supports all configurator features, there are limits on how many configurations can be created with a stage in a certain period of time.

**A configurator stage cannot be edited directly.**  
Like with the published version of your configurator, you have to create a draft based on the stage in order to make changes.  
Once the draft is ready, you can stage it again and thus update the staged version.  
Unlike a preview, the embed URL of the stage won't change when you stage a new draft.

You can alter the behavior of a configurator when it [is staged, published or in preview](/docs/configurator-logic/configurator-and-presets-variable#properties), which may be necessary e.g. in [checkout](/docs/integrations-and-api/checkout#checkout-and-stages) to account for differences between a production and QA environment.

#### Development workflow with stages

Here is an example of a typical development workflow that makes use of stages:

1.  create a configurator draft as usual and make the desired changes to your configurator
2.  stage the draft. Enter a name for the stage if you don't have one already.
3.  embed the stage in your QA website to test it
4.  create a new draft based on the stage to continue development
5.  once the new draft is ready, stage it again.
    - Repeat these two steps until you have made all necessary changes.
    - You can keep testing the embedded configurator throughout the entire process.
6.  when you are done testing it, publish the stage
    - Until you publish a stage, the live version of your configurator remains fully unaffected by your work on drafts and stages

### Assign asset bundle and configurators

After you have entered the configurator editor you can of course start editing the configurator logic, but at some point you probably want to use assets inside the configurator.

In this case, an asset bundle must be assigned to a configurator. This can be done clicking on the asset drawer in the top center, which lets you select your desired asset bundle. All versions of the asset bundle should now be listed, you probably want to assign the newest version at the top to your configurator. This will be done by clicking on the `+` icon on the left of the desired version.

### Component and groups

In order to build your configurator logic, you can create components and cluster them together in groups.  
The content of those components is Hive code, for more information see [Hive introduction](/docs/configurator-logic/hive-introduction).

### Embed finished configurator

After you have successfully created your first configurator, it is ready to publish, simple hit `Publish` button in the top center in the configurator editor. This will create a new version (as already discussed above) and redirect you to the drafts page.  
You can now embed your configurator wherever you want, for more info see [embedding](/docs/integrations-and-api/embedding-and-whitelist).

---

## Custom Fields

Custom fields allow you to store additional data in different areas of your company:

- [User](#user-fields) … per user (e.g. discount, language)
- [Company/Distributor](#companydistributor-fields) … per company or distributor (e.g. region)
- [Quote](#quote-fields) … per quote (e.g. terms of payment)
- [Quote Item](#quote-item-fields) … per line item (e.g. delivery time)

:::info[Pro Feature]
The availability of custom fields depends on your subscription!

Contact us if you are interested in enabling (more) custom fields in your CompanyOn the Combeenation platform, a company means exactly what it describes: a company. For the most part, these are customers who have ordered a configurator from us. However, there are also internal companies that we use for best practice examples, for testing or for internal configurators..
:::

### Creating custom fields

Each custom field consists of three properties:

- **Name** must be a valid Hive identifier. Names are case-insensitive, so `discount` and `Discount` are considered as the same
- **Type** is one of the Hive types `Number`, `Text`, `Logic`, `List<Number>` or `List<Text>`
- **Fallback Value** is the value of the field that will be used if no explicit value for this field is set.

You can create and manage custom fields on your company’s **Settings** page.

- Define fields and fallback values.
- Assign values at the **Company** or **Distributor** level.
- For **User Custom Fields**, you can also assign values per individual user.

:::info

Published Configurators are not affectedThe published link is the published version of the configurator and is used for integration with the customer. Checkouts and share functions can only be tested here. Everyone who knows this link has access to the configurator.

When you create, modify, delete or change the fallback value of a custom field, your staged or published configurators won't be affected immediately – they must be published again to use the updated fields.

This is a safeguard to protect these configurators and allows you to adapt them as necessary when you have to alter fields.

Note that changes to field (company, distributor or user) _values_ do immediately affect staged and published configurators!
:::

### Custom Field Management

##### Company

On the **Company Settings** page, you can:

- Create, edit, or delete custom fields.
- Assign company-specific values.
- **Keep in mind**: deleting a field removes its values in all related entities.

![](<https://docs.combeenation.com/assets/images/image%2891%29-66668d8c32366d11b50472874804691a.png>)

##### Distributor

On the **Distributor Settings** page, you can only set distributor-specific values. If no value is set, the **Fallback Value** from the company is used.

![](<https://docs.combeenation.com/assets/images/image%2892%29-31026457ffceffcc99b0cd181e8ec678.png>)

### Types of custom fields

You can create different types of fields to support various use cases in configurators.

#### User Fields

Custom field values for the signed-in user are accessible in Hive, in the `user.fields` variable.

**Examples**

- Apply different discounts to sales users.
- Restrict feature availability based on user fields.
- Add a `UserId` field to fetch external user data from workflows.

**Value Priority**

1.  User-specific value (set on the Users page)
2.  Company/Distributor value
3.  Fallback value

##### Hive Example

```hive title="Hive"
 // assuming you created a custom field 'Discount'
 BasePrice * (1 - user.fields.Discount)
```

**Note** that you do not have to check a field value for `Empty`, because even if no value for this field is set on the current user (or the user isn’t signed in), the field will still have a value thanks to the Fallback Value.

See the [Hive User](/docs/configurator-logic/user-variable) docs for more details on the `user` variable.

#### Company/Distributor Fields

Company and distributor custom fields are available via `configurator.owner.fields`in Hive.

**Examples**

- Define regions per company or distributor.
- Limit configurator features by company.
- Restrict products for certain distributors

**Value Priority**

1.  Company/Distributor value
2.  Fallback value

##### Hive Example

```hive title="Hive"
// assuming you created a custom field 'Region'
configurator.owner.fields.Region
```

:::note
You do not have to check a field value for `Empty`, because even if no value for this field is set, the field will still have a value thanks to the Fallback Value.

See the [Configurator Variable](/docs/configurator-logic/configurator-and-presets-variable) docs for more details on the `configurator` variable.
:::

#### Quote Fields

Quote custom fields let you enrich your quote infrastructure.

**Examples**

- Add terms of payment to your quotes
- Mark important quotes with a custom severity level

![](<https://docs.combeenation.com/assets/images/image%2895%29-c4792950075f7e728d1507b8588e07c5.png>)

**Value Priority**

1.  Company/Distributor value
2.  Fallback value

The fallback value of a Quote custom field is used, if no value is provided for the currently selected company or distributor. If you define a Company/Distributor value, then this value will be used when no value is provided during
CheckoutThis completes a configuration and exports the data to a third party. The choice of a checkout depends entirely on the needs of the customer or their target group..

##### Hive Example

:::info
Coming soon after this feature is available!
:::

#### Quote Item Fields

Quote item custom fields apply to each line item of a quote.

**Examples**

- Add an image field to each line item.
- Define delivery times per product.

![](<https://docs.combeenation.com/assets/images/image%2896%29-671a5715bd38d87a4e22822570d30096.png>)

**Value Priority**

1.  Company/Distributor value
2.  Fallback value

The fallback value of a Quote Item field is used, if no value is provided for the currently selected company or distributor. If you define a Company/Distributor value, then this value will be used when no value is provided during
CheckoutThis completes a configuration and exports the data to a third party. The choice of a checkout depends entirely on the needs of the customer or their target group..

##### Hive Example

:::info
Coming soon after this feature is available!
:::

---

## Keyboard shortcuts

---

| Hotkey             | Action                                                                    | Detail                                                                               |
| ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `Ctrl + K`         | Quick launcher (backend) Available actions depend on the current view | Fast way to: - go to pages - find and select components - switch company |
| `Ctrl + O`         | Focus component filter box                                                | Only in editor view                                                                  |
| `Ctrl + Shift + L` | Send current session log to the monitoring tool (backend & configurator)  | To reproduce or analyze possible bugs                                                |

### Code editor

The editor is based on the "Monaco editor" which is also used by VS Code.

#### How to find shortcuts

- Press F1 inside the editor and search for your command. If a shortcut is available it will be shown on the right.
- Most of the shortcuts match with the ones from VS Code. If you have VS Code installed you can find them under "File > Preferences > Keyboard shortcuts"

#### Custom Hive hotkeys

| Hotkey     | Action             | Detail                                            |
| ---------- | ------------------ | ------------------------------------------------- |
| `Ctrl + B` | Autoformat records | Formats a record component in a table-like manner |

---

## User Permissions

Every user can be assigned to multiple companies with its own individual role. Each role always includes the permissions of the preceding one.

### Basic explanation

| role      | info                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| sales     | View and analyze configuration insights.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| developer | Can create/edit/delete/publish configurators and asset bundles. In addition, a developer is allowed to manage workflows and edit CompanyOn the Combeenation platform, a company means exactly what it describes: a company. For the most part, these are customers who have ordered a configurator from us. However, there are also internal companies that we use for best practice examples, for testing or for internal configurators. settings. |
| admin     | Is allowed to edit the staff (invite, manage permissions). This role is only given upon special agreement with Combeenation.                                                                                                                                                                                                                                                                                                                                                                                                                                         |

### Detailed Overview

| Permission                              | sales | developer | admin |
| --------------------------------------- | ----- | --------- | ----- |
| analyze configurations/insights/metrics | ✓     | ✓         | ✓     |
| view, edit and publish configurators    |       | ✓         | ✓     |
| view, edit and publish asset bundles    |       | ✓         | ✓     |
| manage company settings                 |       | ✓         | ✓     |
| run workflows                           |       | ✓         | ✓     |
| manage workflows                        |       | ✓         | ✓     |
| manage staff                            |       |           | ✓     |

### Manage staff

Only admins can manage staff. To manage the staff, go to the users page found in the left sidebar. In this view you can do the following:

- Create invite links to invite new users
- Edit role of existing users
- Remove users from the company

---

## Welcome

After your first login or after simply **clicking on the Combeenation logo** in the upper left corner, the welcome page is shown immediately.  
This is your entry to create awesome configurators described below.

![welcome_cards.png](https://docs.combeenation.com/assets/images/welcome_cards-352a122f3618c5761b001f4349526431.png)

#### Creating a new configurator

It is possible to select a template or create a configurator from scratch.

![welcome.png](https://docs.combeenation.com/assets/images/welcome-be35bec018d0ef80743d92064a0718c5.png)

After selecting a template, you can choose your custom configurator name and ID.  
If the template uses asset bundles, then choose names for all required asset bundles.

:::info
The ID is used to create the URL of your configurator.
:::

![create_configurator.png](https://docs.combeenation.com/assets/images/create_configurator-3d4fbc8f78090d1dd7591493a1f7c4ee.png)

---

## Analytics

### Google Tag Manager

Whilst there is no direct integration of a configurator in the Google Tag Manager (GTM), we provide a ready-to-use interface to forward certain configurator events into the “[data layer](https://developers.google.com/tag-platform/tag-manager/datalayer)”.  
The events in the “data layer” can be interpreted by the GTM in the process.

:::info[Google Tag Manager (GTM) setup/configuration]
You are responsible for setting up GTM (embedding the script on the page) and configuring your GTM dashboard (e.g. widgets).
:::

There are 2 ways of triggering such a configurator event:

- via [fireAnalyticsEvent](/docs/configurator-ui-ux/controls/configurator-control#fire-analytics-event) slot
- via [Cbn.utils.IFrameHelper.fireAnalyticsEvent](https://custom-code.docs.combeenation.com/classes/Cbn-2.utils.IFrameHelper.html#fireAnalyticsEvent) Custom Code function

Both variant push the event into the data layer in a standardized format:

```json
// 1: event key only
{
  "event": "myEventKey"
}

// 2: event data as string
{
  "event": "myEventKey",
  "eventData": "Some event data as string"
}

// 3: event data as object
{
  "event": "myEventKey",
  "eventData": {
    price: 10,
    amount: 3
  }
}
```

---

## Flex checkout

Basically the flex checkout lets you decide which data (e.g. amount, description, generated images, ...) will be passed to the parent page when a user performs a Checkout.

As already described in [Embedding and configurations](/docs/integrations-and-api/embedding-and-whitelist), the configurator will communicate with the parent page via cross-document messaging during the checkout. Technically speaking this all happens within your browser on the client side, so it is extremly fast.

### Combeenation platform

On the Combeenation platform you just have to define the data within the property `Parameter` in the flex shop. Combeenation won't enforce a specific file format (can be JSON, CSV, XML, ...), but we strongly recommend JSON. If you aren't required to use a specific JSON format, we strongly recommend the following structure:

```json
{
  "products": [
    {
      // (mandatory) at least one product must be defined
      "main": {
        // (mandatory)
        "productId": "123456", // (mandatory) SKU
        "quantity": 1,
        "price": 99.99, // gross price of the configured product WITHOUT accessories
        "imageUrl": "Assetbundle1.MyImage.url", // url to the image which will be used in the cart
        "title": "My coffee mug", // new title of the product
        "productText": "My own description", // new description of your product
        "customFields": [
          // (optional)
          {
            "id": "model", // (mandatory) unique identifier
            "label": "Model type", // label which the user will also see in the cart (if it is visible)
            "value": "espresso", // value of the custom field
            "position": 1, // position in the cart
            "isVisible": true // if it should be visible in the cart
          }
        ]
      },
      "accessories": [
        // (optional) additional predefined products which will be added to the cart (no custom price/image/title)
        {
          "productId": "987654",
          "quantity": 1
        },
        {
          "productId": "456789",
          "quantity": 1
        }
      ]
    }
  ]
}
```

### Your website/shop/system/...

On the parent page (on which the configurator is embedded) you just have to implement the JavaScript function `window.Combeenation.onCheckout`. This function will be called during the checkout and has one parameter which contains:

- configuration id
- configuration auth token
- `CheckoutParameters` are the values you have defined previously
- `CheckoutParametersHash` SHA256 hash of `CheckoutParameters`
- queryParameters which are set to the iframe url

With this data on your hand you can implement your further checkout logic on your own. Example implementation of the checkout function:

```html
<script type="application/javascript">
  window.Combeenation = window.Combeenation || {};
  window.Combeenation.onCheckout = function (data) {
    /*
    structure of the parameter 'data':
    data.id // id of the configuration (Provided by Combeenation)
    data.authentication // authentication token, which is needed if a customer wants to edit the configuration. (Provided by Combeenation)
    data.checkoutParameters // value of the checkout component property 'Parameter' (Provided by you)
    data.checkoutParametersHash // SHA256 hash of `CheckoutParameters` (Provided by Combeenation)
    data.queryParameters // all query parameters which are added to the iframe URL (Provided by the person who inserts the iframe in the page)
    */
    // e.g. make AJAX calls, redirects, ...
  };
</script>
```

### Data security (integrity)

:::warning
If there is sensitive information in the flex checkout parameter (e.g. price), we strongly recommend that you verify that the information hasn't been tampered with by a malicious user (e.g. price set to 0). Combeenation provides a [HMAC](https://en.wikipedia.org/wiki/HMAC) hash over the data in order to ensure unforgeability.
:::

The checkout response property `checkoutParametersHash` contains a SHA256 hash over the `checkoutParameters`. The hash will be salted with a secret which can be defined in the `HashSecret` property of the flex shop. This secret should be kept private and only be stored on your server.

With the `checkoutParameters` and the secret you can calculate a hash and test whether it matches the given `checkoutParametersHash`. If the hash differs the `checkoutParameters` have been altered.

Example for checking the hash in PHP:

```php
$secret = "myPrivateSecretWhichIsOnlyStoredOnTheServer";
$data = $_POST["checkoutParameters"];
$givenHash = $_POST["checkoutParametersHash"];

// (optional) normalize line endings; there should be no \r in the checkoutParameters
$data = str_replace("\r\n", "\n", $data);

// convert base64 hash
$base64Hash = base64_encode(hash_hmac('sha256', $data, $secret, true));

// check hash
if($base64Hash == $givenHash) {
  echo "Add to cart successful";
} else {
  echo "Hash invalid!";
}
```

---

## FTP checkout

This Checkout shop can upload one or multiple files to a given FTP server. The uploading files are defined via a Hive record, with the following structure:

```hive
[{
  FilePath : "",
  ContentEncoding : Encoding.Utf8,
  Content : ""
}]
```

#### Limits

- Maximum size of all attachments combined is 100 MB.
- Currently only text files are allowed as files (e.g. XML, CSV, JSON, ...).

---

## Mail checkout

This checkout will send one or multiple mails on Checkout. The mails are defined via a Hive record, with the following structure:

```hive
[{
  From : { Name : "John Doe", Mail : "john.doe@example.com" },
  To  : [{ Name : "Jane Doe", Mail : "jane.doe@example.com" }],
  CC  : [{ Name : "", Mail : "" }],
  BCC : [{ Name : "", Mail : "" }],
  Subject : "",
  Message : "",
  Attachments : [{ FileName : "", ContentEncoding : Encoding.Utf8, Content : "" }]
}]
```

:::warning
You can set a from address, but per default this will only be used as reply address and the real from address will be `mail.combeenation.com`.

In order to use your company's domain as sending domain, checkout the options in [Mail settings](/docs/integrations-and-api/mail-settings).
:::

#### Limits

- Maximum size of all attachments combined is 5 MB
- Currently only text files are allowed as attachments (e.g. XML, CSV, JSON, ...).

---

## REST checkout

This Checkout will perform up to five parallel REST requests to given endpoints. The endpoint should return successful HTTP code (200-299). Requests are defined via a Hive record, with the following structure:

```hive
[{
  Method : "",
  Url : "",
  Content : "",
  ContentEncoding : Encoding.Utf8,
  AuthIntegration : "", // deprecated
  Headers : [
    { Key : "Content-Type", Value : "" },
      RestShop.BasicAuth("username", "password") // (optional) helper method if basic auth is required
  ]
}]
```

Hive

#### Limits\Restrictions

- Maximum size for all requests (content + headers) is 10 MB
- Maximum of 5 requests
- Supported HTTP methods: `POST`, `GET`, `PUT`, `DELETE`, `HEAD`, `OPTIONS`, `TRACE`
- Pending requests will be cancelled after 60 seconds
- If an exception occurred or the response code was 408 (`RequestTimeout`), 500 (`InternalServerError`), 502 (`BadGateway`), 503 (`ServiceUnavailable`) or 504 (`GatewayTimeout`) the call will be retried up to three times.
- For `GET` and `HEAD` calls, the content will be omitted
- Currently only text files are allowed as request body (e.g. XML, CSV, JSON, form data, ...).

---

## Shopify

We highly recommend utilizing our free Shopify app if you wish to sell customizable products online through your Shopify shop. The app offers a smooth integration between the configurator and the checkout process of your Shopify shop.

### Setup

To get started, some simple steps must be performed on the Combeenation platform and Shopify shop.

  <iframe
    src="https://www.youtube.com/embed/Kbv-w5rC6j0"
    title="YouTube video"
    style={{
      position: 'absolute',
      top: 0,
      left: 0,
      width: '100%',
      height: '100%',
      border: 0
    }}
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
    allowFullScreen
  />

#### Combeenation platform

- Create a configurator on the Combeenation platform
- Set up a new Shopify shop in the configurator editor. (see [Checkout](/docs/integrations-and-api/checkout) section for more information)
- Adapt the prefilled JSON (for more information regarding the JSON, see [this section](/docs/integrations-and-api/checkout-types/shopify#usage-details))

```hive
ShopifyShop.Validate("""{{
    "products": [
        {{
            "main": {{
                "productId": "123456",
                "quantity": 1,
                "price": 99.99,
                "imageUrl": "Assetbundle1.MyImage.url",
                "title": "My coffee mug",
                "productText": "My product text",
                "weight": 10,
                "weightUnit": "KG",
                "customFields": [
                    {{
                        "id": "model",
                        "label": "Model type",
                        "value": "espresso",
                        "position": 1
                    },
                    {{
                        "id": "productionId",
                        "label": "Prod id",
                        "value": "DLU-128120-HR",
                        "position": 2,
                        "isVisible": false
                    }
                ]
            },
            "accessories": [
                {{
                    "productId": "987654",
                    "quantity": 1
                },
                {{
                    "productId": "456789",
                    "quantity": 2
                }
            ]
        }
    ]
}""")
```

:::info
Do not use the Hive `ShopifyParameter` type. Instead, build the checkout JSON as a Hive formatted string and validate it with `ShopifyShop.Validate`, as shown above.

The `categoryId` property is currently not supported. `ShopifyParameter` defines it as a number, while Shopify now expects a string and returns an error when it receives a number. With the text-based JSON approach, `categoryId` is ignored. Contact us if you need to use product categories.
:::

##### JSON creation with Custom JS

There are certain scenarios where the creation of the JSON in Hive is limited. For example, a dynamic list of accessories may be cumbersome to implement with the current Hive feature set. For these cases and any other custom scenarios, you can create the JSON with Custom JS.

Combeenation offers JS typings to assist during the development process and minimize typos and errors (e.g. incorrect property names). A sample of custom JS code can be seen as follows:

```javascript
const selectedAccessories = /** @type {Accessory[]} */ (CmpUtils.getCmpValue(CmpNames.SelectedAccessories));
const checkoutJson = /** @type {Cbn.CJS.ShopifyCheckoutJson}*/ ({
  products: [
    {
      main: {
        productId: CmpUtils.getTextCmpValue(CmpNames.SelectedProductId),
        quantity: CmpUtils.getNumberCmpValue(CmpNames.SelectedQuantity),
        price: CmpUtils.getNumberCmpValue(CmpNames.SelectedProductPrice),
        customFields: []
      },
      accessories: selectedAccessories.map(x => ({
        productId: x.id,
        quantity: 1
      }))
    }
  ]
});

CmpUtils.setCmpInput(CmpNames.ShopifyCheckoutJson, checkoutJson);
```

##### Validate JSON

In Hive the Shop type provides a function for validating the JSON (for both Text and Object-based parameters). We highly recommend using this function, because it allows you to quickly find problems in the JSON structure:

```javascript
ShopifyShop.Validate(ShopifyCheckoutJson);
```

#### Shopify shop

- Install the Combeenation app from the Shopify app store
- Go to "Apps -> Combeenation Configurator App -> Configurators"
- Add your configurator

For more information, see [this section](/docs/integrations-and-api/checkout-types/shopify#configurators) below.

### Usage details

#### Products

- You can add one or multiple configurable products to the cart.
- The plugin will check the SKU before adding it to the cart
  - Existing SKU: the existing product (with all its predefined parameters like price, title, ...) will be added to the cart
  - New SKU: The app will create a new product with the custom properties defined in the JSON. Those products will be cleared up after some time or if the order was successful.
- With `customFields` own properties can be defined and pushed to Shopify
  - `id` ... should be unique and can be used for further processing via Shopify/API/ERP/CRM systems
  - `label` ... display name of the custom field the user sees in the cart (if visible is true)
  - `value` ... is the value of the custom field
  - `position` ... defines the position of the custom field in the user cart
  - Visibility: Custom fields can be hidden by prefixing the `id` and `label` with `_` (e.g. `_myHiddenField`)
    - Visible fields can provide additional info to the user (e.g. selected model/color/...)
    - Invisible fields can be used for further processing data in Shopify or via API (e.g. internal technical information, IDs, ...)
- Both kinds of custom fields are later accessible in the backend in the order overview:  
  ![image.png](<https://docs.combeenation.com/assets/images/image%2843%29-5e8d18bc36336b634aad193f3a96651b.png>)

#### Prices & tax

- There is currently still an extra price property in the Shopify shop (similar to the other shop types). It will be used for the dashboard metrics, it won't be transferred to the Shopify shop.

:::warning
The one who builds the configurator has to display the price correctly. This means it has to adhere to Shopify settings.  
Usually Shopify adds the tax only during checkout, this means there are two options for those who build the configurator:

- Displaying the user the gross price in the configurator, but passing the net price to the Shopify app, in order to let Shopify add the tax during checkout
- Displaying the user the net price in the configurator and also passing this info to the Shopify app. In this case the user should be informed that the price is without taxes.
  :::

#### Accessories

- Accessories are usually products in the Shopify shop the user wants to add to the cart alongside with the configuration
- Accessories product price will be retrieved from Shopify
- Accessories are always standalone items in the cart. Bundles are not supported in Shopify (in contrast to the [Shopware shop](/docs/integrations-and-api/checkout-types/shopware-6))

### App configuration

#### General

The app configuration is used to define the dimensions of the iframe and properly configure the app and configurator base URLs.

![image.png](<https://docs.combeenation.com/assets/images/image%2841%29-a3fe5b17e92db928a0a8f92a9e0692c5.png>)

App settings include the following configurations:

- Sales channel selection
- iFrame width + unit for product detail page
- iFrame height + unit for product detail page
- Plugin base url: `https://portalcombeenation.com/plugin`
- Configurator base url: `https://portalcombeenation.com/Cfgr`

#### Configurators

Within `Combeenation Configurator App -> Configurators` you can create and manage configurators for your Shopify shop.

##### Create new configurator

![image.png](<https://docs.combeenation.com/assets/images/image%2845%29-a309214513ccede5bfbadde0a9d6a4f2.png>)

Each shop can be configured with unlimited configurators. These can all be individually customized.

- Id: Will be generated upon creation. The app block requires this id.
- Name: Please enter the name of the configurator you’ve created in the Combeenation Platform
- Company: Please enter the company name according to Combeenation Platform. The company name is part of the iFrame Url
- Hash Secret: Please enter the hash secret according to Combeenation's specifications. The hash secret is part of the iFrame url (leave blank for 3D/AR viewer)
- Status: The configurator can be enabled or disabled for this product
- Priority: Product configurator display is done according to the highest priority (so you don’t need to remove your product from another configurator, instead you just set the priority higher, and then only the settings on the one with a higher priority count)
- Hide "Add to cart" button: Hide the button on the product detail page
- Edit products: Here you can select the products which should be assigned to this  
  configurator. You can select as many as you’d like.

##### Advanced configuration

![advanced_Config.png](https://docs.combeenation.com/assets/images/advanced_Config-1add3fa5a5031e70592d76daf27f81ed.png)

You are able to replace the `Add-to-cart` button with a customizable `Configure Now` button.  
It offers the flexibility to customize the button's label text and color to match the shop's design language seamlessly.

#### Configurator Embed Block

If you are using an Online Store 2.0 theme, you must enable the Configurator Embed Block for the plugin to work in your shop.  
To enable the Embed Block, go to the theme editor, click the third icon on the left, and then enable the “Embed Configurator” block.  
![activate embed.png](https://docs.combeenation.com/assets/images/activate%20embed-a10bbede6f5ddc91e379537f2c58a309.png)

#### Configurator Block

A new configurator-block can be added by going into the Theme-Editor and adding a new section where under “Apps” a block with the name Configurator appears  
![app embeds.png](<https://docs.combeenation.com/assets/images/app%20embeds%281%29-2b73c287a090adfe8f666846fef2b0d4.png>)

The rest of the process is similar to the general settings, except that height and width can be set for each block. Only one block can be added per page, as multiple blocks can cause problems.

![block example.png](https://docs.combeenation.com/assets/images/block%20example-03eacd3d244b75b3390f16c0e5db340e.png)

#### Product Page

On the product page, the Configurator will appear below the Product. Once the product has been added to the cart using the configurator, it automatically redirects the customer to the cart, adding the custom products and any additional products in the process.

![product page.png](https://docs.combeenation.com/assets/images/product%20page-65f63d0b41faaf7c79c199626170b8e1.png)

### Import data into Combeenation

To import data from Shopify into the Combeenation platform, follow these steps:

- **Obtain API Access Token**: Generate an admin or storefront API access token in Shopify by creating a custom app.
- **Create JSON data source asset**: Create an asset bundle with a JSON data source that the workflow updates manually or on a schedule.
- **Set Up Workflow**: Configure a workflow in the Combeenation backend to retrieve data from the Shopify GraphQL endpoint.

#### Obtain API Access Token

In order to get the an API access token follow the Shopify guide to create a [custom app](https://help.shopify.com/en/manual/apps/app-types/custom-apps). After you have created the app, the admin API access token will be displayed once, store it securely, this token is later required for the workflow.

:::info
You can also use the storefront API access token to interact with the storefront API. However, be cautious, as this API primarily provides publicly available data and may not include all the information you need. It might not be sufficient for all use cases.
:::

#### Create JSON data source asset

In order to use the data from Shopify in your configurator, you have to create a [JSON data source asset](/docs/asset-management/data-source-asset/json-based-data-sources). If you have no experience with assets, see [Getting started with assets](/docs/asset-management/getting-started-with-assets) first.

If you have an asset bundle, we **recommend the following steps**:

- Install [GraphiQL](https://shopify.dev/docs/api/usage/api-exploration/admin-graphiql-explorer) explorer in your Shopify shop
- Open the GraphiQL and construct a GraphQL query with the necessary information about your products. Example GraphQL query:

```json
{
  products(first: 250) {
    edges {
      node {
        id
        title
        productType
        infoArea: metafield(namespace: "custom", key: "info_area") {
          id
          key
          value
          namespace
        }
        variants(first: 1) {
          edges {
            node {
              sku
              inventoryQuantity
              price
            }
          }
        }
        images(first: 1) {
          nodes {
            url
          }
        }
      }
    }
  }
}
```

- The explorer should now show you the resulting JSON, store this as a file
- Upload the file to your asset bundle as a file asset and assign a clear, descriptive name (e.g. `ShopifyProductsExport`)
- Based on this file asset you can now create one or multiple [JSON based data sources](/docs/asset-management/data-source-asset/json-based-data-sources) (see docs for more info)
- If you have created at least one data source you can continue with the workflow.

#### Set Up Workflow

The final step is to create a [workflow](/docs/integrations-and-api/workflows/workflow-basics) (see docs for more info) that retrieves the product data from Shopify and updates your created asset bundle + configurators.

The workflow sends a POST request to Shopify's GraphQL API. Upon successful data retrieval, it will:

1.  Create a new draft version of the asset bundle.
2.  Update the file asset, automatically refreshing all associated data sources.
3.  If all steps are completed successfully, the asset bundle and linked configurators will be published, providing customers with the most up-to-date data from Shopify.

Here’s an example workflow. Ensure you replace the placeholder data accordingly:

- `bundle` parameter ... needs to be configured in the workflow parameter settings
- `<ACCESS_TOKEN>` ... retrieved in the step above
- `<GRAPHQL_QUERY>` ... retrieved in the step above
- `<SHOP_NAME>` ... name of your Shopify shop, can be found in the URL (e.g. `https://<SHOP_NAME>.myshopify.com`)
- `<FILE_ASSET_NAME>` ... retrieved in the step above (e.g. `ShopifyProductsExport`)

```javascript
import { bundle } from '@workflow/parameters';

export async function run() {
  const requestConfig = {
    headers: {
      'Content-Type': 'application/json',
      'X-Shopify-Access-Token': '<ACCESS_TOKEN>' // header name varies for storefront API
    }
  };
  const content = {
    query: '<GRAPHQL_QUERY>'
  };

  try {
    // 1. try to retrieve the data from Shopify admin API endpoint (url + header name may vary for storefront API)
    const response = await http.post('https://<SHOP_NAME>.myshopify.com/admin/api/2025-01/graphql.json', JSON.stringify(content), requestConfig);

    // 2. create a new asset bundle draft based on the asset bundle parameter
    const draft = await bundle.createDraft();
    // 3. get the file asset which should be updated
    const fileAsset = draft.getAsset('<FILE_ASSET_NAME>');
    // 4. update the shopify file asset
    await fileAsset.update(response.data);
    // 5. publish the asset bundle draft & all configurators
    await draft.publish(_ => {
      return true;
    });
  } catch (error) {
    printError(error);
  }
}

function printError(error) {
  console.error('Error occurred: ' + error);
  console.debug('Url: ' + error.url);
  console.debug('Message: ' + error.message);
  console.group('Start printing error response');
  printResponse(error.response);
  console.groupEnd();
}

function printResponse(response) {
  console.log('Status-Code: ' + response.status);

  console.group('Start printing headers...');
  for (const key in response.headers) {
    console.log(`${key}: ${response.headers[key][0]}`);
  }
  console.groupEnd('Printing headers finished.');

  if (response.data !== undefined) {
    // `url` returns the URL of the retrieved data
    console.log('Data URL: ' + response.data.url);
    // `raw` string is only defined, if data is smaller than 1MB
    console.log('Data Raw: ' + response.data.raw);
  }
}
```

### Whitelisting & Shopify Domains

If you use the [whitelist feature](/docs/integrations-and-api/embedding-and-whitelist#whitelisted-domains) to restrict which domains may embed your configurator, you need to add all domains that will load it — including those used by Shopify's own infrastructure.

In addition to your public shop URL (e.g. `https://myshop.com`), the following domains must be whitelisted so the configurator also works inside the **Shopify theme editor** backend:

- **Your internal Shopify shop domain** — this is your real `.myshopify.com` address, e.g. `https://demo-combeenation.myshopify.com`.  
  To find it, log in to your Shopify admin and look at the URL in your browser — it will be in the format `https://<your-shop-name>.myshopify.com`. Alternatively, go to `Settings > Domains` in your Shopify admin; your `.myshopify.com` domain is always listed there.
- `https://admin.shopify.com`
- `https://online-store-web.shopifyapps.com`

Without these entries the configurator will fail to load when you preview or edit your theme in the Shopify theme editor.

### FAQ

#### Why is the configurator not visible on the Shopify product page?

- Check that the configurator is published in the Combeenation backend.
- In the Shopify app, verify the company name, configurator name, and status in the [configurator settings](#configurators). The hash secret is not relevant for visibility.
- To display it on the product detail page, check that the product is assigned to the configurator in the Shopify app.
- If you use whitelisting, check that the product page's domain and Shopify's theme editor domains are included in the [whitelist](#whitelisting--shopify-domains).

#### Why is the configurator not visible after adding an app block?

- Is the app block added to a product detail page, or are there multiple app blocks on the same page? This scenario is not supported.

  When customers edit a configured product from the cart, they are redirected to the product page and the corresponding configuration session is restored in the iframe. If multiple iframes were allowed on a page, the app could not determine which iframe should display the restored session.

#### Why can't the product be added to the cart?

- Use `ShopifyShop.Validate` to check that the checkout JSON has the correct structure. See [JSON creation with Custom JS](#json-creation-with-custom-js) and the [Hive example](#combeenation-platform).
- Verify the Shopify app configuration, especially the hash secret and selected sales channel.
- For an existing product, verify that its SKU is active, in stock, and available for the store location selected in the Shopify app.
- For a newly created product, wait for Shopify to create and publish it before adding it to the cart. See [Why does adding a newly configured product take time?](#why-does-adding-a-newly-configured-product-take-time).

#### Why does adding a newly configured product take time?

Adding a newly configured product to the cart is not instantaneous. Because every configuration is unique, the plugin must:

1. Create a new product in Shopify.
2. Wait for Shopify to process and publish the product so it becomes available in the storefront.
3. Add the product to the cart.

Product creation itself is usually fast. Most of the delay occurs while Shopify makes the product available in the storefront. Attempting to add the product before this process is complete results in an error.

##### Can this be optimized?

Shopify does not currently provide a way to bypass or accelerate this synchronization. The plugin must wait until Shopify confirms that the product is available before adding it to the cart.

##### Existing vs. New Products

- **Existing products:** Adding to the cart is much faster because no product creation is required.
- **New configured products:** A new Shopify product must be created and synchronized first, which introduces the additional delay.

##### Custom Integrations

If your storefront requires a different workflow, a custom integration is possible. Instead of letting the plugin add the product to the cart, it can send the generated [JSON](#combeenation-platform) to the parent Shopify page, allowing you to implement your own cart or checkout logic.

#### Why are custom fields not visible in the cart?

Custom fields are hidden when both their `id` and `label` begin with an underscore, for example `_myHiddenField`. Hidden fields are still included in the Shopify order and can be used for backend processing. See [Products](#products).

#### Why are accessories shown as separate cart items?

Accessories are standalone Shopify products, and Shopify does not support product bundles in this integration. Their prices are retrieved from Shopify. See [Accessories](#accessories).

#### Why are configured products visible in my Shopify catalog?

The app creates a Shopify product for each configured item, then deletes it after a successful order or after a fixed period when no order is placed. To hide these temporary products from collections, exclude products with the type `COMBEENATION CONFIGURATOR SURCHARGE PRODUCT`.

#### Is the app compatible with every Shopify theme?

Shopify's theme guidelines do not allow compatibility with every theme to be validated. We mainly test the compatitlby against the "Dawn" theme. Test the app thoroughly with your selected theme before publishing it.

#### Why can't I query more than 250 items?

The GraphQL API has an upper limit of 250 entries. To retrieve more items, use [pagination](https://shopify.dev/docs/api/usage/pagination-graphql) in your workflow.

---

## Shopware 6

We highly recommend utilizing our free Shopware 6 plugin if you wish to sell customizable products online through your Shopware 6 shop. The plugin offers a smooth integration between the configurator and the checkout process of your Shopware shop.

### Setup

To get started some simple steps must be performed on the Shopware shop and the Combeenation platform.

  <iframe
    src="https://www.youtube.com/embed/C24mIJi7bzs"
    title="YouTube video"
    style={{
      position: 'absolute',
      top: 0,
      left: 0,
      width: '100%',
      height: '100%',
      border: 0
    }}
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
    allowFullScreen
  />

Prerequisites

- In order to use the Combeenation platform with Shopware 6, you must be using the self-hosted version of the software.
- The configurator must be created/hosted on the Combeenation platform, and you must ensure that the Shopware 6 shop has been added to it. Further details can be found in the Combeenation platform documentation (see [below](/docs/integrations-and-api/checkout-types/shopware-6#combeenation-platform))

#### Combeenation platform

1.  Set up a new Shopware 6 shop in the configurator editor. (see [Checkout](/docs/integrations-and-api/checkout) section for more information)
2.  Adapt the prefilled JSON, see below

To pass data from the Combeenation platform to Shopware, a JSON object with a specific structure must be created. When creating a new shop, an example object will be provided.

```javascript
new Shopware6Parameter {
  //addToWishlist: true, // determines if this product and all its accessoires will be added to the wishlist instead of the cart (default: false)
  products : [
    // (mandatory) at least one product must be defined
    new {
      main : new {
        productId : "123456",  // SKU id from your Shopware system
        quantity : 1,
        price : 99.99, // gross price of the configured product WITHOUT accessories
        imageUrl : "Assetbundle1.MyImage.url", // url to the image which will be used in the cart
        title : "My coffee mug", // new title of the product
        productText : "My product text",  // new description of your product
        customFields : [ // (optional)
          new {
            id : "model", // unique identifier
            label : "Model type", // label which the user will also see in the cart (if it is visible)
            value : "espresso", // value of the custom field
            position : 1, // position in the cart
            //isVisible: true // if it should be visible in the cart (default: true)
          },
          new {
            id : "productionId",
            label : "Prod id",
            value : "DLU-128120-HR",
            position : 2,
            isVisible : false
          }
        ]
      },
      // (optional) additional predefined Shopware products which will be added to the cart (no custom price/image/title)
      accessories : [
        new { productId : "987654", quantity : 1 },
        new {
          productId : "456789", // Shopware sku
          quantity : 2,
          // if false (default) the product will be linked to the main product and can't be deleted from cart
          // if true the product will be added as a standalone product to the cart
          isSingleCartItem : true
        }
      ]
    }
  ]
}
```

:::info
At this point, your configurator is embedded on Shopware and a checkout should be possible. Give it a try!
:::

##### JSON creation via custom JS

There are certain scenarios where the creation of the JSON in Hive is limited. For example, a dynamic list of accessories may be cumbersome to implement with the current Hive feature set. For these cases and any other custom scenarios, you can create the JSON with Custom JS.

Combeenation offers JS typings to assist during the development process and minimize typos and errors (e.g. incorrect property names). A sample of custom JS code can be seen as follows:

```javascript
const selectedAccessories = /** @type {Accessory[]} */ (CmpUtils.getCmpValue(CmpNames.SelectedAccessories));
const checkoutJson = /** @type {Cbn.CJS.Shopware6CheckoutJson}*/ ({
  products: [
    {
      main: {
        productId: CmpUtils.getTextCmpValue(CmpNames.SelectedProductId),
        quantity: CmpUtils.getNumberCmpValue(CmpNames.SelectedQuantity),
        price: CmpUtils.getNumberCmpValue(CmpNames.SelectedProductPrice),
        customFields: []
      },
      accessories: selectedAccessories.map(x => ({
        productId: x.id,
        quantity: 1,
        isSingleCartItem: true
      }))
    }
  ]
});

CmpUtils.setCmpInput(CmpNames.ShopwareCheckoutJson, checkoutJson);
```

##### Validate JSON

In Hive the Shop type provides a function for validating the JSON (for both Text and Object-based parameters). We highly recommend using this function, because it allows you to quickly find problems in the JSON structure:

```javascript
Shopware6Shop.Validate(ShopwareCheckoutJson);
```

#### Shopware shop

1.  Install the [plugin](https://store.shopware.com/combe94943819277f/3d-konfigurator-fuer-shopware-6.html) in your Shopware 6 shop
2.  Go to "Settings -> Extensions -> Combeenation Configurators -> Product Configurators"
3.  Add your configurator

For more information [scroll down](#plugin-configuration).

### Usage details

#### Products

- You can add one or multiple configurable products to the cart.
  - You can add one or multiple configurable products to the wishlist if the flag `addToWishlist` is `true`

- `Price, title, image, description` are optional, if not set the values from the Shopware product will be used. -> Exception: If accessoires are added a price for the main product must be set.
- With `customFields`own properties can be defined and pushed to the Shopware system
  - `id` ... should be unique and can be used for further processing via Shopware/API/ERP/CRM systems
  - `label` ... display name of the custom field the user sees in the cart (if visible is true)
  - `value` ... is the value of the custom field
  - `position`... defines the position of the custom field in the user cart
  - `isVisible`... defines if this custom field should be visible in the cart
    - Visible fields can provide additional info to the user (e.g. selected model/color/...)
    - Invisible fields can be used for further processing data in Shopware or via API (e.g. internal technical information, IDs, ...)

#### Prices & tax

- There is currently still an extra price property in the Shopware 6 shop (similar to the other shop types). It will be used for the dashboard metrics, it won't be transferred to the Shopware shop.
- Tax rate and tax state will be given to the configurator via query parameters
- Tax rate may vary per country based on the different value-added tax (VAT)
- Access the tax rate in Hive with `Configuration.getParameter(Shopware6Shop.TaxRate)` (valid values: `1-100`)
- Tax state vary based on the user account (user or merchant)
- Access the tax state in Hive with `Configuration.getParameter(Shopware6Shop.TaxState)` (valid values: `net` or `gross`)
- Configurator has to display the price correctly according to given parameters.

  :::info
  The one who builds the configurator has to display the price correctly. This means it has to adhere to the given tax parameters from the Shopware 6 shop. E.g. display net price if the tax state is `net`.
  :::

  :::info
  The price given back to the Shopware system should be the **gross price** of the configured product WITHOUT the accessories.
  :::

#### Accessories

- Accessories are usually products in your Shopware shop the user wants to add to the cart alongside with the configuration
- Accessories product price will be retrieved from Shopware
- Accessories can be connected to the main configured product (`isSingleCartItem: false`) or can be added as standalone cart item (`isSingleCartItem: true`).
- Standalone items can be deleted/updated without any effect on the customized configuration

### Plugin configuration

The plugin configuration is used to define the dimensions of the iframe and properly configure the plugin and configurator base URLs.

![](https://docs.combeenation.com/assets/images/Bild1-f8a3c18e2a2e4866e675978d7d0f594d.png)

Plugin settings includes the following configurations:

- Sales channel selection
- iFrame width + unit for product detail page
- iFrame height + unit for product detail page
- Plugin base url: `https://portalcombeenation.com/plugin/`
- Configurator base url: `https://portalcombeenation.com/Cfgr/`

### Shopware 6 settings in detail

Within Settings -> Extensions, there is a menu item "Combeenation Configurators" which allows to create and manage configurators.

By clicking on the 3 dots on the right, configurators can be edited, duplicated and deleted. You can create one or more configurators.

#### Create configurator

When creating a new configurator, the following settings are available:

![](https://docs.combeenation.com/assets/images/Bild2-5427dda0ed0daa68e4656d85b360ef90.png)

##### Settings

- Product configurator name
  - Please enter the name of the configurator you’ve created in the Combeenation Platform. The configurator name is part of the iFrame Url.

- Company
  - Please enter the company name according to Combeenation Platform. The company name is part of the iFrame Url.

- Hash Secret
  - Please enter the hash secret according to Combeenation's specifications.

- Active circuit
  - You must set your configurator active

- Rule
  - A rule builder can be added for the display control of the configurator.
  - If the configurator should always be displayed, select the rule "Always valid (default)".

- Priority
  - Product configurator display is done according to the highest priority

- Display control product details page
  - There are 3 [integration types](/docs/integrations-and-api/checkout-types/shopware-6#display-control-product-details-page) for the product details page to choose from.
  - On the product details page, the article number is also passed to the iFrame in order to load the correct article.

- Dynamic product group
  - For the integration on the product detail page, a dynamic product group is required. The Combeenation configurator is then loaded for these dynamic products.

- Sales channels
  - Selection of the sales channels in which the product configurator should be displayed.

#### Display control product details page

1.  **Load iFrame instead of product details page**  
    The plugin automatically loads the Combeenation configurator on the product detail page of the respective article. As mentioned above, the specific loading of the article is accomplished by adding the product id as url parameter to the configurators iFrame.
2.  **Product detail page with configurator button - without add to cart button**  
    The standard product detail pages are displayed and the shopping cart button is replaced with the "configure now" button. The article is not orderable without configuration.  
    Clicking the button loads the configurator in the "Configurator" tab.

    ![](https://docs.combeenation.com/assets/images/Bild3-4ebf6bb3980dda8d0508999718432572.png)

3.  **Product details page with configurator button - with add to cart button**  
    The standard product detail pages are displayed with the "configure now" button and the standard add to cart button from Shopware. Items can be added to the shopping cart without configuration.  
    Clicking on the button loads the configurator in the "Configurator" tab.

    ![](https://docs.combeenation.com/assets/images/Bild4-f4ca611687b4abf6fb8ea73c32f46405.png)

#### Configurator Integration via Shopping Experience

You can easily integrate your configurator with a shopping experience block/element anywhere in your store.

![](https://docs.combeenation.com/assets/images/Bild5-f8bc7fede303b99d72f78065d374eacf.jpg)

##### Settings

- Combeenation Configurator
  - Please select the configurator which should be displayed in the experience world

- iFrame width + unit
- iFrame height + unit

![](https://docs.combeenation.com/assets/images/Bild6-3d1d650730994575e6f7d01913677e07.jpg)

##### Product detail page via Shopping Experience

If you have configured the product details page via Shopping Experience, you must replace the Buybox and Gallery by setting the “display control product detail page” to "load iFrame instead of product details page". All other display controls are automatically integrated into the product details page shopping experience.

#### REST API

The transferred configuration data is stored per order line item. This data is fully accessible via the Shopware backend or via the Shopware REST API.

To access the Shopware OAuth API you first have to retrieve an `access token`, the full process is described in the [Shopware docs](https://shopware.stoplight.io/docs/admin-api/ZG9jOjEwODA3NjQx-authentication).

```shell
POST https://yourshop.com/api/oauth/token
Content-Type: application/json

{
    "grant_type": "client_credentials",
    "client_id": "YOUR_ID",
    "client_secret": "YOUR_SECRET"
}
```

If you already know the order line item of your order, you can simply request this entry via the [http://yourshop.com/api/order-line-item/\{id\}](http://yourshop.com/api/order-line-item/%7Bid%7D) call, for more info see [here](https://shopware.stoplight.io/docs/admin-api/061f0264c11f0-detailed-information-about-a-order-line-item-resource). Example response from order item:

```json
{
  "id": "b42159bbfcf644809bde62d9d2c0fe5f",
  "type": "order_line_item",
  "attributes": {
    "productId": "c5d43dc9a4784b399b81a774d5ff5377",
    "quantity": 1,
    "label": "Single Weiss",
    "payload": {
      "combeenationPrice": 359,
      "combeenationImageId": "4e461b3abd36451aacab32be44f87a0d",
      "combeenationCustomFields": [
        {
          "id": "textInput",
          "label": "Texteingabe",
          "value": "Combeenation",
          "position": 1,
          "isVisible": true
        },
        {
          "id": "textPosition",
          "label": "Textposition",
          "value": "Vorne oben",
          "position": 2,
          "isVisible": true
        },
        {
          "id": "font",
          "label": "Schriftart",
          "value": "Lobster",
          "position": 3,
          "isVisible": true
        },
        {
          "id": "fontColor",
          "label": "Schriftfarbe",
          "value": "Royalblau",
          "position": 4,
          "isVisible": true
        },
        {
          "id": "logoUrl",
          "label": "Logoupload URL",
          "value": "https://combeespecs.blob.core.windows.net/resources/ACRIS/PORZELLAN/resources/0C9aCfcJYWG.png",
          "position": 5,
          "isVisible": true
        },
        {
          "id": "logoSize",
          "label": "Logo-Größe",
          "value": "M",
          "position": 6,
          "isVisible": true
        },
        {
          "id": "fondColor",
          "label": "Fond-Bemalung",
          "value": "Eisenrot",
          "position": 9,
          "isVisible": true
        }
      ],
      "combeenationConfiguratorEditUrl": "164537474310767104/edit/0BsbN0hebq4",
      "combeenationConfiguratorId": "164537474310767104",
      "isCloseout": false,
      "customFields": {
        "acris_cms_layout_slot_config": []
      },
      "createdAt": "2022-10-07 09:19:35.559",
      "releaseDate": null,
      "isNew": false,
      "markAsTopseller": null,
      "purchasePrices": "{\"extensions\":[],\"currencyId\":\"b7d2554b0ce847cd82f3ac9bd1c0dfca\",\"net\":0,\"gross\":0,\"linked\":true,\"listPrice\":null,\"percentage\":null,\"regulationPrice\":null}",
      "productNumber": "158531C-999",
      "manufacturerId": "0fd9e3fa3a6e4980870116111dc37a15",
      "taxId": "9a518fcac39347a78155c7a711217dd5",
      "tagIds": null,
      "categoryIds": ["12e24ea60d684d5e8116fbc588c6e76c", "617f724d27894167a39e56605f3ed9be"],
      "propertyIds": null,
      "optionIds": null,
      "options": [],
      "streamIds": ["9e618e47ab5a415d89d71b487c7cb1b1"],
      "parentId": null,
      "stock": 999,
      "features": []
    },
    "good": false,
    "position": 2,
    "unitPrice": 379.0,
    "totalPrice": 379.0,
    "customFields": null,
    "apiAlias": null
  },
  "links": {
    "self": "https://YOURSHOP.com/api/order-line-item/b42159bbfcf644809bde62d9d2c0fe5f"
  },
  "relationships": [],
  "meta": null
}
```

If you first have to find the order line item, you could use the search api to find all items from an order for a given order id, this looks something like:

```shell
POST https://yourshop.com/api/search/order
Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "associations": {
    "lineItems": []
  },
  "filter": [
    {
      "type": "equals",
      "field": "orderNumber",
      "value": "10014"
    }
  ]
}
```

#### Email Template (Order Confirmation Including Configurator Data)

While installing the plugin, a new email template for the order confirmation is created. You must replace this template so that the additional configuration data is displayed in the email.

![](https://docs.combeenation.com/assets/images/Bild7-8b99346176ccbd80fd6b91d8456642e2.jpg)

#### Order Overview

Orders placed via the configurator are displayed in the orders overview like all other orders. Since the exact same configuration might not be available later on, the repeat order function is disabled for such orders.

#### Wishlist

To add a product to the wishlist the JSON must be adjusted accordingly see [here](/docs/integrations-and-api/checkout-types/shopware-6#products).

:::info
Please note that shop visitors who are not logged in must accept the cookie for the wish list in order to use the functions. The cookie is listed in the comfort functions section of the storefront cookie manager.
:::

### Import Shopware products into Combeenation

This can be done via [Workflows](/docs/integrations-and-api/workflows/workflow-basics) and [Shopware sales channel](https://docs.shopware.com/en/shopware-6-en/Productcomparison). The Shopware sales channel provides a product feed in any possible format (e.g. CSV, XML, ...). This feed can then be used by the workflow to update a [data source](/docs/asset-management/data-source-asset/basics).

#### Shopware Sales Channel

For the creation of a channel, follow the steps in the [Shopware documentation](https://docs.shopware.com/en/shopware-6-en/Productcomparison). Recommended values for product export sections are:

- File name: something which relates to the products you are exporting (e.g. bikes.csv) or something generic (cbnExport.csv)
- Encoding: UTF-8
- File format: CSV
- Interval: is based on the frequency of your product changes (if there are no daily updates, you can set the interval without problem to 24h or higher)
- Dynamic product group: Create a dynamic product group in order to export only the products which are relevant to the configurator
- After that we will adapt the template of the channel to serve a CSV which is supported as data source input. Sample template provided below:

```header
"sku","price","title","weight","deliverable","manufacturer","imageUrls","Property A","Property B"
```

```body
"{{ product.productNumber }}",{% set price = product.calculatedPrice %}{%- if product.calculatedPrices.count > 0 -%}
    {% set price = product.calculatedPrices.last %}
{%- endif -%}
{{ price.unitPrice|number_format(2, '.', '') }},"{{ product.translated.name }}",{{ product.weight }},"{%- if product.availableStock > 0 -%}true{%- else -%}false{%- endif -%}","{{ product.manufacturer.name }}","{% if product.cover is not null %}{{ product.cover.media.url }}{% endif %}","{%- for property in product.properties -%}{# Property A #}
  {%- if property.groupid == 'f057d0f4d7014a8eb85666d7f96cc844' -%}{{property.name}}{%- endif -%}
{%- endfor -%}","{%- for property in product.properties -%}{# Property B #}
  {%- if property.groupid == 'ef5bedbd0ea946c28e4cf5e90efc4d62' -%}{{property.name}}{%- endif -%}
{%- endfor -%}"
```

For testing the Shopware feed click "Generate preview", if the result is a valid CSV, you are ready for the next step.

Retrieve the URL to the Shopware by navigating back to "General" -> "API access" and copy the export url, which we need for the workflow.

##### Good to know

- The template language used by Shopware is [twig](http://twig.symfony.com/).
- The id of the property can be found by navigating to the according property and copying it from the URL
- The body doesn't contain any new line, because the resulting CSV should only contain a new line at the end of a product.

#### Workflow

In order to import the products from Shopware we will create a new [workflow](/docs/integrations-and-api/workflows/workflow-basics) in your company. In the parameter sections of your workflow add an asset bundle parameter to the bundle which contains your data source. Furthermore create a file parameter, which is basically just the URL we copied earlier in Shopware. This will download the feed from the shopware and make it available for the workflow.

Below is an example workflow with two Shopware feeds and two data sources which will be updated.

```javascript
import { bundle, shopwareFeed, shopwareFeed2 } from '@workflow/parameters';

export async function run() {
  // 1. create a new asset bundle draft based on the asset bundle parameter
  const draft = await bundle.createDraft();

  // 2. get the data source assets which should be updated
  const myDs = draft.getAsset('myDs');
  const myDs2 = draft.getAsset('myDs2');

  // 3. update all data source assets
  await myDs.update(shopwareFeed);
  await myDs2.update(shopwareFeed2);

  // 4. after updating all asset bundles, we publish asset bundle draft
  await draft.publish(cfgr => {
    // for the dev configurator we won't perform a publish
    if (cfgr.name == 'MYCFGRDEV') {
      return { update: true, publish: false };
    }
    return { update: true, publish: true };
  });
}
```

##### Good to know

- This example contains two feeds to demonstrate, that one workflow and can also updates several data sources in one draft without publishing it in between

---

## WooCommerce

The recommended method for implementing a checkout process in a WooCommerce shop is using the flex checkout approach.  
If assistance is needed with integrating the necessary JSON code, please contact [info@combeenation.com](mailto:info@combeenation.com).

---

## Checkout

The main purpose of the Checkout is to complete a configuration and export certain information/data from this configuration to the customer, shopping cart, ERP system or third party application.

Combeenation provides a broad variety of checkout options including [Shopware](/docs/integrations-and-api/checkout-types/shopware-6), [WooCommerce](/docs/integrations-and-api/checkout-types/woocommerce), [mails](/docs/integrations-and-api/checkout-types/mail-checkout), [REST](/docs/integrations-and-api/checkout-types/rest-checkout) or [FTP](/docs/integrations-and-api/checkout-types/ftp-checkout) calls or a [do it yourself](/docs/integrations-and-api/checkout-types/flex-checkout) approach.

### Quickstart

You can create a shop for the checkout type of your liking by clicking on the ➕ icon in the upper right corner of the `CheckoutComponent` editor.

Whilst you can create multiple checkout shops, there's always exactly 1 active shop at a time. The active shop is determined by the resulting value of the [Hive script](/docs/configurator-logic/hive-introduction) in the `CheckoutComponent's Shop` property.

:::info
Since this Hive script can also take its input into consideration, there are many different ways to define which shop should be activated. E.g. by selected preset, by given URI paramter, by the wizard page on which the checkout was initiated, ...
:::

### Checkout and stages

A [configurator stage](/docs/fundamentals/creating-a-configurator#configurator-stages) can be used to test all features of a configurator, including checkout.

However, depending on the type of shop you use in your checkout, you may want to use different checkout settings in a configurator stage. For instance, when sending a mail in a staged configurator, you may want to send that mail to a test address rather than your primary contact address. Or if you have an entirely separate QA environment for your website and/or shop solution you may have to use different product IDs, connection strings, authentication tokens or similar.

In order to achieve slightly different behavior in configurator stages, you can explicitly test if the configurator [is published, staged or in preview](/docs/configurator-logic/configurator-and-presets-variable#properties):

```hive
if configurator.IsPublished then
  "sale@demo.com"
else
  "test@demo.com"
end
```

Hive

Depending on how much your staging checkout differs from a published version, a simple if/else expression in e.g. the recipient field of a mail shop may suffice.  
Another option is to create an entirely separate Shop for your staging checkout and then use that in the Shop property of the Checkout component.

### Advanced configuration

#### How to trigger the checkout

The checkout can be triggered using Signals and Slots in the design editor, by binding the `CheckoutComponent`'s `Do checkout` slot to the `clicked` signal of a button.

During the SigSlo setup you can optionally also set the `Selected shop`, which will set the input value for `CheckoutComponent shop` property.

The Hive rule of the `CheckoutComponent shop` property must actively use its input for the `Selected shop` paramter to actually take effect.

#### Customizing the checkout load mask

By default, the configurator shows a load mask with the text "Adding configuration to cart..." when the checkout is started. This load mask is never hidden by default and will stay there until the user leaves the site or closes the tab or browser.

Since most checkouts redirect to the shopping cart after the checkout is succeeded, the load mask will only be visible briefly.

You can customize the message shown in the load mask via signals & slots. When creating a new configurator, the following SigSlo is responsible for showing the default checkout load mask: `Checkout.CheckoutStarted -> Configurator.ShowLoadMask('Adding configuration to cart...')`:

![](https://docs.combeenation.com/assets/images/AdjustCheckoutLoadMaskText-7a3b5e21ec8ac9371b6eedb1819ee5c8.png)

An easy way to customize the shown message is by simply changing the value of the Message parameter for the existing SigSlo as shown above.

If you'd like to show a more advanced UI during checkout, you can also delete this SigSlo, create your own UI and manage showing and hiding of it using the CheckoutComponent's Checkout started & Checkout succeeded signals.

#### Confirmation after checkout

If you want to hide the load mask after a checkout has succeeded (e.g. after the mail has been sent), you can do this with signals & slots. Simply by using the `CheckoutComponent's Checkout succeeded signal` and the `configurator control's hide load mask slot`. Or you can also show your own UI with some confirmation using the `CheckoutComponent's Checkout succeeded signal`.

#### Continuing configuration after checkout

If needed, you can keep the configurator open for further configuration after the checkout. A new configuration will be started automatically to protect the checked out one from any modifications. This change is completely transparent and should not be noticed by the user. When this new configuration is checked out, it replaces the previous one.

You only have to manually hide the load mask using the `CheckoutComponent's Checkout succeeded signal`.

---

## Combeenation API

The Combeenation API is an interface which can be called programmatically with any possible HTTP REST client.

### Endpoint

The endpoint for the [API v1](/docs/integrations-and-api/combeenation-api#api-v1) is `https://api.combeenation.com/v1`

### Authentication

Authenticate each request by setting the `Authorization` header with a valid API token. Create and manage your API tokens in the company settings. You can have up to two API tokens.

We accept just the API token itself:

```none
"Authorization": "5bNPyHJWpF3PVT0bMho_kOOuPx0RD47pkPjRSsB8uauE6nrie+8eNZhggdwozjzKVqRy4k3xEvQAOHDHAZAoqc=="
```

or the API token in the Bearer format:

```none
"Authorization": "Bearer 5bNPyHJWpF3PVT0bMho_kOOuPx0RD47pkPjRSsB8uauE6nrie+8eNZhggdwozjzKVqRy4k3xEvQAOHDHAZAoqc=="
```

:::warning
Make sure to store your API keys somewhere secure and never share them publicly.
:::

### API v1

For the full URL just concatenate the [endpoint URL](/docs/integrations-and-api/combeenation-api#endpoint) with the action you want to execute (e.g. `https://api.combeenation.com/v1/version`).

#### General

**`[GET]`** `/version` ... returns information about the API endpoint

#### Configurations

**`[POST]`** `/configurations/{id}/copy` ... creates a copy of the configuration with the given `{id}` within the same configurator  
**`[POST]`** `/configurations/copy` ... copies a configuration to any configurator and applies mapping of input values (useful when component names differ)

```json
{
  "id": "170620771536492032", // id of the source configuration
  "targetConfigurator": "MYCONFIGURATOR", // name of the target configurator
  "targetStage": "testing", // (optional) name of a target stage, omit it to use the published configurator
  "inputs": {
    "MyCmp": "CmpRenamed", // src component name : target component name
    "MyCmp2": "MyCmp2"
  }
}
```

#### Finishes

**`[POST]`** `/finishes/{id}/copy` ... copy the finish with the given `{id}`  
**`[POST]`** `/finishes/copy` ... copies a finish to any configurator and applies mapping of input values (useful when component names differ)

```json
{
  "id": "170620771536492032", // id of the source finish
  "targetConfigurator": "MYCONFIGURATOR", // name of the target configurator
  "targetStage": "testing", // (optional) name of a target stage, omit it to use the published configurator
  "inputs": {
    "MyCmp": "CmpRenamed", // src component name : target component name
    "MyCmp2": "MyCmp2"
  }
}
```

---

## Configuration Finish

A configuration can be explicitly finished, which marks it as complete and triggers a number of user-defined actions such as sending mails, creating a quote, pushing data to 3rd party applications (such as ERPs) or adding an item to an ecommerce shopping cart.

:::info[On Checkout]
The process of completing a configuration was previously known as [Checkout](#), which is still available and fully functional.

We are currently in the process of rolling out the new Finish experience.
:::

### Finish Actions

Everything that happens when a configuration is finished is defined by so-called finish actions in the `FinishActions` rule.

You can define different sets of actions based on the current user, [configurator stage](/docs/fundamentals/creating-a-configurator#configurator-stages) or any other characteristic you like.  
When a configuration is finished, you can view the results of all actions on the [Insights](/docs/configuration-insights/configuration-insights-) page.  
You can optionally assign a custom `actionName` to each of your finish actions, if you plan to access their results later on.

**Checkout interaction:** if your configurator contains a `CheckoutComponent`, then its `Shop` will be automatically converted into a finish action.
You can keep using the `CheckoutComponent` and define additional finish actions – but be aware that certain actions can only be used once per configuration.
If you do not define a Goal for your finish (with `OnFinish.SetGoal`), then the `Shop.Name` will be set as Goal.

**Example FinishActions rule**

```hive
var actions : List<FinishAction> = [
  OnFinish.SetOutput({
    color: SelectedColor,
    price: unitPrice * Amount
  }),
];

if Input = "Save" then
  actions.concat([
    OnFinish.SetGoal("Save"),
    OnFinish.SendMail(new {
      from: new { mail: "test@example.com", name: "Test Inc." },
      to: [ new { mail: "user@example.com" } ],
      subject: "Test Mail",
      message: "Example content",
    })
  ])
elif Input = "Quote" then
  actions.concat([
    OnFinish.SetGoal("Quote"),
    OnFinish.Quote(MyQuote)
  ])
else
  actions
end
```

:::tip[TIP]
By using an **explicit** type, the `var actions : List<FinishAction>` variable will be able to hold a list of **any** type of finish action.
Without the explicit type, the list would want all actions to be of the **same** type. \
This also helps when combining lists of actions and is why in the example the `concat()` is done in each branch of the `if`
:::

---

## Embedding & Whitelist

### Embedding

To embed a Configurator in a website, only two HTML tags (`<script>`& `<iframe>`) are required, example:

```html
<script src="https://portal.combeenation.com/plugin/COMPANY/CONFIGURATOR"></script>
<iframe class="cbn-embedded-configurator" frameborder="0" data-cfgrurl="https://portal.combeenation.com/Cfgr/COMPANY/CONFIGURATOR">
</iframe>
```

Plain text

The `<script>` tag (the plugin) is required to achieve communication between the parent page and the configurator. The script tag has to be included every time and should be embedded in the `<head>`-section of the website.

`<iframe>` is a HTML 5 element which basically just displays another website (e.g. Combeenation configurator) in the current website (e.g. your website). Place this element wherever the configurator should be visible on the website.

#### Embed Snippet

Combeenation platform provides a ready-to-go embed snippet for your configurator under `Dashboard > Embedding`. Basically, you just need to paste the code on the desired place on your website and you're good to go.

If you are using a CMS (e.g. WordPress, Drupal, ...) there is most likely some kind of HTML editor, which allows you to add the embed code to the page. If you are unsure where to put the code or don't have access to your code please contact your web administrator.

#### Best practice - Step by Step

To provide the best embedding experience, please follow the according steps.

##### Step 1

Make sure that the correct media queries are used within the configurator. Otherwise, the embedded configurator will scale poorly and incorrectly.

✓ `min-width, max width, min-height or max-height`

✕ `min-device-width, max-device-width, min-device-height or max-device-height`

```css
@media only screen and (min-width: 123px) and (max-width: 456px) {
  ...;
}
```

##### Step 2

Embedding the `<script>` in the `<head>` section of the website:

```html
<script src="https://portal.combeenation.com/plugin/COMPANY/CONFIGURATOR"></script>
```

And the `<iframe>` in the `<body>` wherever the configurator should later be displayed.

```html
<iframe class="cbn-embedded-configurator" frameborder="0" data-cfgrurl="https://portal.combeenation.com/Cfgr/COMPANY/CONFIGURATOR">
</iframe>
```

:::info
The values for COMPANY and CONFIGURATOR need to be exchanged to those of your configurator.
:::

##### Step 3

Next step would be the customizing the `<iframe>` element. It depends on how the configurator is embedded into the website.

Directly into the website:

```css
.cbn-embedded-configurator {
  width: 100vw;
  height: 100vh;
}
```

Standalone page:

```css
.cbn-embedded-configurator {
  width: 100vw;
  height: calc(100vh -NAVHEIGHT);
}
```

The `<iframe>` element provides several attributes which customize the behavior or appearance:

- `class="cbn-embedded-configurator"`... This CSS class is required, because the plugin uses it to identify configurator
- `frameborder="0"` (optional) ... is used to specify whether to display the border around the content
- `allow="clipboard-write"` (optional) … to allow copy-paste from the `<iframe>` page
- `allow="fullscreen"` (optional) … allows the configurator to go fullscreen

##### Step 4

Make sure to test the finished embedded configurator on desktop, tablet and smartphone devices.  
Height of the iframe can vary depending on the used web browser.

### Whitelisted Domains

A Combeenation configurator can be embedded into a limited or unlimited number of websites, depending on your subscription. You can choose these so-called "whitelisted" domains on which your configurator may be used.

Attempting to use the configurator on any other website will result in an error. The domain restriction can be circumvented by crafty users that temper with their browser settings (or use custom browsers), but it will be effective for everyday users. This makes it unappealing for scammers or other malign parties to try and mislead users by embedding your configurator, as it won't work for the broad majority of users.

You can configure the whitelisted domains for your configurator under `Dashboard > Embedding > Whitelist domains`.

:::warning
If your configurator is **already embedded** into several sites and you haven't set any whitelisted domains yet, then **once you add the first domain**, the configurator will be **blocked** on all other sites!

If you are in this situation, prepare a list of all domains beforehand and then enter them all at once to avoid any downtimes.
:::

### Configurator URLs

This section explains the different URLs and how they can be used to open a configurator.  
Each URL starts with `https://portal.combeenation.com/Cfgr` and can end with one of the following:

`/{YourCompany}/{YourConfigurator}` - the default configurator URL which will start a new configuration based on the default preset  
`/{YourCompany}/{YourConfigurator}/{PresetName}` - configurator URL which will start a new configuration based on the given preset  
`/{YourCompany}/{YourConfigurator}/{ConfigurationId}/copy` - URL which starts a new configuration based on a given configuration  
`/{YourCompany}/{YourConfigurator}/{ConfigurationId}/edit/{ConfigurationAuthToken}` - URL which lets the user edit an existing configuration

**Explanation of the substitutes (terms in curly braces {})**

`{YourCompany}` - the reference name for your company on the platform  
`{YourConfigurator}` - the reference name for your configurator  
`{PresetName}` - the id or the name of your preset (see preset view in configurator editor, where you can also set the default preset for your configurator)  
`{ConfigurationId}` - is a unique number which identifies a configuration, will be generated for each new configuration.  
`{ConfigurationAuthToken}` - text which is needed to edit an existing configuration, will be generated for each new configuration.

### External Events

External events allow the **parent page** to signal meaningful occurrences to the configurator. Each event is recorded in the configuration event log and is visible in
[**Cfgn Insights**](../configuration-insights/configuration-insights-.md), making it easy to understand what happened during a configuration session.

#### Sending an event

Use the Combeenation plugin's `sendEventToConfigurator` API on your parent page to dispatch an event:

```js
// parameter #1 type: identifies the event (e.g. error, success, ... - max. 100 characters)
// parameter #2 data: optional – any additional context (max. 40 000 characters)
window.Combeenation.sendEventToConfigurator('error', { code: 503 });
```

Any non-empty string is a valid event type. The type `"error"` carries special meaning: It is treated as a **checkout failure**. All checkout actions of the associated finish are marked as failed, and the configuration is flagged accordingly in Cfgn Insights.

#### Listening on an event

The configurator can listen for external events sent from the parent page and react accordingly. This is useful for responding to user actions or system events that occur outside the configurator.

To listen for events, use the `onParentPageEvent` method in your code:

**API v1 (legacy):**

```js
Cbn.utils.IFrameHelper.onParentPageEvent((type, data) => {
  console.log('Received event:', type, data);

  if (type === 'error') {
    // Handle error event
    const errorData = JSON.parse(data);
    console.error('Checkout failed:', errorData);
  }
});
```

**API v2 (recommended):**

```js
CbnSdk.onParentPageEvent((type, data) => {
  console.log('Received event:', type, data);

  if (type === 'error') {
    // Handle error event
    const errorData = JSON.parse(data);
    console.error('Checkout failed:', errorData);
  }
});
```

---

## Integrations

### Overview

Integrations provide a secure mechanism for communicating with external systems during configuration sessions through the Combeenation server infrastructure. Rather than exposing sensitive credentials (such as authentication tokens) on the client side, this architecture stores secrets securely on the server, with all external API calls being proxied through Combeenation servers.

:::warning
Never persist/store secrets on the client side
:::

### HTTP-Based Integrations

Combeenation supports HTTP-based integrations with multiple authentication methods, including Bearer Token and OAuth 2.0 authentication flows.

#### Configuration Requirements

Each integration requires the following configuration:

- **Unique Name**: An identifier for the integration (later used in CustomCode)
- **Display Name**: A human-readable name
- **Anonymous users access**: Define whether the integration can be used by all users or restricted to authenticated users only
- **Valid Endpoints**: Specify valid endpoint URLs that can be called through this integration, ensuring that only approved endpoints are accessible

#### Bearer Token Authentication

Bearer Token authentication enables standard token-based authentication by automatically including the configured secret in the Authorization header of all outgoing requests.

#### OAuth 2.0 Integration

Combeenation supports OAuth 2.0 authentication using the **Client Credentials flow**. This requires the following configuration:

- **Client ID**: The OAuth client identifier
- **Client Secret**: The OAuth client secret
- **Token Endpoint**: The authorization server's token endpoint URL

**Token Management**: Access tokens are automatically cached on the server to optimize performance and reduce load on the OAuth provider. Tokens are automatically refreshed when they expire, ensuring uninterrupted service.

### Usage in Custom Code

Once an HTTP-based integration has been configured, it can be invoked from custom code using the [`CfgrUtils.executeIntegration()`](https://custom-code.docs.combeenation.com/functions/CfgrUtils.executeIntegration.html) method:

```javascript
import { CfgrUtils } from '@combeenation/custom-code-utils';

const response = await CfgrUtils.executeIntegration({
  integrationName: 'CRM',
  httpMethod: 'GET',
  url: 'https://www.mycrmendpoint.com/api/v1/getAllCustomerData',
  headers: {
    'Content-Type': 'application/json'
  }
});

if (!response.ok) {
  logCrmError(`CRM fetch call failed for endpoint '${urlSegment}'`);
}
```

### Usage in workflows

Just add the integration name to `requestConfig`, for detailed info see [here](./workflows/workflow-in-depth.md#request-config) .

```javascript
export async function run() {
  const requestConfig = {
    integrationName: 'myOauthIntegration'
  };
  try {
    const response = await http.get('myoauthapp.com/v1/products', requestConfig);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
```

---

## Mail settings

By default, Combeenation sends all emails via its own mail server ( `no-reply@combeenation.com` ). If you prefer that your customers do not receive emails through this server, we offer two alternatives:

- **Configure your own SMTP server**  
  Use your own mail infrastructure for full control over email delivery.
- **Define sending domains**  
  Authorize Combeenation’s mail server to send emails using your domains (via SPF/DKIM settings).

#### Affected mails

- Invitation mail
- Mails sent during a configuration or Checkout
- Quote mails
- Quote notification mails
- Test mails on the mail setting dialog

### SMTP settings

Go to your Company settings page → email, activate “Use SMTP settings“ and fill out the fields.

The sender mail address will be used as the FROM address for above mentioned mails. The sender name can optionally be set.

:::warning[Check your connection]
If the connection is misconfigured, users will not receive emails. Use "Send Test Mail" to verify the connection.
:::

#### Common SMTP server

Here is a short list of common used SMTP server, if your company has already a SMTP server contact your admin to get the credentials.

##### 365/Microsoft

Go to [admin.microsoft.com](http://admin.microsoft.com/) select a user with an activate license. Go to the users settings page, select mail and click on “Manage email apps“.

![](<https://docs.combeenation.com/assets/images/image%2883%29-b0f4f8f6a2545e2516ecd24061d21d30.png>)

Authenticated SMTP must be activated.

Afterward go to [https://entra.microsoft.com/#home,](https://entra.microsoft.com/#home,) search for “Named Locations”, click on “Configure multifactor authentication trusted IPs“ and allow the following:

![](<https://docs.combeenation.com/assets/images/image%2884%29-496893b92b4e073997a205701ec72051.png>)

Now go to [myaccount.microsoft.com](http://myaccount.microsoft.com/) → Security info → add new app password. Remember this app password.

Go to the Combeenation portal → company settings → email and set the SMTP settings:

- Server: `smtp.office365.com`
- Port: 587
- Enable SSL: yes
- User: Your full 365 address (z. B. [**you@office365.com**](mailto:you@gmx.de))
- Password: The app password you created earlier

##### Gmail

In order to send mails via Gmail, two factor must be activated, and you have to create an app password, see [here](https://support.google.com/mail/answer/185833).

- Server: `smtp.gmail.com`
- Port: 587 or 465
- Enable SSL: yes
- User: Your full Gmail address (z. B. [**you@gmail.com**](mailto:you@gmx.de))
- Password: App password

For more info see [documentation](https://support.google.com/accounts/answer/185833?hl=de&sjid=10270850237545434877-EU).

##### GMX

You must activate IMAP/POP first, go to settings → email → POP3/IMAP → allow access

- Server: `mail.gmx.net`
- Port: 587
- Enable SSL: yes
- User: Your full GMX address (z. B. [**you@gmx.de**](mailto:you@gmx.de))
- Password: Your mail password

For more info see [documentation](https://hilfe.gmx.net/pop-imap/imap/imap-serverdaten.html).

##### Others

Other possible servers are listed below with their server names and ports. SSL is always enabled, and the port defaults to 587 unless otherwise specified.

- Domainfactory: `sslout.df.eu` (Port: 465)
- Easyname: `smtp.easyname.com` (Port: 465)
- iCloud Mail: `smtp.mail.me.com`
- Jimdo: `secure.emailsrvr.com`
- mail.de: `smtp.mail.de`
- Mittwald: `mail.{yourdomain}.xyz` (Port: 465)
- Outlook: `smtp-mail.outlook.com`
- World4You: `smtp.world4you.com`
- Yahoo: `smtp.mail.yahoo.com`

### Sending domains

Setting up the sending domains is a manual process, you've to set some [DKIM TXT entry](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail) on your domain provider. Since this is currently not fully automated you should [contact us](https://www.combeenation.com/en/contact/).

If you have already sending domains configured, those will be displayed on the Company → email settings page.

---

## Single Sign-On

With Single Sign-on (SSO) you can leverage your existing Identity Provider (IdP) to authenticate users. They do not need to create an account manually and can sign into the Combeenation platform in a similar way to other work-related applications.

Single Sign-on is initially available through Microsoft Entra ID using the OpenID Connect (OIDC) protocol. Support for other identity providers will be added over time, based on customer demand.

### Configure SSO

Single Sign-on can be configured for a company or distributor.

For a company setup, go to **Setting > Single sign-on (SSO)**  
For distributors, go to **Distributors** and choose an existing distributor, then open the **Single sign-on (SSO)** tab.

The remaining configuration steps are identical for companies and distributors.

:::tip
You can assign users of your Identity Provider to different distributors (or the company) by setting up multiple SSO configurations.

You can use the same connection settings and choose which users have access by assigning them different roles in each distributor (`None` meaning that they don’t have access).
:::

### Microsoft Entra ID OIDC

### Step 1: Create an App registration

Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/)

In the navigation menu on the left, expand **Entra ID** and click **App registrations**, then click on **New registration**.

![](<https://docs.combeenation.com/assets/images/image%28102%29-7591537fbcaff07a00a8f2c3359414c2.png>)

1.  Enter a name for your app, such as “Combeenation Platform SSO”
2.  Under **Supported account types** select **Accounts in this organizational directory only (My Directory only - Single tenant)**.
3.  For the **Redirct URI** choose the **Web** option and copy the URI from your Combeenation platform settings page– you find it at the bottom of the settings:![](<https://docs.combeenation.com/assets/images/image%28104%29-aafec86b86e56002890701f6c9d18d7f.png>)
4.  Click **Register** to create the app.

    ![](<https://docs.combeenation.com/assets/images/image%28105%29-1c0d754f6b8b0d48cf0e2180ca1219e5.png>)

### Step 2: Copy the Client ID

Open the **Overview** page and copy the **Application (client) ID**.  
Paste it into the **Client Id** field of the Combeenation SSO settings page.

:::tip[Tip]
You must click on **Save changes** in the Combeenation SSO settings page to apply any changes you make.

You don’t have to do this in each step, but don’t forget it at the end if you don’t!
:::

![](<https://docs.combeenation.com/assets/images/image%28106%29-89526d00847e6c6186885e73753f9265.png>)

### Step 3: Create a Client Secret

Open the **Certificates & secrets** page and click on **New client secret**.  
Enter a description for the secret and **Add**.

![](<https://docs.combeenation.com/assets/images/image%28108%29-be2d127783fef876e52ee7f3f017da9c.png>)

Copy the created secret **Value** and paste it into the **Client Secret** field of the Combeenation SSO settings.

![](<https://docs.combeenation.com/assets/images/image%28109%29-04b28c03151ce97b7ce28b7f7ac56b99.png>)

### Step 4: Copy Authority and Metadata endpoints

Back on the **Overview** page, click on **Endpoints**.  
Copy the **Authority URL (Accounts in this organizational directory only)** and paste it into the **Authority** field of the Combeenation SSO settings.  
Next copy the **OpenID Connect metadata document** URL and paste it into the **Metadata Endpoint** field.

![](<https://docs.combeenation.com/assets/images/image%28110%29-96436e3a4de373a4c4b8df1853b30f31.png>)

![](<https://docs.combeenation.com/assets/images/image%28111%29-ba07e5492a2385e263e5bbeffdac9390.png>)

### Step 5: Configure Token Claims

Open **Token Configuration** and click **Add optional claim**.  
Select **ID** as **Token type** and then select the following claims:

- `email`
- `family_name`
- `given_nam`

Click **Add** and then check the **Turn on the Microsoft Graph email, profile permission (required for claims to appear in token)** option in the pop-up that appears, then confirm again by clicking **Add**.

![](<https://docs.combeenation.com/assets/images/image%28112%29-ed449b4dd3601fad0fa22d98dc3157b1.png>)

### Step 6ː Define App roles (optional)

App roles are required to assign different roles to different users. If all your users should have the same role on the Combeenation platform, you can set that role as default and skip this step.

Go to **App roles** and click on **Create app role** to define a new role.  
In the pop-up that appears enter a **Display Name** and select **Users/Groups** for the **Allowed member types** option.  
Next, enter a **Value** for the role – this value has to be pasted into the Combeenation SSO settings page. It can be the same as the Display name.  
Finally, enter a **Description** for the role and click **Apply.**

![](<https://docs.combeenation.com/assets/images/image%28113%29-ffdcf52d847a82c7fe86a5c894b3aca4.png>)

On the Combeenation SSO settings page, choose a **Default role** for your users. This role will be assigned to users that have not been assigned a (known) App role in Entra.  
If you leave this set to **None**, any users with an unknown App role will not be able to sign in!

Next, click on **Add role** to create a mapping between an Entra App role and a Combeenation role.  
Copy the **Value** of your App role into the **App role** field in the dialog that appears and choose a **CBN role.**

Click on **Save changes** when you are done.

![](<https://docs.combeenation.com/assets/images/image%28114%29-79f8e73cba17ed201ff2978390ba0aaa.png>)

### Step 7: Assign Users and Groups

Back in Entra, click on **Enterprise apps** in the main navigation menu on the left and then open **All applications**.  
Enter the name of your app in the **Search by application name or object ID** box and select it in the list below.

![](<https://docs.combeenation.com/assets/images/image%28115%29-6f69ddd72d28dce689f1fb50ced64aef.png>)

On the Enterprise Application page, go to **Users and groups** and click on **Add user/group**.  
The **Add Assignment** page will open; click on **None Selected** under **Users and groups** and select appropriate users and/or groups.  
Choose a role for your users (provided you created **App Roles** in [step 6](/docs/integrations-and-api/single-sign-on#step-6%CB%90-define-app-roles-optional)) and finally click **Assign** to confirm.

![](<https://docs.combeenation.com/assets/images/image%28116%29-f7cef7e15735474b99b05e4b3d495a91.png>)

### Step 8: Test Single Sign-On

On the Combeenation SSO settings page, click the **Test SSO connection** button at the top

![](<https://docs.combeenation.com/assets/images/image%28117%29-469f9af1335bf1238fcf80cfaeb198f8.png>)

You will be redirected to Entra and asked to grant permissions to your Entra app to access basic user profile data.  
If you are an Entra administrator, you can **Consent on behalf of your organization** so that your users won’t be asked individually for these permissions.

The results of the connection test will be displayed to the right of the **SSO status** area. If there was a problem, you will find details about the error there.

Once the connection test succeeds, click on the **Enable SSO** toggle to active Single-Sign On.  
We **strongly recommend** to also deactivate password logins at this point; to do so, click on the **Deactivate password login** toggle.

![](<https://docs.combeenation.com/assets/images/image%28118%29-5d9060ca5ce02d569175ce5ffdc489eb.png>)

:::tip
If you make any changes to connection-related SSO settings, Single Sign-On will be **automatically deactivated** until you completed another **SSO connection test**.

Password login will be activated automatically to ensure you can still access your account in the meantime (you can request a new password on the login screen if necessary).
:::

:::warning[Disable password login]
Make sure to **disable password login** once SSO has been enabled!

The security and maintenance benefits that Single Sign-On provides are lost when users can bypass SSO with passwords!
:::

---

## Supported Browsers

We validate against and fully support our customers’ use of recent versions of the following browsers:

**Desktop**

- Mozilla Firefox
- Google Chrome
- Apple Safari
- Microsoft Edge

**Mobile**

- Google Chrome
- Apple Safari

These are known as "evergreen" browsers because they automatically update to their latest version. Safari, though not strictly evergreen, is updated along with the OS X operating system. With an average of only 6 weeks between evergreen browser releases, specific version numbers change so rapidly they lose their usefulness. As a result, we test against the latest version of each browser and will provide support for any recent version.

Though other browsers may work, we do not attempt to resolve problems with browsers other than those listed above. Browsers that have been developed to comply with the W3C guidelines and specifications, including mobile browsers, should operate successfully.

### Augmented Reality (AR)

Augmented reality can be experienced on mobile devices with Google Chrome (Google Play Services for AR) or Safari for iOS or iPadOS.

---

## Workflow basics

### Overview

With workflows, it is possible to import data in a customizable way into the Combeenation platform and also send data back to ERP/PIM/shop systems.

![image.png](<https://docs.combeenation.com/assets/images/image%2898%29-9dca3fd5053f57beed87605538aaf195.png>)

Workflows enable Platform users to build configurators in a data-oriented way and keep information up to date on a regular basis.

They are written in JavaScript, and the Combeenation system provides a set of built-in JavaScript functions that allow seamless interaction with [assets](/docs/asset-management/3d-and-material-assets/basic-workflow).

### Benefits of Workflows

- **Flexible data import** into Combeenation:
  - Manual imports
  - Scheduled imports on recurring intervals
  - Automated updates via API calls (push-based)
- **Save time** – product data no longer needs to be maintained manually in Combeenation
- **Two-way integration** – push configuration data back into your systems (ERP, PIM, Shop, …)
- **Data sovereignty** – you always remain in full control of your data; Combeenation only retrieves the required working set
- **Monitoring & logging** – track import operations for transparency
- **Error handling** – get notified immediately if a workflow fails

### Workflow run types

Workflow run types can currently be configured per workflow in the settings page. We currently support the following types:

#### 🖱️Manual

Manual workflows are started by a person via the Combeenation platform and are used to import new data on demand.

#### ⌚Scheduled

Scheduled workflows allow you to run workflows at recurring intervals. You can define specific times and select the days of the week for execution.

#### ⚡Trigger based

##### Configuration finished trigger

Runs a workflow when a configuration is finished.

##### Quote state changed trigger

Runs a workflow when a quote transitions to the specified state.

#### ➡️API (coming soon)

Soon, workflows can also be triggered via a dedicated API. This will allow customers to actively push new data (e.g., prices, articles) into the configurator.

---

## Workflow in depth

This article should give you a detailed introduction into the Workflow system. It will cover basic steps like the creation of a workflow and
guide you from the editing till the final execution of a workflow.

### Create a new workflow

**(A)** Workflows can be created and managed per company.  
**(B)** To create an empty workflow, simply click on the **(+) icon** in the right upper corner.  
**(C)** Select a `Name` and an `ID` is automatically created. The `ID` must be unique and is limited in which characters you may use, it is
used for calling it via the push API. The `Name` has no such restriction, use a good name to identify your workflows later on.

![create-workflow.png](<https://docs.combeenation.com/assets/images/create-workflow%282%29-655099f3bfabc0b6b3c8402382410063.png>)

![select-workflow-name.png](<https://docs.combeenation.com/assets/images/select-workflow-name%283%29-de572f2671f6831647069bbb491a3a9f.png>)

### Run and Editor view

After creating a workflow, no runs are visible yet. To start, click **Edit code** and write your workflow’s JavaScript logic.
The integrated editor provides auto-completion and helps you build a ready-to-use workflow.
Every workflow must export a `function run()` and return
a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
This is a minimal and working `Hello World` example. For more examples,
see [templates](/docs/integrations-and-api/workflows/workflow-templates).

```javascript
// When you define parameters in the workflow config, you can import them here to use them:
// import { YOUR_PARAMETER } from '@workflow/parameters';

/**
 * @param {WorkflowRunArgument} arg
 */
export async function run(arg) {
  // When a workflow starts, it calls the run() function.
  // Every workflow must export one and must return a promise (an async function does this automatically)!

  // !!! visit our docs for a number of example workflows to get started !!!
  // https://docs.combeenation.com/docs/workflow-templates

  // In most cases, you'll call at least one API function, which returns a promise that you must await.
  return 'Hello, world!';
}
```

After completing your workflow, click Execute to run and test it. Finished runs appear in the run overview, where you can select a run to
view details (see [the next section](/docs/integrations-and-api/workflows/workflow-in-depth#log)).

### Log

As mentioned earlier, each workflow run generates a log. This log helps you understand what happens during workflow execution. Some entries
are automatically created by Combeenation, but the Platform user can also add custom log messages using the following JavaScript functions:

- `console.debug()`
- `console.info()`
- `console.log()`
- `console.warn()`
- `console.error()`
- `console.group()`
- `console.endGroup()`

A log output always contains a UTC time stamp and a corresponding message. An example log output can be seen here:

![workflow-log.png](<https://docs.combeenation.com/assets/images/workflow-log%283%29-73c7e95f7cd0c21cb30d93151e247410.png>)

### Configuration

To configure a workflow simply click on **Edit config** where it is possible to configure its display name, an optional scheduled execution
and all required [parameters](/docs/integrations-and-api/workflows/workflow-in-depth#parameters).

![workflow-config.png](<https://docs.combeenation.com/assets/images/workflow-config%284%29-a70a35b8449e4ca402df18fe0724dee6.png>)

#### Scheduled execution

Workflows can be executed manually within the Combeenation platform or scheduled to run at recurring intervals. To enable scheduling, click
**Add scheduling** and set the desired interval. Once saved, the next execution is scheduled immediately and will run at the defined time.

![schedule-config.png](<https://docs.combeenation.com/assets/images/schedule-config%283%29-89287b37d37409247c5aa270cc134466.png>)

:::info
The minimal allowed timespan between each workflow runs is **1 hour**.  
All entered values are in UTC time.
:::

#### Triggers

You can also execute workflows based on triggers. Currently, two trigger types are supported:

- Configuration finished trigger – Executes when a configuration is finished.
- Quote state change trigger – Executes when a quote changes to a specified state. Multiple triggers can be defined per quote hub (e.g.,
  perform one action when a quote is won and another when it is lost).

Depending on the trigger type, the `run` function receives a workflow argument containing trigger-specific data (e.g., the configuration
finished trigger provides the configuration, while the quote state change trigger provides quote data).
See [this example](/docs/integrations-and-api/workflows/workflow-templates#workflow-triggers) to learn how to access this data.

#### Notifications

With the help of notifications, it's possible to get notified whenever a workflow fails.  
At the time of writing, we support two different formats, Emails and Webhooks described below.

![workflow-notifications.png](https://docs.combeenation.com/assets/images/workflow-notifications-d720e978381e9b84b6b5783576a9df8c.png)

##### Email

Simply add your Email address and get notified.

![workflow-run-mail-notification.png](https://docs.combeenation.com/assets/images/workflow-run-mail-notification-733bc2db81d68dbc5d76799150685e86.png)

##### Webhook

A Webhook is typically used to connect two different applications and enables sending events over the web through an API.  
This type of notification is based on HTTP and sends POST calls to your URI.

**a) Raw**  
If you select "Raw", we send the following plain JSON to the given URI.  
As you can see, we provide the `CompanyName` , the `WorkflowName` and the `WorkflowRunLink` of the failed workflow.

```json
{
  "CompanyName": "Asset Company",
  "WorkflowName": "My Workflow",
  "WorkflowRunLink": "https://portal.combeenation.com/..."
}
```

**b) Slack**  
In addition, we support the official standard to send notifications to a given Slack channel.  
As mentioned [here](https://api.slack.com/messaging/webhooks), Slack webhooks are a way to post messages from apps directly into Slack.
Simply add your Slack webhook URI into the given field, and we will send a Slack message into your channel.

![workflow-run-slack-notification.png](https://docs.combeenation.com/assets/images/workflow-run-slack-notification-8f4524f07354023feceb68167e207492.png)

#### Parameters

You can use a maximum number of 20 parameters to pass information into your workflow. Each parameter must have its own unique name and must
contain a valid default value.  
All different types of parameters can be added with the **Add parameter** button and can be imported into the workflow code as shown below.

```javascript
import { isEnabled, count, articleName, bundle, file } from '@workflow/parameters';
```

As a result, the defined parameters are automatically loaded into the workflow run.

##### a) Bool

- `Name` ... unique name of the parameter
- `Default value` ... default value of the parameter  
  ![bool-parameter.png](<https://docs.combeenation.com/assets/images/bool-parameter%282%29-412a124626888375057fa3881c69849d.png>)

##### b) Number

- `Name` ... unique name of the parameter
- `Default value` ... default value of the parameter  
  ![number-parameter.png](<img/workflow-in-depth/number-parameter(1).png>)

##### c) String

- `Name` ... unique name of the parameter
- `Default value` ... default value of the parameter  
  ![string-parameter.png](img/workflow-in-depth/string-parameter.png)

##### d) Asset Bundle

You can use this parameter to make changes to an asset bundle, publish it and also publish configurators that use it. Choose an asset bundle
that is assigned to a specific configurator.

:::info
The workflow will always use the **asset bundle version which is used by the configurator**.  
Updating asset bundles via workflows is only supported for published configurators.
:::

- `Name` ... unique name of the parameter
- `Configurator` ... select the configurator which should be used
- `Bundle` ... select the asset bundle from `Configurator`  
  ![asset-bundle-parameter.png](https://docs.combeenation.com/assets/images/asset-bundle-parameter-0b9b113936e114407d82f7fc0a0b6263.png)

##### e) File

- `Name` ... unique name of the parameter
- `Url` ... public URL where the file (i.e. data) is downloaded
- `Authorization scheme` ... (
  optional) [authorization scheme](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#authentication_schemes)
- `Authorization parameter` ... (optional) authorization parameter
- `Fallback content type` ... (optional) fallback content type

:::info
Some URLs are not available publicly, they can only be accessed if certain authorization credentials are provided.  
The `Authorization scheme` and `Authorization parameter` settings map directly to the corresponding HTTP headers.

The **Basic** authentication scheme is frequently used by APIs that utilize API tokens or user/password credentials.  
To set it up, enter `Basic` in the `Authorization scheme` textbox.  
The value for `Authorization parameter` must be a Base64-encoded string of the form `user:password` (_sometimes an API key is used instead
of user information – consult your API's documentation for details_).
:::

![file-parameter.png](<https://docs.combeenation.com/assets/images/file-parameter%283%29-de8b10e1739a1d090e1773daee15ab82.png>)

### HTTP

With the `http` keyword it is possible to perform various HTTP requests.  
You can perform `get`, `post`, `put`, `patch`, `head`, `options` and `delete` requests.

#### Request config

You can configure your requests with the following **optional** request configuration.

```javascript
/** @type {HttpRequestConfig} */
const requestConfig = {
  // (optional) baseUrl which will be prepended to the url
  // It can be convenient to set baseUrl to pass relative URLs.
  baseUrl: 'https://some-domain.com/api',

  // (optional) custom headers to be sent which overwrite any header values from a basicAuth config or
  // from the provided integration with given integrationName
  headers: { 'X-Requested-With': 'XMLHttpRequest' },

  // (optional) timeout in seconds
  timeout: 5,

  // (optional) name of the integration defined for the current company.
  integrationName: 'MyIntegration',

  // If this optional config is set, it indicates that HTTP basic auth should be used, and supplies credentials.
  // This will set an Authorization header, please note that only HTTP basic auth is supported.
  // For Bearer tokens and such, use Authorization custom headers or an integration instead.
  basicAuth: {
    username: 'janedoe',
    password: 's00pers3cret'
  }
};
```

#### Response

Every request returns the following generic response and gives you insights about the success of your request.

```javascript
/** @type {HttpResponse} */
const response = {
  // `data` is the response that was provided by the server
  // can be undefined in the error object
  data: {},

  // `status` is the HTTP status code from the server response.
  status: 200,

  // `headers` the HTTP headers that the server responded with.
  // All header names are lower cased and can be accessed using the bracket notation.
  // Example: `response.headers['content-type']`
  headers: {}
};
```

With the following code, you can print all values of a response:

```javascript
/**
 * @param {HttpResponse} response
 */
function printResponse(response) {
  console.log('Status-Code: ' + response.status);

  console.group('Start printing headers...');
  for (const key in response.headers) {
    console.log(`${key}: ${response.headers[key][0]}`);
  }
  console.groupEnd('Printing headers finished.');

  if (response.data !== undefined) {
    // `url` returns the URL of the retrieved data
    console.log('Data URL: ' + response.data.url);
    // `raw` string is only defined, if data is smaller than 1MB
    console.log('Data Raw: ' + response.data.raw);
  }
}
```

#### Errors

If any error occured, a specialized error can be caught and processed in the returned promise. The error object has the following format:

```javascript
/** @type {HttpError} */
const error = {
  // can be undefined if no response was received, e.g. timeout
  response: {},

  // URL of the request
  url: '',

  // error message which describes the error
  message: ''
};
```

With the following code, you can print all values of an error object:

```javascript
/**
 * @param {HttpError} error
 */
function printError(error) {
  console.error('Error occured: ' + error);
  console.debug('Url: ' + error.url);
  console.debug('Message: ' + error.message);
  console.group('Start printing error response');
  printResponse(error.response);
  console.groupEnd();
}
```

#### Examples

All subsequent examples use the previously documented optional `requestConfig` and the `printResponse` and `printError` methods.

##### get

```javascript
export async function run() {
  try {
    const response = await http.get(url, requestConfig);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
```

##### post, put and patch

The following template can be used with post, put or patch requests mentioned requests.

:::info
The HTTP request body must be provided as a string.
:::

```javascript
export async function run() {
  const content = {
    text: 'HTTP request content of a workflow'
  };

  try {
    const response = await http.post(url, JSON.stringify(content));
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
```

##### head, options and delete

The following template can be used with the head, options and delete requests.

```javascript
export async function run() {
  try {
    const response = await http.head(url, requestConfig);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
```

### Data instances

With `Data.fromJson()` a data instance can be created from a JavaScript (JSON) object. The returned instance provides the `raw` content and a `url`, and can be used to update a file asset.

#### Example

```javascript
export async function run() {
  const myData = await Data.fromJson({
    id: 21,
    title: 'Cucumber',
    category: 'groceries',
    price: 1.49,
    stock: 22,
    tags: ['vegetables', 'onsale'],
    reviews: [
      { rating: 4, comment: 'Very satisfied!', reviewerName: 'Elijah Hill' },
      { rating: 5, comment: 'Fast shipping!', reviewerName: 'Liam Garcia' }
    ]
  });

  console.log(myData.raw);
  console.log(myData.url);

  // write the data into a file asset of an asset bundle draft
  const bundleDraft = await BundleLin.createDraft();
  const fileAsset = bundleDraft.getAsset('jsondata', 'files');
  fileAsset.update(myData);
}
```

### Quotes

With the `quotes` keyword it's possible to load, change and publish any quote using the given hub name and quote number.

#### Example

```javascript
export async function run() {
  const hubName = 'HUB';
  const quoteNumber = 'A2026200';
  try {
    const quote = await quotes.get(hubName, quoteNumber);

    // quote.data can be used to retrieve properties from a quote
    const quoteData = quote.data;
    console.log(quoteData.hubName);
    console.log(quoteData.quoteNumber);

    // get the link to a pdf asset
    const linkToQuotePdf = await quote.createPdf('myPdfAssetPath');

    // change and publish a quote
    quoteData.state = 'won';
    await quote.publish();
  } catch (error) {
    printError(error);
  }
}
```

### Mail

With the `mail` keyword it's possible to send emails directly from workflows.
You can send to single or multiple recipients and include file attachments by URL.

Mail tenant settings will be used, if no distributor name is provided we use the mail settings from the main company.

Limits: There is a hard limit of max. 10 mails to be send during a workflow run.

#### Example: send a mail with a PDF attachment

```javascript
export async function run() {
  await mail.send({
    sender: 'noreply@example.com',
    to: 'recipient@example.com',
    subject: 'Your Quote is ready',
    body: 'Please find the attached Quote.',
    attachments: [
      {
        filename: 'report.pdf',
        url: 'https://example.blob.core.windows.net/files/report.pdf',
        mediaType: 'application/pdf'
      }
    ]
  });
}
```

For a more detailed example see [here](./workflow-templates.md#send-quote-mail-upon-quote-change-trigger).

---

## Workflow templates

### Bare minimum

The following template shows the minimum required code to execute a workflow.

```javascript
export async function run() {
  console.log('Hello World');
  return true;
}
```

### Parameters

This template combines all different kind of parameters and console outputs.

```javascript
import { isEnabled, count, articleName, bundle, file } from '@workflow/parameters';

export async function run() {
  try {
    console.group();
    console.debug('Print all parameters...');
    console.info('isEnabled: ' + isEnabled);
    console.log('count: ' + count);
    console.warn('articleName: ' + articleName);
    console.debug('bundle: ' + bundle);
    console.info('file: ' + file);
    console.groupEnd();
  } catch (e) {
    console.error('Unexpected error: ' + e);
  }
  return true;
}
```

### Update assets

It is possible to update file or datasource assets within a workflow.

:::info
If a file asset is linked to data sources, then all data sources are also updated automatically.
:::

The update of a datasource and a subsequent publish of the corresponding asset bundle is shown in this template.  
Following steps are performed:

1.  create a new asset bundle draft
2.  get an existing data source
3.  update the data source
4.  publish the asset bundle
5.  update related configurators

```javascript
import { bundle, file } from '@workflow/parameters';

// ATTENTION: NEVER forget to await asynchronous calls
export async function run() {
  // 1. create a new asset bundle draft based on the asset bundle parameter
  const draft = await bundle.createDraft();

  // 2. get the data source asset which should be updated
  const dataSourceName = 'articles';
  const folderName = 'data';
  const dataSourceAsset = draft.getAsset(dataSourceName, folderName);

  // 3. update the data source asset
  await dataSourceAsset.update(file);

  // 4. publish the asset bundle draft
  await draft.publish(configurator => {
    // In this block you can decide what should happen to each configurator (or draft) which is using this asset bundle version
    // you have to return an object with the following format: { update: true|false, publish: true|false } for each configurator

    // 5.a) We can, for instance, choose to update but not publish a specific configurator.
    // the 'configurator' argument contains details about the current configurator, such as its name or version, or whether it is a draft
    if (configurator.name === 'MyOtherConfigurator') {
      return { update: true, publish: false };
    }

    // 5.b) We can also return a bool value as a shorthand; returning 'true' is the same as returning { update: true, publish: true }
    return true;
  });
}
```

### Workflow triggers

As mentioned [here](/docs/integrations-and-api/workflows/workflow-in-depth#triggers) the workflow run argument provides different data depending on the trigger type. This is shown in the example below.
Quote and configuration data properties may change in the future—please contact us if you require additional properties.

```javascript
/**
 * @param {WorkflowRunArgument} arg
 */
export async function run(arg) {
  // Argument always contains the workflow run type
  console.debug('Trigger Type: ' + arg.type); // manual, scheduled, api, finishCfgn, ...

  // check for the type to see which trigger started the workflow run
  if (arg.type == 'manual') {
    console.debug('A manual run triggered by a user - no additional information available');
  } else if (arg.type == 'scheduled') {
    console.debug('A scheduled run - no additional information available');
  } else if (arg.type == 'api') {
    console.debug('An api call - not supported currently, will be released soon');
  } else if (arg.type == 'finishCfgn') {
    // triggered when a configuration is finished

    arg.configurator; // name of the configurator
    arg.stage; // stage name of the configurator
    var cfgnJson = JSON.parse(arg.configuration.raw); // configuration data needs to parsed to be process in the workflow
    console.debug('configuration (id): ' + cfgnJson.id);
    console.debug('configuration (cfgr name): ' + cfgnJson.cfgrName);
    console.debug('configuration (created at): ' + cfgnJson.createdAt);
  } else if (arg.type == 'quoteStateChanged') {
    // triggered when the state of a quote is changed

    // arg.quote.data can be used to retrieve a quote within the workflow
    var quoteData = arg.quote.data;
    console.log(quoteData.hubName);
    console.log(quoteData.quoteNumber);
    console.debug('quote (items): ' + quoteData.items.length);
    quoteData.items.forEach(item => {
      if (item.type === 'Item') {
        console.log(' * ' + item.quantity + item.unit + " '" + item.name + "' - " + item.netUnitPriceFinal + quoteData.currency);
      } else if (item.type === 'Section') {
        console.log(" * Section '" + item.name + "'");
      } else {
        console.log('Unknown type:', item.type);
      }
    });

    // change and publish a quote
    quoteData.state = 'processing';
    return await arg.quote.publish();
  } else {
    console.debug('Unkown workflow run type');
  }
  return true;
}
```

### Send quote mail upon quote change trigger

```javascript
/**
 * @param {WorkflowRunArgument} arg
 */
export async function run(arg) {
  if (arg.type == 'quoteStateChanged') {
    // first create the quote pdf for this quote with the desired pdfTemplate
    const quotePdfUrl = await arg.quote.createPdf('pdfTemplatePath');

    // after the quote pdf has been created send a mail
    await mail.send({
      sender: 'noreply@example.com',
      to: 'recipient@example.com',
      subject: 'Your Quote is ready',
      body: 'Please find the attached Quote.',
      attachments: [
        {
          filename: 'Quote.pdf',
          url: quotePdfUrl,
          mediaType: 'application/pdf'
        }
      ]
    });
  } else {
    console.debug('Nothing to do');
  }
}
```

---

## Getting started on the platform

### Account

In order to get started on the [Combeenation platform](http://portal.combeenation.com/), you need an account and a company. A company is the central hub for configurators, collaborative users, assets and other essential components. There are currently two options to achieve this:

- [Create a new company](#create-a-new-company)
- [Join an existing company](#join-an-existing-company)

#### Create a new company

If you are the business owner, you probably choose this option. Visit the [registration page](https://portal.combeenation.com/register) and create a new account, including the company. As you register, we generate a company id suggestion based on your company display name.

##### Unique company id

The company id must be unique on the Combeenation platform and has the following limitations:

- 30 characters maximum
- Only alphanumeric characters and numbers allowed
- Must start with an alphanumeric character

This id will be used to generate configurator links (e.g. [portal.combeenation.com/cfgr/YOURCOMPANYNAME/YOURCFGRNAME](http://portal.combeenation.com/cfgr/YOURCOMPANYNAME/YOURCFGRNAME)) and is also vital if used with our API.

:::info[Choose Wisely]
Select a concise and meaningful name for your company, adhering to the specified limitations.
:::

#### Join an existing company

If there's an existing company on the Combeenation platform where you wish to collaborate, simply request an invitation from the company admin. Once you receive the invite link, you can create your account.

### Platform overview

As soon as you have created or joined a company, you are able to navigate through the platform.

#### Companies

In the left sidebar, you can see a list of all companies you are assigned to. If there is only one company you have access to, the company menu will be collapsed by default. By clicking on your company or pressing **CTRL + K** you can expand this menu and search/visit another companies.

#### Configurators

Below the company selector you can see the configurator section. If there is at least one configurator in this company, it will be selected by default. By selecting a configurator, you get to see the configuration metrics, which represent the statistics of the configurations of a configurator.

A configurator can be published or withdrawn. Published configurators can be embedded on your system (see [Embedding & Whitelist](/docs/integrations-and-api/embedding-and-whitelist)).

Each configurator can have up to 10 drafts, can be found on the drafts page. For more information on how to create and edit a configurator see [Creating a configurator](/docs/fundamentals/creating-a-configurator).

In the drafts page, you see all drafts for the selected configurator, where you can edit or preview your configurator. The embedding section shows information about how your configurator can be embedded in your own page. In addition, there are several configurator related settings e.g. whitelist domains, sending domains.

#### **Assets**

Each configurator requires assets like image, data, 3D models, textures, materials, ...  
Those assets can be managed inside the asset editor (found on the lower left sidebar).

Before uploading an asset, an asset bundle needs to be created. This asset bundle is versioned, and each version can be assigned to a configurator.  
Inside an asset bundle, the assets can be grouped together in folders (folders can't be nested).  
For more information, see [Getting started with assets](/docs/asset-management/getting-started-with-assets).

#### **Workflows**

:::info[Pricing tier dependent]
Depending on your pricing tier, this may not be visible at the moment.
:::

With workflows, it is possible to import data in a customizable way into the Combeenation platform.

It allows the platform user to build configurators in a more data-oriented way and update the data on a regular basis.Workflows are written in JavaScript, and the Combeenation system provides a set of JavaScript functions which allow the interaction with assets.

For more information see [Workflow basics](/docs/integrations-and-api/workflows/workflow-basics)

#### Users

Also found in the lower left sidebar is the user management for each company. A company can have multiple users and each user has a defined role in the company. Each role provides a different set of permissions, for more info see [User Permissions](/docs/fundamentals/user-permissions).

New users can get access to a company by sending an invitation. The invite dialog can be found in the upper right corner of the user screen. You can either enter the mail address of the inviting user directly and a mail with the link will be sent, or just create an invitation link and send it over your preferred messenger.

#### **Settings**

Within this menu, you can configure your company settings like address, subscription and api tokens.

#### **Export**

:::info[Pricing tier dependent]
Depending on your pricing tier, this may not be visible at the moment
:::

The last feature in the sidebar is the export. It allows you to export configurators and asset bundles to different companies.

---

## Customize the quote UI

With the use of Widget Assets it's possible to customize parts of the Quotes page.
It can be used to rearrange the whole details layout, hide and show fields (predefined or [Custom fields](/docs/fundamentals/custom-fields)), change plain text to a Richtext editor and more.

:::info
Admin rights are required to modify the asset or assign it to quotes.
:::

### Basic setup

#### Create a Widget Asset

1. Navigate to an asset bundle in the asset editor
   - Quote widgets and quote pdfs must be in the same bundle!
2. Create a new "Widget Asset" of type "Quote"
   - The widget will be created with the default layout
3. Publish the bundle

#### Assign to an existing quote

To update the UI of a single quote the following steps are necessary:

1. Navigate to any quote and start the edit mode
2. Open the settings dialog (Gear icon at the top right)
3. Select the according bundle, version and widget
4. After confirming your changes the quote will be displayed with your custom UI

#### Assign widget at configuration finish

To use the widget for new quotes (with our without lead):

1. Ensure to have a working configurator with a working [quote or lead setup](https://docs.combeenation.com/docs/category/quote-management)
2. Open a new draft of the configurator
3. Assign the according Asset bundle in the `Assets` workspace
4. Navigate to the `Finish` configuration which creates the lead or quote
5. At the top-level of the definition add the following properties
   - `assetBundleName: "YourBundleName"`
   - `widgetAssetPath: "AssetName"` or `widgetAssetPath: "YourFolder.AssetName"`
6. Afterwards every newly created Quote will use this widget asset

### Editing the asset

The whole configuration has an underlying JSON schema. Inside the asset editor there are helpful inline suggestions and a validation with
additional hints when hovering over the warnings.

All controls share the `$type` property. After entering the wanted type in the editor, it will suggest all possible properties for this control.
To get a **list of all possible controls** check out the info-field "Available UI controls" directly at the top-right of the Widget asset editor.

:::info
The `$type` doesn't always suggest all possible values. The available options are narrowed down based on the other properties present in the object.
For example, in an empty object, only controls that do not require any additional properties are suggested for the `$type` property. If the object already contains the key `property`, only controls that support that property are suggested.
:::

#### Box & Accordion

The main building block of the layout is the `Box` which can be compared to a `div` in HTML.
By default it uses the `flex` layout and can be customized with CSS styles (e.g. to add `gap` or change to a `grid` layout).
The `children` property can then be used to build nested layouts.

The `Accordion` is similar to the `Box` but comes with a fixed header (and property `title`) that lets the children collapse/expand.

**Example: Use `Box` with grid-layout**

```json
{
  "$type": "Box",
  "style": {
    "display": "grid",
    "gridTemplateColumns": "auto 1fr auto",
    "gap": 150
  },
  "children": []
}
```

:::info[Avoid visual customizations]
Although the style property is not restricted, we recommend using it primarily for layout and avoiding styling such as backgrounds or similar customizations,
as it might clash with the platform styling or themes in the future.
:::

#### Accessing fields

> Controls ending with "...Field"

There are several control types to display and edit the quote fields in different ways.
The default widget asset (when creating a new one) contains most of the default fields and should be a good starting point to learn about
their usage.

##### Examples

Field type **Text**: Can be edited as normal text input, multiline or richtext.

```json
[
  {
    "property": "notes",
    "$type": "TextField"
  },
  {
    "property": "notes",
    "$type": "TextField",
    "multiline": true
  },
  {
    "property": "notes",
    "$type": "RichtextField"
  }
]
```

Field type **Number**: Can be used as number input or for date selection (stored as Unix timestamp).

```json
[
  {
    "$type": "NumberField",
    "property": "fields.customQuoteDate"
  },
  {
    "$type": "DateField",
    "property": "fields.customQuoteDate"
  }
]
```

#### Item table

The item table control can be customized in the following ways:

- Columns: Change the default order, remove columns, add custom fields as columns
- Expandable detail section: Can be customized with the same building blocks like `Box`, `TextField`, etc.
  - Comes with a different subset of controls and field properties as they are based on the line items

Because line items have their own type and fields, they also have to be configured individually.

```json
{
  "$type": "ItemTable",
  "itemDetails": [],
  "discountDetails": [],
  "markupDetails": []
}
```

<details>
<summary>Columns - Default</summary>
```json
[
  { "property": "posText" },
  { "property": "name" },
  { "property": "quantity" },
  { "property": "priceNet" },
  { "property": "discount" },
  { "property": "margin" },
  { "property": "finalNet" }
]
```
</details>

<details>
<summary>Item Details - Default</summary>
```json
{
  "$type": "Box",
  "horizontal": true,
  "style": {
    "padding": "1rem 5rem",
    "alignItems": "start",
    "gap": 12
  },
  "children": [
    {
      "$type": "Box",
      "style": {
        "display": "grid",
        "gridTemplateColumns": "minmax(0,200px) minmax(0,400px)",
        "alignItems": "center",
        "rowGap": 8,
        "columnGap": 4
      },
      "children": [
        {
          "$type": "Box",
          "style": {
            "gridColumn": "span 2 / span 2"
          },
          "children": [
            {
              "$type": "RichtextField",
              "property": "description"
            }
          ]
        },
        {
          "$type": "Label",
          "text": "$optional",
          "variant": "small"
        },
        {
          "$type": "BoolField",
          "property": "isOptional",
          "showAsSwitch": true
        },
        {
          "$type": "Label",
          "text": "$tax",
          "variant": "small"
        },
        {
          "$type": "NumberField",
          "property": "tax"
        },
        {
          "$type": "Label",
          "text": "$sku",
          "variant": "small"
        },
        {
          "$type": "TextField",
          "property": "sku"
        },
        {
          "$type": "CustomFieldsList"
        }
      ]
    },
    {
      "$type": "Image",
      "style": {
        "maxHeight": 200,
        "maxWidth": 200
      }
    }
  ]
}
```
</details>

<details>
<summary>Discount & Markup details - Default</summary>
```json
{
  "$type": "Box",
  "horizontal": true,
  "style": {
    "padding": "1rem 5rem",
    "gap": 12
  },
  "children": [
    {
      "$type": "Box",
      "style": {
        "display": "grid",
        "gridTemplateColumns": "minmax(0,200px) minmax(0,400px)",
        "alignItems": "center",
        "rowGap": 8,
        "columnGap": 4
      },
      "children": [
        {
          "$type": "CustomFieldsList"
        }
      ]
    }
  ]
}
```
</details>

### Control properties

:::info
Please note that this is not a complete list of all properties.
When creating a control, refer to the suggestions and validation hints provided directly in the editor for the most up-to-date information.
:::

| Property        | Type   | Description                                                                                                                                                                                                                                                                                                                                              |
| --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| hideInDraft     | Bool   | When the quote is in the edit state, it will not display this control. Available for all controls and also hides children, if existent.                                                                                                                                                                                                                  |
| hideInPublished | Bool   | Counterpart of `hideInDraft`. This property is only available for specific controls, as using it more broadly could unintentionally hide content. For example, a user without the required permissions may never be able to enter the edit state and therefore would never see the value.                                                                |
| style           | Object | Directly apply CSS styles on the control. The keys must be written in camelCase instead of kebap-case. E.g.: `grid-template-columns -> gridTemplateColumns`                                                                                                                                                                                              |
| styleDraft      | Object | Identical to `style` but will only be applied when the quote is in a draft state. If a `style` property is existent it will fully replace it without merging or similar.                                                                                                                                                                                 |
| label           | String | Acts as label and placeholder for the control when in a quote draft (a11y). In a published state it won't be shown, as a `<label>` would be technically invalid and adding a normal text would limit layouting flexibility. Instead, add an independent control of type `Label` which automatically results in a `label` or `span` based on the context. |
| htmlId & for    | String | If the `label` property of an editable control isn't used or not available, it's highly recommended to add a `htmlId` and connect it to a control of type `Label` with the `for` property.                                                                                                                                                               |

### Internationalization (i18n)

Translations are defined in the `i18n` section of the configuration.
The default widget already contains several translations, which can be modified as needed.
It's only possible to translate texts which are used inside this widget asset
(e.g. field values or rules from the configuration can't be translated right now).

To use a translated string in the widget configuration, prefix the translation key with `$`.

```json
{
  "title": "$contact"
}
```

The value `$contact` tells the application to look up the `contact` key in the `i18n` section.

- If a translation is missing, it will directly display the string `$contact` in the UI.
- If only one language is defined, it will always use this one
  - For example, if only `de` is defined it will always fall back to it, regardless of the selected platform language

**Example**

```json
{
  "main": [
    {
      "title": "$contact",
      "$type": "Accordion"
    }
  ],
  "i18n": {
    "en": {
      "contact": "Contact"
    },
    "de": {
      "contact": "Kontakt"
    }
  }
}
```

### Text & value templating (LiquidJS)

For texts and some specific values it's also possible to use liquid templates.
Please see the [official docs](https://liquidjs.com/) for a full list of all templating capabilties.

#### Data context

All the data which is also available for the [field-controls](#accessing-fields) can be accessed.

- `{{ customer.street }}`
- `{{ company.bankDetails.iban }}`
- `{{ notes }}`
- `{{ fields.myCustomText }}`
- ...

##### Additional data

Besides quote-specific data, the following values are also available:

| Key                 | Possible values |
| ------------------- | --------------- |
| `platform.language` | `en` / `de`     |

These values might be extended in the future. Feel free to contact us, in case of new requirements.

#### Examples

Static text with default fields:\
`"text": "Your company name is {{ company.name }}"`

Custom field with condition:\
`"text": "{% if fields.externalId.length == 0 %} Missing ID! {% endif %}"`

Print all fields as json (for debugging purposes):\
`"text": "{{ fields | json }}"`

##### Button with dynamic url

It's also possible to build custom urls with liquid.
This can either be achieved by building the whole url or only specific url parameters.

Pass on url parameter with current platform language (in uppercase):

```json
{
  "$type": "Button",
  "text": "$view",
  "onClick": {
    "action": "ViewConfiguration",
    "urlParams": {
      "lang": "{{ platform.language | upcase }}"
    }
  }
}
```

Custom link with dynamic path, url-param and condition:

```json
{
  "$type": "Button",
  "text": "Open",
  "onClick": {
    "action": "CustomLink",
    "url": "https://www.google.at/{{quoteNumber}}",
    "urlParams": {
      "ref": "{{ fields.refId }}",
      "isInternal": "{% if fields.isInternal and fields.refId.length > 0 %} true {% else %} false {% endif %}"
    }
  },
},
```

---

## Getting started with quotes

Quotes can be created during finishing a configuration. A finish completes a configuration and avoids unintentional modification.
As described in [Checkout](/docs/integrations-and-api/checkout), we support a broad variety of checkout options.
In addition to these options, it’s possible to create quotes which can be managed in a dedicated quotes overview including
price calculation, state management, mail notifications, quote PDF creation etc.

### Quote Hubs

Every quote is created in a dedicated Quote Hub which is defined during the checkout process. This means a quote hub combines quotes from various configurators of your company. All quotes within the same quote hub are managed consistently. For example, they share a unified ascending numbering system or use a pre-defined quote PDF per default. In order to be able to create quotes, you have to fully set-up a quote hub for your company (distributor).

#### Number sequence

When a quote is created during the checkout, then we assign a unique quote number to it which cannot be changed afterwards. This quote number can be used for the customer communication and uniquely identifies a quote within the same quote hub. It’s ensure that two quotes do **never** have the same quote number at any circumstances. The format of this number can only be defined until the first quote has been created, because otherwise a subsequent change of the quote format could result in conflicts with existing quotes.

#### States

A quote can be in different states which describe the current progress and status:

- Request
- Processing
- Sent
- Lost
- Canceled
- Won

### Quote PDF

To enable the creation of a quote PDF, it’s required to specify the PDF asset which should be used.
This PDF asset must be located in a published asset bundle.
You can use a pre-defined quote template during the creation of the [PDF asset](/docs/asset-management/pdf-asset#how-to-create-a-pdf-asset).
After a quote has been published, it’s possible to create a PDF summarizing all details of the quote.
The [context](/docs/asset-management/pdf-asset) of every PDF is provided via the [Quote JSON](/docs/quote-management/getting-started-with-quotes#quote-json) and is applied to the PDF.
With this, it's possible to enrich every quote PDF with data.

### Quote JSON

The following data representation format is used for several use cases:

1. It represents the data usable as context in the [quote PDF](/docs/quote-management/getting-started-with-quotes#quote-pdf) mentioned above.
2. This data format is also used in [workflows](/docs/integrations-and-api/workflows/workflow-in-depth#quotes).
   For example, it can be used to access quote data when the state of a quote has been changed.
3. In addition, it's also possible to define a [custom format](/docs/quote-management/how-to-find-quotes#settings) of the quote PDF file name via accessing properties of a quote.

```json
{
  "finish": {
    "output": {
      "myImageName": "",
      "myImageUrl": "",
      "myFile": ""
    }
  },
  "hubName": "HUB",
  "quoteNumber": "A20260214",
  "version": "V1",
  "state": "request",
  "subject": "My subject",
  "projectId": "project 1",
  "assignee": {
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "john.doe@mail.com",
    "fields": { "Age": 20, "Discount": 5, "DiscountString": "company-user-discount" }
  },
  "currency": "EUR",
  "taxRule": "RevealSalesTax",
  "notes": "Notes text",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "My Customer",
    "addressLine1": "AddressLine1",
    "addressLine2": "AddressLine2",
    "city": "City",
    "street": "Street",
    "postalCode": "PostalCode",
    "country": "Country",
    "emailAddress": "john.doe@mail.com",
    "phoneNumber": "+43 1 1234567"
  },
  "company": {
    "name": "My company",
    "city": "Neufelden",
    "street": "Linzerstraße 4",
    "postalCode": "4120",
    "country": "Österreich",
    "emailAddress": "my.company@service.com",
    "phoneNumber": "+43 1 1234567",
    "imageUrl": "https://picsum.photos/id/2/200",
    "taxId": "ATU23423",
    "bankDetails": {
      "accountHolderName": "Acme",
      "accountNumber": "324234",
      "bankName": "Sparkasse",
      "swift": "BC3234",
      "bic": "BC3234",
      "iban": "AT32304203402340"
    }
  },
  "shipping": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "My Shipping Company GmbH",
    "city": "Neufelden",
    "street": "Linzerstraße 45",
    "postalCode": "3234",
    "country": "Österreich",
    "emailAddress": "john.doe@mail.com",
    "phoneNumber": "+43 1 12345678"
  },
  "quoteDate": 1775113431,
  "discounts": [
    { "id": "0GBzmPASi92", "name": "Customer Discount", "value": 300, "valueType": "Absolute", "net": -300, "gross": -353.6723634847853 },
    { "id": "0GBzmPAX6vY", "name": "Summer Sale", "value": 1, "valueType": "Percent", "net": -119.95, "gross": -141.41 }
  ],
  "markups": [
    { "id": "0GBzmPAX6vZ", "name": "Environment Markup", "value": 2, "valueType": "Percent", "net": 239.9, "gross": 282.82 },
    { "id": "0GBzmPAX6va", "name": "Economic Markup", "value": 19, "valueType": "Absolute", "net": 19, "gross": 22.39924968736974 }
  ],
  "items": [
    { "type": "Section", "id": "0GBzmP9rJUe", "name": "Essential car parts" },
    {
      "type": "Item",
      "id": "0GBzmPA6iES",
      "name": "Battery",
      "description": "Supplies the electrical power to start the engine and run electronics.",
      "quantity": 1,
      "unit": "pc.",
      "netUnitPrice": 200,
      "netUnitPriceFinal": 200,
      "netTotalPrice": 200,
      "netTotalPriceFinal": 200,
      "netUnitDiscount": 0,
      "netTotalDiscount": 0,
      "grossUnitPrice": 240,
      "grossUnitPriceFinal": 240,
      "grossTotalPrice": 240,
      "grossTotalPriceFinal": 240,
      "grossUnitDiscount": 0,
      "grossTotalDiscount": 0,
      "discountPercent": 0,
      "variableCostNet": 30,
      "contributionMarginRatioThreshold": 40,
      "tax": 20,
      "isOptional": false,
      "fields": { "Audio": "fallback-audio", "Labels": ["fallback-label"], "Numbers": [-1] }
    },
    {
      "type": "Item",
      "id": "0GBzmPAJua0",
      "name": "Alternator",
      "description": "Keeps the battery charged and powers the electrical system while the engine runs.",
      "quantity": 1,
      "unit": "pc.",
      "netUnitPrice": 300,
      "netUnitPriceFinal": 285,
      "netTotalPrice": 300,
      "netTotalPriceFinal": 285,
      "netUnitDiscount": 15,
      "netTotalDiscount": 15,
      "grossUnitPrice": 330,
      "grossUnitPriceFinal": 313.5,
      "grossTotalPrice": 330,
      "grossTotalPriceFinal": 313.5,
      "grossUnitDiscount": 16.5,
      "grossTotalDiscount": 16.5,
      "discountPercent": 5,
      "discountType": "Percent",
      "variableCostNet": 50,
      "contributionMarginRatioThreshold": 40,
      "tax": 10,
      "isOptional": false,
      "fields": { "Audio": "fallback-audio", "Labels": ["fallback-label"], "Numbers": [-1] }
    },
    {
      "type": "Item",
      "id": "0GBzmPAM6yG",
      "name": "Brake Pads",
      "description": "The friction material that stops your car.",
      "quantity": 4,
      "unit": "pcs.",
      "netUnitPrice": 100,
      "netUnitPriceFinal": 100,
      "netTotalPrice": 400,
      "netTotalPriceFinal": 400,
      "netUnitDiscount": 0,
      "netTotalDiscount": 0,
      "grossUnitPrice": 110,
      "grossUnitPriceFinal": 110,
      "grossTotalPrice": 440,
      "grossTotalPriceFinal": 440,
      "grossUnitDiscount": 0,
      "grossTotalDiscount": 0,
      "discountPercent": 0,
      "variableCostNet": 20,
      "contributionMarginRatioThreshold": 40,
      "tax": 10,
      "isOptional": false,
      "fields": { "Audio": "fallback-audio", "Labels": ["fallback-label"], "Numbers": [-1] }
    },
    {
      "type": "Item",
      "id": "0GBzmPAM6yH",
      "name": "Tires",
      "description": "Your only contact point with the road.",
      "quantity": 4,
      "unit": "pcs.",
      "netUnitPrice": 300,
      "netUnitPriceFinal": 295,
      "netTotalPrice": 1200,
      "netTotalPriceFinal": 1180,
      "netUnitDiscount": 5,
      "netTotalDiscount": 20,
      "grossUnitPrice": 315,
      "grossUnitPriceFinal": 309.75,
      "grossTotalPrice": 1260,
      "grossTotalPriceFinal": 1239,
      "grossUnitDiscount": 5.25,
      "grossTotalDiscount": 21,
      "discountPercent": 1.6666666666666667,
      "discountType": "Absolute",
      "variableCostNet": 20,
      "contributionMarginRatioThreshold": 40,
      "tax": 5,
      "isOptional": false,
      "fields": { "Audio": "fallback-audio", "Labels": ["fallback-label"], "Numbers": [-1] }
    },
    {
      "type": "Item",
      "id": "0GBzmPAM6yI",
      "name": "Oil Filter",
      "description": "Keeps oil clean. Running without one dirties engine oil fast, leading to engine wear and damage.",
      "quantity": 1,
      "unit": "pc.",
      "netUnitPrice": 20,
      "netUnitPriceFinal": 20,
      "netTotalPrice": 20,
      "netTotalPriceFinal": 20,
      "netUnitDiscount": 0,
      "netTotalDiscount": 0,
      "grossUnitPrice": 24,
      "grossUnitPriceFinal": 24,
      "grossTotalPrice": 24,
      "grossTotalPriceFinal": 24,
      "grossUnitDiscount": 0,
      "grossTotalDiscount": 0,
      "discountPercent": 0,
      "variableCostNet": 2,
      "contributionMarginRatioThreshold": 40,
      "tax": 20,
      "isOptional": false,
      "fields": { "Audio": "fallback-audio", "Labels": ["fallback-label"], "Numbers": [-1] }
    },
    {
      "type": "Item",
      "id": "0GBzmPAM6yJ",
      "name": "Air Filter",
      "description": "Prevents dirt and debris from entering the engine.",
      "quantity": 1,
      "unit": "pc.",
      "netUnitPrice": 50,
      "netUnitPriceFinal": 50,
      "netTotalPrice": 50,
      "netTotalPriceFinal": 50,
      "netUnitDiscount": 0,
      "netTotalDiscount": 0,
      "grossUnitPrice": 52.5,
      "grossUnitPriceFinal": 52.5,
      "grossTotalPrice": 52.5,
      "grossTotalPriceFinal": 52.5,
      "grossUnitDiscount": 0,
      "grossTotalDiscount": 0,
      "discountPercent": 0,
      "variableCostNet": 3,
      "contributionMarginRatioThreshold": 40,
      "tax": 5,
      "isOptional": false,
      "fields": { "Audio": "fallback-audio", "Labels": ["fallback-label"], "Numbers": [-1] }
    },
    {
      "type": "Item",
      "id": "0GBzmPAM6yK",
      "name": "Spark Plugs",
      "description": "Ignite the fuel-air mix in your engine. Bad plugs cause misfires, rough idle, and poor fuel economy.",
      "quantity": 6,
      "unit": "pcs.",
      "netUnitPrice": 20,
      "netUnitPriceFinal": 20,
      "netTotalPrice": 120,
      "netTotalPriceFinal": 120,
      "netUnitDiscount": 0,
      "netTotalDiscount": 0,
      "grossUnitPrice": 24,
      "grossUnitPriceFinal": 24,
      "grossTotalPrice": 144,
      "grossTotalPriceFinal": 144,
      "grossUnitDiscount": 0,
      "grossTotalDiscount": 0,
      "discountPercent": 0,
      "variableCostNet": 3,
      "contributionMarginRatioThreshold": 40,
      "tax": 20,
      "isOptional": false,
      "fields": { "Audio": "fallback-audio", "Labels": ["fallback-label"], "Numbers": [-1] }
    },
    {
      "type": "Item",
      "id": "0GBzmPAM6yL",
      "name": "Motor",
      "description": "The engine of your car.",
      "quantity": 1,
      "unit": "pc.",
      "netUnitPrice": 9000,
      "netUnitPriceFinal": 9000,
      "netTotalPrice": 9000,
      "netTotalPriceFinal": 9000,
      "netUnitDiscount": 0,
      "netTotalDiscount": 0,
      "grossUnitPrice": 10800,
      "grossUnitPriceFinal": 10800,
      "grossTotalPrice": 10800,
      "grossTotalPriceFinal": 10800,
      "grossUnitDiscount": 0,
      "grossTotalDiscount": 0,
      "discountPercent": 0,
      "variableCostNet": 1500,
      "contributionMarginRatioThreshold": 40,
      "tax": 20,
      "isOptional": false,
      "fields": { "Audio": "fallback-audio", "Labels": ["fallback-label"], "Numbers": [-1] }
    },
    {
      "type": "Item",
      "id": "0GBzmPAM6yM",
      "name": "Radiator",
      "description": "Keeps engine temperatures in check by cooling coolant.",
      "quantity": 1,
      "unit": "pc.",
      "netUnitPrice": 100,
      "netUnitPriceFinal": 100,
      "netTotalPrice": 100,
      "netTotalPriceFinal": 100,
      "netUnitDiscount": 0,
      "netTotalDiscount": 0,
      "grossUnitPrice": 120,
      "grossUnitPriceFinal": 120,
      "grossTotalPrice": 120,
      "grossTotalPriceFinal": 120,
      "grossUnitDiscount": 0,
      "grossTotalDiscount": 0,
      "discountPercent": 0,
      "variableCostNet": 20,
      "contributionMarginRatioThreshold": 40,
      "tax": 20,
      "isOptional": false,
      "fields": { "Audio": "fallback-audio", "Labels": ["fallback-label"], "Numbers": [-1] }
    },
    {
      "type": "Item",
      "id": "0GBzmPAOJMW",
      "name": "Brake Rotors",
      "description": "Brake Rotors.",
      "quantity": 4,
      "unit": "pcs.",
      "netUnitPrice": 160,
      "netUnitPriceFinal": 160,
      "netTotalPrice": 640,
      "netTotalPriceFinal": 640,
      "netUnitDiscount": 0,
      "netTotalDiscount": 0,
      "grossUnitPrice": 192,
      "grossUnitPriceFinal": 192,
      "grossTotalPrice": 768,
      "grossTotalPriceFinal": 768,
      "grossUnitDiscount": 0,
      "grossTotalDiscount": 0,
      "discountPercent": 0,
      "variableCostNet": 20,
      "contributionMarginRatioThreshold": 40,
      "tax": 20,
      "isOptional": false,
      "fields": { "Audio": "fallback-audio", "Labels": ["fallback-label"], "Numbers": [-1] }
    },
    { "type": "Section", "id": "0GBzmPAOJMX", "name": "Accessories" },
    {
      "type": "Item",
      "id": "0GBzmPAOJMY",
      "name": "Rear wing",
      "description": "On performance cars at high speed, a spoiler can add downforce to improve stability.",
      "quantity": 1,
      "unit": "pc.",
      "netUnitPrice": 500,
      "netUnitPriceFinal": 500,
      "netTotalPrice": 500,
      "netTotalPriceFinal": 500,
      "netUnitDiscount": 0,
      "netTotalDiscount": 0,
      "grossUnitPrice": 550,
      "grossUnitPriceFinal": 550,
      "grossTotalPrice": 550,
      "grossTotalPriceFinal": 550,
      "grossUnitDiscount": 0,
      "grossTotalDiscount": 0,
      "discountPercent": 0,
      "variableCostNet": 20,
      "tax": 10,
      "isOptional": true,
      "fields": { "Audio": "fallback-audio", "Labels": ["fallback-label"], "Numbers": [-1] }
    },
    {
      "type": "Item",
      "id": "0GBzmPAOJMZ",
      "name": "LED ambient interior lights",
      "description": "LED ambient lights for your car.",
      "quantity": 1,
      "unit": "pc.",
      "netUnitPrice": 100,
      "netUnitPriceFinal": 100,
      "netTotalPrice": 100,
      "netTotalPriceFinal": 100,
      "netUnitDiscount": 0,
      "netTotalDiscount": 0,
      "grossUnitPrice": 110,
      "grossUnitPriceFinal": 110,
      "grossTotalPrice": 110,
      "grossTotalPriceFinal": 110,
      "grossUnitDiscount": 0,
      "grossTotalDiscount": 0,
      "discountPercent": 0,
      "variableCostNet": 20,
      "tax": 10,
      "isOptional": true,
      "fields": { "Audio": "fallback-audio", "Labels": ["label1"], "Numbers": [1] }
    }
  ],
  "fields": {
    "AgencyFee": 10,
    "LeadTime": "30-45 Calendar Days",
    "Comments": "",
    "CreditTerms": "Net 30 Days",
    "CreditDetails": "",
    "FOB": "Londonderry, NH",
    "Assembly": "Ships knocked down & unassembled.  Hardware kits & assembly instructions included.",
    "Freight": "Not included",
    "CoverLetter": "No"
  },
  "netTotalPrice": 12030,
  "netTotalPriceFinal": 11833.95,
  "netTotalOptionalPrice": 600,
  "netTotalOptionalPriceFinal": 600,
  "grossTotalPrice": 14178.5,
  "grossTotalPriceFinal": 13951.136886202585,
  "grossTotalOptionalPrice": 660,
  "grossTotalOptionalPriceFinal": 660,
  "totalTax": 2117.1868862025844,
  "totalTaxValues": [
    { "tax": 5, "value": 60.67427469779074 },
    { "tax": 10, "value": 67.58028970404335 },
    { "tax": 20, "value": 1988.9323218007503 }
  ]
}
```

---

## How to find quotes

#### Overview

After clicking on Quotes in the left menu bar, you can select the desired quote hub with all created quotes. You can configure your set of columns which should be shown for each quote. Simply configure your view to meet your requirements.

![](https://docs.combeenation.com/assets/images/quotes-overview-119ae84b6af725d96a15f694ccad0afe.png)

#### Settings

With the three-dots context menu next to `Add new Quote Hub` you can delete or change the quote hub.
If you decide to change your quote hub, you can find all required settings for your company or distributor.
It’s possible to change the display name or the number sequence.

In addition, it's also possible to define a custom format of the quote PDF file name.
If none is specified, then default name `{{quoteNumber}}-{{version}}` is used.
All liquid placeholders of the quote PDF file name represent objects defined in the [Quote JSON](/docs/quote-management/getting-started-with-quotes#quote-json).
If you want to access the first name of the assignee, then simply use `{{assignee.firstName}}`.
In addition, it's also possible to use liquid filters, e.g., to format a date.

##### Examples

```
{{quoteNumber}}-{{version}}
```

```
{{quoteNumber}}-{{version}}-{{assignee.lastName}}-{{ quoteDate | date:"%Y-%m-%d" }}
```

To use the current timestamp, then simply use `now` which is provided by the system.

```
{{quoteNumber}}-{{version}}-{{assignee.lastName}}-{{ now | date: "%Y-%m-%d" }}
```

In addition, you can configure the email address where quote notifications should be sent.
As a result, you get immediately informed if any anonymous user has created a quote.

![](https://docs.combeenation.com/assets/images/quote-hub-settings-90206e0ec26c98faa8352a0746551322.png)

You can also control who is allowed to view and edit quotes within the hub. See [Quote Permissions](/docs/quote-management/quote-permissions) for details.

:::info[Keep in mind:]
Many settings as the number sequence definition, PDF file name and the notifications can be configured per company/distributor.

The display name of the quote hub is defined globally.
**For admin users:** Utilize the distributor selection to switch between the company/distributor specific quote hub settings.
:::

:::danger[Attention:]
After you have deleted a quote hub, all corresponding quotes will be deleted.
Please always double-check if you really want to delete all quotes, this cannot be undone.
:::

#### Filtering

The first column shows the quote number described [Getting started with quotes](/docs/quote-management/getting-started-with-quotes#number-sequence) which uniquely identifies each quote. For simplicity, it’s possible to change the `State` and the `Assignee` of the quote directly in the overview page without opening the entire quote.

![](https://docs.combeenation.com/assets/images/quotes-overview-119ae84b6af725d96a15f694ccad0afe.png)

You can filter your quotes and view details about your quotes. When you select a value for a filter property, conditions are connected using AND logic, meaning all conditions must be met. If you select multiple values within a single filter property, these values are connected using OR logic, meaning any of the selected values can apply.

The following example filters all quotes with the state `Request`. For instance, it would be possible to change the state or the assignee of these quotes by clicking on the select item.

![](https://docs.combeenation.com/assets/images/quotes-overview-filter-29e3e0da8fd72f12c1013f2908ec5502.png)

---

## How to work with quotes

### Creating quotes

#### Leads

First, a quote can be created based on a lead. This means a successfully created lead during finishing a configuration can
be converted into a quote. Thus, it's easily possible to manage and qualify leads before creating quotes.

![](https://docs.combeenation.com/assets/images/leads-overview-c8ee9b67588d54f3050911a9fb4f933d.png)

#### Configurator

Quotes can also be created directly via the configurator, or more precisely when the configuration is finished.

You will see the `Quote` type which can be used to

- enrich every newly created quote with configuration data,
- select the name of the asset bundle (assigned to the configurator) which should be used to create the quote PDF,
- optionally create rules for selected properties,
- add custom fields to the quote and define rules for them,
- define templates which can be used in the quote details page to add predefined line items, sections, discounts or markups to the quote.

The following types of rules enable the restriction of properties in the quote details page:

- `QuoteLockRule` … locks a selected property and makes it read-only
- `QuoteMinMaxRule` … allowed number range (e.g. `Min = 1` and `Max = 5` )
- `QuoteAllowedTextsRule` … allowed text values (e.g. `"mm"`, `"cm"`, `"m"` )
- `QuoteAllowedNumbersRule`… allowed number values (e.g. `1`, `5` , `10` or `15`)

```hive
new Quote {
  quoteHubName : "QuoteHubName",
  assetBundleName: "MyBundle",
  // pdfAssetPath : "assetFolder.pdfAssetName",
  assignee: [
    user.mail
  ],
  subject : "Subject",
  projectId : "ProjectId",
  currency : Currency.EUR,
  // taxRule : QuoteTaxRule.RevealSalesTax,
  // notes : "Notes text",
  // paymentDueDays : 30,
  // offerValidityDays : 90,
  // contributionMarginRatioThreshold : 60,
  customer : new {
    firstName : "John",
    lastName : "Doe",
    companyName : "My Company GmbH",
    city : "City",
    street : "Street 13",
    // addressLine1 : "My Company GmbH",
    // addressLine2 : "Building C",
    postalCode : "PostalCode",
    country : "Country",
    emailAddress : "john.doe@mail.com",
    phoneNumber : "+43 1 12345678"
  },
  company: new {
    name: "Combeenation GmbH",
    city: "Neufelden",
    street: "Linzer Straße 4",
    // addressLine1: "Oberösterreich",
    // addressLine2: "Building A",
    postalCode: "4120",
    country: "Österreich",
    emailAddress: "info@combeenation.com",
    phoneNumber: "+43 7282 202 00",
    imageUrl: "",
    taxId: "ATU23423",
    // bankDetails: new {
      // accountHolderName: "Combeenation GmbH",
      // accountNumber: "324234",
      // bankName: "Sparkasse",
      // swift: "BC3234",
      // bic: "BC3234",
      // iban: "AT32304203402340"
    // }
  },
  // shipping: new {
  //   firstName: "John",
  //   lastName: "Doe",
  //   companyName: "My Company GmbH",
  //   // addressLine1: "Upper Austria",
  //   // addressLine2: "Building C",
  //   city: "City",
  //   street: "Street 13",
  //   postalCode: "PostalCode",
  //   country: "Country",
  //   emailAddress: "john.doe@mail.com",
  //   phoneNumber: "+43 1 12345678"
  // },
  items : [
    new QuoteSection { name : "Main" },
    new QuoteLineItem {
      name : "My Product 1",
      description : "Description text",
      quantity : 10,
      unit : "m",
      priceNet : 10,
      tax : 20
    },
    new QuoteLineItem {
      name : "My Product 2",
      sku : "MP-2",
      description : "Description text",
      quantity : 1,
      unit : "mm",
      priceNet : 20.5,
      variableCostNet : 15,
      // contributionMarginRatioThreshold : 50,
      tax : 20,
      discount : new {
        value : 5,
        // valueType : PriceAdjustmentType.Percent
      },
      isOptional : true,
      imageUrl : "https://picsum.photos/id/2/200",
      rules: new {
        priceNet: new QuoteMinMaxRule {
          min: 10,
          max: 1000
        },
        quantity: new QuoteAllowedNumbersRule {
          numbers: [1, 5, 10, 15]
        },
        unit:  new QuoteAllowedTextsRule {
           texts: ["mm", "cm", "m"]
         },
        discount: new {
          value: new QuoteMinMaxRule {
            min: 0,
            max: 10
          }
        }
      },
      fields : new {
         myItemCustomField : "My line item property value"
      },
      fieldRules: new {
         myItemCustomField: new QuoteLockRule { }
      },
      actionRules: new {
        delete: new QuoteLockRule { }
      }
    },
    new QuoteDiscount {
      name: "Special Discount",
      value: 300,
      valueType: PriceAdjustmentType.Absolute,
      rules: new {
        value: new QuoteMinMaxRule {
          min: 0,
          max: 400
        }
      },
      actionRules: new {
        delete: new QuoteLockRule { }
      }
    },
    new QuoteDiscount {
      name: "Summer Sale",
      value: 1,
      valueType: PriceAdjustmentType.Percent,
      rules: new {
        value: new QuoteMinMaxRule {
          min: 0,
          max: 5
        }
      }
    },
    new QuoteMarkup {
      name: "Environment Markup",
      value: 2,
      valueType: PriceAdjustmentType.Percent,
      rules: new {
        value: new QuoteMinMaxRule {
          min: 0,
          max: 5
        }
      },
      actionRules: new {
        delete: new QuoteLockRule { }
      }
    },
    new QuoteMarkup {
      name: "Economic Markup",
      value: 50,
      valueType: PriceAdjustmentType.Absolute,
      rules: new {
        value: new QuoteMinMaxRule {
          min: 0,
          max: 100
        }
      }
    }
  ],
  rules: new {
    subject: new QuoteLockRule { },
    projectId: new QuoteAllowedTextsRule {
      texts: ["project 1", "project 2"]
    },
    paymentDueDays: new QuoteMinMaxRule {
      min: 1,
      max: 5
    },
    taxRule: new QuoteLockRule { },
    quoteDate: new QuoteLockRule { }
  },
  templates: [
    new {
      items: [
        new QuoteLineItem {
          name: "Additional Product 1",
          quantity: 1,
          unit: "pc.",
          priceNet: 149,
          tax: 20,
          rules: new {
            priceNet: new QuoteMinMaxRule {
              min: 10,
              max: 100
            },
          },
          fields : new {
             myItemCustomField : "My line item template"
          },
          fieldRules: new {
             myItemCustomField: new QuoteLockRule { }
          },
          actionRules: new {
            delete: new QuoteLockRule { }
          }
        },
        new QuoteLineItem {
          name: "Additional Product 2",
          quantity: 1,
          unit: "pc.",
          priceNet: 289,
          tax: 20,
          rules: new {
            priceNet: new QuoteMinMaxRule {
              min: 100,
              max: 1000,
            },
          },
          fields : new {
             myItemCustomField : "My line item template"
          },
          fieldRules: new {
             myItemCustomField: new QuoteLockRule { }
          },
          actionRules: new {
            delete: new QuoteLockRule { }
          }
        },
        new QuoteSection {
          name: "Section Template"
        },
        new QuoteDiscount {
          name: "Summer Sale",
          value: 3,
        },
        new QuoteMarkup {
          name: "Custom Markup",
          value: 100,
          valueType: PriceAdjustmentType.Absolute,
        }
      ]
  }],
  fields: new {
     myCustomField : "My additional quote property value"
  },
  fieldRules: new {
    myCustomField : new QuoteLockRule { }
  },
  actionRules: new {
    addItem: new QuoteLockRule { },
    addTotalDiscount: new QuoteLockRule { },
    addTotalMarkup: new QuoteLockRule { },
  }
}
```

:::info[Keep in mind]
Always include the `quoteHubName` to select the correct quote hub.

Please ensure that this property is not missing and the quote hub is correctly configured, otherwise the quote cannot be created.
:::

As previously described, every configurator can create quotes in any hub (see the `quoteHubName` property). In the following example, configurator A, B and C create quotes in their dedicated hubs, but configurator D creates quotes in HUB2 and HUB3. This allows you to create quotes from different configurators, but ensure the same number sequence described in the next section.  
This is crucial if products from different configurators should use the same quote numbers in their offers (quote PDFs).

![](https://docs.combeenation.com/assets/images/quote-hubs-85834901f39ba238930d740b5b5bc3f1.png)

#### Changing quotes

After you have configured the quote creation and users have already created quotes, you can use them in the quote overview page.  
A quote is always linked to a configuration which is protected and can no longer be modified to avoid inconsistencies between the configuration and the resulting quote.  
Once you have clicked on a dedicated quote, all details of this quote are shown. You can directly see the resulting quote PDF which is ready to be sent to your customer.  
In addition, it’s conveniently possible to change all details of the quote by clicking on the `Edit Quote` button.

![](https://docs.combeenation.com/assets/images/published-quote-eece3a16eb5fa76bfe039e6c48378990.png)

In a quote draft, you can modify contact details, contents and details (tax rules, custom fields, etc.) of the quote.  
All properties that violate a quote rule are highlighted, check allowed values in the tooltip. If a quote contains issues, then it’s not possible to publish it.  
The button on the right-hand side allows you to see a preview of the quote PDF.

![](<https://docs.combeenation.com/assets/images/quote-details%281%29-38c67ee7dd1a0f3d258c24ad4cf05682.png>)

#### Restoring quotes

If you would like to go back to a previous version or check all changes which have been performed for a quote, then simply click on the history button.

![](<https://docs.combeenation.com/assets/images/quote-history%282%29-6b7730d20c2139a1972c6c8ff881ce06.png>)

---

## Quote Permissions

By default, everyone in your company who can access quotes can view and edit all quotes in a quote hub.
Some teams, however, want their users to only work on their own quotes and not see each other's quotes –
especially pricing details like discounts.

Quote Permissions let you control this per quote hub. You decide the minimum [role](/docs/fundamentals/user-permissions)
required to access quotes that are not assigned to a user, and whether the person who created a quote keeps access to it.

### The assignee always has access

A user can **always** view and edit the quotes that are assigned to them,
regardless of any other setting described below. Assigning a quote is therefore the simplest way to give someone access to it.

You can change the assignee directly in the quotes overview or in the quote details page.

### Configuring permissions

The permission settings are part of the quote hub settings, which you can open with the three-dots context menu next to `Add new Quote Hub`.

#### Access to other users' quotes

_Define the minimum role required for users to view or edit quotes they are not assigned to._

- **Minimum role to view** – the lowest [role](/docs/fundamentals/user-permissions) a user needs to view quotes that are **not** assigned to them.
- **Minimum role to edit** – the lowest role a user needs to edit quotes that are **not** assigned to them.

Both settings default to **sales**. With the default, every user can view and edit all quotes in the hub, because sales is the
lowest role that can access quotes at all.

Raising a setting restricts access. For example, if you set **Minimum role to view** to **developer**, then sales users can only
see quotes that are assigned to them, while developers and admins can still see all quotes.

#### Quote creator access

_Grant creators permanent access to their quotes, even if they are not assigned to them._

- **Creator can always view their quotes** – the user who created a quote can always view it, even when it is not assigned to them.
- **Creator can always edit their quotes** – the user who created a quote can always edit it, even when it is not assigned to them.

Both settings are **off** by default. They only take effect once you raise the minimum role above **sales**: as long as everyone
can view and edit all quotes anyway, they make no difference.

Enable them when you want people to keep access to the quotes they create, without having to assign every quote to themselves.

### Things to keep in mind

- **Quotes created by anonymous users** (from a configurator) have no creator and by default no assignee either (see next point).
  Once you raise the minimum role above sales, these quotes are no longer visible to sales users and must be **explicitly assigned**
  to someone by a developer or admin.
- **There is no automatic assignment.** When a signed-in user creates a quote, they are not assigned to it automatically.
  To make sure a user keeps access to the quotes they create, either:
  - assign them in the configurator when the quote is created (for example `assignee: [ user.mail ]`, see [How to work with quotes](/docs/quote-management/how-to-work-with-quotes#configurator)), or
  - enable **Creator can always view their quotes** / **Creator can always edit their quotes** for the quote hub.

---

## Version highlights 1.20.0

With version 1.20 we are releasing a large update to Combeenation's computational engine that has been a long time in development. The greatest part of this update won't have any directly visible effects for our users, but brings a number of performance and stability improvements that should make our configurators even more delightful to work with.

This update also lays the foundation for more advanced features that would not have been possible in the old system. Stay tuned for some juicy new features in the near future! Until then, we have a couple of new things for you to play with and a host of fixes and quality of life improvements for our ConfiguratorEditor.

One noteworthy improvement revolves around renaming components and changing their type: in the past, the ConfiguratorEditor sometimes failed to show all effects of these changes. We've completely re-designed the way we process such changes and have re-written the configurator-wide error analyser to be more reliable and efficient.

Other impactful changes are outlined in the sections below. Of particular importance is the following section as it will significantly affect your day-to-day work with the ConfiguratorEditor.

### Using components with the # Operator

_Hidden identifiers can now be accessed with the new # operator. The operator **must** also be used to access the `Records`, `Value` and `SelectedKey` properties of a `RecordComponent`._

Naming things is hard. Poorly chosen component names can confuse your colleagues (or yourself) and sometimes they can get you into awkward situations. Imagine a `GraphicComponent` and inside it a visual with the name "Width". Now imagine you had to use both the "Width" visual and the component's `Width` property – how can you tell them apart? They are both called "Width" after all.

This is where the new Escape Operator comes in: `Width` refers to the "closer" thing, in this case the visual, while `#Width` refers to the "hidden" or more distant thing, in this case the component's width property. For the most part, you can avoid landing in situations like this by picking meaningful names – but in case you do end up in one, the escape operator is there to help you.  
_This is also where the operator got its name – and because a number sign (#) resembles prison bars (and because naming things is hard)._

![escape-operator.jpg](https://docs.combeenation.com/assets/images/escape-operator-19d3489805dcd6ffc094df2edb7e6111.jpg)

#### Components

There is a second, more frequently occurring scenario that requires the use of the # operator, and it has to do with certain kinds of components, like the **RecordComponent**. These components have always been two things at once: a component and a value produced by the component. The `RecordComponent` for instance possesses properties like `Records` and `SelectedKey`, while its value is the selected record.

Up until now you could just write the component's name and then access either its properties or those of its value. For example, `myComponent.Records` would return the Records property and `myComponent.Price` would return the "Price" column of the selected Record.

Things got ugly if both the component and its value contained a property with the same name. In that case _you_ had to _know_ which one the system would use, and how to get a hold of the _other_ one. For RecordComponents, that meant you had to write e.g. `myComponent.Value.Name` instead of `myComponent.Name` (because "Name" would refer to the component's Name, not the "Name" column of its value).

Confusing, isn't it? Our goal is to remove these complicated scenarios, but to get there we first had to stop the system from choosing one out of two possible properties for you. Unfortunately that means that for now, _you_ have to do the choosing.

**Specifically,** to access any property of a RecordComponent, you now have to use the Escape Operator. For example, to access the Records property you have to write `#myComponent.Records`. This is now **required**. On the plus side, `myComponent.Name` will now always refer to the "Name" column (if there is one), meaning you no longer have to write `myComponent.Value.Name`.

#### Under the hood

If you're wondering why we chose the Escape Operator to discern component properties, then this section is for you. If you had enough of obscure compiler mumbo jumbo, feel free to move on to the [next section](/docs/releases/release-1200#general-features).

At the beginning of this section we mentioned that certain components are two things at once – a component and its value. This is no longer the case. A component and its value are now two separate entities, where the value is "closer" to you, the user. As a result you always work with the value by default, and if you want to use the "hidden" component you need to "escape" the value first.

Other components that are affected by this change are, in theory, the `ValueComponent` and `ResourceComponent`. However, contrary to the `RecordComponent`, it is unlikely that you will end up needing any of their properties, so don't worry about it. And in case you do need to access one of them, just use the Escape Operator.

### General Features

We have added two **new variables** that can be used to obtain various kinds of information about your configurator: `configurator` and `presets`. For more details, check out their [documentation](/docs/configurator-logic/configurator-and-presets-variable). The `configurator` variable is a replacement for the `plan` keyword, which will be **removed** in a future version.

In addition to single-line comments, you can now also write comments that span multiple lines or just a portion of a single line. Start the comment with `/*` and end it with `*/`, further details and examples can be found in the [documentation](/docs/configurator-logic/hive-language).

### Changes to Text in Hive

_Text comparison is now case sensitive by default, new functions and features have been added to Text._

**Comparing** texts in Hive used to be case insensitive, meaning `"hi" = "Hi"` would return `true`. This was convenient in some cases but problematic in others, for example when you have to deal with case-sensitive product IDs or SKUs.

Text is now **case sensitive**, meaning `"hi" = "Hi"` will return `false`. However, we added a `~=` operator for Text that ignores casing to support existing use cases: `"hi" ~= "Hi"` will return `true`, just like the `=` operator used to.

This change also affects **Maps** such as `Resources` or `Components`. When you wish to retrieve e.g. a Resource by constructing its Name dynamically, you need to use the exact same case you used when creating the Resource.  
For example, if you have a `ResourceComponent` called "pics" and within it a Resource with the name "Pic1", you must write `pics.Resources.Get("Pic1")` to retrieve it. Writing `Get("pic1")` will not return it. (Note that this does **not** affect direct references to the resource! These are still case-insensitive, meaning that `pics.Pic1` will work)

We also added two **new functions** to Text: `contains` can be used to check if a Text contains certain characters or words and `replace` can be used to replace them with a different Text. Check out the [Text docs](/docs/configurator-logic/hive-types/text-type) for more details and examples!

### More Helpful Hive Errors

_Error messages are more precise, easier to understand and include more helpful information._

We've **completely rewritten** all compiler errors to be more understandable and less technical. Each error now briefly states what the problem is and may contain a hint at the end to further explain why it occurred and/or provide guidance for inexperienced users.

We also improved the code **snippets** that are shown in the error message to more precisely highlight where the error occurred. These snippets now also work properly when the affected area spans multiple lines.

Here is an example:

```hive
-- ERROR in TestComponent --------------------------------------------------------------------------

The branches of this 'if' produce different types of values:
The 'then' branch has type Number but the 'else' branch is Text.

3|   if true then 1 else "2" end
                         ^^^

Hint: All branches must have the same type so that no matter which one we take, we always get back the same type of value.
```

Hive

### New: DynamicVisual Items

_You can now access the individual items generated by a `DynamicVisual` with its new `Items` property._

`Items` is a list of visuals, which means you first need to pick the one you are interested in with the `Get` function. You can then access all properties of that visual, such as its `X` or `Y` coordinates or its `Texture` or `Shape`:

```hive
// get the 'x' coordinate of the 2nd visual of the 'boxes' DynamicVisual
DefaultView.boxes.Items.Get(2).X
```

Hive

The number of items matches that of the DynamicVisual's `ItemSource` property.

---

## Archived Release Notes

### Release 18 Dec 25

Version `2.1.202512181`

| Type                                      | Description                                                                                                                                                                                                                        |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Various quote improvements: Configurable quote version names Download button for the quote JSON First level support for company information Enable quote rules on the contribution margin |
| New | Add a `displayName` for the [configurator.owner](/docs/configurator-logic/configurator-and-presets-variable#properties) in Hive                                                                                                    |
| New | Add URL support for the `data_uri` filter of PDF assets                                                                                                                                                                            |

### Release 10 Dec 25

Version `2.1.202512101`

| Type                                      | Description                                                                                                                |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| New | [Quote Rules](/docs/quote-management/how-to-work-with-quotes#creating-quotes) to constrain properties in the quote editor. |
| New | All [Math functions](/docs/configurator-logic/hive-types/math-type) can now be used in Hive queries.                       |

### Release 01 Dec 25

Version `2.1.202512012`

| Type                                      | Description                                                                                             |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| New | [Single Sign-On](/docs/integrations-and-api/single-sign-on) with Microsoft Entra OIDC is now available. |

### Release 24 Nov 25

Version `2.1.202511241`

| Type                                      | Description                                     |
| ----------------------------------------- | ----------------------------------------------- |
| New | Distributor support in the configurator editor. |

### Release 19 Nov 25

Version `2.1.202511191`

| Type                                      | Description                                                                                                                        |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| New | [Convert document endpoint](/docs/asset-management/pdf-asset#how-to-use-a-pdf-asset) for PDF generation, merging and watermarking. |

### Release 05 Nov 25

Version `2.1.202511051`

| Type                                      | Description                                                                                                                                          |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | [Quote history](/docs/quote-management/how-to-work-with-quotes#restoring-quotes) - show all versions of a quote and restore a specific version of it |
| New | [Quote margin calculation](/docs/quote-management/how-to-work-with-quotes#changing-quotes) - check the contribution margin of each line item         |

### Release 15 Oct 25

Version `2.1.202510151`

| Type                                      | Description                                                                                                                           |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| New | Use `...all` in your [Hive queries](/docs/configurator-logic/hive-queries#projecting-data) to include all columns of the data source. |

### Release 07 Oct 25

Version `2.1.202510071`

| Type                                      | Description                                                                                                                                                                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | Workflow [triggers](/docs/integrations-and-api/workflows/workflow-in-depth#triggers) - enable workflows to run automatically in response to specific events, such as a checkout creation or a quote state change. |
| New | Quotes are now [created as Hive objects](/docs/quote-management/how-to-work-with-quotes#creating-quotes) in the configurator editor and support custom fields. |

### Release 08 Sep 25

Version `2.1.202509081`

| Type                                      | Description                                                                                                                                                             |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | ChangeDistributor SigSlo to modify the [configurator.owner](/docs/configurator-logic/configurator-and-presets-variable#properties) during a configuration session |
| New | Insights and quotes platform URLs via the Hive [configuration](/docs/configurator-logic/configuration-variable) variable                                                |

### Release 01 Sep 25

Version `2.1.202509011`

| Type                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Introducing: Hive Objects. Objects are similar to records, but more powerful and built for JSON interop. This initial release introduces the [Shopware6Parameter](/docs/integrations-and-api/checkout-types/shopware-6#combeenation-platform) and [ShopifyParameter](/docs/integrations-and-api/checkout-types/shopify#combeenation-platform) objects to streamline the creation of Shopware 6 and Shopify products. |
| New | Use [List.concat()](/docs/configurator-logic/hive-types/list-type#concatlist) to combine two Hive lists                                                                                                                                                                                                                                                                                                                          |

### Release 06 Aug 25

Version `2.1.202508061`

| Type                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | We support [custom fields](/docs/fundamentals/custom-fields) for 4 different entities now: User ... field per user (e.g. language) -> `user.fields.language` Company/Distributor ... field per company or distributor (e.g. discount) -> `configurator.owner.fields.discount` Quote ... additional field per Quote (e.g. terms of payment) Quote Line Item ... additional fields per line item (e.g. delivery time) |

### Release 31 Jul 25

Version `2.1.202507311`

| Type                                      | Description                                                                                                                       |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| New | Introduce quote/insights notifications: Mails will be sent if a new quote is created or a user is assigned to an insight or quote |

### Release 17 Jul 25

Version `2.1.202507171`

| Type                                      | Description                                                                                                                                                                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Quote improvements: Improved line item positioning support Line item sections Rich text editor for descriptions Set additional values via checkout json (tax rule, discounts) |

### Release 10 Jul 25

Version `2.1.202507101`

| Type                                      | Description                                                                                      |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| New | You may now reference other tables in a data source query to create simple joins between tables. |

### Release 3 Jul 25

Version `2.1.202507031`

| Type                                      | Description                                                                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| New | Quotes can be send via mails.                                                                                          |
| New | SMTP settings can be configured per company/distributor. See [Mail settings](/docs/integrations-and-api/mail-settings) |

### Release 12 Jun 25

Version `2.1.202506121`

| Type                                      | Description                                                                                                                                                                                   |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | A finished configuration which created a quote is protected and can no longer be edited. This means it's not possible to perform subsequent checkouts if a configuration has created a quote. |
| New | Introduce a [configuration.hasQuote](/docs/configurator-logic/configuration-variable#properties) hive variable to check if the current configuration has already a linked quote.              |

### Release 05 Jun 25

Version `2.1.202506051`

| Type                                      | Description                                                                                                                                                                          |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | Introduce [configurator.owner](/docs/configurator-logic/configurator-and-presets-variable#properties) hive variable to identify the owner (company or distributor) of a configurator |
| Fix | Misc fixes and improvements                                                                                                                                                          |

### Release 02 Jun 25

Version `2.1.202506021`

| Type                                      | Description                                                |
| ----------------------------------------- | ---------------------------------------------------------- |
| New | Quotes feature to create, manage and generate (PDF) quotes |

### Release 20 May 25

Version `2.1.202505201`

| Type                                            | Description                                                                                                                                                             |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | New email templates now include the company logo. If the company is ad-free, Combeenation will not be mentioned.                                                        |
| New       | Hive's [Text.toNumber](/docs/configurator-logic/hive-types/text-type#tonumberlocale) function now optionally accepts a locale to convert differently formatted numbers. |
| Change | Calculations in Hive that result in infinity or non-finite / imaginary numbers (e.g. `log(0)`, `sqrt(-1)`) now produce an error instead of a "NaN" text.                |

### Release 24 Apr 25

Version `2.1.202504242`

| Type                                      | Description                                                                                                                                                                                                          |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Configurator Theming / White-Labeling: Upload of a company logo Upload of distributor logos Customization of the whole platform General improvements of theming capabilites |
| New | Allow upload of an user avatar image                                                                                                                                                                                 |

### Release 07 Apr 25

Version `2.1.202504071`

| Type                                      | Description                                                                          |
| ----------------------------------------- | ------------------------------------------------------------------------------------ |
| New | [PDF assets](/docs/asset-management/pdf-asset) for a convenient way of creating PDFs |

### Release 03 Apr 25

Version `2.1.202504031`

| Type                                      | Description                                  |
| ----------------------------------------- | -------------------------------------------- |
| New | Added German as language option for platform |

### Release 26 Mar 25

Version `2.1.202503261`

| Type                                      | Description                                                      |
| ----------------------------------------- | ---------------------------------------------------------------- |
| New | Configurator editor: `Go to rule` feature in CSS Styles overview |
| Fix | Misc fixes and improvements                                      |

### Release 19 Mar 25

Version `2.1.202503191`

| Type                                      | Description                                                                           |
| ----------------------------------------- | ------------------------------------------------------------------------------------- |
| New | Hive queries can load data from other table components (instead of from data sources) |
| New | All fields of linked assets (e.g. Image.Url) can now be used in query expressions     |

### Release 05 Mar 25

Version `2.1.202503051`

| Type                                      | Description                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------------ |
| New | Introduce fullscreen mode for 3d model, material and data source asset editors |
| New | Streamline page headers and add common breadcrumbs                             |
| New | Possibility to create headless configurator projects                           |

### Release 18 Feb 25

Version `2.1.202502181`

| Type                                            | Description                                                                                         |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| New       | Configurator Theming / White-Labeling: Customize the appearance of the Login page in a configurator |
| Change | Whitelist domains: Allow http urls                                                                  |
| Change | Minor restructuring of the Company Settings page                                                    |

### Release 17 Feb 25

Version `2.1.202502174`

| Type                                            | Description                                                                                                 |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| New       | Support "[scene assets](/docs/configurator-ui-ux/controls/3d-viewer-control#scene-asset)" in viewer control |
| Change | Improved UX in data source column config editor                                                             |

### Release 12 Feb 25

Version `2.1.202502121`

| Type                                            | Description                                                                               |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
| New       | Support stages in the "Compare draft" feature of the configurator editor                  |
| Fix       | Fix drafts and users not being properly shown inside the "Compare draft" window           |
| Change | Concurrent uploads of `CfgnFiles` are now processed sequentially instead of being aborted |

### Release 04 Feb 25

Version `2.1.202502041`

| Type                                      | Description                                              |
| ----------------------------------------- | -------------------------------------------------------- |
| New | Create material assets from templates                    |
| New | Add decal creation modal to predefine essential settings |

### Release 30 Jan 25

Version `2.1.202501301`

| Type                                      | Description                                                                                                       |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| New | Convenient way of switching between distributors to check configuration insights and resulting configurator links |
| New | Add 3dm support for file assets                                                                                   |
| New | Add ktx2 support for textures (image assets)                                                                      |
| Fix | Avoid invalid accessibility warnings                                                                              |

### Release 27 Jan 25

Version `2.1.202501271`

| Type                                      | Description                                                                                                                                                                                                                                                   |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Accessibility (a11y) improvements of configurators: New property `aria-label` for relevant controls in the editor Show warnings in case of insufficient labeling Improved default html markup to fulfill basic accessibility |

### Release 23 Jan 25

Version `2.1.202501232`

| Type                                      | Description                                                                      |
| ----------------------------------------- | -------------------------------------------------------------------------------- |
| New | Highlight asset bundles that are assigned to the currently selected configurator |

### Release 19 Dec 24

Version `2.1.202412191`

| Type                                      | Description                                                                                                                                      |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | Added new configuration file properties `DisplayName`, `Size` and `Extension` (available in Hive and Custom Code)                                |
| Fix | Fix an issue where uploading a configuration file would result in unnecessary updates of other components that use the `configuration` variable. |

### Release 18 Dec 24

Version `2.1.202412181`

| Type                                      | Description                                                                                                                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | Added [fireAnalyticsEvent](/docs/configurator-ui-ux/controls/configurator-control#fire-analytics-event) slot to enable the creation of events for the Google Tag Manager |

### Release 11 Dec 24

Version `2.1.202412111`

| Type                                      | Description                                                                                                                                                                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | Introduced [Decals Editor](/docs/asset-management/3d-and-material-assets/decals)                                                                                                                                               |
| New | Distributors Manage multiple distributors with sales users per company Define default values for user custom fields per distributor Specify the maximum number of available seats per company |

### Release 09 Dec 24

Version `2.1.202412091`

| Type                                            | Description                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Change | Improved "Share configuration" features New property "Image url" for Share buttons so they can be used with a Graphic Component. [New functions for Custom Code](https://custom-code.docs.combeenation.com/pages/release-notes/releases/index.html#version-114) Show target platform in events of the Configuration insights |

### Release 02 Dec 24

Version `2.1.202412021`

| Type                                      | Description                                                                                                                                    |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Data sources can now be created [based on JSON file assets](/docs/asset-management/data-source-asset/json-based-data-sources).                 |
| New | A CSV file can now also be uploaded as file asset to then create a data source (until now, it had to be uploaded as a data source asset). |

### Release 26 Nov 24

Version `2.1.202411261`

| Type                                            | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Change | Improved configuration insights filtering New UI for selecting filter properties Display available values per property including their count |
| Change | Improved configuration insights detail view Events will now be displayed Configurations can be assigned to a user Comments can be added Edit button for [personal configurations](/docs/configuration-insights/personal-configurations) New copy button, which allows the user to copy a live configuration to a staging configurator |
| New       | Configuration session time will now be tracked                                                                                                                                                                                                                                                                                                                                         |

### Release 14 Nov 24

Version `2.1.202411141`

| Type                                            | Description                                                                                            |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Change | The control property `Visible` is now based on the type `Logic` (true/false) when setting it with Hive |
| Change | Moved the `Rename component` action from the menu into the toolbar                                     |

### Release 13 Nov 24

Version `2.1.202411131`

| Type                                            | Description                                                                            |
| ----------------------------------------------- | -------------------------------------------------------------------------------------- |
| Change | Avoid throwing error when accessing missing material asset within configurator logic   |
| Fix       | "Show load mask" slot was sometimes ignored when called right after configurator start |

### Release 05 Nov 24

Version `2.1.202411051`

| Type                                            | Description                                                                                                  |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| New       | Tooltip properties for wizard navigator buttons                                                              |
| Change | Custom configurator CSS will load earlier, improving performance and allowing for more customization options |

This new loading method will **not** be automatically applied to existing configurators. It will take effect the next time you make any change to the user interface (design editor) of an existing configurator.

:::caution
With the earlier loading of your CSS, there may be unintended changes to the appearance of the configurator's loading spinner.

For example, if your CSS includes a rule like `* { border-radius: 0px !important; }`, the normally circular loading spinner will appear as a square after your next change.

The good news is that this issue can typically be resolved easily. To prevent such broad CSS rules from affecting the loading spinner, we recommend making your selectors more specific.

For instance, instead of using the general wildcard selector `*`, you can use `.cfgr-parent *` to limit the effect to only the configurator itself: `.cfgr-parent * { border-radius: 0px !important; }`.
:::

### Release 29 Oct 24

Version `2.1.202410292`

| Type                                            | Description                                                                                                                           |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| New       | New mathematical Hive functions [log(), log2() and log10()](/docs/configurator-logic/hive-types/math-type#lognumber)                  |
| Change | Change [intersect()](/docs/configurator-logic/components/record-component#functions) method of Hive tables to accept key-only records |

### Release 28 Oct 24

Version `2.1.202410281`

| Type                                            | Description                                                                                                                                                                 |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | New Hive function [isEmail()](/docs/configurator-logic/hive-types/text-type#isemail) to test if a text is a valid email address                                             |
| New       | Add tag editor in material assets for marking and grouping materials                                                                                                        |
| Change | Improve naming of extracted linked texture assets from 3d model by using the original image file name instead of the auto-generated texture name from the Babylon.js engine |

### Release 24 Oct 24

Version `2.1.202410241`

| Type                                      | Description                                                                         |
| ----------------------------------------- | ----------------------------------------------------------------------------------- |
| New | New 3D models can now be compared with existing assets before finalizing the upload |

### Release 22 Oct 24

Version `2.1.202410221`

| Type                                      | Description                                                                                                                                                                                                                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | Custom Code functionality has a new home in the header bar of the configurator editor Easily upload code, connect to local IDE and sync custom code definitions This fully replaces resource components, which will be deprecated in a future release |

### Release 21 Oct 24

Version `2.1.202410211`

| Type                                      | Description                                                                                                      |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| New | New [permissions and roles](/docs/fundamentals/user-permissions) for the upcoming distributor management feature |

### Release 02 Oct 24

Version `2.1.202410021`

| Type                                            | Description                                                                                                                                                                                                           |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | Add properties to material asset basic editor Detail map configuration Clamp UV for each texture channel Runtime behaviour flags: `needDepthPrePass` / `checkReadyOnEveryCall` |
| Change | Moved the "Configurator picker" into the sidebar                                                                                                                                                                      |

### Release 18 Sep 24

Version `2.1.202409181`

| Type                                      | Description                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Material asset: Adjustable light intensities for preview                                                                                                                                                                                                                                                             |
| New | [Tooltips for controls](/docs/configurator-ui-ux/controls/tooltips-for-controls) Directly define tooltips in the cfgr editor The latest [custom-code-utils](https://www.npmjs.com/package/@combeenation/custom-code-utils) provide functions to access & fully customize the tooltips |

### Release 16 Sep 24

Version `2.1.202409161`

| Type                                      | Description                                                                                                                                                                                                                                                                                                                                     |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Rework of the entire data source config dialog New menu to see which changes cause different output results Advanced way of selecting header and start rows Improved excel sheet selection New feature for moving column configs to handle added/removed columns Improved error handling |

### Release 11 Sep 24

Version `2.1.202409111`

| Type                                      | Description                                                                                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Easier way to allow end users upload files during a configuration and manage them as configuration files in the configuration insights table |
| New | Add svg and webp support for assets (linked asset columns)                                                                                   |
| New | Add webp support for textures                                                                                                                |

### Release 26 Aug 24

Version `2.1.202408261`

| Type                                      | Description                                                                                                                                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | [Configurator specific insights values](/docs/configuration-insights/configuration-insights-#information-about-the-configuration) are now also available in the configuration insights table |

### Release 08 Aug 24

Version `2.1.202408081`

| Type                                      | Description                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------------ |
| New | [Configuration insights](/docs/configuration-insights/configuration-insights-) |

### Release 17 Jul 24

Version `2.1.202407172`

| Type                                            | Description                                                                                                                                |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| New       | Configurator editor: Getting started info in configurator editor when no component is selected                                             |
| Change | Configurator editor: Moved info about configurator presets from header bar into sidebar beneath the component list                         |
| Change | Configurator editor style & layout updates (consistent checkboxes, new layout for graphic editor, refinements for add control dialog, ...) |
| Change | Control property `BorderWidth` is now of type `Text` instead of `Number` which allows usage of CSS units other than `px`                   |
| Fix       | Configurator editor: Show correct user name in "Last edited" column of asset assignment dialog                                             |
| Fix       | Caching issue when opening configurator drafts                                                                                             |

### Release 15 Jul 24

Version `2.1.202407151`

| Type                                      | Description                                                                                                                                                                                                                                                                                      |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | Introducing [personal configurations](/docs/configuration-insights/personal-configurations): users that are signed into the Combeenation platform now exclusively own the configurations they create. You can use the Combeenation login system in your configurators to allow users to sign in. |
| New | [Custom fields](/docs/fundamentals/custom-fields) can be defined for users of a company to store additional data per user.                                                                                                                                                                       |
| New | Information about the currently signed-in [user](/docs/configurator-logic/user-variable) is now accessible in Hive (including new custom fields). This makes it simple to show additional data to signed-in users or make advanced features available only to them.                              |

### Release 08 Jul 24

Version `2.1.202407082`

| Type                                      | Description                                                                                                                                                                                                                                                                                                 |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Visualize [transformations](https://doc.babylonjs.com/features/featuresDeepDive/mesh/transforms), [morph targets](https://doc.babylonjs.com/features/featuresDeepDive/mesh/morphTargets) and [animations](https://doc.babylonjs.com/features/featuresDeepDive/animation/animation_introduction) in 3d asset |

### Release 02 Jul 24

Version `2.1.202407021`

| Type                                            | Description                                                                                                                                                                                                                                                                                                                           |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Change | Custom code (version 1.0.0 or above) General improvement how and when components are requested from the server ⭐ `CustomJSCmps` are no longer necessary For more details see [custom-code-utils - Release Notes](https://custom-code.docs.combeenation.com/pages/release-notes/releases/1_0_0.html) |

### Release 27 Jun 24

Version `2.1.202406271`

| Type                                            | Description                                                                                                                                                                       |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | System provided fallback assets for data sources: Default values for linked assets are no longer mandatory. The platform automatically provides suitable fallback assets for you. |
| New       | New quick access bar in configurator editor for important components like user interface & checkout.                                                                              |
| Change | ⭐ Design component & editor is now called user interface and only accessible via the quick access bar at the top, not via the component list anymore.                            |
| Change | Overhauled layout in add control dialog of user interface editor.                                                                                                                 |

### Release 25 Jun 24

Version `2.1.202406251`

| Type                                      | Description                                                                                                                                                                |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Update viewer control to be compatible with reworked viewer version [V13.0.0](https://3dviewer.docs.combeenation.com/pages/release-notes/releases/index.html#version-1300) |

### Release 12 Jun 24

Version `2.1.202406121`

| Type                                      | Description                                                                                                                                 |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Add notification support to get [notified](/docs/integrations-and-api/workflows/workflow-in-depth#notifications) whenever a workflow fails. |

### Release 04 Jun 24

Version `2.1.202406042`

| Type                                            | Description                                                                            |
| ----------------------------------------------- | -------------------------------------------------------------------------------------- |
| Change | ⭐ Updated the UI of the configurator editor to align with the general platform design |
| Fix       | Minor improvements and fixes (copying controls, auto-generated typings, etc.)          |

### Release 28 May 24

Version `2.1.202405281`

| Type                                      | Description                                                                                                                                                                                                                                                                     |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Improved asset bundle version management: Only show the most relevant asset bundle versions in the version selection dropdown Added "Manage versions" page with detailed bundle version information and possibility to load and edit further versions. |

### Release 13 May 24

Version `2.1.202405131`

| Type                                      | Description                                                                                                                                                                                                                                                                                |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | Add synchronization functionality to [Custom code](/docs/configurator-ui-ux/custom-code/custom-code-) Connects your configurator editor and preview to your locally running custom code project (IDE) Quickly update component typings with the click of a button |

### Release 2 May 24

Version `2.1.202405021`

| Type                                            | Description                                                                                                                                                                                                                                                                                                                                                    |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | Introducing [configurator stages](/docs/fundamentals/creating-a-configurator#configurator-stages): test all features of a configurator (e.g. checkout, share) without having to publish it embed it on QA sites for end-to-end tests repeatedly stage drafts to update the stage once fully tested, publish the stage |
| Change | Revamped asset editor UI: Reorganized elements for improved usability Customizable layout with collapsible and resizable panels Improved user guidance with breadcrumbs and conditional content (e.g. for empty bundles or folders) |
| New       | You can now [restore deleted configurator drafts](/docs/fundamentals/creating-a-configurator#restore-deleted-drafts) within 30 days of deleting them                                                                                                                                                                                                           |
| New       | Publish a history version of a configurator directly (without having to create a draft), e.g. to roll back to the previous version when the current version causes unexpected problems                                                                                                                                                                         |
| New       | Simpler ways to open drafts and the live version of the configurator read-only                                                                                                                                                                                                                                                                                 |

### Release 23 Apr 24

Version `2.1.202404231`

| Type                                      | Description                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Improved error handling for data sources: [Asset errors](/docs/asset-management/getting-started-with-assets#errors-and-warnings) are shown per column and row directly in the data source preview now. This improves the general workflow of configuring data sources and reduces generic errors like `Cannot read 'Bool' value in data source` or similar. |

### Release 16 Apr 24

Version `2.1.202404163`

| Type                                      | Description                                                                                                                                                                                                                                                                                                    |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | "Signals & Slots" list in design editor also shows control properties which use Hive rules and is now called "Connections". This also includes: Easier spotting and navigation to erroneous Hive rules in control properties Improved visualization of the active filter in list |
| New | Previously selected control is automatically re-selected when entering the design editor                                                                                                                                                                                                                       |
| New | Large Hive editor is automatically opened when enabling Hive for a control property                                                                                                                                                                                                                            |
| New | Hive can now also be enabled for the `Font` property                                                                                                                                                                                                                                                           |
| Fix | "Ooops error" when hovering with the mouse over CSS classes in the custom CSS editor                                                                                                                                                                                                                           |
| Fix | Re-added code completion for [built in CSS classes](/docs/configurator-ui-ux/controls/control-dom-and-css-classes#label) of controls which were erroneously removed with introduction of Monaco editor                                                                                                         |
| Fix | Removed incorrectly shown scrollbars in design editor when selecting a control which caused unpleasant & irritating layout shifts                                                                                                                                                                              |
| Fix | Sometimes enabling Hive for a control property required 2 clicks                                                                                                                                                                                                                                               |

### Release 09 Apr 24

Version `2.1.202404091`

| Type                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Introduce `Custom code` as successor of `CustomJS` Greatly improves working with components in TypeScript New npm package [@combeenation/custom-code-utils](https://www.npmjs.com/package/@combeenation/custom-code-utils) which replaces [@combeenation/custom-js-utils](https://www.npmjs.com/package/@combeenation/custom-js-utils) Auto-generated typings (interface) file and automatic registration of components in code |

### Release 02 Apr 24

Version `2.1.202404021`

| Type                                      | Description                                                                                                                                         |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Button property "Hyperlink target" which allows more fine grained control over where the link should open (in new tab, same tab, parent frame, ...) |
| New | Improved cfgr draft preview (configurations will be persisted, edit/copy urls are now supported, ...)                                               |

### Release 20 Mar 24

Version `2.1.202403201`

| Type                                      | Description                                                      |
| ----------------------------------------- | ---------------------------------------------------------------- |
| Fix | Pinterest share button didn't work in some occasions             |
| Fix | Inconsistent behavior in the code editor when using save hotkeys |

### Release 18 Mar 24

Version `2.1.202403183`

| Type                                            | Description                                                                                                                                        |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | New code editor inside the configurator editor. Based on the so-called "Monaco editor" which is also used by VS Code.                              |
| New       | Button in table components to conveniently create a table selection component                                                                      |
| Change | 3d viewer control in design editor automatically reloads when asset bundle assignments of configurator are changed to always show the latest model |
| Fix       | Improved behavior for `Ctrl+z` in code editor. No more unexpected occurrence of code from other components etc.                                    |
| Fix       | Design editor was sometimes broken after changing asset assignments of configurator                                                                |

### Release 14 Mar 24

Version `2.1.202403141`

| Type                                      | Description                                                                                                                   |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Fix | "Oops error" after reconnecting a timed out session in configurator                                                           |
| Fix | Automatic activation of 3d viewer inspector in configurator preview when not possible due to usage of viewer production build |

### Release 13 Mar 24

Version `2.1.202403131`

| Type                                            | Description                                                                                                                                                                    |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New       | Add option to disable autofocusing camera when switching models in viewer control                                                                                              |
| New       | Fresh look for configurator preview header with new options Use local custom TS/JS Show SigSlo logs in the browser console |
| Change | When the Babylon inspector is shown in the configurator preview using the button in the preview header, it will be automatically re-shown after page refresh                   |
| Change | New browser tab titles, so that different ares like editor, assets, configurator preview etc. are easier to distinguish when developing a configurator with multiple tabs open |
| Fix       | Configurator preview watch results have not been updated anymore after session reconnect                                                                                       |

### Release 04 Mar 24

Version `2.1.202403041`

| Type                                            | Description                                                                                                                                                              |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New       | Asset Manager: UI displays asset [errors and warnings](/docs/asset-management/getting-started-with-assets#errors-and-warnings) to inform about problems in asset bundles |
| New       | Asset Manager: Now supports additional material types (like "StandardMaterial") for 3D model uploads                                                                     |
| Change | Redirect to home page instead of dashboard after login and other situations                                                                                              |
| Change | An asset bundle with errors can no longer be published                                                                                                                   |

### Release 22 Feb 24

Version `2.1.202402221`

| Type                                      | Description                                                                                                                                                                                                                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | A new [Text.encodeJson()](/docs/configurator-logic/hive-types/text-type#encodejson) function escapes reserved characters in a JSON text                                                                                                                                        |
| New | The [Number.toText()](/docs/configurator-logic/hive-types/number-type#totextformatlocale) function now accepts an optional [Locale](/docs/configurator-logic/hive-types/local-type) parameter to format a number according to that region (e.g. `Locale.de`, `Locale.fr` etc.) |

### Release 20 Feb 24

Version `2.1.202402201`

| Type                                            | Description                                                                                                                                                                                                    |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | Modernized the [whitelisted domain](/docs/integrations-and-api/embedding-and-whitelist#whitelisted-domains) settings on the embedding page                                                                     |
| Change | To make configurator draft previews behave more like published configurators, only updates of actively used components will now be sent (you can still use watches in the debug panel to access any component) |

### Release 13 Feb 24

Version `2.1.202402131`

| Type                                      | Description                      |
| ----------------------------------------- | -------------------------------- |
| Fix | Broken "forget password" feature |

### Release 12 Feb 24

Version `2.1.202402121`

| Type                                      | Description                                               |
| ----------------------------------------- | --------------------------------------------------------- |
| New | Show origin of 3d model in babylon asset preview          |
| New | Select nodes in babylon asset via picking mesh in preview |

### Release 08 Feb 24

Version `2.1.202402082`

| Type                                      | Description                                                                                                                                                                                           |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | [Optional chaining operator](/docs/configurator-logic/hive-language#optional-chaining-operator-) (`?.`) in Hive to only access properties / call functions when the current expression is not `empty` |
| New | You can now create [empty lists](/docs/configurator-logic/hive-types/list-type#empty-lists-) ( `[]`) in Hive. The type of the list will be inferred automatically.                                    |
| New | Hive variables are now fully supported in table component queries.                                                                                                                                    |

### Release 02 Feb 24

Version `2.1.202402021`

| Type                                      | Description                                                                  |
| ----------------------------------------- | ---------------------------------------------------------------------------- |
| New | Make viewer control loading mask texts adjustable                            |
| Fix | Viewer control loading mask gets hidden immediately when starting AR journey |

### Release 01 Feb 24

Version `2.1.202402011`

| Type                                      | Description                                                                                                                                                                                                                                                                                                                                    |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | New proprties `gap` & `padding` for container controls (panel, layer & wizard page). `padding` is also available for dataviews. Those new properties behave exactly the same as their CSS counterparts [gap](https://developer.mozilla.org/en-US/docs/Web/CSS/gap) & [padding](https://developer.mozilla.org/en-US/docs/Web/CSS/padding). |
| New | Change assigned material of any mesh in the babylon asset                                                                                                                                                                                                                                                                                      |
| New | Batch saving node changes (tags and material) in babylon asset                                                                                                                                                                                                                                                                                 |

### Release 24 Jan 24

Version `2.1.202401241`

| Type                                      | Description                                                             |
| ----------------------------------------- | ----------------------------------------------------------------------- |
| New | Welcome page                                                            |
| New | Advanced configurator templates with asset support                      |
| New | Asset tree view: Multi-select with `Ctrl` or `Shift` and bulk edit them |

### Release 9 Jan 24

Version `2.1.202401091`

| Type                                      | Description                                                                                                   |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| New | Self service account creation                                                                                 |
| New | Revamped invitation system                                                                                    |
| New | Auto save changes in design editor when page is left to go to configurator preview (or somewhere else)        |
| New | Prevent closing of page when there are unsaved changes in design editor                                       |
| Fix | Prevent changes in custom CSS to overwrite CSS variables which have been set by the `UpdateCssVariables` slot |

### Release 21 Dec 23

Version `2.1.202312211`

| Type                                      | Description                                                        |
| ----------------------------------------- | ------------------------------------------------------------------ |
| New | Add UI for configuring textures inside material asset basic editor |

### Release 12 Dec 23

Version `2.1.202312121`

| Type                                      | Description                                                                            |
| ----------------------------------------- | -------------------------------------------------------------------------------------- |
| New | You can now use [variables in Hive](/docs/configurator-logic/hive-language#variables)! |

### Release 21 Nov 23

Version `2.1.202311211`

| Type                                      | Description                                                                   |
| ----------------------------------------- | ----------------------------------------------------------------------------- |
| New | Preserve file names when downloading assets                                   |
| New | Add additional shopify parameters (Weight, WeightUnit & CategoryId)           |
| Fix | Changes in the asset draft are now always correctly applied to the cfgr draft |
| Fix | Fix problems with the viewer-only configurator creation                       |

### Release 08 Nov 23

Version `2.1.202311081`

| Type                                      | Description                                                                                                                                                                                                                                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fix | Introduce a [Url property](/docs/configurator-logic/components/graphic-component#archive-and-url) for `GraphicComponent` that is correctly updated e.g. when a configuration is copied. The `GetUrl()` function does not always update correctly and will be deprecated in a future release. |

### Release 07 Nov 23

Version `2.1.202311071`

| Type                                            | Description                                                                                                   |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| New       | Managers & admins can now manage company settings & [api tokens](/docs/integrations-and-api/combeenation-api) |
| Remove | Integration system (FTP, REST, Website, Magento)                                                              |
| Remove | Magento 2 shop                                                                                                |

### Release 06 Nov 23

Version `2.1.202311061`

| Type                                      | Description                                                                                                                                                                                                                           |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | You can now [sort](/docs/configurator-logic/hive-queries#sorting-data) the records returned by a data source query and/or [limit](/docs/configurator-logic/hive-queries#limiting-the-number-of-rows) how many records can be returned |

### Release 31 Oct 23

Version `2.1.202310311`

| Type                                            | Description                                                                                                                                                                                                                                                                               |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | Live-preview of 3d materials within the asset material editor                                                                                                                                                                                                                             |
| New       | Content of data sources can now be previewed directly in the asset editor                                                                                                                                                                                                                 |
| Change | Improved import of data sources based on excel files: General improvement how column types are detected Default values can be changed when "Auto config detection" is enabled Default values are now considered when auto detecting the type of a column |

### Release 24 Oct 23

Version `2.1.202310241`

| Type                                            | Description                                                                                                                                                                                                        |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Change | Color properties of material assets: Text input is now a hex color code More sophisticated color picker Correctly apply colors in the 3d model (automatic color space conversion) |

### Release 19 Oct 23

Version `2.1.202310194`

| Type                                            | Description                                                                                                                                                                                                                                                                                                                                                    |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Change | Various Babylon.js inspector adjustments: added button to start inspector from debug panel inspector renders outside configurator to keep configurator layout untouched various fixes due to [reworked integration in 3d viewer](https://3dviewer.docs.combeenation.com/pages/release-notes/releases/index.html#version-1000) |

### Release 17 Oct 23

Version `2.1.202310171`

| Type                                      | Description                                                                                                                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | Data source queries now support the `not` and `-` (negation) operator as well as all number functions (`toText`, `round`, `floor`, `ceiling`, `truncate`, `atLeast`, `atMost`) |

### Release 16 Oct 23

Version `2.1.202310161`

| Type                                      | Description                                              |
| ----------------------------------------- | -------------------------------------------------------- |
| New | Improve user experience for material asset expert editor |

### Release 11 Oct 23

Version `2.1.202310111`

| Type                                      | Description                                                                                                          |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| New | You can now target an existing configurator when copying a configurator to another company (a draft will be created) |
| New | A configurator draft will display a lock icon when another user is currently editing it.                             |

### Release 4 Oct 23

Version `2.1.202310042`

| Type                                      | Description                                                                                                         |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| New | [Copy configurators and asset bundles across companies](/docs/fundamentals/copying-configurators-and-asset-bundles) |

### Release 4 Oct 23

Version `2.1.202310041`

| Type                                      | Description                                                                                                                                                                                                     |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | [Custom layout](/docs/configurator-ui-ux/controls/dataview#custom-layout) property for dataviews which allows the user to further customize the appearance of dataview entries using a HTML templating language |
| New | Hive in controls enabled for [Entries](/docs/configurator-ui-ux/controls/dataview) & [Value](/docs/configurator-ui-ux/controls/dataview) property of dataviews & comboboxes                                     |
| New | New parameter for viewer [AR slot](/docs/configurator-ui-ux/controls/3d-viewer-control#start-ar) which allow customization of environment and loading screen logo                                               |
| Fix | Loading screen of the babylon asset preview sometime got stuck                                                                                                                                                  |
| Fix | Wrong assignment of texture image assets in babylon asset preview                                                                                                                                               |

### Release 17 Aug 23

Version `2.1.202308171`

| Type                                            | Description                                                                                                                                                                                                                                                                        |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | Collapsible sidebar in dashboard                                                                                                                                                                                                                                                   |
| New       | Allow deletion of configurator even if there are finished or shared configurations                                                                                                                                                                                                 |
| New       | New "sanitize value" checkbox in editor for certain control properties when "Hive in controls" is enabled for them (e.g. `label.Value`, `panel.HeaderText`, ...) which allows disabling of [User input sanitization](/docs/configurator-ui-ux/user-input-sanitization) when needed |
| Change | Improvements for Hive in controls: Better initial rule when enabling Hive support for `Visible` property When creating a control via drag & drop of a component, Hive in controls is used instead of SigSlo where possible |
| Fix       | Issues when continuing editing in a timed out session. E.g. new Hive rule is now correctly applied without having to reload the page or switching the selected component etc.                                                                                                 |
| Fix       | Zooming model in 3d viewer with mouse wheel does not scroll parent containers (like parent page) anymore                                                                                                                                                                           |

### Release 1 Aug 23

Version `2.1.202308011`

| Type                                      | Description                                                                                      |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| New | ⭐ Hive in controls. You can now write Hive logic in control properties.                         |
| Fix | The error indicator for TableComponents now correctly resets when an error in the query is fixed |

### Release 15 Jun 23

Version `2.1.202306151`

| Type                                            | Description                                                                                                                                     |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | Data source queries now allow columns to be [modified and new ones to be created](/docs/configurator-logic/hive-queries#projecting-data)        |
| Change | You may now use more operators, functions and if/then/else expressions in [query filters](/docs/configurator-logic/hive-queries#filtering-data) |

### Release 13 Jun 23

Version `2.1.202306131`

| Type                                            | Description                                                                        |
| ----------------------------------------------- | ---------------------------------------------------------------------------------- |
| New       | New [Shopify](/docs/integrations-and-api/checkout-types/shopify) shop              |
| New       | Provide cache for data sources to speed up queries                                 |
| Change | Rename DIY to [FLEX shop](/docs/integrations-and-api/checkout-types/flex-checkout) |
| Change | Minor fixes (trim whitespace during login, reorder shops types, ...)               |

### Release 01 Jun 23

Version `2.1.202306011`

| Type                                      | Description                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------- |
| New | Introduce [3D/AR viewer configurator](/docs/fundamentals/3d-ar-viewer) |

### Release 24 May 23

Version `2.1.202305241`

| Type                                      | Description                                              |
| ----------------------------------------- | -------------------------------------------------------- |
| New | Show / hide nodes in babylon asset preview               |
| Fix | Layering order (z-index) of modal dialogs and load masks |

### Release 10 May 23

Version `2.1.202305102`

| Type                                      | Description                                                                   |
| ----------------------------------------- | ----------------------------------------------------------------------------- |
| New | Custom date range picker for configurator metrics on dashboard                |
| New | Integrate documentation as dockable side panel (Doc360 Knowledge Base Widget) |

### Release 08 May 23

Version `2.1.202305081`

| Type                                      | Description                                                                                                                                                                                                                                                                                                                                                                     |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fix | "Oops error" when passing invalid tag manager values to 3d viewer control. This fix requires an update from [viewer v9.0.0](https://3dviewer.docs.combeenation.com/pages/release-notes/releases/index.html#version-900) to [v9.0.1](https://3dviewer.docs.combeenation.com/pages/release-notes/releases/index.html#version-901) which is performed automatically by the system. |

### Release 03 May 23

Version `2.1.202305031`

| Type                                      | Description                                                                                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Material parameters in viewer controls [Set parameter values](/docs/configurator-ui-ux/controls/3d-viewer-control#set-parameter-values) slot |

### Release 28 Apr 23

Version `2.1.202304281`

| Type                                      | Description                                                                                     |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
| New | [Start AR](/docs/configurator-ui-ux/controls/3d-viewer-control#start-ar) slot in viewer control |

### Release 27 Apr 23

Version `2.1.202304271`

| Type                                            | Description                                                                                                            |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| New       | [``Intersect` function`](/docs/configurator-logic/components/record-component#functions) for (record component) tables |
| Change | Update of all mail texts + links                                                                                       |

### Release 20 Apr 23

Version `2.1.202304201`

| Type                                            | Description                                          |
| ----------------------------------------------- | ---------------------------------------------------- |
| Fix       | Added support for viewer version 8 in viewer control |
| Remove | Remove Google Analytics from cfgr page               |

### Release 17 Apr 23

Version `2.1.202304171`

| Type                                      | Description                                    |
| ----------------------------------------- | ---------------------------------------------- |
| New | Create empty PbrMaterial assets                |
| New | Upload JSON files to create PbrMaterial assets |

### Release 13 Apr 23

Version `2.1.202304131`

| Type                                      | Description                                                                                                                                              |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | [API](/docs/configurator-ui-ux/controls/3d-viewer-control-with-custom-code) which allows the 3d viewer control to be used with custom JS                 |
| New | `__root__` nodes are now automatically renamed when converting a GLB to a babylon asset to prevent name clashes in the 3d viewer                         |
| New | Automatically remove unused "default material" from `__root__` node when converting GLB to a babylon asset to prevent bootstrap errors in viewer control |
| Fix | Bug when importing 3d assets with long material names which prevented creation of some material assets                                                   |

### Release 04 Apr 23

Version `2.1.202304041`

| Type                                      | Description                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------------ |
| New | ⭐ New UI for dashboard and its related pages                                  |
| New | Users with an existing account can be added to the company without invite mail |

### Release 30 Mar 23

Version `2.1.202303301`

| Type                                            | Description                                                                 |
| ----------------------------------------------- | --------------------------------------------------------------------------- |
| New       | ⭐ [Viewer 3d control](/docs/configurator-ui-ux/controls/3d-viewer-control) |
| Change | Every company now has asset support                                         |
| Change | Reduce workflow schedule interval to 1h                                     |

### Release 20 Mar 23

Version `2.1.202303202`

| Type                                      | Description                                  |
| ----------------------------------------- | -------------------------------------------- |
| New | Support creation of 3D assets from GLB files |

### Release 15 Mar 23

Version `2.1.202303151`

| Type                                      | Description                                                                      |
| ----------------------------------------- | -------------------------------------------------------------------------------- |
| New | Material names are now automatically corrected when a Babylon asset is uploaded. |

### Release 08 Mar 23

Version `2.1.202303081`

| Type                                      | Description                                                                                                                                                          |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | The new [text asset](/docs/asset-management/text-asset) can store large textual content that can be used in the configurator editor (unlike a file asset's content). |

### Release 06 Mar 23

Version `2.1.202303061`

| Type                                      | Description                              |
| ----------------------------------------- | ---------------------------------------- |
| New | 3D Preview for babylon assets introduced |

### Release 27 Feb 23

Version `2.1.202302271`

| Type                                      | Description                                                                                              |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| New | Tag editor for babylon assets introduced                                                                 |
| Fix | Table components are now always updated correctly when adding or removing columns from their data source |

### Release 01 Feb 23

Version `2.1.202302011`

| Type                                      | Description                                                                  |
| ----------------------------------------- | ---------------------------------------------------------------------------- |
| New | [Workflows](/docs/integrations-and-api/workflows/workflow-basics) introduced |

### Release 05 Dec 22

Version `2.0.202212051`

| Type                                            | Description                                                                 |
| ----------------------------------------------- | --------------------------------------------------------------------------- |
| New       | New [Shopware 6](/docs/integrations-and-api/checkout-types/shopware-6) type |
| Change | New default JSON structure for DIY shop                                     |

### Release 10 Oct 22

Version `2.0.202210101`

| Type                                      | Description                                                                                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Support the creation of data source assets based on Excel file assets. Updates on file assets will be propagated to all linked data sources. |

### Release 29 Sep 22

Version `2.0.202209291`

| Type                                      | Description                                                                                                                                                                                      |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | Improve performance of TableComponent queries. Long-running operations, like loading data from a DataSource, are now scheduled more intelligently to reduce waiting times in configurators. |

### Release 27 Sep 22

Version `2.0.202209271`

| Type                                      | Description                                                                                                                                                                            |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | ⭐ Support for Babylon & PbrMaterial assets See [How to create and use babylon & material assets](/docs/asset-management/3d-and-material-assets/basic-workflow) for more details! |
| New | ⭐ Asset upload dialog provides options to change the suggested name & choose different target folders per asset                                                                       |

Related releases:

- [3d Viewer v5.1.0](https://3dviewer.docs.combeenation.com/pages/release-notes/releases/release-notes/version-details/5-0-1.html)
- [CustomJS utils v6.1.0](https://cjs.docs.combeenation.com/pages/Documentation/releases.html#version-610)

### Release 11 Aug 22

Version `2.0.202208111`

| Type                                      | Description                                                                                                                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Simplify reading & writing of components in CustomJS ([custom-js-utils v6](https://cjs.docs.combeenation.com/pages/Documentation/releases.html#version-600) or higher) |

### Release 9 Aug 22

Version `2.0.202208091`

| Type                                      | Description                                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
| New | Search field above controls tree                                                                  |
| New | Quick launcher (`Ctrl+K`) also shows controls when inside design editor                           |
| New | Option in quick launcher to only show components or controls in search result                     |
| Fix | Re-select control in tree after renaming it even when control is inside inactive wizard page etc. |

### Release 19 Jul 22

Version `2.0.202207191`

| Type                                      | Description                    |
| ----------------------------------------- | ------------------------------ |
| New | Excel support for data sources |

### Release 7 Jul 22

Version `2.0.202207071`

| Type                                      | Description                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | `SetEntries` slot of dataviews & comboboxes now also support CSS colors like hex codes (e.g. `#009a92`) or RGB values (e.g. `rgb(0, 154, 299)`) in addition to Hive images. I.e. stuff like `"#009a92".ToColor().ToImage()` should not be needed anymore in this area and color values from CSV asset data sources can now be used as well. |

### Release 6 Jul 22

Version `2.0.202207062`

| Type                                            | Description                                                                                                                                                 |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | `Ctrl+S` in code editors (hive rule, control properties, CSS editor etc.) saves the current changes and does not show the browsers "Save as" dialog anymore |
| Change | `Shift+Enter` in CSS & control property editor of design component immediately saves changes                                                                |
| Fix       | Sneak peek in design and graphic component shows design resp. graphic instead of global editor background                                                   |
| Fix       | Sneak peek sometimes got stuck                                                                                                                              |

### Release 6 Jul 22

Version `2.0.202207061`

| Type                                      | Description                                                                       |
| ----------------------------------------- | --------------------------------------------------------------------------------- |
| Fix | Browser back & forth navigation in asset editor was sometimes not working anymore |

### Release 30 Jun 22

Version `2.0.202206301`

| Type                                            | Description                                                                                                                                        |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | The Size of File Assets and DataSources is now displayed in the Asset Editor (existing assets must be re-uploaded first).                          |
| New       | The Asset Bundle Assignment dialog now displays more relevant information, like the version name (existing assignments must be updated first).     |
| New       | You can now open a specific Asset Bundle version directly from the Asset Bundle Assignment dialog.                                                 |
| New       | When you select an assigned Asset Bundle version, all versions of that bundle are now shown.                                                       |
| Change | In the Asset Editor, Asset Bundle versions are now sorted by when they were last changed, the newest version is on top and selected by default.    |
| Change | All Asset Folders are now collapsed by default.                                                                                                    |
| Change | When editing a DataSource configuration, you can now press the Enter key to insert a new line without closing the dialog.                          |
| Fix       | If you make a mistake when editing a DataSource configuration, you now get a more helpful message.                                                 |
| Fix       | Asset Bundle drafts are automatically created whenever you make any change to a published version – this didn't work in a few cases, but now does. |

### Release 20 Jun 22

Version `2.0.202206201`

| Type                                      | Description                                                                                                                                                                                                                                                                                   |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | ⭐ Assets (preview feature) File and Image Assets can now be uploaded and used in configurators Assets can be organized in Folders Assets can be renamed, copied and deleted Assets can be referenced in DataSources with the new LinkedAsset column |

### Release 13 Jun 22

Version `2.0.202206131`

| Type                                            | Description                                 |
| ----------------------------------------------- | ------------------------------------------- |
| Remove | Custom ID functionality no longer available |

### Release 30 Mar 22

Version `2.0.202203303`

| Type                                            | Description                                                                                                                                                                                                                                                        |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New       | ⭐ Assets (preview feature) Import files or resources on company-level to use them inside configurators Manage asset bundles Upload CSV-files as `DataSource` assets Query `DataSource` assets with the new `TableComponent` |
| New       | ⭐ First page (Asset editor) based on the new front-end stack with React                                                                                                                                                                                           |
| Change | The cursor of comboboxes is now a `pointer` instead of `text` when hovered                                                                                                                                                                                         |

### Release 8 Feb 22

Version `2.0.202202081`

| Type                                            | Description                                            |
| ----------------------------------------------- | ------------------------------------------------------ |
| New       | Configurator company theme for new Combeenation CI     |
| Change | End user file upload limit increased from 50 to 100 MB |

### Release 31 Jan 22

Version `2.0.202201311`

| Type                                      | Description                                                                             |
| ----------------------------------------- | --------------------------------------------------------------------------------------- |
| Fix | Incorrect SigSlo validation errors shown for SigSlos connected to ShapeDiver 3d control |
| Fix | Record component editor breaks sometimes after auto formatting                          |

### Release 22 Dez 21

Version `2.0.202112221`

| Type                                      | Description    |
| ----------------------------------------- | -------------- |
| New | .NET 6 release |

### Release 16 Dez 21

Version `2.0.202112161`

| Type                                      | Description                                                                                                                                                                 |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | ⭐ Compare Mode: A draft or version can now be compared to any other version of the same company. It can be started from any editor with the button in the top-left corner. |
| New | Components can now be filtered by their type (see menu of the `Components-List` in the editor). The results can be further filtered with the default text-search.           |
| New | Show the draft name in the top-left of the editor                                                                                                                           |
| Fix | Company settings window is now scrollable to prevent cut off elements                                                                                                       |

### Release 14 Dez 21

Version `2.0.202112141`

| Type                                      | Description                                                                           |
| ----------------------------------------- | ------------------------------------------------------------------------------------- |
| Fix | Fixed Shapediver Embedded control having wrong initial parameter values in rare cases |

### Release 29 Nov 21

Version `2.0.202111291`

| Type                                            | Description                                                                                                                                                                                                                                          |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fix       | `Index` parameter of list slots `Add Item` & `Remove Item` are working correctly again.                                                                                                                                                              |
| Change | Available component slots are now chosen based on the component's input type instead of its result type. E.g. a value component with input type `text` which results in a record can now be used as `Set value` slot which was not possible earlier. |
| New       | ⭐ Slot parameters can now directly access column data of value components resulting in a record, which only worked with record components earlier. E.g. `SomeValueCmp.ValueChanged -> PriceLabel.setValue(SomeValueCmp.coldata.price)`.             |
| New       | The configurator slot `updateCssVariables` now accepts records from any source, previously it only worked with record components.                                                                                                                    |
| New       | ⭐ Better visualization for complex component results like records or lists                                                                                                                                                                          |

### Release 29 Sep 21

Version `2.0.202109291`

| Type                                            | Description                                                                  |
| ----------------------------------------------- | ---------------------------------------------------------------------------- |
| Change | ⭐ Revamped [User Permissions](/docs/fundamentals/user-permissions)          |
| New       | Show "Uploaded at" date & time in resource component                         |
| Fix       | Fixed reconnect issues in rare cases (e.g. when creating a new `CSS Module`) |

### Release 18 Aug 21

Version `2.0.202108181`

| Type                                            | Description                                                                     |
| ----------------------------------------------- | ------------------------------------------------------------------------------- |
| New       | Copy drafts across companies (additional drop-down list in the existing dialog) |
| Change | Search fields can be cleared with the `Esc` key                                 |

### Release 8 Jul 21

Version `2.0.202107081`

| Type                                      | Description                                                                                                                                                                                                                                                   |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | 2 responsive templates in the "create configurator" dialog                                                                                                                                                                                                    |
| New | ⭐ Possibility to create PDFs from "self written" HTML and upload them to a resource component. See [CfgrUtils.convertHtmlToPdf](https://cjs.docs.combeenation.com/classes/cfgrutils.html#converthtmltopdf) in CustomJS utils for details on how to use this. |

### Release 23 Jun 21

Version `2.0.202106231`

| Type                                            | Description                                                                                                                                                                              |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Change | ⭐ Revamped configurator dashboard (formerly known as gallery), now contains views for all companies/configurators/drafts, company/configurator settings and a new cfgn metrics overview |
| New       | New property `price` for all shops. The price of the finish (if set) will be taken into account for the `Total Revenue` calculation                                                      |
| Fix       | Textbox caption wasn't correctly positioned when set to "Top"                                                                                                                            |
| Fix       | Users no longer need to logout/login in order to see company assignment changes (e.g. added or removed from a company)                                                                   |
| Change | Ungzipped Babylon files will be gzipped on upload                                                                                                                                        |

### Release 11 Mai 21

Version `2.0.202105111`

| Type                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fix       | Fix issue which sometimes caused the configurator to change wizard pages "on its own" in an "infinite loop". This was mainly an issue when on a bad internet connection. It can still happen that the configurator changes wizard pages "on its own" but this should now stop quite quick and should not end in an "infinite loop" anymore.                                                                        |
| Fix       | Design editor: Some properties with dropdown-values showed only the id instead of the display name                                                                                                                                                                                                                                                                                                                           |
| Change | Improved visualization of `preview/transient mode` and `read-only mode` in the cfgr editor                                                                                                                                                                                                                                                                                                                                   |
| Change | Several improvements and design changes as follow-up of the redesign: Blue background for configurator editor "landing page" as well Reskinned "browser not supported page" Adjust upper alignment of component editors main panel and property lists Hide "zoom control" for default view in the configurator editor background whenever a component editors main panel is visible |

### Release 26 Apr 21

Version `2.0.202104261`

| Type                                            | Description                                                                                                                                           |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Change | Avoid showing Shapediver load timeout error if no viewer version is configured                                                                        |
| Change | In addition to the Redis cache, sessions are now stored in the CosmosDb. Possible Redis cache troubles should no longer disrupt users in the backend. |

### Release 21 Apr 21

Version `2.0.202104211`

| Type                                      | Description                                                                                                                                                                                            |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New | Company theme for "Palme" (green loading animation, ...)                                                                                                                                               |
| New | Automatically remove leading & trailing whitespaces (blanks, new lines etc.) from resource name given to `Upload user resource` slot to prevent accidental and hard to solve "ResourceNotFound" errors |
| Fix | Prevent exception when opening configurator in hidden Firefox tab                                                                                                                                      |

### Release 14 Apr 21

Version `2.0.202104141`

| Type                                            | Description                                                                         |
| ----------------------------------------------- | ----------------------------------------------------------------------------------- |
| Change | Improved changing of combobox values in the Components- and Properties-List         |
| Change | Component-List entries use the whole row width when only the name is shown          |
| Change | Allow text selection in the result panel of Records                                 |
| Fix       | Issues when combobox values weren't correctly commited                              |
| Fix       | Prevent exception when leaving the Design Editor with a Shapediver Embedded control |

### Release 12 Apr 21

Version `2.0.202104121`

| Type                                      | Description                                               |
| ----------------------------------------- | --------------------------------------------------------- |
| Fix | Load mask did not disappear when preparing social sharing |

### Release 4 Apr 21

Version `2.0.202104071`

| Type                                      | Description                                                                                                                 |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| New | Added new properties `CSS Class`, `Over viewer only` and `Hide On` for customizing load mask of Shapediver Embedded Control |

### Release 16 Mar 21

Version `2.0.202103161`

| Type                                            | Description                                                                                                                                                          |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Change | Social Sharing: Added platforms and reworked default button design See [Social share](/docs/configurator-ui-ux/controls/social-share) for detailed information. |

### Release 11 Mar 21

Version `2.0.202103113`

| Type                                            | Description                                                             |
| ----------------------------------------------- | ----------------------------------------------------------------------- |
| New       | Support for new file types in 3d asset resource component: _.stl, _.obj |
| Remove | Removed debug controls container for Shapediver Embedded Control        |

### Release 9 Mar 21

Version `2.0.202103092`

| Type                                      | Description                                                    |
| ----------------------------------------- | -------------------------------------------------------------- |
| New | Added debug controls container for Shapediver Embedded Control |

### Release 2 Mar 21

Version `2.0.202103021`

| Type                                      | Description                                                                        |
| ----------------------------------------- | ---------------------------------------------------------------------------------- |
| Fix | Transition time was not applied when updating camera position in Shapediver viewer |

### Release 26 Feb 21

Version `2.0.202102262`

| Type                                            | Description                                                                                                      |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Change | Shapediver Embedded Control now uses Shapediver API Version V2                                                   |
| Fix       | When a record column was named 'ID' and contained identical values, it led to missing entries in the result-view |

### Release 17 Feb 21

Version `2.0.202102171`

| Type                                      | Description                   |
| ----------------------------------------- | ----------------------------- |
| New | Redesign of the whole backend |

### Release 16 Dec 20

Version `1.26.202012161`

| Type                                      | Description                                             |
| ----------------------------------------- | ------------------------------------------------------- |
| New | New signal `Selected key changed` for record components |

### Release 9 Dec 20

Version `1.26.202012091`

| Type                                      | Description                                                                                              |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| New | New slot `Set caption text` for comboboxes                                                               |
| New | Support for new file types in 3d asset resource component: `*.step`, `*.stp`, `*.hdr` & `*.babylon` |

### Release 13 Aug 20

Version `1.25.202008131`

| Type                                            | Description                             |
| ----------------------------------------------- | --------------------------------------- |
| Change | Increased draft limit from 5 to 10      |
| Change | Increased upload limit from 10 to 50 MB |

### Release 9 Jul 20

Version `1.25.202007088`

| Type                                            | Description                                        |
| ----------------------------------------------- | -------------------------------------------------- |
| Change | Major server improvements (Docker, .NET Core, ...) |
| New       | Whitelist settings for configurators               |
| Remove | Social login buttons removed                       |

### Release 26 Jun 20

Version `1.25.19`

| Type                                            | Description                                                                                                                                                                                          |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Change | "Non admin" users are now also allowed to delete withdrawn configurators                                                                                                                             |
| New       | Highlighting for `dev` drafts in configurator gallery which have not been edited for a long time (@fa-pencil = `dev` draft exists, @fa-pencil = 2 months untouched, @fa-pencil = 6 months untouched) |

### Release 7 Mai 20

Version `1.25.17`

| Type                                            | Description                                                                                          |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Change | Icons to highlight published configurators and configurators with existing `dev` draft(s) in gallery |

### Release 6 Feb 20

Version `1.25.3`

| Type                                      | Description                                                                                                           |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Fix | When creating a new control via DnD of component, oftentimes an error was shown and SigSlos were not created properly |

### Release 27 Jan 19

Version `1.25.0`

| Type                                            | Description                                                                                                                                                                  |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Change | ⭐ New parameter `Sanitize Value` for various `SigSlo` slots. See [User input sanitization](/docs/configurator-ui-ux/user-input-sanitization) for detailed information. |
| New       | ⭐ Improved support for [CSS custom properties (CSS Variables)](/docs/configurator-ui-ux/custom-css/css-properties-variables)                                                |
| New       | New function `CtrlUtils.onInteractiveVisualClicked` in custom JS API                                                                                                         |
| Fix       | Issue with slider control when settings its value to "0"                                                                                                                     |

### Release 2 Aug 19

Version `1.24.87`

| Type                                            | Description                                                                       |
| ----------------------------------------------- | --------------------------------------------------------------------------------- |
| New       | Support for `*.js.gz` files                                                       |
| Change | JavaScript files (`*.js`) will be gzipped and renamed (to `*.js.gz` ) upon upload |
| Change | GLB files (`*.glb`) will be gzipped unless they are already gzipped               |
| Fix       | The tab for the finishes result values will displayed again                       |

### Release 03 Jul 19

Version `1.24.80`

| Type                                            | Description                                                                                                                                                                                                                                                                            |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | Improvements for `Debug view` in configurator preview: New button `Use local custom JS` in control panel which adds `uselocalcjs=true` URI param Monospaced font for Watches panel Options to copy watch result to clipboard, word wrap & prettify it |
| New       | Property `Viewer version` for `ShapeDiver3dEmbedded` ctrl which can be set via SigSlo. Should be used instead of property `Viewer JS` from now on.                                                                                                                                     |
| Change | Drafts can now be copied from 1 configurator into another already existing one. Until now copying of drafts was only allowed to a new configurator or inside the currently selected configurator.                                                                                      |
| Fix       | Properties `Zoom min` & `Zoom max` of `ShapeDiver3dEmbedded` control were not working as expected                                                                                                                                                                                      |
| Change | Maximum size for archived images increased to 5000px in height 5000px in width                                                                                                                                                                                                         |

### Release 23 May 19

Version `1.24.73`

| Type                                            | Description                                                                                       |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Change | [Shopware shop](/docs/integrations-and-api/checkout-types/shopware-6) now supports price per unit |

### Release 28 Apr 19

Version `1.24.64`

| Type                                            | Description                                                                                                                                                                                                                     |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | New slots `Set background` for labels & `Set link URL` for buttons                                                                                                                                                              |
| New       | New API methods `Cbn.utils.TextHelper.btoaUTF8` & `Cbn.utils.TextHelper.atobUTF8` which shall be used in custom JS when converting text (e.g. SVG) to base64 and vice verca instead of erroneous `window.atob` & `window.btoa`. |
| Change | Updated Combeenation logo which is shown at the bottom of configurators which have plans for which the ad is shown.                                                                                                             |

### Release 24 Apr 19

Version `1.24.62`

| Type                                      | Description                                                                          |
| ----------------------------------------- | ------------------------------------------------------------------------------------ |
| New | Add new resource component type `3D assets` (Currently supported: gzipped GLB files) |

### Release 2 Apr 19

Version `1.24.52`

| Type                                      | Description                                                                                                                                                                                                                                                               |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Add new type [Hash](/docs/configurator-logic/hive-types/hash-type) with the methods [computeSha256](/docs/configurator-logic/hive-types/hash-type#computesha256-function) & [computeHmacSha256](/docs/configurator-logic/hive-types/hash-type#computehmacsha256-function) |
| New | Add new text method [IsBase64()](/docs/configurator-logic/hive-types/text-type#isbase64)                                                                                                                                                                                  |

### Release 20 Mar 19

Version `1.24.42`

| Type                                      | Description                                                                        |
| ----------------------------------------- | ---------------------------------------------------------------------------------- |
| New | [QRCode.generate()](/docs/configurator-logic/hive-types/qr-code#generate-function) |

### Release 12 Mar 19

Version `1.24.41`

| Type                                            | Description                                                                                                          |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Fix       | Fix zooming of graphic views with mouse wheel in Firefox & IE                                                        |
| New       | [Combeenation API](/docs/integrations-and-api/combeenation-api)                                                      |
| Change | Product version retention time (keep all versions which are not older than 2 months and always at least 50 versions) |

### Release 8 Jan 19

Version `1.24.0`

| Type                                            | Description                                                                                                                                                                                                                                                                                                               |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | Custom CSS modules which allow splitting of custom CSS into separate modules                                                                                                                                                                                                                                              |
| New       | Slot `Set placeholder` for textboxes & comboboxes                                                                                                                                                                                                                                                                         |
| Change | Minor improvements to design editor: Deselect all controls when pressing the `alt` key Submit `add control` dialog by `Ctrl+Enter` Multi line text values in property lists cannot be edited anymore with the lists single line inline editor since that lead to loss of all line breaks |

### Release 2 Jan 19

Version `1.23.5`

| Type                                      | Description                       |
| ----------------------------------------- | --------------------------------- |
| New | "Notes" property for all controls |

### Release 29 Nov 18

Version `1.23.3`

| Type                                            | Description                                                      |
| ----------------------------------------------- | ---------------------------------------------------------------- |
| Change | Version history UI updated and minor UI changes on draft list    |
| New       | Added button for showing an embedded example of the configurator |

### Release 6 Oct 18

Version `1.23.2`

| Type                                      | Description                                                                                                                         |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| New | Slot [Redirect parent page](/docs/configurator-ui-ux/controls/configurator-control#redirect-parent-page) for `Configurator` control |
| Fix | Slot `Set embed ticket` for `ShapeDiver3dEmbedded` control wasn't working properly                                                  |

### Release 25 Oct 18

Version `1.23.1`

| Type                                            | Description                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | Control `ShapeDiver3dEmbedded` for new ShapeDiver viewer can now be created using the "add control" dialog                                                                                                                                                                                                                                  |
| New       | [⭐ New Configurator control](/docs/configurator-ui-ux/controls/configurator-control) which holds some useful signals & slots to [handle IFrame sizes](/docs/configurator-ui-ux/controls/configurator-control#iframe-size), [restart configurations](/docs/configurator-ui-ux/controls/configurator-control#restart-configuration) and more |
| Change | [⭐ Improved checkout workflow](/docs/integrations-and-api/checkout)                                                                                                                                                                                                                                                                        |
| New       | System texts like `Adding configuration to cart...`, `Reconnecting...` or `Update available` can now be customized per configurator                                                                                                                                                                                                         |
| Fix       | Slot `SetHorizOffset` didn't work when layer was hidden                                                                                                                                                                                                                                                                                     |

### Release 10 Oct 18

Version `1.22.0`

| Type                                            | Description                                          |
| ----------------------------------------------- | ---------------------------------------------------- |
| Fix       | Add missing slot `Set visibility` to slider ctrl     |
| Fix       | Fixed several security issues                        |
| Change | New password policy (password update is recommended) |

### Release 1 Oct 18

Version `1.21.7`

| Type                                            | Description                                                                                       |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Change | [⭐ Updated list of officially supported browsers](/docs/integrations-and-api/supported-browsers) |
| Fix       | Selection of interactive visuals didn't work anymore in Edge                                      |

### Release 5 Sep 18

Version `1.21.2`

| Type                                      | Description                                                                                         |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
| New | Highlighting of names column for erroneous properties in value, graphic, resource & checkout editor |
| Fix | Dataviews sometimes didn't fire "Value changed" signal correctly                                    |
| New | Property "CommPluginSettings" for embedded ShapeDiver3d control                                     |

### Release 28 Aug 18

Version `1.21.0`

| Type                                            | Description                                                                                                                                                                                                                     |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | All Hive errors now indicate in which rule they originally occurred. Previously, some errors did not, which made it difficult to figure out what caused them.                                                              |
| Change | The ComponentList now only highlights components in which an error originates. Indirectly affected components will no longer be highlighted to make it simpler to find the root cause of a problem.                        |
| Change | Overhauled all Hive error messages to make them less verbose and more understandable. Type names will now be written into separate lines. Previously, long inline type names made some error messages unreadable.               |
| New       | Error messages about type mismatches now contain hints about the parts of a type that are not compatible. For example, if two tables do not match, the message will only mention the affected columns and omit all others. |

### Release 7 Aug 18

Version `1.20.45`

| Type                                            | Description                                                                                                     |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Change | New favicon for backend & configurator                                                                          |
| New       | New keyboard shortcut `Ctrl+Alt+Up/Down` for code editor to add new cursor in line above/below                  |
| New       | Button in configurator preview debugger to get current camera position & parameter info of ShapeDiver3d control |
| New       | Property & slot to set camera position of ShapeDiver3d control                                                  |
| New       | Text field in design editors `Add control` dialog to set initial name of newly created control                  |
| Fix       | Prevent copying of control to invalid position. E.g. wizardpages can only be pasted as childs of wizards etc.   |
| Fix       | Correctly apply background color for ShapeDiver3d ctrl                                                          |

### Release 28 Jun 18

Version `1.20.40`

| Type                                      | Description                                                                                           |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Fix | The `Set content URL` slot of the external content control didn't work when calling it multiple times |

### Release 11 Apr 18

Version `1.20.35`

| Type                                      | Description                                                       |
| ----------------------------------------- | ----------------------------------------------------------------- |
| Fix | ComboBoxes sometimes didn't fire "Value changed" signal correctly |
| New | Add handling for session timeout of "old" SD viewer               |

### Release 6 Apr 18

Version `1.20.34`

| Type                                      | Description                                               |
| ----------------------------------------- | --------------------------------------------------------- |
| Fix | Setting checkbox caption via SigSlo sometimes didn't work |
| New | New slot "Set caption text" for textboxes                 |

### Release 28 May 18

Version `1.20.32`

| Type                                            | Description                                    |
| ----------------------------------------------- | ---------------------------------------------- |
| Change | Rasterization will be done via ChromeBeeverter |

### Release 20 Apr 18

Version `1.20.30`

| Type                                            | Description                                                                       |
| ----------------------------------------------- | --------------------------------------------------------------------------------- |
| Remove | Mail share option from share button. You can still share configurations via mail. |

### Release 19 Apr 18

Version `1.20.29`

| Type                                      | Description                                  |
| ----------------------------------------- | -------------------------------------------- |
| Fix | Whitespace in SVG text will now be preserved |

### Release 11 Apr 18

Version `1.20.27`

| Type                                      | Description                                                           |
| ----------------------------------------- | --------------------------------------------------------------------- |
| Fix | Slot "Set header text" didn't work correctly under some circumstances |
| New | New properties "Zoom min" & "Zoom max" for ShapeDiver3d control       |

### Release 9 Apr 18

Version `1.20.26`

| Type                                            | Description                                                                                                                                                                              |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fix       | Certain style issues with older Safari versions (mainly \<\= v9): Centering of text in buttons Background of RadioButtons with "Looks like button" property set |
| Fix       | Page panning on touch devices above GraphicView with zoom & pan disabled                                                                                                                 |
| Change | Textboxes "typing" signal has been removed and "value changed" acts a little different now since it is also triggered a short while after the user stopped typing                        |

### Release 13 Mar 18

Version `1.20.20`

| Type                                      | Description                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------ |
| New | [REST checkout](/docs/integrations-and-api/checkout-types/rest-checkout) |

### Release 22 Feb 18

Version `1.20.15`

| Type                                            | Description                                                                                                                                           |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | New properties for the `ShapeDiver3d` control: `Restrict camera`, `Restrict pan`, `Control damping`, `Zoom speed`, `Viewer version` & `Show controls` |
| New       | New slots for the `ShapeDiver3d` control: `Set viewer version` & `Show/hide controls`                                                                 |
| Change | Slots to set the `ShapeDiver3d` control parameters are now shown in alphabetical order                                                                |

### Release 20 Feb 18

Version `1.20.13`

| Type                                      | Description                                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------------------------------- |
| New | Add message hash to [Flex checkout](/docs/integrations-and-api/checkout-types/flex-checkout) |

### Release 7 Feb 18

Version `1.20.5`

| Type                                      | Description                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------- |
| New | New draft properties `CreatedBy`, `LastPreviewedBy`, `LastPreviewedAt` |

### Release 6 Feb 18

Version `1.20.4`

| Type                                      | Description                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------- |
| New | Signal "Enter pressed" for textboxes                                   |
| New | [FTP checkout](/docs/integrations-and-api/checkout-types/ftp-checkout) |

### Release 1 Feb 18

Version `1.20.3`

| Type                                            | Description                                                                                                  |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Remove | Removed the `plan` keyword (use `configurator` instead)                                                      |
| Remove | Removed `GetEditLink` and `GetCopyLink` functions from `configuration` (use `EditUrl` and `CopyUrl` instead) |

### Release 24 Jan 18

Version `1.20.2`

| Type                                            | Description                                                                                               |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Fix       | Controls which were disabled by SigSlo were erroneously enabled when a parent panel was enabled by SigSlo |
| Fix       | Controls filter of SigSlo connections list wasn't always working correctly                                |
| Fix       | Entered text sometimes disappeared when focus was removed from textbox with connected "typing" signal     |
| Fix       | Adding components per drag & drop to the configurator in the design component sometimes didn't work       |
| Change | Adjusted embedding info in presets view                                                                   |

### Release 21 Dec 17

Version `1.20`

| Type                                            | Description                                                                                                                            |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| New       | [⭐ Introducing the # Operator](/docs/releases/release-1200)                                                                           |
| New       | New variables [configurator](/docs/releases/release-1200#general-features) and [presets](/docs/releases/release-1200#general-features) |
| New       | Text functions `contains` and `replace`                                                                                                |
| Change | Text comparison is now [case sensitive](/docs/releases/release-1200#changes-to-text-in-hive)                                           |
| New       | Case insensitive [`Text comparison operator `~=``](/docs/releases/release-1200#changes-to-text-in-hive)                                |
| New       | [DynamicVisual Items](/docs/releases/release-1200#new-dynamicvisual-items)                                                             |
| New       | Multi-line comments                                                                                                                    |
| Change | Improved Hive [Error Messages](/docs/releases/release-1200#more-helpful-hive-errors)                                                   |
| New       | New properties "Busy graphic URL" & "Busy graphic pos." for ShapeDiver3d control                                                       |
| Change | `Configurator` component is now called `Design`                                                                                        |

### Release 15 Dec 17

Version `1.19.5`

| Type                                      | Description                                                                                               |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| New | New property "Custom URI parameter" for ShapeDiver control (e.g. to set custom ShapeDiver viewer version) |

### Release 7 Dec 17

Version `1.19.2`

| Type                                      | Description                                                  |
| ----------------------------------------- | ------------------------------------------------------------ |
| Fix | Some SVGs were not drawn anymore in latest Chrome version 63 |

### Release 6 Dec 17

Version `1.19.1`

| Type                                      | Description                                                                                |
| ----------------------------------------- | ------------------------------------------------------------------------------------------ |
| New | Zoom & pan of graphic view on touch devices with pinch to zoom                             |
| New | ShapeDiver3d control parameters are now initialised with configuration values from SigSlos |

### Release 12 Oct 17

Version `1.18.0`

| Type                                            | Description                                                                                    |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| New       | Visuals from nested GraphicComponents can now be used as interactive visuals in a graphic view |
| Change | Groups in component list with many components are now collapsed by default                     |
| Fix       | Some minor issues in quick launcher                                                            |

### Release 5 Oct 17

Version `1.17.2`

| Type                                      | Description                                                |
| ----------------------------------------- | ---------------------------------------------------------- |
| Fix | Show preview images for SVG images uploaded in storage tab |

### Release 28 Sep 17

Version `1.17.1`

| Type                                      | Description                                           |
| ----------------------------------------- | ----------------------------------------------------- |
| Fix | Show details for "non image" resources in storage tab |

### Release 19 Sep 17

Version `1.17.0`

| Type                                            | Description                                                                                         |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| New       | Magento 2 shops are now supported                                                                   |
| New       | Create drafts based on other drafts and on older versions (tooltip shows the based on version)      |
| New       | New "Selected" & "Deselected" signal for checkboxes                                                 |
| Change | Updated publish dialog, warning will be displayed if recently published changes will be overwritten |
| Change | Show info message if a deleted draft is opened in preview                                           |
| Change | Drafts are now sorted by their name                                                                 |
| Change | Warning will be shown if a draft gets deleted                                                       |
| Fix       | SVG rasterization fixed, backgrounds are now transparent again                                      |

### Release 17 Aug 17

Version `1.16.0`

| Type                                            | Description                                                                |
| ----------------------------------------------- | -------------------------------------------------------------------------- |
| New       | [⭐ Introducing Drafts](/docs/fundamentals/creating-a-configurator#drafts) |
| Change | Restore your deleted configurators up to seven days                        |

### Release 10 Aug 17

Version `1.15.0`

| Type                                      | Description                                                                                                     |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| New | "Select text" parameter for "Set Focus" slot of textboxes                                                       |
| New | Dynamic signals for output parameters of ShapeDiver3d control                                                   |
| New | Properties for horizontal & vertical alignment of text inside buttons, panel headers, checkboxes & RadioButtons |
| New | Property "Looks like button" for checkboxes & RadioButtons                                                      |
| Fix | Clicking on a graphic view removes focus from currently active element                                          |

### Release 1 Aug 17

Version `1.14.33`

| Type                                      | Description                                                                                |
| ----------------------------------------- | ------------------------------------------------------------------------------------------ |
| New | Documentation of controls DOM & CSS classes                                                |
| New | SigSlos are automatically updated when renaming a control                                  |
| New | Controls can be copied in configurator editor                                              |
| New | More auto completions for custom CSS (built in classes, custom classes from controls etc.) |

---

## Release Notes

### Release 2 Nov 26

| Type                                      | Description                                                                                                                                                                                                     |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | [AI code assist](/docs/ai/getting-started-with-ai#ai-assistants-on-the-platform) for [PDF assets](/docs/asset-management/pdf-asset) and [workflow](/docs/integrations-and-api/workflows/workflow-in-depth) code |
| New | [MCP server](/docs/ai/mcp-server): connect your AI agent to Combeenation so it can explore your configurator and make changes to its drafts                                                                     |
| New | [AI skills](/docs/ai/ai-skills): give your AI agent in-depth knowledge of Hive and Custom Code                                                                                                                  |
| New | Workflows: support `async`/`await` and [creation of data instances](/docs/integrations-and-api/workflows/workflow-in-depth#data-instances) from JSON objects                                                    |
| New | Diff tool: compare a draft with a published configurator or stage                                                                                                                                               |

### Release 1 Oct 26

| Type                                      | Description                                                                                                                                                                                          |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | CSS Variables Integration as dedicated entities in the CSS Variables widget Dynamically adjustable via a Hive rule Importable from another configurator or CSS code |
| New | Make "Style" and "Finish" workspaces adjustable                                                                                                                                                      |

### Release 21 Sep 26

| Type                                      | Description                                                                                                                     |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| New | Support temporary configuration files also for [PDF creation](/docs/asset-management/pdf-asset#how-to-use-a-pdf-asset)          |
| New | Customizable Quote UI: Support [LiquidJS templating](/docs/quote-management/customize-quote-ui#text--value-templating-liquidjs) |
| Fix | Fixed cropped menus, tooltips, etc. when working with Monaco editor                                                             |

### Release 14 Sep 26

| Type                                      | Description                               |
| ----------------------------------------- | ----------------------------------------- |
| New | Add option to keep Stage after publishing |
| New | Customizable access level of file assets  |

### Release 7 Sep 26

| Type                                      | Description                                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------------------------------- |
| New | Customizable Quote UI: The columns and expandable details section can be also customized now |
| New | Editor V2: Batch editing of components and controls                                          |

### Release 18 Aug 26

| Type                                            | Description                                                                                       |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| New       | Finish action notifications: get a mail or webhook notification if one of the finish action fails |
| New       | Show info about invalid CSS stylesheets and inline CSS property                                   |
| New       | Add "Hive in Controls" for CSS class property                                                     |
| Change | Use iframe in layout editor to improve visual equality with real configurator                     |

### Release 12 Aug 26

| Type                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Hive: new [Map type](/docs/configurator-logic/hive-types/map-type) for storing and looking up values by key                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| New | [Hive Query](/docs/configurator-logic/hive-queries) improvements: queries can now run standalone, outside of a table component queries now support [list and map projections](/docs/configurator-logic/hive-queries#projecting-data), in addition to table projections the query [spread operator](/docs/configurator-logic/hive-queries#projecting-data) (`...all`) can now target any expression, and spread fields can be overridden by explicitly declared columns queries now support creating objects (e.g. building a list of objects from a table or list) |
| New | Hive: improved access to user and distributor data: new [`configurator.getUsers()`](/docs/configurator-logic/configurator-and-presets-variable#methods) and [`getDistributors()`](/docs/configurator-logic/configurator-and-presets-variable#methods) functions for looking up all users/distributors of a company new [`configurator.company`](/docs/configurator-logic/configurator-and-presets-variable#properties) variable, always holding the current company's data new [`user`](/docs/configurator-logic/user-variable#properties) fields `id`, `distributor` and `avatar` |
| New | Show nodes metadata in 3d Asset                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

### Release 03 Aug 26

| Type                                            | Description                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | Raw JSON editor for Datasource configuration                                                                                                                                                                                                                                                 |
| New       | Quotes can now be passed to/from distributors with the new `OnFinish.PassQuote()` function. can be used when editing an existing quote or when creating a new one allows you to change both the source quote in the current company/distributor and the target lead |
| Change | Reuse Quote default UI layout for Lead view                                                                                                                                                                                                                                                  |
| Fix       | Cursor jumping to last position when fast typing in Monaco editor                                                                                                                                                                                                                            |

### Release 28 Jul 26

| Type                                      | Description                                                                                      |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| New | Component/Control tree: Add selected item actions (e.g. delete, duplicate) into tree header menu |
| New | Component/Control tree: Delete selected item with "Del" key                                      |
| Fix | Component/Control tree: Disable changing only the casing of a Component or Control name          |
| Fix | Disable publish if errors or unsaved changes are pending                                         |
| Fix | Exception when navigating between CSS style sheets                                               |

### Release 16 Jul 26

| Type                                      | Description                                                                                                                                                    |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Quotes: New Quote Hub [permission settings](/docs/quote-management/quote-permissions) to control which users can view and edit quotes they are not assigned to |
| New | Quotes: Support negative line item prices                                                                                                                      |
| New | Quotes: New way of specifying global taxes                                                                                                                     |
| New | Support renaming configurators and drafts                                                                                                                      |

### Release 13 Jul 26

| Type                                      | Description                                                                                                                                                                |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Widget asset: New asset type which can be used to customize different areas in the platform                                                                                |
| New | Customizable Quote UI: The quote details page can now be customized via a Widget asset to move fields to different places, show/hide them, change the overall layout, etc. |

### Release 30 Jun 26

| Type                                      | Description                                                                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| New | Configurations can now be opened in a read-only [view mode](/docs/configurator-logic/configuration-variable#isviewmode). |

### Release 29 Jun 26

| Type                                      | Description                                                             |
| ----------------------------------------- | ----------------------------------------------------------------------- |
| New | Quotes: Pass on a quote from a company to a distributor and vica versa. |

### Release 18 Jun 26

| Type                                      | Description                                                                                                                                                                               |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Hive: new [JSON type](../configurator-logic/hive-types/json-type) for storing and passing through arbitrary JSON data to external APIs                                                    |
| New | Hive: new [JSON literal](../configurator-logic/hive-types/json-type#json-literal) for simple copy/pasting of raw JSON into a Hive rule                                                    |
| New | Hive: [`TextAsset.getJson()`](../asset-management/text-asset#content) returns the asset content as JSON, or an error if the content isn't valid JSON.                                     |
| New | Hive: introducing `null` as synonym for `empty`.                                                                                                                                          |
| New | Hive: You can now get a table of all uploaded CfgnFiles with [`configuration.GetFiles()`](../configurator-logic/file-upload-and-handling#using-files-in-hive). This table can be queried. |
| New | [External events](../integrations-and-api/embedding-and-whitelist#external-events) for configuration insights.                                                                            |

### Release 16 Jun 26

| Type                                      | Description                                           |
| ----------------------------------------- | ----------------------------------------------------- |
| New | Editor V2: Fully fledged dataview & combobox controls |

### Release 15 Jun 26

| Type                                      | Description                                                                                                                                                      |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Create quote PDFs and send mails in workflows. [Full example](../integrations-and-api/workflows/workflow-templates.md#send-quote-mail-upon-quote-change-trigger) |

### Release 08 Jun 26

| Type                                            | Description                                                                                                                                                                                  |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | Support [quote templates](../quote-management/how-to-work-with-quotes#configurator) which can be used in the quote details page to add predefined line items, sections, discounts or markups |
| Change | Total discounts and markups must be provided via the quote `items` field now                                                                                                                 |
| Change | Rename `type` property of total discount/markup to `valueType` which represents the `PriceAdjustmentType` of the value                                                                       |
| Change | Rename `QuoteItemSection` to `QuoteSection`                                                                                                                                                  |

### Release 28 May 26

| Type                                      | Description                                                                                                                        |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| New | Asset Manager: Data Souces can now be filtered and sorted with Hive expressions                                                    |
| New | Support upload of [temporary configuration files](../configurator-logic/file-upload-and-handling.md#temporary-configuration-files) |

### Release 18 May 26

| Type                                      | Description                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------- |
| New | Editor V2: Streamline tree views for Components and Controls structure |
| New | Editor V2: Add global indicator for editor errors                      |

### Release 11 May 26

| Type                                      | Description                                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
| New | Editor V2: Create Custom Code definitions for controls                                            |
| New | Editor V2: Add indicator for Custom Code definitions sync state                                   |
| New | Editor V2: Automatically create and sync Custom Code definitions on component and control changes |
| New | Download configuration insights as CSV                                                            |
| New | Support custom fields for quote discounts or markups                                              |

### Release 07 May 26

| Type                                      | Description                                                                                                         |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| New | Editor V2: Add Quick Launcher for fast search and navigation across workspaces, components, and controls            |
| New | Editor V2: Connection stability improvements. Retry logic on failures, info dialog for users e.g. when offline etc. |
| New | Editor V2: Stylable system controls (dialogs & loader) in editors "Style" workspace                                 |
| New | Editor V2: Class name suggestions in CSS editors                                                                    |
| Fix | Editor V2: Control properties `margin` & `padding` now support CSS expressions like `calc`, `min`, `max` etc.       |

### Release 04 May 26

| Type                                      | Description                                                  |
| ----------------------------------------- | ------------------------------------------------------------ |
| New | Editor V2: Streamline save behavior across all editors       |
| New | Editor V2: UI/UX improvements to the app header and sidebars |

### Release 27 Apr 26

| Type                                      | Description                                                                                                    |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| New | Feature to create and manage [leads](/docs/quote-management/how-to-work-with-quotes/#leads)                    |
| New | [Custom format](/docs/quote-management/how-to-find-quotes#settings) for download names of generated quote PDFs |

### Release 21 Apr 26

| Type                                      | Description                                                                                           |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| New | New PDF generation mode "Prince XML" for [PDF assets](/docs/asset-management/pdf-asset.md#prince-xml) |

### Release 02 Apr 26

| Type                                      | Description                                                                                                                      |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| New | Support integrations for `http` in [workflows](/docs/integrations-and-api/workflows/workflow-in-depth#request-config)            |
| New | You can now view the results of all finish actions on the [Insights](/docs/configuration-insights/configuration-insights-) page. |

### Release 26 Mar 26

| Type                                      | Description                                                                                                   |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| New | Allow quote updates in [workflows](/docs/integrations-and-api/workflows/workflow-templates#workflow-triggers) |
| New | Introduce a new optional quote [shipping](/docs/quote-management/how-to-work-with-quotes) field               |
| New | Improved file formatting when editing a babylon file                                                          |

### Release 19 Mar 26

| Type                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | Introduce custom fields for Insights values use the new `OnFinish.SetCustomInsights()` function to define insights values custom insights fields must be created first in Settings > Custom Fields ⚠️ The `Price` metric on the configurator dashboard now requires a custom insights field "Price" to work |
| Remove | Deprecate `ValueComponent.Archive` → use `OnFinish.SetOutput()` instead                                                                                                                                                                                                                                                                                                                                              |
| Remove | Deprecate `CheckoutComponent.Quote` → use `OnFinish.Quote()` instead add an overload of `OnFinish.Quote()` that provides a full quote snippet |
| New       | Add an `OnFinish.SetGoal()` function. The finish `goal` can be viewed in Insights and used as filter. It is meant to replace the `shopName` (example values: "Save", Request", "Quote")                                                                                                                                                                                                                              |
| New       | Insights can now be filtered by `Quote Hub` and `Quote number`                                                                                                                                                                                                                                                                                                                                                       |
| New       | Checkout now works even when no Shop is specified                                                                                                                                                                                                                                                                                                                                                                    |
| New       | Checkout (or Finish in editor v2) will now almost always complete, even if there was an error when e.g. sending a mail or creating a quote A new `Finish Action` column in Insights indicates if there was an error in any finish action and can be used to quickly filter all failed finishes A new `Failed Actions` column shows which finish actions failed (can also be used to filter) |

### Release 18 Mar 26

| Type                                      | Description                                                                                                 |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| New | Copy preview configurations with the Combeenation [API](/docs/integrations-and-api/combeenation-api#api-v1) |

### Release 17 Mar 26

| Type                                      | Description                                                           |
| ----------------------------------------- | --------------------------------------------------------------------- |
| New | Introduced [Integrations](/docs/integrations-and-api/integrations.md) |

### Release 10 Mar 26

| Type                                      | Description                                                                                         |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
| New | Several improvements in the quotes module                                                           |
| New | Sync custom code definitions for all quote hive types                                               |
| New | Introduce a [configuration.isFrozen](/docs/configurator-logic/configuration-variable) hive variable |

### Release 25 Feb 26

| Type                                            | Description                                                                                                      |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| New       | Support changing a quote with the configurator.                                                                  |
| Remove | The "Replace Configuration" feature during finishing a configuration.                                            |
| Remove | Remove the asset bundle menu in the quote hub settings. It can be selected using the Quote hive object now. |

### Release 30 Jan 26

| Type                                      | Description                                               |
| ----------------------------------------- | --------------------------------------------------------- |
| New | Quote PDF context: add custom user fields of the assignee |

### Release 29 Jan 26

| Type                                      | Description                                 |
| ----------------------------------------- | ------------------------------------------- |
| New | Undo/Redo support in the quote details view |
| New | Improved visualization of quote issues      |

### Release 21 Jan 26

| Type                                      | Description                                                                                                                                   |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Initial release of [FinishActions](/docs/integrations-and-api/configuration-finish) that will over time replace the current Checkout feature. |

### Release 13 Jan 26

| Type                                      | Description                                                                                                                                                                                                                                        |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New | Specify multiple quote assignee candidates during checkout. The first valid user is assigned.                                                                                                                                                      |
| New | [Quote Action Rules](/docs/quote-management/how-to-work-with-quotes#creating-quotes) to constrain if a specific line item can be deleted any total discount or markup can be added any new line item can be added |

### Release 09 Jan 26

| Type                                            | Description                                                                                                                                                                                                                        |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New       | Quote PDF asset template improvements: Add banking details via context Exchange default company image |
| Remove | PDF asset `data_uri` filter no longer supports on asset paths directly Use on URLs directly: `{{ "https://picsum.photos/id/2/200" \| data_uri }}` Usage for assets: `{{"Images.Bee" \| url \| data_uri}}` |

:::info
You find older release notes in the [archive](release-notes-archive).
:::