Field mappings

The ‘Field Mappings’ menu option allows you to create a custom mapping between the fields defined in your customer’s respective log and the fields available in our system.

On the left-hand side of the mapping tool, select the target field for the desired report (e.g. OCI), then select the desired mapping type (Database, Fixed Value, Dynamic (in Gateway mode only)).

On the right-hand side, select the source field and/or the value to be mapped to the respective protocol field.

Database: In the “Source field” field, select a field from our data model that is to be used as the data source for the selected target field during transmission.

Fixed Value: In the “Source Field” field, enter a fixed value which is to be output in the selected target field when data is transmitted to the calling ERP system.

Dynamic: This mapping type is only available in Gateway mode. Here, during the return transmission from the called shop system, it is possible to pass on and map additional data within the “product” object.

...
    "additionalProp1": [
 {
 "label": "string",
 "value": "string"
 },
          {
 "label": "string",
 "value": "string"
 }
  ],
...

Example: In the “product” object, you also pass the “classifications” array, which in turn contains objects with the keys label and value. Here, you can enter the key name classifications in the first input field and the value of the label key in the second. The value field of the same object will now be used for field mapping.

Customer and shopping basket values

Depending on whether the field mapping is created for OCI or cXML, additional values are available.

cXML

For cXML, the following additional values from the customer settings are available:

• Buyer Identity
• Supplier Identity

OCI

No specific values are available for OCI

All protocols

Regardless of the protocol, the following values from the shopping basket item are available:

• Product name
• Product number
• Quantity
• Unit price
• Gross price
• Net price
• Tax rate
• Item type

What are field transformations?

Field transformations allow you to dynamically modify values in your field mappings before they are transferred to the target system. Using transformations, you can convert input values into other values based on defined rules.

Accessing field transformations

1. Navigate to Field mappings in the main menu.
2. Select an existing field mapping or create a new one.
3. In the field mapping’s detail view, you will see a list of all mapped fields.
4. Next to each field is a green button labelled "Transformation(s)".

Creating and editing transformations

To create or edit a transformation for a field:

1. Click the green “Transformations” button next to the desired field.
2. A side panel containing the transformation settings will open.
3. If no transformation exists yet, an empty mapping will be created automatically.

Configuring a Transformation

Type of Transformation

Two types of transformation are currently supported:

1. "Replace Value" (If transformation): This transformation checks whether the input value matches a defined value and, if necessary, replaces it with another value.

2. "Append To" (AppendTo transformation): This transformation allows you to append a fixed text or the content of another product field to the value of the current field.

Configuring the "Replace Value" transformation

Adding mappings

1. In the "Input value" field, enter the value to be replaced.
2. In the "Replace with" field, enter the target value to be used instead.
3. Click "Add another mapping" to define further replacement rules.

Configuring the "Append To" transformation

With the "Append To" transformation, you have two options:

1. Append fixed value: Select this option to append static text to the field value.

   • In the "Fixed value to append" field, enter the text to be appended.

2. Append value from another field: Select this option to append the value of another product field.

   • From the "Field to append" drop-down menu, select the product field whose value is to be appended.

Saving or deleting transformations

• Click "Save" to save the transformation.
• Click "Delete" to remove the transformation.

Examples of use

Example 1: Converting status values (replace value)

If your source system uses status values such as “0” and “1”, but the target system expects “Inactive” and “Active”:

1. Create a “Replace Value” transformation with the following mappings:
   • Input value: “0” → Replace with: “Inactive”
   • Input value: “1” → Replace with: “Active”

Example 2: Adapting language codes (Replace value)

If your source system uses language codes in the format “de-DE”, but the target system only expects “de”:

1. Create a “Replace Value” transformation with the following mappings:
   • Input value: “de-DE” → Replace with: “de”
   • Input value: “en-US” → Replace with: “en”

Example 3: Setting default values (Replace value)

If you want to ensure that empty values are replaced by a default value:

1. Create a “Replace Value” transformation with the following mapping:
   • Input value: "" → Replace with: “Default”
2. Disable “Use payload as fallback” and set the fallback value to “Default”.

Example 4: Adding units (Append To)

If you want to append units of measurement to numerical values:

1. Create an “Append To” transformation.
2. Select “Append fixed value”.
3. Enter “ kg” as the fixed value to be appended.
4. The result would be, for example, “5” → “5 kg”.

Example 5: Combining item number with description (Append To)

If you want to combine the product number with the product description:

1. Create an “Append To” transformation for the “products.ordernumber” field.
2. Select “Append value from another field”.
3. Select “products.title” as the field to append to.
4. The result would be, for example, “A12345” + “screwdriver” → “A12345 screwdriver”.

Notes

• You can define multiple transformations for a single field.
• The number of active transformations is displayed below the field in the field mapping view.
• Transformations are applied in the order in which they were defined.
• Ensure that all source values and replacement values are defined correctly to avoid unexpected results.
• With the “Append To” transformation, values are concatenated without any additional formatting. If necessary, insert spaces or other separators into the text to be appended.