Node Metadata in Node Functions
There might be cases in which you want a node function to do something based on node metadata. By node metadata, we understand miscellaneous information about the node on which the function applies (e.g., a node name, value length, and precision), which is stored in the schema. The table below lists all possible metadata parameters that you can use in a node function. Note that some metadata parameters apply only to specific data types. MapForce will display a warning when you attempt to use metadata that is incompatible with the current node.
Metadata parameters | Description |
|---|---|
node_name | Supplies the name of the current node as it is shown in the component. This metadata is supported by all nodes. In XML files, node_name refers to the name of the current element or attribute. In CSV components, node_name refers to the name of a CSV field. In databases, node_name refers to the name of a table column. |
node_annotation | Displays annotation text next to the node value in the output. This metadata is supported by all nodes. |
node_minLength | Supplies the value of the minLength facet of the node's data type. Applicable to XML and text nodes with appropriate types. For more information about length-constraining facets, see the XML Schema Recommendation. |
node_maxLength | Supplies the value of the maxLength facet of the node's data type. Applicable to XML and text nodes with appropriate types. For more information about length-constraining facets, see the XML Schema Recommendation. |
node_totalDigits | Supplies the value of the totalDigits facet of the node's data type. Applicable to XML nodes with appropriate types. For details about the totalDigits facet, see the XML Schema Recommendation. |
node_fractionDigits | Supplies the value of the fractionDigits facet of the node's data type. Applicable to XML nodes with appropriate types. For details about the fractionDigits facet, see the XML Schema Recommendation. |
node_length | Supplies the length (in bytes) of a number. Applicable to database fields with appropriate types. To find out more about length, see the Microsoft documentation. |
node_precision | Supplies the number of all digits of a number. Applicable to database fields with appropriate types. For more information, see the Microsoft documentation. |
node_scale | Supplies the number of digits to the right of the decimal point of a number. Applicable to database fields with appropriate types. For more information, see the Microsoft documentation. |
| Note: | The data type of a matadata parameter must coincide with the data type of the relevant node. Otherwise, the function execution will fail. |
Add metadata to a node function
To add a metadata parameter to a node function, you need to create a node function and then click the Add Node Specifics option, which is located under the Node Functions window. This will open the Insert Input with Node Specific dialog box, in which you can select a relevant metadata parameter. Instead of the Add Node Specifics option, you can also choose one of the following options:
•Right-clicking an empty area in the mapping and selecting Insert Input from the context menu.
•Clicking the 
toolbar command.
•Clicking Insert Input in the Function menu.
When matadata is not supported by a node
When a metadata parameter is not supported by a node, you can instruct MapForce to return an empty sequence or not to apply the node function (both options are available in the Insert Input with Node Specific dialog box). The empty sequence must be handled; otherwise, the node function might not return a value at all. You would typically need to use sequence functions (e.g., substitute-missing and exists) or other component types to process the empty sequence further.
Example
The example below explains how to supply annotation text to a node function. For this example, you will need the following mapping: <Documents>\Altova\MapForce2024\MapForceExamples\Tutorial\MissingFields.mfd. In MissingFields.xsd (on which MissingFields.xml is based), we have added the following annotation for the Name element: Article name from catalog Spring 2022. Our goal is to supply this annotation to a node function and to see the annotation in the output. Follow the instructions below.
1.Create a node function for the Name element in the ArticlesOfClothing component.
2.Replicate the function shown below. To add a node_annotation parameter, click Add Node Specifics (see red rectangle below) and select this parameter from the list. To find out how to add and manipulate functions, see Functions Basics.
| Note: | By default, deeply nested structures are not fully scanned so as 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 in the mapping 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. The node function must be connected in order to take effect; expanding unconnected items is not relevant. |
Output
The listing below shows that the annotation has been added to the values of the Name elements.
T-Shirt (Article name from catalog Spring 2022) 25.5 20 Available in black, blue, and red Shirt (Article name from catalog Spring 2022) 70.3 60 Pants (Article name from catalog Spring 2022) Limited stock Jacket (Article name from catalog Spring 2022) 57.5 40 |