====== Debugging =======

There are several ways to test the correct functioning of a mapping transformation:

  - In the Mapping Designer:
    - with automatically generated test data
    - Based on an existing file((This must correspond to an existing [[en:prozessdefinition:repositorien:entitaetstyp:start|entity type]])) in the mapping editor
    - Based on an existing file with multiple entities via analyzer ((This allows a specific entity within a file to be selected.)) in the mapping editor
    - From a backend object ((This allows you to select a specific entity within a file.)) in the mapping editor.
    - Testing Transformation Chains
  - In the message basket:
    - Starting from an existing and analyzed message((This must contain entities which correspond to an existing [[en:prozessdefinition:repositorien:entitaetstyp:start|entity type]]))

===== 1st source object instantiate in the mapping designer ======

To use debugging in the Mapping Designer, the source object must first be instantiated. Choose {{images:hammer.png?nolink}} in the upper left area of the mapping definition view. **Debugging** Menu.\\ 

{{images:mapping_quelle_debugging_menu.png?nolink}}

This offers four different options for object instantiation.

==== a) Create object instance with generated test data =====

In the mapping definition view, select {{images:hammer.png?nolink}} in the upper left area. **Debugging** Menu{{:images:notebook_edit.png|}} the entry  **Generate test data**. This automatically generates an object instance in the source object with data element-specific content and three instances per ArrayList item.
Test data can be used to quickly check whether the transformation produces the desired results.

==== b) Create an object instance from an existing file with a known entity =====

In the mapping definition view, select {{images:hammer.png?nolink}} in the upper left area. **Debugging** Menu the entry {{:images:folder_document.png|}} **load from file** off. If the file selected in the following file selection dialog contains an entity that fits into the source object, it will be instantiated with the contents of the file.

==== c) Create object instance from an existing file with several entities via analyzer =====

This method is useful if source files contain several entities of the source object. 
In the mapping definition view, select {{images:hammer.png?nolink}} in the upper left area. **Debugging** Menu the entry {{:images:folder_document.png|}} **Load via analyzer** off. First the desired analyzer is selected and confirmed with **OK**, with the following file selection dialog the desired file is selected. If the file can be successfully analyzed with the selected analyzer, a list of entities will be offered in the following dialog from which one can now select one and confirm with **OK**.

{{:images:sign_warning.png?nolink|}}**Note:** If a message contains several entities, they can be selected with multiple selection and instantiated as source. This makes it possible to make groupings or evaluations and conversions beyond the entity context.

==== d) Create object instance from a backend object =====

This method is useful if the data source can be operated via database integration. In the mapping definition view, choose {{images:hammer.png?nolink}} in the upper left area. **Debugging** Menu the entry {{:images:data_scroll.png|}} **Load from BackendObject** off.

==== e) Testing transformation chains =====

If a target object is successfully instantiated and the system has a mapping with this target type as source type, you can go directly to a new mapping designer instance with the instantiated target.  In the mapping definition view in the ***right upper area** select from the {{images:hammer.png?nolink}} **debugging** menu the menu entry {{images:plug2.png?nolink}} **Debug with other mapping ***out.\\ 

{{images:mapping_ziel_debugging_menu.png?nolink}}

===== 2. instantiate source object from a message ======

You can access the debugging of mappings directly from messages. So if a message is selected in the list of messages you can use the context menu\\ 

{{:images:nachrichten_kontextmenu.png|}}

via {{images:plug2.png?nolink}} **Debug message *** ► {{images:plug2.png?nolink}} **debug mapping** or in the detail view of a message via the menu\\ 

{{:images:nachricht_debuggen.png|}} 

the content of the message as source object of a mapping with the menu entry {{images:plug2.png?nolink}} ** debug mapping *** instantiate. 

{{:images:sign_warning.png?nolink|}}**Note:** Only if the message has already been successfully analyzed. Otherwise {{images:plug2.png?nolink}}

===== 3. Apply mapping ======

Once you have instantiated the source object, you can translate to the target by removing the following from {{images:hammer.png?nolink}} **debugging** menu the first menu entry {{images:gearwheel_play.png?nolink}} **Apply mapping**((keyboard shortcut CTRL+r is also possible here.)). The input values are then output in the source object (left side) and the output values in the target object (right side). 

==== Status bar =====

The status bar((in the mapping designer, below)) gives a first feedback about success or failure of the transformation via coloring.

  - It is green for success:\\ {{images:mapping_success_statusleiste.png?nolink}}
  - It's yellow on warnings:\\ {{images:mapping_warnungen_statusleiste.png?nolink}}
  - It is red on error:\\ {{images:mapping_fehler_statusleiste.png?nolink}}

All translation steps are displayed in a log window, but this must first be displayed via the {{images:windows.png?nolink}} button in the status bar((In Mapping Designer, below)).\\ 

==== XPath Queries ====

With the [[transformation:mappings:details#xpath_query|XPath query]] individual selections can be tested for the source instance.


===== 4. mapping error ======

If errors occur, the entries of the objects where an error occurred are marked red in the {{images:windows.png?nolink}} log window with object name and error description. The error description can then be used to locate and correct incorrect links. 

==== Custom Error Message =====

If a more complex error output is required, a separate **CustomErrorExpression** can be defined in the map editor for each mapping rule under [[en:transformation:mappings:anlegen:extended_properties#element-eigenschaften|element-properties]]. This must also be a [[en:transformation:mappings:details#xpath_abfrage|XPath-Expression]] e.g. :\\ 

<code>concat('At position: ', $position,' missing the EAN!')</code>\\