Supplying Node Metadata to Node Functions
There might be cases when you want a node function to do something based on some information about the current node (let's call this information "node metadata"). For example, you might need a node function with the following logic: if the node name contains the word "Total", then append the dollar sign to the node value; otherwise, return the node value as is.
In the example just mentioned, "node name" is an example of node metadata. Generally speaking, "metadata" means something which describes data itself, that is, "data about data". By "node metadata", therefore, we understand miscellaneous information about the node on which the function applies, such as node name, value length or precision in case of numeric database types, and others.
The following table lists all possible metadata that you can use in a node function. Note that some metadata listed below is meaningful only for nodes of specific kind (for example, XML or database fields). Consequently, MapForce will display a warning when you attempt to use metadata that is incompatible with the current node.
Provides the name of the current node. This metadata is applicable to all nodes. In case of XML, this is the name of the current element or attribute. In case of CSV, this is the name of the CSV field. In case of databases, it is the name of the table column.
Provides the annotation text displayed next to an item when you click the Show Annotations toolbar button. This metadata is applicable to all nodes.
Provides the value of minLength facet of the node's data type. Applicable to XML and text nodes with appropriate types.
Provides the value of maxLength facet of the node's data type. Applicable to XML and text nodes with appropriate types.
Provides the value of the totalDigits facet of the node's data type. Applicable to XML nodes with appropriate types.
Provides the value of the fractionDigits facet of the node's data type. Applicable to XML nodes with appropriate types.
Provides the length of the node's data type. Applicable to database fields with appropriate types.
Provides the precision of the node's data type. Applicable to database fields with appropriate types.
Provides the scale of the node's data type. Applicable to database fields with appropriate types.
To supply metadata to a node function:
1.Start creating a new node function (see Creating Defaults and Node Functions) or open an existing one for editing (see Editing and Deleting Existing Rules). For example, the function illustrated below concatenates the string "\$" with the node value and returns the result back to the outer mapping. You can find the mapping of this function at the following path: <Documents>\Altova\MapForce2022\MapForceExamples\OrderInUSD.mfd. To open the function's mapping, click the icon next to the Rows item of the target component, and then click the button on the grid.
2.Do one of the following:
•Click Add Node Specifics.
•Right-click an empty area in the mapping, and select Insert Input from the context menu.
•Click the Insert Input toolbar button.
•On the Function menu, click Insert Input.
3.Select the required metadata from the dialog box (for example, "node_name").
|Note:||When you select a metadata parameter to insert, MapForce analyzes all currently expanded nodes on the mapping where the node function already qualifies to apply and determines whether the metadata parameter is supported by these nodes. If not supported, the dialog box displays a warning similar to "The selected metadata parameter is not supported by any currently existing node in the scope of this function". Note that, by default, deeply nested structures are not fully scanned, in order to preserve memory and improve the user experience. If the component where you apply the node function has such deeply nested structures, you can expand the relevant nodes on the mapping so as to make MapForce aware of them. In this case, MapForce will take the expanded nodes into account when you add a new metadata parameter, and the warning may disappear. Remember that a connection must exist for the node function to apply; expanding unconnected items is not relevant.|
4.If the metadata is not supported for the node where the function qualifies to apply, you can decide the behavior of the function as follows:
a.Select the check box Return empty sequence from input if you want to apply the node function and have the metadata parameter return an empty sequence. An empty sequence should not be confused with an empty string. You typically need to use sequence functions such as substitute-missing or exists, or other component types to process it further. Warning: The empty sequence must be handled; otherwise, the node function might not return a value at all.
b.Select the check box Do not apply the node function if you do not want to apply the node function at all when this metadata is not supported by the node.
5.Click OK. A new input parameter is now added to the function's mapping, in addition to the default raw_value one. You can now connect the new parameter's output connector to some target item where you need this metadata (typically, a function's input connector).