position
Returns the position of an item within the sequence of items currently being processed. This can be used, for example, to auto-number items sequentially.
Languages
Built-in, C++, C#, Java, XQuery, XSLT 1.0, XSLT 2.0, XSLT 3.0.
Parameters
Name | Description |
|---|---|
node | This input must receive a connection from a mapping item that provides a sequence of zero or more values. For example, the connection may originate from a source XML item, a CSV field, a database record, and so on. |
Example
The following mapping illustrates using the position function in order to generate unique identification values in data generated by the mapping. This mapping is accompanied by a mapping design file that is available at the following path: <Documents>\Altova\MapForce2024\MapForceExamples\ContactsFromBranchOffices.mfd.
ContactsFromBranchOffices.mfd
In the mapping above, the source XML file contains three branch offices. A branch office may contain an arbitrary number of Contact child items. The goals of the mapping are as follows:
•Extract all Contact items from the source XML file and write them to the target XML file.
•Each contact must be assigned a unique identification number (the ID item in the target XML).
•The ID of each contact must take the form CXX-YYYYY, where X identifies the office number, and Y identifies the contact number. If the office number is less than two characters, it must be left-padded with zeros. Likewise, if the contact number takes less than five characters, it must be left-padded with zeros. Consequently, a valid identification number of the first contact from the first office should look like C01-00001.
To achieve the mapping goals, several MapForce functions have been used, including the position function. The upper position function gets the position of each office. The lower one gets the position of each contact, in the context of each office.
When using the position function, it is important to consider the current mapping context. More specifically, when the mapping runs, the initial mapping context is established from the root item of the target component to the source item connected to it (even indirectly via functions). In this example, the upper position function processes the sequence of all offices and it initially generates the value 1, corresponding to the first office in the sequence. The lower position function generates sequential numbers corresponding to the contact's position in the context of that office (1, 2, 3, and so on). Note that this "inner" sequence will be reset (and thus start from 1 again) when the next office gets processed. Both pad-string-left functions apply padding to the generated numbers, according to the requirements stated previously. The concat function operates in the context of each contact (because of the parent connection from the source to the target Contact). It joins all the computed values and returns the unique identification number of each contact.
The output generated from the mapping above is shown below (note that some of the records were removed for readability):
<Contacts> |
There may also be cases where you need to get the position of items resulting after applying a filter. Note that the filter component is not a sequence function, and it cannot be used directly in conjunction with the position function to find the position of filtered items. Indirectly, this is possible by adding a variable component to the mapping. For example, the mapping below is a simplified version of the previous one. Its mapping design file is available at the following path: <Documents>\Altova\MapForce2024\MapForceExamples\PositionInFilteredSequence.mfd.
The result of variables in MapForce are always sequences. Therefore, in the mapping above, the position function iterates through the sequence created by the variable and returns the position of each item in that sequence. This mapping is discussed in more detail in Example: Filtering and Numbering Nodes.