Using Force Elements During Mapping Rule Activation and Deactivation

In order to provide hooks directly into the mapping rules, There are force elements which allow you to evaluate an expression when a mapping rule is activated, deactivated or both. The force element also provides a way to halt execution of the translation. While the expression evaluated will not be used, some expressions have side effects (such as logging, or arbitrary Tcl scripts) which will only be activated when the expression is evaluated.

The force element must be an immediate child of the mapping element. There are four possible attributes:

1. onActivation: the legal values are “true” or “false”
2. onDeactivation: the legal values are “true” or “false”
3. halt: the legal values are “true” or “false”
4. halt-on: where the legal value is any, including the empty, string

The halt attribute defaults to false if it is not specified.

The onActivation and onDeactivation attributes specify when the contained expression should be evaluated. At least one of onActivation or onDeactivation must be set to ‘true’ or the expression will not be evaluated. It is possible to specify that an expression be evaluated both when the mapping rule is activated and when it is deactivated. This is often useful when combined with the <logexpr> element (discussed later) to determine when various mapping rules match.

There is no default values for the halt-on attribute, this attribute provides the ability for a <force> element to conditionally halt the xfMap. The attribute will cause the xfMap to halt, if it is present and the expression sequence within the <force> element evaluates exactly to the string set on the halt-on attribute.

The following example will halt the reader when a <Tablet> element is matched, the message “’Tablet’ – is not supported” will also be printed as an error to the FME logfile.

<mapping match=”Tablet”>

     <force onActivation=”true” halt=”true”>

       <logexpr severity=”error”>

         <arg>

            <literal expr=”’”/>

            <matched expr=”qname”/>

            <literal expr=”’ – is not supported“/>

         </arg>

       </logexpr>

     </force>

   ...

</mapping>

Note: There is one significant limitation on <force> elements if the contained XML expression sequence has an ‘extract’ element. Since the XML reader is a streaming reader, then when a mapping rule is activated, the entire content of the XML element that triggered it is not yet read. In fact, only attributes of the triggering element will be available for extracting during the activation phase. Extract elements which attempt to reference child elements of the triggering element will evaluate to the empty string on activation of the mapping rule. No such restriction is imposed on mapping rule deactivation.