Mapping files are used
to configure import and export of requirements from resp. to external RM tools.
Besides the pure type, attribute and value mapping, there is also support to
actually „select“ a mapping based on a certain selector predicate. That
predicate is a short script written in Java Script language, either as „medini“
selector (when exporting) or „mapped“ selector (when importing). There are a
few things that can go wrong here; this article lists 5 of the most common one.
1. Using quotes in the selector script
The selector script is
defined as an attribute of the type mapping inside the mapping XML. The XML
code is using double quotes for attribute values so it is impossible to use
double quotes inside the Java Script itself again. If you do that, you
immediately will break the XML and wont be able to finish import.
This XML is not correct:
mappedSelector="alert("hit"); true"Will lead to
Fortunately
the JS interpreter accepts double as well as single quotes. Make sure you
always use single quotes in selector scripts.
This XML is correct:
mappedSelector="alert('hit'); true"And will lead to many of those:
2. Returning
values other than true or false
The selector script is
expected to return either true (use this mapping) or false (do not use this
mapping). Any value other than true or false is interpreted as false! Remember
that the last statement of the script is used as the return value so make sure
your script in the end evaluates an expression to true or false.
Not correct
mappedSelector="console.log(element.name)"
Correct
mappedSelector="element.name != ‚foo‘"
3. Syntax or
runtime error in the script
If the script has a
syntax error or throws an exception at runtime, the problem is currently NOT
reported anywhere. Instead, it is silently ignored and interpreted as false. This
is for historical reasons and an improvement is planned.
Not correct:
mappedSelector="tru"
To diagnose any
problem with the script it is advised to wrap the script in a try/catch
statement and log the problem to the console.
Example:
mappedSelector="try { tru } catch (e) { console.log('Selector failed: {0}', e); false; } "Will lead to this console output:
> Selector
failed: ReferenceError: "tru" is not defined.
4. Using
extended API or other code that depends on pragmas
Some sample code
floating around in this forum uses extended API or special code for example the
„load“ function that requires certain pragmas in place. You may remember that
these pragmas have to be defined in the first line of a script. That is also
true for selector scripts.
Wrong:
mappedSelector="load('doorsng.js'); shape(element, [ 'Heading' ]);"Make sure the right
pragma is in place as for example the $EXPERIMENTAL$ flag. Put it as comment to
the front of your script.
Right:
mappedSelector="/* $EXPERIMENTAL$ */ load('doorsng.js'); shape(element, [ 'Requirement' ]);"
5. Using
selectors breaks the element hierarchy
Using selectors to use
different mappings is working nicely as long as you define mappings for all
types found in the remote module. If you start „picking“ just selected items
but drop others you may run into the problem that medini does not want to
import elements because their direct parent element was not mapped and thus is
not available in medini to place the imported requirement into. These cases
should be avoided. If for any reason you still need to import a sub-set of the
requirements and you are sure you do not need to export them later back to the
server, you may use the „FORCE_AT_ROOT“ option on the mapping definition:
<mapping:MappingDefinition
…
name="Mapping File with FORCE ROOT option enabled"
description="…"
onInit="options['FORCE_AT_ROOT'] = true;">
