Book review Getting Started With BizTalk Services

Recently I was invited to take a look at the Packt Publishing book ‘Getting Started with BizTalk Services’ by Karthik Bharathy  and Jon Fancey.

This is the first available book on Microsoft Azure BizTalk Services and for that reason alone an interesting read. I’ve already played with BizTalk Services so I was curious to measure my knowledge against the book, moreover because the book assumes no prior BizTalk knowledge. The Microsoft Azure platform is expanding at a tremendous rate so I was also interested to see how up to date this book is, as it was published in March 2014 (although that’s only 3 months ago, the release rate of Azure features is quarterly).

To start with the last question, the book is still very up to date. No major changes or new features have been announced that directly impact BizTalk Services. So from that point of view it is still a reliable source of information (besides that WABS is called MABS now J).

The book is organized like this. It starts with a generic overview of what Azure is and for what scenarios it would be useful. It also covers the basics of BizTalk Services.

Next chapter is about the Mapper and from a on-premise BizTalk Server perspective it has been seriously improved. One thing the book briefly touches is the fact that the mapper is not based on XSLT behind the scenes anymore; it’s using XAML. One other thing is the ability to have some sort of exception handling in the map. This has been one of the missing pieces of integration regarding to BizTalk Server. For each operation you can specify what to do in case of an exception, fail or continue and output a null value. Of course this is not really exception handling, but it’s better than nothing.

Then a chapter about Bridges. I knew a bridge was comparable to a BizTalk pipeline but I was surprised to read that behind the scenes a bridge is using Windows Workflow Foundation. This is an indication that the announced workflow engine for BizTalk Services most probably will be Workflow Foundation as well.

Other chapters cover topics like

  • EAI scenarios
  • B2B scenarios (EDI with X12/EDIFACT)
  • Using the BizTalk Adapter Service to connect to on-premise LOB systems
  • Using custom code in bridges
  • Maintaining BizTalk Services using the API via PowerShell or REST service
  • Tracking and Troubleshooting
  • Moving current BizTalk Server investments to BizTalk Services (and when not to)

Especially the chapter about B2B is comprehensive. The X12 standard is used quite often in the US so it makes sense to dive deeper in that part (european customers are using EDIFACT). Besides that the B2B market is the most suitable to move to the cloud first, because it involved integration with other companies which is typically a cloud-scenario.

Everything in the book is described in clear language and doesn’t only scratch the surface. Some topics are explained in more detail including some background as well.

For anyone interested in BizTalk Services and wishes to be quickly up to speed, this is a perfect start.

Didago IT Consultancy

Introducing the BizTalk Port Info Query Tool

Sometimes for a project you have to create a tool which you plan to share with the community. This tool has been on the shelf for at least a year and I finally found time to share it with you.

It started when I got involved as a fire fighter in a BizTalk project at a customer which had a lot of applications and accompanying hundreds of receive and send ports. The architecture was fully based on the pub/sub architecture and it was sometimes very difficult to understand the flow of the message and also to understand where a message would end up. To get a better view of the inner workings I decided to create a small tool to answer questions like:

  • Which ports do uses this specific map?
  • Where is a certain pipeline used?
  • Which ports subscribe to this field?

This tool is capable of reading the management database and retrieve the receive port and send port information via the ExplorerOM assembly. Only port name and so on is not detailed enough, so I added support to retrieve the following information to get a total view:

  • Receive Port Name
  • Receive Locations
  • Receive Transform
  • Receive Pipelines and Pipeline Components + Configuration
  • Receive Adapter Type and Settings like URL’s
  • Send Port Name
  • Send Transforms
  • Send Pipelines and Pipeline Components + Configuration
  • Send Adapter Types and Settings like URL’s
  • Send Port Filter Subscriptions

This information is retrieved for each of the selected applications. Once this information is available, then it is easy to also search through it. So search was added to be able to quickly see which receive ports or send ports are using a certain map or which send ports are subscribed to a certain field value.

It proved to be pretty handy for research purposed. The tool doesn’t require an installer only launching an executable to show up the winforms application. The sources and executable are on CodePlex and are tested with BizTalk 2010 and BizTalk 2013.

If you launch the tool you’ll get the screen below where you can adjust the user id and password to connect to the management database.

StartScreen

Once you click ‘Retrieve BizTalk Applications’ the management database will be queried using the specified credentials to retrieve all deployed BizTalk applications. Depending on the amount of applications this can take some time.

AppsLoaded

The list of applications are prefixed with a checkbox, so you can retrieve the information for specific applications only if you wish. When you’re ready selecting the applications, then click ‘Retrieve Application Info’ to get the details.

PortInfoLoaded

You now see two populated tree view controls on the right hand side. The top one contains the receive port information and the bottom one the send port information. Per BizTalk application there is a hierarchy containing all the details. If you for example expand the tree you’ll see information about the receive locations, transforms, pipelines and so on.

PortInfoExpanded

The following image shows the details of pipeline components and their settings.

PortInfoExpandedPLC

The best part is that you can search through all information in the receive and send port tree views. The search text box scans the trees for a match and displays the results in the bottom list view. In the example below shows a search for every instance containing ‘_to_’ and as expected the maps on the send and receive ports show up, including the path to the applications they reside in.

PortInfoSearch

Sometimes the information (path) is too long, like with filter subscriptions which can take up many characters. In that case you can double-click the entry and the information is displayed in a message box.

PortInfoSearch2

Finally, in situations where you cannot run the tool yourself or if you want to have the information ‘offline’ then you can use the ‘Export App Info’ button. This button saves the tree as a CSV formatted file type which you can open for example in Excel. The export is saved in the folder location the executable is launched from.

Since this started as a tool-with-maximum-use-minimum-UI it is clear the tool can be improved a lot to be more comprehensive and user friendly, but it worked for me. Feel free to take the code and adjust it to your needs!

I hope it helps you guys getting a better understanding of the BizTalk applications you’re faced with :-)

Greetings,

Jean-Paul

Didago IT Consultancy

BTDF and “The mapping does not exist” SSO Error

Recently I needed to use SSO in an existing BizTalk solution where we use the BizTalk Deployment Framework.

Adding SSO support is so easy, but I ran into the famous “The mapping does not exist” SSO error. It took me some time to figure out what the cause was, and by posting it here I hope someone will benefit from it.

To start with some background. The requirement was a configurable value in a mapping, which would be different for Dev/Test/Prod environments. So typically something for SSO.

To deploy SSO as part of the BTDF is pretty easy. In the btdfproj file you have to specify: <IncludeSSO>true</IncludeSSO>

Next, you have to make sure to define the SSO security groups in the btdfproj and settings Excel file. You can also define custom values in the settings Excel, like ‘SomeValueFromSettings’:  <ItemGroup>    <PropsFromEnvSettingsInclude=SsoAppUserGroup;SsoAppAdminGroup;SomeValueFromSettings; />  </ItemGroup>

Finally you have to add this to the btdfproj:  <TargetName=CustomSSOCondition=‘$(Configuration)’ == ‘Server’>
<UpdateSSOConfigItem BizTalkAppName=$(BizTalkAppName)SSOItemName=“SomeValueToBeUsedSSOItemValue=$(SomeValueFromSettings)/>
</Target>

So far so good, this deploys the SSO settings as expected. The interesting thing is how to get these values out of SSO again. The BTDF uses a special technique to store the settings, which means you should only use the provided SSOSettingsFileReader.dll assembly to get values out of SSO.

I used the BizTalk Mapper Extensions Utility Pack to use the SSO Config Get functoid. This all seems to work fine, but if the map is executed at runtime you’ll receive the error “The mapping does not exist”.

Although more reasons exist for this error, for this case it turned out the way of retrieving the SSO values was not supported. Obviously the extension pack uses a different way to retrieve the values from SSO, which works fine if you deploy values to SSO using for example the SSO Configuration Application MMC Snap-In.

Because I wanted to use the BTDF I changed the functoid to a Scripting Functoid which calls an external assembly method of the SSOSettingsFileReader assembly. After this change it worked right away.

After all a pretty simple solution, but isn’t that always the case :-)

HTH,

Jean-Paul Smit

Didago IT Consultancy

[BizTalk 2010] Testing a multiple input map with Visual Studio 2010

Since BizTalk 2010 we have a feature in Visual Studio 2010 which allows us to test maps without having to deploy them into BizTalk Server. Until then we were lucky to have frameworks like BizUnit. Also the BizTalk Software Factory uses this feature to test maps.

To test maps just using Visual Studio 2010 we use this piece of code in our unit test project:

Microsoft.BizTalk.TestTools.Mapper.TestableMapBase map = new …map_name…();

map.TestMap(inputFile, Microsoft.BizTalk.TestTools.Schema.InputInstanceType.Xml, outputFile, Microsoft.BizTalk.TestTools.Schema.OutputInstanceType.XML);

After this statement we have the output file available which we can use to compare it with the expected values.

But what if we have a map with multiple inputs? We’re not able to provide multiple input files. So how do we test them?

To understand this, we need to know how BizTalk handles these kinds of maps. By the way, this post assumes you know how to create a multiple input map. If not, you can check it here.

To handle multiple input maps, BizTalk creates a new schema which contains both input schemas. In this way BizTalk is only facing one (combined) schema again, which contains both input schemas. This schema is not visible for us developers but is used behind the scenes. So to be able to test a multiple input map, we only have to create such a combined message. How do we create such a message?

To explain this I’ve setup a test scenario, which uses the following artifacts.

First Schema:

<?xml
version=1.0
encoding=utf-16?>

<xs:schema
xmlns=http://Didago.Samples.MultipleInputMap.FirstSchema
xmlns:b=http://schemas.microsoft.com/BizTalk/2003
targetNamespace=http://Didago.Samples.MultipleInputMap.FirstSchema
xmlns:xs=http://www.w3.org/2001/XMLSchema>

<xs:element
name=FirstSchema>

<xs:complexType>

<xs:sequence>

<xs:element
name=FirstName
type=xs:string />

<xs:element
name=City
type=xs:string />

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

Second Schema:

<?xml
version=1.0
encoding=utf-16?>

<xs:schema
xmlns=http://Didago.Samples.MultipleInputMap.SecondSchema
xmlns:b=http://schemas.microsoft.com/BizTalk/2003
targetNamespace=http://Didago.Samples.MultipleInputMap.SecondSchema
xmlns:xs=http://www.w3.org/2001/XMLSchema>

<xs:element
name=SecondSchema>

<xs:complexType>

<xs:sequence>

<xs:element
name=LastName
type=xs:string />

<xs:element
name=Country
type=xs:string />

<xs:element
name=Age
type=xs:int />

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

Combined (target) schema:

<?xml
version=1.0
encoding=utf-16?>

<xs:schema
xmlns=http://Didago.Samples.MultipleInputMap.CombinedSchema
xmlns:b=http://schemas.microsoft.com/BizTalk/2003
targetNamespace=http://Didago.Samples.MultipleInputMap.CombinedSchema
xmlns:xs=http://www.w3.org/2001/XMLSchema>

<xs:element
name=CombinedSchema>

<xs:complexType>

<xs:sequence>

<xs:element
name=FirstName
type=xs:string />

<xs:element
name=LastName
type=xs:string />

<xs:element
name=City
type=xs:string />

<xs:element
name=Country
type=xs:string />

<xs:element
name=Age
type=xs:int />

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

I’ve created a map which transforms the first and second schema into the combined schema. If you open the map in an XML editor, you can view what BizTalk does with multiple input maps.

<xs:schema
xmlns:ns2=http://Didago.Samples.MultipleInputMap.SecondSchema
xmlns:tns=http://schemas.microsoft.com/BizTalk/2003/aggschema
xmlns:b=http://schemas.microsoft.com/BizTalk/2003
xmlns:ns1=http://Didago.Samples.MultipleInputMap.FirstSchema
targetNamespace=http://schemas.microsoft.com/BizTalk/2003/aggschema
xmlns:xs=http://www.w3.org/2001/XMLSchema>

<xs:import
schemaLocation=.FirstSchema.xsd
namespace=http://Didago.Samples.MultipleInputMap.FirstSchema />

<xs:import
schemaLocation=.SecondSchema.xsd
namespace=http://Didago.Samples.MultipleInputMap.SecondSchema />

<xs:element
name=Root>

<xs:complexType>

<xs:sequence>

<xs:element
name=InputMessagePart_0>

<xs:complexType>

<xs:sequence>

<xs:element
ref=ns1:FirstSchema />

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element
name=InputMessagePart_1>

<xs:complexType>

<xs:sequence>

<xs:element
ref=ns2:SecondSchema />

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

BizTalk creates a new schema with a ‘Root’ and two sub nodes ‘InputMessagePart_0′ and ‘InputMessagePart_1′. If we recreate this message for our test, we can use the regular unit test code and it will work. The easy way is to take this (xs:)schema part from the map, create a new schema in BizTalk based on this and use the ‘Generate Instance’ feature to have a valid multiple schema example. We can fill this sample with our test message content to have a valid test. For my test scenario it will look like this example below.

<ns0:Root
xmlns:ns0=http://schemas.microsoft.com/BizTalk/2003/aggschema>

<InputMessagePart_0>

<ns1:FirstSchema
xmlns:ns1=http://Didago.Samples.MultipleInputMap.FirstSchema>

<FirstName>FirstName_0</FirstName>

<City>City_0</City>

</ns1:FirstSchema>

</InputMessagePart_0>

<InputMessagePart_1>

<ns2:SecondSchema
xmlns:ns2=http://Didago.Samples.MultipleInputMap.SecondSchema>

<LastName>LastName_0</LastName>

<Country>Country_0</Country>

<Age>10</Age>

</ns2:SecondSchema>

</InputMessagePart_1>

</ns0:Root>

All we have to do now is adjust the content of the test message to fit our needs. Based on this single input test message, we can perform the tests we need and verify it!

Two remarks though:

  1. Besides the Visual Studio testing, there are other test frameworks available. For example BizTalk Map Test Framework or the Fakes Framework
  2. This blog is specifically targeted at BizTalk 2010. Be aware that in BizTalk 2013 there is a bug preventing testing maps using Visual Studio!

[BizTalk] Binding Gotcha

Last week I ran into something I’d like to share with you, and at the same time is a note to self.

Like in any BizTalk project I have to add a port to one of the projects every now and then, and most of the time the settings are 90% the same so I copy the binding section from one of the current bindings and paste them where I need it.

So I did last week. It was a project where I needed to add a send port, and there wasn’t any yet.

So as anyone knows, the send port section starts with:

<SendPortCollection>

</SendPortCollection>

So I opened the bindingmaster of another project, and copied one of the send port sections. Then I pasted in the other project. When I deployed the other project, I got no errors but also the send ports weren’t imported in the application. No errors, no warnings, it just seemed like the send port part was skipped. The receive ports were imported correctly.

What could this be?

At first I thought there was an error in the BizTalk deployment framework variables, but after stripping that part completely it couldn’t be the cause anymore.

In the end it turned out I copied together with the ‘SendPort’ section, also the “<SendPortCollection></SendPortCollection>” also by accident, resulting in:

<SendPortCollection>

<SendPortCollection>

<SendPort…..>…</SendPort>

</SendPortCollection>

</SendPortCollection>

I appears that this isn’t noted by the import task, it just skips the entire ‘sendportcollection’ section and moves on.

It would have been nice if some kind of parsing error was returned.

Beta release BizTalk Sofware Factory for BizTalk Server 2013

After some struggle I proudly present the BizTalk Software Factory for BizTalk Server 2013.

Struggle because I found out the Guidance Automation Extensions and Guidance Automation Toolkit are no longer maintained by Microsoft. They turned it over to the community and is now known as Open GAX/GAT. With this change also changes in the way it works became clear. The BSF uses for example the GAX Extension Library, also a community project, but it never was compiled against the Open GAX/GAT. It took some time to update the code to make it work.

The BizTalk Software Factory is now at its 4th version and the functionality basically is similar to the previous versions. Support for BizUnit however has been discontinued for testing schemas and maps, because the project seems no longer maintained. Some new out-of-the-box test functionality has been added to test maps which is much better, if Microsoft fixes this bug. For orchestration unit tests however, still BizUnit sample code is there which you can take advantage of.

To use BSF v4, you need to install the following prerequisites:

The Open GAX/GAT depends on the Visual Studio 2012 SDK, so you have to install it.

Install GAX and GAT from http://opengax.codeplex.com, in this order:

  • GAX2010-VS2012.vsix
  • GAT2010-VS2012.vsix

If you like the BizTalk Deployment Framework, it is supported in this version as well. Make sure you install v5.1 beta for BizTalk server 2013.

So from now on you can also build structured BizTalk 2013 solution with the guidance of BSF. If you experience issues or you run into a bug, please post it on the Codeplex site.

Enjoy!

Didago IT Consultancy

BizTalk in the spotlights on TechEd NA

This week was TechEd North America week again. A great show with overview and deep dive sessions about almost every aspect of Microsoft technology. I went to the TechEd a couple of times when it was in Amsterdam and I felt like a kid in a candy store. :-)

The last couple of years there was little attention for the integration stack of Microsoft at TechEd, SharePoint was hot and also Azure got lots of attention. This time integration was in the spotlights again and with reason. Microsoft took the first serious step towards integration in the cloud with BizTalk services and this is big! It is getting clearer that integration will be the key feature in tomorrow’s world of technology. On premise systems and SaaS platforms will need to exchange information like nothing before and the integration layer is going to be this intermediary like it has been for years, connecting on premise systems.

Of course BizTalk Server will be around for the next decade. Microsoft has committed itself to a two-year release cycle, so the next version will probably be BizTalk Server 2015. However you need to keep an eye on the new ‘BizTalk-in-the-cloud’ initiative called Windows Azure BizTalk Services or WABS. It was silently tried out as EAI/EDI labs in April 2012, but it showed where we’re heading. Now the WABS are in preview and will be general available soon. At this time it is nowhere near what BizTalk Server offers, but this will change rapidly. Microsoft is on a release cycle of every quarter(!) for services which means they can and will add more BizTalk-Server-like functionality at a rapid pace. One of the extensions will be support for ESB in the cloud.

BizTalk Server is an enterprise level, business critical product which will be around for a long time, because companies will need an integration layer on premise. However while BizTalk Services is catching up the functionality of the on premise version of BizTalk at the moment, I expect this to be the other way around in two year. From 2015 on you’ll see innovation in BizTalk Services that won’t be available in the on premise server version until the next release. Will customer wait for 2 years to get access to new features? With that in mind it will be more and more interesting and important for companies to seriously look at WABS.

If you want to keep up with BizTalk, you can start by watching these interesting BizTalk sessions from TechEd:

Didago IT Consultancy

BizTalk –Unit Testing Enabled in Release mode?

Today I ran into something which took me too much time to figure out, so this blog post is to avoid others to waste their time. In the end the solution was pretty simple, although not very obvious.

I’m working on a project which consists of 15 BizTalk applications. These applications are deployed using the BizTalk Deployment Framework. I tested the deployments on my development environment and everything worked as expected.

When I deployed it to the test environment, I experienced an issue with just one of the applications. It mentioned a missing dependency: Microsoft.BizTalk.TestTools.

This is the assembly that is added as a reference to your Visual Studio project when you enable unit testing in the project properties (http://msdn.microsoft.com/en-us/library/dd257907(v=bts.10).aspx). I always thought this was bound to building the solution in Debug mode and since the BizTalk Deployment Framework builds everything in Release mode, the reference should have been dropped.

Why did this only show up at this particular project?

I checked the assembly with ILSpy and found out the reference to Microsoft.BizTalk.TestTools actually was there, while it was built in Release mode. The first thing I did was checking the configuration manager, to make sure the Test project was left out in Release mode, but this was already the case.

Finally I found out that if you pull up the project properties, the settings are dependent on the Debug or Release mode you’ve selected. So it appeared that I accidentally enabled unit testing while the configuration was in Release mode. When I disabled it for Release, leaving it enabled for Debug, everything deployed fine.

It is good to know not all debug and test related settings are only bound to Debug builds, so be aware they might show up in your Release build.

Didago IT Consultancy

BizTalk 2010: Deploying and Undeploying EDI Parties with the BizTalk Deployment Framework

I’m a big fan of the BizTalk deployment framework, because it makes deployment so easy, repeatable and reliable because it automates a lot of manual actions.

In my current project I’m working with EDI, so I also have to work with parties and agreements. Of course I wanted to embed this in the deployment framework.

Deploying is pretty easy, because the party and agreement information is part of the binding.

But if an application with party and agreement information already has been deployed, how do you undeploy this? Especially because you cannot delete an application if the party information still is there. If you try to do this, you’ll run into this cryptic error:

 

It is trying to say you cannot delete the application as long as the party information is present…..

After some research I found out how to automate this and I decided to dedicate a blog post to it. Also because other people had the same question, see http://biztalkdeployment.codeplex.com/discussions/256406 and http://biztalkdeployment.codeplex.com/discussions/275140.

Fortunately there is a tool in the SDK capable of deleting parties, which can be found at this location in the BizTalk install folder:

C:Program Files (x86)Microsoft BizTalk Server 2010SDKSamplesAdminExplorerOMDeleteParty

Like almost any admin tool it is utilizing the BizTalk Explorer object model (ExplorerOM) to do the trick. You won’t find the exe there. It is an uncompiled project and that gives you the opportunity to adjust the implementation to your needs. This is necessary because the tool needs to access the BizTalkMgmtDB and assumes it is installed on the server running the tool. On a production environment this often isn’t the case and since this tool is part of deploy/undeploy it will run on the BizTalk server. Another improvement I made is to let the tool undeploy multiple parties in one call, something the out-of-the box implementation also isn’t capable of.

So after the mentioned changes, my code looks like this and I can build the solution to create the DeleteParty.exe tool.

using System;

using System.Windows.Forms;

using Microsoft.BizTalk.ExplorerOM;

 

namespace Microsoft.Samples.BizTalk.ExplorerOM.DeleteParty

{

/// <summary>

/// DeletePartyClass is the wapper class for the Main function.

/// </summary>

class DeletePartyClass

{

/// <summary>

/// The main entry point for the application.

/// The only argument should be the name of the party to delete.

/// </summary>

[STAThread]

static void Main(string[] args)

{

// Handle the command-line arguments and switches

if (args.Length != 2)

{

PrintUsage();

return;

}

if ((“/?” == args[0]) || (“-?” == args[0]))

{

PrintUsage();

return;

}

 

// Create the root object and set the connection string

BtsCatalogExplorer catalog = new BtsCatalogExplorer();

catalog.ConnectionString = string.Format(“SERVER={0};DATABASE={1};Integrated Security=SSPI”, args[0], “BizTalkMgmtDB”);

 

try

{

// Split the party information, we might need to remove multiple

string[] parties = args[1].Split(‘,’);

 

foreach (string pty in parties)

{

// Get the requested party from the collection

Party party = catalog.Parties[pty];

if (null == party)

{

Console.WriteLine(“Party named “ + pty + ” was not found.”);

continue;

}

 

Console.WriteLine(“Deleting party: “ + party.Name);

 

// Remove the party

catalog.RemoveParty(party);

 

// commit the changes

catalog.SaveChanges();

 

Console.WriteLine(“Party deleted.”);

}

}

catch (ConstraintException ce)

{

// Any changes need to be reverted

// when there is an error

catalog.DiscardChanges();

 

// Since this is a common configuration exception

// we don’t need a stack trace

Console.WriteLine(ce.Message);

}

catch (Exception e)

{

// Any changes need to be reverted

// when there is an error

catalog.DiscardChanges();

 

Console.WriteLine(e.ToString());

}

}

 

static private void PrintUsage()

{

Console.WriteLine(“Usage:”);

Console.WriteLine();

Console.WriteLine(“DeleteParty.exe <BizTalkDbServer> <PartyName>”);

Console.WriteLine();

Console.WriteLine(” Where: “);

Console.WriteLine(” <BizTalkDbServer> = The name of the SQL Server where the BizTalk databases are installed.”);

Console.WriteLine(” Example: localhost”);

Console.WriteLine(” <Party Name> = The name of the Party(s) to delete. To delete more than one use , to separate (no space between parties!)”);

Console.WriteLine(” Example: MyBusinessParty1,MyBusinessParty2″);

Console.WriteLine();

}

}

}

Next step is adding the DeleteParty.exe to your solution, so it will be copied to the deployment folder. First add the tool to your solution folder where the other deployment framework files are located. Then add the lines below to your BTDFPROJ file so it will be copied and executed as part of the undeployment.

<!–

 

 

 

 

  <AdditionalFiles Include=DeleteParty.exe>

    <

 

 

LocationPath>.</LocationPath>

  </

 

 

AdditionalFiles>

</

 

 

ItemGroup>

 

 

 

 

 

 

 

Make sure the DeleteParty SDK tool is also deployed, otherwise we cannot undeploy the app anymore because of the stuck party information –>

<

 

 

ItemGroup> <!– Custom undeploy to first delete the party information before being able to remove the application –>

 <Target Name=CustomUnDeployTarget>

<Exec Command=..DeleteParty.exe $(DeleteParty_BizTalkDbServer) $(DeleteParty_PartyName) ContinueOnError=False />

</Target>

 

As you can see, I’ve added two variables (‘DeleteParty_BizTalkDbServer’ and ‘DeletePart_PartyName’) to the command line to be able to run this on various environments. For example the ‘BizTalkDbServer’ won’t be the same on all environments. Add the section below somewhere between the other ‘ItemGroups’ in the BTDFPROJ file, so the variables will be read from the settings file and be available in the script.

<ItemGroup>

<!– We are asking the Deployment Framework to create MSBuild properties from the values

in our environment settings file that are named here.

With this request, we can use these values later on in the script

–>

<PropsFromEnvSettings Include=DeleteParty_BizTalkDbServer;DeleteParty_PartyName />

</ItemGroup>

 

The ‘DeleteParty_BizTalkDbServer’ and ‘DeleteParty_PartyName’ are regular settings you have to put in the SettingsFileGenerator.xml settings file.

Now when you run the deployment script, the DeleteParty tool is run as part of the undeploy.

Didago IT Consultancy

 

 

BizTalk Server 2013 SharePoint Adapter Walkthrough

The SharePoint adapter has been redesigned in BizTalk 2013. It now supports for example SharePoint 2013 and SharePoint online, but it can still communicate with the current common versions like SharePoint 2007 and 2010.

If SharePoint 2013 is your platform, the adapter is utilizing the new SharePoint Client side Object Model (SCOM). For older versions of SharePoint it still uses the WSS adapter service component which needs to be installed on the SharePoint server itself.

I wanted to see how easy it has become to use the SharePoint adapter with SCOM so I decided to do some testing. The adapter is obviously capable of reading and writing to SharePoint document libraries and I was surprised how easy it actually is.

My scenario was pretty simple. I wanted to read a message from file and write it to a SharePoint document library. Next I want to read this message from the document library again and write it to disk. For this I installed a SharePoint 2013 foundation edition (by accident in Dutch) on my BizTalk 2013 environment, which is equipped with Windows Server 2012 and SQL Server 2012.

So first I created the Visual Studio solution with a source schema, a target schema and a mapping between the two. No rocket science. From the Visual Studio point of view nothing has changed. You create artifacts like you’re used to in BizTalk 2013.

After deploying the artifacts to BizTalk I created a receive port and location to read from file (with a simple map to transform from source to target), and more interesting a send port to send the message to SharePoint. After selecting ‘Windows SharePoint Services’ in the transport type of the send port, the following dialog is displayed.

What can be configured here:

  • Adapter Web Service Port – The HTTP port of the IIS website where the WSS adapter web service is installed
  • Timeout – Value in milliseconds the adapter waits to finish the send action
  • Use Client OM – Specify if the adapter can use the new SCOM or should use the older WSS adapter service component. You can also set this property in an orchestration.
  • Destination Folder URL – Location of the list to write the messages to, relative to the SharePoint site URL.
  • Filename (optional) – This is pretty cool, you can specify a fixed filename or construct it based on an Xpath expression to get a value from the message.
  • Namespaces (optional) – define namespaces used for the Xpath expressions like in the filename just mentioned.
  • Overwrite – Like in the FILE adapter, allow the message to be overwritten with the same name, but here also rename is possible.
  • SharePoint Site URL – Location of the SharePoint site to use .
  • Microsoft Office Integration – Specify here values to integrate solutions with Microsoft Office InfoPath, by adding processing instructions.

Then continued with this, to cover the second half of the transport properties dialog:

  • SharePoint Online – For the first time it is possible to connect with the SharePoint online cloud solution!
  • Windows SharePoint Services Integration – Allows to fill up to 16 columns by means of name/value pairs in the destination SharePoint list. In my scenario I added two additional columns to test this; ‘CategoryFixed’ with a fixed value and ‘NameFromXpath’ to figure out how Xpath expressions work. The columns defined must exist in the SharePoint list, it won’t create them if they are missing.

An example of an Xpath expression used as column value could be this:

%XPATH=/*[local-name()='Target' and namespace-uri()='http://Didago.SharePointAdapter.Target']/*[local-name()='Fullname' and namespace-uri()='']%

It should start and end with the ‘%’ symbol and the rest is copied from the schema editor in Visual Studio. It is clear I have a target schema containing a (single) ‘Fullname’ element.

The SharePoint site I used is plain and simple and looks like this (unfortunately in Dutch):

There are two document lists named ‘Processed’ and ‘BizTalkList’ and that list has the two in the configuration mentioned columns ‘CategoryFixed’ and ‘NameFromXpath’. With all this configured and setup we can start testing by dropping a test file into the folder.

The test message is also simple:

The mapping between the source and target is just a concatenation of the first and last name into a full name. After dropping the test message in the folder, it is picked up by BizTalk and send to the SharePoint list.

The message is nicely written to the SharePoint list, the fixed column is filled with ‘Target’ and the concatenated full name is extracted from the message. This was very straight forward. One thing to remind is the host instance account must have write permissions on the list.

The second scenario is reading from the SharePoint list, therefor we first need to create a receive location configured for SharePoint.

What can be configured here:

  • Adapter Web Service Port – The HTTP port of the IIS website where the WSS adapter web service is installed.
  • Timeout – Value in milliseconds the adapter waits to finish the send action.
  • Use Client OM – Specify if the adapter can use the new SCOM or should use the older WSS adapter service component. You can also set this property in an orchestration.
  • Archive Filename (optional) – Name of the file when archived, fixed or via Xpath expressions. I used Xpath here.
  • Archive Location URL – List relative to SharePoint Site URL where to archive the processed messages.
  • Archive Overwrite – Allow to overwrite existing messages in the archive.
  • Batch Size – Maximum number of messages read in one batch.
  • Error Threshold – Maximum number of consecutive polling failures before the receive location is disabled.
  • Namespaces (optional) – Define namespaces used for the Xpath expressions like in the archive filename mentioned before.
  • Polling Interval – Interval in seconds between polling for new messages.
  • SharePoint Site URL – Location of the SharePoint site to use.
  • Source Document Library URL – List relative to SharePoint Site URL where to read the messages from.
  • View Name – Name of the view used to filter the messages to read, leave empty to process all messages.
  • Microsoft Office Integration – (optionally try to) remove the Microsoft Office InfoPath processing instructions on the message.
  • SharePoint Online – For the first time it is possible to connect with the SharePoint online cloud solution!

So with this scenario messages will be read from the view named ‘CategorySource’, which has a filter on the ‘CategoryFixed’ column. It shows only messages where that column has the text ‘Source’ as value. Because the first scenario only writes messages to the list with text value ‘Target’, those aren’t picked up by the adapter and I needed to add a document manually to the list with the required field value. In the screenshot below you’ll find the manually added message in the ‘BizTalkList’ SharePoint list and the ‘CategorySource’ is the selected view.

To my surprise both the message from scenario 1 and the manually added message were picked up and not only the one that shows up on the ‘CategorySource’ view. I’m not sure if this is a bug? I couldn’t find anything about it and after all it is a beta.

In the configuration of the receive location I specified to archive the message, which is correctly done by the adapter.

Some nice behavior I experienced is caused by the ‘Archive Overwrite’ setting, which dictates what to do when a message with a certain name already exists in the archive document list. In that case the adapter performs a check-out on the file to process and then waits. This prevents the message from being removed without being processed.

To conclude I must say it is very easy to use the new SharePoint adapter in BizTalk 2013, but I’m going to do some more research on the view name issue I ran into.

Didago IT Consultancy