Example: Import Custom XQuery Function
This example shows you how to import a demo XQuery library module into MapForce and call its functions from a mapping. The demo module in this example consists of only one function which calculates tax on decimal amounts as 20% of the amount. In a production scenario, an XQuery module may contain multiple functions.
All functions declared in the XQuery module must return atomic types and their parameters must also be of atomic data types. Otherwise, the module is not eligible for import into MapForce. |
You can find the demo XQuery module file at the following path relative to your personal "Documents" folder on the computer where MapForce is installed: <Documents>\Altova\MapForce2024\MapForceExamples\Tutorial\module.xq.
xquery version "1.0"; |
module.xq
After you import the XQuery module file into MapForce, you will be able to call the demo:calculatetax function from a mapping. Note that calculating the tax amount with the help of an XQuery function is just for demo purposes—you can achieve the same result by using MapForce built-in functions.
A demo mapping which calls the demo:calculatetax function above is available at the following path: <Documents>\Altova\MapForce2024\MapForceExamples\Tutorial\CalculateTax_XQuery.mfd. When you open this mapping initially, MapForce displays a warning that it contains one or more components that are not available in XQuery. This warning is normal and it occurs because the mapping references a function from a custom XQuery library module that was not imported yet. To remove the warning and run the mapping, we will import the missing XQuery module into MapForce as shown below.
To import the XQuery module into MapForce:
1.Click the Add/Remove Libraries button at the bottom of the Libraries window. The Manage Libraries window opens (see screenshot below).
2.To import functions as a local library (in the scope of the current document only), click Add under the current mapping name. To import functions as a global library (at program level), click Add next to Global Library Imports. When you import a library locally, you can set the path of the library file to be relative to the mapping file. With globally imported libraries, the path of the imported library is always absolute.
3.Browse for <Documents>\Altova\MapForce2024\MapForceExamples\Tutorial\module.xq and click Open. A message box appears informing you that a new library has been added.
The imported library and the demo:calculatetax function are now visible in the Libraries window.
Also, the mapping can now be validated and run without warnings. The demo:calculatetax function illustrated in the image below originates from the imported XQuery module, and it can be added to the mapping just like any other built-in function, see Add a Function to the Mapping.
CalculateTax_XQuery.mfd
The mapping explained
The CalculateTax_XQuery.mfd mapping illustrated above takes as input an XML file that stores articles. Each article has a single price expressed as a decimal value, for example:
<Articles> |
Articles.xml
The mapping produces an XML file which abides by the same schema as the source XML file. Therefore, both the source and target components have the same structure on the mapping. As the mapping connections suggest, nearly all elements are mapped in a straightforward way from target to source—for example, for each Article in the source there will be an Article in the target. The values of all items are copied verbatim from the source XML, except for SinglePrice. The value of SinglePrice is calculated with the help of two functions:
•The demo:calculatetax XQuery function calculates the tax amount by taking the original SinglePrice as input.
•The MapForce built-in add function adds the tax amount to the original SinglePrice amount and returns the final amount.
Importantly, the data type of the SinglePrice item is xs:decimal—which corresponds to the input parameter type and the return type of the XQuery function.
The output produced by the mapping when you click the Output pane is illustrated below. Notice the increase of 20% applied to each price compared to the source XML.
