Mapping in BIZTALK
Introduction
There have been many articles in the internet that describes or outline about mapping features in BizTalk. But today in this article we are diving further to know more features that make our document mapping possible to our need.
BizTalk as a windows server product integrates the heterogeneous system in a particular System architecture. Main important feature of this server product is supported by XSLT extensively. BizTalk Mapper is a graphical tool which assists in transforming data format between any number of schemas of disparate systems (or) entities. Maps also contain the business logic to support our transformation of data required by the target system.
Transformation can be achieved by writing a Custom .NET components, using the external style sheet to perform our work, code driven solution with C# inline code, performing message assignment in the orchestration and driving it to the map.
More preciously we can use the Rule engine to establish the common business logic transformation. Rather than encoding these rules in each end system rule should be deployed in the integration hub. Doing this way simplifies our update process.There is no need for us to customize the system to suit the other system required format. Integration layer will take care all the complex mapping process.
This article is intended to focus on main and advanced concepts of Map. Beginners have to read the respective beginning articles to familiar themselves with mapping process. Mapping tool is supplied with BizTalk server product and documentation of BizTalk is a good start.
Functoids
String Extracting Functoids:
These are the functoids that is used to extract certain number of constant strings from the Input document schema and map it to destination schema. For example if we have to extract first five letters of string then we can use the string left functoid and specify the source by simply dragging to the functoid left input and specify the number of strings to be extracted. Counting of the string value starts from 0. For eg to extract 2 letters specify 0 -1.
This functoid can be used in conjection with string concatenation functoid. Any change in the number of string retrievals have bottle neck. Maps has to be recompiled.
Mass Copy functoid
There are many situations where the fields that might appear in the source document and their mapping with the destination document is dynamic. What should be done in order to create or add the field in schema dynamically? Use the Keyword <ANY> in the schema to achieve this. It is easier said than done. Schema containing the <ANY> element is not validated 100 percent. Validation of schema occurs by combination of namespace and root node and with <ANY> element defined it might be difficult to know the order of field occurrences in advance. In order to obtain the fine validation use validation in pipelines.
From the advanced Tab drag the Mass-copy functoid and place it in the Map. After defining the order of known field create the field with the tag <ANY>.when the schema with the <ANY> element is validated they are considered success. If this schema is mapped to the other schema containing the <ANY> element then the Mass-Copy functoid should be used. Mass – copy functoid can be performed only with the node level not with the fields level. So the node containing the <ANY> field has to be mapped.
Database Lookup functoid
Use this functoid to retrieve the information from the database. First matched result row is obtained . In order to obtain all the rows that matches our criteria use the looping functoid. Database functoid uses the four parameters.
Parameter 1: Identify the field that will be used in the search field. This is the string that would appear in the SQL WHERE clause. Connect this is to the left side of the DATABASE look up functoid.
Parameter 2: Give the values for the connection strings like server name, database name, security. Remember if your SQL server is configured for trusted connection then your BizTalk host to be one of the member of this trusted connection else the connection would be refused.
Parameter 3: Specify the table from which the data should be obtained after the search
Parameter 4: Specify the column of the search. If the column you are specifying end up with more than one result set them using the combination key is advisable. Both the key values should be concatenated before being used as a query search criteria.
Query that we specify in Db look up functoid will be converted as a dynamic SQL. It is more important to use ERROR RETURN Functoid to display in case if there is any connection issue.
Value Extractor functoid should be used to concatenate the values obtained by the query to the destination schema. It is advisable to have the value extractor function name same as that of the search field to facilitate our work.
Looping functoid
This functiod is used when there is repeating data structure found in the source side of the mapping. These repeating structures are consolidated and mapped to the single destination structure. Connect the repeating structure to the left of the functoid and right to the destination node.This functoid functions like the For ... Each statement of our programming languages. For eg a person might order product through the company website and also through the vendor's website. To iterate through the sales we can use this functoid to consolidate the sales and map to our total sales in our destination schema. You can perform the customized consolidation using the Logical functoid.
Logical functoid accepts two parameters of which one of the parameter should be true and other is one which we need to evaluate. For example we can use this functoid to find the Maximum sales by embedding the Logic Sales > 20000.
Iteration functoid
If we want to index through the repeating structure or perform some Business Logic function that is based on no of occurrences of particular field or value we can use iteration functoid.
For example if we want to find the record count of repeating source record connect the repeating record to the left of record count functoid . result will be count of repeating source record. You can combine this with the decision logic functoid to do further filtration.
Custom functoid
You can create your own functoid instead of pasting inline code in each of the shapes.Create C# New library project. You have to reference Microsoft. BizTalk.BaseFunctoids.dll to write the new functoid on our own. We have to use Resource file (resX) to store the functoid configuration parameter. Code the functionality that should be exhibited by the functoid. You have to use the third party tool to attach the image.
Four main properties that you need to describe and mention in your custom code logic is
1.SetName
2.SetDescription
3.SetToolTip
4.SetBitmap
These 4 parameters are mandatory settings. If you are referencing the assembly externally then you have to set the SetExternalFunction attribute.
Only with this setting your BizTalk can know where to find the definition for implementing the mapping process.Your implementation is identified with the help of the assembly.Class.Function name.Your Custom functoid has to be copied to the GAC .You can also set the minimum Input required by the functoid and maximum parameter required.
Date & Time functoid
Most critical business function that depends on time need to have field that describes the time of action performed. For example every single transaction in Banking application whether it succeeds or fails need to keep track of time of action. Date function is used in conjunction and mapped to the destination field.This functoid is very useful in Batch processings. We can also find the number of days past the action happened.You can use the Add Days to produce only day values with out time.
Implementing If-Then-Else function
To implement the If-Then-Else function of programming language use any of the desired logical function from the group and used it with the Value extractor functoid. Establish the connection with the value extractor functoid and Logical functoid. Field that need s to be checked for the condition is linked with the value extractor functoid.Value Extractor functoid defines the action that needs to happen when the logical condition evaluates to true. For eg if we want to map to different destination nodes based on the logical condition evaluation this functoid combination can be used.
Link to the logical condition defines the information on which map will work on. Order of the Value Mapping functoid play a crucial role in determining the outcome. Sometimes order may mix up. One has to visit the configure Functoid input window to check the order of evaluation. Any changes in order should be corrected here.
Value Mapping Functiod.
Value Mapping functoid( Flattening) , Value Mapping functoid are the two forms available.These two fucntoid causes new record to be created in destination for each record in the source based on the logical condition evaluation to true or false. New record will be created for true evaluation, no record will be created false evaluation.
Difference between these two functoid how they are mapped to destination. If value of the incoming field cannot be mapped then value mapping functoid creates empty destination node will be created where as Value Mapping functoid ( flattening) will not created a empty node. This default behaviour of Value mapping functoid can be changed with the help of other functoid and scripting.
Scripting Functoids
External assembly
You can use scripting functoid to do number of functions. It can call the external assembly, it can map to external XSLT file,It can allow you to write c# inline code etc. To link the external assembly go to it property window select script type as External assembly from Drop down.Link to the assembly,class,function of our customized implementation. Be sure that external assembly need to be present in the GAC before compiling and using the Map else error will be thrown.
Inline C# code
You can use the inline script buffer to specify the inline code. Note that this embedding feature creates a maintenance bottle neck.Each method variable mentioned should be unqiue as there are mapped in CDATA tag of map.You cannot debug the code that is inlined. So before embedding them test them in the Visual studio and import it to the inline script buffer. This solves lot of confusion.
Passing Orchestration variable in to MAP
Create the Message schema that contains the fields to capture the information from orchestration.These fields need to be promoted or distinguished field so that it can be made available to context message Only message with the context message can be mapped.
Create and Link the orchestration message to this schema
Define the orchestration variable that instantiates context message in the orchestration. This variable should be of System.Xml.XmlDocument type
Drag a message assignment shape in the orchestration designer and in the construct message specify MapContextMsg as the only message constructed.
Open the Expression editor and load the XML string confirming ContextMessage in to the XmlDocMsgBuilder variable. Then assign this Xml variable to MapContextMsg.
Once instantiated they can be used any where in orchestration.
Once the context message is available mapping need to be performed to map source or destination.
Now drag Transform shape and open the dialog box by double clicking it.Specify the source message to be MapContextMsg and include any other is available. Specify destination message.
This steps are used becoz Mapper cannot directly access the business logic variables from orchestration directly. It can use functoids to invoke other things. However the destination message should not be added as input message for schema
XSLT Scripting
You can used XSLT scripting but it can be used for smaller transformation. Coding will be huge for larger tranforamtion. Instead map all the transformation in a file and import the file to the Mapper by write clicking it on the Mapping page.In contrast to it you can use XSLT Template.
Main difference between scripting and Template is how sources document are passed and accessed. Inline uses XSL methods where as in templates they are passed as parameters.
Templates are used where you need same logic to do the mapping transformation.
Notes:
Few notes about Best practice.
Organising the map can be done using the Grids, Links.
Links that form a particular group can be grouped together in Grid page and there can be as many grid pages depending on your requirement.
Keep the map simple.
Minimize the use of Business rules.
Use labels where ever required.
Summary
In this article, I have tried to cover most important things that can be performed and used in Mapping. Mapping plays an important role for many integration to exchange the data. There are quiet few lefts will update that with Part - II
