BizTalk Server: Basics principles of Maps – Basic maps functionalities (Document mapping) (Part 4)

Posted: April 2, 2012  |  Categories: BizTalk Maps

When we perform a transformation in the message there are 5 basic functionalities that typically arise:

  • A simple mapping of a given value (direct copy)
  • Concatenation of values
  • Conditional selection
  • Custom scripts
  • Add new values (data)

A simple mapping of a given value (direct copy)

This is the most basic operation of all, where we intend to move a value from the source to the destination schema, without performing any kind of operation on the values (direct copy or simple drag-and-drop).

For this, we need only to drag-and-drop the element in the source schema to the element in the destination schema. This operation is exemplified in the next image with the mapping of the element “Address”

BizTalk Mapper Design direct copy

Concatenation of values

Concatenate two or more values from the source to a particular element in the destination schema, is another of the daily operations in mapping, for this we need to:

  • Open the Toolbox window and drag the String Concatenate functoid onto the grid;
  • Drag-and-drop a link of the desired elements from the source to the String Concatenate functoid, for example, the elements: “FirstName” and “LastName”;
  • Drag-and-drop a link from the String Concatenate functoid to the element “FullName” in the destination schema;
BizTalk Mapper Design Concatenation values

Note: the order of the input to the functoid is very important since the concatenation is carried out by the order in which the elements were associated to the functoid (we will explore this topic further on).

Conditional selection

Often we don’t want to simply move values from source to destination schema and sometimes we need to generate data output according to certain conditions. We can make these conditions in many different ways using functoids or through custom scripts, here’s an example: test whether the value in the source is a valid string, if so map it to the destination schema, for this we need to:

  • Open the Toolbox window and drag the Logical String functoid onto the grid, this functoid validates whether the input parameter is a valid string, similar to the C# function String.IsNullOrEmpty.
    • Returns “False” if the string is empty or null;
    • Returns “True” if the value specified by the input parameter is a valid string;
  • Drag-and-drop a link of the desired element from the source to the Logical String functoid, in this case, the element “ZipCode”
  • Drag the Value Mapping functoid from the Toolbox window onto the grid. This functoid returns the value of its second parameter if its first parameter is true, i.e., enables you, based on a Boolean value, to control whether an entire structure or another single value in an input instance message gets copied to an output instance message. The functoid receives two parameters:
    • The first will be a Boolean (True/False);
    • The second is the value to be mapped;
    • If the value of the first parameter is true, then the value of the second parameter is mapped to the destination schema; otherwise, it will not be mapped.
  • Drag a link from the Logical String functoid to the Value Mapping functoid;
  • Drag a link from the element “ZipCode” from the source schema to the Value Mapping functoid;
  • Drag a link from the Value Mapping functoid to the element “ZipCode” in the destination schema;
BizTalk Mapper Design Conditional selection

Custom scripts

Custom scripts are commonly used in more complex transformations or to facilitate some mapping conditions. Basically, there are two main scenarios where we can or should use this functoid:

  • When none of the existing functoids allows doing what we want, the example that we will see is converting a date of birth in age.
  • Or when the use of existing functoids becomes extremely complex to solve a problem of mapping.

There is a “rule” that we normally use to determine whether we should use functoids or custom scripts which tell us: “If you need more than 6 functoids to solve a problem of mapping, you should consider using a script. If you need six or fewer functoids, you should not use a script”.

I like to use this rule in a thoughtful way and not to the letter, i.e., if the existing functoids help me to easily solve the problem, I use the existing functoids. If it becomes extremely complex, then I choose to use custom scripts.

The Scripting functoid enables you to use custom script or code at run time to perform functions otherwise not available. For example, you can call a .NET assembly at run time by using the Scripting functoid and writing your own custom functions. BizTalk Server 2010 supports the following languages for the Scripting functoid:

  • C# .NET
  • JScript .NET
  • Visual Basic .NET
  • Extensible Stylesheet Language Transformations (XSLT)
  • XSLT Call Templates

There are available to the developer six types of scripts:

  • External Assembly: It allows us to associate this functoid with an existing function in assembly published on Global Assembly Cache (GAC).
  • Inline C#: This option allows us to associate and invoke C# code directly into the functoid.
  • Inline JScript .NET: Same as above but using code JScript .NET
  • Inline Visual Basic .NET: Same as above but using code Visual Basic .NET
  • Inline XSLT: This option allows us to associate the Scripting functoid with XSLT.
  • Inline XSLT Call Template: identical to the above, however, it allows us to associate and call XSLT templates directly into the functoid.

In this example, we want to convert a date of birth in age, for this we need to:

  • Open the Toolbox window and drag the Scripting functoid onto the grid,
  • Drag a link from the element “DateOfBirth” from the source schema to the Scripting functoid;
  • Drag a link from the Scripting functoid to the element “Age” in the destination schema;

The result should look like:

BizTalk Mapper Design Custom scripts

For the mapping problem to be completed, we only need to configure the custom script. For this sample we will use “Inline C #” script type, for this, we need to:

  • Make double-click on the Scripting functoid and select the “Script Functoid Configuration” tab;
  • Go to the “Select script type” drop-down box, and select “Inline C#” option. The “inline script” box will display a sample script;
  • Inside “Inline script” property box place the following script:
BizTalk Mapper Design Configure Scripting Functoid

Add new values (data)

In many scenarios, we need to add new data to the final message that do not exist in the source message. It is normal to find situations where, based on existing data in the source message, we will need to consult an external system, e.g. database, in order to acquire more information to complete the required data in the final message.

An example, more basic and simple, is to add a stamped date in the final message, describing the date and time it was processed. For this we need to:

  • Open the Toolbox window and drag the Date and Time functoid onto the grid;
  • Drag a link from the Date and Time functoid to the element “ProcessingDatetime” in the destination schema;
BizTalk Mapper Design Add new values

Note: As you can see, this functoid doesn’t require any input data, returning the current date and time of the system.

Related links

Author: Sandro Pereira

Sandro Pereira lives in Portugal and works as a consultant at DevScope. In the past years, he has been working on implementing Integration scenarios both on-premises and cloud for various clients, each with different scenarios from a technical point of view, size, and criticality, using Microsoft Azure, Microsoft BizTalk Server and different technologies like AS2, EDI, RosettaNet, SAP, TIBCO etc. He is a regular blogger, international speaker, and technical reviewer of several BizTalk books all focused on Integration. He is also the author of the book “BizTalk Mapping Patterns & Best Practices”. He has been awarded MVP since 2011 for his contributions to the integration community.

3 thoughts on “BizTalk Server: Basics principles of Maps – Basic maps functionalities (Document mapping) (Part 4)”

  1. Hello,
    For starters, thank you for your blog, it’s very interested.
    Sorry for the language, I’m French
    I have a question for a mapping with two input messages.
    I will wish to combine data from both messages into one.
    example:
    -Input message 1:
    User
    UserID
    LastName
    FirstName
    -Input message 2:
    Address
    UserID
    AdressLine
    PostCode
    Town
    -Output message :
    User
    UserID
    LastName
    FirstName
    Address
    UserID
    AdressLine
    PostCode
    Town
    In my example, I want to regroup each user together with its address. But I don’t know how.
    Can you help me? Have you an exemple?
    Tank you for your help.
    Nicolas

Leave a Reply

Your email address will not be published. Required fields are marked *

turbo360

Back to Top