Example: Look-up and Concatenation
There are several demo mappings available with MapForce that illustrate typical usage of user-defined functions. One of these mappings is the PersonListByBranchOffice.mfd file available in the <Documents>\Altova\MapForce2022\MapForceExamples\ folder.
This mapping has the following business requirements:
•Extract data from a source XML file and write it to a target XML file. Data consists of employee details, such as first name and last name.
•Look up certain data about each employee in a separate XML file (phone, email address, position).
•Process data in a desired way before writing it to the target. Namely, the phone, email and position of each person must be represented as a single string (comma-separated) and written to the Details element of the target XML.
•Extract only XML elements that match certain criteria—in this case, information about employees from a specific branch office. Callers of the mapping must be able to specify the office name as a parameter at the command line, for example, when the mapping is executed by MapForce Server.
Let's now examine the components that implement the requirements above:
•The input parameter of the mapping ("OfficeName") is a simple input component. A default value ("Nanonull, Inc.") is provided by a constant—this value will be used if the caller of the mapping does not provide a parameter value. To find more about simple input components, see Supplying Parameters to the Mapping.
•To filter only employees that belong to a specific office, the mapping uses a filter component ("Office"). Essentially, the filter checks whether the office name supplied by the parameter is equal to the office name in the source XML file. If yes, the filter passes data from the source Office item to the target component. For more information about filters, see Filters and Conditions.
•To look up information from the second source XML file, the mapping calls a user-defined function, "LookupPerson". The logic of this function is discussed in more detail below.
•To process employee data, the "LookupPerson" function calls internally other functions that retrieve and concatenate information about each employee in a suitable way. All these operations are in the function's own mapping and not visible in the main mapping—a typical example of encapsulation. The "LookupPerson" function then populates the Details element in the target XML.
The look-up functionality is provided by the "LookupPerson" function, whose definition is illustrated below.
As shown above, the function includes the source XML file from where data should be retrieved. Next, it has three input parameters that provide the look-up values: Office_Name, First_Name, and Last_Name. All input parameters are set as mandatory (that is, the check box Input is required is selected in the Properties dialog box).
The "EqualAnd function" is a separate user-defined function enclosed into the current one. This function returns a Boolean value. Calling this function in the sequence illustrated above provides the following Boolean logic:
The function's value (TRUE or FALSE) is passed to the filter each time a new item is processed. When the filter gets value TRUE, the look-up operation is successful and the employee's details are retrieved and returned to the outer mapping. Otherwise, the next item in context is examined, and so on until the loop finishes.
In the first occurrence of "EqualAnd" function, connector b has a circle around it—this indicates that this parameter is set as priority context. Priority context is an optional feature that optimizes the execution of the mapping. Namely, it ensures that the person data of the specific office supplied by the input parameter a is processed first. To set a parameter as priority context, right-click it and choose Priority from the context menu. For more information, see Priority context.
The "Person2Details" function is another function nested into the "LookupPerson" function. This function returns a string value. It concatenates the three values received as parameters and two text constants, as illustrated below:
The concat function is a MapForce built-in function that can take as many parameters as required, see Add or Delete Function Arguments.
Running the mapping
To preview the mapping execution in MapForce, click the Output tab. The mapping runs with the default input parameter ("Nanonull, Inc.") and consequently retrieves employee data only for this office. To retrieve data for another office, change the constant connected to the input parameter from "Nanonull, Inc." to "Nanonull Partners, Inc." and run the mapping again.
If you have licensed MapForce Server, you can also run the mapping at the command line on a Linux, macOS, or Windows machine. First, compile the mapping to a MapForce Server execution file (.mfx) with the menu command File | Compile to MapForce Server Execution File, see also Compiling Mappings to MapForce Server Execution Files. Next, copy the .mfx file to the server machine and run MapForce Server with the command below. The named parameter -p=OfficeName supplies the input value:
mapforceserver run PersonListByBranchOffice.mfx -p=OfficeName:"Nanonull, Inc."
•mapforceserver is the path to the MapForce Server executable as applicable for your operating system.
•Change the path to the .mfx file as applicable, or copy the .mfx to the same folder as the executable.