How Defaults and Node Functions Work

www.altova.com Print this Topic Previous Page Up One Level Next page

Home >  Functions > Defaults and Node Functions >

How Defaults and Node Functions Work

As explained in How to Create Defaults and Node Functions, you can create node functions or defaults for nearly any item (node) on the mapping. Let's call this process defining a rule. Rules have the following important characteristics that make them extremely flexible:

 

Inheritance. When you define a rule on an item that has descendants, the rule will be inherited by descendants by default, unless you choose to disable this option. If the item where you define the function has multiple levels of child items nested under it, you can choose to apply the rule only to direct child items, or to all descendant items.
Type Filtering. MapForce applies rules conditionally, based on the data type of each item. This makes it possible, for example, to apply a certain default value (or a function) for all items of string type, and a different default (or a function) for all items of numeric type. You can also apply rules only to nodes of a specific type that match a specific name or regular expression.

 

The behavior described above has implications. Namely, it is important to make a difference between defining a rule and actually applying one. When you define a rule on some item, it does not necessarily mean that the rule will affect that item. The rule will apply to the item or its descendants only if the rule criteria (data type and inheritance) allow it.

 

To help you understand which rules are defined and which ones apply, MapForce provides the following visual clues on the mapping:

 

Icon

Description

mf_ic_node_func_defined

This icon (black color) indicates that a rule is defined for this item, and may affect all its descendants. Click the icon to modify or delete the rule.

mf_ic_node_func_applied

This icon (red brick color) indicates that the item qualifies (is eligible) for a rule defined at some ancestor level. In other words, there exists a rule that applies to (and may affect) this item.

mf_ic_node_func_defined_applied

This icon (bold, red brick color) indicates that a rule is defined for this item, and at the same time a rule applies to this item. This icon usually appears when a default is defined for a single node.

mf_ic_node_function_blocked

This icon indicates that, even though a rule applies to this item, it is deliberately blocked. You can do this for certain items where you do not want the rule to apply.

 

Note: This icon is displayed only if inheritance is blocked and no other rules are defined at this node. If a rule from an ancestor does apply, the mf_ic_node_func_appliedicon has priority.

mf_ic_node_func_inactive

This icon (grayed out) indicates that, even though a rule applies to this item, it is inactive. For example, this icon may appear for items that are not connected yet on the mapping.

 

In general, when multiple node functions or defaults exist for one and the same item, keep in mind the following rule of thumb:

 

For any single item on the mapping, MapForce always applies only one node function and only one default, regardless of how many node functions or defaults qualify to apply for that item.

 

In practice, this translates as follows:

 

When multiple rules exist for one and the same item, MapForce will apply to an item the rule that is closer to that item. For example, let's assume that you have defined a node function three times: on a root XML node called Company, on its child node called Department, and on the grandchild Employee. In this case, MapForce will apply to the Employee item the function defined on the Employee item, since it is closer. Had there been no function there, it would look up to find the function of the immediate ancestor, Department. If there is no function for Department, then it looks further up to the root node, which in this case is Company. Inheritance is optional; to disable it, clear the Inherit rules from ancestors check box. When this check box is cleared, the item gets the "blocked rule" mf_ic_node_function_blockedicon.
When one and the same item has multiple rules, then MapForce applies the first matching rule from the grid at the top of the Mapping pane. To change the order of rules in this grid, click a rule and then drag and drop to a new position within the grid. Note that you can drag a rule in the grid only if it is defined for the current item. You cannot change the position of inherited rules; you can only enabler or disable inheritance.

 

To better illustrate how this works, we will use a mapping available at the following path: <Documents>\Altova\MapForce2019\MapForceExamples\Tutorial\MissingFields.mfd.

mf_nodefunc_01

MissingFields.mfd

As shown above, this mapping reads data from a source XML file into a target text file (fixed-length fields). In the source XML file, the element Article has child elements of different type: "integer", "string", and "decimal". Note that each child element is optional (minOccurs="0"). Therefore, if any of these elements does not exist in the source XML, you will want to provide a default value; otherwise, you will see empty fields in the target CSV file, for example:

 

  T-Shirt   25    Available in all sizes      

2            2.3                                

3  Pants           Limited stock                

4  Jacket    57.5                              

 

Below we illustrate various ways to handle missing data by means of rules, along with explanations of how rules affect the mapping result. They will also help you understand or control which rule should prevail when multiple rules exist for a given item.

 

Example 1: Provide defaults for all string items

Given the mapping MissingFields.mfd, let's assume that you have the following requirement: If any child of Article is of type "string" and is missing, use "n/a" as default value.

 

To satisfy this requirement, take the steps below:

 

1.Right-click the Article item, and select Node Functions and Defaults | Output Node Functions and Defaults from the context menu.
2.Click Add default ( mf_ic_add_default ).
3.Under Default value, type "n/a" and press Enter.

mf_nodefunc_02

In the mapping above, the rule criteria are set as follows: For all descendant items of Article, if the data type is "string", and if the source XML element is missing, use the default value "n/a". In this example, there are two items of type "string", Name and Description, so the rule will apply to both.

 

As stated before, the item where a rule is defined has the mf_ic_node_func_defined icon next to it. Items where the rule will apply have the mf_ic_node_func_applied icon. If you preview the mapping at this stage, you can see that all missing strings have now been replaced with "n/a" in the output:

 

  T-Shirt   25    Available in all sizes      

2  n/a       2.3   n/a                          

3  Pants           Limited stock                

4  Jacket    57.5  n/a                          

 

Example 2: Provide defaults conditionally based on data type

Let's now assume that, in addition to defaults for string items, you must also supply a default value 0 for any item of numeric type. To satisfy this requirement, take the steps below:

 

1.Click the Article item.
2.Click Add default ( mf_ic_add_default ) and add a second rule with the following criteria:

mf_nodefunc_03

In the mapping above, the rule criteria are set as follows:

 

For all descendant items of Article, if the data type is "string", and if the source XML element is missing, use the default value "n/a"
For all descendant items of Article, if the data type is numeric, and if the source XML element is missing, use the default value "0".

 

Consequently, the output looks as follows:

 

0  T-Shirt   25    Available in all sizes      

2  n/a       2.3   n/a                          

3  Pants     0     Limited stock                

4  Jacket    57.5  n/a                          

 

Note:The data type "numeric" is actually a type category, because it includes both the "integer" and "decimal" data types. It also includes the types "float" and "double", although such types are not present here. In this example, the rule will apply to both Number and SinglePrice elements. If you select "decimal" as data type, the rule will still apply to both Number and SinglePrice, because type "integer" derives from type "decimal", in the XML schema type hierarchy (see §3 in "XML Schema Part 2: Datatypes Second Edition", https://www.w3.org/TR/xmlschema-2). If you select "integer" as data type, however, the rule will apply only to Number.

 

Example 3: Block rule for a specific item

Let's now assume that you still want to apply defaults for all string and numeric items, like in the previous example. However, you do not want to set any default to the SinglePrice item.

 

To satisfy this requirement, click the item SinglePrice, and then clear the check box Inherit rules from ancestors.

mf_nodefunc_04

In the mapping above, the item SinglePrice no longer inherits rules from its parent, Article. Therefore, a "blocked rule" icon mf_ic_node_function_blocked appears next to it.

 

Consequently, the corresponding field still appears empty in the output:

 

0  T-Shirt   25    Available in all sizes      

2  n/a       2.3   n/a                          

3  Pants           Limited stock                

4  Jacket    57.5  n/a                          

 

Example 4: Override inherited rule for a specific item

Let's assume that you still want to supply defaults for all string and numeric values; however, for item SinglePrice exclusively, you want to set a default value of 9999.

 

To satisfy this requirement, take the steps below:

 

1.Click the item SinglePrice.
2.Click Add default ( mf_ic_add_default ) and type a default value of 9999.
3.Optionally, select the Inherit rules from ancestors check box. This step is merely to illustrate that, in this case, the inherited rules will be overridden anyway.

mf_nodefunc_05

Note:        Inherited rules have yellow background.

 

In the mapping above, there are three rules that may apply for item SinglePrice: two inherited ones, and a direct one. In this case, the rule defined directly on the item wins. The inherited rules will be disregarded. Therefore, the output looks as follows:

 

0  T-Shirt   25    Available in all sizes      

2  n/a       2.3   n/a                          

3  Pants     9999  Limited stock                

4  Jacket    57.5  n/a                          

 

Example 5: Set the priority of rules

Let's expand the previous example further and assume that you define one more rule for item SinglePrice, a default of 8888. As stated before, the rule defined directly on the current item wins. However, since two rules now exist on the current item (in addition to the inherited ones), the legitimate question is, which of the two defaults will apply, 8888 or 9999?

mf_nodefunc_06

When multiple rules exist for the same item like in the mapping above, you can choose the winning rule manually, by dragging it up to the top of the grid. The topmost rule always wins. Therefore, the default value for SinglePrice will be 8888 if this rule is at the top of the grid:

 

0  T-Shirt   25    Available in all sizes      

2  n/a       2.3   n/a                          

3  Pants     8888  Limited stock                

4  Jacket    57.5  n/a                          


© 2019 Altova GmbH