WIP: Restructure DataMapper documentation with updated screenshots in…

content/docs/datamapper/01-getting-started/_index.md

@@ -0,0 +1,100 @@
+---
+title: "Getting Started"
+description: "Add DataMapper to your route and understand the interface"
+date: 2026-04-01
+weight: 1
+---
+
+## Overview
+
+To use the DataMapper for creating data transformations, you need to add and configure a DataMapper step in your Camel route. This guide covers the essential steps to get started with the DataMapper interface.
+
+---
+
+## Adding a DataMapper step
+
+Now let's add a DataMapper step to your Camel route. The DataMapper provides a visual interface for creating data transformations without writing XSLT code manually.
+
+1. Add a **Kaoto DataMapper** step in your Camel route. When you `Append`, `Prepend` or `Replace` a step in the Kaoto Design view, you can find the **Kaoto DataMapper** step in the catalog.
+{{< image-sh src="catalog-datamapper-tile.png" text="DataMapper Catalog Tile" >}}
+
+2. Click the added **Kaoto DataMapper** step in the Kaoto Design to open the config form.
+{{< image-sh src="kaoto-datamapper-step.png" text="Kaoto DataMapper step" >}}
+
+3. In the config form, click the `Configure` button to open the visual DataMapper editor.
+{{< image-sh src="datamapper-configure-button.png" text="DataMapper Configure button" >}}
+
+4. This will open the visual DataMapper editor where you can create your data mappings.
+{{< image-sh src="datamapper-blank.png" text="Blank DataMapper UI" >}}
+
+---
+
+## Understanding the Interface
+
+The DataMapper editor is divided into two main sections that represent the data transformation flow:
+
+{{< image-sh src="datamapper-source-target.png" text="Source and Target" >}}
+
+### Source Section (Left Side)
+
+The **Source** section represents where your data comes from - the input side of your mappings. This is where the DataMapper step reads the data from.
+
+- **Body** - The incoming Camel Message Body (the main data payload)
+- **Parameters** - Additional data from Camel Variables and Message Headers
+
+Think of this as the "input" side of your transformation - the data you're reading from.
+
+### Target Section (Right Side)
+
+The **Target** section represents where your data goes to - the output side of your mappings. This is where the DataMapper step writes the transformed data.
+
+- **Body** - The outgoing Camel Message Body (the transformed result)
+
+Think of this as the "output" side of your transformation - the data structure you're creating.
+
+> [!TIP]
+> You can adjust the font size in the DataMapper interface to match your preference. Use the **+** and **-** magnifier icons in the toolbar to make the text larger or smaller for better readability.
+> {{< image-sh src="datamapper-zoom.png" text="Zoom controls in DataMapper toolbar" >}}
+
+---
+
+## Working with Parameters
+
+Parameters allow you to access Camel Variables and Message Headers in your mappings. This is useful when you need to combine data from multiple sources in your transformation.
+
+### Add a Parameter
+
+Follow the below steps to add a parameter.
+
+1. Click the plus **+** button on the right side of the `Parameters` title.
+{{< image-sh src="datamapper-add-parameter.png" text="Parameters" >}}
+
+2. Now type the parameter name and click the check button on the right.
+{{< image-sh src="datamapper-add-parameter-confirm.png" text="Add Parameter confirm" >}}
+
+> [!TIP]
+> When you have many parameters, you can improve readability by hiding them visually. Click the eye icon next to the Parameters section to toggle the visibility of the parameter list.
+> {{< image-sh src="datamapper-hide-parameters.png" text="Hide parameters to improve readability" >}}
+
+> [!NOTE]
+> While Camel Exchange Properties are also mapped to parameters in the current `camel-xslt-saxon` implementation, after the [Camel Variables](https://camel.apache.org/manual/variables.html) have been introduced, it is no longer recommended to store application data in Camel Exchange Properties. We encourage to use [Camel Variables](https://camel.apache.org/manual/variables.html) instead.
+
+### Delete a Parameter
+
+To remove a parameter, click the trash icon next to it and confirm the deletion.
+
+{{< image-sh src="datamapper-delete-param-trash.png" text="Click trash icon to delete parameter" >}}
+{{< image-sh src="datamapper-delete-param-confirm.png" text="Confirm parameter deletion" >}}
+
+> [!NOTE]
+> If the parameter is used in any mappings, those mappings will become invalid after deletion. Review your mappings before removing parameters.
+
+---
+
+## Next Steps
+
+Now that you understand the DataMapper interface, you can:
+
+- **[Attach schemas](../02-attaching-schemas/)** to visualize your data structures
+- **[Create mappings](../03-creating-mappings/)** between source and target fields
+- **[Add conditional logic](../04-conditional-mappings/)** for complex transformations

content/docs/datamapper/02-attaching-schemas/_index.md

@@ -0,0 +1,106 @@
+---
+title: "Attaching Schemas"
+description: "Work with XML and JSON schemas to visualize data structures"
+date: 2026-04-01
+weight: 2
+---
+
+## Overview
+
+Schemas define the structure of your data and enable the visual tree representation in the DataMapper. The DataMapper supports both XML Schema (XSD) and JSON Schema files for Source Body, Target Body, and Parameters.
+
+> [!NOTE]
+> If the data is not structured and just a primitive value, you don't need to attach a schema file.
+
+---
+
+## Attaching a Schema
+
+Follow these steps to attach a schema file to Source Body, Target Body, or Parameters:
+
+1. **Place your schema file** (`.xsd` or `.json`) in the workspace directory
+2. **Click "Attach a schema"** in the Source Body, Target Body, or Parameters section
+{{< image-sh src="datamapper-attach-schema.png" text="Click to attach a schema" >}}
+3. **Click the file button** in the modal
+{{< image-sh src="datamapper-attach-schema-file-btn.png" text="Select schema file" >}}
+4. **Select your schema file**
+{{< image-sh src="datamapper-select-schema.png" text="Choose the schema file" >}}
+
+> [!TIP]
+> You can select and upload multiple schema files at once.
+> {{< image-sh src="datamapper-attach-multiple.png" text="Selecting multiple schema files at once" >}}
+
+5. **For XML schemas only:** Choose the root element - Select which top-level element to use if your schema defines multiple
+{{< image-sh src="datamapper-select-root-element.png" text="Choose root element for XML schema" >}}
+6. **Click Attach**
+{{< image-sh src="datamapper-attach-schema-attach.png" text="Confirm schema attachment" >}}
+7. The **document structure** appears as a tree - The schema is parsed and rendered as an expandable tree view, showing all elements, attributes, and their hierarchical relationships. You can now navigate through the structure and create mappings by dragging fields between source and target sections.
+{{< image-sh src="datamapper-schema-attached.png" text="Schema rendered as a tree" >}}
+
+---
+
+## Detaching a Schema
+
+To remove a schema from Source Body, Target Body, or Parameters, click the **Detach schema** button <img src="datamapper-detach-button.png" alt="Detach schema button" style="display: inline; height: 1.2em; vertical-align: middle;"> and confirm the action.
+
+> [!IMPORTANT]
+> Detaching a schema will remove all mappings associated with that schema. This action cannot be undone.
+
+---
+
+## Understanding JSON Field Labels
+
+> [!NOTE]
+> Kaoto DataMapper uses XSLT 3.0 [`json-to-xml()`](https://www.w3.org/TR/xslt-30/#func-json-to-xml) and [`xml-to-json()`](https://www.w3.org/TR/xslt-30/#func-xml-to-json) functions to support JSON mappings. The field labels reflect this internal representation.
+
+JSON schemas use type-based labels since fields can be anonymous:
+
+| Label | Meaning |
+|-------|---------|
+| `map` | Object field |
+| `array` | Array field |
+| `string` | String field |
+| `number` | Number field |
+
+### Field Label Examples
+
+JSON schema fields are rendered with type-based labels in the tree view. Here's how different field types appear:
+
+{{< image-sh src="datamapper-json-fields.png" text="JSON schema field types in the tree view" >}}
+
+**Understanding the labels:**
+- **Named fields** display as `type [@key = FieldName]` - For example, `string [@key = AccountId]` represents a string field named "AccountId"
+- **Anonymous fields** show only the type - For example, `map` represents an unnamed object
+- **Primitive types** like `string`, `number`, `boolean` indicate the data type
+- **Complex types** like `map` (object) and `array` represent structured data
+
+### Array Fields and Collections
+
+> [!IMPORTANT]
+> For `array` fields, the **children** are the collection items, not the array itself. Collection fields are marked with a layer icon <img src="datamapper-collection-field.png" alt="Collection icon" style="display: inline; height: 1.2em; vertical-align: middle;">. The `map` type field (child of the `array` field) is the actual collection field that you'll use in for-each mappings.
+
+{{< image-sh src="datamapper-json-array-field.png" text="Array field with collection children" >}}
+
+---
+
+## JSON Parameter References
+
+When using structured JSON parameters, they're internally converted to XML. Reference them with a `-x` suffix in XPath expressions:
+
+- Parameter `Account` becomes `$Account-x`
+- Parameter `Cart` becomes `$Cart-x`
+
+{{< image-sh src="datamapper-json-mappings-all.png" text="Complete JSON mapping example showing -x suffix usage" >}}
+
+> [!TIP]
+> When creating mappings through drag and drop, Kaoto DataMapper automatically handles the `-x` suffix. You only need to remember this when editing XPath expressions manually.
+
+---
+
+## Next Steps
+
+Now that you have schemas attached:
+
+1. **[Create simple mappings](../03-creating-mappings/)** between source and target fields
+2. **[Add conditional logic](../04-conditional-mappings/)** for complex transformations
+3. **[Use the XPath editor](../05-xpath-editor/)** for advanced expressions

content/docs/datamapper/03-creating-mappings/_index.md

@@ -0,0 +1,61 @@
+---
+title: "Creating Mappings"
+description: "Build simple field-to-field mappings using drag-and-drop or XPath"
+date: 2026-04-01
+weight: 3
+---
+
+## Overview
+
+Once you have schemas attached, you can create mappings between source and target fields. The DataMapper offers two primary methods: drag-and-drop for quick mappings and XPath expressions for more control.
+
+---
+
+## Drag and Drop Mapping
+
+The easiest way to create a mapping is by dragging a source field onto a target field. A line will be drawn between the fields to visualize the connection.
+
+### Example: Map the Name Field
+
+{{< video src="./datamapper-drag-name.mp4" >}}
+
+> [!TIP]
+> Drag-and-drop is the fastest way to create simple field mappings. The DataMapper automatically generates the correct XPath expression for you.
+
+---
+
+## XPath Expression Mapping
+
+For more control over your mappings, you can type XPath expressions directly.
+
+### Create a Mapping with XPath
+
+1. **Click the 3-dot menu** on the target field
+{{< image-sh src="datamapper-add-selector.png" text="Select 'Add selector expression'" >}}
+
+2. **Enter your XPath expression**
+{{< image-sh src="datamapper-type-xpath.png" text="Type the XPath expression" >}}
+
+> [!NOTE]
+> XPath expressions give you full control over data transformation, including string manipulation, calculations, and conditional logic. For complex expressions, consider using the [XPath Editor](../05-xpath-editor/).
+
+---
+
+## Delete a Mapping
+
+If you need to remove a mapping, click the trash icon <img src="datamapper-delete-mapping-btn.png" alt="Delete mapping icon" style="display: inline; height: 1.2em; vertical-align: middle;"> next to the target field and confirm the deletion.
+
+{{< image-sh src="datamapper-delete-mapping.png" text="Delete mapping" >}}
+{{< image-sh src="datamapper-delete-mapping-confirm.png" text="Confirm mapping deletion" >}}
+
+> [!WARNING]
+> Deleting a mapping is permanent and cannot be undone. Make sure you want to remove the mapping before confirming.
+
+---
+
+## Next Steps
+
+Now that you can create and manage basic mappings:
+
+1. **[Add conditional logic](../04-conditional-mappings/)** with if, choose-when-otherwise, and for-each
+2. **[Use the XPath editor](../05-xpath-editor/)** for complex transformations with functions

content/docs/datamapper/04-conditional-mappings/_index.md

@@ -0,0 +1,106 @@
+---
+title: "Conditional Mappings"
+description: "Use if, choose-when-otherwise, and for-each logic for complex transformations"
+date: 2026-04-01
+weight: 4
+---
+
+## Overview
+
+The DataMapper supports three types of conditional mappings to handle complex transformation logic:
+
+- **`if`** - Execute mapping only when a condition is met
+- **`choose-when-otherwise`** - Branch based on multiple conditions
+- **`for-each`** - Iterate over collection fields (arrays)
+
+---
+
+## If Mapping
+
+Create a mapping that only executes when a specific condition is true.
+
+### Steps
+
+1. **Click the 3-dot menu** on the target field and select **"wrap with if"**
+{{< image-sh src="datamapper-if-if.png" text="Select wrap with if" >}}
+
+2. **Configure the condition** - Drag source fields or type manually
+{{< image-sh src="datamapper-if-condition.png" text="Define the if condition" >}}
+
+3. **Create the mapping** for when the condition is true
+{{< image-sh src="datamapper-if-mapping.png" text="Configure the conditional mapping" >}}
+
+> [!TIP]
+> You can drag source fields into the condition input to quickly build expressions like `$sourceField > 100` or `$status = 'active'`.
+
+---
+
+## Choose-When-Otherwise Mapping
+
+Create branching logic with multiple conditions, similar to switch-case statements.
+
+### Steps
+
+1. **Click the 3-dot menu** and select **"wrap with choose-when-otherwise"**
+{{< image-sh src="datamapper-choose-choose.png" text="Select choose-when-otherwise" >}}
+
+2. **Configure when and otherwise conditions** - Similar to if mapping, configure the condition and create mappings for both when and otherwise branches
+{{< image-sh src="datamapper-choose-otherwise-mapping.png" text="Configure when and otherwise mappings" >}}
+
+3. **Add more when branches** (optional) - If you need multiple conditions, click the 3-dot menu on the choose field and select "Add when" to create additional when branches. Each branch can have its own condition and mappings.
+{{< image-sh src="datamapper-choose-add-when.png" text="Add another when branch" >}}
+
+> [!NOTE]
+> The `otherwise` branch executes when none of the `when` conditions are satisfied, providing a default fallback.
+
+---
+
+## For-Each Mapping
+
+When working with arrays or repeating elements, use for-each mappings to transform each item in the collection. Collection fields are identified by a layer icon <img src="datamapper-layer.png" alt="Layer icon" style="display: inline; height: 1.2em; vertical-align: middle;"> in the document tree.
+
+### Steps
+
+1. **Identify the target collection field** - Look for fields marked with the layer icon <img src="datamapper-layer.png" alt="Layer icon" style="display: inline; height: 1.2em; vertical-align: middle;">, indicating they contain multiple items
+
+2. **Create the for-each mapping** - Click the 3-dot menu on the target collection field and select **"wrap with for-each"**
+{{< image-sh src="datamapper-for-each-for-each.png" text="Select wrap with for-each" >}}
+
+3. **Specify the source collection** - Choose which source collection to iterate over. This determines what data will be processed for each target item.
+{{< image-sh src="datamapper-for-each-condition.png" text="Select source collection to iterate" >}}
+
+4. **Map the collection item fields** - Create mappings for individual fields within each collection item. These mappings will be applied to every item in the collection.
+{{< image-sh src="datamapper-for-each-mappings.png" text="Map fields for each collection item" >}}
+
+> [!IMPORTANT]
+> Inside a for-each mapping, field paths are relative to the collection item. For example, if iterating over `Items`, you reference `Name` instead of `Items/Name`.
+
+---
+
+## Multiple For-Each Mappings
+
+Merge multiple source collections into a single target collection by adding multiple for-each mappings.
+
+### Steps
+
+1. **Create the first for-each mapping** as described above
+
+2. **Add another for-each mapping** - Click "Add Conditional Mapping" in the placeholder below the first mapping, then select "Wrap with for-each"
+{{< image-sh src="datamapper-wrap-with-for-each.png" text="Add second for-each mapping" >}}
+
+3. **Configure the second collection mappings** - Select the second source collection to iterate over, then create field mappings for each item. This allows you to merge data from multiple collections into a single target array, combining items from different sources.
+{{< image-sh src="datamapper-map-2nd-for-each-children.png" text="Configure second collection and map its fields" >}}
+
+{{< video src="./dm_multiplemappings.mp4" subtitles="./dm_multiplemappings.vtt" >}}
+
+> [!TIP]
+> This technique is useful for merging data from multiple sources, such as combining orders from different systems into a single output array.
+
+---
+
+## Next Steps
+
+Now that you understand conditional mappings:
+
+1. **[Use the XPath editor](../05-xpath-editor/)** for complex expressions with functions
+2. Return to the [DataMapper overview](../) to explore other features

content/docs/datamapper/dm_multiplemappings.vtt → content/docs/datamapper/04-conditional-mappings/dm_multiplemappings.vtt

@@ -7,9 +7,9 @@ Merge 2 source collection fields with multiple "for-each" mappings
 00:04.000 --> 00:08.000
 Create first "for-each" mapping
 
-00:18.000 --> 00:22.000
+00:31.000 --> 00:35.000
 Click "Add Conditional Mapping"
 Click "Wrap with for-each"
 
-00:25.000 --> 00:30.000
+00:42.000 --> 00:47.000
 Create second "for-each" mapping