As of version 9.1, Kapow Katalyst has an XML Data Mapper that allows convenient mapping of the data records specified by an XML document into variables of suitable structure.
Selection of the relevant XML element in the source view:
Issues specifically related to selection is further discussed under Selection.
Configuration of the mapping through the "Extract with XML Data Mapper..." dialog accessible through the right-click context menu of the selected XML element:
The open dialog confronts you with three areas of configuration:
The actual mapping area is on the left where the leftmost column shows the available source entities, the top right area permits the choice of an appropriate target variable and type, and the bottom right area is reserved for the configuration of details for individual entity mappings. Each area is discussed in detail in the part about Configuration.
Auto-generation of step sequence that performs the desired mapping at run-time. The steps are created automatically when the dialog is closed by a click on OK:
The specifics of auto-generation is described in Auto-generation of Steps
While the selection of data is easy, it is important to know how selection and mapper interact. When a particular XML element has been selected, the following entities may be mapped into variable attributes using the mapper:
The attributes of the selected element itself. In the left hand 'sources' column such attributes figure as plain text names:
The contents of those sub-elements of the selected element that do not themselves contain sub-elements. In the 'sources' column such elements appear in an XML-like format where names are enclosed by < and >:
The attributes of those sub-elements of the selected element that do not themselves contain sub-elements. In the 'sources' column such attributes also appear in an XML-like format where both the enclosing element names and the attribute names are enclosed by < and >:
Note, that in order for the mapper to be activated for a given selection at least one mappable element must be associated with the selected element.
The configuration step is where most of the user interaction takes place. The aim of the configuration step is to point out an appropriate target variable attribute for each source entity that you wish to map (i.e., it is not required to map all available sources). This mapping is undertaken in a number of steps:
Target selection must be completed first using the variable and type selection facilities in the top right corner of the dialog; there are several options:
Appropriate variable and types may be created from scratch:
This is the most 'automatic' option in the sense that attribute names matching the source entities will be automatically generated and a mapping will be suggested:
A new variable of an existing type may be created:
If this option is chosen the system will automatically try to map source entities where the type prescribes attribute names that coincide with the names suggested by the sources themselves:
An existing variable can be retyped. If a new type is created this option will behave as option 1 and automatically suggest attribute names and mappings based on the available source entities:
If an existing type is selected the behavior is similar to option 2 in the sense that the system will try to map sources automatically based on the attributes in the type:
Note, that when a new mapping is initiated, the system will try to make appropriate choices of variable and type automatically. These suggestions are made based only on the tag name of the selected XML element. If a variable has the same name it will be suggested along with the type that it carries. If no such variable exists but a type is named like the tag name, it will be suggested to create a new variable using this type.
Entity mapping is performed in the left part of the dialog. Two columns show the available source entities and target attributes and in order to map a source entity to a target attribute you simply select the source by clicking it and then select the target by clicking it. This creates a connection shown as a line connecting the source and target:
Thus, the drawn line denotes a specific mapping associating a source and a target. Note that it is possible to map a single source to more than one target:
Each association has a checkbox near the source. If the source entity is required for the overall mapping to be sound, the box should be checked, otherwise not:
Associations can be dissolved as easily as they are created, you simply hover the line close to the target with the mouse and click the red cross that appears:
If no target attribute suitable for the source entity you want to map is offered by the chosen target variable you can add one as part of the mapping process. Once your source is selected you simply click the add button () rather than an existing target attribute. This opens a dialog where you can assign a name and a type to the attribute you are about to add:
Should it happen that an attribute has been mistakenly added it can removed by first selecting it in the right hand column and then clicking the remove button (). Please note that this will only work for attributes that have been added in the current invocation of the mapper, i.e. attributes that have not yet been persisted in the corresponding type file.
Further mapping details can be configured in the lower part of the right hand panel once a specific mapping association has been selected by clicking the target attribute in the right hand column:
A number of details can be configured via this configuration panel:
The target attribute name can be changed here if the attribute was newly added, i.e. it has not yet been persisted.
The target attribute type can be changed here if the attribute was newly added, i.e. it has not yet been persisted.
Data converters may be associated with the mapping, such that data may be brought into acceptable form.
Trim spaces may be toggled on/off if the source entity is an XML attribute.
Once the configuration of a data mapping is done and you press OK in the dialog, the system auto-generates the actual steps required to perform the implied extractions and inserts these steps into the robot. The procedure always generates exactly one extract or extract tag attribute step for each association created in the mapper:
The step are aggregated into a group, which in essence can be thought of as the resulting data mapping, and inserted into the robot. In order to ensure the precision of the data mapping it must be anchored by a named tag that identifies the originally selected XML element. If such a named tag does not exist a Set Named Tag step is generated and inserted into the robot just before the actual data mapping:
Sometimes such a Set Named Tag is not necessary because a suitable named tag is already in place. For instance, this is often the case when the mapping is part of a loop:
Once a data mapping has been configured it can be opened in the data mapper and edited again at a later time. Since data mappings are associated with group steps, the ability to reopen the mapper is also connected to group steps. For a given data mapping you can open the data mapper by selecting Open XML Data Mapper... from the context menu associated with the appropriate group step:
It is important to know that this will only work if the group step is the current step, i.e. green, because otherwise there may not be XML information to support the mapper. Another way of opening the mapper for a group step that is current is to click the Open XML Data Mapper... button in the associated step view:
Once open the mapper will behave exactly as described in How to Create a Data Mapping.
It is of course possible to edit the steps of a data mapping by hand. Only certain changes, however, are compatible with the XML data mapper and opening of a data mapping is therefore subject to a number of conditions, essentially expressing that the group step 'must' be a real data mapping: