Functoids

BizTalk provides functoids to provide a way of performing some processing on the source values before it is copied to the destination. This processing can be anything from converting a string to uppercase over mathematical trigonometric functions to doing a database lookup.

The functoids are divided into categories, and the functoids in each category are described in the following sections. This chapter describes all the functoids. In the section “Advanced Maps,” there are examples of advanced usage of the functoids.

After dragging a functoid to the grid, you can click it to see the properties of the functoid in the Properties window. If the Properties window is not present, you can right-click the functoid and choose Properties, or you can click the functoid and press F4. The Properties window contains the properties listed in Table 3.4.

Table 3.4. Functoid Properties

The screen for configuring the functoid parameters can be resized if necessary. Notice that when you drag a functoid to the grid, it has a yellow exclamation mark on it. This indicates, that the functoid is not fully configured, which at compile time would give you a warning or an error depending on the severity of the missing configuration. When you hover over a functoid that has the yellow exclamation mark on it, you get a tooltip describing what needs to be changed. Most of the time, you have missing input parameters or haven’t connected the output of the functoid to anything.

Figure 3.14. Parameters for a functoid without labels on the links.

Figure 3.15. Parameters for a functoid, using labels on links.

String Functoids

The string functoids perform string manipulation on either an incoming value or a set of values. They all output a string, which can be used as the input for another functoid or sent directly to the destination schema. Table 3.5 lists the string functoids, their usage, and parameters.

Table 3.5. The String Functoids

Mathematical Functoids

The mathematical functoids perform mathematical operations on their input and return an output that can be used as the input for another functoid or sent directly to the destination schema. Because the input parameters to a mathematical functoid are strings and a mathematical functoid returns a string, there are some methods used by the functoids to convert a string into a number to perform mathematical functions on the inputs. As a general rule, an input to a mathematical functoid that is not a number is ignored and if the parameter cannot be ignored, like either parameter in a division, an empty string is returned. Table 3.6 lists the mathematical functoids, their usage, and parameters.

Table 3.6. The Mathematical Functoids

All the functoids return an empty value if a specified parameter is not a number. Optional parameters can be omitted, but if they are used, they must also be numbers or an empty string is returned.

Logical Functoids

The logical functoids perform logical operations on their input and returns a Boolean value that can be used later on as the input for another functoid or to instruct the compiler how to construct the generated XSLT. How the logical functoids aid the compiler in constructing the generated XSLT is discussed in the “Advanced Maps” section. Because the logical functoids are used for either input to other functoids or to instruct the compiler, you cannot get the output of a logical functoid into your destination schema. If you want to do so, you can add a C# scripting functoid (described later) with the code as shown in Listing 3.1 and place that in between the logical functoid and the destination node. Table 3.7 lists the logical functoids, their usage and parameters.

Table 3.7. The Logical Functoids

Listing 3.1. C# Code for Getting Output of a Logical Functoid into a Destination Node

---

public string LogicalToString(string logical)
{
       return logical;


}

---

All the functoids that need to take a Boolean as input need to parse the input to make sure it is in fact a Boolean and not some random string. The algorithm for this is as follows:

1. The input is compared to the string true in a non-case-sensitive manner. If this succeeds, a value of true is returned, and processing stops.

2. The input is compared to the string false in a non-case-sensitive manner. If this succeeds, a value of false is returned, and processing stops.

3. The string is trimmed to remove leading and trailing whitespace.

4. The input is compared to the string true in a non-case-sensitive manner. If this succeeds, a value of true is returned, and processing stops.

5. The input is compared to the string “false” in a non-case-sensitive manner. If this succeeds, a value of false is returned, and processing stops.

6. The input is converted into a number. If this fails, a value of false is returned.

7. The number is greater than 0, a value of true is returned. Otherwise, a value of false is returned.

This algorithm is used by the Logical OR, Logical NOT, and Logical AND functoids to validate the input.

The Not Equal, Equal, Less Than or Equal To, Less Than, Greater Than or Equal To, and Greater Than functoids can all compare numbers to numbers and strings to strings.

Date/Time Functoids

The date/time functoids are a collection of functoids that deal with dates/times. Their output can be used as the input for another functoid or sent directly to the destination schema. Table 3.8 lists the date/time functoids, their usage, and parameters.

Table 3.8. The Date/Time Functoids

Conversion Functoids

The conversion functoids perform conversions on their input and return output that can be used as the input for another functoid or sent directly to the destination schema. Table 3.9 lists the conversion functoids, their usage, and parameters.

Table 3.9. The Conversion Functoids

Scientific Functoids

The scientific functoids perform scientific mathematical operations on their input and return an output that can be used as the input for another functoid or sent directly to the destination schema. Table 3.10 lists the scientific functoids, their usage, and parameters.

Table 3.10. The Scientific Functoids

For all the functoids you get an empty string as the result in case the input parameters could not be parsed as a number.

All trigonometric functoids like Sine, Cosine, Tangent, and Arc Tangent assume the input is in radians. This means that if you want to use any of these functoids on a value of 180° you need to convert the 180° into p first.

Cumulative Functoids

The cumulative functoids perform operations on reoccurring nodes in the source schema and output one value based on all the occurrences of the input node. The output can be used as the input for another functoid or sent directly to the destination schema. Table 3.11 lists the cumulative functoids, their usage, and parameters.

Table 3.11. The Cumulative Functoids

All the cumulative functoids take in two parameters. The first parameter is the value to be accumulated, and the second is a scoping parameter. The scoping parameter is used to generate the XSLT. If no value is passed on, a default value of 1000 is used in the XSLT. If a value is actually passed into the parameter, this is used as an indication of what level of scope to do the accumulation. A value of 0 means that all occurrences of the first parameter are accumulated and the functoid will therefore have only one output. A value of 1 means that the values are accumulated for each parent of the first parameter and an output is therefore generated for each parent. A value of 2 means that the values are accumulated for each grandparent of the first parameter and so on. Note that it is not the functoid that contains this logic. The generated XSLT will do all this for you, making sure that the functoid is called for each level of scoping needed.

Database Functoids

The database functoids can be split into two categories; Those that do database lookup and those that do cross referencing.

Database

The database functoids are used for looking up values in an ADO.NET-compliant database that can be used as the input for another functoid or sent directly to the destination schema. Table 3.12 lists the database functoids, their usage, and parameters.

Table 3.12. The Database Functoids

Cross Referencing

The cross-referencing functoids are used for looking up values in a database and using the values retrieved as the input for another functoid or sending it directly to the destination schema. This is used to map values that are specific to one system to the corresponding values from another system. For instance, you can use this setup to find your enterprise resource planning (ERP) system item number based on the item number your customer has supplied you with in the order you have received.

The cross-referencing functoids are restricted to and make use of the 9 xref_* tables that are present in the BizTalkMgmtDb database. Importing data into these tables is done via the BizTalk Server Cross Reference Import tool (btsxrefimport.exe), which you can find in the BizTalks installation folder. The utility takes in a parameter that specifies the filename of an XML file that basically contains references to eight other XML files, which contain the data that must be imported into the xref_* tables. When data is in the tables, the cross-referencing functoids can be used to look up values in the tables. For detailed information about the syntax of these XML files and how to import the data into the database tables, refer to http://msdn.microsoft.com/en-us/library/aa578674(BTS.70).aspx. Table 3.13 lists the cross-referencing functoids and their usage.

Table 3.13. The Cross-Referencing Functoids

You can see an example of the use of the cross-referencing functoids in the “Advanced Maps” section.

Advanced Functoids

The advanced functoids perform advanced operations on their input. Some of them return an output that can be used as the input for another functoid or sent directly to the destination schema. The use of others assists the compiler in creating the necessary XSLT. Table 3.14 lists the advanced functoids, their usage, and parameters.

Table 3.14. The Advanced Functoids

Third-Party Functoids

You can download several third-party functoids and use them in your solutions. Use your favorite search engine to locate them.