- Mapping

BizTalk: Tips: cumulative map and schema testing

Leonid Ganeline — Wed, 15 Aug 2007 20:58:50 GMT

This is a small tidbit for routine work. It don't take much time but help to work with schemas and maps systematically.

First time:

1). For each map I create the <test-map> folder as:

TestCases\

Maps\

A12_311_to_Canonical\

A12_915_to_Canonical\

2). Get the first test source message and place it in the <test-map> folder. Create a copy of this message and name it "Current".

3). Change the "TestMap Input Instance" property of the map to this name (for example as "<test-map>\Current.xml")

For testing:

1) Copy the test source message to the "test-map" folder with meaningful name (for example as "TwoR4.MustGiveError")

2) Copy the whole text from this file to the Current file. Save Current. (I constantly keep open the Current file in the text editor.)

3). Test the map.

repeat 1-3.

As result I have the full test set for my maps. I've never lost the test message.

I always know where are my test messages and the name of the current test message, it is always the Current :) .

This is a test driven approach. The test data are accumulated and never lost.

The same technique I use for test schemas (using theValidate Instance command). As a result I create such folder structure:

TestCases\

Maps\

A12_311_to_Canonical\

A12_915_to_Canonical\

...

Schemas\

A12_311\

A12_915\

Canonical\

...

Let me know what you think about this.

BizTalk: Mapping: Script functoid: Type of the Input and output parameters

Leonid Ganeline — Mon, 08 Jan 2007 20:26:00 GMT

Rule of thumb:

In the "Script Functoids - Inline C#" use only string types as the input and output parameters.

How it works:
If the C# method in the Script Functoids - Inline C# has non-string parameter, it will be converted to the string on the "border" of this functoid!
Take in mind that the "real" type for Xml elements is "string", no matter how it was defined in the Schema. Xml only mimics the other types.

The Xml holds the values serialized to string and vice versa.

In our case the string "1" is desiarilazed to int 1.

Example:

Script Functoids - Inline C#: string MyMethod (int param1) { ... }

Xml element: <Element1>55</Element1> ==>

The result will be like this: int param1 = (int)"1"; MyMethod(param1);

In this place can be problems!

If we had <Element1>55</Element1>, we have no problems.
But we can have also:

<Element1>ABC</Element1>
or <Element1></Element1>
or <Element1/>
or node = null (that means there is not this node in the Xml document instance at all.

Those cases give us an exception:

"Exception: Error encountered while executing the transform MyProject.MyMap.
Error:Transformation failed..: System.Xml.Xsl.XsltException: Function
'ScriptNS0:MyMethod()' has failed. ---> System.ArgumentException : Cannot
widen from target type to primitive type."

We don't need this result. The exceptions in the map are unwelcome!

Rule of thumb:

Use ONLY string types for input parameters in the "Script Functoids - Inline C#".

If we HAVE TO work with non-string types, move the type-conversion INSIDE the method. It prevents these exceptions. We could handle the type errors.

string MyMethod (string param1)
{

string returnValue = "0";
if (param1 == null || param1 == "") return returnValue;
try
{ // if we need to work with param1 as int!

int param1_int;
param1_int = Convert.ToInt32(param1);

}
catch(InvalidCastException ex) // to process the cases with "nonInt" param1:
{...}
...

BizTalk: Mapper: Script functoids: Enhancement of the UI

Leonid Ganeline — Sun, 29 Jan 2006 06:53:00 GMT

BizTalk: Mapper: Script functoids: Enhancement of the UI

Working with maps into the BizTalk Mapper more then a year, I've got some ideas how the Mapper can be improved.

Look at the Script functoid. Usually I have a lot of them because only very simple logic I can implement with combination of other functoids. If I have more then one "If" then I use a Script functoid (SF).

What I can see when I look at the map and try to understand logic of the SF? Nothing but only that "I have some logic inside". It is quite useless.

Want to know more? Click on the SF. Nothing changed. I have not get any information in the Property windows.

Trying to get information about SF I have to open windows under "Script" parameter to understand if this SF is Inline, External, XSLT template, or Inline XSLT.

Why I want to know this? I've got a project with maps. The first thing I'm going to discover is the inner logic of the map. I try to find out all links with other assemblies, for this I try to found out all Script functoids with "External scripts". And now I have to make a lot of monkey work: click on the SF, click on the "Script" field in the Parameters window, click "a secret" button in this field. All these clicks for EACH SF!

Lets imagine that I would have four sorts of scripts functoids, not only "Script functoid" but "Script Inline", "Script External", "XSLT Template", and "XSLT Inline."

Lets imagine that when I click on the SF I've got the real parameters of this SF:

For the Script External functoid: Assembly, Class, Method, Input and Output parameters.

For the Script Inline functoid: a Signature of this script, Input and Output parameters, Language (C#, VB, JScript).

Not sure about last two. I didn't work with them at all.

And of course, these SFs should get different icons :)

Does somebody have any comments? It would be realy appreciated...

BizTalk: Mapping, Logical functoids, and Boolean values

Leonid Ganeline — Sat, 14 Jan 2006 01:45:00 GMT

BizTalk: Mapping, Logical functoids, and Boolean values

Several times I've got "non intuitive" result by using boolean values in maps.

For example, I've tried to get values "true/false" or something else from the logical functoids for filling up the node in a Destination schema, but didn't get anything.

Here is my discovering using boolean value in the maps.

There are different flavors this problem:

· Where we can use boolean values?

· Where we can get boolean values?

· How we can fill in the nodes with boolean type?

· How we can transform boolean values?

Let’s start.

Script functoid

In the xml document all values are the strings.

It should be (and it is!) non intuitive to transform them to/from the .NET bool values. It can be transformed by using Script functoids. (Pict.1)

I've tested two variants of "inline C#" scripts:

I used the negation operator (“!”) to be sure I’m having a real transformation.

string BoolToString (bool paramBool )

{

return (!paramBool).ToString() ;

}

And

bool BoolToBool (bool paramBool )

{

return (!paramBool);

}

Results:

1. When I changed the link from FieldBoolean node to Functoid to the link from FieldString to Functoid the results were the same.

2. When I changed the input value as “True” / ”true” / “TRUE” / “tRuE” the results were the same.

3. First script returned values “False” / “True” when I passed into it “true” / “false”.
Second script returned values “false” / “true” when I passed into it “true” / “false”.

4. When the input value were “1” / “0” I’ve got the errors.

Conclusion:

1. Script functoid ignores the types of nodes. It always inputs/outputs the string values. Before/after passing them to/from the script it transforms them to the .NET type.

2. Script functoid ignores the cases of the input values when transform them on the boundary of the script to the bool type.

3. Script returns the bool values (transformed on the boundary of the script to the string type) as defined for Microsoft .NET Framework Class Library (see the References below). That’s mean bool values are “true and “false”, bool values transformed inside script to the string values are “True” and “False”.

4. Script functoid implement only “Canonical representation” of the “boolean” type of XML schema not a “Lexical representation” (see the References below). That’s mean the values “1” and “0” should not be used as boolean values in the Script functoid input.

Logical functoids

It’s confusing from the start.

When you see to the Help property of a Logical functoid you can see: “Returns TRUE if the first parameter is equal to the second parameter.”

But into the Configure Functoid Inputs window

“Functoid description:

Use the Equal functoid to return the value “true” if the first input parameter is equal to the second input parameter. This functoid requires two input parameters.”

We can see the different cases in the values.

Is that something mean for us?

I use several maps for testing the logical functoids. (If the Equal functoid is picted with one input link the second input parameter is usualy “true”.) :

(Pict.2)

Here I tried to get the output value from the logical functoid to the destination node.

(Pict.3)

Here is the standard method of using the logical functoid.

(Pict.4)

Here I tried to understand which values return the logical functoid.

Let’s start testing.

Results:

1. In first case the Logical functoid output didn’t create the destination values.

2. When I’ve tried to use “True” or “TRUE” or something else as an argument in place of the logical argument (for example, as a first argument of Value mapping functoid) it didn’t match. Only “true” is working fine.

3. In the third test the second logical functoid matched only values “true”/”false” not “True”/”False” nor “TRUE”/”FALSE”.

Conclusion:

1. We can not get the output value from the logical functoid to the destination node. Seems it could be used only as an input value for other functoids.

2. The logical functoids understand only the low case values, “true” and “false”.

3. The only place where I can use the “literal” logical value generated by the logical functoid is the input of another logical functoid, i.e. the functoid chain. And the logical functoids can only return the low case values, “true” and “false”.

4. Help property of a Logical functoid has an error. The logical functoids can return not “TRUE” but “true”.

Other functoids

Some non-logical functoids can use the boolean values returned by the logical functoids. They are a Value mapping functoid and Value mapping (Flattening) functoid. Not sure about other functoids.

(Pict.5)

IMHO Behavior of the Boolean values and the Logical functoids in the maps are not intuitive.

References:

XML Schema Part 2: Datatypes Second Edition

W3C Recommendation 28 October 2004:

"...

3.2.2 boolean

[Definition:] boolean has the ·value space· required to support the mathematical concept of binary-valued logic: {true, false}.

3.2.2.1 Lexical representation

An instance of a datatype that is defined as ·boolean· can have the following legal literals {true, false, 1, 0}.

3.2.2.2 Canonical representation

The canonical representation for boolean is the set of literals {true, false}.

..."

Microsoft .NET Framework Class Library:

"…

Boolean.TrueString Field

Represents the Boolean value true as a string. This field is read-only.

public static readonly string TrueString;

Remarks

This field is equal to the string "True".

…"

SQL Server doesn't save the Boolean type.

It works with it in Logical operator, that’s all:

SQL Server Books Online:

"...

Logical Operators

Logical operators test for the truth of some condition. Logical operators, like comparison operators, return a Boolean data type with a value of TRUE or FALSE.

..."

Arguments

boolean_expression

"...

Is any valid Microsoft® SQL Server™ expression that returns a Boolean value: TRUE, FALSE, or UNKNOWN.

Result Types

Boolean

..."

BizTalk: Mapping Empty or Missing attributes and elements with different combinations of parameters: Required/Optional, Min/MaxOccurs, Default, Fixed

Leonid Ganeline — Sat, 24 Dec 2005 02:51:00 GMT

Mapping Empty or Missing attributes and elements with different combinations of parameters: Required/Optional, Min/MaxOccurs, Default, Fixed

When I am creating maps it is annoying to me guess which values I'm getting if I have to mapping Empty or Missing attributes/elements. I've made an investigation on the base of a Standard "XML Schema Part 0: Primer. W3C Recommendation, 2 May 2001".
http://www.w3.org/TR/2001/REC-xmlschema-0-20010502/#OccurrenceConstraints (below is this article).
I added the last column with my comments to the original table (in BizTalk mapping has got some differences from the standard!).

I used the BTS2004 Mapper and "Test Map" command. I've changed the properties of attribute and element in a target schema.
I was waiting that the behaviour of mapping should be the same as in standard.
Results are different in several points:
1) "Fixed" and "Default" properties don't change mapping. They only change validation and they have a different effect on validation.
2) "Required" property of attributes: If source attribute is missing the mapping creates the attribute with Empty value.
3) Something strange with "min/maxOccures" properties of elements: If they are (1,1), (-,1), (1,-), or (-,-) and source element is missing the mapping creates an element with Empty value! Only these combinations generate an element with Empty value, other combinations do not create an element.

"
2.2.1 Occurrence Constraints
The comment element is optional within PurchaseOrderType because the value of the minOccurs attribute in its declaration is 0. In general, an element is required to appear when the value of minOccurs is 1 or more. The maximum number of times an element may appear is determined by the value of a maxOccurs attribute in its declaration. This value may be a positive integer such as 41, or the term unbounded to indicate there is no maximum number of occurrences. The default value for both the minOccurs and the maxOccurs attributes is 1. Thus, when an element such as comment is declared without a maxOccurs attribute, the element may not occur more than once. Be sure that if you specify a value for only the minOccurs attribute, it is less than or equal to the default value of maxOccurs, i.e. it is 0 or 1. Similarly, if you specify a value for only the maxOccurs attribute, it must be greater than or equal to the default value of minOccurs, i.e. 1 or more. If both attributes are omitted, the element must appear exactly once.

Attributes may appear once or not at all, but no other number of times, and so the syntax for specifying occurrences of attributes is different than the syntax for elements. In particular, attributes can be declared with a use attribute to indicate whether the attribute is required (see for example, the partNum attribute declaration in po.xsd), optional, or even prohibited.

Default values of both attributes and elements are declared using the default attribute, although this attribute has a slightly different consequence in each case. When an attribute is declared with a default value, the value of the attribute is whatever value appears as the attribute's value in an instance document; if the attribute does not appear in the instance document, the schema processor provides the attribute with a value equal to that of the default attribute. Note that default values for attributes only make sense if the attributes themselves are optional, and so it is an error to specify both a default value and anything other than a value of optional for use.

The schema processor treats defaulted elements slightly differently. When an element is declared with a default value, the value of the element is whatever value appears as the element's content in the instance document; if the element appears without any content, the schema processor provides the element with a value equal to that of the default attribute. However, if the element does not appear in the instance document, the schema processor does not provide the element at all. In summary, the differences between element and attribute defaults can be stated as: Default attribute values apply when attributes are missing, and default element values apply when elements are empty.

The fixed attribute is used in both attribute and element declarations to ensure that the attributes and elements are set to particular values. For example, po.xsd contains a declaration for the country attribute, which is declared with a fixed value US. This declaration means that the appearance of a country attribute in an instance document is optional (the default value of use is optional), although if the attribute does appear, its value must be US, and if the attribute does not appear, the schema processor will provide a country attribute with the value US. Note that the concepts of a fixed value and a default value are mutually exclusive, and so it is an error for a declaration to contain both fixed and default attributes.

The values of the attributes used in element and attribute declarations to constrain their occurrences are summarized in Table 1.
"






Table 1. Occurrence Constraints for Elements and Attributes

Elements	Attributes	Notes	Notes [Leonid Ganeline]
(minOccurs, maxOccurs), fixed, default	use, fixed, default
(1, 1) -, -	required, -, -	element/attribute must appear once, it may have any value	If source attrbute/element is missing the mapping creates the attribute/element with Empty value!
(1, 1) 37, -	required, 37, -	element/attribute must appear once, its value must be 37	If source attrbute/element is missing the mapping creates the attribute/element with Empty value, not 37! (Of course, Target XML doc doesn't pass the output validation.)
(2, unbounded) 37, -	n/a	element must appear twice or more, its value must be 37; in general, minOccurs and maxOccurs values may be positive integers, and maxOccurs value may also be "unbounded"	If source attrbute/element is missing the mapping creates the attribute with Empty value and non an element! I've tried different combinations of min/maxOccurs. Only (1,1),(-,1),(1,-), and (-,-) created an Empty element!
(0, 1) -, -	optional, -, -	element/attribute may appear once, it may have any value	exactly
(0, 1) 37, -	optional, 37, -	element/attribute may appear once, if it does appear its value must be 37, if it does not appear its value is 37	If source attrbute/element is missing Non attrbute/element is created! If source attrbute/element is != Fixed_value Non attrbute/element is changed to Fixed_value, it mapped from a source value, And we've got the output validation errors.
(0, 1) -, 37	optional, -, 37	element/attribute may appear once; if it does not appear its value is 37, otherwise its value is that given	If source attrbute/element is missing/empty Non attrbute/element is created! If source attrbute/element is != Default_value Non attrbute/element is changed to Default_value, it mapped from a source value, And we have NOT got the output validation errors.
(0, 2) -, 37	n/a	element may appear once, twice, or not at all; if the element does not appear it is not provided; if it does appear and it is empty, its value is 37; otherwise its value is that given; in general, minOccurs and maxOccurs values may be positive integers, and maxOccurs value may also be "unbounded"	If source element is missing/empty Non element is created! If source element is != Default_value non element is changed to Default_value, it mapped from a source value, And we have NOT got the output validation error.
(0, 0) -, -	prohibited, -, -	element/attribute must not appear	exactly. BTW If I delete an element but save a whitespace on its place I've got an error"error btm1046: Output validation error: The element cannot contain text or white space. Content model is empty." (?)
Note that neither minOccurs, maxOccurs, nor use may appear in the declarations of global elements and attributes.

“

What I'd like to see in the BizTalk 2004 Mapper (and Schema Editor) at my routine work

Leonid Ganeline — Fri, 23 Dec 2005 22:01:00 GMT

IMHO

What I'd like to see in the BizTalk 2004 Mapper (and Schema Editor) at my routine work:

1. Names of Source and Destination schemas (maybe on the heads of the Source and Dest panes). Usually I work with more then one maps in one project and I have the long map's names as "CompanyNDocumentBlahBlah_TO_CompanyKDocumentBlah2Blah2". These names don't fit into the tab fields and I have to look to the Property window. I always have meaningless the Headers with text "Source/Destination schema". Why don't put here useful information?

2. Icons of the records. I'd like to see on them a visual representation of a property the "Max Occurs" = "unbounded". The works with unbounded records is pretty different then work with "one exemplar" records (different semantic, different functoids). Different view of the Unbounded records help to avoid the typical errors.

3. Icons of the nodes. It was useful to use the different flavors of the icons where we can get different behavior of the nodes. (2. above for example). Different views of the fields help to avoid the typical errors.
Here is the list:

a) "Max Occurs" = "unbounded"

b) "Min Occurs" = "0"

c) “include”, “import”

d) “Optional”/”Required”

4. Expression Editor??? In Orchestration Designer etc. It's so small, it can't be resized, and it can’t be “word-wrap-ed”. Why don't made it like usual window that I can change its size, dock it where I like etc.? Now I have to scroll it all time! "Booooriiiiing (H.Simpson)"

5. Add special window for big values. BTS has many points where the big (or huge!) values pop-up. Examples: - XPath values of Properties in the Properties window - messages and errors in the Task List - long names of the different objects in the Orchestration designer ...
Now I hover cursor over and... do u like this tooltip? Or double-click and work in the specific window. Frequently I have to copy the value in Notepad and work with it. :((
If I could dock "Big values window" under Toolbox or Properties or somewhere else it would be great.
Frankly, I’d like to have "Big values window" like a standard part of VS.NET not only in the BTS environment. When I work with Scripting functoids they all have the same face: in the Map editor - [S], in the Property windows - the absolutely equality values for all functoids. If I want to know more (and of course I want!) I have to open Properties/Script window.

Does somebody have any comments? It would be realy appreciated...