Posts Tagged ‘BizTalk 2010’

For some reason after having migrated a BizTalk 2006/Visual Studio 2005 solution to BizTalk 2010/VS 2010 using Visual Studio Conversion Wizard, I got the following error:

"Cannot generate serialization assembly {AssemblyName}.XmlSerializers.dll because it already exists. Use /force to force an overwrite of the existing assembly"

SGEN-Cannot-generate-serialization-assembly-XmlSerializers

The migration of this project was divided into two parts:

  • First part is to migrate the project as is to the new environment in order to discontinue the old platform;
  • The second part is to improve the project with new functionalities available in the new version (migrate SOAP adapter to WCF and so on);

CAUSE

The XML Serializer Generator creates an XML serialization assembly for types in a specified assembly in order to improve the startup performance of a XmlSerializer when it serializes or deserializes objects of the specified types.

However, some time if you have a traditional Web Service reference in your BizTalk Project this error may suddenly appear. It seems that when you try to build the solution the SGEN process is having some trouble deleting the original XMLSerializers.dll and in result will give you that error.

SOLUTION 1

This problem can be solved by:

  • Going to the path “%windir%\Microsoft.NET\assembly\” (.NET 4.0) or “C:\WINDOWS\assembly” (if you use previous version of .NET) and uninstall the corresponding Project name DLL from there.
  • And then rebuild the Project.

Limitation: each time you deploy the DLL to the GAC, the next time you need to build the project you first need to uninstall the DLL from the GAC

SOLUTION 2

You also can solve this error by choosing not to generate a Serializiation assembly from the Project Properties.

  • Right-click in the project name and select “Properties” option
  • On the left tree option choose “Build” tag
  • Under the Output properties, from the drop box “Generate serialization assembly” select “Off”

Visual-Studio-Project-Properties-Generate-serialization-assembly-off

Finally I had some free time available to be able to update and fix some minor bugs which existed in the latest version of this adapter and already had been reported by community members.

I have to give a special thanks to maakku that reported a problem related to the Daily schedule properties… and the respective solution!!

So today a published a minor release of BizTalk Scheduled Task Adapter is available for download on CodePlex: BizTalk Scheduled Task Adapter v4.0

NOTE: the adapter is still in version 4.0, I have not modified the version. As I said earlier this is a minor release to solved small bugs.

codeplex-BizTalk-Scheduled-Task-Adapter-page

List of improvements in this minor release:

  • Daily scheduler review. Solved a small bug on Daily Properties: settings were not saved correctly when configuring daily schedule in admin console (see more here)
  • Support for 32 and 64 bit Host Instances.
  • Fix the version number of the adapter that was being recorded incorrectly as 3.0.0. After installing the adapter, in Programs and Features the version for the BizTalk Scheduled Task Adapter it was 3.0.0.

Note: The adapter was tested with success running in 32 and 64 bit Host Instances!

Configuring the BizTalk application

This is the final step of this process. In order to properly test the solution we have been developing in BizTalk Server, we need to configure the application that was created in the publication.

For this, we will access the BizTalk Server Administration console to create and configure the following artifacts:

  • One receive port and location to process the input text files;
  • One send port to save the processed files in XML format..

Open the BizTalk Server Administration console under “Start –> Programs –> Microsoft BizTalk Server 2010”. On the left tree menu, maximize “BizTalk Server Administration –> BizTalk Group (…) –> Applications”, and look for the application called “TransfFlatFilesEmXML Demo” and maximize also this application.

maximize-BizTalk-Application

  • Press the right button on top of “Receive Port” menu and select “New –> One-Way Receive Port …” option;
  • A new window appears allowing us to define the port properties:
    • In the “General” tab, set the name of the receive port: “ReceiveTXT”.

New-receive-port

    • In the “Receive Locations” tab, select “New” and set the name to your receive location: “ReceiveTXT_to_XML”; in the property “Type” select the option FILE; and in the property “Receive pipeline” select from the drop down box the pipeline we created earlier: “ReceivePipelineCustomPessoas”;

New-receive-location

    • On the same tab select the “Configure” button. In the “FILE Transport Properties” window, set “Receive Folder” property, with the folder you created earlier “<solution>\PORTS\IN”. On property “File Mask” put the following value: “*. txt”, setting that will be processed only files with the extension. “txt”. Finally select the “Ok” button.

File-Adapter-Properties

    • To finish the process of creating the receive port press “Ok”.

The above steps mentioned, were needed to create one Receive Port and its Receive Location. Now we will create a Send Port to save messages on the file system, after they are processed by BizTalk:

  • Press the right button on top of “Send Ports” menu and select “New –> Static One-way Send Port…”
  • A new window appears allowing us to define the port properties:
    • In the “General” tab, set the name of the send port: ” SaveXMLFile “
    • In the property “Type” select the option FILE;
    • In the property “Send Pipeline” set the pipeline to “XMLTransmit”. This is a native pipeline that is used for processing XML messages.

New-send-port

    • On the same tab select the “Configure” button. In the “FILE Transport Properties” window, set the “Destination Folder” property, with the folder you created earlier “<solution>\PORTS\OUT”. On property “File Mask” put the following value: “%MessageID%.xml”, this is special tag (BizTalk Macro) that will set the name of each file written on the file system with the unique identifier of the message. Finally select the “Ok” button to return to previous window.

Send-port-File-Adapter-Properties

    • In order for the Send Port subscribes to all files, we need to set a filter on the tab “Filters” with the following expression: “BTS.ReceivePortName == ReceiveTXT”.
      • Note: This setting will force each message in the MessageBox which has originates from the Receive Port: ReceiveTXT, be routed and processed by the Send Port we are finished creating.

New-send-port-filter

    • To finish the process of creating the send port press “Ok”.

Finally, we need only to start our application. To do that press right button on top of the application name “TransfFlatFilesEmXML Demo” and select “Start …”.

start-BizTalk-application

Testing the solution

To test the BizTalk application we only need to copy a text file to the directory that is configured on the receive location: “<solution>\PORTS\IN”. The result should appear in the form of an XML document in the folder configured in the send port: “<solution>\PORTS\OUT”.

Note: The file disappears automatically from the input folder, so you should avoid doing drag & drop (move) with the test files at the risk of not being able to use it again.

Conclusion

As presented in this article, BizTalk Server helps us to solve many of the existing problems concerning message transformation: semantic and syntax Transformations, only with “out of the box” features within the product, in few steps and most of the time without developing any code.

The fact of all the definitions of the rules of parsing (transformation rules) are embedded in the form of annotations in XML Schema (XSD), such as the delimiter symbols, or the element size in a positional file, simplifies the reuse of all these schemes in different parts of the process. At any point, the document can be translated back into flat-file because the definition is declarative and symmetric, in contrast to what might happen with a “normal” programming language like C#, where we would have to create two components to translate text to XML and vice versa.

The model used by BizTalk schemas, , centralizes all the message definitions in a single artifact, simplifying the maintenance and evolution of the specification and therefore simplifying future reuse and dependencies management. When we set up this type of project, is exactly this kind of guarantees than keeps the systems operating properly for many years, and at the same time, they make life easier to those who one day have to correct and/or develop any of these processes

Related links

Source code

The solution of this example, as well all the code, is available on MSDN Code Gallery:
BizTalk Server – Transform text files (Flat Files) into XML (64.5 KB)
MSDN Code Gallery

Constructing a Flat Files Schema – Practical example

For this project we will use the BizTalk Server 2010 and Visual Studio 2010, and explain step by step what needs to be developed. Briefly these are the steps we have to perform:

  • Creating an instance of the text file that will serve as a test file for the project;
  • Creating the Schema which will recognize the text file;
  • Creating the Pipeline that will be responsible for processing and transforming the text file;
  • Deploy the BizTalk Server solution;
  • Configuring the BizTalk application;
  • Run the solution;

The solution of this example, as well all the code, is available on MSDN Code Gallery: http://code.msdn.microsoft.com/BizTalk-Server-Transformar-0abe5767

We begin then by launching Visual Studio 2010 and create a new BizTalk project:

  • “File –> New –> Project”, on BizTalk Projects, select the option “Empty BizTalk Server Project”;
  • Insert the project name, physical location on the disk and the name of the solution.

New-BizTalk-project

Creating an instance of the text file that will serve as a test file for the project

Before we begin our development we need to create an instance, or sample of the text file that will serve as a model for the creation of the Flat File Schema. Therefore we will create the following text file on our file system that will be used in our solution:

  • Create a folder “<solution>\TESTFILES” where we will create/put the messages we want to transform. In this article we will use a text file delimited by symbols which will be composed of several lines with the following content:
Sandro;Pereira;1978-04-04;Crestuma;4415 Crestuma
Lígia;Tavares;1982-01-21;Seixo-Alvo;451 Seixo-Alvo
José;Silva;1970-09-19;Crestuma;4415 Crestuma
Rui;Barbosa;1975-09-19;Lever;4415 Lever

Each line consists of the following structure: Name (Nome), Surname (Apelido), Birthdate (Data Nascimento), Address (Morada) and Zip Code (Código Postal);
Note: in () is the equivalent in Portuguese found in pictures. The file “PESSOAS.txt” that we use for testing is available in the directory “<solution >\TESTFILES”.

  • We will also create two folders that we will configure in the BizTalk Administration Console in order to test the solution.
    • Create a folder “<solution >\PORTS\IN” which will serve as the place of entry of Flat File files for conversion;
    • Create a folder “<solution >\PORTS\OUT” which will serve as the output location of the files after they have been converted.
Creating the Schema which will recognize the text file

To create the schema which will recognize the text file, we need to go to the BizTalk solution created in Visual Studio and perform the following steps:

  • Press the right button on top of the project in Solution Explorer, and select the option “Add –> New Item…”.
  • On “Installed Templates” menu in the window “Add New Item”, select the option “Schema Files”, and then select the option “Flat File Schema Wizard”, then provide the name you want to give the scheme in this example: “TXT_to_XML.xsd”

New-flat-file-schema

  • By selecting this option, we will be guided automatically by the tool “BizTalk Flat File Schema Wizard” that will help us to create a Flat File Schema and define its data structure (records, elements, attributes …) based on the text file specified. Select “Next” to continue.

Welcome-flat-file-wizard

  • In the window “Flat File Schema Information” we will have to:
    • Select an instance of the text file that will serve as the model of the structure that we want to transform;
    • Although it is not necessary, it is good practice to rename the Record name “Root”. In this case we will rename it to “People” (Pessoas)
    • And finally, assign a “Target namespace” to the scheme and define the encoding of the input file

information-flat-file-schema-wizard

  • The wizard will load the text file so that we can begin to split it and map it into the desired structure. In this step we need to define how the records or rows are differentiated. The structure of the example is:
Name;Surname;Birthdate;Address;Zip Code{CR}{LF}
(Nome;Apelido; Data Nascimento;Morada;Codigo Postal{CR}{LF})

Since each record “Person” (Pessoa) that we want to create is defined and contained in a line, in the “Select Document Data” we will select all the data portion of the document that will set the record, i.e. the whole first line.

select-file-flat-file-schema-wizard

  • In the window “Select Record Format” we will define whether we are dealing with a Flat File Delimited by symbols or is positional, in our case we will select the “By delimiter symbol” which is delimited by a return Carriage Return/Line Feed.

delimiter-flat-file-schema-wizard

  • In the window “Delimited Record” we will provide the record delimiter, in this case as we want to define the structure of person (Pessoa), i.e. each row is a person, our limiter is {CR}{LF} (Carriage Return/Line Feed)

delimiter-flat-file-schema-wizard-2

  • In the window “Child Elements” we will define what kind of element we want to assign to the registry. As we are defining the Person structure and the file contains multiple people, we have to select the “Element Type” as “Repeating record.” If we do not perform this step, we will not have the ability to split the record into multiple elements / attributes individual.

elements-flat-file-schema-wizard

  • At this stage we successfully created the record Person (Pessoa), i.e. we have just map that each line of the text file corresponds to a record Person. In the “Schema View” select “Next” to continue processing the message

view-flat-file-schema-wizard

  • At this stage the wizard restarts the whole process described above, but if you noticed, the wizard no longer selects all information contained in the text file, but only what was selected to define the record Person. What we will do now is split the information of record “Person” in different elements, for that, we will select only the information required leaving out the Carriage Return/Line Feed.

select-file-flat-file-schema-wizard-2

  • Once again our structure is delimited by symbols (;), then we will select the option “By delimiter symbol”

delimiter-flat-file-schema-wizard-3

  • As we can analyze all the elements are separated by the semicolon (;) that is our delimiter, then in the window “Delimited Record” we must change the value of the “Child delimiter” option to “;”.

delimiter-flat-file-schema-wizard-4

  • In this window “Child Elements”, we will define the different elements/attributes of the structure of the record person. This operation is very similar to any XSD, where we can define the different names and data types. Adjust the values ​​according to the image:

elements-flat-file-schema-wizard-2

  • Finally the wizard will show the equivalent XML structure that your text file document will have. Once you select the option “Finish”, the scheme will be available for you to use in your BizTalk solution.

view-flat-file-schema-wizard-2

After we finalize the creation of the Flat File Schema which will contain the transformation rules of the text file, we can easily test our transformation, without having to get out of our development tool (Visual Studio) and without having to publish our solution.

If we select the Flat File Schema that we just created and access to its properties, we can see that by default all properties are preconfigured so that we can perform tests to our message transformation: the input instance file is configured with the file which was used to create the schema; and the correct input (Validate Instance Input Type: Native) and output (Generate Instance Output Type: XML) formats.

test-flat-file-schema

To test, you simply select the schema and with the right mouse button select the option “Validate Instance”:

validate-flat-file-schema

This option will use the configured file and validate all transformation rules defined and subsequently present the final result or occurring errors:

result-flat-file-schema

Creating the Pipeline that will be responsible for processing and transforming the text file

To create the Receive Pipeline that will be responsible for processing and transforming the text file, we need to go to the BizTalk solution created in Visual Studio and perform the following steps:

  • Press the right button on top of the project in Solution Explorer, and select the option “Add –> New Item…”.
  • On “Installed Templates” menu in the window “Add New Item”, select the option “Pipeline Files”, and then select the option “Receive Pipeline”, then provide the name you want to give the pipeline in this example: “ReceivePipelineCustomPessoas.btp”

New-pipeline-item

  • By selecting the option “Add”, the pipeline editor (BizTalk Pipeline Designer) will appear and that will let you view and add components to all the steps associated with receive pipeline: Decode, Disassemble, Validate and ResolveParty. In this case, the pipeline that we will create, will be responsible for receiving a text file through a receive location and convert it to XML. For that, we will use the “Flat File Disassembler” component which is available in the Visual Studio Toolbox window (Ctrl+W, X). Drag it into the Pipeline in step “Disassemble”.

new-pipeline-flat-file-disassembler

  • Finally, select the component “Flat file disassembler”, go to its properties and on the “Document Schema” option: select the schema created earlier, in case the “TXT_to_XML.”.

pipeline-select-flat-file-schema

Note: If you want to create a send pipeline in order to transform an XML document into Flat File, we would follow the same steps, the difference is that we would have to drag the component “Flat File Assembler” on stage “Assemble”.

Deploy the BizTalk Server solution

All artifacts created yet must be installed on BizTalk Server 2010. However before we can deploy the solution there are some settings we need to do or guarantee:

  • Before deploy the Visual Studio solution into a BizTalk application is necessary that all project assemblies are signed with a strong name key, since they must be installed in the global assembly cache (GAC). For this we need:
    • In Visual Studio Solution Explorer, right-click on the project name and select “Properties” option
    • Select the “Signing” tab and choose “New” in the drop down box “Choose a strong name key file”

sign-project

    • Assign a name, for example “TXTtoXML.snk”

create-stronge-name

  • Likewise, before deploy the Visual Studio solution into a BizTalk application, we need to first define the BizTalk deployment properties, especially the properties of the “BizTalk Group”. If the Visual Studio solution contains multiple projects, we need to set the properties for each project separately.
    • In Visual Studio Solution Explorer, right-click on the project name and select “Properties” option
    • Select the “Deployment” tab and configure the name you we want to assign to the BizTalk application in the property “Application Name”: in our example “TransfFlatFilesEmXML Demo”. The remaining properties may stay with the default values.

deploy-project

Finally we can Build and Deploy the project so that it is published as an BizTalk application inside BizTalk Server:

deploy-project-2

However in order to publish a BizTalk solution, you must be a member of the group “BizTalk Server Administrators”. If the option “Install to Global Assembly Cache” is enabled, on the “Deployment” properties, then you also need permissions to read/write on GAC.

Related links

Necessary tools and artifacts

As mentioned earlier, to solve this problem – BizTalk Server: Transform text files (Flat Files) into XML – we must create at least two artifacts:

  • Flat File Schema: withall the necessary information embedded in the form of annotations in XML Schema (XSD), such as the delimiter symbols, or the element size in a positional file, i.e. the definition of the rules of parsing (transformation rules). This type of artifact can be created manually or with the tool “BizTalk Flat File Schema Wizard”.
  • Receive (and Send – optional) Pipeline: that will be responsible for processing and transforming the text file (Flat File) into its equivalent XML. This artifact can be created using the BizTalk Pipeline Designer.
BizTalk Flat File Schema Wizard

BizTalk Flat File Schema Wizard tool, integrated in Visual Studio, which allows us to easily and visually make transformation of text file (Flat File) into its equivalent XML representation. This tool supports two types of text files:

  • Positional text files:
HEADERXXXXXXXXXXXXXXXXXXXXXXX
BODYXXXXXXXXXXXXXXXXXXXXXXXXX
BODYXXXXXXXXXXXXXXXXXXXXXXXXX
FOOTERXXXXXXXXXXXXXXXXXXXXXXX

flat-file-Positional-header

Note: Header is in Portuguese “Cabeçalho”, therefore the text from the image is in Portuguese

  • Or delimited by symbols:
1999990;1;P0110;1;1;20110307;
1999990;2;P0529;2;2;20110307;
1999990;3;P0530;3;3;20110307;

flat-file-delimiterflat-file-delimiter-elements

BizTalk Pipeline Designer

The editor of pipelines, BizTalk Pipeline Designer, allows us to create, visualize and edit pipelines; move pipeline components between the different stages and configure pipelines components.

biztalk-pipeline-designer

This editor is integrated into Visual Studio and is mainly composed of 3 modules:

  • Properties window: in this window we can see and modify the properties of components in the different stages of the pipeline.
  • Toolbox window: is used as a source for the design surface, it provides access to all the components that we use in pipelines.
  • Design surface: where components from the Toolbox are dragged and dropped, which allows us to draw a graphical representation of a pipeline by inserting the components, available in the toolbox window, in the different stages of the pipeline.

Related links

Introduction

Transformations are one of the most common components in the integration processes. They act as essential translators in the decoupling between the different systems to connect. This article aims to help you understand the process of transforming a text file (also called Flat Files) in an XML document using BizTalk Server Flat File Schemas.

Normally we associate the transformations of documents to BizTalk maps, but the reality is that there are two types of transformations: structure transformation (semantics) and representation transformation (syntax). These latest occurs typically at receiving or sent ports of BizTalk Server,

This article intends to be an introductory note for whom is taking the first steps in this technology.

One of the most ancient and common standards for message representation is to use text files (Flat Files) like: CSV (Comma Separated Values) or TXT files, many of them custom-made for their systems. However over the time, XML became the standard message format because of its widespread use by major corporations and open source development efforts. However do not be fooled and think that these kinds of message are outdated and rarely used, a good example is EDI messages, which is used extensively by large companies, so it is often necessary to transform text files into XML and vice versa.

FlatFile-sample

While tools like Excel can help us interpret such files, this type of process is always iterative and requires few user tips so that software can determine where is need to separate the fields/columns as well the data type of each field. But for a system integration (Enterprise Application Integration) like BizTalk Server, you must reduce any ambiguity, so that these kind of operations can be performed thousands of times with confidence and without having recourse to a manual operator.

Map or Schema Annotation?

As mentioned in the introduction, we can characterize two types of transformations existing in BizTalk:

  • Semantic Transformations: This type of transformation usually occurs only in BizTalk maps. Here the document maintains the same syntax that is represented (XML), but changes its semantics (data content). This type of transformation are typically one-way, since that when we added and aggregate small parts of the information, that compose the document into another differently document, we may miss important details for its reconstruction.

  • Syntax Transformations: This type of transformations occurs in the receive or send pipelines and aim to transform a document into another representation, e.g. CSV to XML. Here the document maintains the same data (semantics), but changes the syntax that is represented. I.e. we translate the document, but typically we don’t modify the structure. Normally, this type of transformation is bidirectional, since we still have the same semantic content, we can apply the same transformation logic and obtain the document in its original format. Common examples of these transformations are also conversions between HL7 and XML, or EDI and XML.

Note: In this article we will talk only of Syntax transformations. If you are looking to learn more about semantic transformations, you can consult the article “BizTalk Server: Basics principles of Maps“.

How does the text files (Flat Files) are processed by BizTalk?

Internally, BizTalk “prefers” to use the message type XML. If messages are in XML format BizTalk “offers” numerous automatisms that are very useful in these environments, such as: message routing based on a particular field (promoted property); tracking and analysis of multidimensional values ​​and dimensions with BAM (Business Activity Monitoring), or making logical decisions within orchestrations (business processes) using elements of the message.

If messaging is the foundation of BizTalk Server, the message schemas are the bedrock on which messaging is built. Fortunately, BizTalk supports the conversion of text files to XML in a simple and intuitive manner, using for that “Flat File Schemas” that are simple XML schemas (XSD) with specific annotations. At first glance, this may seem strange, because the XML Schemas (XSD) are used to describe XML files, however BizTalk uses them as metadata to describe not only XML documents but also text files (flat file).

The trick is that all the necessary information, such as the delimiter symbols, or the element size in a positional file, i.e. the definition of the rules of parsing (transformation rules) are embedded in the form of annotations in XML Schema (XSD), thereby simplifying the reuse of all these schemes in different parts of the process. At any point, the document can be translated back into flat-file because the definition is declarative and symmetric.

Where the Syntax Transformations can occur?

This type of transformations can occur in receive or send pipelines, usually text files (Flat Files) are processed at runtime as follows:

  • The Flat Files are received by an adapter associated to a receive location (Folder in File System for example)
  • A pipeline configured in the receive location will be responsible for transforming the Flat File into its equivalent XML;
  • One or more interested in the message, such as an orchestration will subscribe to the XML document and this message will go through the business process. Note, in a pure messaging scenario there is no need to have orchestrations;
  • If and when necessary, BizTalk can send XML messages again as a text files (Flat Files) by using another pipeline in the send ports, which will be responsible for transforming the XML into its equivalent the Flat File;

As the image below shows:

biztalk-flatlfile-runtime-architecture

The receive pipeline consists of four stages, being that syntax transformations may occur in two of them:

  • Decode stage: This stage is used for components that decode or decrypt the message. The MIME/SMIME Decoder pipeline component or a custom decoding component should be placed in this stage if the incoming messages need to be decoded from one format to another. The syntax transformations can occur in this stage through a custom component.
  • Disassemble stage: This stage is used for components that parse or disassemble the message. The syntax transformations should occur at this stage. In the example that will be demonstrated in this article, we will use the “Flat file disassembler” to transform a text file into XML.

receive-pipeline-architecture

  • Validate stage: This stage is used for components that validate the message format. A pipeline component processes only messages that conform to the schemas specified in that component. If a pipeline receives a message whose schema is not associated with any component in the pipeline, that message is not processed. Depending on the adapter that submits the message, the message is either suspended or an error is issued to the sender.
  • ResolveParty stage: This stage is a placeholder for the Party Resolution Pipeline Component.

Regarding to the send pipelines, they consist of three stages, being that syntax transformations may occur also in two of them:

  • Pre-assemble stage: This stage is a placeholder for custom components that should perform some action on the message before the message is serialized.

send-pipeline-architecture

  • Assemble stage: Components in this stage are responsible for assembling or serializing the message and converting it to or from XML. The syntax transformations should occur at this stage.
  • Encode stage: This stage is used for components that encode or encrypt the message. Place the MIME/SMIME Encoder component or a custom encoding component in this stage if message signing is required. The syntax transformations can occur in this stage through a custom component.

Related links

Introduction

The BizTalk Scheduled Task Adapter is an in-process receive adapter that executes a prescribed task on a daily, weekly or monthly schedule. The adapter is configured entirely within BizTalk, all configurations is stored within the SSODB and can be exported and imported via binding files.

The schedule capabilities are similar to those available with the Windows Scheduled Task Service.

Four simple tasks are included in this version:

  • XmlStringStreamProvider – generates a BizTalk message from a configured Xml string
  • FileStreamProvider – generates a BizTalk message from the contents of a file
  • HttpDownload – generates a BizTalk message from data downloaded from a web site
  • SQLStreamProvider – generates a BizTalk message from the contents of a SQL Query (similar to the old SQL adapter)

Custom tasks can be created. Any .NET class that implements the appropriate interface can be scheduled.

Release History

This adapter is available since BizTalk Server 2004.

  • Release 1.02: last release in Apr 20 2008 by Greg Forsythe, this adapter works with BizTalk Server 2004, BizTalk Server 2006 and BizTalk Server 2006 R2. Compiled in .NET Framework 1.1
  • Release 2.0: last release in Apr 20 2008 by Greg Forsythe, this adapter works with BizTalk Server 2006 and BizTalk Server 2006 R2. Compiled in .NET Framework 2.0
  • Release 3.0: release in Aug 10 2010 by Greg Forsythe, this adapter was tested to work on BizTalk Server 2009. Compiled in .NET Framework 2.0
  • Release 4.0: release in June 12 2012 by Sandro Pereira, this adapter was tested to work on BizTalk Server 2010. Compiled in .NET Framework 4.0
Requirements

The Scheduled Task Adapter v4.0 will work with:

  • BizTalk Server 2010
  • .NET Framework 4.0

 

Installation Process

To install the adapter run "ScheduledTaskAdapter.msi".

  • In the “Welcome” screen press “Next”.

Scheduler-Task-Adapter-welcome-screen

  • In the “Select Installation Folder” screen you must set the installation locations were you what to install the adapter.

Scheduler-Task-Adapter-installation-folder-screen

  • The following screens are very straightforward – In the “Confirm Installation” screen press “Next”, then it will appear the installation progress and assuming all goes well a completion screen.

Scheduler-Task-Adapter-confirmation-screen

Scheduler-Task-Adapter-complete-screen

The setup will install the following assemblies in the selected folder (Default: C:\Program Files (x86)\Biztalk ScheduledTask Adapter):

  • Biztalk.Adapter.ScheduledTaskProperties.dll
  • Calendar.Schedules.dll
  • Microsoft.BizTalk.CommonSettings.dll
  • Microsoft.BizTalk.SqmFramework.dll
  • ScheduledTaskAdapter.Admin.dll
  • ScheduledTaskAdapter.dll
  • ScheduledTaskAdapter.TaskComponents.dll
  • stdole.dll

The setup will add the following assemblies to the Global Assembly Cache (GAC)

  • Biztalk.Adapter.ScheduledTaskProperties.dll
  • Calendar.Schedules.dll
  • ScheduledTaskAdapter.dll
  • ScheduledTaskAdapter.Admin.dll
  • ScheduledTaskAdapter.TaskComponents.dll

 

Post-Installation
Register the Adapter with BizTalk

As it happens with all adapters that we installed on our BizTalk Servers before we can begin to use it we need to register or configure the adapter. To accomplish that we need to:

  • Open BizTalk Administration Console
  • In the console left tree, expand “BizTalk Server Administration –> BizTalk Group –> Platform Settings” and then “Adapters”
  • Right-click on “Adapters” and add a new adapter by selecting the option “New –> Adapter”

register-Scheduler.Task-Adapter-New-Adapter

  • In the “Adapter Properties” window
    • Set the name of the adapter: Name = Schedule
    • In the adapter combo box select the option: Schedule
    • Set the description of the adapter: “BizTalk Scheduled Task Adapter. The schedule capabilities are similar to those available with the Windows Scheduled Task Service.” (this property is optional but I would suggest to always be filled)

register-Scheduler.Task-Adapter-New-Adapter-select-adapter-properties

Note: This configuration requires that you restart the host instance associated with the adapter.

register-Scheduler.Task-Adapter-New-Adapter-restart-host-instances

Using the adapter Context Properties

To utilize the Scheduled Task adapter’s context properties within a filter or orchestration the Biztalk.Adapter.ScheduledTaskProperties.dll must be deployed into the BizTalkMgmtDb.

This can be achieved using the Biztalk Deployment Wizard or equivalent tool.

Note: This step is optional; you only need to do this if you want to use Scheduled Task adapter’s context properties within a filter or orchestration.

As previously mentioned, you can deploy Biztalk.Adapter.ScheduledTaskProperties.dll in various ways; I suggest that you do the following steps:

  • Open BizTalk Administration Console
  • In the console left tree, expand “BizTalk Server Administration –> BizTalk Group” and then “Applications”
  • Right-click on “Applications” and add a new application by selecting the option “New –> Application”

New-application

  • In the “Adapter Properties” window
    • Set the name of the application: BizTalk.Global
    • Set the description of the application: “Application that contain common resources to several applications” (this property is optional but I would suggest to always be filled)

New-application-properties

  • Expand the application created previous and select the option “Resources”
  • Right-click and add a new BizTalk resource by selecting the option “New –> BizTalk Assemblies…”

New-resource

  • In the “Add Resources” window select “Add…” button and from the installation directory select the DLL “Biztalk.Adapter.ScheduledTaskProperties.dll”
    • And select the options: “Overwrite all”, “Add to the global assembly cache on add resource (gacutil)” and “Add to the global assembly cache on MSI file install (gacutil)”

New-resource-dll

  • Select “OK” button

Important note: The BizTalk assembly containing the orchestration code must also add this assembly as a reference

List of improvements in version 4.0

In this new version are available small improvements compared to the current version (3.0). We can highlight the following improvements or changes:

  • 24 hours support in “start time” property. Previous versions had an issue with setting the start time, as it shown 12 hours watch but no AM/PM.
  • Daily scheduler review. Solved a small bug on Daily Properties: unable to switch between “Every day” and “on these days”
  • Installation experience improved. You no longer need to manually add the DLL in GAC.
  • Support for 32 and 64 bit Host Instances.
  • Compiled in Visual Studio 2010 and .NET Framework 4.0.
  • Optimized for BizTalk Server 2010.
  • Documentation improved.

First of all I would like to thank Greg Forsythe for their kindness and for added me as coordinator on this project.

In the past weeks I have been working on this new version of this adapter, mostly making small improvements and documentation, and now I can say… A new version of BizTalk Scheduled Task Adapter is available for download on CodePlex:

codeplex-BizTalk-Scheduled-Task-Adapter-page

Requirements

This adapter was tested to work on BizTalk Server 2010. Compiled in .NET Framework 4.0

The Scheduled Task Adapter v4.0 will work with:

  • BizTalk Server 2010
  • .NET Framework 4.0

List of improvements in version 4.0

  • In this new version are available small improvements compared to the current version (3.0). We can highlight the following improvements or changes:
  • 24 hours support in “start time” property. Previous versions had an issue with setting the start time, as it shown 12 hours watch but no AM/PM.
  • Daily scheduler review. Solved a small bug on Daily Properties: unable to switch between “Every day” and “on these days”
  • Installation experience improved. You no longer need to manually add the DLL in GAC.
  • Support for 32 and 64 bit Host Instances.
  • Compiled in Visual Studio 2010 and .NET Framework 4.0.
  • Optimized for BizTalk Server 2010.
  • Documentation improved.

BizTalk Scheduled Task Adapter v4.0 (1428.0 KB)
CodePlex

“The order in which we perform the links between the elements from source to destination has a huge impact in the final result”. This statement is true and false at the same time!

In fact the order with which we associate links (Drag & Drop) from the source to different destination elements is irrelevant, since the compiler, as previously explained, will process them in the correct order… Except if we have to associate several links to the same destination element or functoid. In these two last cases the order in which the link association takes place is extremely important and can lead to unexpected results.

Impact of the order of links in functoids

The functoids require certain input parameters that can vary according to the functoid that we are using, in this case the order with which we associate the link is extremely important, a practical example is the Value Mapping Functoid.

This functoid returns the value of the second parameter if the value of the first parameter is “true”. If the value of the first parameter is not “true”, the corresponding element or attribute in the output instance message is not created. Therefore, it is necessary to respect the order in which we associate the links:

  • The first parameter must be a value “true” or “false”, generally from the output of some other Logical functoid or from a variable Boolean field in the input instance message.
  • The second is the value that is output if parameter 1 is “true”. This value can be from a link from a node in the source schema that represents simple content, the output from another functoid, or a constant input parameter.

If we change the order in which the links are associated to the functoid, it will lead to mapping errors or unexpected results, according to the functoid used.

The link reorganization in functoids is very easy to accomplish, you just open the functoid detail (double click) and use the sort buttons.

reorganizar-functoids

Impact of the order of links in elements of the destination schema

If we change the order in which we associate the links on the same element in the destination schema we can also have an impact on the desired final result.

Unfortunately, when we associated different links in the same element, there is no way or place in the graphical editor where you can check the order of the association, for example, similarly to what happens with the functoids. The only way to verify the order in these cases is to inspect the XSLT generated code or testing the map.

A good example of this scenario is when we associated two different Scripting functoid, both with custom inline XSLT scripts to the same destination element or record, once again, changing the order of the link association may have unexpected results.

Impact-order-links-in-elements-destination-schema

In this example the first Scripting functoid contain the following XSLT code:

<xsl:for-each select="Client">
   <Person>
      <Name>
         <xsl:value-of select="Name/text()" />
      </Name>
      <Sex>
         <xsl:value-of select="Sex/text()" />
      </Sex>
   </Person>
</xsl:for-each>

This code performs the mapping of all existing elements in the record “Client” from the source schema to the elements on the record “Person” in the destination schema.

The second Scripting functoid contain an identical XSLT code:

<xsl:for-each select="Employee">
   <Person>
      <Name>
         <xsl:value-of select="Name/text()" />
      </Name>
      <Sex>
         <xsl:value-of select="Sex/text()" />
      </Sex>
   </Person>
</xsl:for-each>

but this time it will map all existing elements in the record “Employee” from the source schema to the elements on the record “Person” in the destination schema.

The expected result is to appear in the final document all clients in the record “Person” and then all employees. If we change the order in which we association the links in the record “Person”, we will see that the result he also will be changed.

We can validate the result of this scenario in the following links:

The rule of Link Sequence

In brief, the mapping engine, process the rules by going through the destination schema from the beginning to the end, processing the links in the order that he finds and in case of multiple links in a particular element or functoid, they are processed in the order in which they were associated.

This means that the links associated with the parent nodes (records) are processed before links associated with the children (elements inside the record).

A good example of this scenario is the use of conditions in the parent node (record) when we want to influence the outcome according with a particular condition. So…let’s find all the names of female clients. To do this we will create a map with the following settings:

The-exception-rule-sequence-links

  • Open the Toolbox window and drag the Looping Functoid onto the grid;
    • Drag a link from the record “Client” from the source schema to the Looping Functoid;
    • Drag a link from the Looping Functoid to the record “Person” in the destination schema;
  • Drag the Equal Functoid from the Toolbox window onto the grid;
    • Drag a link from the element “Sex” from the source schema to the Equal Functoid;
    • Drag a link from the Equal Functoid to the record “Person” in the destination schema;
    • Configured the Equal Functoid, by double click in the functoid, and edit the second condition with the value “F” to build a condition equivalent to Sex = “F”;

sex-condition

The Equal Functoid will return the value “True” if the first input, in this case, the element “Sex” is equal to the second input parameter, ie, “F”. Otherwise it will return the value “False”. What will lead to: the record “Client” is only mapped if the condition returns the value “True”.

If you look the code generated:

…
<ns0:PeopleTarget>
   <xsl:for-each select="Client">
      <xsl:variable name="var:v1" select="userCSharp:LogicalEq(string(Sex/text()) , "F")" />
      <xsl:if test="$var:v1">
         <Person>
            <Name>
               <xsl:value-of select="Name/text()" />
            </Name>
            <Sex>
               <xsl:value-of select="Sex/text()" />
            </Sex>
         </Person>
      </xsl:if>
   </xsl:for-each>
</ns0:PeopleTarget>

We can check that the first action of the map, after the cycle that travels the various elements of the record is: get the value generated in the Equal Functoid, which is represented in the variable “v1”;

And the second action is to validate the condition (IF) with the value of the first operation (v1), ie, will test whether the value “v1” is “True” or “False”. If the condition is true the code within the condition is executed, otherwise it will move to the next element without doing anything. Therefore thus we obtain the desired result:

<ns0:PeopleTarget xmlns:ns0="http://HowMapsWorks.PeopleTarget">
   <Person>
      <Name>Elsa Ligia</Name>
      <Sex>F</Sex>
   </Person>
</ns0:PeopleTarget>
The exception to the rule of Link Sequence: Process links out of order

However there is one important exception to this rule of Link Sequence, especially when using custom scripts in recursive records or elements.

Once again, a good example of this scenario is the use of custom scripts to increment counters. We can illustrate this scenario by adding two Scripting Functoids to the map:

  • The first containing the initialization and the function to increment the counter;
    int myCounter = 0;
    public void IncrementCounter()
    {
       myCounter += 1;
    }
    
  • The second getting the value of the counter
    public int ReturnCounter()
    {
       return myCounter;
    }
    

Note: This example will be associated with a loop, or with a recursive element.

The-exception-to-the-rule-of-Link-Sequence-Process-links-out of-order

We would expect that in the first cycle the result of the second script was the value “1”, in the second cycle we obtained the value “2” and so on. However, if we test the map, we will see that the reality is different:

<ns0:PeopleTarget xmlns:ns0="http://HowMapsWorks.PeopleTarget">
   <Person><LineNumber>0</LineNumber></Person>
   <Person><LineNumber>1</LineNumber></Person>
   <Person><LineNumber>2</LineNumber></Person>
</ns0:PeopleTarget>

As we can see in the result above, the sequence in which the links are executed is:

  • Create the record “PeopleTarget”;
  • Creating child elements, and carry out the link rules associated with them:
    • Execute the function “ReturnCounter” that will return the value “0” in the first iteration.
  • Execute the links associated with the parent node:
    • Execution of the function “IncrementCounter”

As we can validate by checking code produced by the map:

…
<ns0:PeopleTarget>
   <xsl:for-each select="Client">
      <Person>
         <xsl:variable name="var:v1" select="userCSharp:ReturnCounter()" />
         <LineNumber>
            <xsl:value-of select="$var:v1" />
         </LineNumber>
         <xsl:variable name="var:v2" select="userCSharp:IncrementCounter()" />
         <xsl:value-of select="$var:v2" />
      </Person>
   </xsl:for-each>
</ns0:PeopleTarget>

Of course we can change the existing code in the Scripting Functoids so we can get around to this behavior and thus obtain the desired result. However, this example serves to warn that in some scenarios, especially in the use of custom scripts in recursive records or elements, it is necessary to verify and validate the sequence in which the rules (links) are executed.

Conclusion

With this article, as we explore some of the common mappings scenarios, trying to dismantle the options that the BizTalk Map engine has taken to fulfill with the original intent of the visual map.

When you begin to explore the world of maps, there are two questions that should evaluate carefully

  • What is the best way to solve a problem: guaranteed there are several approaches to solve a common problem. Often deciding which the best way turns out to be the most difficult. Compile and analyze the code generated can be a good start to begin to understand the impact of certain options.
  • Incremental Testing: very often we are tempted to try to solve a mapping problem from start to finish and only then we test solution. Leave it to the end can make it extremely difficult to detect problems in complex mappings. Limit the scope of testing should be a continuous and incremental process during the creation of maps, tests must be carried out as soon as a significant block is completed.

I hope this kind of hacking can help you to understand the behavior and debugging techniques for this type of elementary problems.

Related links

BizTalk Server – Basics principles of Maps (318.0 KB)
Microsoft | MSDN Code Gallery