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
Property Name |
Description |
(Name) |
The name of the functoid. |
Comments |
A text you can alter to contain some comments about this functoid. |
Help |
A textual description of the functoid that describes what the purpose of the functoid is. |
Input Parameters |
Contains the text Configure Functoid Inputs. If you click in it, you get a button to the right of it with the ellipsis. If you click the ellipsis, you get to a window where you can add constant parameters to the functoid and change the order of the parameters. It usually also has text at the bottom that describes the parameters and what they are used for. After parameters are defined for the functoid, they are listed in this property rather than the text Configure Functoid Inputs. |
Label |
This is the only property you can edit. Here you can enter a friendly name for the functoid in question. This has no functional meaning, but it will perhaps ease the workload for a new developer taking over your map, and it can be used in utilities that do automatic documentation of your solutions. |
Maximum Input Parameters |
Describes what the maximum number of input parameters for this functoid is. |
Minimum Input Parameters |
Describes what the minimum number of input parameters for this functoid is. |
Script |
If the functoid is a Scripting functoid, which is explained later, you can click in this property and then click the ellipsis that appears to configure and edit the script the Scripting functoid should run when called. |
Table Looping Grid |
If the functoid is a Table Looping functoid, which is explained later, you can click this property and then the ellipsis that appears to configure the table looping grid. |
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
Name |
Description |
Lowercase |
This functoid takes in one parameter and returns the same string in lowercase. |
Size |
Returns an integer that equals the length of the input string. If the input string is null, a value of 0 is returned. |
String Concatenate |
This functoid takes in at least 1 string and a maximum of 100 strings. The strings are concatenated in the order they have been added as input to the functoid. The output is the concatenated string. Note this functoid cannot concatenate values in a reoccurring element in the source. You need a cumulative functoid for this, which is explained later. |
String Extract |
This functoid takes in three parameters and returns a substring of the first input. The second input determines the start position of the substring to be extracted and the third parameter determines the end position. Note that although the C# String.Substring method is actually used by the functoid, it wants the end position of the string to extract and not the length of the substring to extract. Also, contrary to the C# string methods, these parameters are 1 based and not 0 based, meaning that the first character of the input is a position 1. |
String Find |
This functoid takes in two parameters and returns the first found instance of the second parameter inside the first parameter. If the first parameter is BizTalk and the second parameter is Talk, the functoid returns the value 4. Note that this is also 1 based and not 0 based as is normally the case in C#. |
String Left |
This functoid takes in two parameters. The first is a string, and the second must be an int. The functoid returns the number of characters specified in the second parameter from the left of the string. If the second parameter is greater than the length of the string, the input string is returned. |
String Left Trim |
This functoid takes in a string and trims it from the left, effectively removing all characters from the beginning of the string until it reaches a nonwhitespace character. The characters that are defined as whitespace are the ones defined in C# as whitespace. These include spaces, carriage returns, line feeds, and others. Given null as input, the functoid returns the empty string. |
String Right |
This functoid does the same as the String Left functoid, only from the right rather than the left. |
String Right Trim |
This functoid takes in a string and trims it from the right. The functionality is the same as the String Trim Left functoid, only from the right rather than the left. |
Uppercase |
This functoid takes in one parameter and returns the same string in uppercase. |
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
Name |
Description |
Absolute Value |
This functoid takes in one value and it returns the absolute value of the value. For a positive number, the absolute value is the same number. For a negative number, the absolute value is the number multiplied by–1. |
Addition |
This functoid takes in a minimum of 2 parameters and a maximum of 100 parameters. It sums the parameters and returns the result. |
Division |
This functoid takes in two parameters and returns the first parameter divided by the second parameter. If either parameter is not a number or if the second parameter is 0, the empty string is returned. |
Integer |
This functoid takes in one parameter and returns the integer part of the value, effectively removing the decimal point and all decimals. This differs from the Round functoid in that it will never round up (only down). |
Maximum Value |
This functoid takes in a minimum of 2 parameters and a maximum of 100 parameters. It returns the largest number found among the parameters. |
Minimum Value |
This functoid takes in a minimum of 2 parameters and a maximum of 100 parameters. It returns the smallest number found among the parameters. |
Modulo |
This functoid takes in two parameters. It returns the remainder from performing a division of the first parameter by the second parameter. |
Multiplication |
This functoid takes in a minimum of 2 parameters and a maximum of 100 parameters. It multiplies all the parameters and returns the result. |
Round |
This functoid takes one required parameter and one optional parameter. The first parameter is the value to round, and the second is the number of decimals to which the first parameter should be rounded off. If the second parameter is not present, the first parameter is rounded off to a whole number. Standard rounding rules apply. |
Square Root |
This functoid takes in one parameter and returns the square root of it. |
Subtraction |
This functoid takes in a minimum of 2 parameters and a maximum of 100 parameters. It subtracts all parameters that are not the first parameter from the first parameter and returns the result. |
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
Name |
Description |
Equal |
This functoid takes in two parameters and returns true if the parameters are equal to each other. If they are not equal, a value of false is returned. |
Greater Than |
This functoid takes in two parameters. It returns true if the first parameter is greater than the second parameter. Otherwise, it returns false. |
Greater Than or Equal To |
This functoid takes in two parameters. It returns true if the first parameter is greater than or equal to the second parameter. Otherwise, it returns false. |
IsNil |
This functoid takes in one parameter, which must be a node in the source schema and cannot be another functoid. The functoid returns true if the node in the source schema is set to nil, like this: <myElement xsi:nil="true"/ > |
Less Than |
This functoid takes in two parameters. It returns true if the first parameter is less than the second parameter. Otherwise, it returns false. |
Less Than or Equal To |
This functoid takes in two parameters. It returns true if the first parameter is less than or equal to the second parameter. Otherwise, it returns false. |
Logical AND |
This functoid takes in a minimum of 2 parameters and a maximum of 100 parameters. It returns the logical AND of all the inputs, meaning that if just one of the inputs is false, a value of false is returned. Otherwise, a value of true is returned. |
Logical Date |
This functoid takes in one parameter and returns a Boolean value depending on whether the input could be parsed as a .NET DateTime. |
Logical Existence |
This functoid takes in one parameter. If the parameter is another functoid, the input must be a Boolean, because the Logical Existence functoid doesn't do any conversion of the input into Boolean. The functoid just passes the value it receives on. If the input is a node in the source schema, however, the functoid returns true if the node is present in the source schema and false otherwise. |
Logical NOT |
This functoid takes in a Boolean value and returns the negation of it, meaning true becomes false and vice versa. |
Logical Numeric |
This functoid takes in one parameter and returns a Boolean value depending on whether the input could be parsed as a .NET double. |
Logical OR |
This functoid takes in a minimum of 2 parameters and a maximum of 100 parameters. It returns the logical OR of all the inputs, meaning that if just one of the inputs is true, a value of true is returned. Otherwise, a value of false is returned. |
Logical String |
This functoid takes in one parameter and returns true if the parameter is neither null nor the empty string. Otherwise, it returns false. |
Not Equal |
This functoid takes in two parameters and returns true if the parameters are not equal to each other. If the two values are equal, a value of false is returned. |
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:
- 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.
- 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.
- The string is trimmed to remove leading and trailing whitespace.
- 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.
- 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.
- The input is converted into a number. If this fails, a value of false is returned.
- 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
Name |
Description |
Add Days |
This functoid takes two parameters and returns a new date as a result of adding the number of days specified in the second parameter to the date specified in the first parameter. |
Date |
This functoid takes no parameters and returns the current date. |
Date and Time |
This functoid takes no parameters and returns the current date and time. |
Time |
This functoid takes no parameters and returns the current time. |
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
Name |
Description |
ASCII to Character |
This functoid takes in one parameter. If the parameter is a number less than 0 or greater than 127, an empty string is returned. Otherwise, the number is converted into the character that has this number in the ASCII table. 65 becomes A, for instance. |
Character to ASCII |
This functoid takes in one parameter. If the parameter is null or the empty string, an empty string is returned. If not, the first character of the string is converted into the ASCII representation. A becomes 65, for instance. |
Hexadecimal |
This functoid takes in one parameter. If the parameter is not a number, the empty string is returned. If the parameter is a number, the integer part of the number is converted to a hexadecimal value. The input is assumed to be a decimal value. |
Octal |
This functoid takes in one parameter. If the parameter is not a number, the empty string is returned. If the parameter is a number, the integer part of the number is converted to an octal value. The input is assumed to be a decimal value. |
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
Name |
Description |
10^n |
This functoid takes in one parameter. The functoid returns 10 lifted to the power of the parameter. For instance, a value of 2 results in 100, and a value of 5 results in 100000. |
Arc Tangent |
This functoid takes in one parameter. The functoid returns the result of performing the arc tangent function on the parameter. |
Base-Specified Logarithm |
This functoid takes in two parameters. If either parameters is less than or equal to 0, an empty string is returned. Also, if the second parameter is 1, an empty string is returned. The functoid returns the base-specified logarithm function using the second parameter as base and performing the function on the first parameter. For instance, parameters 100 and 10 result in the value 2, and parameters 64 and 2 result in the value 6. |
Common Logarithm |
This functoid takes in one parameter. If the parameter is less than or equal to 0, an empty string is returned. Otherwise, the functoid returns the 10-based logarithm of the parameter. For instance, a value of 100 results in 2, and a value of 10000 results in 4. |
Cosine |
This functoid takes in one parameter. If the parameter is a number, the cosine function is called with the parameter as input, and the result of that is returned. |
Natural Exponential Function |
This functoid takes in one parameter. The functoid returns ℮ (The base for the natural logarithm) lifted to the power of the parameter. For instance, a value of 2 results in 7.389..., and a value of 3 results in 20.085.... |
Natural Logarithm |
This functoid takes in one parameter. The functoid returns the natural logarithm of the parameter. The natural logarithm is the logarithm that is based on ℮. |
Sine |
This functoid takes in one parameter. If the parameter is a number, the sine function is called with the parameter as input, and the result of that is returned. |
Tangent |
This functoid takes in one parameter. The functoid returns the result of performing the tangens function on the input. |
X^Y |
This functoid takes in two parameters. The functoid returns the first parameter raised to the power of the second parameter. |
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.8 lists the cumulative functoids, their usage, and parameters.
Table 3.11. The Cumulative Functoids
Name |
Description |
Cumulative Average |
This functoid takes in all the occurrences of the input and outputs the average of the input values. |
Cumulative Concatenate |
This functoid concatenates the occurrences of the input into one string, which is then output. |
Cumulative Maximum |
This functoid takes in all the occurrences of the input and outputs the largest number found among the input values. |
Cumulative Minimum |
This functoid takes in all the occurrences of the input and outputs the smallest number found among the input values. |
Cumulative Sum |
This functoid takes in all the occurrences of the input and outputs the sum of the input values. |
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
Name |
Description |
Database Lookup |
This functoid takes in four parameters, which are all required. The first parameter (p1) is a lookup value, which could be some ID from the source message. The second parameter is a connection string that instructs the runtime where to do the lookup. The third parameter (p3) is the name of the table to do the lookup. The fourth parameter (p4) is the name of the column that is used to find the lookup value. BizTalk creates a query like this: SELECT * FROM p3 WHERE p4 = p1; and connects to the database, and thus selects all values from the row in the table specified that has the right lookup value in the column specified in the fourth parameter. This requires the column in the fourth parameter to be a unique key in the table. If it is not a key, the first row is returned. This functoid cannot be connected to an output node, because it outputs an entire row. Use the Value Extractor functoid, which is explained later, to extract a column value from this row. |
Error Return |
This functoid takes in one parameter, which is a Database Lookup functoid. The functoid outputs any error message that has arrived from performing the query against the database. If no errors occur, the functoid has an empty string as output. |
Value Extractor |
This functoid takes two parameters, which are both required. The first is a Database Lookup functoid. The second is the name of the column from the output row from the Database Lookup to extract. This effectively pulls out one specific value from a named column in the result set of the database query, and this value can then be output to the destination schema. |
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
Name |
Description |
Format Message |
Returns a formatted and localized string using argument substitution and, potentially, ID and value cross referencing |
Get Application ID |
Retrieves an identifier for an application object |
Get Application Value |
Retrieves an application value |
Get Common ID |
Retrieves an identifier for a common object |
Get Common Value |
Retrieves an identifier for a common object |
Remove Application ID |
Removes the identifier for an application object |
Set Common ID |
Sets and returns an identifier for a common object |
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
Name |
Description |
Assert |
This functoid takes in three parameters. The first must be a Boolean value. If the map is compiled in Debug mode, an exception is thrown with the text from the second parameter if the first parameter is false. The third parameter is used as output. If the map is compiled in Release mode, the third parameter is always returned. This is useful for debugging your map, and just as with assertions in normal C# code, it allows you to make sure some conditions are always true. |
Index |
This functoid takes in a minimum of 1 parameter and a maximum of 100 parameters. The first parameter must be a node from the source schema. and the rest represent indexes in each level from the node that is the first parameter and back to the root node. The functoid returns the value in the node given by the first parameter and indexed by the values from the rest of the parameters. An example is provided in the "Advanced Maps" section. |
Iteration |
This functoid takes in one parameter, which must be a node in the source schema. The functoid returns the iteration of the node, meaning that it returns 1 for the first occurrence of the input node, 2 for the second occurrence, and so on. |
Looping |
This functoid takes in a minimum of 2 parameters and a maximum of 100 parameters. The input parameters must be nodes in the source schema and cannot be other functoids. The functoid has no functional purpose and therefore no output as such. You must connect the looping functoid to a record in the destination schema, and the map then generates one output record for each of the input records that correspond to the input parameters. An example of the Looping functoid is provided in the section "Advanced Maps" section. |
Mass Copy |
This functoid takes in one parameter, which must be a node from the source schema. The functoid must be connected to a node in the destination schema, and it copies recursively all the nodes below the source node to the destination node. |
Nil Value |
This functoid takes in one optional parameter. If specified, the parameter must be a Boolean. If not specified, a value of true is assumed. The functoid is connected to a node in the destination structure, and if a value of true is specified in the first parameter, the output node is created with a value of nil. |
Record Count |
This functoid takes in one parameter, which is a node from the source schema. The functoid returns the number of times the node appears in the input regardless of scope. |
Scripting |
This functoid is used to execute some script. The functoid is configurable to either call a specific method in a .NET class in an assembly or to configure a script that is either Inline C#, Inline JScript .NET, Inline Visual Basic .NET, Inline XSLT, or Inline XSLT Call Template. The XSLT scripting options can be used to control creation of destination structure, because the XSLT has access to the entire source structure and the XSLT is inserted into the generated XSLT. The other script types can be used to perform operations on input values and they must output one value. The Scripting functoid is discussed in more detail in the "Advanced Maps" section. If you use a .NET language in your inline script, you have access to the .NET namespaces found at http://msdn.microsoft.com/enus/library/aa561456(BTS.70).aspx. |
Table Extractor |
This functoid takes in two parameters. The first must be a Table Looping functoid, and the second is a number that indicates the column from the table to get the value from. The output from this functoid can then be sent to another functoid as input or directly to the destination schema. An example of the Table Extractor functoid is provided in the "Advanced Maps" section. |
Table Looping |
This functoid takes in a minimum of 3 parameters and a maximum of 100 parameters. The functoid builds a table in memory useful for creating records in the output that have some structure that is not present in the input. The first parameter is a scoping link from a node in the source schema. The second parameter is the number of columns that should be in the table, which corresponds to the number of fields to create in the output. The third parameter and all following parameters are values that can be used to build the table. An example of the Table Looping functoid is provided in the "Advanced Maps" section. |
Value Mapping |
This functoid takes in two parameters. The first must be a Boolean value, and the second parameter can be any value. The functoid outputs the second parameter if the first parameter was true. This functoid differs from the Value Mapping (Flattening) functoid in that this functoid does not attempt to flatten the input into the output. |
Value Mapping (Flattening) |
This functoid takes in two parameters. The first must be a Boolean value, and the second parameter can be any value. The functoid outputs the second parameter if the first parameter was true. This functoid differs from the Value Mapping functoid in that this functoid attempts to flatten the input into the output. This is useful when you have multiple Value Mapping functoids with outputs going to the same record, because otherwise two instances of the destination record will be created. |
Third-Party Functoids
You can download several third-party functoids and use them in your solutions. Use your favorite search engine to locate them.